Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 38 ยท Modern COBOL and Mainframes

JCL for COBOL Jobs

Learn the Job Control Language needed to run COBOL on z/OS - JOB, EXEC and DD statements, DISP, SPACE and DCB, compile-link-go procedures, SYSIN and SYSOUT, return codes with IF/THEN, and sort steps.

A COBOL program on the mainframe does not know where its files are. Its SELECT ... ASSIGN TO CUSTIN names only a label, and something outside the program must say "CUSTIN is the dataset PROD.CUSTOMER.MASTER". That something is JCL, the Job Control Language. A JCL job is a small text deck of 80-column statements that tells z/OS which programs to run, in which order, with which datasets and how to react to failures.

JCL looks strange at first, but it has only three statements you need to understand: JOB, EXEC and DD.

Anatomy of a job

Text
//PAYRUN   JOB (ACCT123),'NIGHTLY PAYROLL',CLASS=A,MSGCLASS=X,
//             NOTIFY=&SYSUID
//STEP010  EXEC PGM=PAYROLL
//STEPLIB  DD DSN=PROD.LOADLIB,DISP=SHR
//EMPIN    DD DSN=PROD.PAYROLL.EMPLOYEE,DISP=SHR
//PAYOUT   DD DSN=PROD.PAYROLL.OUTPUT,
//             DISP=(NEW,CATLG,DELETE),
//             SPACE=(CYL,(5,2),RLSE),
//             DCB=(RECFM=FB,LRECL=80,BLKSIZE=0)
//SYSOUT   DD SYSOUT=*
//

Every JCL statement starts in column 1 with //. A line with //* is a comment. The statement has a name, an operation and parameters, and a comma at the end of a line with a following blank-continued line means "more parameters". The final // alone ends the job.

  • JOB names the job (PAYRUN), gives accounting information and a job CLASS (which queue and priority), MSGCLASS (where the job log goes) and who to notify.
  • EXEC PGM=PAYROLL starts a step that runs the program (a load module) named PAYROLL. EXEC PROC=name or just EXEC name runs a catalogued procedure instead.
  • DD (data definition) statements follow the step and connect the program's file labels to datasets. The name in columns 3 to 10 is the DD name and must match the program's ASSIGN TO name (for SELECT EMPLOYEE-FILE ASSIGN TO EMPIN the DD is EMPIN).
flowchart LR
    SEL["SELECT EMP-FILE<br/>ASSIGN TO EMPIN"] --> DD["//EMPIN DD<br/>DSN=PROD.PAYROLL.EMPLOYEE"]
    DD --> DS[("Dataset on disk")]

The DD name is the bridge between program and dataset (sequential files).

The DD statement's parameters

Parameter Meaning
DSN=name The dataset name (up to 44 characters); DSN=PDS.NAME(MEMBER) for a member
DISP=(status,normal,abnormal) Status NEW, OLD, SHR (shared read), MOD (append); what to do at normal end (KEEP, DELETE, CATLG, UNCATLG, PASS) and at abnormal end
SPACE=(unit,(primary,secondary),RLSE) Space for a new dataset in TRK, CYL or blocks; RLSE frees what is unused
DCB=(RECFM=FB,LRECL=80,BLKSIZE=0) Record format, record length, block size (0 lets the system choose the best)
UNIT=SYSDA, VOL=SER=... Device type and volume (often not needed with SMS)
SYSOUT=* Send printed output to the job's output queue
DUMMY or DSN=NULLFILE No data: reads return end of file, writes are discarded
* or DATA The data follows in the job stream (instream data)

DISP=(NEW,CATLG,DELETE) is the standard way to create a result file: it is created, cataloged if the step ends normally, deleted if it abends so no half-finished file remains. DISP=SHR for an input dataset lets many jobs read it at once; OLD would make others wait.

Instream data is how you give a program test input without creating a dataset:

