The CICS IA Command Flow user exit
The CICS® IA Command Flow user exit provides additional options when you are saving information about the traced commands into the dataspace.
What is the CICS IA Command Flow user exit?
The CICS IA Command Flow user exit point (or the CICS IA Command Flow user exit point ) is a part of the CICS IA Command Flow collector, which is used by your written program to controls the information about CICS TS traced commands that is saved to the dataspace.
Besides the data written by the Command Flow collector, the CICS IA Command Flow user exit can write some additional information to the dataspace. Depending on the input data, the user exit might include or not include user-supplied data to the journal record, or might decline a journal record.
The CICS IA Command Flow collector invokes this user exit for the following CICS TS commands:- LINK
- XCTL
- START
Note: The CICS IA Command
Flow user exit runs as a part of the XEIOUT global user exit program.
For additional information about CICS TS
GLUE programming conventions refer to the CICS TS Customization Guide.
Writing the CICS IA Command Flow user exit program
The CICS IA Command Flow user exit program must be written in assembly language and must be reentrant.Register conventions
The following register
values are provided on entry to an exit program:
- Register 1 contains the address of the user exit parameter list.
- Register 13 contains the address of the standard register save area where your exit program should store its own registers immediately after being invoked.
- Register 14 contains the return address to which the exit program should branch on completion of its work. You do this by using the BR 14 instruction after restoring the calling module registers, or by using the RETURN macro.
- Register 15 contains the entry address of the exit program.
31-bit addressing implications
The implications
for the Command Flow user exit program are as follows:
- The CICS IA Command Flow user exit program is invoked in 31-bit AMODE.
- The user exit can be either RMODE 24 or RMODE ANY.
- If you find it necessary to switch to 24-bit AMODE in the exit program, make sure that you return correctly in 31-bit AMODE.
The user exit parameters list
When the Command Flow user exit is invoked, the CICS IA Command Flow collector that handles the user exit provides it with a parameters list. The address of this 32-byte parameters list is passed to register 1.The Command Flow user exit parameters list
contains the following eight entries:
- Parameter 1
- The address of the command arguments list.
- Parameter 2
- The address of an 8-character application program name.
- Parameter 3
- The reserved parameter.
- Parameter 4
- The address of a 128-byte work area provided for the user exit program.
- Parameter 5
- The address of a 48-character output field 1 in which your user exit program must return user data 1.
- Parameter 6
- The address of a 48-character output field 2 in which your user exit program must return user data 2.
- Parameter 7
- The address of a 48-character output field 3 in which your user exit program must return user data 3.
- Parameter 8
- The address of a 4-byte field in which your user exit program must return code 0, 4 or 8.
Return code | Return code meaning |
---|---|
0 | User exit completed. Add user-supplied resource data to the journal record. |
4 | User exit completed. Do not include user-supplied data in the journal record. |
8 | User exit completed. Do not log the journal record. |
Preparing the CICS IA Command Flow user exit program
The SCIUSAMP member, CIUCMDUE, contains the sample job for compiling and link editing the CICS IA Command Flow user exit and sample user exit programs. The Command Flow user exit program must be added to the RPL data set and defined to CICS TS with the CICS key.Activating the CICS IA Command Flow user exit program
To activate the CICS IA Command Flow user exit program, specify the name of the exit load module in the User Exit Name field on the CICS IA Command Flow Options panel, CIUA01. See Command Flow Options panel, CIUA01.The Sample User Exit program
The sample user exit program gives you a basic idea about how to use the CINC user exit interface. It allows journal records for the XCTL, START and LINK commands to be written only when the EXEC CICS LINK command occurs in the monitored program, and only if the control is passed from a specific program.The logic
of this program can be divided into the following steps:
- Prepare for the command for execution.
- Check whether the EXEC CICS command is a LINK command. If it is not a LINK command, do not write the journal record.
- Check whether the EXEC CICS LINK command was issued by the specific program. If it is not issued by the specific program, do not write the journal record.
- Fill the first User Data Area with the program name that is to be linked. Fill the second User Data Area with the content of COMMAREA, which was passed by that EXEC CICS LINK command.
- Restore registers and pass control to CICS IA.
Figure 1. The sample user exit program
***********************************************************************
EISPLI EQU X'02'
EISCOBOL EQU X'04'
EISASM EQU X'08'
COPY DFHEIPDS
R0 EQU 0
R1 EQU 1 PARAMETER REGISTER
R2 EQU 2
R3 EQU 3
R4 EQU 4
R5 EQU 5 CIUEPAR Base Register
R6 EQU 6 EXEC CICS ARG List Base Register
R7 EQU 7 EXEC CICS ARG0 Base Register
R8 EQU 8
R9 EQU 9
RA EQU 10
RB EQU 11
RC EQU 12 BASE
RD EQU 13 SAVE AREA
RE EQU 14 RETURN ADDRESS
RF EQU 15 ENTRY ADDRESS
EJECT
CIUUESMP CSECT
CIUUESMP AMODE 31
CIUUESMP RMODE ANY
SPACE
SAVE (14,12) SAVE REGISTERS
BALR RC,0 LOAD BASE REGISTER
USING *,RC
LR R5,R1 LOAD PARAMETER LIST ADDRESS TO R5
LR RB,RD
USING CIUEPAR,R5 BASE USER EXIT PARMLIST
L RD,MT_UE_WKAA LOAD WORK AREA ADDRESS TO R13
ST RB,4(,RD) SAVE OLD SAVE AREA ADDRESS IN WORK AREA
SPACE
DROP R1 EIA WAS BASED ON R1 IN COPYBOOK
L R6,MT_UE_ARGL LOAD ADDRESS OF EXEC CICS ARGS LIST
USING EIA,R6 BASE ADDRESSES OF EXEC CICS ARGS
L R7,EIAARG0 LOAD ARG0 ADDRESS
USING EID,R7 BASE ARG0
SPACE
CLC EIDFN,LINKID LINK COMMAND?
JNE SKIPADD NO, LEAVE
L R2,MT_UE_PGNA LOAD ADDRESS OF PROGRAM NAME, FROM
* WHICH EXEC CICS LINK GIVES CONTROL
LA R3,PROGNAME LOAD ADDRESS OF REQUIRED PROGRAM NAME
CLC 0(8,R2),0(R3) COMPARE CURRENT PROGRAM NAME WITH
* PROGRAM NAME WE ARE INTERESTED IN.
JNE SKIPADD LEAVE IF IT IS NOT THE DESIRED PROGRAM
L R2,MT_UE_DAT1A
MVC 0(19,R2),UDATA1 COPY STRING TO USER DATA FIELD ONE
L R3,EIAARG1 ADDRESS OF ARG1 - CALLED PROGRAM NAME
MVC 11(8,R2),0(R3) COPY IT TO USER DATA
L R2,MT_UE_DAT2A
MVC 0(9,R2),UDATA2 COPY STRING TO USER DATA FIELD TWO
CLI EIDOPT2,EIDCOMM DOES COMMAREA EXIST?
JNE NOCOMMA NO, WRITE THAT IT DOES NOT EXIST
L R3,EIAARG2 ADDRESS OF ARG2 - PASSED COMMAREA
MVC 11(22,R2),0(R3) PUT 22 BYTES FROM COMMAREA TO CIUUDAT2
J PUTRC0
NOCOMMA MVC 9(11,R2),NOCOMM COPY STRING TO USER DATA FIELD TWO
PUTRC0 L R2,MT_UE_RETCA
L R3,RC0
ST R3,0(,R2) SAVE RETURN CODE RC=0
J ENDPOINT
SKIPADD L R2,MT_UE_RETCA
L R3,RC8
ST R3,0(,R2) SAVE RETURN CODE RC=8
ENDPOINT L RD,4(,RD) RESTORE OLD SAVE AREA ADDRESS
RETURN (14,12) RESTORE REGISTERS AND
* RETURN TO CALLER
EJECT
* RETURN CODES:
RC0 DC F'0' USER EXIT COMPLETED. YOUR DATA WILL BE
* ADDED TO THE JOURNAL RECORD.
RC4 DC F'4' USER EXIT COMPLETED, YOUR DATA WILL
* NOT BE INCLUDED TO THE JOURNAL RECORD
RC8 DC F'8' USER EXIT COMPLETED,
* DO NOT LOG THE JOURNAL RECORD
* OTHER CONSTANTS:
LINKID DC X'0E02' EXEC CICS LINK COMMAND ID
PROGNAME DC C'FROMPROG' PROGRAM NAME WE ARE TRYING TO CATCH
NOCOMM DC C'NO COMMAREA'
UDATA1 DC CL11'CALLED PGM='
* 012345678901234567890123456789012345678901234567
UDATA2 DC CL9'COMMAREA='
* 012345678901234567890123456789012345678901234567
CIUEPAR DSECT
* CICS IA USER EXIT PARAMETERS
MT_UEPL DS 0CL32 User exit parmlist Overlays XPI work storage
* INPUT
MT_UE_ARGL DS A ADDRESS OF COMMAND ARG LIST
MT_UE_PGNA DS A ADDRESS OF 8-BYTE PROGRAM NAME
MT_UE_RSVA DS A RESERVED
MT_UE_WKAA DS A ADDRESS OF 128 BYTE WORK AREA
* OUTPUT
MT_UE_DAT1A DS A ADDRESS OF 48-BYTE USER DATA1 AREA
MT_UE_DAT2A DS A ADDRESS OF 48-BYTE USER DATA2 AREA
MT_UE_DAT3A DS A ADDRESS OF 48-BYTE USER DATA3 AREA
MT_UE_RETCA DS A RETURN CODE ADDRESS
END CIUUESMP
***********************************************************************