When rolling totals forward, the SUM clause adds a sum counter from a lower-level CONTROL FOOTING report group to a sum counter in a higher-level footing group. The control logic and necessary control hierarchy for rolling counters forward begins in the CONTROL clause.

In the following example, WEEK-AMT is a sum counter found in the lower-level CONTROL FOOTING group, EACH-WEEK. This sum counter is named in the SUM clause in the higher-level CONTROL FOOTING report group, EACH-MONTH. The value of each WEEK-AMT sum is added to the higher-level counter just before the lower-level CONTROL FOOTING group is printed.

RD EXPENSE-FILE. . . . CONTROLS ARE EACH-MONTH, EACH-WEEK. 01 TYPE CONTROL FOOTING EACH-WEEK. 02 LINE PLUS 2. 03 COLUMN 1 PIC IS X(30) VALUE IS "TOTAL EXPENSES FOR WEEK/ENDING". 03 COLUMN 33 PIC IS X(9) SOURCE IS MONTH. 03 COLUMN 42 PIC IS X(2) SOURCE IS DAY. 03 WEEK-AMT COLUMN 45 PIC ZZ9.99 SUM COST. 01 TYPE CONTROL FOOTING EACH-MONTH. 02 LINE PLUS 2. 03 COLUMN 10 PIC X(18) VALUE IS "TOTAL EXPENSES FOR". 03 COLUMN 29 PIC X(9) SOURCE MONTH. 03 COLUMN 50 PIC ZZ9.99 SUM WEEK-AMT.

The following output is a result of rolling the totals forward:

1 2 3 4 5 column 1234567890123456789012345678901234567890123456789012345 TOTAL EXPENSES FOR DECEMBER 379.19

10.8.11.4 RESET Option

When a CONTROL FOOTING group is printed, the SUM counter in that group is automatically reset to zero. If you want to specify when a SUM counter is reset to zero, use the RESET phrase. RESET names a data item in a higher-level CONTROL FOOTING that will cause the SUM counter to be reset to zero. RESET is used only with a SUM clause.

The following example sums SALES, resetting the counter to zero only when it encounters a new year (YEAR). This prevents the sum from being reset to zero when a new month causes a control break, giving a running total of the months within the year.

RD SALES-REPORT. . . . CONTROLS ARE YEAR, EACH-MONTH, EACH-WEEK. . . . 01 TYPE CONTROL FOOTING EACH-MONTH 02 COLUMN 10 PIC ZZ9.99 SUM SALES RESET ON YEAR.

10.8.11.5 UPON Option

Another SUM option is the UPON phrase. This phrase allows selective subtotaling for the DETAIL Report Group named in the phrase. When you use the UPON phrase, you cannot reference the sum counter in the SUM clause. You can use any File or Working-Storage Section elementary numeric data item.

When you code the UPON option with the SUM clause, the value of the data items of the SUM clause will be added whenever the TYPE DETAIL report group you name in the UPON option is generated.

WORKING-STORAGE SECTION. . . . 01 WORK-AREA. . . . 03 ADD-COUNTER PIC 9 VALUE 1. REPORT SECTION. . . . 01 FIRST-DETAIL-LINE TYPE IS DETAIL LINE IS PLUS 2. . . . 01 TYPE IS CONTROL FOOTING FINAL. 05 LINE IS PLUS 3. . . . 05 LINE PLUS 2. 10 COLUMN 5 PIC Z(3)9 SUM ADD-COUNTER UPON FIRST-DETAIL-LINE.

In the preceding example, the value of ADD-COUNTER is added to the CONTROL FOOTING FINAL counter every time the FIRST-DETAIL-LINE report group is generated.

10.8.12 Restricting Print Items

In a Report Writer program, the GROUP INDICATE clause eliminates repeated information from report detail lines by allowing an elementary item in a DETAIL report group to be printed only the first time after a control or page break. The following example illustrates the use of this clause:

01 DETAIL-LINE TYPE DETAIL LINE PLUS 1. 05 COLUMN 1 GROUP INDICATE PIC X(6) VALUE "SALES:". * (prints only the first time after a control or page break) 05 COLUMN 10 PIC X(10) SOURCE BRANCH. * (prints each time)

