newCache: Create a logical record cache

This function creates a logical record cache or retrieves a token for an existing logical record cache.

Last updated

Changed in 2022.
Changed in 2019.
Changed for PUT13.
Changed for PUT04.

Format

#include   <tpf/c_cach.h>
int        newCache (const void    *cache_name,
                     cacheTokenPtr cachetokenReturn,
                     const int     primary_key_length,
                     const int     secondary_key_length,
                     const int     data_length,
                     const int     number_entries,
                     const int     castoutTime,
                     const char    *type_of_cache,
                     const void    *cacheExt);

cache_name

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

The name must be 4–12 characters in length. If the name is fewer than 12 characters, any blank padding on the right is ignored.
The name must begin with an alphabetic character.
The name can contain numeric characters, uppercase alphabetic characters, the dollar sign ($), the at sign (@), or the underscore (_).
For processor-shared caches, the name must be identical on every processor in the complex that is caching the same data.

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. 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 in the range 1 - 256.

secondary_key_length

The maximum length of the secondary key for a cache entry. If you want the cache to use a secondary key to identify cache entries, specify a value in the range 1 - 256. If a secondary key will not be used, set this value to 0.

data_length

The maximum length of the data area for a cache entry in the logical record cache. The actual data element size can be less than the value of the data_length parameter. The value of the data_length parameter determines whether the cache is created as a traditional logical record cache or an enhanced logical record cache. Specify one of the following values:

For traditional logical record caches, which have a maximum entry size of less than or equal to 4096 bytes, the value of the data_length parameter must be in the range 1 - 4096.
For enhanced logical record caches, which have a maximum entry size of greater than 4096 bytes, the value of the data_length parameter must be in the range 4097 - 2147483647 or a value of 0. A value of 0 is specified to indicate that the maximum entry size is limited to the total size of the cache or 2147483647 bytes, whichever is less. For enhanced logical record caches, you must specify the total_cache_size field on the cacheExt parameter.

number_entries

The number of unique cache entries that the cache holds before the cache reuses cache entries. The value of the number_entries parameter must be in the range 1 - 999999999 for both traditional and enhanced logical record caches.

castoutTime

The number of seconds that a cache entry can reside in cache before it is cast out. After the specified number of seconds is reached, the cache entry is no longer valid. If an application tries to read the entry, a CACHE_NOT_FOUND error is returned. Specify a nonnegative integer value. If you specify a value of 0, entries in the cache do not expire unless you specify a castout time on the updateCacheEntry or tpf_updateCacheEntry_ext function.

type_of_cache

A pointer to a character that contains 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.

If the cache is defined to use recoverable system heap, you must specify Cache_ProcQ for the type_of_cache parameter.

cacheExt

Specifies one of the following values:

NULL
Indicates that the extended parameter block is not provided. If you specify NULL for this parameter, a traditional logical record cache is created by using 64-bit system heap. The cache does not use a castout program or castout function.
A pointer to an extended parameter block (cacheExtParam) structure.
Creates or retrieves a token for any of the following logical record cache types and options:
- Logical record caches that use recoverable system heap or a castout program.
- All enhanced logical record caches. You must specify the cacheExt parameter if the logical record cache is an enhanced logical record cache.
You must specify one of the following values for the version field of the cacheExtParam structure:

CACHE_EXTPARAM_VERSION_1

Specifies version 1 of the structure. Version 1 uses 64-bit system heap to back the logical record cache.
If you specify this version for an enhanced logical record cache, you must specify the following field:

total_cache_size

Sets the total size of the enhanced logical record cache. The minimum value must be the value of the number_entries parameter multiplied by 4096. For a traditional logical record cache, which has a maximum entry size in the range 1 - 4096, the total_cache_size field is ignored.

CACHE_EXTPARAM_VERSION_2

Specifies version 2 of the structure. Version 2 uses 64-bit system heap or recoverable system heap to back the logical record cache. Version 2 of the cacheExtParam structure contains all of the fields that are in version 1 and the following additional fields:

flag_ext

Indicates the type of system heap that is used to back the logical record cache.
Specify one of the following values:

CACHE_USE_64BIT_SYSTEM_HEAP

Indicates that 64-bit system heap is used to back the logical record cache. The logical record cache can be processor shared or processor unique.

CACHE_USE_RECOVERABLE_SYSTEM_HEAP

Indicates that recoverable system heap is used to back the logical record cache. The logical record cache must be processor unique.

castOutProgram

Specifies the 4-character name of a program that is called when logical record cache processing tries to remove an entry from the cache.
Specify a 5-byte array with a NULL-terminated string that contains the 4-character program name. If you do not want to specify a castout program, specify an empty string.

