CA Scheduler Job Management Job Step Records

Document ID : KB000027952
Last Modified Date : 14/02/2018
Show Technical Document Details

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, however, 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 instead for CA Scheduler JM return code testing to determine if the job succeeded or failed.

 

Instructions:

If all the programs in a batch job follow the standard convention where only RC 0000 is acceptable, then it is easy to use the fail code and fail oper fields in the job definition in CA Scheduler Job Management (CA Scheduler JM):

 

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

 

Having multiple good and bad return codes makes it impossible to define a single return code test for determining if the job succeeded or failed with the use of job step records.

Before you use job step records, you need to make sure that the installation option STEPLVL is set to YES. Go to CA Scheduler JM option 3.10 and look for the STEPLVL option:

STEPLVL = YES         JOB STEP TRACKING SUPPORT

If the value is not set to YES, then contact your site's CA Scheduler JM administrator.

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

CA Scheduler JM 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, which is the step with the most complex rules for its return code. As you recall, 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, CA Scheduler JM 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?

CA Scheduler JM 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, CA Scheduler JM will consider any and all return codes from the other steps as acceptable. STEP1 could end with a return code of 4000 and CA Scheduler JM would mark the job complete.

To have CA Scheduler JM 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. CA Scheduler JM 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 CA Scheduler JM uses the job step records when the job executes. STEP1 ends with a return code of zero. CA Scheduler JM 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. CA 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 CA Scheduler JM 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, CA Scheduler JM marks the job as failed with a status of "Step Failed RC=00008."

Example 3

STEP2 gets a return code of 12 (which CA Scheduler JM considers good) and STEP3 gets a return code of eight (which CA Scheduler JM considers bad). CA Scheduler JM will mark the job as failed with a status of "Step Failed RC=00012." CA Scheduler JM 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. Procedures 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.

Job step records can be used to let CA Scheduler JM correctly interpret non-standard return codes. By allowing CA Scheduler JM to validate the return codes instead of having your operations staff manually verify them you will speed up your production job streams and eliminate mistakes.

 

As always, please contact CA Technologies support for CA Scheduler Job Management if you have further questions.