JCL: Controlling the Job Process: Text-only Version

JCL: Controlling the Job Process


Unit 1. Conditional Job Processing



In this course, you will learn how to control job processing.
In this unit, you will learn the ways to control the processing of a job by using the conditional (IF) construct.
You will learn how to use the IF/THEN, ELSE, and ENDIF statements and relational-expressions within the IF/THEN statement.

After completing this unit, you should be able to:


Topic 1.1: IF Construct

*What Is a Construct?
The three statements — IF/THEN, ELSE, and ENDIF — are collectively called a construct. You use these simple elements together to assemble the logic that conditionally executes job steps.
For ease of reference, we will use the term IF construct to refer to the IF/THEN, ELSE, and ENDIF statements.

IF Is Easy
The IF construct is easier to use than the COND parameter to control a job's processing. You can see more about the COND parameter later in this course, but these are the basic differences:


IF Is Powerful
The IF construct is a more powerful feature than the COND parameter.
For example,


*Test the IF Construct
The relational-expressions you can test with the IF construct include






Topic 1.2: IF and JCL Syntax

  //<name> IF <(>relational-expression<)>  THEN <comments>
  :
  :
  //<name> ELSE   <comments>
  :
  :
  //<name> ENDIF  <comments>
*Format the IF
Above is the format of the IF construct. The operation field specifies the part of the construct you're coding.
IF specifies the relational-expression evaluated by the system.
THEN defines the job steps executed when the relational-expression is true.
A THEN clause consists of all statements between the THEN and its matching ELSE (or ENDIF). If no statements are specified, it is called a null THEN.

  //<name> IF <(>relational-expression<)>  THEN <comments>
  :
  :
  //<name> ELSE   <comments>
  :
  :
  //<name> ENDIF  <comments>
ELSE and ENDIF








*Code the JCL IF
Coding the JCL IF construct follows the same patterns as IF/THEN/ELSE/ENDIF constructs found in other languages.
This course assumes that you understand this basic logic processing. You'll concentrate on the coding rules specific to JCL.
Here's one. You can code the IF construct anywhere in the job after the JOB statement.
Let's look at some simple examples and then examine the coding rules in detail. Note that these examples evaluate return code values. Programs assign a return code to signify a certain condition. Return codes can be 0 to 4095.

  //EXAMPLE  JOB
  //S1     EXEC PROC1
    
  //S2OK   EXEC PROC2
    
  //S2BAD  EXEC PROC3
  
*Execute a Procedure
This jobstream executes a procedure as the first step.
If the return code from that step is zero (meaning everything went okay), then PROC2 is executed.
The ELSE statement tells the system to execute PROC3 when the IF condition is not met. In this case, the IF condition is not met when the return code from S1 is not equal to 0.
The ENDIF statement ends the IF construct.

  //EXAMPLE  JOB
  //S1     EXEC PROC1
  //COND01 IF RC = 0 THEN
  //S2OK   EXEC PROC2

ELSE Is Not Required
The jobstream above is similar to the preceding one. Notice here that no other job steps execute if the S1 return code is not equal to 0.
The ELSE statement is coded for clarity but not required.





  //<name> IF <(>relational-expression<)>  THEN <comments>
    :
    :
  //<name> ELSE   <comments>
    :
    :
  //<name> ENDIF  <comments>
*General IF Format
Above is the general format of the IF construct again.
Now look at each piece of the construct and how you code it.

   IF <(>relational-expression<)>  THEN <comments>
    :
    :
   ELSE   <comments>
    :
    :
   ENDIF  <comments>
*Name It
The name field is optional on all of the above statements. If you specify it, it must be unique within the job and conform to the standard rules for DD names:


 
  //<name> <(>relational-expression<)>   <comments>
    :
    :
  //<name>    <comments>
    :
    :
  //<name>   <comments>
IF and ENDIF Are Required
The operation field can contain IF, ELSE, THEN, or ENDIF.
IF and ENDIF are required.

*Preface With COND
Some simple coding conventions can make these constructs easier to follow.
One suggestion is to name each construct with the preface COND.
For example:   IF RC = 0 THEN
Then, include this name in the comment field of the ELSE and ENDIF statements to aid readability.
For example: //COND01  IF RC = 0 THEN //   : //       ELSE    //   : //       ENDIF

 //COND01  IF  RC = 0   THEN
 //TRUE01   EXEC   PROC1
 //        ELSE   COND01
 //FALSE01  EXEC  PROC2
 //END01   ENDIF  COND01
*One Caution!
The system does not use the comment field of the ENDIF to match the IF statement name. It matches the ENDIF to the prior IF statement.
You'll see the importance of this as you begin to nest IF statements.

Topic 1.3: Unit 1 Summary

In this unit, you learned the IF construct can refer to the IF/THEN, ELSE, and ENDIF statements, and that the IF construct specifies the conditions for when you do want to execute job steps.
You learned the operation field specifies the part of the construct you're coding as shown in the following:
You also learned that the IF construct can be coded anywhere in the job after the JOB statement, the name field is optional on all statements in the IF construct, and if you specify the name field, it must be unique within the job and conform to the standard rules for DD names. You also learned the operation field can contain IF, ELSE, THEN, or ENDIF, but that IF and ENDIF are required.
And finally, you learned to name each construct with the preface COND, and that including construct names in the comment field of the ELSE and ENDIF statements aids readability.

Unit 2. Relational-Expressions



In this unit, you will learn how to code relational-expressions within an IF/THEN statement.

After completing this unit, you should be able to:


Topic 2.1: Operators

*The Relational-Expression
//<name> IF <><>  THEN <comments>
The relational-expression is the condition that is evaluated as either true or false. You can enclose the expression in parentheses or omit the parentheses on simple expressions. Here is what you can include in the expression.
Examine the following table
Comparison operators Logical operators
EQ or =  Equal to AND or & AND
NE or ¬= Not equal to OR or | OR
GT or > Greater than   
LT or < Less than   
GE or >= Greater than or equal to NOT operator:
LE or <= Less than or equal to NOT or ¬ NOT
NG or ¬> Not greater than   
NL or ¬< Not less than   


