Report Writer: the basics

The Report Writer describes a printed page instead of writing it. The layout lives in a REPORT SECTION, the program says GENERATE once per record, and the runtime decides where every line goes, when a page ends and what the heading of the next page looks like.

GnuCOBOL 3.2 implements it, so every report on this page came out of a real run, and the page break below is the one the runtime made by itself.

The REPORT SECTION and RD

Three pieces make a report: a file whose FD names a report, a RD entry that says how long a page is and where the body may start, and one or more line groups, each with a TYPE. The output is a plain file of text:

IDENTIFICATION DIVISION. PROGRAM-ID. RWP. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT REP-F ASSIGN TO "paged.txt" ORGANIZATION IS LINE SEQUENTIAL FILE STATUS IS WS-ST. DATA DIVISION. FILE SECTION. FD REP-F REPORT IS LIST-REPORT. WORKING-STORAGE SECTION. 01 WS-ST PIC XX. 01 WS-NAME PIC X(8). 01 WS-AMOUNT PIC 9(5). 01 T-NAMES. 05 T-NAME PIC X(8) OCCURS 6 TIMES. 01 T-AMOUNTS. 05 T-AMT PIC 9(5) OCCURS 6 TIMES. 01 WS-I PIC 9 VALUE 0. REPORT SECTION. RD LIST-REPORT PAGE LIMIT IS 6 LINES HEADING 1 FIRST DETAIL 4. 01 TYPE PAGE HEADING. 05 LINE 1 COLUMN 1 PIC X(10) VALUE "NAME". 05 COLUMN 12 PIC X(8) VALUE "AMOUNT". 01 DETAIL-LINE TYPE DETAIL. 05 LINE PLUS 1 COLUMN 1 PIC X(8) SOURCE WS-NAME. 05 COLUMN 12 PIC 9(5) SOURCE WS-AMOUNT. PROCEDURE DIVISION. MOVE "apple" TO T-NAME(1). MOVE 250 TO T-AMT(1). MOVE "fig" TO T-NAME(2). MOVE 40 TO T-AMT(2). MOVE "pear" TO T-NAME(3). MOVE 300 TO T-AMT(3). MOVE "kiwi" TO T-NAME(4). MOVE 500 TO T-AMT(4). MOVE "date" TO T-NAME(5). MOVE 75 TO T-AMT(5). MOVE "plum" TO T-NAME(6). MOVE 60 TO T-AMT(6). OPEN OUTPUT REP-F. INITIATE LIST-REPORT. PERFORM VARYING WS-I FROM 1 BY 1 UNTIL WS-I > 6 MOVE T-NAME(WS-I) TO WS-NAME MOVE T-AMT(WS-I) TO WS-AMOUNT GENERATE DETAIL-LINE END-PERFORM. TERMINATE LIST-REPORT. CLOSE REP-F. STOP RUN.

cobc -x -free -Wall -o rwp rwp.cob
./rwp
cat -A paged.txt

NAME AMOUNT$
$
$
apple 00250$
fig 00040$
pear 00300$
NAME AMOUNT$
$
$
kiwi 00500$
date 00075$
plum 00060$

cat -A marks the end of each line with a dollar sign, so the twelve lines are visible. The page holds six lines, the heading takes the first, the body starts at line 4, three details fit, and the runtime made a second page with the heading repeated and the body again from line 4. No program statement counted a line or started a page.

INITIATE, GENERATE and TERMINATE

The three verbs are the whole interface. INITIATE takes the report and prepares its pages, GENERATE adds one detail line per call, and TERMINATE finishes the last page and writes what is left. A report that is not initiated has no page to write to, and the runtime stops the program with a message rather than a status:

GENERATE also takes the name of a control footing in the next lesson, and the line group it names must be a TYPE DETAIL for a detail record. The name of the group is the name the program uses: DETAIL-LINE here, not the record of the file.

Columns and data

