HCL Workload Automation, Version 9.4

Tracking jobs

The agent uses the JES/SMF exits to track the status changes for all the jobs submitted through it.

Job states

The status events related to the jobs submitted via the agent for z/OS are generally issued by JES and SMF and intercepted by the agent for z/OS. The agent then forwards them to dynamic workload broker in an XML message. The job states are reported on the Dynamic Workload Console and on the conman command line.

The following table summarizes the states a job undergoes, from submission to completion, and maps the corresponding status names as they are reported by JES/SMF, the agent for z/OS, and on the user interfaces.

Table 1. Job events and statuses as mapped by the involved components
Event description Agent internal event Status name as passed by the agent for z/OS to dynamic workload broker in XML Status name as displayed by the Dynamic Workload Console and conman Other details
The agent has found an error in the JCL included in the job and stops processing it. IJ0 - FAIL This event is generated by the agent for z/OS when dynamic workload broker submits the job.
Job JCL. A job has been submitted.

The job has been submitted by dynamic workload broker and the JCL has been placed in the JES internal reader by the agent for z/OS. The job has not yet been submitted by JES, but the IDs assigned to the job by dynamic workload broker and by JES have been mapped together.

KJ1 INFO BOUND This event is generated by the agent for z/OS after copying the JCL in the JES internal reader.
Reader event: a job has entered the JES system. A1 or B1 SUBMITTED WAIT This event is generated by JES on the system hosting the agent for z/OS and sent to dynamic workload broker by the agent for z/OS.
Job-start event: a job has started to execute. A2 or B2 EXECUTING EXEC This event is generated by SMF on the system where the job is submitted and sent to dynamic workload broker by the agent for z/OS.
Step-end event: a job step has finished executing. A3S or B3S EXECUTING EXEC The event is generated on the system where the job is submitted but is discarded unless there is a step ABEND.
Job-end event: a job has finished executing. A3J or B3J SUCCEEDED EXECUTION or FAILED EXECUTION SUCC or ABEND This event is generated by SMF on the system where the job is submitted and sent to dynamic workload broker by the agent for z/OS.
Job-termination event: a job has been added to the JES output queues. A3P or B3P SUCCEEDED EXECUTION or FAILED EXECUTION SUCC or ABEND This event is generated by JES on the system where the job is submitted and sent to dynamic workload broker by the agent for z/OS.
Job Print end A4 or B4 - - Optional event that depends on the JCL content.

The event is recorded in the event data set (EELEVDS) but is not forwarded to dynamic workload broker.

Job is purged A5 or B5 - - Optional event that depends on the JCL content.

The event is recorded in the event data set (EELEVDS) but is not forwarded to dynamic workload broker.

JCL errors

The agent parses the JCL sent by dynamic workload broker before it submits it to JES. If it finds a syntax error in the JCL, it stops the submission process and records the error message in the job log.

Job error codes

Return codes other than zero after a job is submitted are to be considered errors. The return code is sent back to dynamic workload broker by the agent for z/OS via HTTP in an XML POST together with the job ID and name. The z/OS® error code is mapped to a numeric code which is displayed in conman or in the Dynamic Workload Console. The following table lists the error codes that can be returned after a job is submitted and their mapping on z/OS and on HCL Workload Automation.
Table 2. Error codes returned after a job is submitted.
Return code mapped on HCL Workload Automation Error description Displayed as job extended property on conman or the Dynamic Workload Console
1nnnn (nnnn is xxx converted to decimal digits) System abend error codes in hexadecimal notation. Sxxx
2nnnn (nnnn is xxx converted to decimal digits) User abend error codes in hexadecimal notation. Uxxx
30007 A JCL error occurred immediately; that is, the error was detected before the job began. This code is also possible when both the job-start event (type A2) and the job-end event (type A3J) are missing. JCLI
30020 A failure occurred when the agent attempted to submit a job. The operation should be marked as ended-in-error. OSUB
30021 A failure occurred when the agent attempted to retrieve the JCL for a job. OSUF
30026 The job was canceled by the operator or by a TSO user before execution. This code is also possible if the job-termination event (type A3P) is missing. CAN
30027 The completion code is unknown. The job has ended, but no completion code is available. This code is also possible if the job-end event (type A3J) is missing. CCUN
30029 A JCL error was recognized after the job began to execute, or a JCL error was recognized after syntax checking in the internal reader. JCL
90000 User-defined error codes in hexadecimal notation. xxxx

The event data sets

The agent uses the EELHTDS and EELEVDS event data sets which contain the records that describe the events created by its job tracking functions. An event-writer task writes and reads records to and from these data sets.

EELHTDS records the events originated by dynamic workload broker and related to the submission of workload.

EELEVDS records the events originated by JES and SMF that are related to job execution and that are to be sent back to dynamic workload broker .

Another data set named EELHTREF is used as a service data set to briefly store the jobs sent within the submission requests coming from HCL Workload Automation. If the jobs call for the retrieval of a JCL stored in the z/OS system, or require variable substitution, these actions are performed here.

Because the event data sets provide a record of each event, events will not be lost if the agent or an event processing component must be restarted. The submit checkpointing process ensures that submit requests are synchronized with dynamic workload broker, thereby preventing lost requests caused by communication failures.

Important: The data sets are formatted the first time they are used. If for some reason you format one of the data sets again, this results in the loss of all the events queued on all data sets.