*Don't Mix Operators
//<name> IF <><>  THEN <comments>
Note that you can code either a mnemonic (EQ) or a symbol (=) for the operator. Although mixing the operator symbols can be done, it is not recommended. The relational-expression is much easier to read if you code all statements in the same format.
Here are some basic coding considerations.
Now look at several examples.

    //TESTRC  IF RC < 12  THEN
  
    //TESTRC  IF NOT RC < 12  THEN
NOT Reverses the Condition
The first IF/THEN statement above tests the simple condition RC < 12. In this case, the THEN clause executes if the return code is any of these: 0,1,2,3,4,5,6,7,8,9,10,11.
In the second example, NOT negates or reverses the condition. Therefore, return codes like 12,13,14,15, etc. cause the THEN clause to execute.

     //TESTRC  IF RC GE 12  THEN
  
     //TESTRC  IF (RC > 12 | RC = 12)  THEN
  
     //TESTRC  IF ¬ (RC > 12 | RC = 12)  THEN
*Test the Same Condition
The first two examples above show two ways to test the same condition. The first uses a comparison operator; the second uses a logical operator. For both, however, the THEN clause executes for return codes of 12 or greater.
The third example uses NOT again to reverse the condition. Here, return codes of 0,1,2,3,4,5,6,7,8,9,10,11 cause the THEN clause to execute.

      //TESTRC  IF (RC > 4 & RC < 12)  THEN
  
      //TESTRC  IF NOT(RC > 4 & RC < 12)
  
      //TESTRC  IF NOT(RC > 4) & RC < 12  THEN
*Parentheses
Now notice how parentheses can affect the outcome. The first example above tests a condition using the AND logical operator. In this case, the THEN clause executes for return codes greater than 4 and less than 12 — 5,6,7,8,9,10,11.
The second example negates the entire condition by using NOT. Now, the THEN clause executes for return codes 0,1,2,3,4 and 12,13,14,15, etc.
In the third example, NOT negates only the first clause of the condition. Thus, return codes 0,1,2,3,4 cause the THEN clause to execute.





Topic 2.2: Keywords

*A Keyword List
So far you have see only the RC relational-expression keyword. Here is a complete list of the keywords that you can code in the relational-expression.
Examine the following table
Keyword Purpose
RC examines a return code
ABEND tests for an abnormal end of a program
¬ABEND tests that an abnormal end of a program did not occur
ABENDCC examines an ABEND condition code
RUN tests if a job step executed
¬RUN tests if a job step did not execute

All the keywords can include a stepname and procstepname to refine the test to a specific job step. The format is stepname.procstepname.keyword.
Let's look now at how to code each one.

RC...
examines a return code.
This keyword tests a return code with a comparison operator. The return code can be in the range 0-4095. The examples presented thus far in the course used the RC keyword. Here are two more:
IF  RC = 0   THEN
IF  STEP1.RC < 12  THEN
If you omit the stepname, then the highest return code from all job steps is tested.

ABENDCC...
examines an ABEND condition code.
You can also test an ABEND condition code in a similar fashion with the ABENDCC keyword.
To test a system completion code, use the Sxxx format. The xxx in this format is a hexadecimal value set by the system. For example: IF ABENDCC = S0C7 THEN
To test a user completion code use the Uxxxx format. The xxxx in this format is a four-digit value set by a program. For example: IF STEP7.ABENDCC = U1200 THEN
If you omit the stepname, the most recent ABEND code that occurred is evaluated.

ABEND and ¬ABEND
ABEND tests for an abnormal end of a program.
¬ABEND tests that an abnormal end of a program did not occur.
Use these keywords to test whether an ABEND occurred or not.
Either of these formats test for an ABEND.
IF  ABEND  THEN
IF  STEP4.PROCAS01.ABEND = TRUE  THEN
These formats test that an ABEND did not occur.
IF ¬ABEND  THEN
IF  TEST01.ABEND = FALSE  THEN
If you omit the stepname, all prior steps are included in the evaluation.

RUN and ¬RUN
RUN tests if a job step executed.
¬RUN tests if a job step did not execute.
You code the RUN keyword similarly to ABEND, however, RUN tests that a specific step ran.
For example,






  //EXAMPLE  JOB
  //S1     EXEC PROC1
    
  //S2OK   EXEC PROC2
  //NOTOK  ELSE
  //S2BAD  EXEC PROC3
  //       ENDIF COND01
*More About IF
Let's finish up the discussion on the IF construct by covering several miscellaneous items. If a step within a job ABENDs, the IF construct will not execute unless it tests for an ABEND condition or a specific ABEND code.
For example, if any step in the procedure PROC1 above ABENDs, none of the following statements execute.

  //EXAMPLE  JOB
  //S1     EXEC PROC1
  
  //S2OK   EXEC PROC2
  //NOTOK  ELSE
  //S2BAD  EXEC PROC3
  //       ENDIF COND01
*Test for ABEND
However, if you test for an ABEND as in the COND01 construct in this example, then the system will process it.



Topic 2.3: Special IF Considerations

*Use THEN/ELSE with IF
Here are a few considerations when coding the THEN and ELSE clauses in an IF construct.


  //EXAMPLE  JOB
  //S1       EXEC PROC3
  
  //BOTHOK    EXEC    PROC4,PARM=(11)
  //          ELSE    COND02
  //OK01      EXEC    PROC4,PARM=(10)
  //          ENDIF   COND02
  //       ELSE    COND01
  //ERR    EXEC    PROC4,PARM=(ERR)
  //       ENDIF   COND01
*Nesting IF Constructs
You can nest another IF construct after the THEN clause or the ELSE clause.
This jobstream uses a nested IF construct to test the results of the procedure (PROC3) that executes.

  //EXAMPLE  JOB
  //S1       EXEC PROC3
  
  //COND02    IF  (S1.PROC3S2.RC = 0) THEN
  //BOTHOK    EXEC    PROC4,PARM=(11)
  //          ELSE    COND02
  //OK01      EXEC    PROC4,PARM=(10)
  //          ENDIF   COND02
  //       ELSE    COND01
  //ERR    EXEC    PROC4,PARM=(ERR)
  //       ENDIF   COND01
*Less Than 8
//COND01 IF      (RC < 8) THEN
tests that all prior return codes are less than 8. In this case, it tests all the steps in PROC3.
If the result is true, the next statement is processed — that is, the next IF construct.

  //EXAMPLE  JOB
  //S1       EXEC PROC3
  //COND01 IF  (RC < 8) THEN
  
  //BOTHOK    EXEC    PROC4,PARM=(11)
  //          ELSE    COND02
  //OK01      EXEC    PROC4,PARM=(10)
  //          ENDIF   COND02
  //       ELSE    COND01
  //ERR    EXEC    PROC4,PARM=(ERR)
  //       ENDIF   COND01
PROC3 Is 0
//COND02  IF      (S1.PROC3S2.RC = 0) THEN tests that the return code in step PROC3S2 of PROC3 is 0. If this is true, the next statement — the EXEC — is processed.
//BOTHOK  EXEC    PROC4,PARM=(11) executes PROC4 and passes 11 as a parameter to indicate that step PROC3S2 of PROC3 (called by jobstep S1) was 0 and all return codes in PROC3 were less than 8.

  //EXAMPLE  JOB
  //S1       EXEC PROC3
  //COND01 IF  (RC < 8) THEN
  //COND02    IF  (S1.PROC3S2.RC = 0) THEN
  //BOTHOK    EXEC    PROC4,PARM=(11)
  //       ELSE    COND01
  //ERR    EXEC    PROC4,PARM=(ERR)
  //       ENDIF   COND01
PROC4 Is 10
If the return code of S1.PROC3S2 is not 0, the ELSE clause executes PROC4 with a parameter of 10. This indicates that all return codes for PROC3 were less than 8, but the return code for S1.PROC3S2 was not = 0.
//        ENDIF   COND02
ends the COND02 IF construct.

  //EXAMPLE  JOB
  //S1       EXEC PROC3
  //COND01 IF  (RC < 8) THEN
  //COND02    IF  (S1.PROC3S2.RC = 0) THEN
  //BOTHOK    EXEC    PROC4,PARM=(11)
  //          ELSE    COND02
  //OK01      EXEC    PROC4,PARM=(10)
  //          ENDIF   COND02

IF Is False
When the result of the COND01 IF clause is false, the ELSE clause is processed. This clause executes PROC4 with a parameter of ERR to indicate that all return codes in PROC3 were not less than 8.
And the COND01 IF construct ends with the statement
//       ENDIF   COND01



  //EXAMPLE  JOB
  //         EXEC PROC3
  //OK01    EXEC   PROC4,PARM=(0)
  //        ELSE   COND01
  //OK02       EXEC    PROC4,PARM=(8)
  //           ELSE    COND02
  //ERR        EXEC    PROC4,PARM=(ERR)
  //           ENDIF   COND02
  //        ENDIF   COND01
*Nested IF Constructs
This jobstream uses a nested IF construct in the ELSE clause. If all the return codes from PROC3 are 0, PROC4 executes with a parameter of 0.
The ELSE clause starts another IF construct (COND02). If all the return codes are less than 8, PROC4 executes with a parameter of 8. Otherwise, it executes with a parameter of ERR.
Then both IF constructs end.







*Keep It Simple
The IF construct can be nested to form rather complex tests. Bear in mind that these are logic statements. Be careful to keep the logic simple. Otherwise, you defeat the purpose of the IF construct by making it even more complex to follow than its predecessor the COND parameter.
Here are some simple guidelines to follow.


Note: If an IF construct is coded with a COND parameter, both must be satisfied for a step to execute.


Topic 2.4: Unit 2 Summary

In this unit, you learned the relational-expression is the condition that is evaluated as either true or false, and that you can enclose the expression in parentheses or omit them on simple expressions. You learned that in the expression, you can include comparison operators, logical operators, and the NOT operator.
You also learned all keywords can include a stepname and procstepname to refine the test to a specific job step, and if a step within a job ABENDs, the IF construct will not execute unless it tests for an ABEND condition or a specific ABEND code.
And finally, you learned to nest another IF construct after the THEN clause or the ELSE clause.

Unit 3. COND Parameter



In this unit, you will learn ways to control the processing of a job by using the COND parameter. You'll learn how to use the COND parameter to conditionally execute a JOB or its steps.

After completing this unit, you should be able to:


*What Is COND?
The COND parameter is
Let's look at how the COND parameter is coded and evaluated.

*Test the Return Code
The COND parameter on the JOB statement is used to test the return code set during the processing of each JOB step.
The return code is a number from 0 to 4095, which reflects the results of a JOB step.

*Standard Return Codes
Some return codes are standard for certain programs.
For example,
Most programming languages permit you to set the return code from your program. You can then establish codes to signify different processing situations, for example: 0 - OK, 4 - recoverable errors, 8 - unrecoverable errors.

*The JOB Ends
The return code is checked when each JOB step completes.
If a return code set by the step meets the criteria set in the COND parameter, the JOB stops processing at this point. The rest of the steps are bypassed and the JOB ends.



Topic 3.1: COND Code

*Code the COND
You'll see a few examples of the COND parameter in a moment, but first let's see how the parameter is coded. The format of the COND parameter on the JOB statement is COND=((code,operator)...) where...
Examine the following table
code This number is compared to the return code.
It is an integer from 0-4095.
operator The comparison made to the return code is
EQ - equal to
NE - not equal to
LT - less than
LE - less than or equal to
GT - greater than
GE - greater than or equal to

Note that mathematical symbols like = are not allowed in the COND parameter.

*The Coding Rules
The first two rules to consider when coding the COND parameter are
1. The outer parentheses are necessary only if more than one test is coded.
COND=(0,NE)  is valid COND=((8,GE),(12,LT)) is valid COND=(8,GE),(12,LT) is invalid
2. Up to 8 tests may be coded in the parameter. (That's left up to you. It's hard enough to code two tests!)
If any of the tests are true, the JOB stops processing.





RC Equals 0
What if you want the JOB to process only if the return code for each JOB step is 0?
The best way to state the sentence is: "Do not continue to execute this JOB (terminate) if 0 does not equal the return code."
The JOB statement to do this is //TEST   JOB   COND=(0,NE).

RC Does Not Equal 0
//TEST   JOB   COND=(0,NE)
The JOB with this JOB statement will stop processing if any return code (rc) is not equal to zero. The chart below helps map this out.
Examine the following table
STEP RETURN CODE TEST 0 NE rc RESULT
1 0 no continue
2 4 yes end

