# Compaq COBOL
User Manual

Previous | Contents | Index

## 10.8.3 Defining a Report Writer Logical Page with the PAGE Clause

To define the logical page for a Report Writer report, you use the PAGE clause. This clause enables you to specify the number of lines on a page and the format of that page. For example, the PAGE clause allows you to specify where the heading, detail, and footing appear on the printed page. If you want to use vertical formatting, you must use the PAGE clause.

The RD entry example in Section 10.8.2 contains the following PAGE clause information:

RD Entry Line |  | Meaning
--- | --- | ---
PAGE LIMIT IS | 66 | Maximum number of lines per page is 66
HEADING | 1 | Line number on which the first report heading (RH) or page heading (PH) should print on each page
FIRST DETAIL | 13 | First line number on which a control heading (CH), detail (DE), or control footing (CF) should print on a page
LAST DETAIL | 30 | Last line number on which a CH or DE can print on a page
FOOTING | 50 | Last line number on which a control footing (CF) can print on a page (if specified, page footing (PF) and report footing (RF) report groups follow the line number shown in FOOTING)

The PAGE LIMIT clause line numbers are in ascending order and must not exceed the number specified in the PAGE LIMIT clause (in this example, 66 lines).

Section 10.8.4 describes report group entries in more detail.

## 10.8.4 Describing Report Group Description Entries

In a Report Writer program, report groups are the basic elements that make up the logical page. There are seven types of report groups, which consist of one or more report lines printed as a complete unit (for example, a page heading). Each report line can be subdivided into data items or fields.

Table 10-1 lists the seven types of report groups:

Table 10-1 Report Writer Report Group Types
Report Group Type | Description
--- | ---
REPORT HEADING | Prints a title or any other information that pertains to the entire report
PAGE HEADING | Prints a page heading and column headings
CONTROL HEADING | Prints a heading when a control break occurs
DETAIL | Prints the primary data of the report
CONTROL FOOTING | Prints totals when a control break occurs
PAGE FOOTING | Prints totals or comments at the bottom of each page
REPORT FOOTING | Prints trailer information for the report

A Report Writer program can include both printable report groups and null report groups. Null report groups are groups that do not print but are used for control breaks.

Figure 10-9 shows the report group presentation order found on a logical page. You must code at least one DETAIL report group (printable or null) in your program to produce a report. All other report groups are optional. Note that you can code a report group by using the abbreviations shown in Figure 10-9.

Figure 10-9 Presentation Order for a Logical Page

Figure 10-10 shows a report that uses all seven of the report groups listed in the preceding table.

Figure 10-10 Sample Report Using All Seven Report Groups

To code report groups, you use an 01-level entry to describe the physical and logical characteristics of the report group and the Report Writer TYPE clause to indicate the type of the report group. The TYPE clause can be preceded by a user-defined report group name. The CONTROL HEADING and FOOTING report groups use data names that are also specified as CONTROL clause names in the Report Description entry (see Section 10.8.10 for CONTROL clause information).

The following example shows how to use the TYPE and CONTROL clauses:

    DATA DIVISION.

    REPORT SECTION.

    01   REPORT-HEADER TYPE IS REPORT HEADING.
    01   PAGE-HEADER TYPE IS PAGE HEADING.
    01   CONTROL-HEADER TYPE IS CONTROL HEADING CONTROL-NAME-1.
    01   DETAIL-LINE TYPE IS DETAIL.
    01   CONTROL-FOOTER TYPE IS CONTROL FOOTING CONTROL-NAME-2.
    01   PAGE-FOOTER TYPE IS PAGE FOOTING.
    01   REPORT-FOOTER TYPE IS REPORT FOOTING.

## 10.8.5 Vertical Spacing for the Logical Page

You use the LINE clause for positioning vertical lines within a report group or for indicating vertical line space between two report groups. The LINE clause indicates the start of an absolute print line (a specific line on a page) or where a relative print line (an increment to the last line printed) is to print on the page. You can use this clause with all report groups.

In the following example, the LINE clause indicates that this report group begins on absolute line number 5 on a page. LINE IS 7 indicates that this report group has a second line of data found on absolute line number 7. Absolute line numbers must be specified in ascending order.

    01   PAGE-HEADER TYPE IS PAGE HEADING.
         02  LINE IS 5.
         .
         .
         .
         02  LINE IS 7.

In the following example the term PLUS in the LINE clause indicates that DETAIL-LINE prints two lines after the last line of the previous report group. If you used a CONTROL HEADING report group that ended on line 20 before DETAIL-LINE, then DETAIL-LINE would print beginning on line 22.

    01   DETAIL-LINE TYPE IS DETAIL.
         02  LINE PLUS 2.

