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:
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
:
:
//<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
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.
You learned the operation field specifies the part of the construct you're coding as shown in the following:
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.
In this unit, you will
learn how to code relational-expressions within an IF/THEN statement.
//<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.
*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.
//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.
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.
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.
//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.
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.
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.
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.
*What Is COND?
The COND parameter is
*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,
*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.
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...
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.
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).
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).
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.
*Then Code It!
Next, think of it logically.
Then, consider how to code it. .
*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
*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).
The EVEN/ONLY CONDition executes the step as follows:
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
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!
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.
Let's look first at how to control job execution by limiting processing time.
*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.
Now we'll look at the parameters used to cancel jobs that exceed certain byte, card, line, or page limits.
*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.
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
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.
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.
In this unit, you will
learn the various JCL restart and checkpoint options to use when a job fails.
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:
*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.
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:
*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
*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:
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.
In a previous unit, you
learned some of the processing control options unique to JES3 systems.
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.
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.
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.
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.
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:
- Control job processing with the conditional (IF)
construct
- Using IF and JCL syntax
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:
- The IF construct specifies the conditions for when you do
want to execute job steps.
- The COND parameter specifies the conditions for when you do not want to execute job steps.
IF Is Powerful
The IF construct is a more powerful feature than the COND parameter.
For example,
- The COND parameter on the first step of a job is ignored; however, the IF construct is tested
- You can nest IF constructs
- You can code symbolic parameters in the IF construct
- You can test more types of relational-expressions with the IF construct
*Test the IF Construct
The relational-expressions you can test with the IF construct include
- Comparison operations such as > or <
- Logical operator AND, OR
- NOT operator
- Relational-expression keywords that test return codes, abend codes, abend condition, step execution
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
- ELSE defines the job steps that execute when the
relational-expression is false
An ELSE clause consists of all the statements between the ELSE and its matching ENDIF. If no statements are specified you can omit it or, if coded, it is called a null ELSE.
- ENDIF designates the end of the IF construct; one is required for each IF construct
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:
- Begin in column 3 and be followed by at least 1 blank
- Made up of 1 to 8 alphanumeric or national characters
- Must be alphabetic or national ($,#,@) in the first character
//<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:
- IF specifies the relational-expression evaluated
- THEN defines the job steps executed when the relational-expression is true
- ELSE defines the job steps that execute when the relational-expression is false
- ENDIF designates the end of the IF construct
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.
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:
- Use operators in relational-expressions
- Identify keywords for relational-expressions
- List some special IF considerations
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.
| 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.
- The NOT operator is evaluated first, the comparison operator second, and the logical operator last.
- Use parentheses for readability and to control the evaluation of complex expressions.
- As in other languages, expressions within parentheses are evaluated prior to the ones outside.
//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 ListSo 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.
| 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.
//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 IFHere are a few considerations when coding the THEN and ELSE clauses in an IF construct.
- One of the clauses must contain at least one EXEC statement.
- Certain statements execute conditionally based upon the evaluation of the relational-expression. These include EXEC, DD, and STEPLIB. See the JCL Reference manual for the complete list.
- These statements should not be coded at all: JOB, JOBLIB, JOBCAT, JCLLIB, SYSCHK, and XMIT.
- Certain statements execute regardless of the logic in the IF construct. These include JES2 and JES3 statements; comment (//*) statements; and null (/*) statements. Refer to your JCL Reference manual for a complete list.
//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.
- Try to avoid nesting wherever possible.
- Avoid nesting more than three levels deep.
- Indent to visually depict the flow.
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:
- Code the COND parameter
- Use multiple COND tests
- Recognize EVEN/ONLY condition tests
*What Is COND?
The COND parameter is
- A keyword parameter
- Optional
*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,
- A return code of 8 issued by a compiler or linkage editor indicates that serious errors were found
- A return code of 0 usually indicates that a JOB step ran fine
*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 CONDYou'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...
| 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.
| 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).
| 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 8Now, 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).
| 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.
| For these rc's... | 0 - 3 | 4 - 8 | 9 - 4095 |
| The JOB... | terminates | executes | terminates |
*Then Code It!
Next, think of it logically.
| Terminate the JOB if... |
3 >= rc 4 > rc |
— or — — or — |
9 <= rc or 8 < rc |
Then, consider how to code it. .
| 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
- Terminate for return codes 0-3
- Execute for return codes 4-8
- Terminate for return codes 9-4095 ...
*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 ONLYThe EVEN/ONLY CONDition executes the step as follows:
- ONLY if previous steps have ABENDed
- EVEN if previous steps have
ABENDed
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
- At the end of all conditions, as shown
- At the beginning of all conditions
- Between the conditions
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:
- Control job processing by limiting time parameters
- Control job processing by setting output limits
Topic 4.1: Controlling Time
*Limit TIMELet's look first at how to control job execution by limiting processing time.
| 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 JobsNow we'll look at the parameters used to cancel jobs that exceed certain byte, card, line, or page limits.
| 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.
| 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
| 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:
- If the number of lines exceeds 20,000
- If the number of pages exceeds 150.
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:
- Initiate job restarts
- Recognize additional JES2/JES3 processing options
Topic 5.1: Designating Restarts
*Designate the RestartVarious 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:
- At the beginning or within a job step
- At the beginning or within a procedure step
- At a specified checkpoint as with the RD parameter, there are
several conditions and requirements for using the RESTART
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 StatementsYou 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:
| /*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:
- The communication protocol being used
- Whether a remote workstation is configured as a dedicated or non-dedicated line
- Any security products used by your installation to control remote job
entry workstations
You should refer to the standards and guidelines at your installation regarding remote job entry.
*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:
- Before a certain time
- On a weekly, monthly or yearly basis
*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:
- The communication protocol being used
- Whether a remote workstation is configured as a dedicated or non-dedicated line You should refer to the standards and guidelines at your installation regarding remote job entry
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:
- Process jobs using JCL communication options
- Process jobs using JES2 communication options
Topic 6.1: JCL Options
*Some JCL Communication OptionsA variety of JCL communication options are available for use in job processing.
For example,
- The MSGCLASS and MSGLEVEL parameters of the JOB statement determine the output class of the job log and the amount of information to be included.
- The PARM parameter of the EXEC statement passes information to a program.
- The NOTIFY parameter is used in background or batch job processing to let you know when your job is completed.
- The PIMSG parameter of the OUTPUT JCL statement controls the handling of messages by the Print Services Facility (PSF).
- The JCL COMMAND statement and its JES2/JES3 counterparts send MVS and JES commands to the system from your JCL.
*Statements and JCL
Let's look at these communication options in more depth.
| 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 StatementThere 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.
No comments:
Post a Comment