All subsequent steps are bypassed.





RC Is Greater Than 8
The JOB terminates if 8 is greater than the return code (0 to 7). So it executes when 8 is less than or equal to the return code (8 and above).
Examine the following table
RETURN TEST
8 GT rc
RESULT
0 yes end
4 yes end
8 no continue
12 no continue


Topic 3.2: Multiple COND Tests

RC 4 through 8
Now, let's consider multiple conditional tests. In these cases, if any test is true, the JOB stops processing.
This COND parameter will allow the JOB to continue processing if the return codes set are 4 through 8, as in
//TEST   JOB   COND=((3,GE),(8,LT).
Examine the following table
STEP RETURN CODE TEST 1 3 >= rc TEST 2 8 < rc RESULT
1 4 no no continue
2 8 no no continue
3 0 yes no end

All subsequent steps are bypassed.

*What Do You Want?
Many people have trouble coding the COND parameter.
The following screens show a way to analyze it that may be helpful. First, chart what is desired.
Examine the following table
For these rc's... 0 - 3 4 - 8 9 - 4095
The JOB... terminates executes terminates


*Then Code It!
Next, think of it logically.
Examine the following table
Terminate the
JOB if...		 3 >= rc
4 > rc		 — or —
— or —		 9 <= rc or
8 < rc

Then, consider how to code it. .
Examine the following table
Code... 3,GE
4,GT		 — or —
— or —		 9,LE
8,LT


*Return on the Right!
Most folks want to consider the return code a variable coded on the left in the test. It seems natural since most programming languages are constructed this way.
However, the COND parameter is coded just the opposite! The return code variable information goes on the right.
Thus, if you want a JOB to
use any of the following: COND=((3,GE),(9,LE)) COND=((3,GE),(8,LT)) COND=((4,GT),(9,LE)) COND=((4,GT),(8,LT))





*Stop Conditions
As soon as a return code meets any one of the conditions, the JOB stops processing.
If the return code is     2 ——> 2 NE 2 (no, cont), 4 NE 2 (yes, stop)
            4 ——> 2 NE 4 (yes, stop) ...
It also stops for any other value, such as: 0 ——> 2 NE 0 (yes, stop)
Thus, this job NEVER continues!





*Rule 1
The COND parameter can also be coded on the EXEC statement.
This brings up two last rules to consider:
1. If the COND parameter is coded only on the EXEC statement, i.e. there is no COND parameter on the JOB statement the COND parameter is compared to the return code of previous steps. If the return code meets the criteria set in the COND parameter, the step is bypassed. However, the JOB continues to execute.

*Rule 2
2. If the COND parameter is coded on both the EXEC statement and the JOB statement the COND parameter on the JOB statement is evaluated prior to those coded on the EXEC statements. If a step return code satisfies the criteria coded on the JOB statement, the JOB is terminated. The EXEC COND parameter settings are not evaluated.



  //UPDTE   JOB
  //STEP1   EXEC  EDIT
  //STEP2   EXEC  UPDATE,COND=(4,LE)
  //STEP3   EXEC  REPORT
    
  

*An EXEC Example
In this example a COND parameter is coded only on the EXEC statement.

  //UPDTE   JOB                        //UPDTE   JOB  COND=(4,LE)
  //STEP1   EXEC  EDIT                 //STEP1   EXEC EDIT
  //STEP2   EXEC  UPDATE,COND=(4,LE)   //STEP2   EXEC UPDATE, COND=(4,LE)
  //STEP3   EXEC  REPORT               //STEP3   EXEC REPORT
    
                        
  STEP2 - bypassed                     
  STEP3 - executed                             (STEP2 and STEP3 are not executed)
*A JOB Example
Notice the change when the COND parameter is coded on the JOB statement.





*Use the Step Name
The return codes of any of the prior steps can be tested by using the step name.
Like this:
//STEP5  EXEC REPORT,COND=(4,LT,STEP1)
says bypass this step if 4 < the return code set in STEP1 or only execute this step if the return code of STEP1 is < or = 4.
If you don't code the step name, all previous return codes will be tested. If any satisfy the test, the step is bypassed.









ABENDing
The other additional test that can be made is for prior steps ending abnormally — ABENDing.
This is done with a test for EVEN or ONLY.

Note: Usually a COND tells when to bypass the step. However, EVEN and ONLY tell when to execute the step.
When using EVEN or ONLY, you're limited to coding up to 7 tests in the COND parameter (rather than the usual 8).


Topic 3.3: EVEN/ONLY and COND

EXEC Scans for EVEN or ONLY
The EVEN/ONLY CONDition executes the step as follows:
Ordinarily an abnormal end terminates a JOB. But the system scans the remaining EXEC statements looking for EVEN or ONLY.
If a step containing EVEN or ONLY is found it executes if none of the condition code tests are satisfied. See the next screen for an example.

  //STEP1  EXEC PGM=COPY
  //STEP2  EXEC PGM=MERGE
  //STEP3  EXEC PGM=READ,COND=((4,EQ),EVEN)
  //STEP4  EXEC PGM=WRITE,COND=(8,GT,STEP1)
*Another Example
Here's a previous example, slightly modified.
Now STEP3 executes when the completion codes of STEP1 and STEP2 are not 4 — even if STEP1 or STEP2 ABENDs.
Note that EVEN and ONLY can be coded
Also note that outer parentheses are needed (as shown above) when more than one test is coded.





COND Relates
Now, let's see how the COND code on the JOB and EXEC statements relate.
The JOB statement overrides the EXEC statement. This means that if a CONDition is satisfied for the JOB statement, the entire JOB will stop processing.
The EXEC statement doesn't get a chance!





Topic 3.4: Unit 3 Summary

