The system branches to this exit whenever a system command is input, provided the task has been activated.
Three cases of command input can be distinguished:
the command is input interactively from a data display terminal
the command is input from a cataloged file (SPOOLIN, ENTER-JOB, CALL-PROCEDURE) or in remote batch mode
the command is issued via the MCLP interface from a TU program (see the “Executive Macros” manual [9]).
The SYSCMD exit routine enables the command flow of all active tasks during the OPEN session to be monitored.
The exit routine can:
accept the input command without modifications (return code EX080CAC)
reject the command (return code EX080CRJ)
modify or replace the command (return code EX080CRO)
insert one or more new commands (return codes EX080CRS/EX080CLR).
The return code of the exit routine must be stored in the EX080RC field of parameter area EX080. The address of the parameter area is passed to the exit routine in R1.
The following information is passed to the exit routine:
R1 = A(EX080 parameter area) R12 = A(TPR program manager) R13 = A(save area of calling component) R14 = A(indirect return) R15 = A(exit routine)
Notes
The contents of registers 12, 13 and 14 must not be destroyed by the exit routine.
The SYSCMD exit routine should process commands in the same way, regardless of how they were entered.
If the exit routine is deactivated while a command is replaced by several commands, the following dummy command record is sent to the user program:
/REMARK SYSCMDEXIT NO MORE ACTIVE DURING PROCESSINGIf commands are skipped in a procedure by means of /SKIP-COMMANDS, the exit routine is called once for each command skipped. The same applies in the case of an error when the spin-off mechanism (search for STEP, LOGOFF, SET-JOB-STEP) causes commands to be skipped.
Variable substitution has already been effected in CALL-PROC procedures when the exit is called.
In the case of branch flags, the branch destination is stored twice.
The information for the calling system module must be returned in the EX080RC field of the parameter area.
EX080 D
EX080PL DSECT
*-
*- INPUT INFORMATION
*-
EX080IND DC AL1(0) SOURCE OF COMMANDS
EX080TER EQU 1 -CMD READ FROM A TERMINAL
EX080FIL EQU 2 -CMD READ FROM A JCL FILE
EX080MCL EQU 4 -CMD READ VIA MCLP
EX080TRN EQU 8 -CMD READ VIA TRCMD 999
EX080BUF EQU 16 -CMD FOUND IN BS2000 BUFFER 999
*-
EX080BIT DC X'00' BIT_INFO 900
EX080SDF EQU X'80' -INPUT IN SDF STRUCTURED FORM002
EX080SD2 EQU X'40' -INPUT IN NEW SDF STRUCT FORM120
EX080STR EQU X'00' -INPUT IN STRING MODE 900
*-
EX080UNU DC 2X'00' 900
*-
EX080IR DC A(0) A (INPUT RECORD)
*-
*- OUTPUT INFORMATION
*-
EX080RC DC AL1(0) SYSCMD EXIT'S RETURN CODE
EX80CAC EQU 0 -CMD REC ACCEPTED
EX80CRJ EQU 4 -CMD REC REJECTED
EX80CRO EQU 8 -CMD REC REPLACED BY ONE
EX80CRS EQU 12 -CMD REC REPLACED BY SEVERAL
EX80CLR EQU 16 -LAST CMD REC REPLACED
DC 3X'00' UNUSED IN VER=710
*-
EX080RR DC A(0) A (RETURNED RECORD)
*-
*- ADDITIONAL INPUT INFORMATION
*-
EX080ILR DC A(0) A (LOWER CASE INPUT RECORD)
EX080STD DC A(0) A (STD FORM)
EX080PLL EQU *-EX080PL LENGTH OF SYSCMD EXIT P/L
Meanings of the fields:
EX080IND | Type of command input | |
EX080TER | command input from terminal | |
EX080FIL | command input from JCL file | |
EX080MCL | command input from user program via MCLP | |
EX080BIT | Indicator for SDF | |
EX080SDF | input in SDF structure | |
EX080STR | input not in SDF structure | |
EX080IR | Address of input command record | |
EX080RC | Return code | |
EX080CAC | command accepted | |
EX080CRJ | command rejected | |
EX080CRO | command modified or replaced | |
EX080CRS | command replaced by several commands | |
EX080CLR | last command record replaced | |
EX080RR | Address of command record returned to calling system component when command is modified or replaced | |
Meanings of the return codes in the EX080RC field
Return code X’04’: command rejection (EX080RC=EX080CRJ)
In interactive mode, no system message is output to the terminal. The exit routine can, however, send a message to the user.
In the case of command input from a cataloged file (PROC A or PROC C or corresponding SDF commands), the following message is output:
/REMARK COMMAND REJECTED BY THE SYSTEM ADMINISTRATOR
In batch mode the same message is entered in the logging file.
Return code X’08’: command replacement or modification (EX080RC=EX080CRO)
The exit routine itself must construct the new or modified command and pass the address of the command record to the calling system component via the EX080RR field of the parameter area.
Format of the command record (if not standardized SDF transfer area):
0 | 2 | 4 | RL-1 |
RL | command with operands |
where RL = record length
ISAM keys, continuation characters and symbolic parameters (&...) are not permitted in the command record. The record length may be modified.
In interactive mode, no system message is output.
In the case of command input from a cataloged file, the new or modified command is output or entered in the logging file.
When the command is input via MCLP, the replacing command must also be legal for MCLP, otherwise return code X’14’ (invalid command) is returned to the user program.No DO, CALL, LOAD, LOGOFF, ABEND, EXECUTE or corresponding SDF commands may be returned and no other command may be called via MCLP, since that would cause the user program to be unloaded immediately.
If an error occurs during processing of the new command, X’10’ (illegal command) is reported to the user program.
Return codes X’0C’ and X’10’: replacement of one command by several
(EX080RC=EX080CRS/EX080CLR)
If the exit routine returns a command record to the system (see RC = 08) and simultaneously sets the return code in the EX080RC field of the parameter list to X’0C’
(= EX080CRS), it is given control again immediately and can pass the next command record. As of the second call after return code X’0C’, the address of the input command record (field EX080IR in the parameter area) is set to zero. When the exit routine returns the last command, it must set the return code in the parameter area to X’10’ (=EX080CLR).
In interactive mode, no system message is output for the replacement of one command by several commands.
In batch mode, the replacing commands are written to the logging file.
When a command is entered via MCLP, the notes on return code X’08’ must be given due consideration. The commands mentioned above must not be returned via a command sequence, since this would cause the user program to be unloaded immediately. If a buffer has been provided in the user program for storing the results of MCLP command processing, this buffer must be able to accommodate the results of the entire command sequence. It is to be expected that many user programs working with MCLP calls will not run correctly when the exit routine replaces one command by several commands.