These statements produce the following lines:

SALES: BRANCH-A BRANCH-B BRANCH-C

The next two examples are nearly identical programs; the only difference is the use of the GROUP INDICATE clause in the second example.

The following program does not contain a GROUP INDICATE clause:

01 DETAIL-LINE TYPE IS DETAIL LINE IS PLUS 1. 02 COLUMN 1 PIC X(15) SOURCE A-NAME. 02 COLUMN 20 PIC 9(6) SOURCE A-REG-NO.

It produces the following output:

1 2 3 123456789012345678901234567890 Name Registration Number Rolans R. 123456 Rolans R. 123457 Rolans R. 123458 Vencher R. 654321 Vencher R. 654322 Vencher R. 654323 Vencher R. 654324 Anders J. 987654 Anders J. 987655 Anders J. 987656

The following example contains a GROUP INDICATE clause:

01 DETAIL-LINE TYPE IS DETAIL LINE IS PLUS 1. 02 COLUMN 1 PIC X(15) SOURCE A-NAME GROUP INDICATE. 02 COLUMN 20 PIC 9(6) SOURCE A-REG-NO.

With the GROUP INDICATE clause, the program produces the following output:

1 2 3 123456789012345678901234567890 Name Registration Number Rolans R. 123456 123457 123458 Vencher R. 654321 654322 654323 654324 Anders J. 987654 987655 987656

10.8.13 Processing a Report Writer Report

In a Report Writer program, you usually use the following five statements:

• INITIATE
• GENERATE
• TERMINATE
• USE BEFORE REPORTING
• SUPPRESS

You must use the INITIATE, GENERATE, and TERMINATE statements. The USE BEFORE REPORTING and the SUPPRESS statements are optional.

Before any Report Writer statement is executed, the report file must be open.

10.8.13.1 Initiating the Report

The INITIATE statement begins the report processing and is executed before any GENERATE or TERMINATE statements. The report name used in this statement is specified in the RD entry in the Report Section and in the REPORT clause of the FD entry for the file to which the report is written.

INITIATE sets PAGE-COUNTER to 1, LINE-COUNTER to zero, and all SUM counters to zero.

This program code uses the code in Section 10.8.2.

PROCEDURE DIVISION. . . . MAIN SECTION. 000-START. OPEN INPUT CUSTOMER-FILE. OPEN OUTPUT PRINTER-FILE. . . . INITIATE MASTER-LIST.

A second INITIATE statement for the same report must not be executed until a TERMINATE statement for the report has been executed (see Section 10.8.13.4).

10.8.13.2 Generating a Report Writer Report

The GENERATE statement prints the report.

You can produce either detail or summary reports depending on the GENERATE identifier. If you code the name of a DETAIL report group with GENERATE, you create a detail report; if you code a report name with GENERATE, you create a summary report.

10.8.13.3 Automatic Operations of the GENERATE Statement

When the first GENERATE statement is executed, the following report groups are printed, if they are specified in the program:

• REPORT HEADING report group
• PAGE HEADING report group
• CONTROL HEADING report groups
• For detail reporting, the specified TYPE DETAIL report group

A USE BEFORE REPORTING declarative can also execute just before the associated report group is produced, to produce a cover page for the report, for example.

Figure 10-11 shows the sequence of operations for the first GENERATE statement.

Figure 10-11 First GENERATE Statement

For subsequent GENERATE statements in the program, the following operations take place:

• Any USE BEFORE REPORTING declaratives execute just before the associated report group is produced.
• Any specified control breaks occur.
• CONTROL FOOTING and CONTROL HEADING report groups print after the specified control breaks occur.
• In a detail report, the TYPE DETAIL report groups print.
• SUM operands are incremented.
• Sum counters are reset as specified.

Figure 10-12 shows the sequence of operations for all GENERATE statements except the first. See Figure 10-11 for a comparison with the sequence of operations for the first GENERATE statement.

Figure 10-12 Subsequent GENERATE Statements

The TERMINATE statement completes the processing of a report.

Like INITIATE, the TERMINATE statement report name is specified in the RD entry in the Report Section and in the REPORT clause of the FD entry for the file to which the report is written.

When the TERMINATE statement is executed, breaks occur for all control fields, and all control footings are written; any page footings and report footings are also written.

