Compiling, link-editing and utility steps

One changed COBOL program reaches production through two programs before it runs: the compiler, IGYCRCTL, and the binder, IEWBLINK. IBM ships three procedures for the trip, and a compile that ends with return code 8 still reaches the binder under the procedure’s default test.

This lesson reads the procedures for compiling and link-editing step by step, runs the same build with cobc, and then names the utility steps that create, copy, sort and catalog the data sets around a batch program.

Compiling and link-editing are two steps of IBM’s procedures

Compiling turns the source into an object moduleobject module: What a compile produces: the program's machine code with its calls to other programs still unresolved. The binder combines object modules into a program the system can load.; link-editing turns object modules into a program the system can load. IBM’s cataloged procedures package the steps: IGYWC compiles, IGYWCL compiles and link-edits, and IGYWCLG also runs the result. In IGYWCL the COBOL step runs IGYCRCTL, and the caller supplies COBOL.SYSIN with the source and COBOL.SYSLIB with the copybook libraries. The object goes to the temporary data set &&LOADSET through SYSLIN, and the LKED step’s binderbinder: The z/OS program that link-edits object modules into a program stored in a load library, resolving the calls between them; IBM's COBOL procedures run it as IEWBLINK in their LKED step. writes the program to SYSLMOD, a PDSEPDSE: A partitioned data set extended: a library like a PDS whose directory grows as needed and whose freed space is reused without a compress. COBOL 6 executables must be stored in one. More in “z/OS data sets, catalogs and GDGs”:

//BLDSHOW  JOB (ACCT),'BUILD SHOWACCT',CLASS=A,MSGCLASS=X
//* Concept listing, not run: compiles SHOWACCT and link-edits it
//* into the load library with IBM's procedure IGYWCL.
//BUILD    EXEC IGYWCL,PGMLIB='BANK.PROD.LOAD',GOPGM=SHOWACCT,
//            PARM.COBOL='SSRANGE,LIST,MAP'
//COBOL.SYSIN  DD DISP=SHR,DSN=BANK.PROD.COBOL(SHOWACCT)
//COBOL.SYSLIB DD DISP=SHR,DSN=BANK.PROD.COPYLIB

The compiler’s return code says how bad its messages were, and the procedure tests it:

LKED says COND=(8,LT,COBOL), so it is bypassed only after a compile return code of 12 or 16. A program with E-level errors is link-edited and, in IGYWCLG, run, although IBM says its results might not be what you expect. Step through IGYWCLG:

cobc does the same two steps on this computer

Locally, cobc -c compiles to an object file, as IGYWC does, and cobc -x with the objects link-edits them into one program, as IGYWCL does. -I plays SYSLIB for copybooks and -t writes the listing that SYSPRINT holds on z/OS. The build of ACCTLIST and its subprogram SHOWACCT, then a compile with the copybook library left out:

from session import files, run

# The build of ACCTLIST and SHOWACCT with cobc, step by step as IBM's procedures do it on z/OS: a compile that writes
# an object file and a listing, with the copybook library in the place of SYSLIB; a link of the two into one program;
# a run; and a compile with the copybook library left out.
files("acctlist.cob", "showacct.cob", "copylib/ACCTREC.cpy")
run("""
cobc -std=ibm -c -I copylib -t showacct.lst -fno-theaders showacct.cob
ls
cat showacct.lst
cobc -std=ibm -x -I copylib acctlist.cob showacct.o
./acctlist
!cobc -std=ibm -c acctlist.cob
""")

$ cobc -std=ibm -c -I copylib -t showacct.lst -fno-theaders showacct.cob
$ ls
acctlist.cob
copylib
showacct.cob
showacct.lst
showacct.o
$ cat showacct.lst

000001         IDENTIFICATION DIVISION.
000002         PROGRAM-ID. SHOWACCT.
000003        * A subprogram: shows the account record it is passed.
000004         DATA DIVISION.
000005         LINKAGE SECTION.
000006         COPY ACCTREC.
000001C       * ACCTREC: one account, as the account file holds it.
000002C        01  ACCT-REC.
000003C            05  ACCT-ID             PIC X(6).
000004C            05  ACCT-BRANCH         PIC X(3).
000005C            05  ACCT-BALANCE        PIC S9(9)V99 COMP-3.
000007         PROCEDURE DIVISION USING ACCT-REC.
000008             DISPLAY "SHOWACCT: " ACCT-ID " " ACCT-BRANCH " "
000009                 ACCT-BALANCE
000010             GOBACK.


