Capstone C: the batch job

The module works; now something has to feed it. The job reads a file of fixed-width requests, turns each one into the record the module expects, calls it, and prints what came back. This is the shape of every batch step that sits in front of a service written by somebody else.

The page shows the job and the module as one file of two programs, so that the listing builds and runs with one command, exactly as printed. In a shop they are two sources, and the build names both: cobc -x job.cob taxcalc.cob. The records are written out in each program here; with COPY "reqans.cpy" they come from the copybook of the previous page, and the compiler reads the same text either way.

The request file

Five requests, fourteen bytes each: version, operation, cents. The file is the one the job writes when it is missing, so the page is one build and one run.

01TAX000010000 01TAX000025000 01NET000050000 02TAX000010000 01XXX000010000

Read as text it is not obviously wrong anywhere, which is the trouble with fixed-width files: the second line has a version of 2 and the fifth has an operation of XXX, and both are only visible when a program applies the contract to them.

The job

The file holds two programs. The first is the job: it seeds requests.dat when it is not there, reads it, parses each fourteen-byte line and calls the module. The second is the module, with the two records in its LINKAGE SECTION:

IDENTIFICATION DIVISION. PROGRAM-ID. TAXJOB. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT REQ-F ASSIGN TO "requests.dat" ORGANIZATION IS LINE SEQUENTIAL FILE STATUS IS WS-REQ-STATUS. DATA DIVISION. FILE SECTION. FD REQ-F. 01 REQ-LINE PIC X(14). WORKING-STORAGE SECTION. 01 WS-REQ-STATUS PIC XX. 01 WS-EOF PIC X VALUE "N". 01 WS-SEED-LINE PIC X(14). 01 WS-OK PIC 9(3) VALUE 0. 01 WS-BAD PIC 9(3) VALUE 0. 01 WS-RESULT PIC 9(9)V99. 01 WS-RESULT-OUT PIC Z(8)9.99. 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. MAIN-PARA. OPEN INPUT REQ-F IF WS-REQ-STATUS = "35" PERFORM SEED-REQUESTS END-IF CLOSE REQ-F OPEN INPUT REQ-F PERFORM UNTIL WS-EOF = "Y" READ REQ-F AT END MOVE "Y" TO WS-EOF NOT AT END PERFORM DO-REQUEST END-READ END-PERFORM CLOSE REQ-F DISPLAY "ok " WS-OK " failed " WS-BAD IF WS-BAD IS GREATER THAN 0 MOVE 4 TO RETURN-CODE END-IF STOP RUN. SEED-REQUESTS. OPEN OUTPUT REQ-F MOVE "01TAX000010000" TO WS-SEED-LINE WRITE REQ-LINE FROM WS-SEED-LINE MOVE "01TAX000025000" TO WS-SEED-LINE WRITE REQ-LINE FROM WS-SEED-LINE MOVE "01NET000050000" TO WS-SEED-LINE WRITE REQ-LINE FROM WS-SEED-LINE MOVE "02TAX000010000" TO WS-SEED-LINE WRITE REQ-LINE FROM WS-SEED-LINE MOVE "01XXX000010000" TO WS-SEED-LINE WRITE REQ-LINE FROM WS-SEED-LINE CLOSE REQ-F. DO-REQUEST. MOVE REQ-LINE(1:2) TO REQ-VERSION MOVE REQ-LINE(3:3) TO REQ-OP MOVE REQ-LINE(6:9) TO REQ-CENTS CALL "TAXCALC" USING REQUEST-REC ANSWER-REC COMPUTE WS-RESULT = ANS-CENTS / 100 MOVE WS-RESULT TO WS-RESULT-OUT IF ANS-STATUS = 0 ADD 1 TO WS-OK DISPLAY "ok " REQ-OP " " REQ-CENTS " cents -> " FUNCTION TRIM(WS-RESULT-OUT) " " FUNCTION TRIM(ANS-MESSAGE) ELSE ADD 1 TO WS-BAD DISPLAY "bad " REQ-OP " " REQ-CENTS " cents -> status " ANS-STATUS " " FUNCTION TRIM(ANS-MESSAGE) END-IF. END PROGRAM TAXJOB. 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.

The call is one statement: CALL "TAXCALC" USING REQUEST-REC ANSWER-REC. The two records are the same twelve lines in the job and in the module, in the order the module USING list names them, and both sides pass them by reference without saying so, which is the default of the language.

Parsing a fixed-width request

The line arrives as PIC X(14) and the fields are cut out of it by position:

MOVE REQ-LINE(1:2) TO REQ-VERSION version MOVE REQ-LINE(3:3) TO REQ-OP operation MOVE REQ-LINE(6:9) TO REQ-CENTS cents, a plain integer

