Capstone B: transactions and the statement

The account file exists; now something has to change it. Posting is the same three statements every ledger program in the world uses: READ the record by key, COMPUTE the new balance and REWRITE it. Everything else on the page is about what to do when the read finds nothing.

The transaction file

Five transactions, one per line: an id, a sign and an amount of nine digits with two implied decimals. The sign is a character of its own, and the next section says why.

C00001-000010000 C00002+000005000 C00003+000002550 C00009+000001000 C00004-000050000

Read as a record it is TXN-ID PIC X(6), TXN-SIGN PIC X and TXN-AMOUNT PIC 9(7)V99, sixteen bytes. The amount is unsigned: the sign is the field before it, so the program adds or subtracts on purpose and no negative number is ever stored in a text field.

The posting program

IDENTIFICATION DIVISION. PROGRAM-ID. LEDGER. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT TXN-F ASSIGN TO "txn.dat" ORGANIZATION IS LINE SEQUENTIAL FILE STATUS IS WS-TXN-STATUS. SELECT IDX-F ASSIGN TO "customers.idx" ORGANIZATION IS INDEXED ACCESS MODE IS DYNAMIC RECORD KEY IS IDX-ID FILE STATUS IS WS-IDX-STATUS. DATA DIVISION. FILE SECTION. FD TXN-F. 01 TXN-REC. 05 TXN-ID PIC X(6). 05 TXN-SIGN PIC X. 05 TXN-AMOUNT PIC 9(7)V99. FD IDX-F. 01 IDX-REC. 05 IDX-ID PIC X(6). 05 IDX-NAME PIC X(20). 05 IDX-REGION PIC X(2). 05 IDX-BALANCE PIC S9(9)V99. WORKING-STORAGE SECTION. 01 WS-TXN-STATUS PIC XX. 01 WS-IDX-STATUS PIC XX. 01 WS-EOF PIC X VALUE "N". 01 WS-SEED-LINE PIC X(16). 01 WS-APPLIED PIC 9(3) VALUE 0. 01 WS-UNKNOWN PIC 9(3) VALUE 0. 01 WS-NEW PIC S9(9)V99. 01 WS-AMT-OUT PIC -(7)9.99. 01 WS-BAL-OUT PIC -(9)9.99. 01 WS-STMT-LINE PIC X(70). PROCEDURE DIVISION. MAIN-PARA. OPEN INPUT TXN-F IF WS-TXN-STATUS = "35" PERFORM SEED-TXN END-IF CLOSE TXN-F OPEN INPUT IDX-F OPEN INPUT TXN-F PERFORM UNTIL WS-EOF = "Y" READ TXN-F AT END MOVE "Y" TO WS-EOF NOT AT END PERFORM APPLY-TXN END-READ END-PERFORM CLOSE TXN-F CLOSE IDX-F DISPLAY "applied " WS-APPLIED " unknown " WS-UNKNOWN IF WS-UNKNOWN IS GREATER THAN 0 MOVE 4 TO RETURN-CODE END-IF STOP RUN. SEED-TXN. OPEN OUTPUT TXN-F MOVE "C00001-000010000" TO WS-SEED-LINE WRITE TXN-REC FROM WS-SEED-LINE MOVE "C00002+000005000" TO WS-SEED-LINE WRITE TXN-REC FROM WS-SEED-LINE MOVE "C00003+000002550" TO WS-SEED-LINE WRITE TXN-REC FROM WS-SEED-LINE MOVE "C00009+000001000" TO WS-SEED-LINE WRITE TXN-REC FROM WS-SEED-LINE MOVE "C00004-000050000" TO WS-SEED-LINE WRITE TXN-REC FROM WS-SEED-LINE CLOSE TXN-F. APPLY-TXN. MOVE TXN-ID TO IDX-ID READ IDX-F INVALID KEY ADD 1 TO WS-UNKNOWN DISPLAY "unknown customer " TXN-ID EXIT PARAGRAPH END-READ IF TXN-SIGN = "-" COMPUTE WS-NEW = IDX-BALANCE - TXN-AMOUNT ELSE COMPUTE WS-NEW = IDX-BALANCE + TXN-AMOUNT END-IF MOVE WS-NEW TO IDX-BALANCE REWRITE IDX-REC INVALID KEY DISPLAY "rewrite failed " TXN-ID " " WS-IDX-STATUS EXIT PARAGRAPH END-REWRITE ADD 1 TO WS-APPLIED MOVE TXN-AMOUNT TO WS-AMT-OUT MOVE IDX-BALANCE TO WS-BAL-OUT MOVE SPACES TO WS-STMT-LINE STRING IDX-ID " " FUNCTION TRIM(IDX-NAME) " " TXN-SIGN FUNCTION TRIM(WS-AMT-OUT) " -> " FUNCTION TRIM(WS-BAL-OUT) DELIMITED BY SIZE INTO WS-STMT-LINE END-STRING DISPLAY FUNCTION TRIM(WS-STMT-LINE).

Above the listing stand IDENTIFICATION DIVISION. and PROGRAM-ID. LEDGER.. The file is opened I-O through the same SELECT as the build program, and the balance is now S9(9)V99 so an overdraft is a number and not a wrap-around. APPLY-TXN reads by key, and its INVALID KEY branch is the only place an unknown customer is handled.

