Compiling, Linking and Language Environment

Four steps turn the Circulation program LOANCNT (a main program that calls the subprogram FEECALC) into something that can run, and a fifth runs it.

Source: Enterprise COBOL for z/OS 6.5 Programming Guide: Compiling under z/OS; Programming Guide: Compile and link-edit procedure (IGYWCL)

The program object is the current form of the load module. A conventional load module sits in a PDS; a program object needs a PDSE (or a z/OS UNIX file), and the Programming Guide asks for the program object of the COBOL program to be linked into a PDSE in its Java interoperability tasks. The IBM procedure allocates SYSLMOD with DSNTYPE=LIBRARY, which makes a PDSE. This page does not rely on any detail of the binder beyond the Programming Guide; the binder’s own manual (MVS Program Management) defines program objects and the control statements precisely.

IBM supplies three cataloged procedures, in increasing scope:

In IGYWCL the LKED step runs only if the compile ended with a return code of 8 or less (COND=(8,LT,COBOL)), reads SYSLIB from the LE SCEELKEX and SCEELKED libraries, takes the object module from &&LOADSET and writes the result to SYSLMOD. The data set prefixes and some libraries are installation-dependent, so the values above are those of the IBM-supplied procedure, not necessarily those of a site. Calling the procedure and overriding its DDs is the same technique as for any procedure: the DD name is written as step.ddname.

This job compiles LOANCNT with listing options, binds it with the already-compiled FEECALC, and stores the program object in the Circulation load library (z/OS; not run here; the DD names and procedure parameters are checked against the Programming Guide, the binder control statements INCLUDE and NAME are standard binder syntax that this page did not check against the MVS Program Management manual):

Running the result is a separate job step (z/OS; not run here). The STEPLIB makes the program object and the LE run-time libraries visible, CEEOPTS supplies LE options (see Runtime options), and CEEDUMP receives the dump that LE writes after an unhandled error:

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

A batch compilation can hold several programs in one SYSIN. The NAME compiler option decides how they are bound: the compiler writes a binder NAME statement, and every program from one NAME to the next goes into one program object, which takes the name of the last program of the group. The batch must end each program with END PROGRAM, or the next program is nested inside the previous one. Source: Programming Guide: Compiling multiple programs (batch compilation)

A program with EXEC SQL or EXEC CICS statements needs the matching option, because the compiler would otherwise not process them.

Both options are used at compile time only, so they appear in the listing’s "options in effect" section and in the PARM of the compile step, for example PARM.COBOL='SQL("...")'. DYNAM and CICS conflicted until the September 2026 PTF PH73033, which allows the two to be used together; before it, the compiler gave a warning when both were given. The copy of the Programming Guide read for this page still lists the restriction that DYNAM must not be used when programs with EXEC SQL run under CICS or are called by a program that uses the Db2 call attach facility.

Source: Enterprise COBOL for z/OS 6.5 Programming Guide: SQL compiler option; Programming Guide: CICS compiler option; Programming Guide: DYNAM compiler option; What’s new in Enterprise COBOL for z/OS 6.5

How the binder is used depends on how programs call each other. With NODYNAM (the default), a CALL "FEECALC" with a literal is a static call: the object module of FEECALC is bound into the same program object as LOANCNT, as in the job above. With DYNAM, the call is dynamic: FEECALC is a separate program object found at run time through STEPLIB or the link list, and changing it needs no re-bind of the caller. A CALL of a data item always loads the target at run time. For RENT programs (the default) the Programming Guide recommends binding the program object with the RENT binder option (or REUS if non-COBOL serially reusable programs are included); if any program in the object is not reentrant, NOREUS is needed so that CANCEL gives a fresh copy. The language side of CALL, CANCEL and LINKAGE SECTION is on Subprograms: CALL and Linkage; the GnuCOBOL form of the same choice is shown below with cobc -m.

Source: Enterprise COBOL for z/OS 6.5 Programming Guide: RENT compiler option; Programming Guide: DYNAM compiler option

cob2 compiles and links from a z/OS UNIX shell with one command, which is how COBOL fits into make, Git and CI on z/OS. It passes only files that end in .cbl to the compiler (everything else goes to the linker), always adds the RENT and TERM options, writes a requested listing to file.lst, and uses the shell command c89, the shell interface to the binder, for the link step. A few forms (z/OS; not run here, taken from the Programming Guide’s examples with the Circulation names):

The first compiles only (loancnt.o); the second compiles and links two sources into loancnt; the third passes compiler options with -q; the fourth asks for debugging information (-g is TEST with no suboptions) and a copybook directory; the last uses the Db2 coprocessor and writes the DBRM to an existing data set (without a name after -dbrmlib it goes to a .dbrm file). The options that matter most:

PTF PH72005 (July 2026) added, for cob2 and z/OS UNIX: automatic code page conversion of tagged z/OS UNIX input files, UTF-8 files included, when their code page differs from the CODEPAGE option of the compile; the PDS forms of -I; -MF and -MT for -M; paths for input and output files handled like xlc, gcc and clang (a relative path to the source is accepted); and the new TERM(SOURCELINE) option, which prefixes diagnostics sent to the terminal with the source file name and the relative line number. This is the same set of enhancements named on Compilers and Dialects and Mainframe Environment Primer. The OPTFILE option is ignored when compiling with cob2. Whether a given site has applied the PTF is a question for its system programmer.