PROCEDURE DIVISION. . . . 300-END-OF-FILE. TERMINATE MASTER-LIST. CLOSE CUSTOMER-FILE, PRINTER-FILE. STOP RUN.

If no GENERATE statement has been executed for the report, the TERMINATE statement does not produce any report groups.

A second TERMINATE statement for the report must not be executed before a second INITIATE statement for the report has been executed.

The TERMINATE statement does not close the report file; a CLOSE statement must be executed after the TERMINATE statement.

Figure 10-13 shows the sequence of operations for TERMINATE.

Figure 10-13 TERMINATE Statement

In a COBOL program, you specify a Declarative section to define procedures that supplement the standard procedures of the program. Note that in a Report Writer program, you can specify the USE BEFORE REPORTING statement. This USE BEFORE REPORTING statement gives you more control over the data to be printed in a Report Writer program.

The USE BEFORE REPORTING statement:

• Allows you to define declarative procedures
• Causes those procedures to be executed just before a specified report group is printed (this specified report group name is written with the USE statement)
• Lets you modify the data to be printed (for example, where simple sum operations must be augmented by more complex operations involving multiplication, division, and subtraction)
• Lets you suppress printing the report group

The following example indicates that the phrase BEGINNING-OF-REPORT is to be displayed just before the REPORT HEADING group named REPORT-HEADER; the phrase END-OF-REPORT is to be displayed just before the REPORT FOOTING group called REPORT-FOOTER.

PROCEDURE DIVISION. DECLARATIVES. BOR SECTION. USE BEFORE REPORTING REPORT-HEADER. BOR-A. DISPLAY "BEGINNING-OF-REPORT". EOR SECTION. USE BEFORE REPORTING REPORT-FOOTER. EOR-A. DISPLAY "END-OF-REPORT". END DECLARATIVES.

Note that you cannot use INITIATE, GENERATE, or TERMINATE in a Declarative procedure.

10.8.13.6 Suppressing a Report Group

You can also use the SUPPRESS statement in a USE BEFORE REPORTING procedure to suppress the printing of a report group. For example, you can suppress printing of an unnecessary total line, such as a line for a monthly sales total that has only one sale or a line of zeros.

The SUPPRESS statement nullifies any NEXT GROUP and LINE clauses, but leaves the LINE-COUNTER value unchanged.

Note that the SUPPRESS statement applies only to that particular instance of the report group; that group will be printed the next time unless the SUPPRESS statement is executed again.

The SUPPRESS statement has no effect on sum counters.

10.8.14 Selecting a Report Writer Report Type

You can print two types of reports using the Report Writer feature. In a detail report, you print primary data information as well as totals. In a summary report, you print only control heading and footing information (such as report data headings and totals) and exclude detail input record information.

Section 10.9 provides examples of detail and summary reports.

10.8.14.1 Detail Reporting

In detail reporting, at least one printable TYPE DETAIL report group must be specified. A GENERATE statement produces the specified TYPE DETAIL report group and performs all the automatic operations of the Report Writer facility as specified in the report group entries (see Section 10.8.13.3).

In the following example, DETAIL-LINE is the name of the DETAIL report group. When this GENERATE statement executes, a detail report is printed.

200-READ-MASTER. READ CUSTOMER-FILE AT END MOVE HIGH-VALUES TO NAME. IF NAME NOT = HIGH-VALUES GENERATE DETAIL-LINE.

10.8.14.2 Summary Reporting

In summary reporting, the GENERATE statement performs all of the automatic operations of the Report Writer facility, but does not produce any TYPE DETAIL report groups.

A report name references the name of an RD entry. If MASTER-LIST is an RD entry, then GENERATE MASTER-LIST produces HEADING and FOOTING report groups (in the order defined), but omits DETAIL report group lines.

10.9 Report Writer Examples

This section provides you with the input data and sample reports produced by five Report Writer programs. Each sample report has a program summary section that describes the Report Writer features used in that program; you can examine the summary and output to determine the usage of Report Writer features. Note that each sample report is followed by the program that was used to generate it.

