gtpa2m23 | Application Programming |
To update an entry in a logical record cache, the application starts the updateCacheEntry function, passing the following as inputs:
If the new data is to be individually timed, a pointer to a timeout value can be passed. If not, set the timeout parameter to NULL. The updateCacheEntry function works as both an add when the entry is not already in the cache or as an update when the entry already exists in the cache. Therefore, the updateCacheEntry function can be used for both an add and an update; however, there is no way to determine whether the updateCacheEntry function performed an add or an update.
See TPF C/C++ Language Support User's Guide for more information about the updateCacheEntry function. See Adding an Entry to a Logical Record Cache for more information about adding an entry to a logical record cache.
The following shows the function to update an entry in a logical record cache:
long updateCacheEntry(const cacheTokenPtr cache_to_update, const void * primary key, const long * primary_key_length, const void * secondary key, const long * secondary_key_length, const long * size_of_entry, const void * entry_data, const long * timeout, const char * invalidateOthers);
If the target cache was defined with both a primary and a secondary key, both a primary and a secondary key must be provided on each call to the updateCacheEntry function. If the cache was defined with a primary key only, only a primary key is passed. If a secondary key is specified, the updateCacheEntry function ignores it.
The invalidateOthers parameter is used to identify this updateCacheEntry as a change to the local cache only (an add call; see Adding an Entry to a Logical Record Cache for more information about adding an entry to a logical record cache) or as a change to all caches in the complex (an update call). If the cache is a processor shared cache, the invalidateOthers parameter is then used to tell the logical record cache to invalidate this entry in all processors. If the entry is marked as an update type by setting the invalidateOthers value to Cache_Invalidate, the logical record cache will start CF support to inform any other processor that has registered interest in this cache entry that it has been changed. Do this when the source information is actually changed on permanent storage and is not used if this call was just to add the information to the local cache. Using the invalidateOthers parameter the wrong way can cause performance problems. If the invalidateOthers parameter is set to either a NULL pointer or a pointer to a char of Cache_NoInvalidate, the updateCacheEntry function call is considered an add or update of the entry in the local cache only. If the cache is a processor unique cache, there is no difference between the two types of calls (add or update) and the invalidateOthers parameter is ignored.
The timeout parameter is used to associate a lifetime, in seconds, to the entry. If the entry remains in the cache beyond this lifetime, the entry is invalidated and a CACHE_NOT_ FOUND return code is returned to the next readCacheEntry function that tries to read the entry. The new timeout parameter overrides the value specified for the castOutTime parameter on the newCache function call, overlays the value the updated entry may contain, and restarts the timeout function for the entry using the new value.
The following example shows how to update an entry with primary and secondary keys in the processor shared cache that was created previously and how to cause any other processors with the same entry to have the entry marked as invalidated.
char primaryKey[ ] = "update the entry with this key"; char secondaryKey[ ] = "using this secondary key"; char data[255] = "This is the data entry"; long primaryKeyL = 0; long secondaryKeyL = 0; long dataL = 0; char invalidateOption = Cache_Invalidate; /*force invalidation of other processors */ primaryKeyL = strlen( primaryKey ); /* get length of primary Key */ secondaryKeyL = strlen( secondaryKey ); /* get length of secondary Key */ dataL = strlen( data ); /* get length of data string */ if( updateCacheEntry ( &myCacheUnique, /* addr of the token for the cache */ primaryKey, /* primary key */ &primaryKeyL, /* primary key length */ NULL, /* no secondary key */ NULL, /* no secondary key length */ &dataL, /* length of data to put in entry */ data, /* address of data */ &lifeTime, /* entry timeout */ &invalidateOption) /* invalidateOthers option */ != CACHE_SUCCESS) /* successful add */ { printf("error updating entry in Unique_Cache"); /* write message */ exit(1); /* and exit */ }