Chapter 5 C Routines Reference

JagCmGetCachebyName

Description

Retrieve the handle for the cache with the specified name.

Syntax

JagStatus JagCmGetCachebyName (
        SQLCHAR      *cachename,
        JagCmCache   *cache
        );

Parameters

cachename

The cache name.

cache

The address of a JagCmCache handle. If a matching cache is available, its handle is returned as *cache. If no matching cache exists, *cache is set to NULL.

Return Values

Return value	To indicate
JAG_SUCCEED	Success. *cache is set to the address of the matching cache.
JAG_FAIL	Failure.

JagCmGetCachebyName fails for the following reasons:

A NULL value was passed for cachename.
No matching cache was found.
A matching cache is installed, but the cache properties do not allow retrieval with JagCmGetCachebyName. The "Enable cache-by-name access" option must be enabled in the Connection Cache Properties dialog.

JagCmGetCachebyName records a message that describes the failure reason in the server log file.

Usage

JagCmGetCachebyName allows you to retrieve connections without specifying the user name, password, and other parameters that are required by the JagCmGetCachebyUser routine.

You can retrieve a cache handle with either JagCmGetCachebyUser or JagCmGetCachebyName. Calling JagCmGetCachebyName allows you to change the cache user name, password, or server in Jaguar Manager without requiring corresponding changes to your component source code.

In order for components to retrieve a cache with JagCmGetCachebyName, the Jaguar Administrator must select the "Enable cache-by-name access" option for the cache in Jaguar Manager. JagCmGetCachebyName fails if the cache does not have this option enabled.