Chapter 5 C Routines Reference

JagCmGetCtx

Description

Obtain the connectivity-library-specific context reference that is used to allocate cached connections in a cache.

Syntax

JagStatus JagCmGetCtx (

        JagCmCache    *cache,

        SQLCHAR       *username,

        SQLCHAR       *password,

        SQLCHAR       *server,

        SQLCHAR       *con_lib,

        SQLPOINTER    *ctx

);

Parameters

cache

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

When *cache is NULL, the values of username, password, server, and con_lib are used to search for a matching cache. If found, *ctx is set to the address of the connectivity-library context handle, and *cache is set to the matching cache handle.
If *cache contains a valid cache handle, JagCmGetCtx retrieves the connectivity-library context for the indicated cache. You can call JagCmGetCachebyUser or JagCmGetCachebyName to obtain a cache handle for any cache that is defined in Jaguar Manager.

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, a string value indicating the connectivity library used by connections in the cache. Ignored when cache is not NULL.

When cache is NULL, con_lib must be one of the following:

con_lib value	To indicate
"CTLIB_110"	Sybase Open Client Client-Library
"ODBC"	An ODBC implementation library

ctx

The address of a variable that receives the connectivity library context used to allocate cached connections. The returned type depends on the connectivity library, as follows:

Connectivity library	Value returned in *ctx
Client-Library	A pointer to a CS_CONTEXT structure. Each connection cache uses a separate CS_CONTEXT structure.
ODBC	An ODBC SQLHENV environment handle. This handle is shared by all ODBC connection caches.

Return Values

Returns	To indicate
JAG_SUCCEED	Successful retrieval of the CS_CONTEXT for a Client-Library connection cache.
JAG_FAIL	Failure. JagCmGetCtx fails when con_lib specifies an invalid value.

JagCmGetCtx fails for the following reasons:

The cache parameter is passed as NULL.
The value of cache is not NULL, and *cache references an invalid cache.
The value of cache is NULL, and there is no cache matching the values specified for the username, password, server, and con_lib parameters.

Usage