In the following example the LINE clause specifies that the REPORT FOOTING report group prints on line 32 of the next page:

    01  REPORT-FOOTER TYPE IS REPORT FOOTING.
        02  LINE IS 32 ON NEXT PAGE.

You can code NEXT PAGE only for CONTROL HEADING, DETAIL, CONTROL FOOTING, and REPORT FOOTING groups, and only in the first LINE clause in that report group entry.

Within the report group, absolute line numbers must be in ascending order (although not consecutive) and must precede all relative line numbers.

You can use the NEXT GROUP clause instead of the LINE clause to control line spacing. In NEXT GROUP clause, you specify the amount of vertical line space you want following one report group and before the next. You use this clause in the report group that will have the space following it, as shown in the following example:

    01    CONTROL-HEADER TYPE IS CONTROL HEADING CONTROL-NAME-1
          NEXT GROUP PLUS 4.

    01    DETAIL-LINE TYPE IS DETAIL.

This example indicates relative line use. The report group (DETAIL) immediately following this CONTROL HEADING report group will print on the fourth line after the CH's last print line.

You can also specify absolute line spacing with the NEXT GROUP clause. An absolute line example---NEXT GROUP IS 10---places the next report group on line 10 of the page. In addition you can use NEXT GROUP NEXT PAGE, which causes a page-eject to occur before the NEXT GROUP report group prints.

NEXT GROUP can be coded only for REPORT HEADING, CONTROL HEADING, DETAIL, CONTROL FOOTING, and PAGE FOOTING report groups, and only at the 01 level.

A PAGE FOOTING report group must not specify the NEXT PAGE phrase of the NEXT GROUP clause.

Both the LINE and NEXT GROUP clauses must adhere to the page parameters specified in the PAGE clause in the RD entry.

In addition, the Report Writer facility keeps track of the number of lines printed or skipped on each page by using the LINE-COUNTER, which references a special register that the compiler generates for each Report Description entry in the Report Section. The Report Writer facility maintains the value of LINE-COUNTER and uses this value to determine the vertical positioning of a report.

## 10.8.6 Horizontal Spacing for the Logical Page

The COLUMN NUMBER clause defines the horizontal location of items within a report line.

You use the COLUMN NUMBER clause only at the elementary level. This clause must appear in or be subordinate to an entry that contains a LINE NUMBER clause. Within the description of a report line, the COLUMN NUMBER clauses must show values in ascending column order. Column numbers must be positive integer literals with values from 1 to the maximum number of print positions on the printer. For example:

    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 40    PIC X(20)          SOURCE ADDRESS.
            02 COLUMN 97    PIC $$$,$$$,$$$.99 SOURCE INVOICE-SALES.

Omitting the COLUMN clause creates a null (nonprinting) report item. Null report items are used to accumulate totals and force control breaks as described in Section 10.8.4.

The following example shows the use of a COLUMN NUMBER clause in a LINE clause:

    02  LINE 15 COLUMN 1 PIC X(12) VALUE "SALES TOTALS".

The previous example results in the following output:

                    1         2         3         4
    column 1234567890123456789012345678901234567890
           SALES TOTALS

In the next example, the COLUMN NUMBER clauses are subordinate to a LINE NUMBER clause:

    02  LINE 5 ON NEXT PAGE.
       03     COLUMN 1  PIC X(12)       VALUE "(Cust-Number".
       03     COLUMN 14 PIC 9999        SOURCE CUST-NUM.
       03     COLUMN 18 PIC X           VALUE ")".
       03     COLUMN 20 PIC X(15)       VALUE "TOTAL PURCHASES".
       03     COLUMN 36 PIC $$$$,$$$.99 SUM TOT-PURCHS.

The previous example produces the following output:

                    1         2         3         4
    column 1234567890123456789012345678901234567890123456
           (Cust-Number 1234) TOTAL PURCHASES   $1,432.99

## 10.8.7 Assigning a Value in a Print Line

In a Report Writer program, one way you specify a value for an item is to use the VALUE clause. This clause designates that the data item has a constant literal value. You often use this clause with REPORT HEADING and PAGE HEADING report groups, because the data in these groups is usually constant, as shown in the following example:

    01      TYPE IS PAGE HEADING.
            02    LINE  5.
               03 COLUMN 1
                     PIC X(27) VALUE "CUSTOMER MASTER FILE REPORT".
               03 COLUMN 40
                     PIC X(5)  VALUE "SALES".

