gtpc2m55 | C/C++ Language Support User's Guide |
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:
- The name must be 4 to 12 characters long and padded on the right with
blanks if necessary.
- The name must begin with an alphabetic character.
- The name can contain numeric characters, uppercase alphabetic characters,
the special characters $ or @, or underscore (_).
- The name must be identical on every processor in the complex that is
caching the same data.
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
- This function uses the contents of the cache control record and the
information specified with the ZCACH command to determine the size of the
logical record cache you are creating. If the logical record cache was
defined previously through the ZCACH command, its specifications override
those specified for the newCache function. If the logical
record cache has not been defined yet, the newCache function
creates the logical record cache using the passed values. See TPF Operations for more information about the ZCACH
command.
- For processor shared caches using the CF, enter the ZCFCH command to
override the logical record cache size. See TPF
Operations for more information about the ZCFCH command.
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