For more information about the castout program, see Castout program or castout function.

For more information about the cacheExtParam structure, see the code in the tpf/c_cach.h file.

Normal return

CACHE_SUCCESS: The function is completed successfully.

Error return

CACHE_ERROR_REDEFINE

The logical record cache already exists. The cache specifications on this request are different from the values that were specified when the existing cache was created. The values of the following parameters might cause the mismatch:

primary_key_length
secondary_key_length
data_length
type_of_cache
The flag_ext field of the cacheExt parameter

CACHE_ERROR_PARAM

The value that was passed for one or more of the parameters is not valid.

CACHE_ERROR_FULL

The maximum number of logical record caches that can be created was already reached.

CACHE_ERROR_GSYS

Unable to allocate the amount of system heap that is needed to hold the logical record cache.

Programming considerations

For z/TPF systems that support multiple subsystems, the castout program that is pointed to by the castOutProgram field must be a program that is loaded to the system as subsystem shared. The ECB subsystem information when the castout program is called might be different from the subsystem information when the entry is cast out by the cache.
For more information about when caches are re-created and reattached after an IPL, see Logical record cache IPL considerations.
If the newCache function is called and the cache already exists, the token for the existing cache is returned. However, to avoid the overhead that might occur with subsequent calls, ensure that the caller saves the cache token and passes that token to all future calls to logical record cache functions for the specified logical record cache. If the caller cannot pass the token to other applications that use the cache, other applications can use the tpf_cacheNameToToken function to retrieve the cache token.

Examples

The following example creates a new processor-shared traditional logical record cache that is backed by 64-bit system heap.

#include <errno.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>
#include <tpf/sysapi.h>
#include <tpf/tpfapi.h>
#include <tpf/c_cach.h>


int main(int argc, char **argv)
{
   int         rc = 0;
   int         primary_key_length = 8;
   int         secondary_key_length = 0;
   int         data_length = 4096;          //traditional logical record cache, specify 4k as entry size
   int         default_number_entries = 300;
   int         castOutTime = 10;
   char        cache_type = Cache_ProcS;    //processor shared
   cacheToken  cache_token;

   
   cacheExtParam cep;
   cacheExtParamPtr cepp = &cep;
   memset(cepp,0x00,sizeof(cep));
   cepp->version = CACHE_EXTPARAM_VERSION_2;
   //cepp->total_cache_size                 //total cache size is ignored for traditional LRC
   cepp->flag_ext = CACHE_USE_64BIT_SYSTEM_HEAP;        //cache backed by 64-bit system heap
   
   rc = newCache
        (
         "IBMCACHE_DRV",
         &cache_token,
         primary_key_length,
         secondary_key_length,
         data_length,
         default_number_entries,
         castOutTime,
         &cache_type,
         cepp
        );
  if (rc != CACHE_SUCCESS)
  {
     printf("Failure: newCache failed with rc = %d\n", rc);
     return -1;
  }
  printf("Success: newCache\n");
  return 0;
}

The following example creates a new processor-unique enhanced logical record cache that is backed by recoverable system heap and uses a castout program.

#include <errno.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>
#include <tpf/sysapi.h>
#include <tpf/tpfapi.h>
#include <tpf/c_cach.h>


int main(int argc, char **argv)
{
   int         rc = 0;
   int         primary_key_length = 8;
   int         secondary_key_length = 0;
   int         data_length = 5000;          //enhanced logical record cache, specify 5k as entry size
   int         default_number_entries = 500;
   int         castOutTime = 10;
   char        cache_type = Cache_ProcQ;    //processor unique
   cacheToken  cache_token;

   
   cacheExtParam cep;
   cacheExtParamPtr cepp = &cep;
   memset(cepp,0x00,sizeof(cep));
   cepp->version = CACHE_EXTPARAM_VERSION_2;
   cepp->total_cache_size = 2000000;                    //total cache size is about 2MB
   cepp->flag_ext = CACHE_USE_RECOVERABLE_SYSTEM_HEAP;  //cache backed by recoverable system heap
   strcpy(cepp->castOutProgram,"QZZZ”);
   rc = newCache
        (
         "IBMCACHE_DRV",
         &cache_token,
         primary_key_length,
         secondary_key_length,
         data_length,
         default_number_entries,
         castOutTime,
         &cache_type,
         cepp
        );
  if (rc != CACHE_SUCCESS)
  {
     printf("Failure: newCache failed with rc = %d\n", rc);
     return -1;
  }
  printf("Success: newCache\n");
  return 0;
}