COND parameter - IBM-JCL

Parameter Type

Keyword, optional

Purpose
Use the COND parameter to test return codes from previous job steps and determine whether to bypass this job step. You can specify one or more tests on the COND parameter, and you can test return codes from particular job steps or from every job step that has completed processing. If any of the test conditions are satisfied, the system evaluates the COND parameter as true and bypasses the job step. If none of the test conditions specified on the COND parameter are satisfied, the system evaluates the COND parameter as false and executes the job step.

The system performs the COND parameter tests against return codes from the current execution of the job. If a test specifies a previous step that was bypassed, the system evaluates the COND parameter as false.

Bypassing a step because of a return code test is not the same as abnormally terminating the step. The system abnormally terminates a step following an error so serious that it prevents successful execution. In contrast, bypassing of a step is merely its omission.

If a step abnormally terminates, the system normally bypasses all following steps in the job unless the step(s) are part of an IF/THEN/ELSE/ENDIF construct that specifies the ABEND, ABENDCC, or ÏABEND keywords. Another way to make the system execute a following step, for instance, to write a dump, is to code EVEN or ONLY on that step’s EXEC statement. The EVEN or ONLY subparameters are interpreted first. If they indicate that the step should be executed, then the return code tests, if specified, are performed. If no return code tests were coded or if none of the coded tests is satisfied, the system executes the step.

Instead of coding a JOB statement COND parameter, code an EXEC statement COND parameter when you want to:

  • Specify different tests for each job step.
  • Name a specific step whose return code the system is to test.
  • Specify special conditions for executing a job step.
  • Bypass only one step. When a step is bypassed because of a JOB COND parameter, all following steps in the job are bypassed.

Note that a test showing that a return code from a step is zero is not sufficient to verify that the step did not fail; the system may fail a step (or job) even if the return code is zero. This could happen, for example, as a result of specifying CATLG_ERR FAILJOB(YES) and incurring that type of “post execution error.” (The return code is generated by the application program and is never changed by the operating system.) You can determine that a step failed due to a “post execution error” if bit SMF30SYE in the two-byte SMF30STI field in the SMF30 subtype 4 record is on.

1.Syntax

  • One return code test is: (code,operator)
  • You can omit the outer parentheses if you code only one return code test or only EVEN or ONLY.
  • Specify up to eight return code tests. However, if you code EVEN or ONLY, specify up to seven return code tests.
  • You can omit all return code tests and code only EVEN or ONLY.
  • Place the EVEN or ONLY subparameters before, between, or after the return code tests.
  • Null positional subparameters of the COND parameter are invalid.

2.Subparameter Definition

code
Specifies a number that the system compares to the return codes from all previous steps in the job or from specific steps. code is a decimal number from 0 through 4095.

Note: Specifying a decimal number greater than 4095 could result in invalid return code testing or invalid return codes in messages.

operator
Specifies the type of comparison to be made to the return code. If the specified test is true, the step is bypassed.Operators and their meanings are:

Operator Meaning

Operator Meaning

Use Table to select the correct operator.

Operator Meaning

stepname

Identifies the EXEC statement of a previous job step that issues the return code to be used in the test. If the specified step is in a procedure, this step must be in the same procedure. Otherwise, the specified step must not be in a procedure; the specified step must contain a PGM keyword, rather than invoke a procedure.

If you omit stepname, the code you specify is compared to the return codes from all previous steps. If the return code issued by any of those previous steps causes the test condition to be satisfied, the system evaluates the COND parameter as true and bypasses the job step. If this step is invoked in JCL that runs as a started task.

stepname.procstepname
Identifies a step in a cataloged or in-stream procedure called by an earlier job step. Stepname identifies the EXEC statement of the calling job step; procstepname identifies the EXEC statement of the procedure step that issues the return code to be used in the test. The step identified by procstepname must contain the PGM keyword, rather than invoke a procedure.

