Copybooks, COPY, and REPLACE

COPY is a compiler-directing statement: it is not executed, it is processed by the compiler (or a preprocessing phase) which replaces the whole statement, from the word COPY to the closing period, with the text of the library member. In the words of the Language Reference, compiling source that contains COPY statements is logically equivalent to processing all of them first and compiling the resulting text. The general form is:

The rules that matter in practice:

REPLACING changes the library text for this one COPY; the member itself is not modified. Each operand-1 is compared with the library text word by word, in the order written, and the first match is replaced by the corresponding operand-2. A text word is a COBOL word, literal or separator, so matching is always against whole words unless LEADING or TRAILING is used.

Four rules explain nearly every surprise:

The :TAG: convention is the portable way to replace a part of a name. The library text contains a dummy operand delimited by colons (parentheses also work, but colons are recommended because parentheses are used for subscripts), and the COPY replaces the whole delimited word:

The next program copies the Circulation book layout twice with different prefixes (LEADING), the counters twice with different tags, and the member layout with a whole-word and a TRAILING replacement:

It compiles without a warning (also with -std=ibm) and prints:

Source: Enterprise COBOL 6.5 Language Reference: Comparison and replacement examples

Seeing the expanded text removes the guesswork. cobc -E replacing.cob writes the source after COPY and REPLACE have been processed (the listing below is shortened to the first and last copy; cobc -E drops comment lines and compresses blanks, and its #line markers show which file each line came from):

Note that LEADING ==BOOK-== also turned BOOK-RECORD into OLD-RECORD and BOOK-ACTIVE into OLD-ACTIVE: every word that starts with the characters is changed. Both compilers expose the same facility for finding such surprises: GnuCOBOL with -E, Enterprise COBOL with the source listing, where copied lines are marked (z/OS; not run here).

Source: Enterprise COBOL 6.5 Language Reference: Comparison and replacement rules

REPLACE is the same text substitution applied to the program itself, not only to copied text. It is a compiler-directing statement too: it ends with a period and may appear wherever a character string may. A REPLACE statement stays in effect from where it is written until the next REPLACE statement or the end of the separately compiled program. REPLACE OFF. cancels it. The compiler processes COPY first and REPLACE second, so a REPLACE also acts on text that came from a copybook, and a REPLACE cannot contain a COPY. Text produced by a REPLACE must not contain another REPLACE.

The data item MAX-LOANS really exists and holds 5, but while the first REPLACE is active the word is replaced by the literal 3; after REPLACE OFF. it is an ordinary name again. Output of the compiled program (no warnings):

Source: Enterprise COBOL 6.5 Language Reference: REPLACE statement

A constant defined with REPLACE is invisible to the debugger and to the data-name cross-reference, because it never becomes a data item; for values that belong to the program prefer a VALUE clause or a condition name, and keep REPLACE for what really is text. The GnuCOBOL manual also documents REPLACE ALSO, which adds replacements to the ones already in effect instead of discarding them, and REPLACE LAST OFF, which removes the most recent one. The Enterprise COBOL 6.5 Language Reference describes only the plain form and REPLACE OFF, so code meant for both compilers should not use the two extra forms. GnuCOBOL 3.2 accepts them:

Source: GnuCOBOL Programmer’s Guide: REPLACE

Compiler directives such as >>DEFINE and >>IF, which choose which text is compiled, are a different mechanism and are covered in Compiler Directives and Conditional Compilation.

The statement names a member; the environment decides which libraries are searched. The two compilers describe the same idea with different tools.

GnuCOBOL’s own description is that COB_COPY_DIR is the variable that IBM mainframe programmers will recognize as SYSLIB. Its search order for COPY XXXXXXXX. is: the folder named as the library, the folder of the program being compiled, the -I folders, the COBCPY folders, then COB_COPY_DIR. In each folder the names XXXXXXXX.CPY, .CBL, .COB, .cpy, .cbl, .cob and the bare name are tried in that order. Enterprise COBOL, when searching a z/OS UNIX directory for a member that is not written as a literal, tries the extensions .cpy, .CPY, .cbl, .CBL, .cob and .COB with upper and lower case versions of the name. That is why BOOKREC.cpy works for both.

Each of the following was compiled with cobc -x -Wall; the messages are real. The first three are deliberately wrong.

The same copybook twice. Copying LOANREC twice defines LOAN-RECORD and every field twice. GnuCOBOL warns about the redefinition, and any reference to one of the names is then ambiguous. Use REPLACING (as in the example above) to give the second copy other names.

No period after COPY. The next word is taken as part of the statement:

Replacing part of a word. COPY BOOKREC REPLACING ==BOOK== BY ==TITLE==. replaces nothing, because no library word is exactly BOOK, and the compiler says so only when a name is used:

Two more problems are not diagnosed at all. A REPLACING that matches nothing is silent. And on z/OS a copybook edited after a program was compiled does not change the object module: the program keeps the old layout until it is recompiled. Treat a layout change as a change to every program that copies it; the practice is discussed in Coding Standards and Best Practices.

A mainframe copy library is a partitioned data set (PDS) or PDSE, and the utility that copies, merges and reorganizes the members of such data sets is IEBCOPY. A commonly shown job step uses it to build or refresh the copy library, for example copying the members of one library into another with a control statement of the form COPY OUTDD=OUT,INDD=IN (z/OS; not run here). The step only fills the library. It is the SYSLIB DD of the compile step, shown above, that makes the compiler read it: COPY BOOKREC. never mentions IEBCOPY, and a library that no SYSLIB or COPYLOC points to is invisible to the compiler. The utility and its control statements are documented in the DFSMSdfp Utilities manual; the other dataset utilities are covered in Datasets and Mainframe Utilities. Where the book by Tom Taulli presents the IEBCOPY step as "the copy library", read it as the place where members are stored; the compile step is where they are resolved.

Source: z/OS 3.2 DFSMSdfp Utilities (PDF)

The book describes copy members and the library step in the vocabulary of a mainframe compile job and does not cover what changed afterwards. Three things have moved: copy members can now also be searched in z/OS UNIX directories (with cob2, -I and the SYSLIB environment variable) and through COPYLOC, so a copybook no longer has to be a PDS member; the COPY ... REPLACING rules were tightened and documented in detail, including the single-REPLACING-per-chain rule and the partial-word forms; and on a workstation the equivalent of the library is a directory given to cobc -I, with COB_COPY_DIR or COBCPY as the environment form.