Capstone B: the indexed customer file

Capstone A ended with a report over a file that is read once. Capstone B is the other shape: a file that is found, changed and written back, one record at a time. The fixed-width customer data becomes an indexed file with an account balance, and the next lesson posts transactions to it.

The record and the key

The indexed record has the four fields of the customer layout and a balance, which the fixed-width file does not have. The balance is S9(9)V99: signed, because an account can be overdrawn, and with two decimals because it is money.

position length field picture 1 6 IDX-ID X(6) the record key 7 20 IDX-NAME X(20) 27 2 IDX-REGION X(2) 29 11 IDX-BALANCE S9(9)V99 sign and nine digits

The key is the id, and the file keeps its own copy of it in an index. That copy is why a READ by key costs the same whether the file holds six records or six million, and why a REWRITE cannot change the key of a record: the index would have to be rebuilt around it. The lesson on indexed files has the mechanics; this page uses them.

The build program

IDENTIFICATION DIVISION. PROGRAM-ID. BUILDIDX. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT TXT-F ASSIGN TO "customers.dat" ORGANIZATION IS LINE SEQUENTIAL FILE STATUS IS WS-TXT-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 TXT-F. 01 TXT-REC. 05 T-ID PIC X(6). 05 T-NAME PIC X(20). 05 T-REGION PIC X(2). 05 T-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-TXT-STATUS PIC XX. 01 WS-IDX-STATUS PIC XX. 01 WS-EOF PIC X VALUE "N". 01 WS-SEED-LINE PIC X(37). 01 WS-WRITTEN PIC 9(2) VALUE 0. 01 WS-SKIPPED PIC 9(2) VALUE 0. 01 WS-SEEN PIC 9(2) VALUE 0. PROCEDURE DIVISION. MAIN-PARA. OPEN INPUT TXT-F IF WS-TXT-STATUS = "35" PERFORM SEED-DATA END-IF CLOSE TXT-F OPEN INPUT TXT-F OPEN OUTPUT IDX-F DISPLAY "building customers.idx " WS-IDX-STATUS PERFORM UNTIL WS-EOF = "Y" READ TXT-F AT END MOVE "Y" TO WS-EOF NOT AT END PERFORM COPY-RECORD END-READ END-PERFORM CLOSE TXT-F CLOSE IDX-F DISPLAY "written " WS-WRITTEN " skipped " WS-SKIPPED PERFORM LIST-INDEX STOP RUN. SEED-DATA. OPEN OUTPUT TXT-F MOVE "C00001Ada Lovelace N1000123456" TO WS-SEED-LINE WRITE TXT-REC FROM WS-SEED-LINE MOVE "C00002Grace Hopper N1000234567" TO WS-SEED-LINE WRITE TXT-REC FROM WS-SEED-LINE MOVE "C00003Alan Turing S2000045678" TO WS-SEED-LINE WRITE TXT-REC FROM WS-SEED-LINE MOVE "C00004Katherine Johnson S2000567890" TO WS-SEED-LINE WRITE TXT-REC FROM WS-SEED-LINE MOVE "C00005Edsger Dijkstra E3000078901" TO WS-SEED-LINE WRITE TXT-REC FROM WS-SEED-LINE MOVE "C00006Barbara Liskov E3000123456" TO WS-SEED-LINE WRITE TXT-REC FROM WS-SEED-LINE CLOSE TXT-F. COPY-RECORD. IF T-AMOUNT IS NOT NUMERIC ADD 1 TO WS-SKIPPED EXIT PARAGRAPH END-IF MOVE T-ID TO IDX-ID MOVE T-NAME TO IDX-NAME MOVE T-REGION TO IDX-REGION MOVE T-AMOUNT TO IDX-BALANCE WRITE IDX-REC INVALID KEY DISPLAY "write " T-ID " duplicate " WS-IDX-STATUS ADD 1 TO WS-SKIPPED EXIT PARAGRAPH END-WRITE ADD 1 TO WS-WRITTEN DISPLAY "write " T-ID " " WS-IDX-STATUS. LIST-INDEX. MOVE "N" TO WS-EOF OPEN INPUT IDX-F PERFORM UNTIL WS-EOF = "Y" READ IDX-F NEXT AT END MOVE "Y" TO WS-EOF NOT AT END ADD 1 TO WS-SEEN DISPLAY "read " IDX-ID " " FUNCTION TRIM(IDX-REGION) " " IDX-BALANCE END-READ END-PERFORM CLOSE IDX-F DISPLAY "records " WS-SEEN.

