JagBindCol  JagCmGetCachebyName

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 EAServer 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. Table 5-2 lists possible values.

bufp

The address of a buffer or variable to receive the property value. Table 5-2 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.

Returns

Return value

To indicate

JAG_SUCCEED

Success

JAG_FAIL

Failure

JagCmCacheProps fails for the following reasons:

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

Usage

Table 5-2 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 EAServer 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 library name.

JAG_CM_MUTEX

(UNIX only.) A Server-Library mutex that is used to single-thread ODBC calls. For more information, see Chapter 26, “Using Connection Management,” in the EAServer Programmer’s Guide.

A Server-Library SRV_OBJID mutex key.

Input is ignored.

Output is the mutex 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 EAServer 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 ...
}

See also

JagCmGetCachebyUser, JagCmGetCtx





Copyright © 2005. Sybase Inc. All rights reserved. JagCmGetCachebyName