Capstone B: sort, totals and control breaks
The account file is in id order and the report is by region, so something has to sort it. Capstone B ends with the pipeline that every batch system has somewhere: read a file, release the records into a sort, take them back in a new order, and print the report with a control break.
Why a sort at all
A control-break report needs its records grouped, and grouping is sorting. The indexed file can be read by id, which is the wrong order, and it can be read by an alternate key on region, which would work and would need a second index maintained on every posting. The program takes the third way: one pass over the file, the records into a sort, the sort puts them in region order, and the report reads them in that order.
SORT with an input and an output procedure is the COBOL form of that. The input procedure RELEASEs a record for each one it reads, the runtime sorts the work file, and the output procedure RETURNs them one at a time in the new order:
OPEN INPUT IDX-F
loop: READ IDX-F NEXT, move the fields, RELEASE SRT-REC
SORT SRT-F ON ASCENDING KEY SR-REGION ON ASCENDING KEY SR-ID
loop: RETURN SRT-F, control break on SR-REGION, print
The program
IDENTIFICATION DIVISION.
PROGRAM-ID. PIPELINE.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
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.
SELECT SRT-F ASSIGN TO "stmt.srt".
DATA DIVISION.
FILE SECTION.
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.
SD SRT-F.
01 SRT-REC.
05 SR-REGION PIC X(2).
05 SR-ID PIC X(6).
05 SR-NAME PIC X(20).
05 SR-BALANCE PIC S9(9)V99.
WORKING-STORAGE SECTION.
01 WS-IDX-STATUS PIC XX.
01 WS-EOF PIC X VALUE "N".
01 WS-LAST-REGION PIC X(2) VALUE SPACES.
01 WS-SUBTOTAL PIC S9(11)V99 VALUE 0.
01 WS-GRAND PIC S9(11)V99 VALUE 0.
01 WS-COUNT PIC 9(4) VALUE 0.
01 WS-GROUP-COUNT PIC 9(4) VALUE 0.
01 WS-COUNT-OUT PIC Z(3)9.
01 WS-GROUP-OUT PIC Z(3)9.
01 WS-SUB-OUT PIC -(11)9.99.
01 WS-GRAND-OUT PIC -(11)9.99.
01 WS-BAL-OUT PIC -(9)9.99.
01 WS-DETAIL PIC X(60).
PROCEDURE DIVISION.
MAIN-PARA.
SORT SRT-F
ON ASCENDING KEY SR-REGION
ON ASCENDING KEY SR-ID
INPUT PROCEDURE IS RELEASE-ALL
OUTPUT PROCEDURE IS PRINT-REPORT
MOVE WS-COUNT TO WS-COUNT-OUT
MOVE WS-GROUP-COUNT TO WS-GROUP-OUT
DISPLAY "grand total " FUNCTION TRIM(WS-GRAND-OUT)
" over " FUNCTION TRIM(WS-COUNT-OUT) " customers in "
FUNCTION TRIM(WS-GROUP-OUT) " regions"
STOP RUN.
RELEASE-ALL.
OPEN INPUT IDX-F
IF WS-IDX-STATUS NOT = "00"
DISPLAY "customers.idx missing: run BUILDIDX first" UPON STDERR
MOVE 8 TO RETURN-CODE
STOP RUN
END-IF
PERFORM UNTIL WS-EOF = "Y"
READ IDX-F NEXT
AT END MOVE "Y" TO WS-EOF
NOT AT END
MOVE IDX-REGION TO SR-REGION
MOVE IDX-ID TO SR-ID
MOVE IDX-NAME TO SR-NAME
MOVE IDX-BALANCE TO SR-BALANCE
RELEASE SRT-REC
END-READ
END-PERFORM
CLOSE IDX-F.
PRINT-REPORT.
MOVE "N" TO WS-EOF
PERFORM UNTIL WS-EOF = "Y"
RETURN SRT-F
AT END MOVE "Y" TO WS-EOF
NOT AT END
PERFORM HANDLE-LINE
END-RETURN
END-PERFORM
IF WS-LAST-REGION NOT = SPACES
PERFORM PRINT-BREAK
END-IF
MOVE WS-GRAND TO WS-GRAND-OUT.
HANDLE-LINE.
IF SR-REGION NOT = WS-LAST-REGION
IF WS-LAST-REGION NOT = SPACES
PERFORM PRINT-BREAK
END-IF
MOVE SR-REGION TO WS-LAST-REGION
ADD 1 TO WS-GROUP-COUNT
END-IF
MOVE SR-BALANCE TO WS-BAL-OUT
MOVE SPACES TO WS-DETAIL
STRING SR-ID " " FUNCTION TRIM(SR-NAME) " "
FUNCTION TRIM(WS-BAL-OUT)
DELIMITED BY SIZE INTO WS-DETAIL
END-STRING
DISPLAY " " FUNCTION TRIM(WS-DETAIL)
ADD 1 TO WS-COUNT
ADD SR-BALANCE TO WS-SUBTOTAL
ADD SR-BALANCE TO WS-GRAND.
PRINT-BREAK.
MOVE WS-SUBTOTAL TO WS-SUB-OUT
DISPLAY "region " FUNCTION TRIM(WS-LAST-REGION)
" total " FUNCTION TRIM(WS-SUB-OUT)
MOVE 0 TO WS-SUBTOTAL.
Above the listing stand IDENTIFICATION DIVISION. and PROGRAM-ID. PIPELINE.. The sort file is declared with SD and not FD in the FILE SECTION, which is the one declaration a program that uses a sort must get right: a RELEASE against an FD is a compile error, and the message is RELEASE not allowed on this record item.
The output procedure is the control break of capstone A with the fields changed: SR-REGION is the break key, WS-SUBTOTAL is reset after every printed subtotal, and the line after the loop prints the group that the end of the file would otherwise swallow.
The run without an index
The pipeline depends on a file that another step built, and it says so when the file is not there instead of reading nothing and reporting zero:
rm -f customers.idx
./pipeline
echo $?
customers.idx missing: run BUILDIDX first
8
Status 8 is the one from the batch patterns lesson: a file the job needed was not there. The message names the step that makes it, so the person who reads the scheduler log knows what to run and in which order. A pipeline whose steps say this is a pipeline that can be rerun from the failed step; one that reports "0 customers" is a pipeline that quietly reports nothing for a week.
The report
The three steps in order, each with its status:
./buildidx
./ledger
echo $?
./pipeline
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
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
C00005 Edsger Dijkstra 789.01
C00006 Barbara Liskov 1234.56
region E3 total 2023.57
C00001 Ada Lovelace 1234.56
C00002 Grace Hopper 2345.67
region N1 total 3580.23
C00003 Alan Turing 456.78
C00004 Katherine Johnson 5678.90
region S2 total 6135.68
grand total 11739.48 over 6 customers in 3 regions
0
The status 4 of the ledger does not stop the chain, which is the point of a warning: the transactions that could be posted were posted, and the one unknown id is in the log. A step list that stopped on 4 would never produce the report after a single bad id, and a step list that ignored 8 would report on a file that no longer exists.
The order the sort chose
The report runs E3, N1, S2, not the N1, S2, E3 of the layout lesson. The sort put the regions in the order of the characters: E is less than N and N is less than S. A business reader may expect north first, and that is a report change and not a sort change: a region code that sorts in business order is a code with a leading digit, or the report takes a region table and prints its groups in table order.
The totals agree with capstone A line for line, because the balances are the same six amounts: 2023.57, 3580.23 and 6135.68, and 11739.48 in total. That is not a coincidence to enjoy and forget: it is the check that the two pipelines, one over text and one over an index, agree about the same data. When two reports of the same numbers disagree, one of the two programs has a bug, and the cheaper one to check is the one with the smaller input.
The work file stmt.srt is created by the runtime when the sort starts and removed when it ends; nothing on the page has to clean it up. In a mainframe job the same file is a DD statement, and its size is the thing a job fails on.
Exercises
- Add ON DESCENDING KEY SR-BALANCE after the two ascending keys and print the report. Which line moves, and why does the control break still group the regions?
- Replace the sort with an ALTERNATE KEY IS IDX-REGION on the file and a READ ... NEXT over it. Which program changes, and what does the posting program pay for it?
- Make the pipeline return 8 when a region total is negative, and post a transaction that makes one negative. Which step fails the chain?
- Remove the sort and print the report in id order. How many subtotals does it print, and why is that the bug the sort prevents?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What does the input procedure of a SORT do?
Answer
RELEASEs each record it reads into the sort file
RELEASE-ALL reads the index and releases one record per customer.
-
How must the sort file be declared in the FILE SECTION?
Answer
With SD, not FD
RELEASE against an FD is a compile error.
-
What status does the pipeline return when customers.idx is missing?
Answer
8
The run without an index ends with 8 and names BUILDIDX.
-
Why does the report run E3, N1, S2?
Answer
The sort orders the region codes by character value
E sorts before N and N before S.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 A PIC 9(4)V99 VALUE 100.00. 01 B PIC 9(4)V99 VALUE 250.50. 01 C PIC 9(5)V99. PROCEDURE DIVISION. COMPUTE C = A + B DISPLAY C. STOP RUN.Answer
00350.50
A hundred plus two hundred and fifty and a half is three hundred and fifty and a half.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q6. DATA DIVISION. WORKING-STORAGE SECTION. 01 R PIC X(2) VALUE "N1". 01 L PIC X(2) VALUE "N1". PROCEDURE DIVISION. IF R = L DISPLAY "same group" ELSE DISPLAY "new group" END-IF. STOP RUN.Answer
same group
The saved region equals the current one, so no break is due.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q7. DATA DIVISION. WORKING-STORAGE SECTION. 01 N PIC 9(3) VALUE 3. 01 T PIC 9(6) VALUE 0. 01 I PIC 9(2). PROCEDURE DIVISION. PERFORM VARYING I FROM 1 BY 1 UNTIL I IS GREATER THAN N ADD I TO T END-PERFORM. DISPLAY T. STOP RUN.Answer
000006
One plus two plus three is six.
-
What does this program print?
IDENTIFICATION DIVISION. PROGRAM-ID. Q8. DATA DIVISION. WORKING-STORAGE SECTION. 01 T. 05 T-R PIC X OCCURS 4 TIMES. PROCEDURE DIVISION. MOVE "S2N1" TO T. DISPLAY T-R(1) T-R(2) T-R(3) T-R(4). STOP RUN.Answer
S2N1
The four characters keep their order.
-
Why does status 4 of the ledger not stop the chain?
Answer
The postings that could be applied were applied, and the report can still run
A single unknown id should not stop the report.
-
What proves that capstone A and capstone B agree about the money?
Answer
The two reports print the same subtotals and the same grand total
2023.57, 3580.23, 6135.68 and 11739.48 appear on both pages.
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