tpf_cacheNameToToken: Retrieve a cache token

This function retrieves the cache token for an existing logical record cache.

Last updated

  • Changed in 2022.
  • Changed in 2019.
  • Added for PUT13.

Format

#include  <tpf/c_cach.h>
int  tpf_cacheNameToToken(const char* cache_name, cacheTokenPtr cachetokenReturn);
cache_name
The name of the logical record cache.
cachetokenReturn
The address of the cacheToken field where the assigned value for the cache token is returned. This value is passed on all future calls to logical record cache functions for the specified logical record cache. Logical record cache support uses this value to identify the correct logical record cache for each function call.

Normal return

CACHE_SUCCESS
The function is completed successfully.

Error return

CACHE_ERROR_PARAM
The value that is passed for one of the parameters is not valid.
CACHE_ERROR_HANDLE
The cache that the cache_name parameter specifies does not exist.

Programming considerations

  • This function does not create a cache that does not exist. This function returns a token only for an existing logical record cache.
  • Logical record caches that are allocated by using recoverable system heap are typically reattached during logical record cache restart processing and survive an IPL. However, cache tokens are not preserved across an IPL. After an IPL, use this function to retrieve the current cache tokens.

Examples

The following example shows how to retrieve the cache token for an existing cache.
#include <tpf/c_cach.h>
int rc = 0; 
cacheToken     tokenReturn; 
rc = tpf_cacheNameToToken("MYCACHE_0001", &tokenReturn);
if(rc == CACHE_SUCCESS)    
    printf("Cache %s exists.\n",cacheName); 
else if(rc == CACHE_ERROR_HANDLE )    
    printf("Cache %s does not exist.\n",cacheName); 
else    
    printf("Error converting cache name %s to token.\n",cacheName);