Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 38 ยท Divisions and Data Description

COPY, REPLACING and Copybooks

Share record layouts across programs with COBOL copybooks: the COPY statement, COPY REPLACING pseudo-text, the REPLACE statement, search paths and good copybook practice.

Large COBOL systems have dozens of programs that read and write the same files. If every program retyped the customer record layout, one changed field would mean dozens of edits and, sooner or later, one program that was forgotten. Copybooks solve this: the layout is written once in a separate file and every program pulls it in with COPY.

COPY basics

A copybook is an ordinary text file (usually .cpy or .cbl) holding source lines. COPY name. is replaced by the file's contents before compilation, much like #include in C.

CUSTREC.cpy:

COBOL
       01 CUSTOMER-RECORD.
          05 CUST-ID        PIC 9(6).
          05 CUST-NAME      PIC X(30).
          05 CUST-BALANCE   PIC S9(7)V99.
          05 CUST-STATUS    PIC X.
             88 CUST-ACTIVE VALUE "A".

Program:

COBOL
       DATA DIVISION.
       FILE SECTION.
       FD CUSTOMER-FILE.
           COPY CUSTREC.
       WORKING-STORAGE SECTION.
           COPY ERRCODES.

After the compiler's preprocessing, the program looks exactly as if you had typed those lines. COPY can be used in any division, though layouts (data division) and constants are the most common uses. The COPY statement ends with a period.

Where does the compiler look?

On the mainframe the copybook is a member of a library (a partitioned data set) named in the compile JCL (SYSLIB). With GnuCOBOL:

Terminal
cobc -x -I copybooks payroll.cob

-I dir adds a directory to the search path, and the environment variable COB_COPY_DIR does the same. By default the compiler also tries the extensions .cpy, .CPY, .cbl and .cob.

COPY ... REPLACING

REPLACING edits the copied text on the way in. Replace pseudo-text (delimited by ==) or a single word:

TRANSREC.cpy:

COBOL
       01 :PFX:-RECORD.
          05 :PFX:-ACCOUNT   PIC 9(10).
          05 :PFX:-AMOUNT    PIC S9(7)V99.
COBOL
       WORKING-STORAGE SECTION.
           COPY TRANSREC REPLACING ==:PFX:== BY ==IN==.
           COPY TRANSREC REPLACING ==:PFX:== BY ==OUT==.

The result is two records, IN-RECORD with IN-ACCOUNT and IN-AMOUNT, and OUT-RECORD with OUT-ACCOUNT and OUT-AMOUNT. The colon tags :PFX: are just a convention: the compiler matches the exact text between the == pairs. This is how you get several copies of one layout (an input, an output and a saved previous record) without name clashes.

You can replace several items in one statement:

COBOL
           COPY CUSTREC REPLACING ==CUST-== BY ==OLD-==
                                  ==9(6)==  BY ==9(8)==.

Be careful: replacing CUST- with OLD- changes every occurrence of that text, including inside longer words.

The REPLACE statement

REPLACE works on the whole program text from where it appears, not only on one copybook:

COBOL
           REPLACE ==MAX-ROWS== BY ==500==.
           ...
           REPLACE OFF.

It is a text substitution before compilation. Modern code uses a named constant instead (01 MAX-ROWS CONSTANT AS 500.), which is easier to debug.

A tiny COPY preprocessor (Python stand-in)

This runnable block is Python, not COBOL. It does what the compiler's preprocessor does: replace COPY name. with the file's lines and apply REPLACING.

Python Expand COPY and REPLACING

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.

A copybook is also a size contract (Python stand-in)

Because the same text defines the layout for the writer and the reader of a file, both programs agree on field positions. The next block shows what goes wrong when one program uses an outdated copy.

Python Why one shared layout matters

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 stale reader silently reads the wrong columns. Nothing in COBOL checks that, which is exactly why a single copybook, recompiled into every program that uses it, matters.

Good copybook practice

  • One layout, one copybook; give it a meaningful name (CUSTREC, ERRCODES).
  • Keep copybooks free of logic; they define data and constants.
  • Use prefixes with REPLACING so the same layout can appear twice in a program.
  • Whenever a copybook changes, recompile every program that uses it. Build tools and cross-reference reports help you find them.
  • Do not put 01 level VALUE clauses that only one program needs into a shared copybook.

Common mistakes

  • Forgetting the period after COPY name.
  • A copybook with IDENTIFICATION DIVISION text or unbalanced END-IF.
  • Different case in file names on Linux (custrec.cpy versus CUSTREC.cpy).
  • REPLACING without == delimiters on multi-word text.
  • Modifying a copybook but recompiling only one program.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does COPY CUSTREC. do?

    COPY is a compile-time text inclusion. It does not run when the program runs.
  2. 2. How do you give cobc an extra directory to search for copybooks?

    -I adds a search directory. The COB_COPY_DIR environment variable also works.
  3. 3. What is the purpose of REPLACING ==:PFX:== BY ==IN== on a COPY?

    REPLACING substitutes pseudo-text in the copied lines, so one copybook yields IN-xxx and OUT-xxx names.
  4. 4. After changing a copybook, what must you do?

    The text is expanded at compile time, so each user program must be recompiled.

Summary

  • A copybook holds shared source text; COPY name. pulls it in before compilation.
  • COPY ... REPLACING ==old== BY ==new==. edits the text, so a layout can be reused with different prefixes.
  • REPLACE substitutes text for the rest of the program; named constants are usually cleaner.
  • Tell the compiler where to look (SYSLIB on z/OS, -I or COB_COPY_DIR in GnuCOBOL) and recompile every user after a change.

Next: ACCEPT and DISPLAY