The latest release of IBM’s CICS transaction processing software, CICS Transaction Server (TS) for z/OS V3.2, contains many enhancements and is an exciting step in the development of CICS. This article describes CICS file control component enhancements, including some that were made in the base level of CICS TS V3.2 and others that were implemented via the IBM service channel after CICS TS V3.2 became available.
Shared Data Tables Larger Than 2GB
CICS has supported data tables since CICS/MVS V2 in the 1980s. Initially, they weren’t shared between CICS systems, but existed as in-memory versions of keyed files. Basic data table support came in user-maintained data tables and CICS-maintained data tables.
User-maintained data tables, intended as scratch pads for data that was expected to be needed only temporarily, provided fast read and write access. Since they existed only with memory, they could initially be loaded from an underlying VSAM file. After loading, the data table and the file were decoupled, so any subsequent changes to one weren’t reflected in the other.
CICS-maintained data tables worked similarly, but remained associated with their underlying VSAM file. They were automatically synchronized with any changes made to the associated file; their primary use was for optimized reads and browses of the file’s records, since these could be accommodated by retrieving the record data from memory and not via an I/O request to the underlying data set. This meant they were efficient at read-only operations.
CICS/ESA V3.3 extended data table support with the introduction of shared data tables support. This was originally an optional feature, but was incorporated into the base CICS product with CICS/ESA V4.1. Shared data tables replaced the original in-memory data tables. They stored the data component in a data space associated with a CICS system. The associated table entry and index components (which CICS used to access the associated data in the data space) were stored in the address space of the File-Owning Region (FOR) CICS system that owned the data table.
By exploiting access registers to reference the data space storage, impressive performance improvements could be achieved for read-only requests. Cross-memory shared read access considerably improved read-only requests against shared data table records held in data spaces owned by remote CICS systems in the same Logical Partition (LPAR).
A particular CICS system owns each shared data table; other CICS systems can read a table by means of program calls to cross-memory routines in the owning system. Shared data tables benefit because it’s more efficient to use z/OS cross-memory services instead of CICS function shipping to share a data file between multiple CICS systems in a z/OS image, and it’s more efficient to access data from memory than from DASD.
Exploiting cross-memory techniques like this avoids the overhead of a full-function shipped request from one CICS system to another. For requests that update records (such as rewrites or deletes), however, there’s still the need to function ship the request to the remote CICS, and to make the associated changes to the underlying file, too, in a transactional environment.
As with the original basic data tables implementation, shared data tables provide the user-maintained and CICS-maintained models for the two different varieties of data table. When they were implemented, shared data tables were limited to 2GB per CICS system. This was because the real storage available per z/OS image at the time was limited to 2GB. All shared data tables a CICS region owned were held in the same data space, so the combined data table size was limited to 2GB. However, subsequent enhancements to the z/Architecture have removed this limitation, and CICS TS V3.2 has now exploited removal of this restriction.
With CICS TS V3.2, the data components of a shared data table can now be stored across multiple data spaces. In addition to this space constraint relief, the table entry and index components of the table are no longer held in the owning FOR CICS system’s address space. Instead, they’re stored in their own separate data spaces. This provides virtual storage constraint relief for the owning CICS system.
CICS TS V3.2 creates three data spaces for its initial shared data tables support:
• DFHDT001 holds the table entry descriptors
• DFHDT002 holds the index nodes
• DFHDT003 holds the actual data records.
Each of the data spaces are initially allocated 16MB of virtual storage. CICS then automatically allocates additional data space storage as needed. Note: The z/OS system command D J,jobname can be used to show the data spaces allocated to a job such as a CICS system.
If a data space used for holding the record data reaches its maximum capacity of 2GB, CICS dynamically allocates a new data space. This allocation process continues until one of several events may occur. The table entry descriptor data space or index node data space may eventually fill up. Alternatively, the maximum number of supported data spaces (currently 100) may be in use by a CICS system. There also may be a data space limit as specified by the IEFUSI installation exit for z/OS.
You can migrate your data table owning FORs to CICS TS V3.2 to benefit from the additional data spaces available at that release. Application- Owning Regions (AORs) at lower releases can access the data tables in this way, and can be migrated to CICS TS V3.2 at a later date.
Extended ESDS Support
CICS has supported extended VSAM Key Sequenced Data Sets (KSDSs) for several releases. CICS wasn’t affected by the extended RBAs in the KSDS indexes. The complexity of extended RBAs was hidden from CICS. Indirectly, extended Relative Record Data Sets (RRDSs) and Variable Relative Record Data Sets (VRRDSs) also have been supported. The Relative Record Number (RRN) is still a 4-byte field, but in practice it can be used to access records well beyond the 4GB boundary, since this represents a 4-byte RRN, rather than a relative byte address where 4 bytes give the 4GB restriction.
Entry-Sequenced Data Sets (ESDSs) are sequential VSAM data sets. The records in them can be fixed or variable length and are accessed using Relative Byte Addressing (RBA). Records can be added only to the end of the data set, and although a record can be updated, the length of that record can’t be changed. Records in an ESDS can’t be physically deleted. To logically delete them, you must rewrite the records with a delete indicator or use GLUE XFCLDEL during a write backout. ESDSs can be browsed in either direction and alternate indices can be defined and used.
The RBA of a record is a 32-bit unsigned number assigned when created. The RBA is the number of bytes from the start of the data set to the record itself. The RBA is used to read a specific record, start a browse at a specific record, or reset the browse to a different record.
In DFSMS 1.5, VSAM changed. Until this point, VSAM only allowed an ESDS to be 4GB; only a 32-bit number was needed for its RBA values. However, as customer data requirements increased, more data needed to be stored in ESDS files and they began to reach the 4GB limiting size. This led to VSAM introducing a new flavor of ESDS called an “extended format, extended addressing data set.” Such data sets support 64-bit RBAs. In CICS, this new ESDS type is known as an extended ESDS. Until CICS TS V3.2, however, CICS limited its support of ESDS data sets to their original 4GB RBA limit.
To use an extended ESDS, you must create it in an extended format. You do so by selecting the DATACLAS keyword on the DEFINE CLUSTER SMS command in IDCAMS. This creates an ESDS with extra bytes for control information in each Control Interval (CI). It’s possible to create an extended ESDS in this way by accident; this caused problems in pre-CICS V3.2 environments because they couldn’t handle the required 64-bit RBA values. Attempts to open such data sets defined with the extended attribute failed with error message DFHFC0966, codes 8504, 0008, 0068 for non-Record Level Sharing (RLS). CICS Program Temporary Fix (PTF) UK40655 (APAR PK65454) results in message DFHFC0509 being issued in the same scenario for RLS.
The limitation for CICS was that an RBA is an unsigned 32-bit binary field limiting it to 4GB addressability. Now that VSAM allows ESDSs to be greater than 4GB, CICS needed to increase the addressability of an RBA so applications can easily take advantage of the potential for larger ESDS data sets. In CICS TS V3.2, this limitation is solved. The first change is that the EXEC CICS command level Application Programming Interface (API) has a new parameter— XRBA (Extended Relative Byte Address). This is now available for file control commands that previously supported the RBA parameter. XRBA is an 8-byte unsigned, 64-bit binary number.
Programs that are used to access an ESDS can be split into two categories, RBA-insensitive and RBA-sensitive.
RBA-insensitive programs don’t pass a specific RBA on any commands and are programs that simply read or write to the next sequential record. These would be applications that browse sequentially from the start of the file, or write to the end of the file. These programs should be able to work unaltered with extended ESDSs. Unfortunately, the same can’t be said of RBA-sensitive programs, since these would be applications that directly read or update a specific record by RBA and rely on RBA data.
RBA-sensitive programs will need to be altered to use XRBA so extended ESDSs can be exploited when migrating to CICS TS V3.2. If these programs aren’t amended to use XRBA, any request that specifies an RBA will fail with an ILLOGIC 110 response due to a VSAM 080068 error. Browse requests that start at a specific relative byte address other than zero are regarded as RBA-sensitive programs. Note messages DFHFC6037 or DFHFC6038 will be issued per file on the first application that attempts to access an extended ESDS file using the RBA option.
Although CICS has provided support for extended ESDS data sets, their use is still restricted. An extended ESDS can’t have an alternate index, for example. VSAM imposes this restriction. This means the only way to access an extended ESDS is through the base component of the cluster.
To use XRBA, insert it on commands instead of RBA and change the length of the RIDFLD variable to an 8-byte field. Note, however, there are some exceptions when using an XRBA:
• You can’t use it when function shipping a request to a remote CICS where the FOR is running CICS TS V3.1 or lower. In this case, the responses received on the AOR will vary, depending on the FOR’s CICS level.
• XRBA and RBA shouldn’t be mixed in a request. An example would be an EXEC CICS STARTBR command specifying XRBA, followed by an EXEC CICS READNEXT command with RBA specified.
CICS TS V3.2 doesn’t support XRBAs against a KSDS, as this method of accessing KSDS files via relative byte addresses is rarely used.
If you’re migrating to CICS TS V3.2 and don’t intend to use extended ESDSs, you can continue as is. However, if you would like to exploit this new VSAM option, here are some considerations to keep in mind before migration time:
• The forward recovery log and auto-journaling records need to cope with extended ESDSs. This should be done by checking all journaling applications that refer to file control log records. Changes were made to the log record formats, so utilities may need updating to take into account these changes.
• Migrate your FORs before your AORs. Otherwise, an application may attempt to access an extended ESDS that isn’t yet available, leading to function shipping errors. Failure to migrate in this order may result in ILLOGIC errors.
The format of the forward recovery and auto journal record had to be changed to accommodate the new 8- byte XRBA value. To indicate the file is an extended ESDS, the tie up record will have a data set type (FLJB_TUR_ DATASET_TYPE) of ‘X’ and FLJB_ TUR_BASE_KEY_LENGTH set to 8. For the update records, there’s a new bit for FLJB_BITS titled FLJB_GENERAL_ EXTENDED_ESDS (x’04’). The following FLJB fields for Common Data (CD) also have been changed. The FLJB_CD_ KEY_LENGTH will be set to 8 and the FLJB_CD_BASE_ESDS_RBA will be set to X’FFFFFFFF’. The 8-byte XRBA value will be in field FLJB_CD_KEY. The RBA value, in field FLJB_CD_BASE_ ESDS_RBA, being set to X’FFFFFFFF’ should force a failure in a utility that hasn’t been amended to use the new format records.
The CICS systems programmer will need to evaluate all GLUEs that use file control. Examples would be:
• XFCLDEL: GLUE for marking ESDS records as logically deleted
• XFCBFAIL,XFCBOUT,XFCBOVER: GLUEs for backout purposes
• XFCFRIN,XFCFROUT,XFCREQ, XFCREQC: entry and exit GLUEs.
The CICS systems programmer may need to develop new global exit programs for extended ESDSs, check existing global user exit programs, and modify those displays that are generated from the use of file control commands. When checking existing global user exit programs, be aware that UEP_FC_ RECORD_ID_TYPE can now be set to UEP_FC_XRBA, and FC_EIDOPT8 has a new value of x’08’ to show that XRBA is specified.
CICS application programmers must evaluate user applications. Applications that are RBA-sensitive must be revised and able to cater to the 8-byte XRBA value by changing RBA to XRBA on all the file control requests and the RIDFLD length from 4 to 8 bytes. Also, any calculations used to generate or obtain an RBA value must be reviewed to handle the larger 64-bit relative byte address.
The data administrator’s responsibility during migration is to ensure that ESDS data sets can be extended. This requires defining a new DATACLAS as extended, backing up existing ESDS data, changing the DATACLAS on applicable ESDS data sets, and restoring the data to the new extended ESDSs. After all these changes are made, you’ll be free to continue in an extended ESDS world.
Threadsafety
CICS TS V3.2 lets threadsafe applications use RLS files. So applications running on an open Task Control Block (TCB) won’t need to switch to the QR TCB in the AOR when issuing a request against an RLS file. This may allow increased throughput when compared to the model of a remote file accessed via an FOR. So, for some application mixes, there may now be good reason to convert files to RLS rather than access them via an FOR. File control requests to a remote file will still need to switch to the QR TCB, as will requests to a CICS data table, non-VSAM files and, prior to the application of PTF UK37688 (APAR PK45354), local VSAM files.
CICS TS V3.2 users running on z/OS 1.9 who have threadsafe programs can now exploit CICS file control threadsafety for local VSAM Local Share Resource (LSR) files by installing PTF UK37688.
The PTF cover letter should be carefully reviewed for the necessary prerequisite PTFs in both CICS and VSAM, and for any changes that may impact you. For example, the default for the FCQRONLY SIT option has been changed from NO to YES, meaning that the choice to use threadsafety in file control must be explicitly made. If you were previously exploiting threadsafety for CICS file control requests against VSAM RLS files and letting FCQRONLY default to NO, you must now explicitly set FCQRONLY(NO) after installing UK37688.
With UK37688 installed and FCQRONLY(NO) set, the following commands may now run threadsafe:
• File control requests to local VSAM LSR files, which are being run on a z/OS 1.9 system with the required prerequisites.
• File control requests to a VSAM RLS file.
For technical reasons, there are still some restrictions to using threadsafety in CICS file control. The following requests will still be made to run under the QR TCB by CICS:
• File control requests to a VSAM Non- Shared Resources (NSR) file
• File control requests to a local VSAM LSR file running on a pre-z/OS 1.9 system
• File control requests to remote files
• File control requests to Basic Direct Access Method (BDAM) files
• File control requests to CICS data tables.
To learn more about CICS file control threadsafety, reference these technical notes:
• 1264464 - PK45354 enables file control threadsafety for local VSAM LSR files
• 1219609 - MustGather: documentation for file control (VSAM non-RLS) waits in CICS on z/OS.
By enabling threadsafety in parts of file control, CICS has further extended the scope of its API that can execute under open TCBs, and improved its ability to exploit parallel processing capabilities under concurrent TCBs on multiple Central Processors (CPs).
Summary
The CICS TS V3.2 support for shared data tables larger than 2GB in size should be transparent to existing users of shared data tables in CICS. This enhancement hasn’t significantly changed the total amounts of real and virtual storage required for existing data tables. Most of the additional control information CICS uses to support these larger tables has been integrated into existing data area structures without requiring their expansion. Likewise, movement of the table entry descriptors and index nodes from out of the owning CICS system’s address space and into their own data spaces helps reduce the CICS storage requirements associated with these components.
CICS TS V3.2 support for extended ESDSs means you should follow several migration steps to ensure the forward recovery log, FORs, and AORs are updated in the appropriate order. Also, all applications, global user exits, and ESDS DATACLAS definitions need to be evaluated and potentially altered to allow use of extended ESDSs.
Finally, the continuing enhancements to the threadsafe support in CICS have enabled RLS and local VSAM files to use open TCBs for executing threadsafe application code that invokes file control requests. This provides the potential for significant performance improvements in those environments where threadsafe programs use RLS or local VSAM file control requests under open TCBs.
We hope this article has helped explain the background to these new and exciting enhancements to CICS.
