JCL for COBOL Programmers

A job is a stream of 80-column records. Each JCL statement starts with // in columns 1 and 2 and has up to four fields separated by blanks: the optional name, the operation (JOB, EXEC, DD, IF, …​), the parameters and optional comments. A statement that does not fit before column 72 is continued by ending the line after a complete parameter and its comma, and starting the next line with // followed by a blank, with the parameters resuming in columns 4 to 16. Comment, null, delimiter and JCL command statements cannot be continued. The statements a COBOL programmer meets are:

Source: z/OS 3.2 MVS JCL Reference: Job control statements, Format of statements

The names of jobs, steps and DDs are one to eight characters. The output of a batch job is a collection of three data sets that the system always produces: the JES job log (JESMSGLG), the statement images (JESJCL) and the system messages (JESYSMSG); MSGLEVEL controls how much is printed in the last two. In the system messages the messages IEF142I and IEF472I mark the normal and the abnormal end of a step, and the IEF285I messages tell what happened to each data set (kept, deleted, cataloged). Those are the first things to read when a job misbehaves.

Every step ends with a return code, a number from 0 to 4095 that tells the job scheduler how the step went. For a COBOL program it is the value of the RETURN-CODE special register at the end of the program, which Enterprise COBOL defines as a signed four-digit binary item with initial value zero, and which is passed to the operating system as a user return code when control returns to it. (The values the operating system accepts may be fewer than the register can hold.) The convention that z/OS programs and IBM’s compilers follow is:

This is a convention, not part of the language: the value is whatever the program moves to RETURN-CODE, and the job decides what to do with it. An abend (for example a system completion code S0C7 for a data exception, or a user code such as U0100) is a different outcome from a return code, and is tested separately.

The next program is the portable part of this page. LOANCHECK validates the day’s transactions and reports the result by return code: 0 if every record is a checkout or a return, 4 if there were rejects, 8 if there were rejects and the caller asked for a strict run, and 12 if the file would not open. The argument stands in for PARM, which GnuCOBOL does not have. Compiled with cobc -x -Wall -I. loancheck.cob (and with -std=ibm), no warnings, it was run four times, with LOANTRAN (the four valid transactions of the Circulation data), with a bad record X appended, with the argument STRICT, and with the file missing, and the shell’s exit status is shown after each run:

The copybook is LOANREC of Copybooks and REPLACE. On z/OS the same program needs two changes: ASSIGN TO LOANTRAN (a DD name, without the quotes and the LINE SEQUENTIAL organization, because the data set is a QSAM data set), and the PARM linkage shown earlier instead of ACCEPT ... FROM COMMAND-LINE. The missing-file case of this test gave status 35 in GnuCOBOL; on z/OS a missing DD statement shows up at the same OPEN, and the status codes and messages to check are on File Status Codes.

Source: Enterprise COBOL for z/OS 6.5 Language Reference: RETURN-CODE special register; GnuCOBOL 3.2 manual

A procedure is a group of steps with placeholders called symbolic parameters, written &NAME in the JCL. It is cataloged (a member of a procedure library, called by its name) or in-stream (between PROC and PEND right after the JOB statement). The PROC statement gives each symbol a default, and the EXEC that calls the procedure overrides it:

