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.
Possible return code values are shown in the following
table:
Table 1. User exit return code values
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.
***********************************************************************
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
***********************************************************************