Retrieve the handle for the cache with the specified name.
JagStatus JagCmGetCachebyName ( SQLCHAR *cachename, JagCmCache *cache );
The cache name.
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 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.
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 EAServer Manager without requiring corresponding changes to your component source code.
In order for components to retrieve a cache with JagCmGetCachebyName, the EAServer Administrator must select the “Enable cache-by-name access” option for the cache in EAServer Manager. JagCmGetCachebyName fails if the cache does not have this option enabled.
Connection caches can be created, viewed, and modified with EAServer Manager. See Chapter 26, “Using Connection Management,” in the EAServer System Administration Guide for details.