Also, many of the report pages in Reports 2 through 5 have been compressed into fewer pages than you would normally find. For example, a report title page is typically found on a separate page. Whether you are producing a report for yourself or for a customer, you must begin by designing the report.

The data records shown in Figure 10-14 are used for the programs in this section.

Figure 10-14 Sample MASTER.DAT File

EX1006 uses the PAGE HEADING, DETAIL, and CONTROL FOOTING report groups and produces a detail report---EX1006.LIS.

To get EX1006.LIS, you use the following commands:

On OpenVMS

$ COBOL EX1006 $ LINK EX1006 $ RUN EX1006 $ PRINT/NOFEED EX1006.LIS <>

Note that the case of the command parameters is insignificant in the preceding command example.

On Tru64 UNIX

% cobol ex1006.cob % a.out % lpr EX1006.LIS <>

Note that the case of the file name, EX1006.LIS, is significant in the preceding command example, because the file specification in the ASSIGN statement in Example 10-6 was given in upper case. The program (EX1006) in Example 10-6 produces the output shown in Figure 10-15 (EX1006.LIS).

Example 10-6 Sample Program EX1006

IDENTIFICATION DIVISION. PROGRAM-ID. EX1006. ENVIRONMENT DIVISION. CONFIGURATION SECTION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT CUSTOMER-FILE ASSIGN TO "MASTER.DAT". SELECT SORT-FILE ASSIGN TO "EX1006-SORTIN.TMP". SELECT SORTED-FILE ASSIGN TO "EX1006-SORTOUT.TMP". SELECT PRINTER-FILE ASSIGN TO "EX1006.LIS". DATA DIVISION. FILE SECTION. SD SORT-FILE. 01 SORTED-CUSTOMER-MASTER-FILE. 02 SORT-NAME PIC X(26). 02 PIC X(73). FD CUSTOMER-FILE. 01 CUSTOMER-MASTER-FILE PIC X(99). FD SORTED-FILE. 01 CUSTOMER-MASTER-FILE. 02 NAME. 03 LAST-NAME PIC X(15). 03 FIRST-NAME PIC X(10). 03 MIDDLE-INIT PIC X. 02 ADDRESS PIC X(20). 02 CITY PIC X(20). 02 STATE PIC XX. 02 ZIP PIC 99999. 02 SALESMAN-NUMBER PIC 99999. 02 INVOICE-DATA. 03 INVOICE-NUMBER PIC 999999. 03 INVOICE-SALES PIC S9(5)V99. 03 INVOICE-DATE. 04 INV-DAY PIC 99. 04 INV-MO PIC 99. 04 INV-YR PIC 9999. FD PRINTER-FILE REPORT IS MASTER-LIST. WORKING-STORAGE SECTION. 01 UNEDITED-DATE. 02 UE-YEAR PIC 9999. 02 UE-MONTH PIC 99. 02 UE-DAY PIC 99. 02 FILLER PIC X(6). 01 ONE-COUNT PIC 9 VALUE 1. REPORT SECTION. RD MASTER-LIST PAGE LIMIT IS 66 HEADING 1 FIRST DETAIL 13 LAST DETAIL 55 CONTROL IS FINAL. 01 TYPE IS PAGE HEADING. 02 LINE 5. 03 COLUMN 1 PIC X(27) VALUE "CUSTOMER MASTER FILE REPORT". 03 COLUMN 105 PIC X(4) VALUE "PAGE". 03 COLUMN 109 PIC ZZZ9 SOURCE PAGE-COUNTER. 02 LINE 7. 03 COLUMN 1 PIC X VALUE "+". 03 COLUMN 2 PIC X(110) VALUE ALL "-". 03 COLUMN 112 PIC X VALUE "+". 02 LINE 8. 03 COLUMN 1 PIC X VALUE "|". 03 COLUMN 10 PIC X(4) VALUE "NAME". 03 COLUMN 29 PIC X VALUE "|". 03 COLUMN 43 PIC X(7) VALUE "ADDRESS". 03 COLUMN 81 PIC X VALUE "|". 03 COLUMN 91 PIC X(7) VALUE "INVOICE". 03 COLUMN 112 PIC X VALUE "|". 02 LINE 9. 03 COLUMN 1 PIC X VALUE "|". 03 COLUMN 2 PIC X(110) VALUE ALL "-". 03 COLUMN 112 PIC X VALUE "|". 02 LINE 10. 03 COLUMN 1 PIC X(6) VALUE "| LAST". 03 COLUMN 16 PIC X(7) VALUE "| FIRST". 03 COLUMN 26 PIC X(4) VALUE "|MI|". 03 COLUMN 35 PIC X(6) VALUE "STREET". 03 COLUMN 48 PIC X VALUE "|". 03 COLUMN 52 PIC X(4) VALUE "CITY". 03 COLUMN 71 PIC X VALUE "|". 03 COLUMN 72 PIC X(2) VALUE "ST". 03 COLUMN 74 PIC X VALUE "|". 03 COLUMN 81 PIC X VALUE "|". 03 COLUMN 83 PIC X(4) VALUE "DATE". 03 COLUMN 90 PIC X VALUE "|". 03 COLUMN 92 PIC X(6) VALUE "NUMBER". 03 COLUMN 98 PIC X VALUE "|". 03 COLUMN 103 PIC X(6) VALUE "AMOUNT". 03 COLUMN 112 PIC X VALUE "|". 02 LINE 11. 03 COLUMN 1 PIC X VALUE "+". 03 COLUMN 2 PIC X(110) VALUE ALL "-". 03 COLUMN 112 PIC X VALUE "+". 01 DETAIL-LINE TYPE DETAIL LINE PLUS 1. 02 COLUMN 1 PIC X(15) SOURCE LAST-NAME. 02 COLUMN 17 PIC X(10) SOURCE FIRST-NAME. 02 COLUMN 28 PIC XX SOURCE MIDDLE-INIT. 02 COLUMN 30 PIC X(20) SOURCE ADDRESS. 02 COLUMN 51 PIC X(20) SOURCE CITY. 02 COLUMN 72 PIC XX SOURCE STATE. 02 COLUMN 75 PIC 99999 SOURCE ZIP. 02 COLUMN 81 PIC Z9 SOURCE INV-DAY. 02 COLUMN 83 PIC X VALUE "-". 02 COLUMN 84 PIC 99 SOURCE INV-MO. 02 COLUMN 86 PIC X VALUE "-". 02 COLUMN 87 PIC 9999 SOURCE INV-YR. 02 COLUMN 92 PIC 9(6) SOURCE INVOICE-NUMBER. 02 COLUMN 99 PIC $$$,$$$,$$$.99- SOURCE INVOICE-SALES. 02 DETAIL-COUNT PIC S9(10) SOURCE ONE-COUNT. 02 INV-AMOUNT PIC S9(9)V99 SOURCE INVOICE-SALES. 01 FINAL-FOOTING TYPE IS CONTROL FOOTING FINAL LINE PLUS 5 NEXT GROUP NEXT PAGE. 02 COLUMN 20 PIC X(17) VALUE "TOTAL RECORDS: ". 02 FDC COLUMN 40 PIC ZZZ,ZZZ,ZZ9 SUM ONE-COUNT. 02 COLUMN 75 PIC X(15) VALUE "TOTAL SALES: ". 02 FIA COLUMN 95 PIC $$$,$$$,$$$,$$$.99- SUM INVOICE-SALES. PROCEDURE DIVISION. 000-DO-SORT. DISPLAY "*** EX1006 ***". SORT SORT-FILE ON ASCENDING KEY SORT-NAME WITH DUPLICATES IN ORDER USING CUSTOMER-FILE GIVING SORTED-FILE. DISPLAY "*** Created EX1006.LIS ***". 050-START. OPEN INPUT SORTED-FILE. OPEN OUTPUT PRINTER-FILE. ACCEPT UNEDITED-DATE FROM DATE. INITIATE MASTER-LIST. PERFORM 200-READ-MASTER UNTIL NAME = HIGH-VALUES. 100-END-OF-FILE. TERMINATE MASTER-LIST. CLOSE SORTED-FILE, PRINTER-FILE. STOP RUN. 200-READ-MASTER. READ SORTED-FILE AT END MOVE HIGH-VALUES TO NAME. IF NAME NOT = HIGH-VALUES GENERATE DETAIL-LINE.

Figure 10-15 EX1006.LIS Listing