gtpc2m5nC/C++ Language Support User's Guide

readCacheEntry-Read a Cache Entry

This function reads a cache entry.

Format

#include   <c$cach.h>
long       readCacheEntry( const cacheToken * cache_to_read),
                           const void *primary_key,
                           const long *primary_key_length,
                           const void *secondary_key,
                           const long *secondary_key_length,
                                 long *size_of_buffer,
                                 void *buffer);

cache_to_read
The returned cache_token from the newCache function that defined the logical record cache.

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 must be equal to or less than the maximum value specified on the newCache function.

secondary_key
A pointer to a field that contains the value of the secondary key. If a secondary key length was not specified on the newCache function, this field is ignored and will contain a null pointer.

secondary_key_length
The length of the specified secondary key. The length must be equal to or less than the maximum value specified on the newCache function.

size_of_buffer
A pointer to a field that contains the length of the passed buffer. This field is overlayed with the actual length of the data entry.

buffer
A pointer to the area that is to be overlayed with the contents of the specified cache entry if the entry is found; otherwise, the buffer remains unchanged.

Normal Return

CACHE_SUCCESS
The function is completed successfully.

Error Return

One of the following:

CACHE_ERROR_HANDLE
The cache_token provided for the cache_to_read parameter is not valid.

CACHE_ERROR_PARAM
The value passed for one of the parameters is not valid.

CACHE_NOT_FOUND
The cache entry was not read because it was not found in the cache.

CACHE_ERROR_CACHE
The cache address has changed.

Programming Considerations

The primary and secondary keys must exactly match the primary and secondary keys used to add an entry to the cache. The entry control block (ECB) must have the same database ID (DBI) as the ECB used to create the entry.

Examples

The following example reads a cache entry from the file system directory cache.

#include <c$cach.h>
#include <i$glue.h>
 
    struct itran *tran;
    long   primaryKeyLgh = strlen( tran->itran_response.itres_name );
    long   secondaryKeyLgh = sizeof(ino_t);
    struct TPF_directory_entry tde;
    long   bufferSize= sizeof(struct TPF_directory_entry);
    struct icontrol * contrl_ptr; /* pointer file system control area */
 
    contrl_ptr = cinfc_fast_ss(CINFC_CMMZERO,
                  ecbptr()->ce1dbi);
 
    if ((contrl_ptr->icontrol_dcacheToken.token1 == 0)
        ||
       (readCacheEntry(&contrl_ptr->icontrol_dcacheToken,
                        &tran->itran_response.itres_name,
                        &primaryKeyLgh,
                        &tran->itran_response.
                                  itres_parent_inode.inode_ino,
                        &secondaryKeyLgh,
                        &bufferSize,
                        &tde) != CACHE_SUCCESS))
       [
               /* read directory entry from file  */
        ]
 

Related Information