CICS calculation of LSR pool parameters

If you have not specified LSR parameters for a pool, CICS® calculates the buffers and strings required for you.

To do this calculation, CICS scans all the installed file resource definitions for files specified to use the pool. For each file, it uses the following values:
  • From the CICS file resource definitions:
    • The number of strings, as specified on the STRINGS parameter
  • From the VSAM catalog:
    • The levels of index for each of these files
    • The control interval (CI) sizes
    • The keylengths for the base, the path (if it is accessed through an alternate index path), and upgrade set alternate index.

If you have specified only buffers or only strings, CICS performs the calculation for the buffers and strings you have not specified.

The following information helps you calculate the buffers required. A particular file might require more than one buffer size. For each file, CICS determines the buffer sizes required for the following components:
  • The data component
  • The index component, if it is a KSDS
  • The data and index components for the alternate index, if it is an alternate index path
  • The data and index components for each alternate index in the upgrade set, if any
The number of buffers for each file is calculated as follows:
  • For data components for base and alternate index = (STRINGS= in the file resource definition entry) + 1
  • For index components for base and alternate index = (STRINGS= in the file resource definition entry) + (the number of levels in the index) – 1
  • For data and index components for each alternate index in the upgrade set, one buffer each
When this calculation has been done for all the files that use the pool, the total number of buffers for each size is further calculated as follows:
  • The number is reduced to either 50% or the percentage specified in the SHARELIMIT in the LSRPOOL definition. The SHARELIMIT parameter takes precedence.
  • If necessary, the number is increased to a minimum of three buffers.
  • The number is rounded up to the nearest 4 KB boundary.
To calculate the number of strings, CICS determines the number of strings required to handle concurrent requests for each file as the sum of the following values:
  • STRINGS parameter value for the base
  • STRINGS parameter value for the alternate index (if it is an alternate index path)
  • n strings if there is an upgrade set (where n is the number of members in the upgrade set).
Note: If the LSR pool is calculated by CICS and the data sets have been archived by hierarchical storage manager (HSM), when the first file that needs the LSR pool is opened, the startup time of a CICS system can be considerably lengthened because the data sets are needed one by one. CICS obtains the necessary catalog information, but it does not open the database. Therefore the database is still effectively archived. This problem recurs when the region is started again, and remains until the data set has been opened.
When the strings have been accumulated for all files, the total number of buffers is further calculated as follows:
  • The total is reduced to either 50% or the percentage specified in the SHARELIMIT parameter in the LSRPOOL definition. The SHARELIMIT parameter takes precedence.
  • The total is reduced to 255 (the maximum number of strings allowed for a pool by VSAM).
  • The total is increased to the largest specified STRINGS value for a particular file.

The parameters calculated by CICS are shown in the CICS statistics.

Note: From z/OS® V2.2, VSAM provides a dynamic buffer addition capability that will allocate extra buffers for an LSR pool when no buffer is available for a given VSAM request. For CICS, it is preferable to retry the request rather than allow immediate expansion of an LSR pool, so dynamic buffer addition is not enabled for CICS LSR pools.

CICS provides metrics in both statistics and monitoring that can be used to tune LSR buffer allocations. Refer to the statistics for files for the number of times that tasks were queued as a result of buffer waits. Refer to exception monitoring data to identify which transactions are forced to wait and for how long.

Switching data sets from RLS mode to LSR mode

There might be occasions when you must switch a data set from RLS mode to non-RLS mode (for example, to read-only LSR mode during a batch update). This switch could lead to the LSR pools that are not explicitly defined, and which CICS builds using default values, not having sufficient resources to support files switched to LSR mode after the pool has been built.

To avoid files failing to open because of the lack of adequate resources, you can specify that CICS includes files opened in RLS mode when it is calculating the size of an LSR pool using default values. To specify the inclusion of files defined with RLSACCESS(YES) in an LSR pool that is being built using values that CICS calculates, specify RLSTOLSR=YES for this system initialization parameter (RLSTOLSR=NO is the default).

See RLSTOLSR system initialization parameter for more information about this parameter.

