A copybook-driven interface

A call between two programs is a contract written in bytes: the caller passes an address, the callee reads a layout. A COBOL shop writes that layout once, in a copybook, and both sides copy it, so the contract is a file in version control and not a paragraph in somebody's notes.

The copybook above is how a shop writes that layout once. The programs on this page are one file that holds both of them, with the two records written out in each program rather than copied, because a code block on this site is one file and the page has to build with one command. The copybook lesson shows the COPY form; with COPY "iface.cpy" in place of the twelve lines in each program, the two files build with one command as well, and print the same two lines.

The interface copybook

Two records: the request the caller fills and the answer the callee writes. Both carry the fields a batch interface needs, and the request carries a version so that a callee can refuse a caller it does not understand:

01 IFACE-REQ. 05 IFACE-VERSION PIC 9(2). 05 IFACE-OP PIC X(6). 05 IFACE-AMOUNT PIC 9(7). 01 IFACE-RSP. 05 IFACE-CODE PIC 9(2). 05 IFACE-RESULT PIC 9(9).

Save it as iface.cpy. The request is fifteen bytes, two for the version, six for the operation and seven for the amount, and the answer is eleven. There is no SYNC anywhere: the two sides are both COBOL, and the padding of one compiler is not the padding of another.

The caller and the callee in one file

The first program fills a request, calls the callee and reads the answer; the second checks the version first and the operation second, and writes a code for each failure. The second is a subprogram with a USAGE list, so it cannot be an executable on its own, and the two programs share one file so that one command builds and runs the pair:

IDENTIFICATION DIVISION. PROGRAM-ID. CALLER. DATA DIVISION. WORKING-STORAGE SECTION. 01 IFACE-REQ. 05 IFACE-VERSION PIC 9(2). 05 IFACE-OP PIC X(6). 05 IFACE-AMOUNT PIC 9(7). 01 IFACE-RSP. 05 IFACE-CODE PIC 9(2). 05 IFACE-RESULT PIC 9(9). PROCEDURE DIVISION. MOVE 1 TO IFACE-VERSION. MOVE "DOUBLE" TO IFACE-OP. MOVE 1250 TO IFACE-AMOUNT. CALL "CALLEE" USING IFACE-REQ IFACE-RSP. DISPLAY "code " IFACE-CODE " result " IFACE-RESULT. MOVE 2 TO IFACE-VERSION. CALL "CALLEE" USING IFACE-REQ IFACE-RSP. DISPLAY "code " IFACE-CODE " result " IFACE-RESULT. STOP RUN. END PROGRAM CALLER. IDENTIFICATION DIVISION. PROGRAM-ID. CALLEE. DATA DIVISION. WORKING-STORAGE SECTION. 01 WS-SUPPORTED PIC 9(2) VALUE 1. LINKAGE SECTION. 01 IFACE-REQ. 05 IFACE-VERSION PIC 9(2). 05 IFACE-OP PIC X(6). 05 IFACE-AMOUNT PIC 9(7). 01 IFACE-RSP. 05 IFACE-CODE PIC 9(2). 05 IFACE-RESULT PIC 9(9). PROCEDURE DIVISION USING IFACE-REQ IFACE-RSP. MOVE 0 TO IFACE-CODE. MOVE 0 TO IFACE-RESULT. IF IFACE-VERSION NOT = WS-SUPPORTED MOVE 4 TO IFACE-CODE ELSE EVALUATE IFACE-OP WHEN "DOUBLE" COMPUTE IFACE-RESULT = IFACE-AMOUNT * 2 WHEN OTHER MOVE 8 TO IFACE-CODE END-EVALUATE END-IF. GOBACK. END PROGRAM CALLEE.

cobc -x -free -Wall -o job ifacejob.cob
./job

code 00 result 000002500
code 04 result 000000000

The first program is the main one because it comes first, the second is kept by name because the first calls it, and the linker resolves CALLEE inside the same executable. The first call worked, the second was refused with code 4 because the caller announced version 2 and the callee knows version 1.

