gtpa2m1z | Application Programming |
A Logical record cache is a set of system functions that allows an application to define and use memory caches. A cache is a hashed structure for holding information in lookaside storage buffers. A lookaside storage buffer is a temporary storage area where a copy of the data is saved to avoid refetching the data on every access. The data is retrieved from the temporary storage area instead of its permanent residence. The cache gives the application fast access to frequently used information without always needing to retrieve the information from an external storage device. The logical record caches are named caches that are subsystem shared, but the entries are subsystem unique. If two applications try to use the same name for their cache, the first call will create the cache and the second application will be connected to the created cache as long as the structure attributes of the create call for the second application are identical to the first application. Otherwise, the create call for the second application is returned with an error code.
Logical record caches are subsystem shared and either processor unique or processor shared. Processor unique caches contain information that pertains only to the processor where the information resides and does not need to be kept synchronous with the image of any other processor. Processor shared caches contain information that is shared across the processors in the complex so the information must be kept synchronous with the information contained in the caches for the other processors. In a processor shared cache, updating an entry will cause all other processors using the same named cache to have their representation of the information invalidated so that a CACHE_NOT_ FOUND return code is returned the next time the information is accessed.
Logical record cache support uses coupling facility (CF) cache support to maintain information synchronization between the same named caches residing in different processors in the complex. This synchronization is done through the cache name. At least one CF must be added to the locking configuration by using the ZCFLK ADD command before a logical record cache can use a CF. When a processor shared cache is created and a CF is available for use, a CF cache structure is created in the CF with the same name as the cache that is created. If the CF cache structure already exists, the processor is connected to the structure that already exists. The CF cache structure is a directory-only structure that is used to keep track of the entries that are in the cache of each processor. Through this mechanism, the processor copy of the cache is notified of an update to an entry by another processor, which causes the CF to invalidate the corresponding entry of the processor. CF cache structures are created with a disposition of DELETE (STRDISP=DELETE specified on the CFCONC macro). See TPF Database Reference for more information about CF cache support, CF cache structures, and structure persistence for CF cache structures. See TPF Operations for more information about the ZCFLK ADD command. See TPF System Macros for more information about the CFCONC macro.
The information held in the logical record cache must also be resident on an external storage device. A cache is lost over a processor IPL and must be reestablished by the application after an IPL occurs. There is no mechanism for preserving the contents of a cache over an IPL.
The logical record cache uses the database ID (DBI) in the entry control block (ECB) and the primary and secondary keys (which are passed on the function call) to identify entries in the cache. The DBI and the keys are hashed and the result is used to locate a specific entry in the cache. The primary and secondary keys can be from 1 to 256 characters in length. A cache must have a primary key length defined, but does not need a secondary key. The keys and the DBI are used to uniquely identify an entry in the cache. The length of the keys specified on the function calls must be less than or equal to the lengths specified on the create function call. Because the cache is hashed, an entry can only be found as long as the specified keys and DBI exactly match the keys on the entry. There is no way to perform a partial key search on the entries in the cache. When the cache is processor shared, the values of the keys and the DBI are hashed into a 14-byte hash name that is used to identify an entry to the CF. Because the CF and logical record cache support do not support synonyms for the 14-byte hash name, logical record cache support will not store two different entries that hash to the same 14-byte hash name. This is true whether the cache is using the CF or not.
When adding or updating an entry in the cache, it is the responsibility of the application to serialize the call. If the call is not serialized, it is possible for two ECBs on different central processing units (CPUs) in the same processor to try to add or update the same entry at the same time. If this occurs, logical record cache support adds the entry for one and then overlays it for the other. It is difficult to predict which CPU call will cause the information to be overlaid. This is also true for processor shared caches. To guarantee that the cache does not contain old information, the application should perform all adds and updates while maintaining an external serialization lock. Otherwise, it is possible for a cache invalidate to flow from one processor to another through the CF, and for the second processor to retrieve old information from the external storage device and add the information again before the first processor has completed updating the information.
The following are examples of caches the TPF system currently uses: