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.
| 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 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.