gtpa2m22Application Programming

Adding an Entry to a Logical Record Cache

To add an entry to a logical record cache, the application starts the updateCacheEntry function, passing the following as inputs:

If the data is to be individually timed, you can pass a pointer to a timeout value. If not, set the timeout parameter to NULL. The updateCacheEntry function works as both an add when the entry is not already in cache or as an update when the entry already exists in 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 Updating an Entry in a Logical Record Cache for more information about updating an entry in a logical record cache.

The following shows the function to add an entry to 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);     

Primary and Secondary Keys

If the target cache was defined with both a primary and a secondary key, both a primary and secondary key must be specified on a call to the updateCacheEntry function. If the cache was defined with only a primary key, only a primary key is passed. If a secondary key is specified, the updateCacheEntry function ignores it.

invalidateOthers Parameter

The invalidateOthers parameter is used to identify the updateCacheEntry function as a change to local cache only or as a change to all caches in the complex. Because this call is used to add the entry to the local cache so that the next readCacheEntry will find the entry, set the invalidateOthers parameter to either a NULL pointer or a pointer to a char of Cache_noInvalidate.

timeout Parameter

The timeout parameter is used to associate a lifetime, in seconds, to the entry. If the entry remains in 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 timeout parameter overrides the value specified for the castOutTime parameter on the newCache function call.

Examples

The following example shows how to add an entry with primary and secondary keys defined to the processor shared cache that was created previously.

char  primaryKey[ ] = "add 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_NoInvalidate;
 
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(
                    &myCacheShared,        /* addr of the token for the cache */
                     primaryKey,           /* primary key                     */
                    &primaryKeyL,          /* primary key length              */
                     secondaryKey,         /* secondary key                   */
                    &secondaryKeyL,        /* secondary key length            */
                    &dataL,                /* length of data to put in entry  */
                     data,                 /* address of data                 */
                     NULL,                 /* no timeout                      */
                    &invalidateOption)     /* invalidateOthers option         */
 
 
                      != CACHE_SUCCESS)    /* successful add                  */
    {
      printf("error on adding to Shared_Cache");   /* write message           */
      exit(1);                                     /* and exit                */
    }
 

The following example shows how to add an entry with a primary key to the processor unique cache that was created previously and has only primary keys defined.

 long        lifeTime = 180;                 /*life time of 180 seconds (3 min) */
 
strcpy( primaryKey, "add the entry with this key");
 primaryKeyL = strlen( primaryKey );         /* get length of primary Key       */
 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                   */
                       NULL)                 /* no invalidateOthers option      */
                       != CACHE_SUCCESS)     /* successful add                  */
    {
      printf("error adding entry to Unique_Cache");   /* write message  */
      exit(1);                                        /* and exit       */
    }