Data set name sharing

Data set name (DSN) sharing is the default for all VSAM data sets. It is specified as MACRF=DSN in the VSAM ACB. It causes VSAM to create a single control block structure for the strings and buffers required by all the files that relate to the same base data set cluster, whether as a path or direct to the base. VSAM makes the connection at open time of the second and subsequent files. Only if DSN sharing is specified does VSAM realize that it is processing the same data set.

This single structure offers the following benefits:
  • It provides VSAM update integrity for multiple access control blocks (ACB) updating one VSAM data set.
  • It allows the use of VSAM share options 1 or 2, while still permitting multiple update blocks within the CICS region.
  • It saves virtual storage.

DSN sharing is the default for files using both NSR and LSR. The only exception to this default is made when opening a file that has been specified as read-only (READ=YES or BROWSE=YES) and with DSNSHARING(MODIFYREQS) in the file resource definition. CICS provides this option so that a file (represented by an installed file resource definition) can be isolated from other users of that same data set in a different LSR pool or in NSR by suppressing DSN sharing. CICS ignores this parameter for files with update, add, or delete options because VSAM would not then be able to provide update integrity if two file control file entries were updating the same data set concurrently.

The NSRGROUP parameter is associated with DSN sharing. It is used to group file resource definitions that are to refer to the same VSAM base data set. NSRGROUP=name does not affect data sets that use LSR.

When the first member of a group of DSN-sharing NSR files is opened, CICS must specify to VSAM the total number of strings to be allocated for all file entries in the group, with the BSTRNO value in the ACB. VSAM builds its control block structure at this time regardless of whether the first data set to be opened is a path or a base. CICS calculates the value of BSTRNO used at the time of the open by adding the STRINGS values in all the files that share the same NSRGROUP parameter.

If you do not provide the NSRGROUP parameter, the VSAM control block structure can be built with insufficient strings for later processing. Avoid this structure for performance reasons. In such a case, VSAM invokes the dynamic string addition feature to provide the extra control blocks for the strings as they are required, and the extra storage is not released until the end of the CICS run.

Alternate index considerations

For each alternate index defined with the UPGRADE attribute, VSAM upgrades the alternate index automatically when the base cluster is updated.

For NSR, VSAM uses a special set of buffers associated with the base cluster. This set consists of two data buffers and one index buffer, which are used serially for each alternate index associated with a base cluster. It is not possible to tune this part of the VSAM operation.

For LSR, VSAM uses buffers from the appropriate subpool.

Take care when specifying to VSAM that an alternate index is in the upgrade set. Whenever a new record is added, an existing record deleted, or a record updated with a changed attribute key, VSAM updates the alternate index in the upgrade set. This update involves extra processing and extra I/O operations.

Situations that cause extra physical I/O

Some situations that can lead to many physical I/O operations, thus affecting both response times and associated processor path lengths, are as follows:
  • When a KSDS is defined with SHROPT of 4, all direct reads cause a refresh of both index and data buffers (to ensure the latest copy).
  • Any sequence leading to CICS issuing ENDREQ invalidates all data buffers associated with the operation. This situation might occur when you end a get-update (without the following update), a browse (even a start browse with a no-record-found response), a mass-insert, or any get-locate from a program. If the operation is not explicitly ended by the program, CICS ends the operation at sync point or end of task.
  • If there are more data buffers than strings, a start browse causes at least half the buffers to participate immediately in chained I/O. If the browse is short, the additional I/O is unnecessary.

Other VSAM definition parameters

Select free space parameters with care, because these parameters can help reduce the number of control interval (CI) and control area (CA) splits. Where records are inserted all over a VSAM data set, it is appropriate to include free space in each CI. Where the inserts are clumped, free space in each CA is required. If all the inserts take place at just a few positions in the file, allow VSAM to split the CA, and it is not necessary to specify any free space at all.

Adding records to the end of a VSAM data set does not cause CI or CA splits. Adding sequential records to anywhere but the end causes splits. An empty file with a low-value dummy key tends to reduce splits; a high-value key increases the number of splits.