JCL procedures, symbols and conditional steps

A nightly job of five steps must post only when validation ended with a return code of 4 or less, print totals only when nothing failed, and tell someone when anything ended with 8 or more. Two IF statements decide all three, and the same posting steps serve test and production through one procedure.

This lesson runs a chain of COBOL steps whose return codes decide what runs next, then writes the posting steps once as a procedure whose symbols change with each call.

A step’s return code decides which steps run next

Conditional stepsconditional step: A job step that runs or is skipped by the return codes of the steps before it, under an IF/THEN/ELSE/ENDIF construct or a COND parameter. run or are skipped by the return codes of the steps before them. A COBOL program sets RETURN-CODERETURN-CODE: A special register that a program sets to report how it ended. When the run ends, its value goes to the operating system as the exit status, which a shell shows in $?. More in “Install GnuCOBOL, compile with cobc and run programs”, and when it ends, that value becomes its step’s return code, which the job log shows as the condition code. The IF/THEN/ELSE/ENDIF statements of JCL then test it: IBM’s reference says RC means the highest return code of the steps that have run so far, and a step that did not start or ended abnormally is not counted. nightly.jcl uses two such tests:

//NIGHTLY  JOB (ACCT),'NIGHTLY POSTING',CLASS=A,MSGCLASS=X
//* Concept listing, not run: an instream procedure with two
//* symbols, called for production, and steps run on return codes.
//POSTPROC PROC HLQ=BANK.TEST,RUNMODE=TRIAL
//POST     EXEC PGM=POSTTXN,PARM='MODE=&RUNMODE'
//STEPLIB  DD DISP=SHR,DSN=&HLQ..LOAD
//TXNIN    DD DISP=SHR,DSN=&HLQ..TXN.DAILY(0)
//POSTED   DD DSN=&HLQ..POSTED(+1),DISP=(NEW,CATLG,DELETE),
//            SPACE=(CYL,(115,12),RLSE),DCB=(RECFM=FB,LRECL=22)
//SYSOUT   DD SYSOUT=*
//         PEND
//EXTRACT  EXEC PGM=EXTRACT
//VALIDATE EXEC PGM=VALIDATE
//         IF (RC <= 4) THEN
//RUN      EXEC POSTPROC,HLQ=BANK.PROD,RUNMODE=FULL
//         ENDIF
//         IF (RC < 8) THEN
//REPORT   EXEC PGM=BRREPORT
//         ELSE
//NOTIFY   EXEC PGM=NOTIFY
//         ENDIF

Conditional steps can be tried on this computer, where an exit status plays the return code. stepend.cob stands in for each step’s program, and run_chain.sh applies the two IF statements, once for a night where POST ends with 0 and once for one where it ends with 12:

       IDENTIFICATION DIVISION.
       PROGRAM-ID. STEPEND.
      * Stands in for the program of one job step: it is given the
      * step's name and a return code, and ends with that code in
      * RETURN-CODE, as a real program does when it is done.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01  COMMAND-TEXT            PIC X(40).
       01  STEP-NAME               PIC X(8).
       01  CODE-TEXT               PIC X(4).
       01  STEP-CODE               PIC 9(4).
       PROCEDURE DIVISION.
           ACCEPT COMMAND-TEXT FROM COMMAND-LINE
           UNSTRING COMMAND-TEXT DELIMITED BY ALL SPACE
               INTO STEP-NAME CODE-TEXT
           END-UNSTRING
           COMPUTE STEP-CODE = FUNCTION NUMVAL (CODE-TEXT)
           DISPLAY "  " STEP-NAME " runs and sets RETURN-CODE "
               STEP-CODE
           MOVE STEP-CODE TO RETURN-CODE
           GOBACK.

from session import files, run

# Job NIGHTLY's five steps on this computer: stepend.cob stands in for each step's program, and run_chain.sh applies
# the IF/THEN/ELSE/ENDIF statements of nightly.jcl. First a night where POST ends with 0, then one where it ends with 12.
files("stepend.cob", "run_chain.sh")
run("""
cobc -x stepend.cob
bash run_chain.sh 0
bash run_chain.sh 12
""")

$ cobc -x stepend.cob
$ bash run_chain.sh 0
  EXTRACT  runs and sets RETURN-CODE 0000
  VALIDATE runs and sets RETURN-CODE 0004
  POST     runs and sets RETURN-CODE 0000
  REPORT   runs and sets RETURN-CODE 0000
  NOTIFY is bypassed: the ELSE of IF (RC < 8)
highest return code of the job: 4
$ bash run_chain.sh 12
  EXTRACT  runs and sets RETURN-CODE 0000
  VALIDATE runs and sets RETURN-CODE 0004
  POST     runs and sets RETURN-CODE 0012
  REPORT is bypassed: RC 12 is not < 8
  NOTIFY   runs and sets RETURN-CODE 0000
highest return code of the job: 12

On the good night RC was 4 after VALIDATE, so POST ran, and REPORT ran because RC stayed below 8. On the bad night POST ended with 12, so the ELSE branch ran NOTIFY in place of REPORT. Step through the bad night:

Older JCL decides the same things with the COND parameter of the EXEC statement, a bypass test: when one of its tests is true, the step is skipped. Where an IF says when the steps inside it run, a COND test says when its own step does not. A job that abends runs no later step by default, unless a test names the abend.

A procedure is a set of steps whose symbols each call can change

The posting step of nightly.jcl is written once, as a procedure, and called by a step with EXEC POSTPROC,HLQ=BANK.PROD,RUNMODE=FULL. JCL proceduresprocedure: A set of JCL steps written once and called by name from an EXEC statement: instream between PROC and PEND in the job, or cataloged as a member of a procedure library. come in two kinds: an instream procedure sits inside the job between a PROC and a PEND statement, and a cataloged procedure is a member of a procedure library that any job may call. The PROC statement gives each symbolic parametersymbolic parameter: A name such as &HLQ in a JCL procedure that each call can give a value. The PROC statement sets its default, and a value on the calling EXEC statement replaces it for that call. a default, HLQ=BANK.TEST here, and a value on the calling EXEC statement wins over it. expand_proc.py expands POSTPROC both ways:

"""Expands the instream procedure POSTPROC of nightly.jcl the way the system does when a step calls it: the PROC
statement gives each symbol a default, the calling EXEC statement may give it another value, and every &name in the
procedure is replaced. A period right after a symbol is a delimiter and is dropped, so &HLQ..LOAD becomes
BANK.PROD.LOAD (z/OS MVS JCL Reference, Using symbols before fixed code). && starts a temporary data set name, not a
symbol."""
import re
from pathlib import Path

SYMBOL = re.compile(r"(?<!&)&([A-Z#@$][A-Z0-9#@$]{0,7})\.?")


def keywords(text):
    """HLQ=BANK.TEST,RUNMODE=TRIAL -> {'HLQ': 'BANK.TEST', 'RUNMODE': 'TRIAL'}"""
    return dict(part.split("=", 1) for part in text.split(",") if "=" in part)


def substitute(line, values):
    return SYMBOL.sub(lambda m: values.get(m.group(1), m.group(0)), line)


lines = Path("nightly.jcl").read_text().splitlines()
start = next(i for i, l in enumerate(lines) if " PROC " in l)
end = next(i for i, l in enumerate(lines) if l.split()[1:2] == ["PEND"])
defaults = keywords(lines[start].split(" PROC ", 1)[1].strip())
body = lines[start + 1:end]
call = next(l for l in lines[end:] if "EXEC POSTPROC" in l)
overrides = keywords(call.split("EXEC POSTPROC", 1)[1].strip(", "))

for title, values in (("called with the defaults", defaults), ("called by " + call.split()[0][2:], {**defaults, **overrides})):
    print(f"POSTPROC {title}: " + ", ".join(f"&{k}={v}" for k, v in values.items()))
    for line in body:
        if "&" in line:
            print("  " + substitute(line, values))

POSTPROC called with the defaults: &HLQ=BANK.TEST, &RUNMODE=TRIAL
  //POST     EXEC PGM=POSTTXN,PARM='MODE=TRIAL'
  //STEPLIB  DD DISP=SHR,DSN=BANK.TEST.LOAD
  //TXNIN    DD DISP=SHR,DSN=BANK.TEST.TXN.DAILY(0)
  //POSTED   DD DSN=BANK.TEST.POSTED(+1),DISP=(NEW,CATLG,DELETE),
POSTPROC called by RUN: &HLQ=BANK.PROD, &RUNMODE=FULL
  //POST     EXEC PGM=POSTTXN,PARM='MODE=FULL'
  //STEPLIB  DD DISP=SHR,DSN=BANK.PROD.LOAD
  //TXNIN    DD DISP=SHR,DSN=BANK.PROD.TXN.DAILY(0)
  //POSTED   DD DSN=BANK.PROD.POSTED(+1),DISP=(NEW,CATLG,DELETE),

Called with the defaults, every data set is a BANK.TEST one and the PARM says TRIAL; called by step RUN, the same statements name BANK.PROD data sets and FULL. A period right after a symbol ends its name and disappears, which is why the procedure writes &HLQ..LOAD with two periods: IBM’s example is &DEPT..POK for D58.POK. Step through one statement:

Three more statements help JCL procedures and symbols serve many jobs. JCLLIB names the private libraries searched for cataloged procedures and INCLUDE groups, one JCLLIB per job. INCLUDE brings a group of JCL statements from such a library into the job. SET gives symbols values for the statements that follow, and IBM’s reference says a value on a calling EXEC or PROC statement overrides the SET value.

Practise: return codes, procedures and symbols

These questions use the two nights of chain_session.py and the expansion of POSTPROC.

COND, the bypass test, worked through every operator and three traps Pro: opens with a Pro, Premium or Ultimate pass

Overrides, symbols that eat periods, and GDG generations on a restart Pro: opens with a Pro, Premium or Ultimate pass

Interview questions

A warm-up answered in full, then three questions about conditions, procedures and restarts that misbehaved:

Key takeaways

• A COBOL program’s RETURN-CODE becomes its step’s return code, and IF/THEN/ELSE/ENDIF tests RC, the highest code of the steps that have run, to decide which conditional steps run next.
• A job that abends runs no later step by default; COND is the older way to write conditions, as a test that bypasses a step when it is true.
• JCL procedures are written once, instream between PROC and PEND or cataloged in a library, and the symbols of each call replace their defaults; two periods keep one after a symbol.