A control-break report

Most batch reports are a list of records with a total whenever a key changes: sales by region, hours by employee, stock by warehouse. The pattern is called a control break, it is older than most of the languages around it, and it has one hard requirement: the file is sorted on the key the report breaks on.

Every program on this page writes its own input file first, so the whole example is one file you can build and run.

A break on a sorted key

The program keeps the previous key and the running subtotal, and it compares the key of the record it has just read with the one it saved. When they differ, the subtotal of the group that just ended is printed and the new group starts:

IDENTIFICATION DIVISION. PROGRAM-ID. BRK1. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT SALES-F ASSIGN TO "sales1.dat" ORGANIZATION IS LINE SEQUENTIAL FILE STATUS IS WS-STATUS. DATA DIVISION. FILE SECTION. FD SALES-F. 01 SALES-REC. 05 REGION PIC X(2). 05 AMOUNT PIC 9(5). WORKING-STORAGE SECTION. 01 WS-STATUS PIC XX. 01 WS-EOF PIC X VALUE "N". 01 WS-PREV PIC X(2). 01 WS-SUB PIC 9(7) VALUE 0. 01 WS-GRAND PIC 9(7) VALUE 0. PROCEDURE DIVISION. OPEN OUTPUT SALES-F. MOVE "N1" TO REGION. MOVE 100 TO AMOUNT. WRITE SALES-REC. MOVE 250 TO AMOUNT. WRITE SALES-REC. MOVE "N2" TO REGION. MOVE 40 TO AMOUNT. WRITE SALES-REC. MOVE "S1" TO REGION. MOVE 500 TO AMOUNT. WRITE SALES-REC. MOVE 25 TO AMOUNT. WRITE SALES-REC. CLOSE SALES-F. OPEN INPUT SALES-F. PERFORM READ-NEXT. MOVE REGION TO WS-PREV. MOVE AMOUNT TO WS-SUB. ADD AMOUNT TO WS-GRAND. PERFORM READ-NEXT. PERFORM UNTIL WS-EOF = "Y" IF REGION = WS-PREV ADD AMOUNT TO WS-SUB ELSE PERFORM PRINT-BREAK MOVE REGION TO WS-PREV MOVE AMOUNT TO WS-SUB END-IF ADD AMOUNT TO WS-GRAND PERFORM READ-NEXT END-PERFORM. PERFORM PRINT-BREAK. DISPLAY "grand total " WS-GRAND. CLOSE SALES-F. STOP RUN. READ-NEXT. READ SALES-F AT END MOVE "Y" TO WS-EOF END-READ. PRINT-BREAK. DISPLAY "region " WS-PREV " subtotal " WS-SUB.

cobc -x -free -Wall -o brk1 brk1.cob
./brk1

region N1 subtotal 0000350
region N2 subtotal 0000040
region S1 subtotal 0000525
grand total 0000915

Three groups, three subtotals, one grand total, and the totals add up: 350 + 40 + 525 is 915. The last PERFORM PRINT-BREAK after the loop is the break the end of the file would otherwise swallow, which is the mistake this pattern exists to avoid.

The priming read

The first record of the file is read before the loop, and the loop compares the next record with it. That is why the pattern needs no test for "is this the first record": the first group is opened by hand and every other group is opened by a break. A loop that reads first and compares afterwards has to ask the question on every pass, and it prints an empty group at the start if it gets the answer wrong.

The two paragraphs at the end are the other half of the pattern. READ-NEXT is the only read in the program, so the end-of-file test exists once. PRINT-BREAK is the only place a subtotal is printed, so the report has one format to keep right. A control-break report whose breaks are printed in three places is the report whose subtotals disagree.

Two levels of break

A second key inside the first one gives a second level. The file is sorted by region and then by branch, and a change of region is also a change of branch, so the inner break is printed first and the outer one after it:

