gtpc2m55C/C++ Language Support User's Guide

newCache-Create a New Logical Record Cache

This function creates a new logical record cache.

Format

#include   <c$cach.h>
long       newCache (const void *cache_name,
                     cacheToken *cache_token,
                     const long *primary_key_length,
                     const long *secondary_key_length,
                     const long *data_length,
                     const long *number_entries,
                     const long  castoutTime,
                     const char *type_of_cache,
                     const long *reserved);
 

cache_name
The name of the logical record cache. The logical record cache name must meet the following requirements:

Logical record cache and coupling facility (CF) cache support use this information to name the logical record cache. See TPF Application Programming for more information about logical record cache support and TPF Database Reference for more information about CF cache support.

cache_token
The address of the cacheToken field where the assigned value for the cache token will be returned. This value is passed on all future cache access requests for the specified logical record cache. This value enables logical record cache support to uniquely identify the correct logical record cache for the request.

primary_key_length
The maximum length of the primary key for a cache entry. The value must be from 1 to 256.

secondary_key_length
The maximum length of the secondary key for a cache entry. The value must be from 1 to 256. If a secondary key will not be used, set this value to zero.

data_length
The maximum length of the data area for a cache entry in the logical record cache. The actual data element may be smaller than this value, but the storage allocation assumes the maximum data length. The value must be from 1 to 4096.

number_entries
The minimum number of unique cache entries the cache will hold before it begins to reuse the least-referenced cache entries. The value must be from 1 to 999 999 999. This value is used if there is no cache entry in the cache control record. If you have defined the logical record cache using the ZCACH command, the number of cache entries defined for the logical record cache in the cache control record is used. In other words, the value specified with the ZCACH command overrides that specified for the newCache function. See TPF Operations for more information about the ZCACH command.

For processor shared entries, this value is ignored if the cache is using a CF cache structure. If the cache must fall back to local mode because of the loss of all CFs, this value will be used as defined previously.

castoutTime
The number of seconds, specified as an integer value, that a cache entry can reside in cache before it is cast out. Once this value is reached, the cache entry is marked as not valid and results in a not found condition. This forces a cache update for the cache entry. If zero is specified, the cache entries are not aged out of cache.

type_of_cache
A defined value that indicates whether the cache is processor shared or processor unique. Code Cache_ProcS for processor shared. Code Cache_ProcQ for processor unique.

reserved
Reserved for future use by IBM. Set reserved to NULL.

Normal Return

CACHE_SUCCESS
The function is completed successfully.

Error Return

One of the following:

CACHE_ERROR_REDEFINE
The logical record cache already exists. The entry size values on this request are different than the values used to create the logical record cache.

CACHE_ERROR_PARAM
The value passed for one of the parameters is not valid.

CACHE_ERROR_FULL
The maximum number of logical record caches that can be created has already been reached.

CACHE_ERROR_GSYS
Unable to allocate the system heap to fulfill the logical record cache size request.

Programming Considerations

Examples

The following example creates a new logical record cache for holding file system directory entries.

#include <c$cach.h>
 
#include <i$glue.h>
 
   struct  icontrol * contrl_ptr;  /* pointer file system control area */
   char  cache_name [CACHE_MAX_NAME_SIZE]; /* cache name build area*/
   long  primeKeyLgh=NAME_MAX;          /* max lgh of a path name */
   long  secondaryKeyLgh=sizeof(ino_t); /* INODE ordinal numb lgh */
                    /* data length for directory cache */
   long  dataLgh=sizeof(struct TPF_directory_entry);
         /* invalidate entry after x seconds*/
   long  castOutTime = TPF_FS_CACHE_TIMEOUT ;
   char  cacheType=Cache_ProcS;    /* processor shared cache      */
 
 
             memset(cache_name, 0x00, CACHE_MAX_NAME_SIZE);
             strcpy(cache_name, TPF_FS_DIR_CACHE_NAME);
 
             contrl_ptr = cinfc_fast_ss(CINFC_CMMZERO,
                            ecbptr()->ce1dbi);
 
             if (newCache(&cache_name;
,
                          &contrl_ptr-;>icontrol_dcacheToken,
                           primeKeyLgh,
                           secondaryKeyLgh,
                           dataLgh,
                           numbEntries,
                           castOutTime,
                          &cacheType,
                          NULL) != CACHE_SUCCESS)
               {
                  printf("Error creating directory cache");
               }

Related Information