Creating Step Conditions
Overview
A z/OS JES batch job consists of one or more steps defined by JCL EXEC statements. The JCL EXEC statement identifies the program that the step is to execute. During job execution, steps are executed sequentially under conditions defined by the JCL statements. When a step completes execution, a Step Condition code is recorded by JES. The Step Condition code is either an integer condition code, in the range of 0 - 4095, or an ABEND code. If a step does not execute, which can be for a number of reasons, it is referred to as FLUSH'ed.
A task's status of SUCCESS or FAILED is determined by task exit code processing. The z/OS Task Details Exit Code Processing field specifies the method used to determine the task status for a z/OS batch job. When the Step Conditions method is selected, the task status of the z/OS batch job is controlled by the Step Conditions defined in the z/OS Task and parent workflow.
In addition to determining the z/OS Task status, Step Conditions provide a means to control the execution of job steps without any changes to the batch job JCL. A Step Condition definition can specify that job execution is halted, continued, or determined by a console operator. For example, if a multi-step job has a step that ends with a condition code of 8, you could include a Step Condition check to decide whether or not to run the following steps.
Step Conditions can be applied at the z/OS Task level or at the workflow level that apply to all z/OS tasks in that workflow and sub-workflows.
Note
If Step Conditions has been selected for Exit Code Processing, and you then select a different option, a confirmation pop-up displays to warn that any defined Step Conditions will be removed.
Runtime Monitoring
You can monitor Step Conditions at run time via the Activity Monitor, which lets you add or change Step Conditions for a single task instance and then re-run that job.
Creating a Step Condition
Step 1 | From the Automation Center navigation pane, select Tasks > z/OS Tasks. The z/OS Tasks list displays. |
|---|---|
Step 2 | Select the task for which you want to create one or more Step Conditions. The z/OS Task Details for that task displays. |
Step 3 | In the Exit Code Processing field, select Step Conditions from the drop-down list and then click the Update button. |
Step 4 | Click the Step Conditions tab. The Step Conditions list displays a list of any currently defined Step Conditions for this task. |
Step 5 | Click New. The Step Condition Details pop-up dialog displays. |
Step 6 | Using the field descriptions, below, as a guide, complete the fields as needed. |
Step 7 | Click a Save button to save the record and return to the Step Conditions list. |
Step 8 | If appropriate, repeat these steps for any additional Step Conditions you want to add. |
Step Condition Details Field Descriptions
The table below describes the fields and buttons in the Step Conditions Details pop-up dialog.
Field Name | Description |
|---|---|
Step | Job step name to match. A blank value or an asterisk ( |
Procedure | Procedure step name to match. A blank value or an asterisk ( |
Program | Program name to match. A blank value or an asterisk ( |
Condition Codes | Conditions codes are integer return codes from the program or ABEND codes. Integer return codes are specified as a comma-separated list of integer values or ranges. Ranges are specified with a dash ( |
Action | Action to take and the task status to set if the Step Condition matches. See Step Condition Logic, below, for an explanation of the actions. |
Metadata | This section contains Metadata information about this record. |
UUID | Universally Unique Identifier of this record. |
Updated By | Name of the user that last updated this record. |
Updated | Date and time that this record was last updated. |
Created By | Name of the user that created this record. |
Created | Date and time that this record was created. |
Buttons | This section identifies the buttons displayed above and below the Step Condition Details that let you perform various actions. |
Save | Saves a new record in the Controller database. |
Save & New | Saves a new record in the Controller database and redisplays empty Details so that you can create another new record. |
Save & View | Saves a new record in the Controller database and continues to display that record. |
New | Displays empty (except for default values) Details for creating a new record. |
Update button |
Saves updates to the record. |
Refresh | Refreshes any dynamic data displayed in the Details. |
Delete button |
Deletes the current record. |
Close | For pop-up view only; closes the pop-up view of this task. |
Step Condition Logic
Step Condition exit code processing starts the task with a task status of SUCCESS. As the job executes and steps complete, the task status can change from SUCCESS to FAILED based on Step Condition definitions and job execution conditions. Once a task status has been changed to FAILED, it cannot be changed back to SUCCESS.
Note
The Controller searches Step Condition definitions based on their order in the Step Conditions list; the definition at the top of the list is searched first. To change the order of the definitions in the list, drag and drop them to any location.
In addition to Step Condition definitions changing the task status, the following specific job execution conditions will change the task status:
- JCL errors (for examaple, IEFC452I or IEF453I) change the task status to FAILED.
- A job step ABEND that does not match any Step Condition definition changes the task status to FAILED.
As job steps complete execution, Universal Controller searches the list of task-level Step Condition definitions that matches the current step based on the job step name, procedure step name, program name, and the Step Condition code. The search stops when the first definition is found. If a matching Step Condition is found, the Step Condition action is taken. If no matching task-level Step Condition is found, the search continues with the parent workflow-level Step Conditions. If no matching workflow-level Step Condition is found, the search continues with its parent workflow-level Step Conditions and so on until a match is found or all Step Conditions have been search in the hierarchy. If no matching Step Condition is found, the Controller takes no action and normal JES processing of the job continues.
Note
If a step does not execute, no search is performed for that step in the Step Condition definitions. For example, if a job step FLUSH'es due to a JCL IF statement, the Step Conditions will not be search for the step.
The Step Condition definition action value specifies two attributes, the action to take and the task status. These two attributes are combined into combinations that form the possible action values. The following Step Condition actions are supported:
Continue/Success | Job execution continues and task status is set to SUCCESS. |
|---|---|
Continue/Failed | Job execution continues and task status is set to FAILED. |
Halt/Failed | Job execution is halted at the current step and task status is set to FAILED. |
Askoper | Job execution is stopped and the Controller sends a WTOR message to the console operator requesting a reply on how job execution should proceed. The action is dependent upon the operator reply (see Example 4, below). |
During job processing, the Controller issues message UAG1059A to the job log when it matches a Step Condition definition to a step that has completed execution. Message UAG1059A includes the Step Condition definition values including the action that is taken. The message provides an audit record of Step Condition processing that has influenced job execution.
Example Steps and Condition Codes
This section provides a sample job and PROC, followed by example condition code checks for that job.
Example Job and Procedure
Example Job
Example Procedure (Cataloged Procedure)
User Interface Specifications and Actions
The following examples specify condition code checks for the example job above.
Example 1
In this example, if the condition code of any step of the job is greater than 12, the job halts and the task status is set to FAILED.
Example 2
In this example, if the condition code of any procedure step executed as job step S1 is equal to 8, the job continues and the task status is set to SUCCESS.
Example 3
In this example, if the condition code of program IEBGENER is 0 or 12, the job continues and the task status is set to SUCCESS.
Example 4
In this example, if the condition code from job step S1, procedure step STEP2 is user ABEND U0010, the operator is alerted with a WTOR console message that specifies the job name, the job step, the procedure step, and the actual condition code. The Controller will take the action specified by the operator reply.
Issued WTOR
The UAG1058A WTOR message identifies the job name as JOBA, step name as S1, procedure step name as STEP2, and the Step Condition code as U0010 that matched the Step Condition definition which resulted in the ASKOPER action.
Operator Reply
The operator must reply with one of the following:
- (1) CONTINUE/SUCCESS
- (2) CONTINUE/FAILED
- (3) HALT/FAILED
(See Step Condition Logic for an explanation of these replies.)
Example 5
In this example, if the condition code from job step S1, procedure step STEP3 is within the range of 0-7, the job continues and the task status is set to SUCCESS.
Example 6
In this example, if the condition code from job step S1, procedure step STEP1 is greater than 0, the job continues and the task status is set to FAILED.