JCL Return Codes

Return codes (condition codes) in JCL are numeric values that a program or utility sets when it finishes. The job step’s completion status is determined by this code (and by whether the step abended). You use the COND parameter (and sometimes IF/THEN/ELSE) to skip or run steps based on earlier return codes.

Explain Like I'm Five: What Are Return Codes?

When a step runs (like running a program), it can finish in different ways: "everything’s fine" (usually 0), "there was a small problem" (often 4), or "something went wrong" (8, 12, 16, etc.). That number is the return code. The next step can say "if the previous step’s number was too high, don’t run me" or "run me only if something failed." Return codes are how steps tell the job what happened and how the job decides what to do next.

Condition Codes: What the Numbers Mean

Each step produces a condition code (CC) when it ends. By convention, 0 means success. Higher values often indicate increasing severity, but the exact meaning depends on the program or utility. Many IBM and third-party programs use multiples of 4 (0, 4, 8, 12, 16). Once a step completes, its condition code is fixed; you cannot change it from JCL. If a step abends (abnormal end), it may not set a numeric return code in the usual way; the step is still considered failed and later steps can be skipped unless you use COND=EVEN.

Always check the program or utility documentation for the exact return codes it uses. Some use 0 for success and any non-zero for error; others use a specific range for warnings vs errors.

The COND Parameter

COND is specified on the EXEC statement of a step. It tells the system when to bypass that step. If the condition is true, the step is skipped (not executed). If the condition is false, the step runs. The syntax is COND=(value,operator[,stepname]) or multiple conditions: COND=((value,op[,step]), ...). If stepname is omitted, the condition applies to the return code of any previous step (whichever gives the tested result). Operators are: GT (greater than), GE (greater than or equal), LT (less than), LE (less than or equal), EQ (equal), NE (not equal).

1
2
3
4
//STEP1    EXEC PGM=PROG1
//STEP2    EXEC PGM=PROG2,COND=(4,LT)
//STEP3    EXEC PGM=PROG3,COND=(8,EQ,STEP1)
//CLEANUP  EXEC PGM=CLEANUP,COND=EVEN

STEP2 is bypassed if any previous step (here STEP1) had a return code less than 4. So if STEP1 returns 0, 1, 2, or 3, STEP2 is skipped. STEP3 is bypassed only if STEP1’s return code equals 8. CLEANUP runs even if STEP1, STEP2, or STEP3 abended (COND=EVEN). When you have multiple conditions in one COND, the step is bypassed if any of the conditions is true (OR logic).

COND=EVEN and COND=ONLY

COND=EVEN means: run this step even if a previous step abended. Normally, when a step abends, subsequent steps are skipped. EVEN overrides that so this step always runs. Use it for cleanup, releasing resources, or sending a final message regardless of success or failure.

COND=ONLY means: run this step only if a previous step abended. If all previous steps completed normally (even with a non-zero return code), this step is skipped. Use it for error-recovery or failure-notification steps that should run only when something went wrong.

1
2
3
//RUN      EXEC PGM=MAIN
//NOTIFY   EXEC PGM=SENDMSG,COND=ONLY
//RELEASE  EXEC PGM=RELEASE,COND=EVEN

NOTIFY runs only if RUN abended. RELEASE runs whether RUN and NOTIFY succeeded or failed.

Testing a Specific Step’s Return Code

To test the return code of a specific step, use the third operand: COND=(value,operator,stepname). For example COND=(0,NE,STEP1) means bypass this step if STEP1’s return code is not equal to 0 (i.e. STEP1 failed). COND=(8,GE,STEP2) means bypass if STEP2’s return code is greater than or equal to 8. The stepname must be the name of a previous step in the same job. You can mix conditions: COND=((4,LT,STEP1),(8,GE,STEP2)) bypasses if STEP1 had CC < 4 or STEP2 had CC ≥ 8.

IF/THEN/ELSE and Return Codes

Modern JCL supports IF/THEN/ELSE blocks so you can group steps and run or skip them based on conditions. The condition can test return codes (e.g. STEP1.RC = 0 or STEP1.RC > 4). This is an alternative to coding COND on every step when you have multi-step logic. ENDIF closes the block. See the conditional-execution and IF/THEN/ELSE tutorials for syntax and examples.

Return Codes in Procedures

In cataloged or in-stream procedures, each step still has a return code. When the procedure is invoked, the step names are qualified (e.g. PROCNAME.STEP1). You can reference those in COND or IF: COND=(8,GE,PROCNAME.STEP1). Symbolic parameters in the procedure can change program names or DD names but do not change how return codes work; the step name used in COND must match the executed step name (after symbolic substitution if applicable).

MAXCC and IDCAMS

MAXCC is the maximum condition code from any step in the job (or the highest code that was tested). In some contexts (e.g. job completion messages or NOTIFY), you may see MAXCC reported. In the IDCAMS utility, MAXCC is a reserved word used in control statements to set or test the condition code for IDCAMS operations. It does not change the condition code of earlier steps; it only affects how IDCAMS completes. For general JCL, you control step execution with COND (and IF/THEN/ELSE), not by “setting” MAXCC from JCL.

Step-by-Step: Bypassing a Step on Any Failure

1. Decide the threshold: e.g. bypass the step if any previous step had return code ≥ 4.
2. On the EXEC statement for the step you want to conditionally skip, add COND=(4,GE). GE means “greater than or equal”; the step is bypassed when any prior step’s CC is 4 or higher.
3. If you need to test only one step, use COND=(4,GE,STEPNAME).

Step-by-Step: Running Cleanup Even After an Abend

1. Add a step that performs cleanup (release datasets, send message, etc.).
2. Code COND=EVEN on that step’s EXEC so it runs even when a previous step abended.
3. Place the cleanup step after all steps that might abend.

Best Practices

• Document the return codes your programs and utilities use so COND conditions are meaningful.
• Use COND=EVEN for cleanup or must-run steps; use COND=ONLY for failure-only logic.
• Test specific steps with the third operand (stepname) when the job has multiple steps and you care which one failed.
• Check the job’s completion message and step listing to see which steps ran and what return codes they had.

Test Your Knowledge