Three details in that paragraph are the whole of a posting program. The read sets IDX-BALANCE from the file, so the COMPUTE uses the stored value and not a value from an earlier iteration. The REWRITE writes the same record back and cannot change the key, which is the rule from the previous lesson. And the statement line is built with STRING from edited fields, so the amounts print with a sign and two decimals while the stored fields stay plain numbers.

The run

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

C00001 Ada Lovelace -100.00 -> 1134.56
C00002 Grace Hopper +50.00 -> 2395.67
C00003 Alan Turing +25.50 -> 482.28
unknown customer C00009
C00004 Katherine Johnson -500.00 -> 5178.90
applied 004 unknown 001
4

Four transactions applied, one customer unknown, status 4. The arithmetic is checkable by hand: 1234.56 less 100 is 1134.56, 2345.67 plus 50 is 2395.67, 456.78 plus 25.50 is 482.28, 5678.90 less 500 is 5178.90. Each line starts with the id, so the journal can be sorted, filed and compared with the transaction file it came from.

Why a sign column

A COBOL numeric field in a text file can hold a sign in three ways: an overpunched last digit, a separate leading or trailing character, or a COMP-3 half-byte that no text editor can show. All three are legal in COBOL and all three have caused a batch failure somewhere.

The transaction file here uses the second: the sign is a character of its own and the amount is unsigned. The price is one byte per record and a branch in the program; the gain is that the file can be read, written and checked by anything, including awk and a person with an editor. For a file that arrives from outside the system, that is the right trade. For the account file, which only COBOL touches, the signed S9(9)V99 inside the indexed record is fine.

The third form, packed decimal, is what a mainframe database extract usually holds and what lesson 016 shows. A program that reads such a file needs a conversion step before anything else can read it, and that step is the reason many batch systems have a "file convert" job at the front of the chain.

An unknown customer

C00009 is not in the file, so the READ returns INVALID KEY and the record is not touched. The program prints the id, counts it and returns 4, which is the same warning status the validation step of capstone A used: the run did its work and something needs a person.

The alternative, stopping at the first unknown customer, is the wrong default for a posting job. A file of ten thousand transactions with one bad id would apply nothing, and the rerun after the fix would apply everything from the start. The right shape is to post what can be posted, write the rejects to a file, and return a status that says how many. That is what makes a rerun a rerun and not a redo.

The next lesson takes the balances the run left and turns them into a report by region, which needs the sort the index does not provide.

Exercises

  1. Add a transaction that would overdraft C00005 and run the postings. What does the balance line print, and what does the sign do?
  2. Write the unknown ids to rejects.dat with the amount. Which FD and which OPEN do you need?
  3. Change the transaction file to carry the sign on the amount (S9(7)V99) and remove the sign branch. Which byte of the file changes, and can cat still show it?
  4. Make the program return 8 when more than a tenth of the transactions are unknown. Which status does the sample file produce?

Questions

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

  1. Which three statements post a transaction to an indexed file?

    Answer

    READ, COMPUTE and REWRITE

    APPLY-TXN reads by key, computes the balance and rewrites the record.

  2. What does the INVALID KEY branch of the READ mean here?

    Answer

    No record with that id is in the file

    C00009 is not in the index, so the read finds nothing.

  3. Why is the transaction amount unsigned with a separate sign column?

    Answer

    So the text file can be read and checked by any tool

    The lesson trades one byte and a branch for a readable file.

  4. What is the balance of C00002 after the run?

    Answer

    2395.67

    2345.67 plus 50.00 is 2395.67.

  5. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 A PIC S9(5)V99 VALUE 100.00. 01 B PIC S9(5)V99 VALUE 150.25. 01 C PIC S9(6)V99. PROCEDURE DIVISION. COMPUTE C = A - B DISPLAY C. STOP RUN.

    Answer

    -00050.25

    A hundred less a hundred and fifty and a quarter is minus fifty and a quarter.

  6. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q6. DATA DIVISION. WORKING-STORAGE SECTION. 01 W PIC X(3) VALUE "ABC". 01 N PIC 9(2) VALUE 0. PROCEDURE DIVISION. INSPECT W TALLYING N FOR ALL "A" DISPLAY N. STOP RUN.

    Answer

    01

    The letter A appears once.

  7. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q7. DATA DIVISION. WORKING-STORAGE SECTION. 01 S PIC X(10) VALUE "AB". 01 D PIC X(10). PROCEDURE DIVISION. STRING S "CD" DELIMITED BY SPACE INTO D DISPLAY "[" D "]". STOP RUN.

    Answer

    [ABCD]

    STRING stops at the first space of S, which is after AB, then appends CD.

  8. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q8. DATA DIVISION. WORKING-STORAGE SECTION. 01 A PIC 9(3) VALUE 40. 01 B PIC 9(3) VALUE 5. 01 C PIC 9(4). PROCEDURE DIVISION. COMPUTE C = A * B DISPLAY C. STOP RUN.

    Answer

    0200

    Forty times five is two hundred.

  9. Why return 4 rather than stop at the first unknown customer?

    Answer

    So the good transactions are posted and the rejects are reported

    Stopping would leave a rerun to redo everything.

  10. What does REWRITE do to the key of a record?

    Answer

    Nothing: the key must stay the same or the rewrite is refused

    The index is built around the key, as lesson 077 shows.

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