Report Writer: breaks and limits

A report is more than a list of lines: it groups them, totals each group and prints a grand total at the end. The Report Writer does the control break of the previous report lesson by itself, from the list of keys in the RD, and this page shows which parts of that promise this compiler keeps and which it does not.

CONTROL, headings and footings

CONTROLS ARE names the keys of the report from the finest to the coarsest, with FINAL for the grand total. Each key gets a TYPE CONTROL HEADING group that runs when the key changes and a TYPE CONTROL FOOTING group that runs before the change; SUM adds the detail amounts of the group:

IDENTIFICATION DIVISION. PROGRAM-ID. CTL. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT REP-F ASSIGN TO "summary.txt" ORGANIZATION IS LINE SEQUENTIAL FILE STATUS IS WS-ST. DATA DIVISION. FILE SECTION. FD REP-F REPORT IS SALES-REPORT. WORKING-STORAGE SECTION. 01 WS-ST PIC XX. 01 WS-REGION PIC X(2). 01 WS-NAME PIC X(8). 01 WS-AMOUNT PIC 9(5). 01 T-ROWS. 05 T-ROW OCCURS 5 TIMES. 10 T-REGION PIC X(2). 10 T-NAME PIC X(8). 10 T-AMOUNT PIC 9(5). 01 WS-I PIC 9 VALUE 0. REPORT SECTION. RD SALES-REPORT PAGE LIMIT IS 20 LINES HEADING 1 FIRST DETAIL 4 CONTROLS ARE FINAL WS-REGION. 01 TYPE PAGE HEADING. 05 LINE 1 COLUMN 1 PIC X(20) VALUE "SALES BY REGION". 01 TYPE CONTROL HEADING WS-REGION. 05 LINE PLUS 2 COLUMN 1 PIC X(8) VALUE "REGION: ". 05 COLUMN 9 PIC X(2) SOURCE WS-REGION. 01 DETAIL-LINE TYPE DETAIL. 05 LINE PLUS 1 COLUMN 3 PIC X(8) SOURCE WS-NAME. 05 COLUMN 14 PIC 9(5) SOURCE WS-AMOUNT. 01 TYPE CONTROL FOOTING WS-REGION. 05 LINE PLUS 1 COLUMN 3 PIC X(9) VALUE "SUBTOTAL ". 05 COLUMN 14 PIC 9(7) SUM WS-AMOUNT. 01 TYPE CONTROL FOOTING FINAL. 05 LINE PLUS 2 COLUMN 3 PIC X(9) VALUE "TOTAL ". 05 COLUMN 14 PIC 9(7) SUM WS-AMOUNT. PROCEDURE DIVISION. MOVE "N1" TO T-REGION(1). MOVE "apple" TO T-NAME(1). MOVE 250 TO T-AMOUNT(1). MOVE "N1" TO T-REGION(2). MOVE "fig" TO T-NAME(2). MOVE 40 TO T-AMOUNT(2). MOVE "N1" TO T-REGION(3). MOVE "date" TO T-NAME(3). MOVE 75 TO T-AMOUNT(3). MOVE "S1" TO T-REGION(4). MOVE "pear" TO T-NAME(4). MOVE 300 TO T-AMOUNT(4). MOVE "S1" TO T-REGION(5). MOVE "kiwi" TO T-NAME(5). MOVE 500 TO T-AMOUNT(5). OPEN OUTPUT REP-F. INITIATE SALES-REPORT. PERFORM VARYING WS-I FROM 1 BY 1 UNTIL WS-I > 5 MOVE T-REGION(WS-I) TO WS-REGION MOVE T-NAME(WS-I) TO WS-NAME MOVE T-AMOUNT(WS-I) TO WS-AMOUNT GENERATE DETAIL-LINE END-PERFORM. TERMINATE SALES-REPORT. CLOSE REP-F. STOP RUN.

cobc -x -free -Wall -o ctl ctl.cob
./ctl
cat summary.txt

