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
- Add a transaction that would overdraft C00005 and run the postings. What does the balance line print, and what does the sign do?
- Write the unknown ids to rejects.dat with the amount. Which FD and which OPEN do you need?
- 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?
- 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.
-
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.
-
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.
-
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.
-
What is the balance of C00002 after the run?
Answer
2395.67
2345.67 plus 50.00 is 2395.67.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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