A field of a line group has a column, a PIC that says how wide it is, and a SOURCE that says which working-storage field it shows. The PIC of the column is independent of the source, so a report can show an amount in a layout the data does not use:

IDENTIFICATION DIVISION. PROGRAM-ID. RWD. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT REP-F ASSIGN TO "sales.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-NAME PIC X(8). 01 WS-AMOUNT PIC 9(5). 01 T-NAMES. 05 T-NAME PIC X(8) OCCURS 3 TIMES. 01 T-AMOUNTS. 05 T-AMT PIC 9(5) OCCURS 3 TIMES. 01 WS-I PIC 9 VALUE 0. REPORT SECTION. RD SALES-REPORT PAGE LIMIT IS 12 LINES HEADING 1 FIRST DETAIL 4. 01 TYPE PAGE HEADING. 05 LINE 1 COLUMN 1 PIC X(12) VALUE "SALES REPORT". 05 LINE 2 COLUMN 1 PIC X(20) VALUE "--------------------". 01 DETAIL-LINE TYPE DETAIL. 05 LINE PLUS 1 COLUMN 1 PIC X(8) SOURCE WS-NAME. 05 COLUMN 12 PIC 9(5) SOURCE WS-AMOUNT. PROCEDURE DIVISION. MOVE "apple" TO T-NAME(1). MOVE 250 TO T-AMT(1). MOVE "fig" TO T-NAME(2). MOVE 40 TO T-AMT(2). MOVE "pear" TO T-NAME(3). MOVE 300 TO T-AMT(3). OPEN OUTPUT REP-F. INITIATE SALES-REPORT. PERFORM VARYING WS-I FROM 1 BY 1 UNTIL WS-I > 3 MOVE T-NAME(WS-I) TO WS-NAME MOVE T-AMT(WS-I) TO WS-AMOUNT GENERATE DETAIL-LINE END-PERFORM. TERMINATE SALES-REPORT. CLOSE REP-F. STOP RUN.

cobc -x -free -Wall -o rwd rwd.cob
./rwd
cat sales.txt

SALES REPORT
--------------------

apple 00250
fig 00040
pear 00300

The heading is two lines because the group says so, the detail body starts at line 4, and LINE PLUS 1 puts each detail one line below the previous one. A column without LINE stays on the line of the previous column of the same group, which is how one row is built out of several fields.

A GENERATE without INITIATE

Remove the INITIATE and the program still builds. The first GENERATE stops the run:

IDENTIFICATION DIVISION. PROGRAM-ID. BADRW. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT REP-F ASSIGN TO "bad.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-NAME PIC X(8). 01 WS-AMOUNT PIC 9(5). 01 T-NAMES. 05 T-NAME PIC X(8) OCCURS 3 TIMES. 01 T-AMOUNTS. 05 T-AMT PIC 9(5) OCCURS 3 TIMES. 01 WS-I PIC 9 VALUE 0. REPORT SECTION. RD SALES-REPORT PAGE LIMIT IS 12 LINES HEADING 1 FIRST DETAIL 4. 01 TYPE PAGE HEADING. 05 LINE 1 COLUMN 1 PIC X(12) VALUE "SALES REPORT". 05 LINE 2 COLUMN 1 PIC X(20) VALUE "--------------------". 01 DETAIL-LINE TYPE DETAIL. 05 LINE PLUS 1 COLUMN 1 PIC X(8) SOURCE WS-NAME. 05 COLUMN 12 PIC 9(5) SOURCE WS-AMOUNT. PROCEDURE DIVISION. MOVE "apple" TO T-NAME(1). MOVE 250 TO T-AMT(1). MOVE "fig" TO T-NAME(2). MOVE 40 TO T-AMT(2). MOVE "pear" TO T-NAME(3). MOVE 300 TO T-AMT(3). OPEN OUTPUT REP-F. PERFORM VARYING WS-I FROM 1 BY 1 UNTIL WS-I > 3 MOVE T-NAME(WS-I) TO WS-NAME MOVE T-AMT(WS-I) TO WS-AMOUNT GENERATE DETAIL-LINE END-PERFORM. TERMINATE SALES-REPORT. CLOSE REP-F. STOP RUN.

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