Text
//SYSIN    DD *
00001ADA LOVELACE        150000
00002GRACE HOPPER        099999
/*

/* ends the data. A COBOL ACCEPT from SYSIN or a file assigned to SYSIN reads these lines.

To build a program you run the compiler and the binder. Installations provide procedures for this. A typical IBM one, IGYWCL (compile and link-edit), is used like this:

Text
//BUILD    JOB (ACCT123),'BUILD PAYROLL',CLASS=A,MSGCLASS=X
//CL       EXEC IGYWCL
//COBOL.SYSIN   DD DSN=DEV.COBOL.SOURCE(PAYROLL),DISP=SHR
//COBOL.SYSLIB  DD DSN=DEV.COPYLIB,DISP=SHR
//LKED.SYSLMOD  DD DSN=DEV.LOADLIB(PAYROLL),DISP=SHR
//

Names with a dot, such as COBOL.SYSIN, address a DD statement in a step inside the procedure: the COBOL step. SYSIN is the source, SYSLIB the copybook library (copybooks), SYSLMOD the load library that receives the load module. Compiler options can be set with a PARM on the step: //COBOL EXEC PGM=IGYCRCTL,PARM='LIST,MAP,XREF,SSRANGE'. Option names depend on the compiler version.

Running the program afterwards uses EXEC PGM=PAYROLL with STEPLIB pointing at DEV.LOADLIB. PARM can also pass text to the program, read through the Linkage Section:

Text
//GO       EXEC PGM=PAYROLL,PARM='2026-11'
COBOL
       LINKAGE SECTION.
       01  PARM-AREA.
           05  PARM-LEN   PIC S9(4) COMP.
           05  PARM-TEXT  PIC X(100).
       PROCEDURE DIVISION USING PARM-AREA.

On the mainframe the first two bytes hold the length of the string.

Steps, return codes and conditions

A job has one or more steps that run in order. Each step ends with a condition code (the program's RETURN-CODE). You rarely want to run the update step if the edit step failed. Modern JCL uses IF/THEN/ELSE/ENDIF:

Text
//STEP010  EXEC PGM=EDIT
//STEP020  EXEC PGM=UPDATE,COND=(0,NE,STEP010)

reads as "skip STEP020 if 0 is not equal to STEP010's return code". The older COND parameter means "bypass this step if the test is true", which is why it confuses people. The clearer version:

Text
//CHECK    IF (STEP010.RC <= 4) THEN
//STEP020  EXEC PGM=UPDATE
//         ELSE
//STEP030  EXEC PGM=ALERT
//         ENDIF

STEP010.RC is the return code of step 010; ABEND, RUN and STEP010.ABENDCC are other tests. Use the RETURN-CODE convention from file status and error handling so the JCL can make good decisions: 0 clean, 4 warnings tolerated, 8 or more stop the job.

Typical utilities

Jobs often combine your program with IBM utilities:

  • IEBGENER: copy a sequential dataset (SYSUT1 in, SYSUT2 out, SYSIN DD DUMMY).
  • SORT (DFSORT or SYNCSORT): //SORTIN, //SORTOUT and //SYSIN DD * with control statements like SORT FIELDS=(1,5,CH,A) (sort and merge). It is faster than a COBOL SORT for plain reordering.
  • IDCAMS: define and delete VSAM clusters (DEFINE CLUSTER, REPRO to load a file into one, LISTCAT) (VSAM files).
  • IEFBR14: a program that does nothing; with a DD it creates or deletes datasets through the DISP.
  • IKJEFT01: runs TSO commands, and with DSN commands is how DB2 programs are executed in batch (embedded SQL).

Reading the results

After a job finishes you read its output in SDSF. The job log (JESMSGLG) shows return codes per step, the JCL as interpreted (JESJCL) and the system messages (JESYSMSG). A COBOL compiler listing, DISPLAY output (sent to SYSOUT) and the abend messages are in their own sections. If a step fails with JCL ERROR nothing runs; with an IEC141I 013-18 open error, check that the DD record format matches the FD.

A model to play with

JCL cannot run here. The Python stand-ins imitate two things: how a job decides which steps run based on return codes, and how a DD name links a program label to a dataset.

Python Stand-in: step return codes and IF/THEN/ELSE

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python Stand-in: resolving a DD name to a dataset (ASSIGN TO label)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The first block prints RC=0 and both STEP020 runs and STEP030 skipped for the clean job; for the failed one it prints RC=8, STEP020: skipped and the ELSE branch. The second block shows the third OPEN failing because there is no TAXIN DD, the same problem you meet on a real system.

Common mistakes

  1. A DD name that differs from the ASSIGN TO name by one letter: the program cannot open its file.
  2. Forgetting DISP=(NEW,CATLG,DELETE) and leaving half-written datasets behind after an abend.
  3. Using DISP=NEW for a dataset that already exists (the job fails) or OLD for a shared one (jobs queue).
  4. Wrong LRECL or RECFM: abend S013 or fields shifted.
  5. Statements past column 71 (anything after it is ignored).
  6. Confusing COND logic; prefer IF/THEN/ELSE.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a DD statement do?

    The DD name matches the label in ASSIGN TO, and DSN etc. say where the data really is.
  2. 2. What does DISP=(NEW,CATLG,DELETE) mean?

    The three values are the status, the normal-end disposition and the abnormal-end disposition.
  3. 3. Which JCL statement runs a program?

    EXEC PGM=name starts a step that runs the named load module.
  4. 4. How does JCL learn whether a COBOL program succeeded?

    Each step ends with a condition code; IF/THEN/ELSE tests it, for example STEP010.RC <= 4.

Summary

  • JCL has three core statements: JOB, EXEC (run a program or procedure) and DD (attach datasets).
  • The DD name must match the program's ASSIGN TO name; DISP, SPACE and DCB control the dataset.
  • Compile and link with a procedure such as IGYWCL, then run the load module with STEPLIB.
  • Use return codes and IF/THEN/ELSE to control step flow; read the results in SDSF.

Next: Embedded SQL and DB2