Above the listing stand IDENTIFICATION DIVISION. and PROGRAM-ID. BUILDIDX.. Three parts of it are the lesson. COPY-RECORD checks the amount with IS NOT NUMERIC before it writes anything, because the fixed-width file can hold a short line and the indexed record cannot hold a bad number. The WRITE has an INVALID KEY branch that reports a duplicate id and counts it as skipped rather than letting the status pass. And LIST-INDEX reads the file back with READ ... NEXT, which is the only way to see the order the index chose.

The run

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

building customers.idx 00
write C00001 00
write C00002 00
write C00003 00
write C00004 00
write C00005 00
write C00006 00
written 06 skipped 00
read C00001 N1 +000001234.56
read C00002 N1 +000002345.67
read C00003 S2 +000000456.78
read C00004 S2 +000005678.90
read C00005 E3 +000000789.01
read C00006 E3 +000001234.56
records 06
0

Every status is 00, which is what a successful write to a file with no duplicates returns. The six reads come back in key order, and the key order is the order of the ids, not the order the records were written in; here the two happen to be the same, which is a property of the sample data and not of the file.

Key order on the way out

To see the difference, write the same records in another order. The ACCESS MODE IS DYNAMIC declaration accepts keys in any order, so a program that writes C00003 first is legal, and the read afterwards still starts at C00001. That is the property a ledger depends on: the order of the input file is not the order of the account file, and a report over the account file is in id order by construction.

The alternate order that matters for capstone B is region, and the index does not provide it. The next lesson posts transactions; the one after that sorts the statement lines by region with SORT, because a control-break report needs the order and the file does not have it.

The file on disk

ls -l customers.idx

-rw-r--r--    1 agent    agent      8192 Nov 18 15:16 customers.idx

Eight kilobytes for six records of thirty-nine bytes: the rest is the index and the block structure the runtime keeps around the data. An indexed file is not a text file and cannot be edited with an editor; the only way in is a program with an FD, which is a cost and also the reason it is hard to corrupt by hand.

A rebuild is always possible from the fixed-width file, and that is the property to keep: the text file is the source of truth, the indexed file is derived. A batch system that can rebuild its master file from the extract is a system whose worst case is a rerun, not a restore.

Exercises

  1. Add ORGANIZATION IS INDEXED with an ALTERNATE KEY IS IDX-REGION and read the file in region order. Which declaration in the SELECT changes?
  2. Write the records in reverse order and list the index again. What does the order of the read tell you about the file?
  3. Make two source lines with the same id and run the build. Which status does the second write return, and what does the program print?
  4. Change IDX-BALANCE to 9(9)V99 and post a negative amount in the next lesson. What happens to the sign?

Questions

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

  1. What does a READ by key cost in an indexed file?

    Answer

    About the same however many records the file holds

    The index holds the key and points at the record.

  2. Why can a REWRITE not change the key?

    Answer

    The index is built around the key and would have to be rebuilt

    The lesson on indexed files shows the status a changed key returns.

  3. What status does a successful WRITE to the index return?

    Answer

    00

    Every write line of the run ends with 00.

  4. Which record does READ NEXT return first?

    Answer

    The one with the lowest key

    The six reads come back C00001 to C00006 in key order.

  5. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 B PIC S9(5)V99 VALUE -12.50. PROCEDURE DIVISION. DISPLAY B. STOP RUN.

    Answer

    -00012.50

    A signed display field keeps the sign and every digit of the picture.

  6. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q6. DATA DIVISION. WORKING-STORAGE SECTION. 01 A PIC 9(3) VALUE 100. 01 B PIC 9(3) VALUE 250. 01 C PIC 9(3). PROCEDURE DIVISION. COMPUTE C = B - A DISPLAY C. STOP RUN.

    Answer

    150

    Two hundred and fifty minus a hundred is a hundred and fifty.

  7. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q7. DATA DIVISION. WORKING-STORAGE SECTION. 01 R. 05 R-ID PIC X(3) VALUE "C01". 05 R-N PIC X(3) VALUE "AB". PROCEDURE DIVISION. DISPLAY LENGTH OF R. STOP RUN.

    Answer

    6

    Three characters of id plus three of name is six.

  8. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q8. DATA DIVISION. WORKING-STORAGE SECTION. 01 T. 05 T-K PIC X OCCURS 3 TIMES. PROCEDURE DIVISION. MOVE "XYZ" TO T. DISPLAY T-K(3) T-K(1). STOP RUN.

    Answer

    ZX

    The third character is Z and the first is X.

  9. Why is the fixed-width file the source of truth and the index derived?

    Answer

    The index can always be rebuilt from the text, so a bad index is a rerun

    The lesson ends on the rebuild property.

  10. What does the INVALID KEY branch on WRITE catch here?

    Answer

    A duplicate key, which the index refuses

    The write branch reports a duplicate id and skips the record.

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 indexed file is the one GnuCOBOL 3.2 writes; its size on this machine is on the page.

Article author: Arthur Isaev