libcob: error: GENERATE SALES-REPORT but no INITIATE was done
libcob: warning: implicit CLOSE of REP-F ('bad.txt')
1

The run ends with exit status 1, the runtime names the report and the verb in the message, and the file is closed for the program with a warning. That is the whole error handling of the Report Writer: a missing INITIATE is not a file status and cannot be caught with IF WS-ST NOT = "00".

Exercises

  1. Change the page limit of rwp to 12 lines. How many pages does the report have, and where is the second heading?
  2. Add a column with the line number of the detail to rwd. Which statement supplies it?
  3. Give the detail line a PIC 9(5) column of width three and read the report. What happened to the amounts?
  4. Move the INITIATE of rwd after the loop. Which message does the first GENERATE print?

Questions

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

  1. Which section of the DATA DIVISION holds a report description?

    Answer

    REPORT SECTION, after WORKING-STORAGE

    The RD entry and the line groups of the page sit in the REPORT SECTION.

  2. What does PAGE LIMIT IS 6 LINES do?

    Answer

    It ends a page after six lines and starts the next one with its heading

    The report of six records came out as two pages of six lines.

  3. Which verb starts a report?

    Answer

    INITIATE

    Without it the first GENERATE stopped the run with an error.

  4. What does the SOURCE clause of a report field name?

    Answer

    The working-storage field the column shows

    Each detail line was filled from WS-NAME and WS-AMOUNT.

  5. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q5. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-N PIC 9 VALUE 0. 01 W-I PIC 9 VALUE 0. PROCEDURE DIVISION. PERFORM VARYING W-I FROM 1 BY 1 UNTIL W-I IS GREATER THAN 6 ADD 1 TO W-N END-PERFORM. DISPLAY W-N. STOP RUN.

    Answer

    6

    Six passes count six records, the number the paged report showed.

  6. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q6. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-PAGE PIC 9 VALUE 6. 01 W-LINE PIC 9 VALUE 4. 01 W-LEFT PIC 9 VALUE 0. PROCEDURE DIVISION. SUBTRACT W-LINE FROM W-PAGE GIVING W-LEFT. DISPLAY W-LEFT. STOP RUN.

    Answer

    2

    The statement subtracts 4 from 6, so the field holds 2.

  7. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q7. DATA DIVISION. WORKING-STORAGE SECTION. 01 T-A. 05 T-V PIC 9(3) OCCURS 3 TIMES. 01 W-I PIC 9 VALUE 0. 01 W-S PIC 9(5) VALUE 0. PROCEDURE DIVISION. MOVE 100 TO T-V(1). MOVE 20 TO T-V(2). MOVE 3 TO T-V(3). PERFORM VARYING W-I FROM 1 BY 1 UNTIL W-I IS GREATER THAN 3 ADD T-V(W-I) TO W-S END-PERFORM. DISPLAY W-S. STOP RUN.

    Answer

    00123

    The loop adds the three amounts, and the field is five digits wide.

  8. What does this program print? IDENTIFICATION DIVISION. PROGRAM-ID. Q8. DATA DIVISION. WORKING-STORAGE SECTION. 01 W-A PIC 9(5) VALUE 250. PROCEDURE DIVISION. DISPLAY W-A "|" . STOP RUN.

    Answer

    00250|

    A PIC 9(5) field shows five digits, with the leading zeros.

  9. How does the program learn that a GENERATE failed because the report was not initiated?

    Answer

    It cannot: the runtime stops the program with a message and exit status 1

    The message came from libcob, not from the file status of the report.

  10. What is the output of a Report Writer report?

    Answer

    An ordinary file of lines, one per printed line, trailing spaces removed by a line sequential file

    cat read the report and cat -A showed the line ends.

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