z/TPF - Group home

Dynamically Resizable Logical Record Cache (PJ46253)

  

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:

  1. 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+ 

 

  1. 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+

 

 

  1. 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.