In this unit, you learned that the COND parameter on the JOB statement is used to test the return code set during the processing of each JOB step, and the return code is a number from 0 to 4095, which reflects the results of a JOB step. You also learned the JOB stops processing if a return code set by the step meets the criteria set in the COND parameter.
You learned two rules to consider when coding the COND parameter; that is, the outer parentheses are necessary only if more than one test is coded, and up to 8 tests may be coded in the parameter. You also learned that when using multiple conditional tests, if any test is true, the JOB stops processing.
You learned the COND parameter can also be coded on the EXEC statement, and the return codes of any prior steps can be tested by using the stepname8. You also learned the other additional test that can be made for prior steps ending abnormally is ABENDing and is done with a test for EVEN or ONLY.
And finally, you learned the JOB statement overrides the EXEC statement, meaning that if a CONDition is satisfied for the JOB statement, the entire JOB will stop processing.

Unit 4. Additional Job Control Information



In this unit, you will learn about some additional pieces of information that control the processing and execution of a job.
You will learn how to control processing by limiting processing time and canceling jobs that exceed specified output limits.
You will also learn to control job execution via restart options, scheduling options, and remote job submission and to use some common job communication options.

After completing this unit, you should be able to:


Topic 4.1: Controlling Time

*Limit TIME
Let's look first at how to control job execution by limiting processing time.
Examine the following table
To control by JOB Statement EXEC Statement JES2 Statements
timing execution TIME parameter TIME parameter TIME on /*JOBPARM


*Format TIME
As you saw in a previous course, the TIME parameter on JOB and EXEC statements specifies the maximum processing time for a job or job step.
The format of the TIME parameter is
TIME=(<minutes><,seconds>)
minutes = 1-357912 seconds = 1-59.
For example, TIME=10       (ten minutes) TIME=(,30)    (thirty seconds).

You should refer to the standards and guidelines at your installation that deal with specifying CPU time. Many installations restrict the use of the TIME parameter.
If the job exceeds the CPU time limit, it is generally terminated.





*Use TIME on the JOB and EXEC Statements
The TIME parameter on JOB and EXEC statements works with processing time.
Within JES2, the /*JOBPARM statement also has a TIME parameter. However, the /*JOBPARM TIME parameter measures elapsed clock time, not CPU time.
When clock time exceeds a specified /*JOBPARM TIME value, a message is sent to the operator.
For example, /*JOBPARM TIME=2
sends a message to the operator when the job's elapsed clock time exceeds two minutes.

*Use Your Installation Guidelines
Job processing is not affected by use of this parameter; that is, the job is not canceled when the TIME value is exceeded.
Most programmers have limited need for this parameter, and use their installation's default.
You should refer to the standards and guidelines at your installation for more information on this parameter.



Topic 4.2: Controlling Output Limits

*Canceling Jobs
Now we'll look at the parameters used to cancel jobs that exceed certain byte, card, line, or page limits.
Examine the following table
To control processing by JOB Statement JES3 Statements
canceling jobs that exceed output limits CANCEL subparameter of BYTES, CARDS, LINES and PAGES parameters CANCEL subparameter on //*MAIN
canceling jobs and issuing dumps when output limit exceeded DUMP subparameter of BYTES, CARDS, LINES and PAGES parameters DUMP subparameter of //*MAIN


*The Output Limits
One way to control job processing is to specify cancellation of a job when the output exceeds a given limit.
This technique is particularly useful in testing, or when you suspect a problem in your program.
As you saw in the first course, there are four parameters on the JOB statement used to specify output limits.
Use these parameters on the JOB statement to limit the number of BYTES to be spooled, CARDS to be punched, LINES to be printed, or PAGES to be printed.

CANCEL, DUMP, or WARNING
These parameters are used with three subparameters to specify your desired cancellation option:
CANCEL, which cancels the job when output limit is exceeded
DUMP, which cancels the job when output limit is exceeded and issues a dump
WARNING, which warns the operator when output limit is exceeded and the operator may cancel the job
The formats of these parameters are similar: parameter=(<nnnnnn><,CANCEL>), parameter=(<nnnnnn><,DUMP>), parameter=(<nnnnnn><,WARNING>).

*Identify the Parameter
Output limits (nnnnnn) are expressed according to the type of parameter.
Examine the following table
If Parameter is: nnnnnnn is:
BYTES 0-999999, expressed in thousands of bytes
CARDS 0-99999999 (limit is 6500000 in JES3 systems)
LINES 0-999999, expressed in thousands of lines
PAGES 0-99999999

For example, PAGES=(60,CANCEL) will cancel the job if output exceeds 60 pages.
LINES=(100,DUMP) will cancel the job and issue a dump if output exceeds 100,000 lines.

*The Output Default Limits
You can also use the BYTES, CARDS, LINES, and PAGES parameters to cancel jobs when output exceeds your installation's default limits.
For example, LINES=(,CANCEL)
will cancel a job if the number of lines to be printed exceeds the installation's specified limits.

*Cancel Jobs in JES3
In a JES3 system, you can use the BYTES, CARDS, LINES, and PAGES parameters on the //*MAIN statement to cancel jobs that exceed output limits.
These parameters are almost identical to the ones used on the JOB statement and are coded in a similar manner.
The general format is
//*MAIN  parameter=(<nnnn><,action>)
For example, //*MAIN  PAGES=(100,CANCEL) will cancel the job if output exceeds 100 pages.

*Distinction 1
There are two main distinctions between these output parameters used in JOB statements and //*MAIN statements.
First, in the //*MAIN statement, you can also specify the action C to indicate CANCEL D and specify DUMP W to indicate WARNING.
For example,
//*MAIN  BYTES=(150,CANCEL)
is equivalent to
//*MAIN  BYTES=(150,C).

*Distinction 2
Second, the maximum values for output limits in JOB and //*MAIN statements are different.
Output limits for the //*MAIN statements are
Examine the following table
Parameter Valid Output Limits
BYTES 1-999999, expressed in thousands of bytes
CARDS 1-9999, expressed in hundreds of cards
LINES 1-9999, expressed in thousands of lines
PAGES 1-16777215

For example, //*MAIN  BYTES=(150,DUMP)
will cancel the job and issue a dump if output exceeds 150,000 bytes.



*Overrides
If you use the BYTES, CARDS, LINES, or PAGES parameter in both a //*MAIN statement and a JOB statement, the values specified in the JOB statement will override those in the //*MAIN statement.
For example, in a job with the JCL
//TEST  JOB  1234,SMITH,PAGES=(100,CANCEL)
//*MAIN   PAGES=(150,DUMP)
the job will be canceled when output exceeds 100 pages, and no dump will be issued.

*The Output Conditions
However, suppose you have a job with this JCL:
//TEST  JOB  1234,SMITH,LINES=(20,CANCEL)
//*MAIN   PAGES=(150,DUMP)
In this example, the job will be canceled when either of the following output conditions is met:


Note: A dump will be issued only if the number of pages exceeds 150.




Topic 4.3: Unit 4 Summary

In this unit, you learned the TIME parameter on JOB and EXEC statements specifies the maximum processing time for a job or job step, and the format of the TIME parameter is TIME=(<minutes><,seconds).You also learned that within JES2, the /*JOBPARM statement also has a TIME parameter; however, the /*JOBPARM TIME parameter measures elapsed clock time, not CPU time.
You learned the four parameters on the JOB statement that specify output limits, that is the BYTES parameter, which limits the number of bytes to be spooled, the CARDS parameter, which limits the number of cards to be punched, the LINES parameter, which limits the number of lines to be printed, and the PAGES parameter, which limits the number of pages to be printed.
You learned the parameters that are used with three subparameters to specify your desired cancellation option, including CANCEL, which cancels the job when output limit is exceeded, DUMP, which cancels the job when output limit is exceeded and issues a dump, and WARNING, which warns the operator when output limit is exceeded and the operator may cancel the job.
And finally, you learned that in a JES3 system, you can use the BYTES, CARDS, LINES, and PAGES parameters on the //*MAIN statement to cancel jobs that exceed output limits. You also learned that if you use the BYTES, CARDS, LINES, or PAGES parameter in both a //*MAIN statement and a JOB statement, the values specified in the JOB statement will override those in the //*MAIN statement.

Unit 5. Controlling Restarts



In this unit, you will learn the various JCL restart and checkpoint options to use when a job fails.

After completing this unit, you should be able to:


Topic 5.1: Designating Restarts

*Designate the Restart
Various JCL restart and checkpoint options allow you to designate restart points when a job fails.
These options are not supported in all environments. Since restarts can get pretty complicated and are often restricted. We'll just be covering some of the basic concepts.
You should refer to the standards and guidelines at your installation that deal with restarts.

*Avoid Re-Executing a Job
Job restart options are typically used in production environments to save time. By using restart options, you can avoid having to execute an entire job again when a problem occurs in the middle of execution.
Restart options are also useful in testing environments when you're working with long test jobs or jobstreams.
There are two basic restart options for jobs that terminate abnormally: (1) automatic restart to restart a job at the beginning of a job, job step, procedure step, or designated checkpoint, and (2) deferred restart to restart at the beginning of a job step, procedure step, or designated checkpoint when the job is resubmitted.

*Use the RD and RESTART Parameters
Restarts are specified using the RD and RESTART parameters.
The RD parameter is used to request an automatic restart of a job if the job fails. (RD stands for Restart Definition).
The RESTART parameter is used to specify a restart point when a job is resubmitted.





*The RD Parameter
The RD parameter can be used within JOB and EXEC statements to request an automatic restart if the job fails.
While the RD parameter is not commonly used, it has some specific applications. For example, suppose you have a job that references some shared data sets. In the normal execution of a job, the job could fail if a data set is temporarily unavailable. By requesting an automatic restart, you might avoid having to resubmit the job.
Restarts with the RD parameter are not completely "automatic"; operator approval is required to confirm a job or job step restart.

JOB RD Overrides EXEC RD
When used in a JOB statement, the RD parameter specifies a job restart.
When used in an EXEC statement, the RD parameter specifies a step restart.
The value of the JOB statement RD parameter will override any EXEC statement RD parameters. The RD parameter can be assigned one of four values, and its use is governed by several conditions.
Refer to your JCL manuals and installation guidelines for more information about the RD parameter.



  //TEST    JOB  (123,ACT),SMITH  
  //STEP1   EXEC PGM=PAY
  :
  //STEP2   EXEC PGM=AP
  :
  //STEP3   EXEC PGM=AR
*The RESTART Parameter
The RESTART parameter can be used within a JOB statement to designate a restart point when a job is resubmitted.
The RESTART parameter is typically used when resubmitting a job after correcting an error.
For example, suppose you have a jobstream consisting of three independent job steps like the one shown above.

                 //TEST    JOB  (123,ACT),SMITH
                 //STEP1   EXEC PGM=PAY
                 :
                 //STEP2   EXEC PGM=AP
                 :
  
*Error
When you execute the job, it fails because you didn't define the correct data set in STEP3.

                  //TEST    JOB  (123,ACT),SMITH
                  //STEP1   EXEC PGM=PAY
                  :
                  //STEP2   EXEC PGM=AP
           :
 
*Correct
After correcting your JCL, you might resubmit the job, specifying a restart at STEP3. In this way, the system doesn't have to repeat the instructions in the first two steps.

*Determine the RESTART
The value of the RESTART parameter determines where the job will be restarted:
Refer to your JCL manuals and installation guidelines for more information about this parameter.



*Other Restart Options
Although not typically used by most programmers, there are a couple of other restart options you should know.
Within JES2 and JES3 systems, you have the option to specify an automatic restart of jobs that terminate due to system failure.
In JES2 systems, you use the RESTART=Y parameter on the /*JOBPARM statement.
In JES3 systems, you use the FAILURE parameter on the //*MAIN statement. These options are limited to the restart of the entire job only and have several other conditions for their use.
Refer to your JCL manuals and installation guidelines for more information.



Topic 5.2: Other JES2/JES3 Processing Options

*Special Routing Statements
You can submit jobs in a JES2 system for execution on another system by using special routing statements:
/*ROUTE XEQ node  
/*XEQ   node  
/*XMIT  node
node=destination node

*Equivalent Statements
The /*ROUTE XEQ and /*XEQ statements are equivalent.
These statements designate the destination system for execution of a job.
The destination node can be identified by node number or name.

*After the JOB Statement
The /*ROUTE XEQ or /*XEQ statement must be placed after your JOB statement, but before any DD statements.
For example, this JCL
//TEST    JOB  123,SMITH  
/*XEQ     WEST  
//STEP1   EXEC PGM=MINE
will send the job to a node called WEST.
The jobstream will be scanned for JCL errors on the host JES2 system and will then be transmitted to node WEST for execution of the entire job (including the first JOB statement).

*The /*XMIT Statement
The /*XMIT statement sends records or jobstreams from one system to another.
When the /*XMIT statement is used, JES2 sends only those records/statements that fall between the /*XMIT statement and a specified delimiter.
In this example,
//TESTA  JOB  DEPTA,LEE




JES2 will send only the statements between the /*XMIT statement and the /* delimiter.

*Different Routing Statements
There are a few key differences between these routing statements:
Examine the following table
/*ROUTE XEQ or /*XEQ /*XMIT
Sends entire job to destination system Sends only designated part of jobstream to destination system
Processes entire job on destination system Processes statements outside of /*XMIT and delimiter range on host system; processes statements between /*XMIT and delimiter on destination system
Scans entire jobstream for JCL errors before sending to destination Scans jobstream for JCL errors at destination


*Remote Executions
Using these remote execution options can be tricky.
Statements, parameters, and attributes must follow the destination system's guidelines.
In addition, data sets and procedures referenced in the jobstream must be available on the destination system.





/*SIGNON and /*SIGNOFF
The JES2 /*SIGNON and /*SIGNOFF statements are used for remote job entry. They allow you to submit jobs from a remote workstation for processing by JES2.
The /*SIGNON statement lets JES2 know you want to begin a remote job processing session.
The /*SIGNOFF statement lets JES2 know you want to end the session.

*Some Statement Conditions
Use of these statements is governed by a number of conditions, including:


*Specify a DEADLINE
The DEADLINE parameter on the JES3 //*MAIN statement is used in deadline and periodic scheduling. You can use this parameter to specify job execution:


*No Need to Rush
The DEADLINE parameter is typically used when a job doesn't have to be executed immediately. For example, you might use the DEADLINE parameter to submit a job on first shift, specifying execution before the end of the next day.
In many JES3 installations, job processing is automatically controlled through job schedulers.
Refer to your installation guidelines if you want to use deadline or periodic scheduling.

*Use Another System
You can submit jobs in a JES3 system for execution on another system by using special routing statements:
//*ROUTE XEQ node
//<name> XMIT DEST=node
node=destination node
Both of these statements can be used to send records or job input streams from one system to another for execution.

*Go WEST
In this example,
//TEST    JOB 123,SMITH

//TEST2   JOB AP,SMITH
:
JES3 will send JOB statement TEST2 and the statements that follow it to a node called WEST.

*Go to HQ
In this example,
//TEST    JOB   123,SMITH

:
/*
JES3 will send the records between the XMIT JCL statement and the /* delimiter to a node called HQ.

*Restricted Transmission
The XMIT JCL statement is often preferred over the //*ROUTE XEQ statement, since the latter has restrictions on the types of records that can be transmitted.
You control what records are to be sent by where you put the routing statement, as well as through the use of delimiters. Using these remote execution options can be tricky.
Statements, parameters, and attributes must follow the destination system's guidelines. In addition, data sets and procedures referenced in the jobstream must be available on the destination system.
Refer to your JCL manuals for more information on remote job entry.

*Use JES3 for Remote Jobs
The JES3 /*SIGNON and /*SIGNOFF statements are used for remote job entry. They allow you to submit jobs through a data link from a remote workstation for processing by JES3.
The /*SIGNON statement lets JES3 know you want to begin a remote job processing session.
The /*SIGNOFF statement lets JES3 know you want to end the session.

*More Conditions
Use of these statements is governed by a number of conditions, including:


Topic 5.3: Unit 5 Summary

In this unit, you learned that job restart options are typically used in production environments to save time, and that by using restart options, you can avoid having to execute an entire job again when a problem occurs in the middle of execution. You learned the two basic restart options for jobs that terminate abnormally, including the automatic restart and the deferred restart.
You also learned the RD parameter can be used within JOB and EXEC statements to request an automatic restart if the job fails, and the RESTART parameter can be used within a JOB statement to designate a restart point when a job is resubmitted. You learned that within JES2 and JES3 systems you have the option to specify an automatic restart of jobs that terminate due to system failure.
You learned the /*ROUTE XEQ and /*XEQ statements are equivalent, and that these statements designate the destination system for execution of a job. You also learned the /*XMIT statement sends records or jobstreams from one system to another.
You learned that the JES2 /*SIGNON and /*SIGNOFF statements are used for remote job entry, allowing you to submit jobs from a remote workstation for processing by JES2.
You also learned the DEADLINE parameter on the JES3 //*MAIN statement is used in deadline and periodic scheduling, and that you can submit jobs in a JES3 system for execution on another system by using special routing statements, such as //*ROUTE XEQ node or //<name> XMIT DEST=node.
And finally, you learned that the JES3 /*SIGNON and /*SIGNOFF statements are used for remote job entry, allowing you to submit jobs through a data link from a remote workstation for processing by JES3.

Unit 6. Job Communication Options



In a previous unit, you learned some of the processing control options unique to JES3 systems.
In this unit, you'll look at some common JCL communication options.
Most installations have specific guidelines and defaults regarding the use of various JCL communication facilities. In this unit, you will learn some of these facilities.

After completing this unit, you should be able to:


Topic 6.1: JCL Options

*Some JCL Communication Options
A variety of JCL communication options are available for use in job processing.
For example,


*Statements and JCL
Let's look at these communication options in more depth.
Examine the following table
To JOB Statement EXEC Statement Other Statements
route messages to specific output class MSGCLASS parameter      
control amount of information printed in the job log MSGLEVEL parameter      
send data to a program    PARM parameter   
request message upon completion of job processing or printing NOTIFY parameter    JES2 /*NOTIFY statement
specify message handling by PSF       PIMSG parameter on OUTPUT JCL


MSGCLASS and MSGLEVEL
You learned about the MSGCLASS and MSGLEVEL parameters in a previous course.
To review, the MSGCLASS parameter on the JOB statement routes your job's messages to a particular output class.
The format of this parameter is MSGCLASS=outputclass.
For example, //TEST    JOB  MSGCLASS=Q routes your job's messages to output class Q.

*The MSGCLASS Default
The system default MSGCLASS is A, although many installations have their own defaults.
Frequently an installation selects a message class that will always be held to offer system users flexibility in the output media.
For example, a held message class allows online systems like TSO/E or ROSCOE to display a job's output on the terminal.
You should check your installation guidelines regarding use of the MSGCLASS parameter.

*The MSGLEVEL Parameter
The MSGLEVEL parameter on the JOB statement controls the amount and type of job control statements and systems messages that print.
The format of this parameter is MSGLEVEL=(statements,messages), with the
statements value:
0 to print the JOB statement only
1 to print all JCL statements
2 to print instream JCL statements only
and the
messages value:
0 to print allocation/termination messages only if the job abnormally ends
1 to print all allocation/termination messages

*An MSGLEVEL Example
For example, //TEST    JOB  MSGLEVEL=(1,0)
will print all JCL statements, but print allocation/termination messages only if the job abnormally ends.
As with the MSGCLASS parameter, your installation has default values set for MSGLEVEL. You should refer to your installation guidelines regarding the use of this parameter.

*The PARM Parameter
You learned about the PARM parameter in a previous course.
The PARM parameter on the EXEC statement sends data to the program.
The method that the program uses to obtain the data from the PARM parameter depends on the language used. The programming guide for the language describes the process.
Many utilities, compilers, linkage editors, and other system programs use the PARM parameter to change the options in effect.
Application programs may use a PARM field to signal that special processing is to be performed, such as month, quarter, or year-end processing.

*Format PARM
The format of this parameter is
PARM=subparameter.
When multiple subparameters are needed, use one of these formats:
PARM=(subparameter,subparameter,...) PARM='subparameter,subparameter,...'
The total number of subparameters passed cannot exceed 100 characters.
For example, PARM=(40,132) will be received by the program as 40,132.

There are several variations and restrictions for coding multiple subparameter values or values containing special characters.
Refer to your JCL manuals for more details.



*The NOTIFY Parameter
Use the NOTIFY parameter when you want the system to let you know when a job has completed or output has printed.
The NOTIFY parameter is typically used when you have submitted a job for batch or background processing.
It's a way of making sure the system will let you know when the job has run.

*Use NOTIFY
There are several ways to use the NOTIFY parameter.
Use the NOTIFY parameter on the JOB statement to specify the userid to notify when a job has completed.
The NOTIFY parameter can be used when submitting background jobs to TSO/E.

*Format NOTIFY
The format of the parameter is NOTIFY=userid where userid is a valid TSO/E userid.
For example, NOTIFY=SMITH will prompt the system to send a message to user SMITH when the job completes processing.

NOTIFY and the OUTPUT Statement
Another way to use the NOTIFY parameter is on an OUTPUT JCL statement. You can use the NOTIFY parameter on this statement to request that a message be sent when your output has completed printing.
The general format of this parameter is
NOTIFY=<node.>userid
where node indicates a node name and userid specifies the userid to notify. If the node subparameter is omitted, the system will default to the node where the job was submitted.

*A NOTIFY Example
For example, //OX   OUTPUT   NOTIFY=SMITH
prompts the system to send a message to userid SMITH when the output has printed.
//OX2  OUTPUT   NOTIFY=HQ.SMITH
prompts the system to send a message to userid SMITH at node HQ.

*Four Userids
You can specify up to four userids in an OUTPUT JCL NOTIFY parameter.
The format for multiple userids is
NOTIFY=(<node1.>userid1,...<node4.>userid4)
For example,
//OX3  OUTPUT   NOTIFY=(SMITH,YOUNG)
prompts the system to send a message to userids SMITH and YOUNG when the output has printed.



*The PIMSG Parameter
The PIMSG parameter on the OUTPUT JCL statement specifies how the Print Services Facility (PSF) should handle messages.
While the PIMSG parameter has several functions, it is commonly used to control the printing of messages by PSF.

*Format PIMSG
The general format of the PIMSG parameter is
PIMSG=(YES/Y,<msg-count>) to print all messages generated by PSF, and
PIMSG=(NO/N,<msg-count>) to print error messages if the printing of the data set fails.
The msg-count subparameter is used to request that printing is canceled after the msg-count value is exceeded. Valid values are 0-999, where 0 means infinite.

PIMSG Default
The system default value for the PIMSG parameter is PIMSG=(YES,16). You don't need the parentheses if you are not using msg-count.
For example, //OUT1    OUTPUT  PIMSG=(YES,0) prints all error messages.
Messages are printed at the end of the output data set.
Refer to your installation guidelines and the PSF programmer's guide to learn more about the PIMSG parameter and associated statements.





Topic 6.2: JES2 Options

JES2 and the /*NOTIFY Statement
There are several valid formats for the JES2 /*NOTIFY statement:
/*NOTIFY userid
/*NOTIFY node.userid
/*NOTIFY node:userid
/*NOTIFY node/userid
/*NOTIFY node(userid)
where node identifies the node name, and userid specifies the TSO/E or VM userid to notify.
If the node subparameter is omitted, JES2 defaults to the node where the job was submitted.
For example, /*NOTIFY BIRCH requests that the system send a job completion message to userid BIRCH at the submitting node.

*Equivalent NOTIFY Statements
The statements below are equivalent.
/*NOTIFY HQ.BIRCH
/*NOTIFY HQ:BIRCH
/*NOTIFY HQ/BIRCH
/*NOTIFY HQ(BIRCH)
They specify that the system send a job completion message to userid BIRCH at node HQ.

Tip: The /*NOTIFY statement overrides the JOB statement NOTIFY parameter.




Topic 6.3: Unit 6 Summary

In this unit, you learned that the MSGCLASS parameter on the JOB statement routes your job's messages to a particular output class, and the MSGLEVEL parameter on the JOB statement controls the amount and type of job control statements and systems messages that print.
You learned the PARM parameter on the EXEC statement sends data to the program. You also learned to use the NOTIFY parameter when you want the system to let you know when a job has completed or output has printed, and you learned to use NOTIFY on an OUTPUT JCL statement to request that a message be sent when your output has completed printing.
You also learned the PIMSG parameter on the OUTPUT JCL statement specifies how the Print Services Facility (PSF) should handle messages.
And finally, you learned to use the JES2 /*NOTIFY statement to specify a userid to receive the job's completion messages.