External Job Monitor

You can use the External Job Monitoring (EJM) tool to identify Jobs that were not started by the Automation Engine (AE) system, but by a third-party scheduling system, or were manually submitted. You can react to these Jobs in the AE system by using the Event Monitor (EM) and the AE Agent. The external Job Monitor runs as a started task.

This page includes the following:

How does the External Job Monitor (EJM) work?

You can react to external events through the Event Monitor.

The Event Monitor identifies Console events, automatic FILE events, and the end of z/OS Jobs. However, you can also use it to react to external files that are generated. As soon as the External Job Monitor identifies an external Job that has ended, it creates a file to which the Event Monitor can react. The Event Monitor communicates with the AE system via the Agent and triggers an Event object.

As not all Jobs that end require action, you can use a filter file to determine the Jobs or steps that require a reaction. As soon as the EJM recognizes that a defined Job has ended, it creates a temporary file. This file is only required for the generation of an SMF record to which the Event Monitor can react. You can delete it afterward.

Important! Note that creating and deleting files causes entries in the dataset catalog. Make sure that you reorganize the catalog regularly.

To be able to identify external Jobs within a Sysplex, an External Job Monitor and an Event Monitor instance must run on each local partition (LPAR). Each LPAR has its own SMF subsystem which is not designed for a SYSPLEX environment. There is no direct connection between EJM and EM. The EJM signals to the EM that a Job has ended by generating a file. The EM sends the data to the z/OS Agent across LPARs.

SMF Exit for the External Job Monitor

Events and information concerning the External Job Monitor are written to the CADS via the AEEXJM SMF Exit module. This SMF Exit module is automatically loaded when the External Job Monitor module starts. The SMF Exit for the External Job Monitor is similar to the Event Monitor's SMF Exit with the exception that it only collects type 30 records. The SMF Exit continues to collect events even when the EJM has ended. A message is written to the log file if a Job that has been specified in the filter file finishes in the meantime.

Note: You can use the existing CADSDEL program as an emergency recovery for the EJM.

Important! Do not use the same names for filter files in several LPARs as problems may occur if Jobs of the same name end on different LPARs at the same time. In this case, the system attempts to generate files of the same name in parallel which eventually leads to an error. As this error hardly ever occurs, the utility only writes an error message to the log file and continues.

Filter File

You need an EJM filter file to select the Jobs that have ended and to which you need to react. The individual filter criteria are immediately checked whenever an event occurs.

Example: A filter file contains a condition that refers to a particular step or procedure step. The system immediately recognizes when this step ends and can react to it already before the Job has ended.

A filter file contains the following selection criteria:

Job name (partially/fully qualified)
Step name (partially/fully qualified)
ProcStep name (partially/fully qualified)
Job end
Return code

The filter file must include the DCB attributes RECFM (record format)=VB, LRECL (record length) =85 and BLKSIZE (block size) =5120. The filter file includes an 85-character line for each filter.

Use the following command to reload the filter file manually:

MODIFY <Nameof the started task>, RELOAD

You can define the following filter criteria:

Job name

Filters for the Job's name in z/OS
The wildcard characters * and ? can be used

Columns: 1-8 (Length 8

Step name (Optional)

Filters for the Job's step name in z/OS
The wildcard characters * and ? can be used

Columns: 9-16 (Length 8)

ProcStep name (Optional)

Filters for the Job's procedure step name in z/OS
The wildcard characters * and ? can be used

Columns: 17-24 (Length 8)

Job end
- " "
  A check is made as soon as the step or procedure step ends,
- X
  A check is made when the Job ends. The completion code is not evaluated.
- N
  A check is made when the Job ends and when it ends normally with a return code between 0 and 4095.
- A
  A check is made when the Job ends and when it ends abnormally with a return code between 4096 and 12287.
Column: 25 (Length 1)

Job return code (Optional)

Filters for the Job's return code such as Condition Code, User Abend, and System Abend. Several return codes must be separated with a semicolon (;) or a colon (,). You can define From-To areasby using a hyphen (-).

Columns: 26-41 (Length 16)

File name

The file name of the temporary file that will be generated for redirection.

Columns: 42-85 (Length 44)

The following example shows a filter file:

JOBTEST STEP3* 0-100;S0C4 JOB.ZUC800A1.EJM.TRIGGER.TEMP01
JOBF* STEP01 N0,4,8,12-16 JOBF.ZUC800A1.EJM.TRIGGER.TEMP02
JOBTEST2DUMMY 0-4096 JOB.ZUC800A1.EJM.TRIGGER.TEMP03
JOBTEST2DUMMY2 N0-4096 JOB.ZUC800A1.EJM.TRIGGER.TEMP04

The individual filter lines are connected through an OR relation. Therefore, the lines are processed and checked in sequences. If a selection applies, the particular file will be created.