Source: Enterprise COBOL for z/OS 6.5 Programming Guide: Compiling and linking with the cob2 command; Programming Guide: cob2 syntax and options; What’s new in Enterprise COBOL for z/OS 6.5

The compiler writes its report to SYSPRINT (or to file.lst under cob2). What it contains depends on options, and a listing that was not requested cannot be recovered after the fact, so a production compile saves it:

OFFSET and LIST are mutually exclusive, and if both are given, OFFSET wins. The listing statements EJECT, SKIP1 to SKIP3 and TITLE, and the *CONTROL (*CBL) LIST, MAP and SOURCE switches inside the program, narrow what is printed. A listing, in the order the sections appear, looks like this (a shape only; real listings have a product banner and many more lines):

Under a source line the compiler prints diagnostics in the form nnnnnn IGYppxxxx-l message-text, where nnnnnn is the source line number, IGY marks a compiler message, pp two characters naming the compiler phase (relevant only when reporting a suspected compiler error to IBM), xxxx the message number and l the severity letter. Messages found while processing options, CBL and PROCESS statements and COPY or REPLACE statements appear near the top; messages about the program are ordered by line number near the end; and a summary closes the listing. The severity letter decides the return code of the compile step:

The final return code is generally the highest one met. FLAG(x,y) chooses which messages are printed (default FLAG(I,I): all, embedded in the source listing too), NOCOMPILE(x) stops generating code once a message of severity x or higher occurs (the printed default is NOCOMPILE(S), so a severe error stops code generation), and a message exit (EXIT(MSGEXIT)) lets a site change a message’s severity or suppress it, which changes the return code as well. In cob2, -comprc_ok plays the role of the COND test of IGYWCL: with the default of 4, a warning does not stop the link, an error does. Compiling a program named ERRMSG prints the complete list of messages with their numbers, severities and texts. The runtime messages, with the prefix IGZ and a severity letter, are different: they come from the library at execution time and are shown in the job output, not in the compiler listing. The meanings of both are in the Messages and Codes manual.

Source: Enterprise COBOL for z/OS 6.5 Programming Guide: Format of compiler diagnostic messages; Programming Guide: Severity codes for compiler diagnostic messages; Programming Guide: LIST; Programming Guide: MAP; Programming Guide: XREF; Programming Guide: OFFSET; Enterprise COBOL for z/OS 6.5 Messages and Codes (PDF)

Options are set at several levels, and the higher level wins. For a compile with JCL the order from highest to lowest is: installation defaults that the site has fixed; the values of BUFSIZE, OUTDD, SQL and SQLIMS for the first program of a batch; options on CBL or PROCESS statements before the IDENTIFICATION DIVISION; options on the invocation (the PARM of the step, or cob2 -q); and installation defaults that are not fixed. Two conflicting options at the same level resolve to the last one. A mutually exclusive pair is resolved by a table in the Programming Guide, of which the rows most often met are these: OFFSET forces NOLIST; NUMPROC(PFD) is not allowed together with NUMCHECK(ZON(LAX)); CICS forces LP(32) and RENT; LP(64) forces NOCICS, RENT, NOSMARTBIN and NOTHREAD; TEST forces OBJECT and NODECK. The installation can change every default below, so the reliable way to know the defaults of a site is to compile a program with no options and read "options in effect" in the listing.

The defaults below were taken from the Enterprise COBOL for z/OS 6.5 Programming Guide, page "COBOL compiler options" and the page of each option.

Source: Enterprise COBOL for z/OS 6.5 Programming Guide: COBOL compiler options; ARCH; TUNE; OPTIMIZE; TEST; SSRANGE; NUMCHECK; INITCHECK; TRUNC; NUMPROC; LP; SMARTBIN

Options can also be written in the source with a CBL (or PROCESS) statement before the IDENTIFICATION DIVISION, which is how a program carries the options it must be compiled with; the compiler directives that sit inside the program are on Compiler Directives and Conditional Compilation. An example is CBL OPT(2),SSRANGE,XREF in columns 8 to 72.

Language Environment is the common run time under which Enterprise COBOL, PL/I, C/C++ and assembler routines run on z/OS. The compiler generates calls to it for storage, file and I/O services, DISPLAY, condition handling and the termination of the program, which is why a COBOL program needs the LE libraries (CEE.SCEERUN and SCEERUN2 in the procedures above) when it runs.

GnuCOBOL has the same chain with different names. cobc runs the preprocessor, the parser and the translator to C, then the C compiler, then the linker; the "binder" is the system linker; the program object is an executable (-x) or a shared module (-m); and the run time is libcob, configured by runtime.cfg and by COB_* environment variables. The general picture and cobc -v are in the figure and tables on Getting Started. This section runs each stage on the Circulation programs and shows the output. The subprogram FEECALC prices a late return (0.35 per day, capped at 5.00, as in the fines of Arithmetic and COMPUTE), and the main program LOANCNT counts the day’s transactions and calls it.

The input LOANTRAN is the Circulation transaction file (four lines of the data set of the other pages: three checkouts and a return) placed in a subdirectory data, so that the effect of the file path is visible. Source: GnuCOBOL 3.2 manual