The previous example results in the following output:

                    1         2         3         4         5
    column 12345678901234567890123456789012345678901234567890
           CUSTOMER MASTER FILE REPORT            SALES

## 10.8.8 Defining the Source for a Print Field

To assign a variable value to an item in a Report Writer program, you use the SOURCE clause.

The SOURCE clause, written in the Report Section, is analogous to the MOVE statement.

The clause names a data item that is moved to a specified position on the print line. Before an item that contains a SOURCE clause is printed, the Report Writer moves the value in the field named in the SOURCE clause into the print line at the print position specified by the COLUMN clause, as shown in the following example. Any data editing specified by the PICTURE clause is performed before the data is moved to the print line.

    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 35    PIC X(20) SOURCE ADDRESS.
            02 COLUMN 55    PIC X(20) SOURCE CITY.
            02 COLUMN 75    PIC XX    SOURCE STATE.
            02 COLUMN 78    PIC 99999 SOURCE ZIP.

You can also code a SOURCE clause with PAGE-COUNTER or LINE-COUNTER as its operand, as the following example shows. PAGE-COUNTER references a special register created by the compiler for each Report Description entry in the Report Section. This counter automatically increments by 1 each time the Report Writer executes a page advance. The use of PAGE-COUNTER eliminates Procedure Division statements you normally would write to explicitly count pages, as shown in the following example:

    01      TYPE IS PAGE HEADING.
            02      LINE 5.
                    03      COLUMN 1
                            PIC X(27) VALUE "CUSTOMER MASTER FILE REPORT".
                    03      COLUMN 52
                            PIC X(4)  VALUE "PAGE".
                    03      COLUMN 57
                            PIC ZZZ9
                            SOURCE PAGE-COUNTER.

This example produces the following output:

                       1         2         3         4         5         6
       column 123456789012345678901234567890123456789012345678901234567890
              CUSTOMER MASTER FILE REPORT                        PAGE    9

## 10.8.9 Specifying Multiple Reports

To include two or more reports in one file, you specify multiple identifiers in the REPORTS clause and provide multiple RDs in the Report Section.

To identify the lines of two or more reports in one file, you use the CODE clause, as shown in the following example:

    FILE SECTION.
    FD   REPORT-FILE
         REPORTS ARE REPORT1
                     REPORT2
                     REPORT3.
    REPORT SECTION.
    RD   REPORT1...
         CODE"AA".

    RD   REPORT2...
         CODE"BB".

    RD   REPORT3...
         CODE"CC".

The CODE clause specifies a 2-character nonnumeric literal that identifies each print line as belonging to a specific report. When the CODE clause is specified, the literal is automatically placed in the first two character positions of each Report Writer logical record. Note that if the clause is specified for any report in a file, it must be used for all reports in that file.

## 10.8.10 Generating and Controlling Report Headings and Footings

When you write a report that has control headings and/or footings, you must use the CONTROL clause to create control levels that determine subsequent headings and totals.

The CONTROL clause, found in the RD entry, names data items that indicate when control breaks occur. The CONTROL clause specifies the data items in major to minor order. You must define these CONTROL data items, or control names, in the Data Division, and reference them in the appropriate CONTROL HEADING and FOOTING report groups.

When the value of a control name changes, a control break occurs. The Report Writer acknowledges this break only when you execute a GENERATE or TERMINATE statement for the report, which causes the information related to that CONTROL report group to be printed.

In the following example, the report defines two control totals (MONTH-CONTRL and WEEK-CONTRL) in the CONTROL clause. The source of these control totals is in an input file named IN-FILE. The file must be already sorted in ascending sequence by MONTH-CONTRL and WEEK-CONTRL. The Report Writer facility automatically monitors these fields in the input file for any changes. If a new record contains different data than the previous record read, Report Writer triggers a control break.

    FD    IN-FILE.
    01    INPUT-RECORD.
          02  MONTH-CONTRL    PIC...
          02  ...
          02  ...
          02  WEEK-CONTRL     PIC...
    FD    REPORT-FILE   REPORT IS SALES-REPORT.
          .
          .
          .
    REPORT SECTION.
    RD    SALES-REPORT.
          CONTROLS ARE MONTH-CONTRL, WEEK-CONTRL.
    01    DETAIL-LINE TYPE IS DETAIL.

    01    TYPE IS CONTROL FOOTING MONTH-CONTRL.

    01    TYPE IS CONTROL FOOTING WEEK-CONTRL.

