CICS Agent User Exits

Agents › DevTest CICS Agent › CICS Agent User Exits

CICS Agent User Exits

ITKOUEX1 - DevTest CICS Agent Initialization Exit

This exit is called during the DevTest CICS Agent initialization. The exit can be used to:

Indicate the user group that this CICS region is a member of
Indicate the CICSPlex that this CICS region is a member of
Allocate storage and pass the address/length to other exits using the token parameter
Perform other initialization as required by other user exits

This exit is invoked through a CICS LINK, so it can be written in any language that CICS supports. During initialization, a CICS LINK to ITKOUEX1 is attempted.

If this exit is not necessary, take one of the following actions:

Do not include a module that is named ITKOUEX1 in the DFHRPL concatenation.
Disable the exit in the PPT.

Parameters are passed in COMMAREA.

The following table describes the parameters:

Parameter	Length in Bytes	Input or Output	Data Type	Description
Token	8	Input/Output	Unknown	Eight bytes that may be used by the user exits. Maintained across exit calls.
Group	8	Output	Character	Set by exit. Identifies a user group of which this CICS is a member.
CICSPlex	8	Output	Character	Set by exit. Identifies a CICSPlex of which this CICS is a member.
Sysid	4	Input	Character	CICS SYSID from CICS ASSIGN SYSID().
Applid	8	Input	Character	CICS APPLID from CICS ASSIGN APPLID().
Jobname	8	Input	Character	CICS job name from CICS INQUIRE SYSTEM JOBNAME().
LPAR	8	Input	Character	LPAR name from CVTSNAME in which this CICS resides.
Sysplex	8	Input	Character	SYSPLEX name from ECVTSPLX in which this CICS resides.

ITKO.CICSAGNT.CNTL(ITKOUEX1) contains a sample COBOL ITKOUEX1. This sample sets the user group to the first four characters of the CICS job name.

ITKO.CICSAGNT.CNTL(ITKOEX1C) contains the COBOL COMMAREA copybook.

ITKO.CICSAGNT.CNTL(ITKOEX1A) contains the Assembler COMMAREA copybook.

ITKO.CICSAGNT.CNTL(COMPUEX1) contains COBOL compile JCL.

ITKOUEX2 - DevTest CICS Agent Termination Exit

This exit is called during the DevTest CICS Agent termination. It can be used to perform any cleanup that user exits require (for example, free storage and close files).

This exit is invoked through a CICS LINK, so it can be written in any language that CICS supports. During the agent termination, a CICS LINK to ITKOUEX2 is attempted. If this exit is not necessary, take one of the following actions:

Do not include a module that is named ITKOUEX2 in the DFHRPL concatenation.
Disable the exit in the PPT.

Parameters are passed in COMMAREA.

The following table describes the parameters:

Parameter	Length in Bytes	Input or Output	Data Type	Description
Token	8	Input/Output	Unknown	Eight bytes that may be used by the user exits. Maintained across exit calls.

ITKO.CICSAGNT.CNTL(ITKOUEX2) contains sample COBOL ITKOUEX2.

ITKO.CICSAGNT.CNTL(ITKOEX2C) contains the COBOL COMMAREA copybook.

ITKO.CICSAGNT.CNTL(ITKOEX2A) contains the Assembler COMMAREA copybook.

ITKO.CICSAGNT.CNTL(COMPUEX2) contains the COBOL compile JCL.

ITKOUEX3 - LISA CICS COMMAREA Consolidation Exit

This exit is used to manage a COMMAREA that contains addresses that refer to storage outside of the COMMAREA. This exit consolidates the storage fragments with the COMMAREA to create a single contiguous COMMAREA.

This exit is called:

During the CICS LINK recording, for both the before and after images, to create a replacement COMMAREA with no addresses referencing data outside the COMMAREA. The exit is responsible for GETMAINing the new storage area. The DevTest CICS Agent will FREEMAIN the area. Addresses in the COMMAREA that point to locations within the COMMAREA are also problematic. In this case, the exit should convert the addresses to relative offsets during recording and revert them to real addresses during playback.
During CICS LINK playback (virtualization) to restore the original COMMAREA from the DevTest response.
During CICS Agent initialization (after user exit 1) so the exit can perform any additional initialization tasks.
During CICS Agent termination (before user exit 2) so that the exit can perform any additional termination tasks.

This exit is invoked through a CICS LINK, so it can be written in any language that CICS supports. However, assembler language is best suited to address manipulation and variable length data movement. During initialization, a CICS LINK to ITKOUEX3 is attempted.

If this exit is unnecessary, take one of the following actions:

Do not include a module named ITKOUEX3 in the DFHRPL concatenation.
Disable the exit in the PPT.

Parameters are passed in COMMAREA.

The following table describes the parameters:

Parameter	Length in Bytes	Input or Output	Data Type	Description
Token	8	Input/Output	Unknown	Eight bytes that may be used by the user exits. Maintained across exit calls.
Call Type	1	Input	Binary	12 indicates Playback 16 indicates Termination
Image Type	1	Input	Binary	4 indicates a Before Image 8 indicates an After Image
COMMAREA Address	4	Input	Address	Address of COMMAREA passed on the application CICS LINK.
COMMAREA Length	2	Input	Binary	Length of COMMAREA passed on the application CICS LINK.
Calling Program	8	Input	Character	Name of program issuing the CICS LINK command.
Target Program	8	Input	Character	Name of program being LINKed to.
New COMMAREA Address	4	Input/Output	Address	For recording: The address of the new consolidated COMMAREA is placed here by this exit. This exit typically GETMAINs the area. For Playback: The address of the new consolidated COMMAREA from the VSE response is placed here. This exit copies the contents to the application COMMAREA.
New COMMAREA Length	2	Input/Output	Binary	For recording: The length of the new consolidated COMMAREA is placed here by this exit. For Playback: The length of the new consolidated COMMAREA from the VSE response is placed here for this exit to use.
Return Code	1	Output	Binary	0 indicates that the COMMAREA was successfully consolidated. The DevTest CICS Agent will use the New COMMAREA Address and New COMMAREA Length to create the recorded image. 4 indicates that this exit was successful; however there is no new COMMAREA created. The DevTest CICS Agent uses the COMMAREA from the CICS LINK to create the recorded image. 8 indicates that this exit failed and there is no new COMMAREA. The DevTest CICS Agent returns to the application from the CICS LINK with EIBRCODE, EIBRESP and EIBRESP2 as indicated in the following parameters. 12 indicates all the processing of return code 8, and the indication that this exit should be removed from future DevTest CICS Link recording and playback.
EIBRCODE	6	Output	Binary	The EIBRCODE value to be used when the Return Code is 8 or 12.
EIBRESP	4	Output	Binary	The EIBRRESP value to be used when the Return Code is 8 or 12.
EIBRESP2	4	Output	Binary	The EIBRRESP2 value to be used when the Return Code is 8 or 12.

Assembler language sample ITKOUEX3 is in ITKO.CICSAGNT.CNTL(ITKOUEX3).

This sample manages a COMMAREA in the format that the Software AG Natural language produces when calling COBOL with the Natural parameter CALLRPL=(ALL,3) or CALLRPL=(ALL,4). With this format of COMMAREA, the COMMAREA length is 12 (when CALLRPL=(ALL,3) is used) and 16 (when CALLRPL=(ALL,4) is used). The first fullword in the COMMAREA is the address of a parameter list. The high-order bit set to 1 in the address indicates the last parameter. The third fullword is the address of a list of parameter lengths.

ITKO.CICSAGNT.CNTL(ITKOEX3A) contains the Assembler COMMAREA copybook.

ITKO.CICSAGNT.CNTL(ASMBUEX3) contains the assembly JCL.