SALES BY REGION


REGION: N1
apple 00250
fig 00040
date 00075
SUBTOTAL 0000365

REGION: S1
pear 00300
kiwi 00500
SUBTOTAL 0000800

TOTAL 0001165

The program never compares a key, never keeps a subtotal and never prints a break. It generates five detail lines in region order and the runtime did the rest: two region headings, two subtotals of 365 and 800, and a grand total of 1165 that is the sum of the subtotals and of the five amounts.

The order requirement is the same as in the hand-written report: the rows went in grouped by region. A GENERATE of a lower region after a higher one would close the higher group and open the lower one again, and the report would show the region twice.

A page footing

TYPE PAGE FOOTING adds lines at the end of every page. With LINE PLUS 1 it follows the last group that printed:

IDENTIFICATION DIVISION. PROGRAM-ID. PFOOT. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT REP-F ASSIGN TO "footer.txt" ORGANIZATION IS LINE SEQUENTIAL FILE STATUS IS WS-ST. DATA DIVISION. FILE SECTION. FD REP-F REPORT IS SALES-REPORT. WORKING-STORAGE SECTION. 01 WS-ST PIC XX. 01 WS-REGION PIC X(2). 01 WS-NAME PIC X(8). 01 WS-AMOUNT PIC 9(5). 01 T-ROWS. 05 T-ROW OCCURS 5 TIMES. 10 T-REGION PIC X(2). 10 T-NAME PIC X(8). 10 T-AMOUNT PIC 9(5). 01 WS-I PIC 9 VALUE 0. REPORT SECTION. RD SALES-REPORT PAGE LIMIT IS 20 LINES HEADING 1 FIRST DETAIL 4 CONTROLS ARE FINAL WS-REGION. 01 TYPE PAGE HEADING. 05 LINE 1 COLUMN 1 PIC X(20) VALUE "SALES BY REGION". 01 TYPE CONTROL HEADING WS-REGION. 05 LINE PLUS 2 COLUMN 1 PIC X(8) VALUE "REGION: ". 05 COLUMN 9 PIC X(2) SOURCE WS-REGION. 01 DETAIL-LINE TYPE DETAIL. 05 LINE PLUS 1 COLUMN 3 PIC X(8) SOURCE WS-NAME. 05 COLUMN 14 PIC 9(5) SOURCE WS-AMOUNT. 01 TYPE CONTROL FOOTING WS-REGION. 05 LINE PLUS 1 COLUMN 3 PIC X(9) VALUE "SUBTOTAL ". 05 COLUMN 14 PIC 9(7) SUM WS-AMOUNT. 01 TYPE CONTROL FOOTING FINAL. 05 LINE PLUS 2 COLUMN 3 PIC X(9) VALUE "TOTAL ". 05 COLUMN 14 PIC 9(7) SUM WS-AMOUNT. 01 TYPE PAGE FOOTING. 05 LINE PLUS 1 COLUMN 1 PIC X(11) VALUE "end of page". PROCEDURE DIVISION. MOVE "N1" TO T-REGION(1). MOVE "apple" TO T-NAME(1). MOVE 250 TO T-AMOUNT(1). MOVE "N1" TO T-REGION(2). MOVE "fig" TO T-NAME(2). MOVE 40 TO T-AMOUNT(2). MOVE "N1" TO T-REGION(3). MOVE "date" TO T-NAME(3). MOVE 75 TO T-AMOUNT(3). MOVE "S1" TO T-REGION(4). MOVE "pear" TO T-NAME(4). MOVE 300 TO T-AMOUNT(4). MOVE "S1" TO T-REGION(5). MOVE "kiwi" TO T-NAME(5). MOVE 500 TO T-AMOUNT(5). OPEN OUTPUT REP-F. INITIATE SALES-REPORT. PERFORM VARYING WS-I FROM 1 BY 1 UNTIL WS-I > 5 MOVE T-REGION(WS-I) TO WS-REGION MOVE T-NAME(WS-I) TO WS-NAME MOVE T-AMOUNT(WS-I) TO WS-AMOUNT GENERATE DETAIL-LINE END-PERFORM. TERMINATE SALES-REPORT. CLOSE REP-F. STOP RUN.

