Dynamically resizable logical record cache support (APAR PJ46253 and corequisite z/TPFDF APAR PH30577) provides you with the capability to increase the number of entries in a logical record cache without losing the existing cached data.
Previously, to increase the number of entries in an existing logical record cache, you had to delete the cache and re-create the cache with an increased number of entries specified. All cached data was lost and the cache had to be repopulated. As a result, system resource usage might increase because applications had to make calculations or retrieve data from DASD to repopulate the cache.
With this support, you can use the ZCACH REFRESH command to increase the number of entries in a processor-unique traditional logical record cache while the cache is being used. In addition, existing cached data is not lost by increasing the number of cache entries. As a result, you can increase the number of entries in a cache without needing to repopulate the cache.
To dynamically add entries to an existing cache, you must first specify the maximum number of entries the cache can hold before the cache is created. After creating the cache, the actual number of entries can be altered by changing the number of entries attribute in the cache definition and then issuing the ZCACH REFRESH command to update the cache instance with the new, larger number of cache entries. Note that the number of entries can be increased, but not decreased for a cache. Also, multiple increases of the number of entries are allowed up to the maximum number of entries value set for the cache. The maximum number of entries for that cache can’t be changed without deleting and re-creating the cache.
For example:
- The following commands create a cache definition for the cache “MYCACHE”. We'll setup the cache definition with the number of entries (NUMENT) set to 2,000 and the maximum number of entries (MAXNUMENT) set to 8,000. This will allow us to create a cache with 2000 entries. The number of entries can be expanded in the future up to 8000 entries while it is still operational and without losing any existing cache data. The ZCACH DEFINITION command with the CREATE parameter specified, creates the cache definition which will be used to specify all information necessary to create our cache. The ZCACH DEFINITION command with the ALTER parameter specified, continues setting up the cache definition. Lastly, the ZCACH DEFINITION command with the DISPLAY parameter specified, shows us the values set within our completed cache definition.
==>ZCACH DEFINITION CREATE MYCACHE CACHETYPE-UNIQUE
CSMP0097I 12.28.44 CPU-B SS-BSS SSU-HPN IS-01
CACH0041I 12.28.44 THE CACHE DEFINITION WAS CREATED FOR CACHE MYCACHE WITH CACHETYPE-UNIQUE.+
==>ZCACH DEFINITION ALTER MYCACHE MAXNUMENT-8000 NUMENT-2000 MAXENTSIZE-2048 MEMTYPE-64bit PKEYLEN-16 SKEYLEN-0
CSMP0097I 12.27.04 CPU-B SS-BSS SSU-HPN IS-01
CACH0048I 12.27.04 THE CACHE DEFINITION WAS ALTERED FOR CACHE MYCACHE.+
==>ZCACH DEFINITION DISPLAY MYCACHE
CSMP0097I 12.27.46 CPU-B SS-BSS SSU-HPN IS-01 _
CACH0045I 12.27.46 CACHE DEFINITION ATTRIBUTE DISPLAY
CACHE NAME: MYCACHE
TYPE OF CACHE: PROCESSOR UNIQUE
CASTOUT PROGRAM: **NOT SET**
CASTOUT TIME: **NOT SET**
MAX ENTRY SIZE: 2048
MEMORY TYPE: 64-BIT SYSTEM HEAP _
PRIMARY KEY SIZE: 16
SECONDARY KEY SIZE: 0
NUMBER OF CACHE ENTRIES DEFINED: 2000
MAXIMUM NUMBER OF CACHE ENTRIES: 8000
TOTAL MEMORY USABLE BY CACHE ENTRIES: **NOT SET**
DISPLAY COMPLETE+
- Now lets create the actual cache instance. The ZCACH CREATE command creates the logical record cache from the cache definition we created above. We use the ZCACH DISPLAY ATTRIBUTES command to display the values used for this cache instance. We see that the values used within the cache instance are based on those specified in the cache definition above. At this point we have a usable cache with 2000 entries that can be populated and accessed by applications.
==>ZCACH CREATE MYCACHE
CSMP0097I 12.29.55 CPU-B SS-BSS SSU-HPN IS-01
CACH0050I 12.29.55 THE CACHE WAS CREATED FOR CACHE MYCACHE.+
==>ZCACH DISPLAY ATTRIBUTES MYCACHE
CSMP0097I 12.30.08 CPU-B SS-BSS SSU-HPN IS-01
CACH0035I 12.30.08 CACHE ATTRIBUTE DISPLAY
NAME MYCACHE , ADDR 0000000883659000
CACHE ENTRY BLOCK ADDR: 0000000883A00000
CACHE ATTRIBUTES: TRADITIONAL, PROCESSOR UNIQUE, NOT CONNECTED TO CF,
CACHE CREATION/DELETION SYNCHRONIZED,
CACHE IS BACKED BY 64-BIT SYSTEM HEAP
NUMBER OF CACHE ENTRIES DEFINED 2000
MAXIMUM CACHE ENTRIES ALLOWED 8000
NUMBER OF HASH ENTRIES DEFINED 3989
PRIMARY KEY SIZE 16 SECONDARY KEY SIZE 0
MAX ENTRY SIZE 2048
CASTOUT TIME 0
DISPLAY COMPLETE+
- Lets assume that the cache has been in use for some time and we have determined that the size of the cache, 2000 entries, is not adequate for our needs and we would like to increase its size. Prior to PJ46253 we would need to delete the original cache and create a new larger cache. With PJ46253, however, we simply increase the value of the NUMENT attribute in the cache definition using the ZCACH DEFINITION command with the ALTER parameter specified and issue the ZCACH REFRESH command to refresh the cache instance, bringing its number of entries up to 6000. Also, note that this was done in NORM state with application traffic using the cache while all of this is going on and no loss of cached data!
==>ZCACH DEFINITION ALTER MYCACHE NUMENT-6000
CSMP0097I 12.31.53 CPU-B SS-BSS SSU-HPN IS-01
CACH0048I 12.31.53 THE CACHE DEFINITION WAS ALTERED FOR CACHE MYCACHE.+
==>ZCACH DEFINITION DISPLAY MYCACHE
CSMP0097I 12.32.10 CPU-B SS-BSS SSU-HPN IS-01 _
CACH0045I 12.32.10 CACHE DEFINITION ATTRIBUTE DISPLAY
CACHE NAME: MYCACHE
TYPE OF CACHE: PROCESSOR UNIQUE
CASTOUT PROGRAM: **NOT SET**
CASTOUT TIME: **NOT SET**
MAX ENTRY SIZE: 2048
MEMORY TYPE: 64-BIT SYSTEM HEAP _
PRIMARY KEY SIZE: 16
SECONDARY KEY SIZE: 0
NUMBER OF CACHE ENTRIES DEFINED: 6000
MAXIMUM NUMBER OF CACHE ENTRIES: 8000
TOTAL MEMORY USABLE BY CACHE ENTRIES: **NOT SET**
DISPLAY COMPLETE+
==>ZCACH REFRESH MYCACHE
CSMP0097I 12.32.35 CPU-B SS-BSS SSU-HPN IS-01
CACH0062I 12.32.35 THE MYCACHE CACHE WAS SUCCESSFULLY REFRESHED.+
==>ZCACH DISPLAY ATTRIBUTES MYCACHE
CSMP0097I 12.33.00 CPU-B SS-BSS SSU-HPN IS-01
CACH0035I 12.33.00 CACHE ATTRIBUTE DISPLAY
NAME MYCACHE , ADDR 0000000883659000
CACHE ENTRY BLOCK ADDR: 0000000883A00000
CACHE ATTRIBUTES: TRADITIONAL, PROCESSOR UNIQUE, NOT CONNECTED TO CF,
CACHE CREATION/DELETION SYNCHRONIZED,
CACHE IS BACKED BY 64-BIT SYSTEM HEAP
NUMBER OF CACHE ENTRIES DEFINED 6000
MAXIMUM CACHE ENTRIES ALLOWED 8000
NUMBER OF HASH ENTRIES DEFINED 3989
PRIMARY KEY SIZE 16 SECONDARY KEY SIZE 0
MAX ENTRY SIZE 2048
CASTOUT TIME 0
DISPLAY COMPLETE+
This support also includes efficiency improvements to the existing logical record cache support. These improvements apply to all logical record caches on the z/TPF system. In addition, the display from the ZCACH DISPLAY command with the COUNTS parameter specified provides a more accurate estimate of the number of in-use entries for caches that use castout times.
For more information about APARs PJ46253 and PH30577, see the APEDITs.