Michael Coughlan
Page 62
Each report group starts with a level 01 report group definition. The metalanguage for the report group definition is given in Figure 18-3.
501
Chapter 18 ■ the COBOL repOrt Writer
Figure 18-3. Metalanguage for the report group definition
RD Entry
When you create an RD entry, keep in mind that ReportGroupName is required only when the group
• Is a DETAIL group referenced by a GENERATE statement or the UPON phrase of a SUM clause
• Is referenced in a USE BEFORE REPORTING sentence in the declaratives
• Is required to qualify the reference to a SUM counter
LINE NUMBER Clause
When you use the LINE NUMBER clause, keep the following in mind:
• The LINE NUMBER clause is used to specify the vertical positioning of print lines. Lines can be
printed on
•
A specified line (absolute)
•
A specified line on the next page (absolute)
•
The current line number plus some increment (relative)
• The LINE NUMBER clause specifies where each line is to be printed, so no item that contains a
LINE NUMBER clause may contain a subordinate item that also contains a LINE NUMBER clause
(subordinate items specify the column items).
502
Chapter 18 ■ the COBOL repOrt Writer
• Where absolute LINE NUMBER clauses are specified, all absolute clauses must precede all
relative clauses, and the line numbers specified in the successive absolute clauses must be in
ascending order.
• The first LINE NUMBER clause specified in a PAGE FOOTING group must be absolute.
• The NEXT PAGE clause can appear only once in a given report group description, and it must
be in the first LINE NUMBER clause in the report group.
• The NEXT PAGE clause cannot appear in any HEADING group.
NEXT GROUP Clause
When you use the NEXT GROUP clause, keep the following things in mind:
• The NEXT GROUP clause is used to specify the vertical positioning of the start of the next group.
This clause can be used to specify that the next report group should be printed on
•
A specified line (absolute)
•
The current line number plus some increment (relative)
•
The next page
• The NEXT PAGE option in the NEXT GROUP clause must not be specified in a page footer.
• The NEXT GROUP clause must not be specified in a REPORT FOOTING or PAGE HEADING group.
•
When used in a DETAIL group, the NEXT GROUP clause refers to the next DETAIL group to be printed.
The TYPE Clause
The TYPE clause specifies the type of the report group. The type of the report group governs when and where it is printed in the report (for instance, a REPORT HEADING group is printed only once: at the beginning of the report).
When you use the TYPE clause, keep the following things in mind:
• Most groups are defined once for each report, but control groups (other than CONTROL ..FINAL
groups) are defined for each control-break item.
• In REPORT FOOTING, and CONTROL FOOTING groups, SOURCE and USE clauses must not reference
any data item that contains a control-break item or is subordinate to a control-break item.
• PAGE HEADING and FOOTING groups must not reference a control-break item or any item
subordinate to a control-break item.
• DETAIL report groups are processed when they are referenced in a GENERATE statement.
All other groups are processed automatically by the Report Writer. There can be more than
one DETAIL group.
• The REPORT HEADING, PAGE HEADING, CONTROL HEADING FINAL, CONTROL FOOTING FINAL, PAGE
FOOTING, and REPORT FOOTING report groups can each appear only once in the description
of a report.
Report Group Lines
The subordinate items in a report-group record describe the report lines and columns in the report group. There are two formats for defining items subordinate to the report-group record. The first is usually used to define the lines of the report group, and the second defines and positions the elementary print items.
503
Chapter 18 ■ the COBOL repOrt Writer
Defining the Print Lines
Print lines in a report group are usually defined using the metalanguage given in Figure 18-4. This format is used to specify the vertical placement of a print line, and it is always followed by subordinate items that specify the columns where the data items are to be printed.
Figure 18-4. Metalanguage for vertical print line positioning
As shown in the metalanguage, the level number is from 2 to 48, inclusive. If ReportLineName is used, its only purpose is to qualify a SUM counter reference.
Defining the Elementary Print Items
The elementary print items in the print line of a report group are described using the metalanguage shown in Figure 18-5. As you can see, the normal data-description clauses such as PIC, USAGE, SIGN, JUSTIFIED, BLANK WHEN
ZERO, and VALUE may be applied when describing an elementary print item. The Report Writer provides a number of additional clauses that may also be used with these items.
Figure 18-5. Metalanguage to define elementary report items
SumCounterName can only be referenced if the entry uses the SUM clause to define a sum counter.
504
Chapter 18 ■ the COBOL repOrt Writer
The COLUMN NUMBER Clause
When you use the COLUMN NUMBER clause, keep the following things in mind:
• COLUMN NUMBER specifies the position of a print item on the print line. When this clause is used,
it must be subordinate to an item that contains a LINE NUMBER clause.
• In a given print line, the ColNum#ls should be in ascending sequence.
• ColNum#l specifies the column number of the leftmost character position of the print item.
The GROUP INDICATE Clause
The GROUP INDICATE clause can only appear in a DETAIL report group. It is used to specify that a print item should be printed only on the first occurrence of its report group after a control break or page advance. For instance, in Listing 18-3, the state name and sales agent number are suppressed after their first occurrence. As a reminder, I have repeated the DETAIL group declaration here:
01 DetailLine TYPE IS DETAIL.
02 LINE IS PLUS 1.
03 COLUMN 1 PIC X(14)
SOURCE StateName(StateNum) GROUP INDICATE.
03 COLUMN 17 PIC 999
SOURCE SalesAgentNum GROUP INDICATE.
03 COLUMN 30 PIC $$$,$$$.99 SOURCE ValueOfSale.
The SOURCE Clause
The SOURCE clause is used to identify a data item that contains the value to be used when the print item is printed. For instance, the SOURCE ValueOfSale clause in the previous example specifies that the value of the item to be printed in column 30 is to be found in the data item ValueOfSale.
The SUM Clause
The SUM clause is used both to establish a sum counter and to name the data items to be summed. A SUM clause can appear only in the description of a CONTROL FOOTING report group. Statements in the PROCEDURE DIVISION can be used to alter the contents of the sum counters.
You can do three forms of summing in the Report Writer:
• Subtotaling
• Rolling forward
• Crossfooting
Subtotaling
When the SUM clause is used with a data item declared in the FILE or WORKING-STORAGE SECTION, then each time a GENERATE is executed, the value to be summed is added to the sum counter. If there is more than one DETAIL group in the report, the SUM
..UPON option allows you to select which sum counter to total. For instance, if the report contains two DETAIL groups—one called DetailLine and the other called AlternateDetailLine—you can use SUM..UPON to
specify that subtotaling is to be done only each time a GENERATE AlternateDetailLine is executed.
505
Chapter 18 ■ the COBOL repOrt Writer
Rolling Forward
When the SUM clause is used with a data item representing the sum counter of another CONTROL FOOTING group, then each time the other group is executed, the value of its sum counter is added to the value of the sum counter of the current group.
Listing 18-3 contains good examples of both subtotaling and rolling forward. Example 18-6 provides a reminder of the relevant code. Each time a DETAIL line is GENERATED, the ValueOf Sale is added to the TotalAgentSales sum counter. When a control break occurs on SalesAgentNum, the accumulated sum is printed and is added
to the TotalStateSales sum counter. When a control break occurs on StateNum, the sum accumulated in the
TotalStateSales sum counter is added to the final total sum counter.
Example 18-6. Subtotaling and Rolling Forward from Listing 18-3
01 SalesAgentGrp
TYPE IS CONTROL FOOTING SalesAgentNum NEXT GROUP PLUS 2.
: : : : : : : : : : : : : : :
03 TotalAgentSales COLUMN 45 PIC $$$$$,$$$.99 SUM ValueOfSale.
01 StateGrp TYPE IS CONTROL FOOTING StateNum NEXT GROUP PLUS 2.
02 LINE IS PLUS 2.
: : : : : : : : : : : : : : :
03 TotalStateSales COLUMN 45 PIC $$$$$,$$$.99 SUM TotalAgentSales.
01 TotalSalesGrp TYPE IS CONTROL FOOTING FINAL.
: : : : : : : : : : : : : : :
03 COLUMN 48 PIC $$,$$$,$$$.99 SUM TotalStateSales.
Crossfooting
In crossfooting, the sum counters in the same CONTROL FOOTING group can be added together to create another sum counter. In Example 18-7, each time a GENERATE statement is executed, the value of NetWeightOfGoods (in the file record) is added to the NWG sum counter, and the value of WeightOfPackingMaterials (in the file record) is added to WPM (subtotaling). When a control break occurs on OrderNumber, the values of the NWG and WPM sum counters are added together to give the combined total identified as GrossWeight and printed in column 40 (crossfooting).
Example 18-7. Crossfooting to Create the GrossWeight Sum Counter
01 ShippingGrp
TYPE IS CONTROL FOOTING OrderNumber NEXT GROUP PLUS 3.
: other entries :
: other entries :
03 NWG COLUMN 20 PIC Z,ZZ9 SUM NetWeightOfGoods.
03 WPM COLUMN 30 PIC ZZ9 SUM WeightOfPackingMaterials.
03 GrossWeight COLUMN 40 PIC ZZ,ZZ9 SUM GNW, PMW.
The RESET ON Clause
Sum counters are normally reset to zero after a control break on the control-break item associated with the report group. For instance, in Example 18-6, if you wanted SalesAgentGrp to show a rolling total of the sales in the state, you could change SalesAgentGrp as shown in Example 18-8. In this example, TotalAgentSales prints the sales of a particular agent and is reset to zero when the footer group is printed, whereas StateSalesToDate prints a rolling total of sales for the state and is reset to zero only when there is a control break on StateNum.
506
Chapter 18 ■ the COBOL repOrt Writer
Example 18-8. Using the RESET ON Clause
01 SalesAgentGrp
TYPE IS CONTROL FOOTING SalesAgentNum NEXT GROUP PLUS 2.
: : : : : : : : : : : : : : :
03 TotalAgentSales COLUMN 45 PIC $$$$$,$$$.99 SUM ValueOfSale.
03 StateSalesToDate COLUMN 60 PIC $$$$$,$$$.99 SUM ValueOfSale
RESET ON StateNum.
Special Report Writer Registers
The Report Writer maintains two special registers for each report declared in the REPORT SECTION.: LINE-COUNTER and PAGE-COUNTER.
LINE-COUNTER
LINE-COUNTER is a reserved word that can be used to access a special register that the Report Writer maintains for each report in the REPORT SECTION. The Report Writer uses the LINE-COUNTER register to keep track of where the lines are being printed on the report. It uses this information and the information specified in the PAGE LIMIT clause in the RD
entry to decide when a new page is required.
Although the LINE-COUNTER register can be used as a SOURCE item in the report, no statements in the PROCEDURE
DIVISION can alter the value in the register.
References to the LINE-COUNTER register can be qualified by referring to the name of the report given in the RD entry.
PAGE-COUNTER
The reserved word PAGE-COUNTER is used to access a special register that the Report Writer maintains for each report in the REPORT SECTION. It keeps track of the number of pages printed in the report. The PAGE-COUNTER register can be used as a SOURCE item in the report, but the value of the PAGE-COUNTER may also be changed by statements in the PROCEDURE DIVISION .
PROCEDURE DIVISION Report Writer Verbs
The Report Writer introduces four new verbs for processing reports:
• INITIATE
• GENERATE
• TERMINATE
• SUPPRESS PRINTING
The first three are normal PROCEDURE DIVISION verbs, but the last one can only be used in the declaratives. I will postpone discussion of that verb until I deal with declaratives.
The INITIATE Verb
An INITIATE statement starts the processing of the ReportName report or reports. The metalanguage for the INITIATE
verb is given in Figure 18-6.
507
Chapter 18 ■ the COBOL repOrt Writer
Figure 18-6. Metalanguage for the INITIATE verb
Before INITIATE is executed, the file associated with the ReportName must have been opened for OUTPUT or
EXTEND. This is illustrated in Listing 18-3 by these statements:
SELECT PrintFile ASSIGN TO "Listing18-3.Rpt".
: : : : : : : : :
FD PrintFile
REPORT IS SolaceSalesReport.
: : : : : : : : :
RD SolaceSalesReport
: : : : : : : : :
OPEN OUTPUT PrintFile
: : : : : : : : :
INITIATE SolaceSalesReport
The GENERATE Verb
The GENERATE statement drives the production of the report. The metalanguage for GENERATE is given in Figure 18-7.
Figure 18-7. Metalanguage for the GENERATE verb
The target of a GENERATE statement is either a DETAIL report group or a ReportName. When the target is a
ReportName, the report description must contain the following:
• A CONTROL clause
• Not more than one DETAIL group
• At least one group that is not a PAGE or REPORT group
When all the GENERATE statements for a particular report target the ReportName, the report performs summary processing only, and the report produced is called a summary report. For instance, to make a summary report using Listing 18-3, all you have to do is change
GENERATE DetailLine
to
GENERATE SolaceSalesReport.
If you specify GENERATE SolaceSalesReport, then the DETAIL group is never printed, but the other groups are printed.
The TERMINATE Verb
You use a TERMINATE statement to instruct the Report Writer to finish the processing of the specified report. The metalanguage for TERMINATE is given in Figure 18-8.
508
Chapter 18 ■ the COBOL repOrt Writer
Figure 18-8. Metalanguage for the TERMINATE verb
When TERMINATE is executed, the Report Writer prints the PAGE and REPORT FOOTING groups, and all the
CONTROL FOOTING groups are printed as if there had been a control break on the most senior control group.
After the report has been terminated, the file associated with the report must be cl
osed. For instance, in Listing 18-3, the TERMINATE SolaceSalesReport statement is followed by the CLOSE PrintFile statement.
Declaratives
The main structural elements of a COBOL program are divisions, sections, and paragraphs. This section introduces a new structural element: declaratives. When declaratives are used, they are the first element in the PROCEDURE DIVISION
and start with the word DECLARATIVES and end with END DECLARATIVES. Declaratives specify USE procedures that are executed when certain conditions occur. You write the USE procedures in the declaratives in consecutive sections.
When declaratives are used, the remainder of the PROCEDURE DIVISION must consist of at least one section.
Example 18-9 is a template the shows the structure of declaratives.
Example 18-9. Structure of Declaratives
PROCEDURE DIVISION.
DECLARATIVES
SectionName SECTION.
USE statement
ParagraphName.
COBOL Statements
END DECLARATIVES.
Main SECTION.
Declaratives are used for two main purposes:
• To extend the functionality of the Report Writer
• To handle file operation errors
Using Declaratives with the Report Writer
Declaratives are used to extend the functionality of the Report Writer by performing tasks or calculations that the Report Writer cannot do automatically or by selectively stopping a report group from being printed (using the SUPPRESS PRINTING command). When you use declaratives with the Report Writer, the USE BEFORE REPORTING phrase lets you specify that a particular section of code is to be executed before the identified report group is printed. The metalanguage for the USE statement used with the Report Writer is given in Figure 18-9.
Figure 18-9. Metalanguage for the Report Writer version of USE