docs.intersystems.com
Home  /  Application Development: Language Bindings and Gateways  /  Using the InterSystems Managed Provider for .NET  /  Connecting to the InterSystems IRIS Database


Using the InterSystems Managed Provider for .NET
Connecting to the InterSystems IRIS Database
[Back]  [Next] 
InterSystems: The power behind what matters   
Search:  


This chapter describes how to create a connection between your client application and the InterSystems IRIS™ Server using a IrisConnection object. Such connections are used by both InterSystems IRIS Object Binding classes and ADO.NET Managed Provider classes.
Creating a Connection
The code below establishes a connection to a namespace named USER. The connection object is usable by any class that requires an InterSystems IRIS connection, regardless of whether you are using InterSystems IRIS Object Binding classes, ADO.NET Managed Provider classes, or both. See Connection Parameters for a complete list of parameters that can be set when instantiating a connection object.
The following simple method could be called to start a connection:
Add Code to Instantiate the InterSystems IRIS Connection
  public IrisConnection IrisConnect;
  private void CreateConnection(){
    try {
      IrisConnect = new IrisConnection();
      IrisConnect.ConnectionString =
        "Server=localhost; Port=51773; Namespace=USER;"
        + "Password=SYS; User ID=_SYSTEM;";
      IrisConnect.Open();
    }
    catch (Exception eConn){
      MessageBox.Show("CreateConnection error: " + eConn.Message);
    }
  }
This example defines the IrisConnection object as a global that can be used anywhere in the program. Once the object has been created, it can be shared among all the classes that need it. The connection object can be opened and closed as necessary. You can do this explicitly by using IrisConnect.Open() and IrisConnect.Close(). If you are using an ADO.NET Dataset, instances of DataAdapter will open and close the connection automatically, as needed.
You can also prompt the user for a connection string. The previous example could be rewritten as follows:
Use the IrisConnection.ConnectDlg() Method
  private void CreateConnection(){
    try {
      IrisConnect = new IrisConnection();
      IrisConnect.ConnectionString = IrisConnection.ConnectDlg();
      IrisConnect.Open();
    }
  ...
The ConnectDlg() method displays the standard InterSystems IRIS connection dialog and returns the user's input as a connection string.
Connection Pooling
Connection pooling is on by default. The following connection string parameters can be used to control various aspects of connection pooling:
For example, the following connect string sets the initial size of the connection pool to 2 and the maximum number of connections to 5, and activates connection reset with a maximum connection idle time of 3 seconds:
      IrisConnect.ConnectionString =
        "Server = localhost;"
        + " Port = 51773;"
        + " Namespace = USER;"
        + " Password = SYS;"
        + " User ID = _SYSTEM;"
        + " Min Pool Size = 2;"
        + " Max Pool Size = 5;"
        + " Connection Reset = true;"
        + " Connection Lifetime = 3;";

The IrisConnection class also includes the following static methods that can be used to control pooling:
ClearPool(conn)
   IrisConnection.ClearPool(conn);
Clears the connection pool associated with connection conn.
ClearAllPools()
   IrisConnection.ClearAllPools();
Removes all connections in the connection pools and clears the pools.
Using the IrisPoolManager Class
The IrisClient.IrisPoolManager class can be used to monitor and control connection pooling programmatically. The following static methods are available:
ActiveConnectionCount
int count = IrisPoolManager.ActiveConnectionCount;
Total number of established connections in all pools. Count includes both idle and in-use connections.
IdleCount()
   int count = IrisPoolManager.IdleCount();
Total number of idle connections in all the pools.
IdleCount(conn)
   int count = IrisPoolManager.IdleCount(conn);
Total number of idle connections in the pool associated with connection object conn.
InUseCount()
   int count = IrisPoolManager.InUseCount();
Total number of in-use connections in all pools.
InUseCount(conn)
   int count = IrisPoolManager.InUseCount(conn);
Total number of in-use connections in the pool associated with connection object conn.
RecycleAllConnections(Boolean)
   IrisPoolManager.RecycleAllConnections(bool remove);
Recycles connections in all pools
RecycleConnections(conn, Boolean)
   IrisPoolManager.RecycleConnections(conn,bool remove)
Recycles connections in the pool associated with connection object conn.
RemoveAllIdleConnections()
   IrisPoolManager.RemoveAllIdleConnections();
Removes idle connections from all connection pools.
RemoveAllPoolConnections()
   IrisPoolManager.RemoveAllPoolConnections();
Deletes all connections and removes all pools, regardless of what state the connections are in.
InterSystems IRIS Server Configuration
Very little configuration is required to use a .NET client with an InterSystems IRIS Server process. This section describes the server settings required for a connection, and some troubleshooting tips.
Every .NET client that wishes to connect to an InterSystems IRIS Server needs the following information:
Check the following points if you have any problems:
Connection Parameters
The following tables describe all parameters that can be used in a connection string.
Required Parameters
The following parameters are required for all connection strings (see Creating a Connection).
SERVER
IP address or host name. For example: Server = localhost
alternate names: ADDR, ADDRESS, DATA SOURCE, NETWORK ADDRESS
PORT
Specifies the TCP/IP port number for the connection. For example: Port = 51773
NAMESPACE
Specifies the namespace to connect to. For example: Namespace = USER
alternate names: INITIAL CATALOG, DATABASE
PASSWORD
User's password. For example: Password = SYS
alternate name: PWD
USER ID
set user login name. For example: User ID = _SYSTEM
alternate names: USER, UID
Connection Pooling Parameters
The following parameters define various aspects of connection pooling (see Connection Pooling).
CONNECTION LIFETIME
The length of time in seconds to wait before resetting an idle Pooled connection when the connection reset mechanism is on. Default is 0.
CONNECTION RESET
Turn on Pooled connection reset mechanism (used with CONNECTION LIFETIME). Default is false.
MAX POOL SIZE
Maximum size of connection pool for this specific connection string. Default is 100.
MIN POOL SIZE
Minimum or initial size of the connection pool, for this specific connection string. Default is 0.
POOLING
Turn on connection pooling. Default is true.
Other Connection Parameters
The following optional parameters can be set if required.
APPLICATION NAME
Sets the application name.
CONNECTION TIMEOUT
Sets the length of time in seconds to try and establish a connection before failure. Default is 30.
alternate name: CONNECT TIMEOUT
CURRENT LANGUAGE
Sets the language for this process.
LOGFILE
Turns on logging and sets the log file location.
alternate name: LOG FILE.
PACKET SIZE
Sets the TCP Packet size. Default is 1024.
PREPARSE IRIS SIZE
Sets an upper limit to the number of SQL commands that will be held in the preparse cache before recycling is applied. Default is 200.
SO RCVBUF
Sets the TCP receive buffer size. Default is 0 (use system default value).
alternate name: SO_RCVBUF
SO SNDBUF
Sets the TCP send buffer size. Default is 0 (use system default value).
alternate name: SO_SNDBUF
SSL
Specifies whether SSL/TLS secures the client-server connection (see Configuring .NET Clients to Use SSL/TLS with InterSystems IRIS in the Security Administration Guide). Default is false.
TCP NODELAY
Sets the TCP nodelay option. Default is true.
alternate name: TCP_NODELAY
TRANSACTION ISOLATION LEVEL
Sets the System.Data.IsolationLevel value for the connection.
alternate name: TRANSACTIONISOLATIONLEVEL
WORKSTATION ID
Sets the Workstation name for process identification.