Chapter 5 C Routines Reference

JagCmCacheProps

Description

Retrieve connection cache properties.

Syntax

JagStatus JagCmCacheProps (
        JagCmCache          cache,
        JagAction           cmd,
        JagCmCachePropEnum  prop,
        SQLPOINTER          bufp,
        SQLINTEGER          buflen,
        SQLINTEGER          *outlen
        );

Parameters

cache

A JagCmCache control handle. You can call JagCmGetCachebyUser to obtain a cache handle for any cache that is defined in Jaguar Manager. A non-null, valid cache handle is required to access any property other than JAG_CM_CACHEBYNAME.

When retrieving the JAG_CM_CACHEBYNAME value, you can pass a null cache handle, as described in "Determining whether by-name access is allowed".

cmd

Must be JAG_GET.

prop

A symbolic constant that indicates the property of interest. "Connection cache properties" lists possible values.

bufp

The address of a buffer or variable to receive the property value. "Connection cache properties" lists the datatypes to pass for each property.

buflen

The length, in bytes, of *bufp. If buflen indicates insufficient space for the value to be retrieved, JagCmCacheProps sets outlen to the required number of bytes and returns JAG_FAIL.

outlen

The address of a SQLINTEGER variable that receives the number of bytes written to *bufp. For string properties, outlen includes the null-terminator.

Return Values

Return value	To indicate
JAG_SUCCEED	Success
JAG_FAIL	Failure

JagCmCacheProps fails for the following reasons:

The cache, cmd, or prop parameters are invalid.
bufp is NULL.
buflen indicates that *bufp contains insufficient space.

Check the server's log file for more information when JagCmCacheProps fails.

Usage

The following table summarizes connection cache properties. Access to all properties except JAG_CM_CACHEBYNAME requires a valid cache handle:

Table 5-2: Connection cache properties
Property	Specifies	*bufp datatype
JAG_CM_CACHEBYNAME	Whether a cache can be retrieved by calling JagCmGetCachebyName. This property can be accessed before retrieving a cache handle, as described in "Determining whether by-name access is allowed".	A SQLCHAR array For input, specifies the cache name of interest. On return, unchanged.
JAG_CM_CACHENAME	The name of the cache (as it appears in Jaguar Manager).	A SQLCHAR array. Input value is ignored. Output value is the cache name.
JAG_CM_CACHESIZE	The configured size of the cache.	SQLINTEGER Input is ignored. Output is the cache size.
JAG_CM_CONLIB	The connectivity library: "ODBC", "CTLIB_110", "OCI_7", or "OCI_8".	A SQLCHAR array. Input is ignored. Output is the connectivity libray name.
JAG_CM_MUTEX	(UNIX only.) A Server-Library mutex that is used to single-thread ODBC calls. For more information, see "Single-Threading ODBC Calls on Solaris" in the Jaguar CTS Programmer's Guide.	A Server-Library SRV_OBJID mutex key. Input is ignored. Output is the mutext key.
JAG_CM_PASSWORD	The password used by connections in the cache.	A SQLCHAR array. Input is ignored. Output is the password.
JAG_CM_SERVER	The name of the server to which the cache's connections connect.	A SQLCHAR array. Input is ignored. Output is the server name.
JAG_CM_USERNAME	The user name for connections in the cache.	A SQLCHAR array. Input is ignored. Output is the server name.

Determining whether by-name access is allowed

The JagCmGetCachebyName method allows you to retrieve a connection cache by specifying only the cache name, rather than specifying values for the cache user name, password, and server name. However, by-name access must be enabled for the cache in Jaguar Manager to allow retrieval with JagCmGetCachebyName.

You can call JagCmCacheProps to determine whether by-name access is allowed for a specified cache, before attempting to retrieve the cache handle with JagCmGetCachebyName. Pass the address of the cache name as the bufp parameter and the address of a SQLINTEGER for the outlen parameter. The *outlen value will be non-zero if the cache can be accessed with JagCmGetCachebyName. The example below illustrates the call syntax:

JagStatus       status;
SQLINTEGER      outval;
SQLCHAR         myCacheName[] = "mycache";

status = JagCmCacheProps((JagCMCache)NULL, JAG_GET, 
                         JAG_CM_CACHEBYNAME,
                         (SQLPOINTER)myCacheName, 
                         strlen(myCacheName), &outval);
if (status != JAG_SUCCEED)
  ... log the error ...
}
if (outval == JAG_TRUE) {
  ... by-name access is not allowed for the cache ...
}

After retrieving a valid cache handle, you can determine whether by-name access is allowed as shown in the example below:

SQLINTEGER      outval;
JagCmCache      myValidCache; 
JagStatus       status;

status = JagCmCacheProps(myValidCache, JAG_GET, 
                         JAG_CM_CACHEBYNAME,
                         (SQLPOINTER)NULL,
                         0, &outval);
if (status != JAG_SUCCEED) {
  ... log the error ...
}
if (outval == JAG_TRUE) {
  ... by-name access is not allowed for the cache ...
}