Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.

For information on migrating to InterSystems IRIS, see Why Migrate to InterSystems IRIS?

Connecting to the Caché Database

This chapter describes how to create a connection between your client application and the Caché Server using a CacheConnection object. Such connections are used by both Caché Object Binding classes and ADO.NET Managed Provider classes

Creating a Connection

The code below establishes a connection to the SAMPLES namespace used by most Caché sample programs (see “The Caché .NET Sample Programs” for details). The connection object is usable by any class that requires a Caché connection, regardless of whether you are using Caché 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.

Add Code to Instantiate the Caché Connection

The following simple method could be called to start a connection:

  public CacheConnection CacheConnect;
  private void CreateConnection(){
    try {
      CacheConnect = new CacheConnection();
      CacheConnect.ConnectionString = 
        "Server=localhost; Port=1972; Namespace=SAMPLES;"
        + "Password=SYS; User ID=_SYSTEM;";
    catch (Exception eConn){
      MessageBox.Show("CreateConnection error: " + eConn.Message);

This example defines the CacheConnection 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 CacheConnect.Open() and CacheConnect.Close(). If you are using an ADO.NET Dataset, instances of DataAdapter will open and close the connection automatically, as needed.

Use the CacheConnection.ConnectDlg() Method

You can also prompt the user for a connection string. The previous example could be rewritten as follows:

  private void CreateConnection(){
    try {
      CacheConnect = new CacheConnection();
      CacheConnect.ConnectionString = CacheConnection.ConnectDlg();

The ConnectDlg() method displays the standard Caché 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:

  • 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:

      CacheConnect.ConnectionString = 
        "Server = localhost;"
        + " Port = 1972;"
        + " Namespace = SAMPLES;"
        + " Password = SYS;"
        + " User ID = _SYSTEM;"
        + " Min Pool Size = 2;"
        + " Max Pool Size = 5;"
        + " Connection Reset = true;"
        + " Connection Lifetime = 3;";

The CacheConnection class also includes the following static methods that can be used to control pooling:


Clears the connection pool associated with connection conn.


Removes all connections in the connection pools and clears the pools.

Using the CachePoolManager Class

The CacheClient.CachePoolManager class can be used to monitor and control connection pooling programmatically. The following static methods are available:

int count = CachePoolManager.ActiveConnectionCount;

Total number of established connections in all pools. Count includes both idle and in-use connections.

   int count = CachePoolManager.IdleCount();

Total number of idle connections in all the pools.

   int count = CachePoolManager.IdleCount(conn);

Total number of idle connections in the pool associated with connection object conn.

   int count = CachePoolManager.InUseCount();

Total number of in-use connections in all pools.

   int count = CachePoolManager.InUseCount(conn);

Total number of in-use connections in the pool associated with connection object conn.

   CachePoolManager.RecycleAllConnections(bool remove);

Recycles connections in all pools

RecycleConnections(conn, Boolean)
   CachePoolManager.RecycleConnections(conn,bool remove)

Recycles connections in the pool associated with connection object conn.


Removes idle connections from all connection pools.


Deletes all connections and removes all pools, regardless of what state the connections are in.

For a working example that uses most of these methods, see the Proxy_9_Connection_Pools() method in the bookdemos sample program (see “The Caché .NET Sample Programs”).

Caché Server Configuration

Very little configuration is required to use a .NET client with a Caché Server process. The sample programs provided with Caché should work with no change following a default Caché installation. This section describes the server settings required for a connection, and some troubleshooting tips.

Every .NET client that wishes to connect to a Caché Server needs the following information:

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

  • A case-sensitive username and password.

By default, the sample programs use the following connection information:

  • connection string: "localhost[1972]:SAMPLES"

  • username: "_SYSTEM"

  • password: "SYS"

Check the following points if you have any problems:

  • Make sure that the Caché Server process is installed and running.

  • Make sure that you know the IP address of the machine on which the Caché Server process is running. The sample programs use "localhost". If you want a sample program to default to a different system you will need to change the connection string in the code.

  • Make sure that you know the TCP/IP port number on which the Caché Server is listening. The sample programs use "1972". If you want a sample program to default to a different port, you will need change the number in the sample code.

  • 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). The sample programs use the administrator username "_SYSTEM" and the default password "SYS". Typically, you will change the default password after installing the server. If you want a sample program to default to a different username and password, you will need to change the sample code.

  • Make sure that your connection URL includes a valid Caché namespace. This should be the namespace containing the classes and data your program uses. The samples connect to the SAMPLES namespace, which is pre-installed with Caché.

Connection Parameters

The following tables describe all parameters that can be used in a connection string.

Required Parameters

The following five parameters are required for all connection strings (see “Creating a Connection”).

Required Parameters
Name Description
SERVER IP address or host name. For example:
Server = localhost
PORT Specifies the TCP/IP port number for the connection. For example:
Port = 1972
NAMESPACE Specifies the namespace to connect to. For example:
Namespace = SAMPLES
PASSWORD User's password. For example:
Password = SYS
alternate name: PWD
USER ID set user login name. For example:
alternate names: USER, UID

Connection Pooling Parameters

The following parameters define various aspects of connection pooling (see “Connection Pooling”).

Connection Pooling Parameters
Name Description
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.

Other Connection Parameters
Name Description
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 CACHE 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 Caché” in the Caché 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.
WORKSTATION ID Sets the Workstation name for process identification.