In a shop the two programs are two files, each with COPY "iface.cpy" where this listing writes the records, and the build names both: cobc -x caller.cob callee.cob. The bytes are the same, because the copybook is inserted into both before the compiler reads them.

The version field

The version is the cheapest insurance in a batch system. A copybook is shared by programs that are rebuilt on different days, and the one thing that must not happen is a callee reading a record it does not know. The three rules that make the field work are:

  1. The callee checks the version before it uses any other field, and answers with a code instead of doing half the work.
  2. A change to the layout raises the version, in the copybook, in the same commit that changes the callee.
  3. The caller treats an unknown code as a failure of the step, not as a warning, and puts the code in its log.

The codes themselves are part of the contract and belong in the copybook as comments or as level-88 names, so that a program that returns 4 and a program that tests for 4 read the same word for it. The next lesson builds the same interface as separate modules and shows what -m and canned objects add to the picture.

Exercises

  1. Add an operation "HALVE" to the callee and call it from the caller with an odd amount. What does the result look like, and which clause decides it?
  2. Send "DOUBLE" with version 1 and an amount of 9999999. What does the result hold, and why?
  3. Add a field to IFACE-RSP and rebuild only the caller. What does the caller print, and what does the callee write?
  4. Replace both PIC 9(2) codes with level-88 names in the copybook and use them on both sides.

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What makes the copybook an interface?

    Answer

    Both programs copy it, so the bytes of the request and the answer are the same on both sides

    The caller and the callee copied the same file into different sections.

  2. What does the version field of the request do?

    Answer

    It lets the callee refuse a caller whose layout it does not know

    The second call of the page announced version 2 and was refused with code 4.

  3. What does the callee do before it uses the amount?

    Answer

    It clears the answer, checks the version and checks the operation

    The code and the result are set to zero first, and the two checks follow.

  4. Which status did the call with version 2 return?

    Answer

    04, and a result of zero

    The second line of the run is code 04 result 000000000.

  5. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-V PIC 9(2) VALUE 2. 01 W-S PIC 9(2) VALUE 1. 01 W-C PIC 9(2) VALUE 0. PROCEDURE DIVISION. IF W-V NOT = W-S MOVE 4 TO W-C END-IF. DISPLAY W-C. STOP RUN. END PROGRAM Q5.

    Answer

    04

    The versions differ, so the code is set to four.

  6. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q6. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-A PIC 9(7) VALUE 1250. 01 W-R PIC 9(9) VALUE 0. PROCEDURE DIVISION. COMPUTE W-R = W-A * 2 DISPLAY W-R. STOP RUN. END PROGRAM Q6.

    Answer

    000002500

    The nine-digit result holds 2500 with five leading zeros.

  7. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q7. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-OP PIC X(6) VALUE "DOUBLE". PROCEDURE DIVISION. EVALUATE W-OP WHEN "DOUBLE" DISPLAY "doubling" WHEN OTHER DISPLAY "unknown" END-EVALUATE. STOP RUN. END PROGRAM Q7.

    Answer

    doubling

    The operation matches the first branch of the EVALUATE.

  8. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q8. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-N PIC 9 VALUE 1. 01 W-T PIC 9(3) VALUE 0. PROCEDURE DIVISION. PERFORM UNTIL W-N IS GREATER THAN 3 ADD W-N TO W-T ADD 1 TO W-N END-PERFORM. DISPLAY W-T. STOP RUN. END PROGRAM Q8.

    Answer

    006

    The three passes add one, two and three.

  9. Why does the copybook have no SYNC clause?

    Answer

    The two sides must agree byte for byte, and SYNC padding depends on the compiler

    The lesson on SYNC showed the padding the compiler inserts; an interface cannot afford it.

  10. What is the right reaction of the caller to code 8?

    Answer

    A failed step, with the code in the log

    An unknown operation is a defect of the caller and the job should not report success for it.

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