The third move is the safe one because the field it fills is an integer of cents. A move of the same nine characters into a 9(7)V99 would read them as an integer amount and drop the implied decimals, which is exactly the bug the copybook was written to prevent. The lesson that bit a reader once is MOVE rules: the decimal point of a picture is a property of the receiving field, not of the characters.

A real job checks the line before it parses it: fourteen bytes, digits where digits belong, an operation from a list. This one lets the module answer 8 and 9 for the two bad lines, which is the interface doing its job: the module is the one place that knows which versions and operations exist.

The run

cobc -x -free -Wall -o job job.cob
./job
echo $?

ok  TAX 000010000 cents -> 13.00 tax calculated
ok  TAX 000025000 cents -> 32.50 tax calculated
ok  NET 000050000 cents -> 435.00 net after fee
bad TAX 000010000 cents -> status 08 unsupported request version
bad XXX 000010000 cents -> status 09 unknown operation
ok 003 failed 002
4

Three answers and two refusals, status 4. The arithmetic is checkable: thirteen percent of a hundred is thirteen, of two hundred and fifty is thirty-two and a half, and five hundred less the sixty-five cent fee is four hundred and thirty-five.

The refusals are as important as the answers. A version 2 request is a caller from the future: the module says so instead of reading the bytes as if the layout had not changed. An XXX operation is a typo: the module says which. Two different numbers, two different things to fix.

What a real job writes

The job prints because a page is easier to read than a file. A production version writes the answers to a file the next step reads, with the request echoed beside the answer so a reader can check one line without the input file:

01 ANSWER-LINE PIC X(80). 05 AL-REQUEST PIC X(14). 05 AL-STATUS PIC 9(2). 05 AL-CENTS PIC S9(11). 05 AL-MESSAGE PIC X(30).

The echo makes the file twice as wide and worth every byte. A line that fails carries the request that caused it, and a support person does not need three files open to answer the question "what was sent here". The next lesson tests the module directly, without the job and without the file, which is the other half of trusting an interface.

Exercises

  1. Add a request with operation NET and an amount below the fee. What does the module answer, and should it be a failure?
  2. Write the answers to answers.dat with the request echoed. Which paragraph changes, and which FD is needed?
  3. Reject a line that is not fourteen bytes before you parse it. Which status do you give it, and why not 8?
  4. Build the job against TAXCALC.so instead of the source. Which command links it, and what happens if the module is missing at run time?

Questions

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

  1. How does the job pass the records to the module?

    Answer

    CALL "TAXCALC" USING REQUEST-REC ANSWER-REC, by reference

    The call names the two records of the copybook in order.

  2. Why does the parse move nine characters into a field of cents?

    Answer

    The field is an integer, so no implied decimal can differ between the sides

    A 9(7)V99 receiving field would read the digits as an integer amount.

  3. What status does the run return?

    Answer

    4, because two requests were refused

    The trailer says ok 003 failed 002 and the status is 4.

  4. Which two requests were refused?

    Answer

    The version 2 request and the XXX operation

    The statuses 08 and 09 name the two reasons.

  5. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 L PIC X(14) VALUE "01TAX000010000". 01 V PIC 9(2). PROCEDURE DIVISION. MOVE L(1:2) TO V DISPLAY V. STOP RUN.

    Answer

    01

    The first two characters are 01.

  6. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q6. DATA DIVISION. WORKING-STORAGE SECTION. 01 C PIC 9(9) VALUE 25000. 01 R PIC 9(5)V99. PROCEDURE DIVISION. COMPUTE R = C / 100 * 13 / 100 DISPLAY R. STOP RUN.

    Answer

    00032.50

    Two hundred and fifty at thirteen percent is thirty-two and a half.

  7. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q7. DATA DIVISION. WORKING-STORAGE SECTION. 01 A PIC 9(2) VALUE 8. 01 B PIC 9(2) VALUE 9. PROCEDURE DIVISION. IF A NOT = B DISPLAY "different" END-IF. STOP RUN.

    Answer

    different

    Eight is not nine, so the DISPLAY runs.

  8. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q8. DATA DIVISION. WORKING-STORAGE SECTION. 01 S PIC X(4) VALUE "ABCD". 01 P PIC X(2). PROCEDURE DIVISION. STRING S(3:1) S(4:1) DELIMITED BY SIZE INTO P DISPLAY P. STOP RUN.

    Answer

    CD

    Positions three and four are C and D.

  9. Why is the copybook included in WORKING-STORAGE of the job?

    Answer

    The job owns the records it passes; the module borrows them through LINKAGE

    The module declares the same records in LINKAGE SECTION.

  10. How many sources are on the build line?

    Answer

    Two: the job and the module

    cobc -x -o job job.cob taxcalc.cob; the copybook is included, not compiled.

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 job includes reqans.cpy, so its listing starts at the data division; the build command on the page is the real one.

Article author: Arthur Isaev

Banner image