IAM/RLS CICS Considerations

Additionally, there are no changes required to the IAM file definitions under CICS. There are a couple of IAM provided CICS exit routines that must be installed and activated to use IAM/RLS under CICS. These exits are needed so IAM/RLS can provide the required record locking protocols. Exits are used for IAM/RLS to recognize when a logical unit of work (UOW) completes due to a SYNCPOINT request, or transaction termination, which is done using the CICS Task Related User Exit (TRUE) facility. IAM also provides a CICS Global User Exit (GLUE) for backout, to recognize when a transaction backout is taking place that is subsequent to the original transaction, such can occur during an emergency restart. If these exits are not activated, then attempts to OPEN IAM files for IAM/RLS processing under CICS will be failed. There is an additional Global User Exit (GLUE) that is provided and must be installed if it is desired that IAM abend any transactions that have encountered lock contention and have indicated that IAM/RLS is to ABEND such transactions.

CICS RDO Settings

The RLSACCESS(NO) parameter must be set for IAM files at all times, even when being used under IAM/RLS and IAM/PLEX. The RLSACCESS(YES) is for real VSAM files only.

IAM/RLS CICS Exits

IAM customers that wish to use the IAM/RLS functionality in their CICS regions must install and activate the provided Task Related User Exit (TRUE), IAMBCICS, the provided Global User Exit (GLUE), IAMXFCBO, IAMXFCRQ and the CICS transaction program IAMXCNTL. To do this, the following steps are required.

• Make sure that modules IAMXCINI, IAMBCICS, IAMXFCBO, IAMXFCRQ, IAMXCNTL, and IAMXCINR are in a data set that is part of the DFHRPL concatenation in the CICS JCL.
• Make sure that modules IAMXCINI, IAMBCICS, IAMXFCBO, IAMXFCRQ, IAMXCNTL and IAMXCINR are defined to CICS in DFHCSD.
• The five modules IAMXCINI, IAMBCICS, IAMXFCBO, IAMXFCRQ and IAMXCINR must be defined with the following attributes:
• LANGUAGE=ASSEMBLER
• RELOAD=NO
• DATALOCATION=ANY
• EXECKEY=CICS.
• The module IAMXCNTL must be defined with the following attributes:
• LANGUAGE=ASSEMBLER
• RELOAD=NO
• DATALOCATION=ANY
• API=OPENAPI
• EXECKEY=CICS
• Alternatively, one can use the CICS batch utility program DFHCSDUP to define the IAM exits. The following JCL example shows how to run the CICS DFHCSDUP program to define the IAM exits to a specified CICS CSD (CICS System Definition file). The input as specified by the SYSIN DD card is the IAMSAMP member IAMEXITS which should be reviewed prior to running the update job shown below.

Example of JCL to update CICS CSD, Member IAMCSDUP in IAMSAMP

IAM/RLS and CICS Initialization

Using IAM/RLS and CICS requires that the IAM exits are defined and enabled during both the stage II and the stage III initialization phases of CICS. The IAM program IAMXCINI performs this initialization of the necessary exits and additional internal storage areas for IAM and must be added to the CICS PLTPI program table. The program IAMXCINI must be added to the second and third stage of the PLTPI list that is used at CICS startup. An example of how this might look is:

Example of PLT Table for IAM Exits

An alternate IAM startup PLTPI program is available to use in place of IAMXCINI called IAMXCINR. IAMXCINR should be used in place of IAMXCINI if a site is using or is planning on using the RLS options CONSISTENT and/or REPEATABLE on any of their application EXEC CICS READ requests. Note that if at IAM/RLS setup time your site is not currently using VSAM/RLS then it would not be possible to be using these EXEC CICS READ options, since these options would generate an error condition if the file was not defined with RLSACCESS(YES). IAMXCINR will enable program IAMXFCRQ for GLUE exits XFCREQ and XFCREQC. This will enable IAM/RLS support for the EXEC CICS READ CONSISTENT and REPEATABLE options. This GLUE exit enable IAM/RLS to also release record lock on non-recoverable files when CICS UNLOCK command is issued. Without IAMXFCRQ enabled, record lock set by CICS READ on a non-recoverable file is released only when a REWRITE happens or when the transaction ends. Running IAM/RLS GLUE exits XFCREQ and XFCREQC, does carry a fair amount of CPU overhead, therefore, we recommend you to use PLTPI program IAMXCINI and not IAMXCINR unless support for the CONSISTENT and REPEATABLE options and record lock release with CICS UNLOCK is important for the particular CICS region involved.

The IAM program IAMXCINI or IAMXCINR, in the PLTPI functions as an exit activator within CICS to initialize the IAM and CICS environment. They will issue some or all of the following CICS SPI (System Program interface) commands:

• EXEC CICS ENABLE PROGRAM(IAMXFCBO) EXIT(XFCBOUT) START
• EXEC CICS ENABLE PROGRAM(IAMXFCRQ) EXIT(XFCREQ) START
• EXEC CICS ENABLE PROGRAM(IAMXFCRQ) EXIT(XFCREQC) START
• EXEC CICS ENABLE PROGRAM(IAMBCICS) TASKSTART START

These commands activate the CICS customization exits at GLUE and TRUE points respectively, for required IAM/RLS functionality within the CICS region.

During CICS Initialization stages, IAM will issue to the CICS job log the following console messages:

CICS PLT Stage II messages:

CICS PLT Stage III messages:

The very first IAM file that is shared via IAM/RLS will cause at OPEN time, the following console messages to occur:

CICS Automatic Disconnect and Reconnect after a restart of IAM/RLS

