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.
JagStatus JagCmGetConnection ( JagCmCache *cache, SQLCHAR *username, SQLCHAR *password, SQLCHAR *server, SQLCHAR *con_lib, SQLPOINTER *connection, JagCmOpt opt );
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 EAServer 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.
When *cache is NULL, the user name for connections in the desired cache. Ignored when *cache is not NULL.
When *cache is NULL, the password used by connections in the desired cache. Ignored when *cache is not NULL.
When *cache is NULL, the name of the server to which cached connections are made. Ignored when *cache is not NULL.
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 |
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.
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 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 EAServer Manager. |
JAG_FAIL |
Failure. JagCmGetConnection returns JAG_FAIL when the call specifies an invalid con_lib value. |
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.
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.
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. |
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.
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.
