Capstone C: the copybook interface
Two programs written by two people at two times have to agree about a record. The agreement is the interface, and in COBOL it is a copybook: one file that both include, so the compiler, and not a meeting, is what keeps the two sides the same shape.
The programs on this page are one file with two programs in it, and the two records are written out in each of them rather than copied. A code block on this site is one file, so the listing has to build and run with one command; in a shop the records live in the copybook below, reqans.cpy, and each program says COPY "reqans.cpy" where this listing writes the twelve lines. The compiler inserts the same text either way, and the copybook lesson shows that form.
A contract in bytes
Capstone C is a tax service: a caller sends a request (a version, an operation and an amount in cents) and gets an answer (a version, a status, a result in cents and a message). Four things make it a contract rather than a hope:
- One copybook describes both records and is the only declaration of them.
- The version field says which contract the caller speaks, and the module refuses a version it does not know instead of reading the bytes as if it did.
- The status field is part of the answer, so a caller can branch on a number and not on the text of a message.
- Money crosses the interface as an integer number of cents, so no MOVE can apply a decimal point twice and no COMP-3 assumption can differ between the two sides.
The fourth rule is the one that saves the most time in practice. A fixed-width interface that sends 9(7)V99 as text is read by a MOVE into a numeric field as an integer of those digits, without the implied decimals, so a request for a hundred becomes ten thousand. The capstone project makes the unit explicit in the field name and sends cents.
The copybook
Save this as reqans.cpy, in the folder the compiler searches for copybooks or beside the sources:
01 REQUEST-REC.
05 REQ-VERSION PIC 9(2).
05 REQ-OP PIC X(3).
05 REQ-CENTS PIC 9(9).
01 ANSWER-REC.
05 ANS-VERSION PIC 9(2).
05 ANS-STATUS PIC 9(2).
05 ANS-CENTS PIC S9(11).
05 ANS-MESSAGE PIC X(30).
The request is fourteen bytes: two of version, three of operation and nine of cents. The answer is forty-three: version, status, a signed count of cents with eleven digits, and a thirty-character message. In a project both sides of the interface include this file and neither declares the fields a second time.
The copybook is a fragment: no PROGRAM-ID, no divisions. A code block on this site is one file, and one file cannot be both a program and a copybook that another file includes, so the program below writes these twelve lines out in each of its two programs. That listing builds with one command and is what the run on this page executed; a project with two source files uses COPY instead and compiles the same bytes.
The module and a demo program
The file holds two programs. The first is a demo that calls the module three times: a good request, the same request with a version the module does not know, and a request with an operation it does not know. The second is the module itself, with the two records in its LINKAGE SECTION:
IDENTIFICATION DIVISION.
PROGRAM-ID. TAXDEMO.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 REQUEST-REC.
05 REQ-VERSION PIC 9(2).
05 REQ-OP PIC X(3).
05 REQ-CENTS PIC 9(9).
01 ANSWER-REC.
05 ANS-VERSION PIC 9(2).
05 ANS-STATUS PIC 9(2).
05 ANS-CENTS PIC S9(11).
05 ANS-MESSAGE PIC X(30).
01 WS-RESULT PIC Z(9)9.99.
PROCEDURE DIVISION.
MOVE 1 TO REQ-VERSION
MOVE "TAX" TO REQ-OP
MOVE 10000 TO REQ-CENTS
CALL "TAXCALC" USING REQUEST-REC ANSWER-REC
PERFORM SHOW-ANSWER
MOVE 2 TO REQ-VERSION
CALL "TAXCALC" USING REQUEST-REC ANSWER-REC
PERFORM SHOW-ANSWER
MOVE 1 TO REQ-VERSION
MOVE "XXX" TO REQ-OP
CALL "TAXCALC" USING REQUEST-REC ANSWER-REC
PERFORM SHOW-ANSWER
STOP RUN.
SHOW-ANSWER.
COMPUTE WS-RESULT = ANS-CENTS / 100
DISPLAY "req " REQ-VERSION " " REQ-OP " -> ver " ANS-VERSION
" status " ANS-STATUS " cents " FUNCTION TRIM(WS-RESULT)
" " FUNCTION TRIM(ANS-MESSAGE).
END PROGRAM TAXDEMO.
IDENTIFICATION DIVISION.
PROGRAM-ID. TAXCALC.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 WS-RATE PIC 9V99 VALUE 0.13.
LINKAGE SECTION.
01 REQUEST-REC.
05 REQ-VERSION PIC 9(2).
05 REQ-OP PIC X(3).
05 REQ-CENTS PIC 9(9).
01 ANSWER-REC.
05 ANS-VERSION PIC 9(2).
05 ANS-STATUS PIC 9(2).
05 ANS-CENTS PIC S9(11).
05 ANS-MESSAGE PIC X(30).
PROCEDURE DIVISION USING REQUEST-REC ANSWER-REC.
MOVE 1 TO ANS-VERSION
MOVE 0 TO ANS-CENTS
MOVE SPACES TO ANS-MESSAGE
IF REQ-VERSION NOT = 1
MOVE 8 TO ANS-STATUS
MOVE "unsupported request version" TO ANS-MESSAGE
GOBACK
END-IF
EVALUATE REQ-OP
WHEN "TAX"
COMPUTE ANS-CENTS ROUNDED = REQ-CENTS * WS-RATE
MOVE 0 TO ANS-STATUS
MOVE "tax calculated" TO ANS-MESSAGE
WHEN "NET"
COMPUTE ANS-CENTS = REQ-CENTS - 6500
MOVE 0 TO ANS-STATUS
MOVE "net after fee" TO ANS-MESSAGE
WHEN OTHER
MOVE 9 TO ANS-STATUS
MOVE "unknown operation" TO ANS-MESSAGE
END-EVALUATE
GOBACK.
END PROGRAM TAXCALC.
Above the first program stand IDENTIFICATION DIVISION. and PROGRAM-ID. TAXDEMO.; above the second, PROGRAM-ID. TAXCALC. and END PROGRAM TAXCALC. closes it. The module answers with GOBACK and never STOP RUN, because a subprogram that stops the run ends the caller too.
The status values are three and they are the contract: 0 for an answer, 8 for a request version the module does not know, and 9 for an operation it does not know. A caller that tests only zero and non-zero is a caller that cannot tell "your software is older than mine" from "you sent a typo", and those two need different people to fix them.
The run
cobc -x -free -Wall -o taxdemo taxcalc.cob
./taxdemo
echo $?
req 01 TAX -> ver 01 status 00 cents 13.00 tax calculated
req 02 TAX -> ver 01 status 08 cents 0.00 unsupported request version
req 01 XXX -> ver 01 status 09 cents 0.00 unknown operation
0
Three things are visible in the three lines. The first call answers thirteen per cent of a hundred, in cents. The second carries version 2, and the module refuses it with status 8 instead of reading the bytes as if the layout had not changed. The third carries an operation the module does not know and gets status 9. The ver field is what the module answered in ANS-VERSION, so the caller can log the version it actually talked to.
The module as a file of its own
The same file builds with -m into a shared object, which is how the next two lessons would ship it if the job and the harness were separate programs:
cobc -m -free -Wall -o TAXCALC.so taxcalc.cob
ls -l TAXCALC.so
-rwxr-xr-x 1 agent agent 24328 Nov 18 16:55 TAXCALC.so
The name matters: the runtime finds a module by its PROGRAM-ID at the first CALL, and cobc -m writes a shared object that keeps every entry point of the file. The modules lesson has the search path and the two ways to link a module into an executable.
The version field
A version field is cheap and it is the only thing that lets an interface change without a flag day. The rules this project uses are the smallest set that works:
- The caller sends the version of the contract it was written for, not the version of the module it hopes to find.
- The module answers with the version of the contract it implements, in ANS-VERSION, so a caller can log what it talked to.
- A version the module does not know is a status, not a crash: 8, with a message that names the version.
- Adding a field means a new version and a module that accepts both, not a field appended to the end of the old record.
The next lesson calls this module from a batch job over a file of requests, and the one after that calls it from a test harness with a table of expected answers. Both use the copybook, neither declares the record, and that is the whole of the argument for the interface file.
Exercises
- Add an operation GROSS that adds the fee back. Which of the three files change?
- Make the module answer a version 1 request with ANS-VERSION 2 and see what the job of the next lesson logs. Should the caller trust the field?
- Change the message to twenty characters. What happens to the record length, and which side breaks if only one copybook is edited?
- Build the module without -m and try to call it from a program. Read the runtime message.
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What makes a copybook an interface?
Answer
Both sides include the same file, so one declaration describes both
The caller and the module declare the records only once, in reqans.cpy.
-
Why does the request carry cents and not a decimal amount?
Answer
An integer unit survives every MOVE and every compiler unchanged
A MOVE of 9(7)V99 text into a numeric field drops the implied decimals.
-
What does status 8 mean from TAXCALC?
Answer
The request version is not one the module knows
The module sets 8 for a version other than 1 and 9 for an unknown operation.
-
Why does the module end with GOBACK rather than STOP RUN?
Answer
STOP RUN would end the caller as well
A subprogram returns to its caller.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 C PIC 9(9) VALUE 10000. 01 R PIC 9(7)V99. PROCEDURE DIVISION. COMPUTE R = C / 100 DISPLAY R. STOP RUN.Answer
0000100.00
Ten thousand cents divided by a hundred is a hundred and no cents.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q6. DATA DIVISION. WORKING-STORAGE SECTION. 01 S PIC X(4) VALUE "ABCD". 01 N PIC 9(2). PROCEDURE DIVISION. INSPECT S TALLYING N FOR ALL "B" DISPLAY N. STOP RUN.Answer
01
The letter B appears once.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q7. DATA DIVISION. WORKING-STORAGE SECTION. 01 A PIC 9(2) VALUE 2. 01 B PIC 9(3). PROCEDURE DIVISION. EVALUATE A WHEN 1 MOVE 10 TO B WHEN 2 MOVE 20 TO B WHEN OTHER MOVE 30 TO B END-EVALUATE. DISPLAY B. STOP RUN.Answer
020
A is two, so the second WHEN runs.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q8. DATA DIVISION. WORKING-STORAGE SECTION. 01 M PIC X(8) VALUE "TWO". PROCEDURE DIVISION. DISPLAY LENGTH OF M " " FUNCTION TRIM(M). STOP RUN.Answer
8 TWO
LENGTH OF gives eight and TRIM leaves the three letters.
-
Why is the copybook listing on this page a fragment?
Answer
A code block cannot be both a program and a copybook that another file includes
The builds on the page are the real commands, run by hand.
-
What does the module answer in ANS-VERSION?
Answer
The version of the contract the module implements
The module moves 1 to ANS-VERSION before it does anything else.
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. The module and the two programs of the next lessons were built from the listings on these pages with the commands shown; the copybook cannot live in a single code block, which is why the listings start below the header lines.
Article author: Arthur Isaev