deleteCacheEntry: Delete a cache entry

This function deletes an entry in a logical record cache.

Last updated

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

Format

#include  <tpf/c_cach.h>
int        deleteCacheEntry(const cacheToken *cache_to_delete,
                            const void *primary_key,
                            const int  *primary_key_length,
                            const void *secondary_key,
                            const int  *secondary_key_length);
cache_to_delete
The cache token for the logical record cache where the entry is to be deleted.
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.

Normal return

CACHE_SUCCESS
The function is completed successfully.

Error return

CACHE_ERROR_HANDLE
The cache token provided for the cache_to_delete parameter is not valid. When this error is returned, the entry is not removed from the cache.
CACHE_ERROR_PARAM
The value that was passed for one of the parameters is not valid. When this error is returned, the entry is not removed from the cache.
CACHE_ERROR_CASTOUT
The specified castout function failed too many times. When this error is returned, the entry is not removed from the cache.

Programming considerations

  • Primary and secondary keys must exactly match the primary and secondary keys that were used to add the entry to the cache.
  • The entry control block (ECB) must have the same database ID (DBI) as the ECB used to add the entry.
  • If the target cache is a processor-shared cache that uses CF, copies of the deleted entry in all other processors are invalidated.
  • 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 shows how to delete a cache entry from a cache that is named MYCACHE. 
#include <tpf/c_cach.h>

cacheToken cacheToken;
int        rc;
int        primaryKey = 1;

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

// Delete the cache entry.
// The last two parameters are NULL because this cache does not use secondary keys.
rc = deleteCacheEntry(&cacheToken, &primaryKey, sizeof(int), NULL, NULL);
if (rc != CACHE_SUCCESS)
{
  printf(“deleteCacheEntry() returned unexpected return code %d\n”, rc);
}