COPY Books

COBOL 3.1 · ✓ verified by execution on 2026-08-16

A copybook is a reusable file containing COBOL source code that can be inserted into a program at compile time. They are the backbone of COBOL development, ensuring that record layouts and common routines stay consistent across hundreds of programs.

How the COPY Statement Works

The COPY statement tells the compiler to literally include the text from another file directly into your source code before compilation begins.

Here is a basic example of using a COPY statement to include a copybook called screenio:

ID DIVISION.
       PROGRAM-ID. MAIN.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       COPY screenio.
       PROCEDURE DIVISION.
           DISPLAY 'RED IS: ' COB-COLOR-RED.
           STOP RUN.

Output

RED IS: 4

Your output

You can optionally enclose the copybook name in quotes, and you can explicitly specify the file extension like .cpy.

Predict the output cobol

Read the code. What exactly will it print? Commit to an answer before you look.

ID DIVISION.
       PROGRAM-ID. MAIN.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       COPY "screenio".
       PROCEDURE DIVISION.
           DISPLAY 'BLUE: ' COB-COLOR-BLUE.
           STOP RUN.

Output

BLUE: 1

You predicted

If the copybook does not exist, the compiler will raise an error and halt compilation immediately.

The REPLACING Clause

Unlike simple file inclusion mechanisms in other languages, COBOL’s COPY statement has a powerful REPLACING clause. This allows you to perform textual substitution on the copybook’s contents as they are being inserted into your program.

ID DIVISION.
       PROGRAM-ID. MAIN.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       COPY screenio REPLACING ==COB-COLOR-RED== BY ==MY-RED==.
       PROCEDURE DIVISION.
           DISPLAY 'MY-RED IS: ' MY-RED.
           STOP RUN.

Output

MY-RED IS: 4

Your output

This is incredibly useful when you want to use the same copybook structure for multiple variables without causing a naming conflict. For instance, you could copy an address layout twice, once replacing ADDR- with HOME-ADDR- and once replacing it with WORK-ADDR-.

The Notorious Missing Period

A crucial and often-missed rule about the COPY statement is that it must be terminated with a period. If you omit the period, the compiler will complain with a syntax error, and it might manifest in confusing ways.

ID DIVISION.
       PROGRAM-ID. MAIN.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       COPY screenio
       PROCEDURE DIVISION.
           STOP RUN.

This example raises an error (on purpose)

syntax

Your output

You will get an opportunity to fix this exact error in the challenges below!

Case Sensitivity on UNIX

When you are compiling COBOL on a UNIX or Linux system (like you are doing right now), the COPY statement is entirely case-sensitive. The name of the copybook specified in your code must perfectly match the filename on the system. If your file is named screenio.cpy, a COPY SCREENIO statement will completely fail to locate it.

Edge Cases

Nested COPY Statements: You can use a COPY statement inside another copybook, provided there are no circular dependencies.
Partial Replacements: The REPLACING clause is capable of changing partial words or prefixes, which requires careful use of the == delimiters.

Check yourself

What does the COPY statement actually do when your program is compiled?

Reveal answer

It includes the code at compile time — COPY statements are resolved entirely at compile time. The copybook contents are literally inserted into the source code before compilation begins.

Which punctuation mark is absolutely mandatory at the end of every COPY statement?

Reveal answer

A period — A period is absolutely mandatory at the end of every COPY statement, even if it interrupts another statement like an IF.

Why is COBOL's COPY statement more powerful than a simple file inclusion like

Reveal answer

It can edit the imported code on the fly — Unlike basic include mechanisms, COBOL's COPY statement has a REPLACING clause that can edit the imported source code on the fly as it is being copied.

Is the COPY statement case-sensitive when you are compiling on a UNIX system?

Reveal answer

Yes, the casing must exactly match the filename — The COPY statement is case-sensitive on UNIX systems, so the casing in the code must exactly match the filename.

Challenges

🐞 Bug Hunt +20 XP

Bug Hunt: This program tries to use a COPY statement, but it is missing the mandatory period at the end of the COPY statement. Fix it to make it compile!

This code runs. It just does the wrong thing. Read it, find the defect, fix it — the tests below decide when you are right.

COBOL has no in-browser runtime, so this one is pen-and-paper: work out what the fixed code should be, then open the solution and compare. The expected output below is real — it came from compiling the solution with GnuCOBOL when this page was built.

Test 1 — expects "BLUE: 1"

Need a hint? (−25% XP)

Try looking closely at the end of the COPY statement.

Show solution (0 XP)

       ID DIVISION.
       PROGRAM-ID. MAIN.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       COPY screenio.
       PROCEDURE DIVISION.
           DISPLAY 'BLUE: ' COB-COLOR-BLUE.
           STOP RUN.

Challenge 2 +20 XP

Bug Hunt: This program tries to replace COB-COLOR-RED with ADMIN-RED using COPY REPLACING, but the syntax is wrong. Fix it!

Test 1 — expects "ADMIN-RED: 4"

Need a hint? (−25% XP)

Try looking closely at the end of the COPY statement.

Show solution (0 XP)

       ID DIVISION.
       PROGRAM-ID. MAIN.
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       COPY screenio REPLACING ==COB-COLOR-RED== BY ==ADMIN-RED==.
       PROCEDURE DIVISION.
           DISPLAY 'ADMIN-RED: ' ADMIN-RED.
           STOP RUN.