Within a CICS region, IAM has the capability to automatically disconnect and then subsequently reconnect to an IAM/RLS address space after the IAM/RLS address space has been terminated and then has restarted. This eliminates the need to restart or recycle one or multiple CICS regions that are sharing IAM data sets via the IAM/RLS option.

The IAM code that does the setting of CICS FILEIDs closed, attempting the RETRY of shunted UOWs and then setting the FILEIDs OPEN and AVAILABLE, runs underneath the default transaction ID of $IAM, unless a different transaction ID has been specified in the IAM Global Options for the CICSTXID= operand. The transaction will run as a CICS OPENAPI subtask so as to facilitate the speedy disconnect and reconnects and closing and opening of IAM files affected by an IAM/RLS instance being terminated and restarted.

Disconnect Process

An IAM/RLS address space can terminate for a variety of reasons such as an operator issued a normal IAM/RLS QUIESCE command or an MVS "P" (stop or halt) command to the IAM/RLS instance or due to an abnormal termination or canceling of the IAM/RLS instance. In either situation, IAMcode within the CICS region determines that the IAM/RLS region to which it is connected has terminated. Initially theIAM code in CICS will build and maintain a list of the IAM files that were opened in CICS and being shared via the affected IAM/RLS address space. While IAM is building this list of affected IAM files within the CICS region, IAMwill attempt to set each of these IAM files to a CICS "CLOSED" state, when there are no active UOWs (unit-of-work) for the IAM file.

However, if there are active UOWs for an affected IAM file, then internally IAM code will issue a CICS 'FORCECLOSE" command. This "FORCECLOSE" command will cause any CICS tasks that have active UOWs to the IAM file to attempt to go through normal CICS backout. That is, they will be "rolled back" (any updates in flight will be backed out). However, as CICS will see the IAM file as being in a "not available" status (due to the IAM/RLS address space instance having been terminated) and CICS will cause the UOWs to be retained, logged, and converted into "shunted UOWs". These "shunted UOWs" will later get resolved when the affected IAM file becomes available again.

Disconnect Messages

There are a variety of different messages that may be seen in different places when an IAM/RLS instance is no longer active. Below are examples of these messages:

On a CICS terminal for in flight transactions at time of disconnect:

On the system console and the CICS joblog:

On the system console and CICS joblog:

On the CICS Destination Log CSMT(DD=MSGUSR

Reconnect Process

When the IAM code within a CICS region determines that the IAM/RLS address space has been subsequently restarted, IAM will issue a reconnect message and then using the saved list ofIAM files, IAM will attempt to reopen each of the affected files. Initially, IAM will attempt a SET DATASET RETRY for each of the associated IAMdata sets for each of the corresponding CICS FILEIDS in the saved IAM file list. This "RETRY" option will cause any existing "SHUNTED UOWs" to be retried. This causes the previously failed or shunted units of work that were in flight at the time that the IAM/RLS address space terminated to be rolled back (backed out). After the "shunted UOWs" have been retried, then IAM causes the affected CICS FILEIDs to be set to an OPEN and ENABLED state. At this point, normal processing and access to the IAM files via the connected IAM/RLS region can proceed.

Reconnect Messages

Shown below are examples of messages that can appear on the console and CICS joblog when IAM/RLS has been restarted:

On the CICS Destination Log CSMT (DD=MSGUSR)

GLUE for Record Lock Timeout

For some IAM/RLS users it may not be practical to deal with the “ILLOGIC” condition raised in CICS when a transaction has timed out while waiting for a record lock. This can occur if a customer has specified that time outs should occur when waiting for locks under IAM/RLS on the CICSLOCK parameter. For those users, a program is provided that runs as a CICS Global User Exit (GLUE), which will purge transactions that receive the IAM/RLS specific ILLOGIC condition.

A site wishing to activate this functionality needs to do the following:

• Make sure that modules IAMXFCAB and IAMXFCAT are in a data set that is part of the DFHRPL concatenation in the CICS JCL.
• Make sure that modules IAMXFCAB and IAMXFCAT are defined to CICS in DFHCSD.
• Add IAMXFCAT to the second stage of the PLTPI list that is used at CICS startup.
• Restart CICS.

The exit activator program, IAMXFCAT, programmatically issues the command “EXEC CICS ENABLE PROGRAM(IAMXFCAB) EXIT(XFCREQC) START”. This command causes CICS to enter IAMXFCAB at the conclusion of each file request made through the standard CICS API before returning control to the application logic.

The exit program itself checks the EIBRCODE for the IAM/RLS deadlock specific indicators, and if they are found it programmatically issues a command to purge the transaction. This results in a transaction abend with a code of AKC3. Users that decide to use this feature will have to determine if they wish to suppress this dump code or use the dumps to identify the files and the activities that are involved in dead lock situations.

Users that have other programs enabled for the XFCREQC exit should generally enable IAMXFCAB last, CICS will run programs at exits in the order they were enabled.

CILOCK

The CICS System Initialization Table (SIT) parameter CILOCK defaults to NO. This setting is intended to reduce the number of VSAM exclusive control conflicts when reading VSAM files for update. It does so by using extra CPU cycles and doing extra I/O. IAM locks at the record level, not at the control interval level, thereby eliminating this delay except when concurrent transactions are attempting to update the same records. Therefore, the CILOCK parameter should be set to YES when most or all of the VSAM files have been converted to IAM.

If CICS is running with the default CILOCK value of NO and IAM files are being shared with IAM/PLEX or IAM/RLS, then it is critical to provide a sufficient value for the VSAM STRINGS. Failure to do so can result in a CICS deadlock situation if a waiting for strings condition occurs.