IAM/PLEX CICS Considerations

Overview

CICS TS (Transaction Server) V5.3 and above customers can use IAM files under IAM/PLEX, without changes to their application programs or transactions.

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/PLEX under CICS. These exits are needed so IAM/PLEX can provide the required record locking protocols. Exits are used for IAM/PLEX 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 as can occur during an emergency restart. If these exits are not activated, then attempts to OPEN IAM files for IAM/PLEX 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/PLEX 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/PLEX CICS Exits

IAM customers that wish to use the IAM/PLEX functionality in their CICS regions must install and activate the provided Task Related User Exit (TRUE), BCICS, the provided Global User Exits (GLUE), XFCBO and XFCRQ, the CICS transaction program XCNTL. To do this, the following steps are required.

• Insure that modulesIAMXCINI, IAMBCICS, IAMXFCBO, IAMXFCRQ IAMXCNTL, and IAMXCINR are in a data set that is part of the DFHRPL concatenation in the CICS JCL.
• Insure that modules IAMXCINI, IAMBCICS, IAMXFCBO, IAMXFCRQ, IAMXCNTL and IAMXCINR are defined to CICS in DFHCSD.
• Each of the five modules (IAMXCINI, IAMBCICS, IAMXCFBO, IAMXCNTL, 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 ICL (IAM Installation Control Library) member IAMEXITS which should be reviewed prior to running the update job shown below.

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

IAM/PLEX and CICS Initialization

Using IAM/PLEX 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 as below:

Example of PLT Table for IAM Exits

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(XFCRQ) START
• EXEC CICS ENABLE PROGRAM(IAMXFCRQ) EXIT(XFCRQC) START
• EXEC CICS ENABLE PROGRAM(IAMBCICS) TASKSTART START

These commands activate the CICS customization exits at GLUE and TRUE points respectively for required IAM/PLEX 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/PLEX will cause at OPEN time, the following console messages to occur:

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

Within a CICS region, IAM has the capability to automatically disconnect and then subsequently reconnect to an IAM/PLEX instance after the IAM/PLEX address space has been terminated and then has restarted. This eliminates the need to restart or recycle one or multiple CICS regions that are sharingIAM data sets via the IAM/PLEX 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/PLEX instance being terminated and restarted.

Disconnect Process

An IAM/PLEX instance can terminate for a variety of reasons such as an operator issued a normal IAM/PLEX QUIESCE command or an MVS "P" (stop or halt) command to the IAM/PLEX instance or due to an abnormal termination or canceling of the IAM/PLEX instance. In either situation, IAM code within the CICS region determines that the IAM/PLEX region to which it is connected has terminated. Initially, the IAM 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/PLEX instance. While IAM is building this list of affected IAM files within the CICS region, IAM will 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/PLEX instance having been terminated) CICS will cause the UOWs to be retained, logged, and converted into “shunted UOWs”. These “shunted UOWs” will later get resolved when the affectedIAM file becomes available again.

Disconnect Messages

There are a variety of different messages that may be seen in different places when an IAM/PLEX instance is not 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 job log:

On the system console and CICS job log when the IAM/PLEX address space is on the same LPAR as the CICS region:

On the system console and job log when the IAM/PLEX instance is on another LPAR:

On the CICS Destination Log CSMT (DD=MSGUSR

Reconnect Process

When the IAM code within a CICS region determines that the IAM/PLEX address space has been subsequently restarted, IAM will issue a reconnect message and then using the saved list of IAM files IAM will attempt to reopen each of the affected files. Initially IAM will attempt a SET DATASET RETRY for each of the associated IAM data 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/PLEX 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/PLEX region can proceed.

Reconnect Messages

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

On the CICS Destination Log CSMT (DD=MSGUSR)

:

GLUE for Record Lock Time Out

For some IAM/PLEX 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/PLEX on the CICSLOCK parameter (See IAM-PLEX-Parameters). For those users, a program is provided that runs as a CICS Global User Exit (GLUE), which will purge transactions that receive the IAM/PLEX 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. (This is after the DFHPLT TYPE=ENTRY,PROGRAM=DFHDELIM.)
• Restart CICS.

The exit activator program, IAMXFCAT, issues the CICS SPI 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 IAMXFCAB itself checks the EIBRCODE for the IAM/PLEX deadlock-specific indicators, and if they are found it 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 at the GLUE exit point “XFCREQC”, should generally enable IAMXFCAB last, as CICS will run programs at exits in the order they were enabled.