IDENTIFICATION DIVISION. PROGRAM-ID. BRK2. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT SALES-F ASSIGN TO "sales2.dat" ORGANIZATION IS LINE SEQUENTIAL FILE STATUS IS WS-STATUS. DATA DIVISION. FILE SECTION. FD SALES-F. 01 SALES-REC. 05 REGION PIC X(2). 05 BRANCH PIC X(2). 05 AMOUNT PIC 9(5). WORKING-STORAGE SECTION. 01 WS-STATUS PIC XX. 01 WS-EOF PIC X VALUE "N". 01 WS-PREV-R PIC X(2). 01 WS-PREV-B PIC X(2). 01 WS-SUM-B PIC 9(7) VALUE 0. 01 WS-SUM-R PIC 9(7) VALUE 0. 01 WS-GRAND PIC 9(7) VALUE 0. PROCEDURE DIVISION. OPEN OUTPUT SALES-F. MOVE "N1" TO REGION. MOVE "B1" TO BRANCH. MOVE 100 TO AMOUNT. WRITE SALES-REC. MOVE 50 TO AMOUNT. WRITE SALES-REC. MOVE "B2" TO BRANCH. MOVE 20 TO AMOUNT. WRITE SALES-REC. MOVE "N2" TO REGION. MOVE "B1" TO BRANCH. MOVE 70 TO AMOUNT. WRITE SALES-REC. MOVE "B2" TO BRANCH. MOVE 5 TO AMOUNT. WRITE SALES-REC. MOVE "S1" TO REGION. MOVE "B1" TO BRANCH. MOVE 30 TO AMOUNT. WRITE SALES-REC. MOVE "B2" TO BRANCH. MOVE 40 TO AMOUNT. WRITE SALES-REC. CLOSE SALES-F. OPEN INPUT SALES-F. PERFORM READ-NEXT. MOVE REGION TO WS-PREV-R. MOVE BRANCH TO WS-PREV-B. PERFORM UNTIL WS-EOF = "Y" IF REGION NOT = WS-PREV-R PERFORM PRINT-BRANCH PERFORM PRINT-REGION MOVE 0 TO WS-SUM-B MOVE 0 TO WS-SUM-R MOVE REGION TO WS-PREV-R MOVE BRANCH TO WS-PREV-B ELSE IF BRANCH NOT = WS-PREV-B PERFORM PRINT-BRANCH MOVE 0 TO WS-SUM-B MOVE BRANCH TO WS-PREV-B END-IF END-IF ADD AMOUNT TO WS-SUM-B ADD AMOUNT TO WS-SUM-R ADD AMOUNT TO WS-GRAND PERFORM READ-NEXT END-PERFORM. PERFORM PRINT-BRANCH. PERFORM PRINT-REGION. DISPLAY "grand total " WS-GRAND. CLOSE SALES-F. STOP RUN. READ-NEXT. READ SALES-F AT END MOVE "Y" TO WS-EOF END-READ. PRINT-BRANCH. DISPLAY " branch " WS-PREV-B " subtotal " WS-SUM-B. PRINT-REGION. DISPLAY "region " WS-PREV-R " total " WS-SUM-R.

cobc -x -free -Wall -o brk2 brk2.cob
./brk2

branch B1 subtotal 0000150
branch B2 subtotal 0000020
region N1 total 0000170
branch B1 subtotal 0000070
branch B2 subtotal 0000005
region N2 total 0000075
branch B1 subtotal 0000030
branch B2 subtotal 0000040
region S1 total 0000070
grand total 0000315

The order of the two PERFORMs inside the region branch is the whole design: the branch subtotal belongs to the group that is ending, the region total is printed after it, and both counters are set to zero before the new group takes its first amount. Swap the two, or reset a counter before printing it, and the report is one line short.

Unsorted data, a wrong report

The pattern has no defence against unsorted input. The same records in another order give a report that looks perfectly normal and is wrong:

