Scheduler Job Management Job Step Records
Article ID: 27952
Updated On:
Products
Issue/Introduction
Most z/OS batch programs end with a return code of zero to indicate that the program has successfully completed or end with some number greater than zero to indicate failure.
Some programs may issue multiple return codes in different steps and can be considered "good" endings and some that should be considered "bad." In cases like these, job step records should be used for Scheduler return code testing to determine if the job succeeded or failed.
Resolution
If all the programs in a batch job follow the standard convention where only RC 0000 is acceptable, then use the fail code and fail oper fields in the Scheduler job definition:
------ CA-SCHEDULER 11.0 (SCHD) CPU JOB BASE ----------
COMMAND ===>
Name . . . JOBNAME Number . . 01 Station . . 40 Schedule . . SCHDNAME
Failures:
Fail Oper . . . . GE
Fail Code . . . . 00001
Abend Option . . .
Fail Option . . .
Options:
Insert CA-11 . Interrupt . . . . . NO
Stage JCL . .
Memo . . . . .
Test Parm . .
Enter END to Exit, UP for Previous Screen, or DOWN for Next Screen.
In this example, if any step ends with any return code greater than or equal to one, then the job is considered to have failed.
-
To test multiple good and bad return codes, use the Scheduler JOB STEPS definition.
Using JOB STEPS definition requires that installation option STEPLVL be set to YES. Go to Scheduler online option 3.10 and look for the STEPLVL option:
STEPLVL = YES JOB STEP TRACKING SUPPORT
For these examples we are going to use the following JCL:
//JOBNAME JOB ?
//STEP1 EXEC PGM=PROGRAM1
//DD1 DD DISP=SHR,DSN=?
/*
//STEP2 EXEC PGM=PROGRAM2
//DD2 DD DISP=SHR,DSN=?
/*
//STEP3 EXEC PGM=PROGRAM3
//DD3 DD DISP=SHR,DSN=?
/*
STEP1 and STEP3 should end with a return code of zero. Any other return code should be considered a failure.
STEP2 may be considered successful if it ends with either a zero or a 12. Any other return code is a failure.
To define the job step records, edit the job in the database and choose option 3:
------ CA-SCHEDULER 11.0 (SCHD) JOB --------
OPTION ===> 3
Job . . . . . JOBNAME
Job Number. . 01
Station . . . 40
Schedule. . . SCHDNAME
1 DEFINITION - Job Definition
2 CRITERIA - Job Selection Criteria
3 JOB STEPS - Job Step Definitions
4 DRIVER - Parms for Driver Jobs
5 VRM - Virtual Resources
Enter END to Exit.
Scheduler displays the list of currently defined job step records for this job. Since nothing has been defined yet, the list is empty.
---- CA-SCHEDULER 11.0 (SCHD) JOB STEPS --------
COMMAND ===> SCROLL ===> PAGE
Name . . . JOBNAME Number . . 01 Station . . 40 Schedule . . SCHDNAME
Procstep Stepname Type Failoper Failcode More
-------- -------- ---- -------- -------- ----
*********************** Bottom of data *******************
To define a job step record, type an I (for insert) on the command line and press Enter. The job step definition panel is displayed.
-------------------- CA-SCHEDULER 11.0 (SCHD) JOB STEPS -------------------
COMMAND ===>
Name . . . JOBNAME Number . . 01 Station . . 40 Schedule . . SCHDNAME
Step Definition:
Procedure step name . . (Outside of the procedure)
Step name . . . . . . . (Step name with PGM=)
If true, step is . . . BAD (Good or Bad)
Fail operator . . . . . Return code . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
Enter END to exit, or press ENTER to save changes.
We'll start with STEP2. A return code of zero or 12 should be considered as good executions for this step, so the screen is filled in like this:
-------------------- CA-SCHEDULER 11.0 (SCHD) JOB STEPS -------------------
COMMAND ===>
Name . . . JOBNAME Number . . 01 Station . . 40 Schedule . . SCHDNAME
Step Definition:
Procedure step name . . (Outside of the procedure)
Step name . . . . . . . step2 (Step name with PGM=)
If true, step is . . . good (Good or Bad)
Fail operator . . . . . eq Return code . . . . . . 0
. . . . . eq . . . . . . 12
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
Enter END to exit, or press ENTER to save changes.
The step name of STEP2 is used to identify which step in the job we are describing. (Job steps that execute procedures are somewhat different. Please see the discussion at the end of this article.)
Job step records allow you to define either the return codes that are acceptable (good) for the step or the return codes that are unacceptable (bad). In this case, we know what return codes are acceptable, so we enter "good" to answer the "If true, step is" question.
Finally, we enter the tests that should be performed on the return code. If any one of these tests are true, then the step is considered to have completed successfully. (If we had entered "bad" in the previous field, the step would be considered to have failed if any of the tests were true.)
In our case, we know that a return code of zero or 12 is good, so we enter EQ 0 and EQ 12 in the fields.
Pressing enter defines the job step record and returns you to the job step record display.
-------------------- CA-SCHEDULER 11.0 (SCHD) JOB STEPS -- COMMAND ISSUED
COMMAND ===> SCROLL ===> PAGE
Name . . . JOBNAME Number . . 01 Station . . 40 Schedule . . SCHDNAME
Procstep Stepname Type Failoper Failcode More
-------- -------- ---- -------- -------- ----
STEP2 GOOD EQ 00000 Y
******************************* Bottom of data ********************
The display shows that a job step record for STEP2 exists to test for acceptable (good) return codes and shows the first condition code test. The Y in the More column indicates that more than one test exists for this step. If you want to see or change the condition code tests, you can select the job step record by typing an S to the left of the row and pressing Enter.
With the job step record for STEP2 defined, Scheduler will mark the job as failed if STEP2 gets any return code other than zero or 12. But what about the other steps in the job?
Scheduler ignores the fail code and fail oper fields on the job definition if one or more job step records are defined. In other words, with only the job step record for STEP2 defined, Scheduler will consider any and all return codes from the other steps as acceptable. STEP1 could end with a return code of 4000 and Scheduler would mark the job complete.
To have Scheduler validate the return codes for the other steps, you need one or more additional job step records. You may define a job step record for every step in the job, but that becomes a maintenance issue when the JCL is changed.
Instead, you may define a "default" job step record for all steps in the job that do not have their own job step records.
To create the default job step record for this job, type an I (for insert) on the command line and press Enter to display the job step definition screen.
-------------------- CA-SCHEDULER 11.0 (SCHD) JOB STEPS -------------------
COMMAND ===>
Name . . . JOBNAME Number . . 01 Station . . 40 Schedule . . SCHDNAME
Step Definition:
Procedure step name . . (Outside of the procedure)
Step name . . . . . . . (Step name with PGM=)
If true, step is . . . BAD (Good or Bad)
Fail operator . . . . . Return code . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
Enter END to exit, or press ENTER to save changes.
Enter a step name of * (asterisk), then define the condition code test that should be performed for all steps that do not have their own job step records. In this case, we've said that only zero is acceptable from the other steps:
-------------------- CA-SCHEDULER 11.0 (SCHD) JOB STEPS -------------------
COMMAND ===>
Name . . . JOBNAME Number . . 01 Station . . 40 Schedule . . SCHDNAME
Step Definition:
Procedure step name . . (Outside of the procedure)
Step name . . . . . . . * (Step name with PGM=)
If true, step is . . . good (Good or Bad)
Fail operator . . . . . eq Return code . . . . . . 0
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
Enter END to exit, or press ENTER to save changes.
Press Enter to return to the list of job step records:
-------------------- CA-SCHEDULER 11.0 (SCHD) JOB STEPS -- COMMAND ISSUED
COMMAND ===> SCROLL ===> PAGE
Name . . . JOBNAME Number . . 01 Station . . 40 Schedule . . SCHDNAME
Procstep Stepname Type Failoper Failcode More
-------- -------- ---- -------- -------- ----
* GOOD EQ 00000
STEP2 GOOD EQ 00000 Y
******************************* Bottom of data ************************
If our job had more than one step with non-standard return codes, we would define a job step for each of those steps. Scheduler does not have any limits on the number of job step records that may be defined for a job.
Example 1
Let's look at how Scheduler uses the job step records when the job executes. STEP1 ends with a return code of zero. Scheduler looks for a specific job step record for STEP1, doesn't find one, so uses the default job step record for the job. The default says the step is good if the return code equals zero, which it does, so the step is considered successful.
STEP2 ends with a return code of 12. Scheduler JM looks for a specific job step record for STEP2 and finds one. The job step record says the return code is good if it equals zero or if it equals 12. It does, so the step is considered successful.
STEP3 ends with a return code of zero, which is treated exactly the same as STEP1. Note that Scheduler would show the status of the job as "Completed RC=00012."
Example 2
Consider another run of the job, where STEP2 gets a return code of eight. The job step record says the return code is good if it equals zero or equals 12. Since it doesn't, the step is considered bad.
CA Scheduler JM does not prevent the rest of the job from executing. If STEP3 in our job should not execute when STEP2 gets a bad condition code, then the COND keyword should be used on the STEP3 EXEC statement.
Once the job has finished executing, Scheduler marks the job as failed with a status of "Step Failed RC=00008."
Example 3
STEP2 gets a return code of 12 (which Scheduler considers good) and STEP3 gets a return code of 08 (which Scheduler considers bad). Scheduler will mark the job as failed with a status of "Step Failed RC=00012." Scheduler always displays the highest return code received for the job, even though, in this case, the highest return code is not the one that caused the job to fail. JCL procedures add some complexity to job step records due to the confusion between "procedure step names" and "step names." Consider this JCL:
//JOBNAME2 JOB ?
//STEP1 EXEC PGM=PROGRAM1
//DD1 DD DISP=SHR,DSN=?
/*
//STEP2 EXEC MYPROC
/*
The JCL procedure MYPROC contains this JCL:
//MYPROC PROC
//STEPA EXEC PGM=PROGRAMA
//DDA DD DISP=SHR,DSN=?
//*
//STEPB EXEC PGM=PROGRAMB
//DDB DD DISP=SHR,DSN=?
//*
Suppose that PROGRAMA issues a return code of 100 for success and any other number (including zero) means it has failed.
The job step record for this step would look like this:
-------------------- CA-SCHEDULER 11.0 (SCHD) JOB STEPS -------------------
COMMAND ===>
Name . . . JOBNAME2 Number . . 01 Station . . 40 Schedule . . SCHDNAME
Step Definition:
Procedure step name . . step2 (Outside of the procedure)
Step name . . . . . . . stepa (Step name with PGM=)
If true, step is . . . good (Good or Bad)
Fail operator . . . . . eq Return code . . . . . . 100
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
Enter END to exit, or press ENTER to save changes.
The "procedure step name" is the name you see in the JCL executing the procedure (STEP2 in this case). The "step name" is the name on the EXEC statement actually executing a program (STEPA here). If you want to define a default job step record for this job, it might look like this:
-------------------- CA-SCHEDULER 11.0 (SCHD) JOB STEPS -------------------
COMMAND ===>
Name . . . JOBNAME2 Number . . 01 Station . . 40 Schedule . . SCHDNAME
Step Definition:
Procedure step name . . (Outside of the procedure)
Step name . . . . . . . * (Step name with PGM=)
If true, step is . . . good (Good or Bad)
Fail operator . . . . . eq Return code . . . . . . 0
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
Enter END to exit, or press ENTER to save changes.
Notice that the procedure step name is blank, even though this job uses a procedure. The default job step record is always defined with a blank procedure step name and an asterisk in the step name field. The asterisk should not be considered a wild card character - it is just the name of the default job step records.
Feedback
