updateCacheEntry: Add or update a cache entry

This function adds or updates an entry in a logical record cache.

Last updated

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

Format

#include  <tpf/c_cach.h>
int       updateCacheEntry(const cacheToken *cache_to_update,
                           const void *primary_key,
                           const int  *primary_key_length,
                           const void *secondary_key,
                           const int  *secondary_key_length,
                           const int  *size_of_entry,
                           const void *entry_data,
                           const int  *timeout,
                           const char *invalidateOthers);
cache_to_update
The cache token for the logical record cache where the entry is to be updated.
primary_key
A pointer to a field that contains the value for the primary key.
primary_key_length
The length of the specified primary key. Specify a length that is 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. Specify a length that is 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_entry
A pointer to a field that contains the length of the passed entry data.
entry_data
A pointer to the area that contains the actual entry data to be saved in the logical record cache.
timeout
A pointer to an integer that indicates the number of seconds that a cache entry can reside in cache before it expires. 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.

If you specify NULL for the pointer or a value of 0 for the integer, the castout time that is specified for the cache is used. If a positive value is specified for the integer, this value overrides the castout time that is specified for the cache. If -1 is specified for the integer when an entry that is already in the cache is updated, the flush time for this entry is not reset for this update. If -1 is specified for the integer when a new entry is added to the cache, the castout time that is specified for the cache is used. Do not specify a negative value other than -1 for the integer.

invalidateOthers
A pointer to a char that is set to either Cache_NoInvalidate or Cache_Invalidate. If one of the following conditions is met, the updateCacheEntry function modifies only this processor's cache:
  • The pointer is NULL.
  • The pointer to a char is set to Cache_NoInvalidate.
  • The cache is processor unique.
  • A processor-shared cache is processing in local mode.

If the pointer to a char is set to Cache_Invalidate, logical record cache support tries to invalidate any other processor's cache entry for the specified entry.

Normal return

CACHE_SUCCESS
The function is completed successfully.

Error return

CACHE_ERROR_HANDLE
The cache token provided for the cache_to_update parameter is not valid.
CACHE_ERROR_PARAM
The value that is passed for one of the parameters is not valid.

Programming considerations

  • 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 adds a cache entry to a cache that is named MYCACHE.
#include <tpf/c_cach.h>

cacheToken          cacheToken;
int                 rc;
int                 primaryKey = 1;
int                 primaryKeyLen = sizeof(int);
struct myCachedData entryData;
int                 entryDataSize = sizeof(struct myCachedData);
char                invalidateOthers = Cache_Invalidate;

// Set up the cache entry data in the “entryData” structure.
.
.
.

// 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);
}

// Update the cache entry.
// NULL values are specified for the secondary_key and secondary_key_length
// parameters because this cache does not use secondary keys.
rc = updateCacheEntry(&cacheToken, &primaryKey, &primaryKeyLen, NULL, NULL,
                      &entryDataSize, &entryData, NULL, &invalidateOthers);
if (rc != CACHE_SUCCESS)
{
  printf(“updateCacheEntry() failed with return code %d\n”, rc);
}