Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 38 ยท Subprograms

Copybooks and Nested Programs

Learn how COBOL shares code with COPY and copybooks, customizes them with REPLACING, and structures a run unit with nested programs, GLOBAL and COMMON, EXTERNAL data and CALL conventions.

Two programs that exchange a customer record must agree on every byte of its layout. If each programmer types the description by hand, sooner or later one of them changes it and the other does not. COBOL's answer is the copybook: a source file holding a data description (or code) that the compiler pastes into any program with the COPY statement. This lesson covers copybooks and their REPLACING option, then shows how COBOL can nest one program inside another.

COPY and copybooks

Create a file CUSTREC.cpy:

COBOL
       01  :PFX:-RECORD.
           05  :PFX:-ID        PIC 9(8).
           05  :PFX:-NAME      PIC X(25).
           05  :PFX:-STATE     PIC XX.
           05  :PFX:-BALANCE   PIC S9(7)V99 COMP-3.

Programs then include it where the description belongs:

COBOL
       FILE SECTION.
       FD  CUST-FILE.
           COPY CUSTREC.

The compiler replaces the COPY statement with the text of the file before it does anything else. On the mainframe copybooks live in a partitioned data set named in the compile JCL (SYSLIB), in GnuCOBOL they are searched along the -I include path and COB_COPY_DIR, with the extensions .cpy, .CPY or .cob. A change to the copybook reaches every program at its next compile, so remember to recompile all programs and subprograms that use it. That is why a shared record layout is stored in one place.

REPLACING

Plain COPY produces the same names every time, which is a problem when you need two copies in one program (input and output record, old and new master). REPLACING substitutes text while copying:

COBOL
       FD  OLD-MASTER.
           COPY CUSTREC REPLACING ==:PFX:== BY ==OLD==.
       FD  NEW-MASTER.
           COPY CUSTREC REPLACING ==:PFX:== BY ==NEW==.

The pseudo-text between == and == is replaced as a token sequence. After this you have OLD-RECORD, OLD-ID, NEW-RECORD and NEW-ID. The colons around PFX are just a convention that makes the placeholder stand out and cannot clash with real names.

You can also replace whole phrases, for instance REPLACING ==PIC 9(8)== BY ==PIC 9(10)==, or a table size: ==MAX-LINES== BY ==100==. A standalone REPLACE statement does the same for all the source after it, until REPLACE OFF. Use these sparingly: heavy text substitution makes programs hard to debug because the listing no longer matches the source you read.

flowchart LR
    C["CUSTREC.cpy"] --> P1["Program ORDERS<br/>COPY CUSTREC"]
    C --> P2["Program BILLING<br/>COPY CUSTREC"]
    C --> P3["Subprogram CUSTCHK<br/>COPY CUSTREC in LINKAGE"]

One definition, many programs: the compiler copies the text into each.

Copybooks in the Linkage Section

Copy the layout into the caller's Working-Storage and into the subprogram's LINKAGE SECTION. Then the parameter descriptions cannot drift apart:

COBOL
       LINKAGE SECTION.
           COPY CUSTREC REPLACING ==:PFX:== BY ==LK==.
       PROCEDURE DIVISION USING LK-RECORD.

(See CALL and the Linkage Section for the rules on matching parameters.)

Copybook habits that pay off

  • Keep one record per copybook and give it a name that says what it is.
  • Include a version comment and the record length at the top.
  • Put only data (and perhaps constants) in copybooks; shared logic belongs in a subprogram.
  • For paragraphs shared by programs, a copybook in the Procedure Division works but is a poor substitute for a subprogram.
  • Avoid nesting copybooks more than one level deep; the dependency tree becomes a puzzle.

Nested programs

COBOL-85 introduced nested programs: one program written inside another, separated from it by END PROGRAM. The inner program is hidden from everything outside its container.

COBOL
       IDENTIFICATION DIVISION.
       PROGRAM-ID. REPORTER.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01  WS-TOTAL   PIC 9(5) VALUE 12345.
       PROCEDURE DIVISION.
       MAIN.
           CALL "FORMAT-NUMBER" USING WS-TOTAL
           STOP RUN.

           IDENTIFICATION DIVISION.
           PROGRAM-ID. FORMAT-NUMBER.
           DATA DIVISION.
           LINKAGE SECTION.
           01  LK-NUM    PIC 9(5).
           PROCEDURE DIVISION USING LK-NUM.
               DISPLAY "Total: " LK-NUM
               EXIT PROGRAM.
           END PROGRAM FORMAT-NUMBER.
       END PROGRAM REPORTER.

Rules for nesting:

  • A program may CALL its directly contained programs and any program marked COMMON in a sibling position. A COMMON program can be called by any program in the same container, not only by its parent. A sibling that is not COMMON can be called only by the program that contains it.
  • Names declared as GLOBAL in an outer program (data items, files) are visible to all programs nested inside it. Everything else is local. Without GLOBAL, a nested program cannot see its parent's data.
  • Every program in the nest ends with its own END PROGRAM name.; the outermost one is last.

Nested programs are comparatively rare in mainframe code, where separately compiled subprograms are standard. They suit "private helpers" and appear in code written for GnuCOBOL and Micro Focus.

Sharing data: EXTERNAL and GLOBAL

  • EXTERNAL: 01 SHARED-CTRS EXTERNAL. Several separately compiled programs in the same run unit that declare the same external name (with the same layout) share one storage area, without passing it as a parameter. This is how some systems share counters, a table loaded once, or a file.
  • GLOBAL: a nested-program feature as described above.

Both reduce parameter lists but also hide dependencies: a reader cannot tell from a CALL which data the callee touches. Prefer parameters; use these when many subprograms really need the same big table.

Seeing the substitution

The model below shows COPY ... REPLACING as text substitution on a copybook template, and why two copies in one program need different prefixes.

Python Stand-in: COPY REPLACING as text substitution

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.

Python Stand-in: record length from a copybook (why one 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 first block prints two versions of the record, with OLD- and NEW- names; the last line prints True, which only demonstrates that identical substitutions give identical text, so without different prefixes the second copy would reuse the same names. The second block prints sizes 8, 25, 2 and 5 (a packed 9-digit field takes 5 bytes: nine digits plus a sign nibble, rounded up), for a record length of 40 bytes.

Common mistakes

  1. Recompiling only the program you changed after altering a shared copybook. Subprograms with the old layout silently disagree.
  2. Two copies without REPLACING: duplicate data names or ambiguous references (you can qualify with OF, but it gets ugly).
  3. Copying 01-level items into the middle of a group by accident.
  4. Relying on GLOBAL or EXTERNAL where a parameter would document the dependency.
  5. Missing END PROGRAM lines in a nest, which gives confusing compile errors.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. When is the COPY statement processed?

    COPY is a source-level inclusion done by the compiler's text manipulation phase.
  2. 2. What does COPY CUSTREC REPLACING ==:PFX:== BY ==OLD== do?

    REPLACING performs text substitution during the copy, so OLD-ID, OLD-NAME and so on appear.
  3. 3. How can a nested program see an item of its containing program?

    GLOBAL makes a data item or file visible to the nested programs.
  4. 4. What does the COMMON clause on a nested program allow?

    A COMMON program is callable by sibling programs, not just its direct parent.

Summary

  • A copybook is text shared with COPY; it keeps record layouts identical across programs.
  • REPLACING customizes names or values so one copybook can be used several times.
  • Recompile every program that uses a copybook after you change it.
  • Nested programs hide helpers inside a container; GLOBAL and COMMON control visibility, EXTERNAL shares data across separately compiled programs.

Next: User-defined functions and recursion