Chapter 5 C Routines Reference

JagCmGetConnection

Description

Retrieve a connection from a specified cache or from any cache that matches a specified set of values for server, user name, password, and connectivity library.

Syntax

JagStatus JagCmGetConnection (
        JagCmCache    *cache,
        SQLCHAR       *username,
        SQLCHAR       *password,
        SQLCHAR       *server,
        SQLCHAR       *con_lib,
        SQLPOINTER    *connection,
        JagCmOpt      opt
        );

Parameters

cache

The address of a JagCmCache cache handle variable. The input value determines how the parameter is used:

If *cache is not NULL, it must specify a valid cache handle. JagCmGetConnection attempts to return a connection from the specified cache. You can call JagCmGetCachebyUser to obtain a cache handle for any cache that is defined in Jaguar Manager.
If *cache is NULL, characteristic values for username, password, server, and con_lib must be supplied. If a matching cache is found, *cache is set to handle for the cache.

username

When *cache is NULL, the user name for connections in the desired cache. Ignored when *cache is not NULL.

password

When *cache is NULL, the password used by connections in the desired cache. Ignored when *cache is not NULL.

server

When *cache is NULL, the name of the server to which cached connections are made. Ignored when *cache is not NULL.

con_lib

When *cache is NULL, indicates a string value indicating the connectivity library used by connections in the cache. Ignored when *cache is not NULL.

When *cache is NULL, allowable values for con_lib are:

con_lib value	To indicate
"CTLIB_110"	Sybase Open Client Client-Library
"ODBC"	An ODBC implementation library
"OCI_7"	Oracle Call Interface 7.x
"OCI_8"	Oracle Call Interface 8.x

connection

The address of a variable that receives the connection handle. Declare a variable of the appropriate type, as follows:

For ODBC connections, pass the address of an SQLHDBC variable
For Client-Library connections, pass the address of a CS_CONNECTION * variable
For Oracle 7.x connections, pass the address of an OCI Lda_Def variable
For Oracle 8.x connections, pass the address of an OCI OCISvcCtx variable

On successful return, the connection will be open and in a state that allows commands to be sent to the remote server.

opt

A symbolic value that indicates the desired behavior if all connections in a cache are in use. Allowable values are:

Value of opt	JagCmGetConnection behavior when all connections are in use
JAG_CM_NOWAIT	Fails with an error if no connection can be returned.
JAG_CM_WAIT	Does not return until a connection becomes available.
JAG_CM_FORCE	Allocates and opens a new connection. The new connection is not cached and will be destroyed when JagCmReleaseConnection is called.

Return Values

Return value	To indicate
ODBC status code	The result of a SQLAllocConnect or SQLConnect call, or SQL_SUCCESS in the case where a previously opened connection is returned.
Client-Library status code	The result of a ct_con_alloc or ct_connect call, or CS_SUCCEED in the case where a previously opened connection is returned.
OCI_SUCCESS (An OCI 7.x and 8.x status code)	Successful retrieval of an OCI 7.x or 8.x connection.
OCI_FAIL (An OCI 7.x and 8.x status code)	Failure to retrieve an OCI 7.x or 8.x connection. Check the server log for errors, and verify that the connection can be pinged in Jaguar Manager.
JAG_FAIL	Failure. JagCmGetConnection returns JAG_FAIL when the call specifies an invalid con_lib value.

Usage

JagCmGetConnection returns a connection that was allocated and opened with the specified connectivity library and that has matching values for server, user name, and password.

JagCmGetConnection behaves differently depending on whether the *cache parameter is NULL.

Calls that pass a NULL cache handle

If *cache is NULL, CmGetConnection looks for a cache with settings that match the values of the username, password, server, and con_lib parameters. If a cache is found and a connection is available, a connection is returned from that cache and *cache is set to reflect the cache from which the connection came. If no cache is found, then a connection structure is allocated, a connection is opened using the specified connectivity library and the new connection structure is returned. If a cache was found, con_lib is ignored. The following table summarizes the JagCmGetConnection call when *cache is NULL.

Table 5-3: JagCmGetConnection behavior when *cache is NULL
Cache found?	Connection available in cache?	Result
Yes	Yes	The call returns a connection handle in connection and sets cache to reflect the cache from which the connection came.
Yes	No	Depending on the value of the opt parameter, the call fails, waits for an available connection, or allocates and opens a new, uncached connection. *cache is returned as NULL.
No	N/A	The call attempts to allocate and open a new, uncached connection. *cache is returned as NULL.

Cached and uncached connections

A connection obtained with JagCmGetConnection is either cached or uncached.

A cached connection is one that was taken from a configured connection cache. When JagCmGetConnection returns a cached connection, it sets *cache to indicate the cache to which the connection belongs. Cached connections must be released to the cache from which they were taken: pass the cache reference obtained in the JagCmGetConnection call when calling JagCmReleaseConnection.

An uncached connection is one that was not taken from a cache. JagCmGetConnection returns an uncached connection in either of the following cases:

There is no cache configured with the specified username/password/server/con_lib parameter values.
There is a matching cache, all its connections are in use, and the JagCmGetConnection call specifies JAG_CM_FORCE as the value of the opt parameter.

Calls that pass a non-NULL cache handle

When a cache handle is passed in *cache, JagCmGetConnection looks for an available connection in that cache. If none is available, then the value of the opt parameter determines whether the call waits for a connection to be released, fails, or opens a new, uncached connection.