EVEN
Specifies that this job step is to be executed even if a preceding job step abnormally terminated. When EVEN is coded, the system:

  • Does not test the return code of any steps that terminated abnormally.
  • Does test the return code of any steps that terminated normally. If none of the return code tests for these steps is satisfied, this job step is executed.

ONLY
Specifies that this job step is to be executed only if a preceding step abnormally terminated. When ONLY is coded, the system:

  • Does not test the return code of any steps that terminated abnormally.
  • Does test the return code of any steps that terminated normally. If none of the return code tests for these steps is satisfied, this job step is executed.

3.Overrides
If you code the COND parameter on the JOB statement and on one or more of the job’s EXEC statements, and if a return code test on the JOB statement is satisfied, the job terminates. In this case, the system does not process any subsequent EXEC statement COND parameters.

If the tests on the JOB statement are not satisfied, the system then performs the return code tests on the EXEC statement. If a return code test is satisfied, the step is bypassed.

4.Location in the JCL
You can specify the COND parameter on any EXEC statement in the job. However, the system evaluates a COND parameter on the first EXEC statement in a job as false.

5.On an EXEC Statement that Calls a Procedure
The COND parameter on an EXEC statement that calls a cataloged or in-stream procedure (a calling EXEC statement) will either override or is added to the called EXEC
statements.

The COND on the calling EXEC statement overrides the COND on the called EXEC statement. If the called EXEC statement does not have COND coded on it, the COND on the calling EXEC statement will be added to the called EXEC statement.

If an EXEC statement calls a cataloged or in-stream procedure, the COND parameter overrides the COND parameter on or is added to:

  • The EXEC statement named in the procstepname qualifier, which is to the left of the equals sign. The parameter applies only to the named
    procedure step. The EXEC statement can have as many
    COND.procstepname parameters as the procedure has steps; each COND parameter must specify a unique procstepname.
  • All EXEC statements in the procedure if procstepname is not coded. Then the parameter applies to this job step and to all steps in the called procedure.

6.Considerations when Using the COND Parameter
Be aware of the following considerations when specifying COND parameters. Some of these considerations relate to errors that prevent step execution, no matter what is specified on the COND parameter, while others are related to the use of the COND parameter.

Errors that Prevent Step Execution, Regardless of COND Specifications
Certain error conditions prevent the system from executing a step, regardless of any requests specified through the COND parameter. These conditions are as follows:

Abnormal Termination by the System
After certain types of abnormal termination by the system, remaining job steps are not executed, regardless of whether EVEN or ONLY were specified. The completion codes associated with these types of abnormal termination are:

122 Operator canceled job
222 Operator or TSO/E user canceled job

You might encounter other system completion codes for which remaining job steps are not executed, regardless of whether EVEN or ONLY was specified.

Backward References to Data Sets
If a step is bypassed because of its COND parameter or if a step abnormally terminates, a data set that was to have been created or cataloged in the step may not exist, may not be cataloged, or may be incomplete. Thus, a job step should not refer to a data set being created or cataloged in a step that could be bypassed or abnormally terminated. If the job step does make such a reference, the system might not be able to execute the step.

When the Program Does Not Have Control
For the system to act on the COND parameter, the step must abnormally terminate while the program has control. If a step abnormally terminates during scheduling, due to failures such as JCL errors or the inability to allocate space, the system bypasses the remaining steps, no matter what the COND parameter requests.

JES3 Considerations
In both JES2 and JES3 systems, an EXEC COND parameter determines if a step is executed or bypassed. However, JES3 processes all jobs as though each step will execute; therefore, JES3 allocates devices for steps that are bypassed. JES3 will fail jobs that delete a data set in one step and attempt to reference the deleted data set in a later step, even if the step that deletes the data set is bypassed during execution. JES3 does not support conditional JCL, although it does permit conditional statements to be specified.

COND Parameter on the First Statement in a Job
The system evaluates a COND parameter on the first EXEC statement in a job as false. However, you can use an IF statement before the first EXEC statement in a job to bypass the step.

