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
- Add a request with operation NET and an amount below the fee. What does the module answer, and should it be a failure?
- Write the answers to answers.dat with the request echoed. Which paragraph changes, and which FD is needed?
- Reject a line that is not fourteen bytes before you parse it. Which status do you give it, and why not 8?
- 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.
-
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.
-
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.
-
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.
-
Which two requests were refused?
Answer
The version 2 request and the XXX operation
The statuses 08 and 09 name the two reasons.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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