Return Codes (RCs) / Condition Codes

Purpose

Return codes (also called condition codes) are numeric values returned by programs and job steps to indicate their completion status. These codes are fundamental to job flow control in JCL, enabling conditional execution based on the success or failure of previous steps.

Key Benefit:

Return codes provide a standardized way to determine whether a job step executed successfully, encountered errors, or requires special handling. By evaluating these codes, JCL can implement complex logic for error recovery, alternative processing paths, and job flow control.

Return Code Basics

Return codes in z/OS and JCL environments follow these conventions:

Return codes are 8-bit values ranging from 0 to 255
By convention, codes typically indicate:
- 0: Successful completion
- 4: Warning condition (minor issues)
- 8: Error condition (significant issues)
- 12: Serious error (major issues)
- 16: Terminal error (fatal issues)
- 20+: Catastrophic errors or program-specific codes
Programs set their return code before termination (in Assembler via register 15, in high-level languages via specific statements)
System utilities and compilers follow standard return code conventions
Custom application programs may define their own return code meanings

COND Parameter

The COND parameter on JOB and EXEC statements allows conditional execution based on return codes from previous steps.

COND on EXEC Statements

jcl

1
2
//STEP2 EXEC PGM=PROGRAM2,
//       COND=(code,comparison,stepname)

code: The return code value to compare against (0-4095)
comparison: One of the following operators:
- GT: Greater than
- GE: Greater than or equal to
- EQ: Equal to
- LT: Less than
- LE: Less than or equal to
- NE: Not equal to
stepname: The name of the step whose return code is being tested (optional)

COND Operation: A step is bypassed (not executed) if any of the conditions specified is true. This can be counterintuitive - the condition describes when to skip the step, not when to run it.

COND on JOB Statements

jcl

1
2
//JOBABC JOB accounting-info,name,
//       COND=(code,comparison)

The COND parameter on a JOB statement applies to all steps in the job. If the condition becomes true, all remaining steps are bypassed.

Multiple Conditions

jcl

1
2
//STEP3 EXEC PGM=PROGRAM3,
//       COND=((4,LT,STEP1),(8,EQ,STEP2))

This example bypasses STEP3 if STEP1 returned a code less than 4 OR if STEP2 returned a code equal to 8.

IF/THEN/ELSE Conditional Execution

Modern JCL offers IF/THEN/ELSE statements for more intuitive conditional logic:

jcl

1
2
3
4
5
6
7
//STEP1  EXEC PGM=PROGRAM1
//*
// IF (STEP1.RC <= 4) THEN
//STEP2  EXEC PGM=PROGRAM2
// ELSE
//STEP3  EXEC PGM=PROGRAM3
// ENDIF

This example runs STEP2 if STEP1 was successful or had only warnings, otherwise it runs STEP3.

IF/THEN/ELSE advantages over COND:

More intuitive logic - test when to run a step, not when to skip it
Support for AND and OR operators for complex conditions
Support for testing system ABENDs and other conditions
Nesting capability for complex logic

Common Return Codes for Standard Utilities

Utility	RC=0	RC=4	RC=8	RC>8
IEBCOPY	Successful	Minor issues (e.g., duplicate member replaced)	Processing errors	Serious errors, processing terminated
IEBGENER	Successful	Warnings	Processing errors	Serious errors
IDCAMS	Successful	Warnings	Function completed with error	Function not completed due to error
SORT	Successful	Warnings (e.g., duplicate records)	Processing errors	Serious errors
COBOL Compiler	Clean compile	Warnings, executable created	Errors, no executable	Severe errors
IEFBR14	Always returns 0	N/A	N/A	N/A

Setting and Using Return Codes

Setting Return Codes in Programs

Different programming languages have different methods for setting return codes:

Language	Method	Example
Assembler	Load register 15 before program exit	asm 1 2 `LA R15,8 Set RC=8 BR R14 Return to caller`
COBOL	RETURN-CODE special register	cobol 1 2 `MOVE 8 TO RETURN-CODE. GOBACK.`
PL/I	PLIRETC function	pli 1 `CALL PLIRETC(8);`
C	return statement in main()	c 1 `return 8;`
REXX	EXIT instruction	rexx 1 `EXIT 8`

Accessing Return Codes in JCL

JCL provides several ways to access return codes for conditional processing:

Step Return Code: STEP.RC or stepname.RC
jcl
```
1
// IF (STEP1.RC > 0) THEN
```
Previous Step Return Code: RC (shorthand for previous step)
jcl
```
1
// IF (RC = 0) THEN
```
Job Return Code: JOBRC (maximum return code so far)
jcl
```
1
// IF (JOBRC <= 4) THEN
```
ABENDs: STEP.ABEND or STEP.ABENDCC
jcl
```
1
// IF (STEP1.ABEND) THEN
```
Testing Specific ABEND Codes:
jcl
```
1
// IF (STEP1.ABENDCC = 'S0C7') THEN
```

Advanced Condition Code Usage

Complex Conditions

jcl

1
2
3
// IF ((STEP1.RC > 4) & (STEP1.RC < 12)) | (STEP2.RC = 0) THEN
//STEP3  EXEC PGM=PROGRAM3
// ENDIF

This example runs STEP3 if STEP1 had an error (but not a serious one) OR if STEP2 was successful.

Nested Conditions

jcl

1
2
3
4
5
6
7
8
// IF (STEP1.RC = 0) THEN
//STEP2  EXEC PGM=PROGRAM2
//   IF (STEP2.RC <= 4) THEN
//STEP3  EXEC PGM=PROGRAM3
//   ENDIF
// ELSE
//STEP4  EXEC PGM=PROGRAM4
// ENDIF

This example demonstrates nested IF statements for complex job flow logic.

Return Code Manipulation

Sometimes it's useful to set an artificial return code for testing or control purposes:

jcl

1
2
3
4
5
6
7
8
//SETRCODE EXEC PGM=IEFBR14
// IF (CONDITION) THEN
//SET     SET RC=8
// ENDIF
//*
// IF (RC = 8) THEN
//ERRPROC EXEC PROC=ERRORHANDLING
// ENDIF

This example sets a synthetic return code based on a condition for subsequent decision making.

Common Issues and Troubleshooting

Issue	Possible Causes	Solutions
Steps running when they should be skipped	COND logic inverted (tests when to skip, not run)	Review COND condition logic Consider using IF/THEN/ELSE instead
Steps skipped incorrectly	Incorrect comparison operator or return code value	Add MSGLEVEL=(1,1) to JOB statement to see actual return codes Verify the codes expected from each program
Unexpected return codes	Program error or misunderstood program behavior	Review program documentation for return code meanings Add error checking within programs
COND parameter ignored	Job abended (COND parameters don't apply after abends)	Use IF/THEN/ELSE with ABEND testing instead Add EVEN/ONLY parameter to EXEC statement

JOBRC and Final Job Return Code

Every job returns a final return code, which is used by job schedulers and dependent jobs to determine subsequent actions.

Default Behavior: The final job return code is the highest return code from any step that executed

JOBRC Statement: Allows explicit control of the final job return code

jcl

1
2
//MYJOB    JOB (ACCT),'MY NAME',MSGLEVEL=(1,1)
//JOBRC    JOBRC MAXIMUM

JOBRC Options:
- MAXIMUM: Use the highest return code (default)
- LASTRUN: Use the return code from the last step that ran
- (stepname): Use the return code from the named step
- (stepname.procstep): Use the return code from the named proc step

Best Practices

Use Standard Return Codes: Follow conventions (0=success, 4=warning, 8=error, etc.) for consistency
Prefer IF/THEN/ELSE Over COND: Modern JCL conditional constructs are more readable and flexible
Document Non-Standard Codes: Add comments explaining any unusual return code meanings
Be Specific in Conditions: Test for specific return code values or ranges rather than just zero vs. non-zero
Handle ABENDs: Include ABEND testing in critical jobs to ensure proper error handling
Review Job Output: Use MSGLEVEL parameter to ensure return codes are visible in job output
Use MAXRC Step: For critical jobs, consider adding a final step that evaluates and reports overall status
Document Job Flow: Include flow charts or comments explaining the job's decision logic

JES2 vs JES3 Considerations

Return code handling is generally the same in both JES2 and JES3 environments, but there are some considerations:

Feature	JES2	JES3
Return code visibility	Standard format in job log	Standard format in job log
Dependent job control	Through job scheduler or automation tools	Native dependent job control features
Condition code treatment	Standard	Enhanced options with JES3 control statements

Related Concepts

IF Statement - Conditional processing based on return codes
COND Parameter - Traditional conditional execution
JOBRC Statement - Control of final job return code
Conditional Execution - Broader topic of conditional processing in JCL
JOB Statement - Can include COND parameter for job-level conditions
EXEC Statement - Can include COND parameter for step-level conditions