cobc -x -free -Wall -o pfoot pfoot.cob
./pfoot
cat -n footer.txt

1 SALES BY REGION
2
3
4 REGION: N1
5 apple 00250
6 fig 00040
7 date 00075
8 SUBTOTAL 0000365
9
10 REGION: S1
11 pear 00300
12 kiwi 00500
13 SUBTOTAL 0000800
14
15 TOTAL 0001165
16 end of page
17
18
19
20

The footer came out on line 16, right below the grand total, and the rest of the twenty-line page is blank. An absolute LINE NUMBER is accepted by the compiler as well, and the runs behind this page put a footer declared at line 19 on line 20 and one declared at line 2 on line 5 of the second page: the runtime moves a footer to the next page when the groups before it do not fit, so LINE PLUS is the form to write when the position matters.

What 3.2 does not do

Two parts of the Report Writer of the standard are missing here. The first is the declarative that runs code at the start or the end of a report. This program names it, and the compiler reads the name as a file name:

IDENTIFICATION DIVISION. PROGRAM-ID. LIM1. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT REP-F ASSIGN TO "lim1.txt" ORGANIZATION IS LINE SEQUENTIAL FILE STATUS IS WS-ST. DATA DIVISION. FILE SECTION. FD REP-F REPORT IS SMALL-REPORT. WORKING-STORAGE SECTION. 01 WS-ST PIC XX. REPORT SECTION. RD SMALL-REPORT PAGE LIMIT IS 10 LINES HEADING 1. 01 TYPE PAGE HEADING. 05 LINE 1 COLUMN 1 PIC X(5) VALUE "head". PROCEDURE DIVISION. DECLARATIVES. REPORT-DECL SECTION. USE BEFORE REPORTING SMALL-REPORT. REPORT-DECL-P. DISPLAY "before". END DECLARATIVES. OPEN OUTPUT REP-F. INITIATE SMALL-REPORT. TERMINATE SMALL-REPORT. CLOSE REP-F. STOP RUN.

cobc -x -free -Wall -o lim1 lim1.cob

lim1.cob: in section 'REPORT-DECL':
lim1.cob:24: error: 'SMALL-REPORT' is not a field
22 | DECLARATIVES.
23 | REPORT-DECL SECTION.
24 > USE BEFORE REPORTING SMALL-REPORT.
25 | REPORT-DECL-P.
26 | DISPLAY 'before'.

The second missing part is the USAGE of a report field: only display, national and UTF-8 fields are allowed in a line group, so a column cannot borrow the packed format of the data it shows:

IDENTIFICATION DIVISION. PROGRAM-ID. LIM2. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT REP-F ASSIGN TO "lim2.txt" ORGANIZATION IS LINE SEQUENTIAL FILE STATUS IS WS-ST. DATA DIVISION. FILE SECTION. FD REP-F REPORT IS SMALL-REPORT. WORKING-STORAGE SECTION. 01 WS-ST PIC XX. 01 WS-AMOUNT PIC 9(5) VALUE 250. REPORT SECTION. RD SMALL-REPORT PAGE LIMIT IS 10 LINES HEADING 1. 01 TYPE PAGE HEADING. 05 LINE 1 COLUMN 1 PIC X(5) VALUE "head". 01 DETAIL-LINE TYPE DETAIL. 05 LINE PLUS 1 COLUMN 1 PIC 9(5) USAGE COMP-3 SOURCE WS-AMOUNT. PROCEDURE DIVISION. OPEN OUTPUT REP-F. INITIATE SMALL-REPORT. GENERATE DETAIL-LINE. TERMINATE SMALL-REPORT. CLOSE REP-F. STOP RUN.

