Connecting to the Caché Database

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.

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;";
      CacheConnect.Open();
    }
    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.

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();
      CacheConnect.Open();
    }
  ...

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.

• Min Pool Size and Max 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:

ClearPool(conn)

   CacheConnection.ClearPool(conn);

Clears the connection pool associated with connection conn.

ClearAllPools()

   CacheConnection.ClearAllPools();

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:

ActiveConnectionCount

int count = CachePoolManager.ActiveConnectionCount;

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

IdleCount()

   int count = CachePoolManager.IdleCount();

Total number of idle connections in all the pools.

IdleCount(conn)

   int count = CachePoolManager.IdleCount(conn);

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

InUseCount()

   int count = CachePoolManager.InUseCount();

Total number of in-use connections in all pools.

InUseCount(conn)

   int count = CachePoolManager.InUseCount(conn);

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

RecycleAllConnections(Boolean)

   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.

RemoveAllIdleConnections()

   CachePoolManager.RemoveAllIdleConnections();

Removes idle connections from all connection pools.

RemoveAllPoolConnections()

   CachePoolManager.RemoveAllPoolConnections();

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.