IDENTIFICATION DIVISION. PROGRAM-ID. BRK3. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT SALES-F ASSIGN TO "sales3.dat" ORGANIZATION IS LINE SEQUENTIAL FILE STATUS IS WS-STATUS. DATA DIVISION. FILE SECTION. FD SALES-F. 01 SALES-REC. 05 REGION PIC X(2). 05 AMOUNT PIC 9(5). WORKING-STORAGE SECTION. 01 WS-STATUS PIC XX. 01 WS-EOF PIC X VALUE "N". 01 WS-PREV PIC X(2). 01 WS-SUB PIC 9(7) VALUE 0. 01 WS-GRAND PIC 9(7) VALUE 0. PROCEDURE DIVISION. OPEN OUTPUT SALES-F. MOVE "N1" TO REGION. MOVE 100 TO AMOUNT. WRITE SALES-REC. MOVE "S1" TO REGION. MOVE 500 TO AMOUNT. WRITE SALES-REC. MOVE "N1" TO REGION. MOVE 250 TO AMOUNT. WRITE SALES-REC. CLOSE SALES-F. OPEN INPUT SALES-F. PERFORM READ-NEXT. MOVE REGION TO WS-PREV. MOVE AMOUNT TO WS-SUB. ADD AMOUNT TO WS-GRAND. PERFORM READ-NEXT. PERFORM UNTIL WS-EOF = "Y" IF REGION = WS-PREV ADD AMOUNT TO WS-SUB ELSE PERFORM PRINT-BREAK MOVE REGION TO WS-PREV MOVE AMOUNT TO WS-SUB END-IF ADD AMOUNT TO WS-GRAND PERFORM READ-NEXT END-PERFORM. PERFORM PRINT-BREAK. DISPLAY "grand total " WS-GRAND. CLOSE SALES-F. STOP RUN. READ-NEXT. READ SALES-F AT END MOVE "Y" TO WS-EOF END-READ. PRINT-BREAK. DISPLAY "region " WS-PREV " subtotal " WS-SUB.

cobc -x -free -Wall -o brk3 brk3.cob
./brk3

region N1 subtotal 0000100
region S1 subtotal 0000500
region N1 subtotal 0000250
grand total 0000850

Two lines for N1, and a reader of the printed report has no way to tell that they belong together. The grand total is still correct, because it does not depend on the order, and that is exactly what makes the fault survive: the numbers a manager adds up are right while the grouping they describe is not.

The cure is in the file, not in the program: the data is sorted before the report step, by SORT or by the job that produced the file. A program that must not trust its input checks the order itself and sets a return code when a key arrives out of sequence.

Exercises

  1. Add a count of the records in each region to the report of brk1.
  2. Make the break print a line only when the subtotal is above zero. Which change in the program does that need?
  3. Delete the final PERFORM PRINT-BREAK of brk1. Which region goes missing from the report, and why that one?
  4. Sort the records of brk3 by hand and run it again. How many lines does the report have now?

