readCacheEntry: Read a cache entry

This function reads a cache entry.

Last updated

  • Changed in 2022.
  • Changed in 2021 (information only; no code change).
  • Changed in 2019.
  • Changed for PUT13.

Format

#include   <tpf/c_cach.h>
int        readCacheEntry(const cacheToken * cache_to_read,
                          const void *primary_key,
                          const int  *primary_key_length,
                          const void *secondary_key,
                          const int  *secondary_key_length,
                                int  *size_of_buffer,
                                void *buffer);
cache_to_read
The cache token for the logical record cache where the entry is to be read.
primary_key
A pointer to a field that contains the value of the primary key.
primary_key_length
The length of the specified primary key. The length that is specified must be equal to or less than the value of the PRIMARY KEY SIZE attribute of the active cache.
secondary_key
A pointer to a field that contains the value of the secondary key. If a secondary key was not specified for the active cache, this field is ignored.
secondary_key_length
The length of the specified secondary key. The length that is specified must be equal to or less than the value of the SECONDARY KEY SIZE attribute of the active cache. If a secondary key was not specified for the active cache, this field is ignored.
size_of_buffer
A pointer to a field that contains the length of the passed buffer. This field is overlaid with the actual length of the data entry if the entry is found; otherwise, the length of the passed buffer remains unchanged.
buffer
A pointer to the area that is to be overlaid with the contents of the specified cache entry if the entry is found; otherwise, the buffer remains unchanged.

Normal return

CACHE_SUCCESS
The function is completed successfully.

Error return

CACHE_ERROR_HANDLE
The cache token provided for the cache_to_read parameter is not valid.
CACHE_ERROR_PARAM
The value that is passed for one of the parameters is not valid.
CACHE_NOT_FOUND
The cache entry was not read because it was not found in the cache.
CACHE_ERROR_CASTOUT
The application tried to read an expired entry. When logical record cache support tried to remove the entry from the cache, the specified castout function or program failed too many times.

Programming considerations

  • The primary and secondary keys must exactly match the primary and secondary keys that were used to add an entry to the cache. The entry control block (ECB) must have the same database ID (DBI) as the ECB used to create the entry.
  • Use the newCache, tpf_newCache_ext, or tpf_cacheNameToToken function to retrieve a logical record cache token.
  • For more information about when caches are re-created and reattached after an IPL, see Logical record cache IPL considerations.

Examples

The following example reads a cache entry from a cache that is named MYCACHE.
#include <tpf/c_cach.h>

cacheToken          cacheToken;
int                 rc;
int                 primaryKey = 1;
int                 primaryKeyLen = sizeof(int);
struct myCachedData returnedData;
int                 returnedDataSize = sizeof(struct myCachedData);

// Retrieve the cache token.
rc = tpf_cacheNameToToken("MYCACHE", &cacheToken);
if (rc != CACHE_SUCCESS)
{
  printf(“tpf_cacheNameToToken() returned unexpected return code %d\n”, rc);
  exit(0);
}

// Read the cache entry.
rc = readCacheEntry(&cacheToken, &primaryKey, &primaryKeyLen, NULL, NULL,
                    &returnedDataSize, &returnedData);
if (rc != CACHE_SUCCESS)
{
  printf(“readCacheEntry() failed with return code %d\n”, rc);
}