COPY and copybooks
A copybook is a file of COBOL source that is not a program: a record description, a set of constants, a table. The compiler inserts it where a COPY statement stands, before it parses anything else. Two programs that COPY the same copybook therefore hold byte-for-byte the same record, which is the whole reason the device exists.
The first and second listings of the page are the copybook and the part of a program that copies it. That part is a fragment on purpose: a program that copies a file is built only when the file sits beside it, and a code block here is one file. The build commands are the real ones, with cusrec.cpy in the same folder as the program, and the third listing is the same program with the record written out, which builds and runs on its own.
A copybook is a file
Save this as cusrec.cpy. It is a level 01 record and nothing else: no division, no section, no period after the last entry that would end something the copybook does not own.
01 CUS-REC.
05 CUS-ID PIC X(3).
05 CUS-NAME PIC X(8).
05 CUS-BAL PIC 9(5).
The program below uses it. Above the fragment stand the two lines every program has, IDENTIFICATION DIVISION. and PROGRAM-ID. CPY., and the copybook file sits beside it:
DATA DIVISION.
WORKING-STORAGE SECTION.
COPY "cusrec.cpy".
PROCEDURE DIVISION.
MOVE "A10" TO CUS-ID.
MOVE "Ada" TO CUS-NAME.
MOVE 1250 TO CUS-BAL.
DISPLAY CUS-ID " " CUS-NAME " " CUS-BAL.
DISPLAY "record is " LENGTH OF CUS-REC " bytes".
STOP RUN.
cobc -x -free -Wall -o cpy cpy.cob
./cpy
A10 Ada 01250
record is 16 bytes
The three fields behave as if they had been written in the program, because they were: the compiler read the copybook text at the place of the COPY and the listing it compiled is the program with that text in it. The record is 16 bytes, 3 + 8 + 5, and LENGTH OF reads it from the copied description.
The COPY statement
COPY takes the name of the member in quotes or as a word, and the statement ends with a period. The text of the member is inserted where the statement is, so a copybook in the FILE SECTION describes the record of an FD, and the same copybook in WORKING-STORAGE describes a record of the program.
A COPY of the same member twice in one program is refused, because the second copy defines the same names again. Two different programs may copy it as often as they like; that is the normal arrangement, and the lesson on CALL and USING uses one copybook for both sides of a call.
The same program written out
A copybook is a convenience for the compiler and not a feature of the running program: the compiler inserts the text where COPY stands, and what it parses is the program with those lines in it. The same program with the record written out is a complete listing that builds with one command and no second file, and it prints the same two lines:
IDENTIFICATION DIVISION.
PROGRAM-ID. CPYPLAIN.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 CUS-REC.
05 CUS-ID PIC X(3).
05 CUS-NAME PIC X(8).
05 CUS-BAL PIC 9(5).
PROCEDURE DIVISION.
MOVE "A10" TO CUS-ID.
MOVE "Ada" TO CUS-NAME.
MOVE 1250 TO CUS-BAL.
DISPLAY CUS-ID " " CUS-NAME " " CUS-BAL.
DISPLAY "record is " LENGTH OF CUS-REC " bytes".
STOP RUN.
cobc -x -free -Wall -o cpyplain cpyplain.cob
./cpyplain
A10 Ada 01250
record is 16 bytes
The two programs differ by one file and by nothing else. That is worth seeing once, because it explains both directions of the device: a copybook saves typing and keeps two programs in step, and it cannot do anything the program could not do by writing the lines itself. When a copybook changes, the programs that copy it change at the next compile and no earlier, which is the property that makes it safe and the property that makes an old binary a liability.
Where the compiler looks
The name in the COPY is a member name, not necessarily a file name: the compiler adds the extensions it knows, so COPY "cusrec" found cusrec.cpy in the same run, with the same output, and COPY "cusrec.cpy" names the file directly.
The compiler looks in the folder of the source file, in its own copy directory and in every -I folder of the command line. The copy directory of this build is the one the install lesson printed with cobc --info: /usr/share/gnucobol/copy. A job that keeps its copybooks outside the folder of the program therefore has two ways to find them: an explicit -I on the command line, or COB_COPY_DIR in the environment. Both were run for this page: with the copybook moved to a subfolder, the build needed -I sub and printed the same two lines.
cobc --info | grep COB_COPY_DIR
COB_COPY_DIR : /usr/share/gnucobol/copy
A record described by a copybook
This is the arrangement of most production COBOL: the record of a file is written once, in a copybook, and every program that reads or writes that file copies it. The program below writes one record and reads it back, and the FD holds nothing but the COPY:
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT CUS-F ASSIGN TO "cus.dat"
ORGANIZATION IS LINE SEQUENTIAL
FILE STATUS IS WS-ST.
DATA DIVISION.
FILE SECTION.
FD CUS-F.
COPY "cusrec.cpy".
WORKING-STORAGE SECTION.
01 WS-ST PIC XX.
PROCEDURE DIVISION.
OPEN OUTPUT CUS-F.
MOVE "A10" TO CUS-ID.
MOVE "Ada" TO CUS-NAME.
MOVE 1250 TO CUS-BAL.
WRITE CUS-REC.
CLOSE CUS-F.
OPEN INPUT CUS-F.
MOVE SPACES TO CUS-REC.
MOVE ZERO TO CUS-BAL.
READ CUS-F
AT END DISPLAY "the file is empty"
NOT AT END DISPLAY "read " CUS-ID " " CUS-NAME " " CUS-BAL
END-READ.
CLOSE CUS-F.
STOP RUN.
cobc -x -free -Wall -o cpy3 cpy3.cob
./cpy3
cat cus.dat
read A10 Ada 01250
A10Ada 01250
The file holds sixteen bytes and no separators, because the record of a copybook is fixed width: A10, Ada padded to eight characters and 01250. The MOVE SPACES and MOVE ZERO before the read are there so that a failed read shows its own emptiness instead of the values the program last wrote.
A COPY of a file that is not there
The member is found at compile time or not at all. A misspelled or missing copybook is an error at the line of the COPY, and every name it was supposed to define becomes undefined as well:
DATA DIVISION.
WORKING-STORAGE SECTION.
COPY "nothere.cpy".
PROCEDURE DIVISION.
MOVE "A10" TO CUS-ID.
DISPLAY CUS-ID.
STOP RUN.
cobc -x -free -Wall -o nocpy nocpy.cob
nocpy.cob:5: error: nothere.cpy: No such file or directory
3 | DATA DIVISION.
4 | WORKING-STORAGE SECTION.
5 > COPY "nothere.cpy".
6 | PROCEDURE DIVISION.
7 | MOVE "A10" TO CUS-ID.
nocpy.cob:7: error: 'CUS-ID' is not defined
The second error is the interesting one: the program never had a CUS-ID, it had a COPY that was supposed to bring one in. A build log with twenty of those lines has one cause, the first line of the log. That is why a build script checks the exit status of the compiler and not the number of messages.
Exercises
- Move the COPY of the first program from WORKING-STORAGE to the FILE SECTION and add an FD. What else has to change?
- Copy cusrec.cpy twice in one program and read the compiler message.
- Put the copybook in a subfolder, build with -I, and say which line changes.
- Add a level 88 to the copybook for a zero balance, and use it in the program without changing the data division of the program.
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What does COPY insert into a program?
Answer
The source text of the member, at the place of the statement
The fields of the copybook were used by name in the procedure division.
-
Which extension does the compiler add to a member name?
Answer
.cpy, so COPY "cusrec" finds cusrec.cpy
The same program with COPY "cusrec" built and printed the same line.
-
Where is a copybook allowed to be used?
Answer
Anywhere the copied text is valid, such as the FILE or WORKING-STORAGE section
The page copied it into WORKING-STORAGE and into an FD record.
-
What is the first error of a COPY of a missing member?
Answer
The member: No such file or directory, at the line of the COPY
The build printed nothere.cpy: No such file or directory before the undefined names.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-REC. 05 W-ID PIC X(3). 05 W-NAME PIC X(8). PROCEDURE DIVISION. MOVE "A10" TO W-ID. MOVE "Ada" TO W-NAME. DISPLAY "[" W-REC "]". STOP RUN.Answer
[A10Ada ]
A group move of the record shows the two fields side by side, the name padded to eight.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q6. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-REC. 05 W-A PIC X(3). 05 W-B PIC 9(5). PROCEDURE DIVISION. DISPLAY LENGTH OF W-REC. STOP RUN.Answer
8
The record is the three characters plus the five digits.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q7. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-REC. 05 W-A PIC X(3). 05 W-B PIC 9(5). PROCEDURE DIVISION. MOVE "A10" TO W-A. MOVE 1250 TO W-B. DISPLAY "[" W-REC "]". STOP RUN.Answer
[A1001250]
The five-digit amount follows the three characters with no separator, exactly as the copybook lays the record out.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q8. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-A PIC X(3) VALUE "A10". 01 W-B PIC X(5) VALUE SPACES. PROCEDURE DIVISION. IF W-A IS EQUAL TO "A10" MOVE "found" TO W-B END-IF. DISPLAY W-B. STOP RUN.Answer
found
The comparison is true, so the three-character literal fills the field.
-
Why is a build log read from its first error?
Answer
A missing copybook leaves every name it should define undefined, so the later errors are one cause
The second error of the failing build was the CUS-ID that the copybook would have declared.
-
Two programs read the same file. What does the copybook give them?
Answer
The same record layout, byte for byte, from one source text
That is the purpose of the device: one description, many programs.
The code on this page was built with cobc (GnuCOBOL) 3.2.0 and run on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev