Retrieve a connection from a specified data source or from any data source 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 data source handle. JagCmGetConnection attempts to return a connection from the specified data source. You can call JagCmGetCachebyUser to obtain a data source handle for any data source.
If *cache is NULL, characteristic values for username, password, server, and con_lib must be supplied. If a matching data source is found, *cache is set to handle for the data source.
When *cache is NULL, the user name for connections in the desired data source. Ignored when *cache is not NULL.
When *cache is NULL, the password used by connections in the desired data source. 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 data source. 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 data source 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. |
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 data source 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 data source and *cache is set to reflect the data source from which the connection came. If no data source 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 data source was found, con_lib is ignored. The following table summarizes the JagCmGetConnection call when *cache is NULL.
Data source found? |
Connection available in data source? |
Result |
|---|---|---|
Yes |
Yes |
The call returns a connection handle in *connection and sets *cache to reflect the data source 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 data source. When JagCmGetConnection returns a cached connection, it sets *cache to indicate the data source to which the connection belongs. Cached connections must be released to the data source from which they were taken: pass the data source reference obtained in the JagCmGetConnection call when calling JagCmReleaseConnection.
An uncached connection is one that was not taken from a data source. JagCmGetConnection returns an uncached connection in either of the following cases:
There is no data source configured with the specified username/password/server/con_lib parameter values.
There is a matching data source, all its connections are in use, and the JagCmGetConnection call specifies JAG_CM_FORCE as the value of the opt parameter.
When a data source handle is passed in *cache, JagCmGetConnection looks for an available connection in that data source. 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.