The substitution rules are the part that people trip over. A symbol’s name ends at a period, and the period is dropped, so &HLQ..CIRC is USERID.CIRC: the first period ends the symbol, the second is the one that appears in the name. Values with special characters are enclosed in apostrophes, a value with a matched pair of parentheses such as (NEW,KEEP) is not, and a symbol can be nullified by assigning it nothing (TRAN=). The SET statement assigns a symbol a value in the job itself (// SET HLQ=USERID). With MSGLEVEL=(1,1) the IEF653I messages of the job log show the values every symbol received.

A step in a called procedure is changed from the calling EXEC and the statements that follow it, always by naming the procedure step, a period and the DD name:

An overriding DD replaces, nullifies or adds parameters to the procedure’s DD of that name; a DD with a new name is added to the step. The PGM parameter cannot be overridden. The overrides must follow the calling EXEC in the order of the procedure steps, an override that does not name a step applies to the step named in the previous override (or the first step), and a PARM.stepname on the EXEC replaces the procedure step’s PARM. A catalogued procedure is found through the libraries named in a JCLLIB ORDER=(lib1,lib2) statement (up to 15, searched in that order before the system procedure libraries), or in the system defaults.

Source: z/OS 3.2 MVS JCL Reference: Procedures and symbols, JCLLIB, PROC and SET statements

A generation data group (GDG) is a family of data sets under one name, one per run, that the system keeps in order: USERID.CIRC.BOOKGDG has generations whose real names are USERID.CIRC.BOOKGDG.G0007V00, .G0008V00 and so on. JCL refers to them by relative generation: USERID.CIRC.BOOKGDG(+1) is the one this job creates, USERID.CIRC.BOOKGDG(0) is the latest that exists, and USERID.CIRC.BOOKGDG(-1) is the one before it. This is what makes a nightly job rerunnable and self-cleaning: last night’s master is (0), tonight’s is (+1), and when a limit is reached the system rolls the oldest generation off the group. The number is signed or zero, has one to three digits, and cannot exceed 255. Omitting the number (DSN=USERID.CIRC.BOOKGDG) reads all the generations as one concatenation.

The group itself, its base, is defined once with IDCAMS (z/OS; not run here):

LIMIT is the maximum number of generations (1 to 255, or up to 999 with EXTENDED), NOEMPTY removes only the oldest generation when the limit is exceeded (EMPTY removes them all), and SCRATCH deletes the rolled-off data set. (0) fails until a generation exists, so the first one is created by a step with a (+1) DD (an IEFBR14 step is enough). The rules for using the relative numbers in a job are the ones the manuals stress:

The job step that creates a generation uses DISP=(NEW,CATLG,DELETE) as for any new data set:

Source: z/OS 3.2 DFSMS Using Data Sets: Processing generation data groups; z/OS 3.2 DFSMS Access Method Services Commands: DEFINE GENERATIONDATAGROUP; z/OS 3.2 MVS JCL Reference: DSNAME parameter, GDGBIAS parameter

IBM supplies cataloged procedures that run the Enterprise COBOL compiler, the binder and the program, so that nobody writes the SYSUT1 to SYSUT15 work files by hand. The Programming Guide documents three, and every installation names, places and customizes its own copies, so check the name and the library prefix in the shop’s procedure library:

The symbols are LNGPRFX (the prefix of the compiler data sets, IGY.V6R5M0 in the Programming Guide) and LIBPRFX (the prefix of the Language Environment data sets, CEE), plus PGMLIB and GOPGM as above. The compiler step runs IGYCRCTL with REGION=0M and its own STEPLIB (the compiler library, then the Language Environment runtime libraries). The caller must supply the source, and a library for COPY:

These two-level names are the way a calling job overrides a procedure: COBOL. and LKED. are the step names, and the DD name follows the period. A complete compile and link followed by a run of the new module, as the developer’s-day section of Mainframe Environment Primer sketches it (z/OS; not run here):

PARM.COBOL replaces the compiler options on the COBOL step only (LIST, MAP and XREF print the listing sections described in Compiling, Linking and Language Environment; the installation’s defaults apply to the options not named). The RUN step is the same program started by name from the library the binder just wrote. Its COND names a procedure step with the stepname.procstepname form. If everything is in one job and the program need not be kept, IGYWCLG does all three steps in one call, and a GO.ddname DD supplies the program’s files:

The Programming Guide notes that the assignment name of a COBOL file should match the DD name of the GO step (//GO.DDNAME DD DSN=...). Because the load module lives in the temporary &&GOSET, nothing is kept after the job, which is right for trying a program and wrong for a program the nightly job will call. A compile that finds a problem ends with a return code that depends on the severity of the worst message (the compiler’s severity codes and IGY messages are on Compiling, Linking and Language Environment), and the COND tests of the procedures decide which steps still run.

Source: Enterprise COBOL for z/OS 6.5 Programming Guide: Using a cataloged procedure; Compile procedure (IGYWC); Compile and link-edit procedure (IGYWCL); Compile, link-edit, and run procedure (IGYWCLG); Programming Guide: Data sets used by the compiler under z/OS

Everything above comes together in the batch run that closes each day at the library. It has four steps, each with its own program and files:

Each step runs only if the earlier ones ended with a return code of 4 or less; a rejected transaction is a 4, not a reason to stop the night. A last step after the other four alerts the operator after an abend or a return code above 4. The job reads as follows (z/OS; not run here):

The points that make this a realistic job are worth reading in turn:

The size of SPACE, the job class and the data class are the installation’s. The SORT step needs no work data sets here because DFSORT allocates them dynamically in current installations (see Sort and Merge), and the control statement SORT FIELDS=(8,6,ZD,A,14,8,ZD,A),EQUALS sorts on the six-digit book number at byte 8 and the eight-digit date at byte 14 of the LOANREC record, both ascending, keeping the original order of equal keys.

Source: z/OS 3.2 MVS JCL Reference; z/OS 3.2 DFSORT Application Programming Guide (PDF)

When the update step fails at three in the morning, the operator does not want to sort the file again, and above all does not want to apply the day’s transactions twice. A job can be resubmitted to start at a given step with the RESTART parameter of the JOB statement:

RESTART=stepname restarts at the beginning of that step, RESTART=* at the first step, and RESTART=(stepname,checkid) at a checkpoint within a step (the checkpoint data set is then described by a SYSCHK DD that must follow the JOB statement). A step in a procedure is named stepname.procstepname, and the restart step must be a step that has a PGM=, and its name must be unique in the job. The manual lists what has to be checked before a job is resubmitted, and each item has a consequence for the nightly job above:

For a COBOL programmer there is a second, more important meaning of restart: the program must make restart safe. The balance-line update writes a new generation instead of changing the master in place, so a failed run leaves the old generation as it was and the job can run again from that step; DISP=(NEW,CATLG,DELETE) makes the same promise for the file. An update in place of a VSAM master has no such protection, and then the job’s design (a backup step before the update, a restart procedure of the scheduler, commit points in Db2) has to supply it.

Source: z/OS 3.2 MVS JCL Reference: RESTART parameter, Generation data sets in restarted jobs; z/OS 3.2 DFSMS Using Data Sets: Processing generation data groups

Zowe CLI submits jobs and reads the spool from a workstation, through the z/OSMF REST services of the system, so the nightly job can be developed with the editor and the terminal of the Modern Tooling: VS Code and Zowe page instead of ISPF and SDSF. The commands of the zos-jobs group that this page needs are:

submit local-file and submit data-set take the JCL from a local file or from a sequential data set or PDS member. The options used here are --wait-for-active (--wfa) and --wait-for-output (--wfo), which hold the command until the job reaches the ACTIVE or OUTPUT state, --view-all-spool-content (--vasc), which prints everything the job wrote and waits for the job to end, --directory (-d), which saves the output in a local directory named by the job ID, and --jcl-symbols (--js), which gives values to the symbols of the JCL as symbol1=value1 symbol2=value2 (the symbols of a procedure called by the job, for example HLQ=USERID). view job-status-by-jobid shows the state and the return code of the job, and view spool-file-by-id takes the job ID and the number of a spool file, which list spool-files-by-jobid shows: the three system data sets of the job and one for each SYSOUT DD. The job ID in the examples (JOB00123) is the form the Zowe documentation uses; JES assigns the real one when the job is submitted and the submit command prints it.

The connection to z/OSMF (host, port, user and password or a token) is not on the command lines above because it comes from a Zowe profile or team configuration created once (see the Zowe documentation), so no host or credential appears in a script. Reading the result is the same as in SDSF: look at the job log for the return codes of the steps and at the IEF142I and IEF472I lines of the system messages, then open the SYSOUT of the step that failed. Zowe 3.x is the current line of the documentation; the commands above are the ones in that documentation, and the book’s Zowe v1 profiles and prerequisites no longer apply.

Source: Zowe CLI: zowe zos-jobs submit local-file; zowe zos-jobs submit data-set; zowe zos-jobs view job-status-by-jobid; zowe zos-jobs list spool-files-by-jobid; zowe zos-jobs view spool-file-by-id