In the previous example, if the value in WEEK-CONTRL changes, a break occurs and Report Writer processes the CONTROL FOOTING WEEK-CONTRL report group. If the value in MONTH-CONTRL changes, a break occurs and Report Writer processes both CONTROL FOOTING report groups, because a break in any control field implies a break in all lower-order control fields as well.

The same process occurs if you include similar CONTROL HEADING report groups. However, CONTROL HEADING control breaks occur from a break to minor levels, while CONTROL FOOTING control breaks occur from a break to major levels.

The following example demonstrates the use of FINAL, a special control field that names the most major control field. You specify FINAL once, in the CONTROL clause, as the most major control level. When you code FINAL, a FINAL control break and subsequent FINAL headings and footings occur during program execution: once at the beginning of the report (as part of the report group, CONTROL HEADING FINAL), before the first detail line is printed; and once at the end of the report (as part of the report group, CONTROL FOOTING FINAL), after the last detail line is printed.

    01   TYPE CONTROL FOOTING FINAL.
         02  LINE 58.
             04  COLUMN 1 PIC X(32) VALUE
                "TOTAL SALES FOR YEAR-TO-DATE WAS".
             04  COLUMN 45 PIC 9(6).99 SOURCE TOTAL-SALES.

This example produces the following output:

                    1         2         3         4         5
    column 1234567890123456789012345678901234567890123456789012345
           TOTAL SALES FOR YEAR-TO-DATE WAS            953208.90

## 10.8.11 Defining and Incrementing Totals

In addition to using either the VALUE or SOURCE clause to assign a value to a report item, you can use the SUM clause to accumulate values of report items. This clause establishes a sum counter that is automatically summed during the processing of the report. You code a SUM clause only in a TYPE CONTROL FOOTING report group.

The identifiers of the SUM clause are either elementary numeric data items not in the Report Section or other sum counters in the Report Section that are at the same or lower level in the control hierarchy of the report, as specified in the CONTROL clause.

The SUM clause provides three forms of sum accumulation: subtotaling, crossfooting, and rolling-forward. These forms are detailed in this section. See Section 10.3 for further discussion.

### 10.8.11.1 Subtotaling

In subtotaling, the SUM clause references elementary numeric data items that appear in the File or Working-Storage Sections and then generates sums of those items.

In the following example, EACH-WEEK represents a CONTROL clause name. COST represents a numeric data item in the File Section that indicates weekly expenses for a company. DAY and MONTH indicate the particular day and month.

    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(4)  SOURCE IS MONTH.
            03  COLUMN 39  PIC IS X(2)  SOURCE IS DAY.
            03  WEEK-AMT   COLUMN 45
                           PIC ZZ9.99 SUM COST.

This example produces the following subtotal output:

                    1         2         3         4         5
    column 12345678901234567890123456789012345678901234567890
           TOTAL EXPENSES FOR WEEK/ENDING  JULY  02    799.23

When the value of EACH-WEEK changes, a control break occurs that causes this TYPE CONTROL FOOTING report group to print. The value of the sum counter is edited according to the PIC clause accompanying the SUM clause. Then the sum lines are printed in the location specified by the items' LINE and COLUMN clauses.

### 10.8.11.2 Crossfooting

In crossfooting, the SUM clause adds all the sum counters in the same CONTROL FOOTING report group and automatically creates another sum counter.

In the following example, the CONTROL FOOTING group shows both subtotaling (SALES-1) and crossfooting (SALES-2):

    01  TYPE DETAIL LINE PLUS 1.
        05  COLUMN 15 PIC 999.99 SOURCE BRANCH1-SALES.
        05  COLUMN 25 PIC 999.99 SOURCE BRANCH2-SALES.

    01  TYPE CONTROL FOOTING BRANCH-TOTAL LINE PLUS 2.
        05  SALES-1  COLUMN 15 PIC 999.99 SUM BRANCH1-SALES.
        05  SALES-2  COLUMN 25 PIC 999.99 SUM BRANCH2-SALES.
        05  SALES-TOT  COLUMN 50 PIC 999.99 SUM SALES-1, SALES-2.

The SALES-1 sum contains the total of the BRANCH1-SALES column and the SALES-2 sum contains the total of the BRANCH2-SALES column (both sums are subtotals). SALES-TOT contains the sum of SALES-1 and SALES-2; it is a crossfooting.

The crossfooting ouput is as follows:

                    1         2         3         4         5         6
    column 123456789012345678901234567890123456789012345678901234567890
                         125.00    300.00                   425.00

Previous | Next | Contents | Index