Skip to main content
************* PRERELEASE CONTENT *************
Previous sectionNext section

Connecting to the InterSystems Database

This chapter describes how to create a connection between your client application and an InterSystems server using an IRISConnection object.

Creating a Connection

The code below establishes a connection to a namespace named USER. See “Connection Parameter Options” 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 connection
  public IRISConnection Conn;
  private void CreateConnection(){
    try {
      Conn = new IRISConnection();
      Conn.ConnectionString =
        "Server=localhost; Port=1972; Namespace=USER;"
        + "Password=SYS; User ID=_SYSTEM;";
      Conn.Open();
    }
    catch (Exception eConn){
      MessageBox.Show("CreateConnection error: " + eConn.Message);
    }
  }
Copy code to clipboard

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 Conn.Open() and Conn.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 {
      Conn = new IRISConnection();
      Conn.ConnectionString = IRISConnection.ConnectDlg();
      Conn.Open();
    }
  ...
Copy code to clipboard

The ConnectDlg() method displays the standard InterSystems connection dialog and returns the user's input as a connection string.

Shared Memory Connections

The standard ADO .NET connection to a remote InterSystems IRIS instance is over TCP/IP. To maximize performance, InterSystems IRIS also offers a shared memory connection for .NET applications running on the same machine as an InterSystems IRIS instance. This connection avoids potentially expensive calls into the kernel network stack, providing optimal low latency and high throughput for .NET operations.

If a connection specifies server address localhost or 127.0.0.1, shared memory will be used by default. TCP/IP will be used if the actual machine address is specified. The connection will automatically fall back to TCP/IP if the shared memory device fails or is not available.

Shared memory can be disabled in the connection string by setting the SharedMemory property to false. For example, the following connection string will not use shared memory, even though the server address is specified as localhost.

  "Server=localhost;Port=1972;Namespace=user;Password = SYS;User ID = _system;SharedMemory=false"
Copy code to clipboard

Shared memory is not used for SSL connections. The log will include information on whether a shared memory connection was attempted and if it was successful.

Note:
Shared memory connections do not work across container boundaries

InterSystems does not currently support shared memory connections between two different containers. If a client tries to connect across container boundaries using localhost or 127.0.0.1, the connection mode will default to shared memory, causing it to fail. This applies regardless of whether the Docker --network host option is specified. You can guarantee a TCP/IP connection between containers either by specifying the actual hostname for the server address, or by disabling shared memory in the connection string (as demonstrated above).

Shared memory connections can be used without problems when the server and client are in the same container.

Connection Pooling

Connection pooling is on by default. The following connection string parameters can be used to control various aspects of connection pooling:

  • Pooling — Defaults to true. Set Pooling to false to create a connection with no connection pooling.

  • Max Pool Size and Min Pool Size — Default values are 0 and 100. Set these parameters to specify the maximum and minimum (initial) size of the connection pool for this specific connection string.

  • Connection Reset and Connection Lifetime — Set Connection Reset to true to turn on the pooled connection reset mechanism. Connection Lifetime specifies the number of seconds to wait before resetting an idle pooled connection. The default value is 0.

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:

      Conn.ConnectionString =
        "Server = localhost;"
        + " Port = 1972;"
        + " Namespace = USER;"
        + " Password = SYS;"
        + " User ID = _SYSTEM;"
        + " Min Pool Size = 2;"
        + " Max Pool Size = 5;"
        + " Connection Reset = true;"
        + " Connection Lifetime = 3;";
Copy code to clipboard

See the “Quick Reference for the .NET Managed Provider” for more details on the various connection pooling methods and properties.

Server Configuration

Very little configuration is required to use a .NET client with an InterSystems 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 server needs the following information:

  • A URL that provides the server IP address, port number, and namespace.

  • A case-sensitive username and password.

Check the following points if you have any problems:

  • Make sure that the server process is installed and running.

  • Make sure that you know the IP address of the machine on which the server process is running.

  • Make sure that you know the TCP/IP port number on which the server is listening.

  • Make sure that you have a valid username and password to use to establish a connection. (You can manage usernames and passwords using the Management Portal: System Administration > Security > Users).

  • Make sure that your connection URL includes a valid namespace. This should be the namespace containing the classes and data your program uses.