tpf_updateCacheEntry_ext: Add or update a cache entry with extended options
This function adds or updates an entry in a logical record cache with extended options.
Last updated
- Changed in 2022.
- Changed in 2019.
- Changed for PUT15.
- Changed for PUT13.
- Changed for PUT08.
- Added for PUT00.
Format
#include <tpf/c_cach.h>
int tpf_updateCacheEntry_ext(
const cacheTokenPtr 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,
int (*castOutFunction
(
const void *primaryKey_ptr,
const int *primaryKey_len,
const void *secondaryKey_ptr,
const int *secondaryKey_len,
const int *entry_len,
const void *entry_ptr,
const int *reserved
),
const int calltype
);
- 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
orCache_Invalidate
. If one of the following conditions is met, the tpf_updateCacheEntry_ext function modifies only the cache of this processor:- 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 the cache entry of any other processor for the specified entry. - castOutFunction
- A function pointer to a user-written function that is
called when logical record cache processing tries to remove
an entry from the cache.
For logical record caches that use recoverable system heap, specify the value for this parameter as NULL. If this parameter is not NULL and the cache uses recoverable system heap, a CACHE_ERROR_PARAM error occurs.
For logical record caches that have a castout function or castout program defined, the castout function that is specified for this parameter overrides the castout function or castout program that is specified for the cache.
For more information about the castout function, see Castout program or castout function.
- calltype
- The call type for the tpf_updateCacheEntry_ext function. Specify one of the following values:
- 0
- If the entry specified by the primary and secondary keys does not exist, the tpf_updateCacheEntry_ext function adds the entry to the cache. If the entry exists, the tpf_updateCacheEntry_ext function updates the existing cache entry.
- CACH_ADD_ONLY
- If the entry specified by the primary and secondary keys does not exist, the tpf_updateCacheEntry_ext function adds the new entry to the cache. If the entry exists, the tpf_updateCacheEntry_ext function does not update the existing entry and returns a CACHE_ERROR_RESTRICTED error.
- CACH_UPDATE_ONLY
- If the entry specified by the primary and secondary keys exists, the tpf_updateCacheEntry_ext function updates the existing entry. If the entry does not exist, the tpf_updateCacheEntry_ext function does not add the entry to the cache and returns a CACHE_ERROR_RESTRICTED error.
Normal return
- CACHE_SUCCESS
- The function is completed successfully.
- CACHE_NOT_FOUND
- A new entry was successfully added to the cache and the calltype parameter was not set to CACH_ADD_ONLY.
Error return
One of the following errors:
- 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.
- CACHE_ERROR_RESTRICTED
- Requested function was not performed because of the restriction specified by the calltype parameter value.
- CACHE_DUP_HASH_ERROR
- A duplicate hash value was generated for a processor-shared cache.
Programming considerations
- For z/TPF systems that support multiple subsystems, the castout function that is pointed to by the castOutFunction parameter must reside in a program that is loaded to the system as subsystem shared. The ECB subsystem information at the time the castout function is called might not be same as the subsystem information when the entry is being cast out by the cache.
- 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
#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.
rc = tpf_updateCacheEntry_ext(&cacheToken, &primaryKey, &primaryKeyLen, NULL, NULL,
&entryDataSize, &entryData, NULL, &invalidateOthers,
NULL, CACH_ADD_ONLY);
if (rc != CACHE_NOT_FOUND)
{
printf("tpf_updateCacheEntry_ext() failed with return code %d\n", rc);
}