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.
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:
  1. Prepare for the command for execution.
  2. Check whether the EXEC CICS command is a LINK command. If it is not a LINK command, do not write the journal record.
  3. 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.
  4. 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.
  5. Restore registers and pass control to CICS IA.
For the sample of the user exit program see Figure 1.
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                                                  
***********************************************************************