cobc -x -free -Wall -o lim2 lim2.cob

lim2.cob:23: error: syntax error, unexpected COMP-3, expecting DISPLAY or DISPLAY-1 or NATIONAL or UTF-8
21 | 05 LINE 1 COLUMN 1 PIC X(5) VALUE "head".
22 | 01 DETAIL-LINE TYPE DETAIL.
23 > 05 LINE PLUS 1 COLUMN 1 PIC 9(5) USAGE COMP-3 SOURCE WS-AMOUNT.
24 | PROCEDURE DIVISION.
25 | OPEN OUTPUT REP-F.

Everything else this page used, from CONTROLS ARE to SUM and the page footing, built and ran. A job that needs a packed column or a hook before the report writes it with the verbs of the previous lesson and a hand-made line, which is what the great majority of production COBOL does anyway.

Exercises

  1. Add a fourth column with the count of the detail lines of each region. Which clause gives the count?
  2. Move the rows of ctl so that S1 comes before N1. Which lines of the report change?
  3. Add a second control key to the report, a branch code finer than the region. Which list does the CONTROLS ARE clause take?
  4. Put LINE NUMBER 19 back into the page footing and run cat -n footer.txt. Which line does the footer land on?

Questions

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

  1. Which clause names the keys of a Report Writer report?

    Answer

    CONTROLS ARE, from the finest key to FINAL

    The RD of the page reads CONTROLS ARE FINAL WS-REGION.

  2. What does SUM WS-AMOUNT in a control footing do?

    Answer

    It adds the WS-AMOUNT of the details of the group and shows the total

    The subtotals 365 and 800 are the sums of the rows of each region.

  3. Which group runs when the value of a control key changes?

    Answer

    The control footing of the old group, then the control heading of the new one

    The report printed SUBTOTAL 365 before REGION: S1.

  4. What does TYPE PAGE FOOTING add?

    Answer

    Lines at the end of every page

    The line end of page came out at the foot of the page.

  5. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-A PIC 9(5) VALUE 250. 01 W-B PIC 9(5) VALUE 40. 01 W-S PIC 9(7) VALUE 0. PROCEDURE DIVISION. ADD W-A TO W-S. ADD W-B TO W-S. DISPLAY W-S. STOP RUN.

    Answer

    0000290

    The footing sums the two amounts into a seven-digit field.

  6. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q6. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-KEY PIC X(2) VALUE "N1". 01 W-PREV PIC X(2) VALUE "S1". PROCEDURE DIVISION. IF W-KEY NOT = W-PREV DISPLAY "new group " W-KEY END-IF. STOP RUN.

    Answer

    new group N1

    The keys differ, so the heading of the new group runs.

  7. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q7. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-A PIC 9(3) VALUE 365. 01 W-B PIC 9(3) VALUE 800. 01 W-T PIC 9(4) VALUE 0. PROCEDURE DIVISION. ADD W-A TO W-T. ADD W-B TO W-T. DISPLAY W-T. STOP RUN.

    Answer

    1165

    The grand total of the report is the sum of the two subtotals.

  8. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q8. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-N PIC 9 VALUE 1. PROCEDURE DIVISION. PERFORM UNTIL W-N IS GREATER THAN 3 DISPLAY W-N ADD 1 TO W-N END-PERFORM. STOP RUN.

    Answer

    1 2 3 on three lines

    The loop prints the counter before it adds one, and stops above three.

  9. Which Report Writer feature does this compiler refuse?

    Answer

    USE BEFORE REPORTING, which it reads as a use of a file name

    The build stopped at that line with SMALL-REPORT is not a field.

  10. Why is a packed column not allowed in a report line group?

    Answer

    A report field may only use DISPLAY, DISPLAY-1, NATIONAL or UTF-8

    The error line lists exactly those four usages as what it expects.

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