gtpa2m21Application Programming

Reading an Entry from a Logical Record Cache

To read an entry from a logical record cache, the application starts the readCacheEntry function, passing the following as inputs:

See TPF C/C++ Language Support User's Guide for more information about the readCacheEntry function.

The primary and secondary keys must exactly match the primary and secondary keys that are used to add the entry to the cache. This includes both the content of the keys and their lengths. Additionally, the ECB must have the same DBI as the ECB that is used to add the entry. If the entry is found, as much of the data in the entry as possible is copied to the passed buffer, and the passed length field is overlaid with the length of the data copied.

The following shows the function for reading a logical record cache entry:

/*          Read a cache entry                */
 
long      readCacheEntry(const cacheTokenPtr  cache_to_read,
                 const void     * primary_key,
                 const long     * primary_key_length,
                 const void     * secondary_key,
                 const long     * secondary_key_length,
                 const long     * size_of_buffer,
                 const void     * buffer);

If the entry is found, a CACHE_SUCCESS return code is returned to the caller. If no entry is found, a CACHE_NOT_FOUND return code is returned to the caller. When you receive this return code, you can retrieve the entry from permanent storage and add it to a logical record cache by using the updateCacheEntry function. See Adding an Entry to a Logical Record Cache for more information about the updateCacheEntry function and using the function to add an entry to a logical record cache.

If the target cache was defined with a primary and secondary key, both a primary and a secondary key must be provided on each call to the readCacheEntry function. If the cache was defined with a primary key only, only a primary key should be passed. If a secondary key is provided, it is ignored by the readCacheEntry function.

Examples

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

char primaryKey[ ] = "find the entry with this key";
char secondaryKey[ ] = "using this secondary key";
char buffer[255];
long primaryKeyL = 0;
long secondaryKeyL = 0;
long bufferL = 255;
 
primaryKeyL = strlen( primaryKey );        /* get length of primary Key          */
secondaryKeyL = strlen( secondaryKey );    /* get length of secondary Key        */
 
if( readCacheEntry (&myCacheShared,        /* addr of the token for the cache    */
                     primaryKey,           /* primary key                        */
                    &primaryKeyL,          /* primary key length                 */
                     secondaryKey,         /* secondary key                      */
                    &secondaryKeyL,        /* secondary key length               */
                    &bufferL,              /* length of buffer to return data in */
                     buffer )              /* address of buffer                  */
                      !=CACHE_SUCCESS)     /* successful read                    */
   {
      printf("entry not found reading Shared_Cache");   /* write message  */
      exit(1);                                          /* and exit       */
    }
 

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

strcpy( primaryKey,  "find the entry with this key");
primaryKeyL = strlen( primaryKey );            /* get length of primary Key */
 
if( readCacheEntry ( &myCacheUnique,        /* addr of the token for the cache    */
                      primaryKey,           /* primary key                        */
                     &primaryKeyL,          /* primary key length                 */
                      NULL,                 /* no secondary key                   */
                      NULL,                 /* no secondary key length            */
                     &bufferL,              /* length of buffer to return data in */
                      buffer )              /* address of buffer                  */
                       !=CACHE_SUCCESS)     /* successful read                    */
    {
      printf("entry not found reading Shared_Cache");   /* write message  */
      exit(1);                                          /* and exit       */
    }