| Previous | Contents | Index |
To create a report with Report Writer, you must write a report to a specific file. That file is described by a File Description (FD) entry; however, unlike a conventional or linage-file report, your FD entry for a Report Writer file must contain the REPORT clause, and you must assign a name for each report in the REPORT clause.
For instance, in the following example, the File Description on the left does not specify Report Writer; however, the example on the right correctly shows a Report Writer File Section entry:
FD SALES-REPORT FD SALES-REPORT
. .
. .
. .
01 SALES-AREA PIC X(133).
01 PRINT-AREA PIC X(133). REPORT IS MASTER-LIST.
|
To completely describe the report that you specify in the REPORT
clause, you must define a Report Section in the Data Division.
Section 10.8.2 describes the Report Section.
10.8.2 Defining the Report Section and the Report File
The Report Section in the Data Division provides specific information about the reports that are specified with the REPORT clause. Each report named in the Data Division File Section also must be defined in the Report Section.
To define a report, use a Report Description (RD) entry followed by one or more Report Group Description entries (01-level) in the Report Section. For example:
FILE SECTION.
FD SALES-REPORT
REPORT IS MASTER-LIST.
.
.
.
REPORT SECTION.
RD MASTER-LIST
PAGE LIMIT IS 66
HEADING 1
FIRST DETAIL 13
LAST DETAIL 30
FOOTING 50.
|
The RD supplies information about the format of the printed page and
the organization of the subdivisions (see Section 10.8.4).
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:
| 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. |
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
|
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
|
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
|
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
|
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.
| Previous | Next | Contents | Index |