JOBLIB with COND=ONLY
If the job contains a JOBLIB DD statement and ONLY is specified in a job step, the JOBLIB unit and volume information are not passed to the next step; when the next step is executed, the system searches the catalog for the JOBLIB data set.

When the JOB Statement Contains a RESTART Parameter
When restarting a job, the restart step becomes, in effect, the first step in the job. Therefore, the system evaluates a COND parameter on the restart step as false and executes the step. Subsequent steps might be executed.

When a COND parameter on a step following the restarted step refers to a step that precedes the restarted step, the system evaluates the COND parameter as false. If all other COND parameters on that step are also false, the system executes the step. When the JOB statement contains a RESTART parameter with a checkpoint id, the system evaluates the COND parameter on the designated restart step as false and executes the step.

7.Summary of COND Parameters

Table: Execution or Bypassing of Current Step Based on COND Parameter

Execution or Bypassing of Current Step Based on COND Parameter

Table: Effect of EVEN and ONLY Subparameters on Step Execution

Effect of EVEN and ONLY Subparameters on Step Execution

8.Examples of the COND Parameter

Example

//STEP6 EXEC PGM=DISKUTIL,COND=(4,GT,STEP3)

In this example, if the return code from STEP3 is 0 through 3, the system bypasses STEP6. If the return code is 4 or greater, the system executes STEP6. Because neither EVEN nor ONLY is specified, the system does not execute this step if a preceding step abnormally terminates.

Example

//TEST2 EXEC PGM=DUMPINT,COND=((16,GE),(90,LE,STEP1),ONLY)

The system executes this step ONLY if two conditions are met:

  1. A preceding job step abnormally terminated.
  2. No return code tests are satisfied.

Therefore, the system executes this step only when all three of the following are true:

  • A preceding job step abnormally terminated.
  • The return codes from all preceding steps are 17 or greater.
  • The return code from STEP1 is 89 or less.

The system bypasses this step if any one of the following is true:

  • All preceding job steps terminated normally.
  • The return code from any preceding step is 0 through 16.
  • The return code from STEP1 is 90 or greater.

Example

In this example, if STEP1 returns a code of 4, STEP2 is bypassed. Before STEP3 is executed, the system performs the first return code test. If 8 is less than the return code from STEP1, STEP3 is bypassed; or, restated, if the STEP1 return code is less than or equal to 8, STEP3 is executed. Because 4 is less than 8, STEP3 is executed. The system does not perform the second return code test because STEP2 was bypassed.

Example

This statement calls cataloged or in-stream procedure BILLING. The statement specifies different return code tests for each of the procedure steps: PAID, LATE, and BILL. The system executes step PAID even if a preceding step abnormally terminates unless the accompanying return code is satisfied.

Example

The procedure TEST exists in SYS1.PROCLIB:

The job:

JOB1 restarts at JOBSTEP. PROCSTP1 is the first step in the job because of the RESTART specification, and the COND parameter test is not valid because no previous steps have run. Therefore, the system evaluates the COND parameter for PROCSTP1 as false, and PROCSTP1 runs. PROCSTP3 has no COND parameter. The COND parameters for PROCSTP2 and PROCSTP4 are used.

The job:

JOB1 restarts at PROCSTP2 as called by JOBSTEP. The COND parameter on JOBSTEP does not specify a procstepname qualifier and therefore applies to all steps in procedure TEST. The system evaluates the COND parameter for PROCSTP2, the restart step, as false, and the step runs. However, the COND parameter for steps PROCSTP3 and PROCSTP4 evaluates as true (because 8 is greater than the return code of 0 provided by all previous steps in the job), and the steps are bypassed.

The job:

JOB1 restarts at PROCSTP2 as called by JOBSTEP. Because of the RESTART specification, PROCSTP2 is the first step in the job. The system evaluates the COND parameter for PROCSTP2 as false, and the step runs. PROCSTP3 has no COND parameter. PROCSTP4 is overridden as specified on JOBSTEP.


All rights reserved © 2018 Wisdom IT Services India Pvt. Ltd DMCA.com Protection Status

IBM-JCL Topics