Questions

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

  1. What does a control-break report require of its input?

    Answer

    The records are sorted on the key the report breaks on

    Unsorted records produced two N1 subtotals in the third program of the page.

  2. Why is the first record read before the loop?

    Answer

    So the loop can compare each record with one already handled, and the first group needs no special case

    The priming read opens the first group by hand, and every later group is opened by a break.

  3. What is printed after the loop ends?

    Answer

    The break of the last group and the grand total

    The last group has no following record to change the key, so its subtotal is printed after the loop.

  4. In a two-level break, which total is printed first when the region changes?

    Answer

    The subtotal of the branch that is ending

    The inner break closes before the outer one, as the branches of N1 show above the N1 total.

  5. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-PREV PIC X(2) VALUE "AA". 01 W-KEY PIC X(2) VALUE "AA". 01 W-SUB PIC 9(3) VALUE 10. PROCEDURE DIVISION. IF W-KEY NOT = W-PREV DISPLAY "break" ELSE DISPLAY "same " END-IF. ADD 5 TO W-SUB. DISPLAY W-SUB. STOP RUN.

    Answer

    same 015

    The two keys are equal, so no break runs, and the subtotal grows by five.

  6. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q6. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT S-F ASSIGN TO "q6c.dat" ORGANIZATION IS LINE SEQUENTIAL FILE STATUS IS W-S. DATA DIVISION. FILE SECTION. FD S-F. 01 S-REC. 05 S-KEY PIC X(2). 05 S-AMT PIC 9(3). WORKING-STORAGE SECTION. 01 W-S PIC XX. 01 W-EOF PIC X VALUE "N". 01 W-PREV PIC X(2). 01 W-SUB PIC 9(5) VALUE 0. PROCEDURE DIVISION. OPEN OUTPUT S-F. MOVE "AA" TO S-KEY. MOVE 20 TO S-AMT. WRITE S-REC. MOVE 30 TO S-AMT. WRITE S-REC. CLOSE S-F. OPEN INPUT S-F. PERFORM READ-NEXT. MOVE S-KEY TO W-PREV. MOVE S-AMT TO W-SUB. PERFORM READ-NEXT. PERFORM UNTIL W-EOF = "Y" IF S-KEY = W-PREV ADD S-AMT TO W-SUB ELSE DISPLAY W-PREV " " W-SUB MOVE S-KEY TO W-PREV MOVE S-AMT TO W-SUB END-IF PERFORM READ-NEXT END-PERFORM. DISPLAY W-PREV " " W-SUB. STOP RUN. READ-NEXT. READ S-F AT END MOVE "Y" TO W-EOF END-READ.

    Answer

    AA 00050

    Both records carry key AA, so the loop adds them and the final break prints the group.

  7. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q7. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT S-F ASSIGN TO "q7c.dat" ORGANIZATION IS LINE SEQUENTIAL FILE STATUS IS W-S. DATA DIVISION. FILE SECTION. FD S-F. 01 S-REC. 05 S-KEY PIC X(2). WORKING-STORAGE SECTION. 01 W-S PIC XX. 01 W-EOF PIC X VALUE "N". 01 W-PREV PIC X(2). 01 W-N PIC 9 VALUE 0. PROCEDURE DIVISION. OPEN OUTPUT S-F. MOVE "AA" TO S-KEY. WRITE S-REC. MOVE "BB" TO S-KEY. WRITE S-REC. MOVE "AA" TO S-KEY. WRITE S-REC. CLOSE S-F. OPEN INPUT S-F. PERFORM READ-NEXT. MOVE S-KEY TO W-PREV. PERFORM READ-NEXT. PERFORM UNTIL W-EOF = "Y" IF S-KEY NOT = W-PREV ADD 1 TO W-N MOVE S-KEY TO W-PREV END-IF PERFORM READ-NEXT END-PERFORM. DISPLAY W-N. CLOSE S-F. STOP RUN. READ-NEXT. READ S-F AT END MOVE "Y" TO W-EOF END-READ.

    Answer

    2

    The keys change twice, AA to BB and BB back to AA, because the file is not sorted.

  8. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q8. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-REGION PIC X(2) VALUE "N1". 01 W-PREV PIC X(2) VALUE "N2". 01 W-SUB PIC 9(3) VALUE 100. PROCEDURE DIVISION. IF W-REGION NOT = W-PREV DISPLAY "region " W-PREV " " W-SUB END-IF. STOP RUN.

    Answer

    region N2 100

    The keys differ, so the break prints the group that is ending, which is the saved key.

  9. A report prints its subtotal in three different paragraphs. What is the risk?

    Answer

    The formats and the counters drift apart, and the subtotals disagree

    One paragraph per break keeps one place responsible for the format and the reset.

  10. Why can an unsorted report look correct to the reader who checks only the totals?

    Answer

    The grand total does not depend on the order, only the grouping does

    The third program printed a correct grand total of 850 and a wrong pair of N1 lines.

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