0 warnings in compilation group
0 errors in compilation group
$ cobc -std=ibm -x -I copylib acctlist.cob showacct.o
$ ./acctlist
SHOWACCT: AC0001 MUM +00000250075
$ cobc -std=ibm -c acctlist.cob
acctlist.cob:7: error: ACCTREC: No such file or directory
    5 |        DATA DIVISION.
    6 |        WORKING-STORAGE SECTION.
    7 >        COPY ACCTREC.
    8 |        PROCEDURE DIVISION.
    9 |            MOVE "AC0001" TO ACCT-ID
acctlist.cob:9: error: 'ACCT-ID' is not defined
    7 |        COPY ACCTREC.
    8 |        PROCEDURE DIVISION.
    9 >            MOVE "AC0001" TO ACCT-ID
   10 |            MOVE "MUM" TO ACCT-BRANCH
   11 |            MOVE 2500.75 TO ACCT-BALANCE
acctlist.cob:10: error: 'ACCT-BRANCH' is not defined
    8 |        PROCEDURE DIVISION.
    9 |            MOVE "AC0001" TO ACCT-ID
   10 >            MOVE "MUM" TO ACCT-BRANCH
   11 |            MOVE 2500.75 TO ACCT-BALANCE
   12 |            CALL "SHOWACCT" USING ACCT-REC
acctlist.cob:11: error: 'ACCT-BALANCE' is not defined
    9 |            MOVE "AC0001" TO ACCT-ID
   10 |            MOVE "MUM" TO ACCT-BRANCH
   11 >            MOVE 2500.75 TO ACCT-BALANCE
   12 |            CALL "SHOWACCT" USING ACCT-REC
   13 |            GOBACK.
acctlist.cob:12: error: 'ACCT-REC' is not defined
   10 |            MOVE "MUM" TO ACCT-BRANCH
   11 |            MOVE 2500.75 TO ACCT-BALANCE
   12 >            CALL "SHOWACCT" USING ACCT-REC
   13 |            GOBACK.
   14 | <EOF>
[exit status 1]

The listing shows COPY ACCTREC expanded line by line, marked C. Without -I copylib one missing copybook made five errors and exit status 1, the local counterpart of a severe compile. On z/OS, compiler options come from the installation defaults, the PARM of the compile step’s EXEC statement and PROCESS or CBL statements in the source; IBM ranks the source statements above the PARM. Locally they are cobc flags, and two compiler optionscompiler option: A setting such as TRUNC or SSRANGE that changes how the compiler builds a program. On z/OS it comes from the installation defaults, the compile step's PARM or a PROCESS statement in the source. change results:

• TRUNC decides how a binary item is cut when a value has more digits than its PICTURE. A z/OS build and a local build with different TRUNC settings can print different numbers from the same program and data.
• SSRANGE adds checks that stop a subscript or reference outside a table or a field. A program built without SSRANGE carries on past such a reference without a message.

Utility steps create, copy, sort and catalog the data sets

Many jobs have utility steps around their COBOL steps, and four IBM programs cover the common work:

Utility steps take their orders from DD statements and control statements, not from code, so reading a job means reading those statements. Choosing one is choosing by the work: IEFBR14 to create or delete, IEBGENER to copy, the sort to put records in order, and IDCAMS for VSAM data sets and the catalog.

Practise: builds, return codes and utilities

These questions use IGYWCL, the build session and the four utility programs.

Compiler options that change results, reproduced with cobc Pro: opens with a Pro, Premium or Ultimate pass

Utility steps line by line: IEFBR14, IEBGENER, the sort and IDCAMS Pro: opens with a Pro, Premium or Ultimate pass

Interview questions

A warm-up answered in full, then three questions about builds and utility steps that misled their owners:

Key takeaways

• IGYWC compiles, IGYWCL also link-edits and IGYWCLG also runs; the caller supplies SYSIN and SYSLIB, and the link-edit is bypassed only after a compile return code over 8.
• cobc -c compiles and cobc -x links, -I plays SYSLIB and -t writes the listing; z/OS takes options from defaults, the EXEC PARM and PROCESS or CBL statements.
• IEFBR14, IEBGENER, SORT and IDCAMS do their work through DD and control statements.