The JCL component provides a facility called the JCL user exit, which enables you to monitor and control various events that occur during execution of a job or TSO session. Certain events enable the user exit to alter the actions that follow the event. For example, when a job is submitted for execution, the user exit can modify the job or create a new one.
This section introduces information that you need to be familiar with before you can take advantage of JCL user exits.
When you submit a job (by clicking Submit on the JCL Control page of ESMAC, for example), a new process, called the parent process, is created in which job preparation and all resource allocation for all job steps of the job occurs. Then, if the job preparation and resource allocation is successful, for each program execution, MSS creates a child process in which the program runs. When the program finishes, the child process ends and the parent process wakes up to perform resource deallocation including such actions as disposition processing.
As far as the user exit is concerned, it has knowledge of the following:
A user exit in the child process has no knowledge of events in the parent process, and vice versa.
The user exit, which must be named MFJUXIT, is optional and is invoked as follows:
CALL 'MFJUXIT' USING JXIT
Where JXIT is the user exit interface block (mfjdxit.cpy). It contains
mfjdxit.cpy describes in detail all of the event codes, actions codes, and the data associated with each event. When looking at mfjdxit.cpy, note the following:
The user exit is called as events occur.
Most events occur in the batch initiator SEP. The exceptions are:
A JCL user exit can remember only the events in the process from which it was invoked.
If the user exit fails for any reason, it is disabled in the failing process for all subsequent events.
Notes:
For each event, this section defines the key (but not all) inputs and outputs and the actions that can be requested for the event. The following actions apply to all events:
The event names listed below correspond in part to the level-88 name assigned to the event code. Similarly, action code names listed correspond in part to the level-88 name assigned to the action code. Having access to the mfjdxit.cpy file will help your understanding of the facilities being described here.
Note: Not all of the events described in this section are currently implemented. The description of an event indicates if it is not currently implemented. If any of the unimplemented events would be of use in your organization, please contact your Micro Focus Sales or Support representative.
Indicates that the program has returned to the system. On of these events occurs for each Event-before-PGM-call. The purpose of this event is to enable your user exit to perform any processing (such as deleting of programs that were loaded when the Event-before-PGM-call occurred) after the end of the program.
This event and Event-before-PGM-call occur in the child process. All other events occur in the parent process. You exit cannot remember any events that occurred in the parent process.
This event is currently not implemented.
Data available for this event includes:
You cannot request any actions for this event; only the default action will take place.
Indicates that the initial program (equivalent of the PGM= JCL parameter) is about to be invoked. This event occurs once for each step (for PGM= program), once for each CALL command (for the program named on the command), and once for each RUN subcommand of the DSN command (for the program named on the subcommand).
For a job step, the difference between this event and Event-step-ready is that this event occurs in the child process giving the user exit the opportunity to do things on behalf of the program about to be invoked. For example, if you need to load special modules that the program will be using, this would be the time to do it. This event does not permit you to change data such as program name, whereas Event-step-ready does.
The purpose of this event is to allow your user exit to perform any processing (such a loading of programs to avoid name conflicts or for other reasons) before the program is invoked.
This event and Event-after-PGM-call occur in the child process. All other events occur in the parent process. Your exit cannot remember any events that occurred in the parent process.
This event is currently not implemented.
Data available for this event includes:
You cannot request any actions for this event; only the default action will take place.
Indicates that the job step has ended.
This event is currently not implemented.
Data available for this event includes:
The following actions can be requested for this event:
Indicates that a TSO CALL command is about to be executed.
This event is currently not implemented.
Data available for this event includes:
The following actions can be requested for this event:
This event indicates that the CALL command has started.
This event is currently not implemented.
Data available for this event includes:
You cannot request any actions for this event; only the default action will take place.
Indicates that the job has ended. This event enables the user exit to examine or change job termination information.
Data available for this event includes:
The following actions can be requested for this event:
Indicates that a job has been flushed either because the user exit requested it to be done or for other reasons for which JCL may flush the job, for example, an invalid job name or missing JOB card.
This event is currently not implemented.
Data available for this event includes:
You cannot request any actions for this event; only the default action will take place.
Indicates that the job failed with a JCL error.
This event is currently not implemented.
Data available for this event includes:
You cannot request any actions for this event; only the default action will take place.
Indicates that a request to submit a job has been received, although the job being submitted has not been read and nothing has been done to it. Note that it is possible that the file containing the job does not even exist, but it very likely does. This event enables the user exit to verify or modify the job that is being submitted.
Data available for this event includes:
The following actions can be requested for this event:
Indicates that the job execution has completely finished and any spool output is ready for viewing or printing. The purpose of this event is to allow the user exit (or processes triggered by it) to access the job’s log and other spool output.
Data available for this event includes:
You cannot request any actions for this event; only the default action will take place.
Indicates that the job has been started.
Data available for this event includes:
You cannot request any actions for this event; only the default action will take place.
Indicates that the job step has ended.
This event is currently not implemented.
Data available for this event includes:
The following actions can be requested for this event:
Indicates that a DSN RUN subcommand is about to be executed.
This event is currently not implemented.
Data available for this event includes:
The following actions can be requested for this event:
Indicates that the RUN subcommand of the DSN command has started.
This event is currently not implemented.
Data available for this event includes:
You cannot request any actions for this event; only the default action will take place.
Indicates that the job step has been bypassed. Event-specific data is exactly is exactly the same as Event-job-started.
This event is currently not implemented.
Data available for this event includes:
You cannot request any actions for this event; only the default action will take place.
Indicates that the job step has ended.
Data available for this event includes:
The following actions can be requested for this event:
Indicates that a job step is about to be executed. This event is similar to Event-before-PGM-call, except that this event occurs in the parent process and enables the user exit to change information such as program name, whereas Event-before-PGM-call does not.
This event enables the user exit to examine or change program alias name, program name and parameter string information.
This event does not occur for TSO sessions.
Data available for this event includes:
The following actions can be requested for this event:
Indicates that the job step has been started.
Data available for this event includes:
You cannot request any actions for this event; only the default action will take place.
Indicates that a TSO session has ended.
This event is currently not implemented.
Data available for this event includes:
The following actions can be requested for this event:
Indicates that a TSO session has been started.
This event is currently not implemented.
Data available for this event includes:
You cannot request any actions for this event; only the default action will take place.
This section briefly describes the events that can occur in each of the following environments:
The events that can occur and their sequence is as follows:
| Event-job-ready followed by one of | |||||||
| Event-job-flushed | |||||||
| Event-job-JCL-error | |||||||
| Event-job-started followed by (for each step in the job, one or more times) | |||||||
| Event-step-ready, followed by one of | |||||||
| Event-step-bypassed | |||||||
| Event-step-started, followed by | |||||||
| Event-before-PGM-call | |||||||
| Event-after-PGM-call | |||||||
| Event-step-ended | |||||||
| Event-job-ended | |||||||
The events that can occur and their sequence is as follows:
| Event-job-ready followed by one of | |||||||
| Event-job-flushed | |||||||
| Event-job-JCL-error | |||||||
| Event-job-started followed by (for each step in the job, one or more times) | |||||||
| Event-step-ready, followed by one of | |||||||
| Event-step-bypassed | |||||||
| Event-step-started, followed by | |||||||
| Event-before-PGM-call, followed by any combinations of | |||||||
| For each CALL command (zero or more times) | |||||||
| Event-CALL-ready | |||||||
| Event-CALL-started, followed by | |||||||
| Event-before-PGM-call | |||||||
| Event-after-PGM-call | |||||||
| Event-CALL-ended | |||||||
| For each DSN RUN subcommand (zero or more times) | |||||||
| Event-RUN-ready | |||||||
| Event-RUN-started, followed by | |||||||
| Event-before-PGM-call | |||||||
| Event-after-PGM-call | |||||||
| Event-RUN-ended | |||||||
| Event-after-PGM-call | |||||||
| Event-step-ended | |||||||
| Event-job-ended | |||||||
There is no currently no support for logging Interactive TSO activity or for the TSO execution in JCL (TSO in batch). JCL activity is logged in the MVS data set MFMVS.SYSLOG.
You can use the user exit to control the logging of the implemented events as follows:
This logging state persists until it is changed again by the user exit. You can change the logging state as often as required.
This section presents a listing of the mfjdxit.cpy copybook used by JXIT. The source for this copybook is in \mfe\base\source.
*===============================================================
* Copyright (C) 1985-2002 Micro Focus International Ltd.
*===============================================================
*
* MFJDXIT - JCL User Exit Control Block
* Contains interface information and is passed as a parameter
* to the JCL user exit (MFJUXIT) which is invoked as
* call 'MFJUXIT' using JXIT
*
* Notes:
* 1. It should be included as follows (e.g.)
* 1 JXIT.
* COPY MFJDXIT REPLACING ==(tag)== BY ==JXIT==.
* 2. Fields beginning with JXIT-I- ( (tag)-I- ) are Input
* to the user exit and must not be modified
* e.g. JXIT-I-size
* 3. Fields beginning with JXIT-U- ( (tag)-U- ) are Input and
* Output. On entry to the user exit, they are set as
* appropriate and may be changed by the user exit to an
* acceptable value upon return.
* e.g. (tag)-U-PGM-alias
* 4. All data is ASCII(ANSI). Null values are those appropriate
* for the data type. i.e. blanks for character data,
* zeros for numeric and binary data
*
* --Date--- Who --What------------------------------------------
* 2002Mar04 DSA Initial version
*
*===============================================================
*===============================================================
* Header
*===============================================================
3 (tag)-I-header.
* Size of this block
5 (tag)-I-size pic s9(8) comp.
* Unless otherwise noted, all events occur for
* JCL, TSO, and TSO-in-batch (PGM=IKJEFTxx or IDAEFTxx)
* Event code of event. Ignore undefined event codes.
5 (tag)-I-event pic s9(8) comp.
* The following events occur for JCL and TSO-in-batch
* and represent execution of a JCL JOB stream
88 (tag)-I-event-job-ready value 1.
88 (tag)-I-event-job-flushed value 2.
88 (tag)-I-event-job-started value 3.
88 (tag)-I-event-job-JCL-error value 4.
88 (tag)-I-event-job-ended value 5.
* The following events occur for an interactive TSO
* session only
88 (tag)-I-event-TSO-started value 6.
88 (tag)-I-event-TSO-ended value 7.
* The following events occur for JCL and TSO-in-batch
* and represnt execution of "EXEC PGM=" JCL stmt
88 (tag)-I-event-step-ready value 8.
88 (tag)-I-event-step-started value 9.
88 (tag)-I-event-step-ended value 10.
88 (tag)-I-event-step-bypassed value 11.
* The following events occur for TSO and TSO-in-batch
* (IKJEFT01) and
* ... represent execution of the TSO "CALL pgm" command
88 (tag)-I-event-CALL-ready value 12.
88 (tag)-I-event-CALL-started value 13.
88 (tag)-I-event-CALL-ended value 14.
* ... represent execution of the DSN subcommand
* "RUN PROG(pgm)"
88 (tag)-I-event-RUN-ready value 15.
88 (tag)-I-event-RUN-started value 16.
88 (tag)-I-event-RUN-ended value 17.
* All of the above events occur in the parent process,
* The process in which the job/step preparation occurs.
*
* The following events occur for all environments
* for execution of a program following all
* "...-started" events.
* ***Note*** that these events occur in the child process
* that executes the program. Any working storage used by
* the user exit will not be the same as that for
* other events which occur in the parent process.
* In the parent process, your user exit will not remember
* information prior to "event-before-PGM-call" or after
* "event-after-PGM-call". Since both of these events
* occur in the shild process, the user exit will be
* able to remember information between these two events.
88 (tag)-I-event-before-PGM-call value 18.
88 (tag)-I-event-after-PGM-call value 19.
*===============================================================
* Action codes for all events. Upon return from the user exit,
* action code indicates next course of action to be taken.
* Upon entry to the user exit, it is set to zero.
*===============================================================
5 (tag)-U-action pic s9(8) comp.
* The JCL engine should continue as if the exit were
* never invoked. Any modified data will be ignored.
88 (tag)-U-action-continue value 0.
* The JCL engine should not call the exit any more in
* this process for this job/TSO session
88 (tag)-U-action-shut-exit value 1.
*===============================================================
* Action codes for: event-job-ready
*===============================================================
* The JCL engine should use all modified
* fields except pc-fname
88 (tag)-U-action-MVS-dsn value 2.
* The JCL engine should use all modified
* fields except MVS-dsn
88 (tag)-U-action-pc-fname value 3.
* The JCL engine should flush the job
88 (tag)-U-action-flush value 4.
*===============================================================
* Action codes for: event-step-ready
* event-CALL-ready
* event-RUN-ready
*===============================================================
* The JCL engine should use all modified fields
88 (tag)-U-action-PGM-info value 5.
* The JCL engine should abend this step/program.
* The step/program will be abended with
* S822 (Region not available)
88 (tag)-U-action-abend value 6.
*===============================================================
* Action codes for: event-job-ended
* event-TSO-ended
* event-step-ended
* event-CALL-ended
* event-RUN-ended
*===============================================================
* The JCL engine should use all modified fields
88 (tag)-U-action-term-info value 7.
*===============================================================
* Action codes for: event-job-started
* event-job-flushed
* event-job-JCL-error
* event-TSO-started
* event-step-bypassed
* event-step-started
* event-CALL-started
* event-RUN-started
* event-before-PGM-call
* event-after-PGM-call
* - No Action codes defined other than 0
*===============================================================
5 pic x(20).
*===============================================================
* Event related data - varies by event
*===============================================================
3 (tag)-I-data pic x(368).
*===============================================================
* Data for: event-job-ready
*===============================================================
3 redefines (tag)-I-data.
5 (tag)-I-data-job-ready.
* Job number
7 (tag)-I-jobnum-assigned pic 9(5).
* Fully qualified PC file name.
7 (tag)-U-pc-fname pic x(260).
* If available, MVS data set name (including member if
* a PDS) assoicated with pc-fname, otherwise blanks.
* e.g. MFIDSA.CNTL(MYJOB) (for a PDS member) or
* S0310.S070508.J01364.D00002.SYSUT2 (for PS)
7 (tag)-U-MVS-dsn pic x(54).
*
7 (tag)-I-submit-type pic x(1).
88 (tag)-I-submit-type-exec value 'E'.
88 (tag)-I-submit-type-scan value 'S'.
7 (tag)-I-animate pic x(1).
88 (tag)-I-animate-on value 'Y'.
88 (tag)-I-animate-off value 'N'.
*===============================================================
* Data for: event-job-flushed
* See event-job-ready.
* - Only the first field is relevant
*===============================================================
*===============================================================
* Data for: event-job-started
* event-job-JCL-error
* event-TSO-started
* event-step-bypassed
* - Field names containing "step" are irrelevant for non-step
* related events
*===============================================================
3 redefines (tag)-I-data.
5 (tag)-I-data-job-started.
7 pointer.
7 pointer.
7 pointer.
*
* Active System and Subsystems combinations are:
* System Subsystem
* ----------------
* JCL JCL
* JCL TSO (IKJEFTxx)
* JCL IMS (DFSRC000)
* TSO TSO
* TSO IMS (CALL DFSRC000)
* IMS IMS
* CICS CICS
*
* Active system
7 (tag)-I-system pic x.
88 (tag)-I-system-JCL value x'00'.
88 (tag)-I-system-TSO value x'01'.
88 (tag)-I-system-ims value x'02'.
88 (tag)-I-system-cics value x'03'.
88 (tag)-I-system-null value x'04'.
* Active subsystem
7 (tag)-I-subsystem pic x.
88 (tag)-I-subsystem-JCL value x'00'.
88 (tag)-I-subsystem-TSO value x'01'.
88 (tag)-I-subsystem-ims value x'02'.
88 (tag)-I-subsystem-cics value x'03'.
88 (tag)-I-subsystem-null value x'04'.
7 (tag)-I-jobname pic x(8).
7 (tag)-I-userid pic x(8).
7 (tag)-I-jobstep pic x(8).
7 (tag)-I-procstep pic x(8).
7 (tag)-I-jobnum pic 9(5).
7 (tag)-I-stepnum pic 9(3).
7 (tag)-I-procstepnum pic 9(3).
7 pic x(1).
7 pic x(1).
7 (tag)-I-msgclass pic x(1).
7 (tag)-I-msglevel1 pic x(1).
7 (tag)-I-msglevel2 pic x(1).
7 pic x.
7 pic x(1).
* Dates in YYYYMMDD format, times in HHMMSShh
7 (tag)-I-job-start-date pic 9(8).
7 (tag)-I-job-start-time pic 9(8).
7 (tag)-I-step-start-date pic 9(8).
7 (tag)-I-step-start-time pic 9(8).
*===============================================================
* Data for: event-job-ended
* event-TSO-ended
* event-step-ended
* event-CALL-ended
* event-RUN-ended
* event-after-PGM-call
* See event-job-started
* - plus the following data
*===============================================================
5 (tag)-U-data-job-ended.
7 (tag)-U-term-type pic x.
88 (tag)-U-term-type-normal value x'00'.
88 (tag)-U-term-type-user-abend value x'01'.
88 (tag)-U-term-type-sys-abend value x'02'.
88 (tag)-U-term-type-RTS-err value x'03'.
88 (tag)-U-term-type-RU-err value x'04'.
88 (tag)-U-term-type-unknown value x'05'.
7 pic x(3).
7 (tag)-U-term-return-code pic s9(8) comp.
7 (tag)-U-term-reason-code pic s9(8) comp.
*===============================================================
* Data for: event-step-ready
* event-step-started
* event-CALL-ready
* event-CALL-started
* event-RUN-ready
* event-RUN-started
* event-before-PGM-call
* See event-job-started
* - Plus the following data
* - Field names containing "step" are relevant
*===============================================================
5 (tag)-I-data-step-ready.
7 (tag)-I-PGM-name pic x(8).
7 (tag)-U-PGM-alias pic x(8).
7 (tag)-U-PGM-parm.
9 (tag)-U-PGM-parm-len pic s9(4) comp.
9 (tag)-U-PGM-parm-txt pic x(100).
*= End of MFJDXIT ==============================================
Copyright © 2008 Micro Focus (IP) Ltd. All rights reserved.