Using .NET and the ADO.NET Managed Provider with Caché
Connecting to the Caché Database
[Home] [Back] [Next]
InterSystems: The power behind what matters   

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:
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:
By default, the sample programs use the following connection 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 five parameters are required for all connection strings (see Creating a Connection).
Required Parameters
Name Description
SERVER IP address or host name. For example:
PORT Specifies the TCP/IP port number for the connection. For example:
NAMESPACE Specifies the namespace to connect to. For example:
PASSWORD User's password. For example:
USER ID set user login name. For example:
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.

Send us comments on this page
Copyright © 1997-2019 InterSystems Corporation, Cambridge, MA