Michael Coughlan
Page 61
The first page of the report produced by Listing 18-3 is shown in Example 18-5.
Listing 18-3. Adding the Sales Agent Commission and Salary to the Report
IDENTIFICATION DIVISION.
PROGRAM-ID. Listing18-3.
AUTHOR. Michael Coughlan.
ENVIRONMENT DIVISION.
INPUT-OUTPUT SECTION.
FILE-CONTROL.
SELECT SalesFile ASSIGN TO "Listing18-3-Sales.DAT"
ORGANIZATION IS LINE SEQUENTIAL.
SELECT PrintFile ASSIGN TO "Listing18-3.Rpt".
DATA DIVISION.
FILE SECTION.
FD SalesFile.
01 SalesRecord.
88 EndOfFile VALUE HIGH-VALUES.
02 StateNum PIC 99.
02 SalesAgentNum PIC 999.
02 ValueOfSale PIC 9(5)V99.
FD PrintFile
REPORT IS SolaceSalesReport.
493
Chapter 18 ■ the COBOL repOrt Writer
WORKING-STORAGE SECTION.
01 StateNameTable.
0 02 StateNameValues.
03 FILLER PIC X(18) VALUE "1149Alabama".
03 FILLER PIC X(18) VALUE "1536Alaska".
03 FILLER PIC X(18) VALUE "1284Arizona".
03 FILLER PIC X(18) VALUE "1064Arkansas".
03 FILLER PIC X(18) VALUE "1459California".
03 FILLER PIC X(18) VALUE "1508Colorado".
03 FILLER PIC X(18) VALUE "1742Connecticut".
03 FILLER PIC X(18) VALUE "1450Delaware".
03 FILLER PIC X(18) VALUE "1328Florida".
03 FILLER PIC X(18) VALUE "1257Georgia".
03 FILLER PIC X(18) VALUE "1444Hawaii".
03 FILLER PIC X(18) VALUE "1126Idaho".
03 FILLER PIC X(18) VALUE "1439Illinois".
03 FILLER PIC X(18) VALUE "1203Indiana".
03 FILLER PIC X(18) VALUE "1267Iowa".
03 FILLER PIC X(18) VALUE "1295Kansas".
03 FILLER PIC X(18) VALUE "1126Kentucky".
03 FILLER PIC X(18) VALUE "1155Louisiana".
03 FILLER PIC X(18) VALUE "1269Maine".
03 FILLER PIC X(18) VALUE "1839Maryland".
03 FILLER PIC X(18) VALUE "1698Massachusetts".
03 FILLER PIC X(18) VALUE "1257Michigan".
03 FILLER PIC X(18) VALUE "1479Minnesota".
03 FILLER PIC X(18) VALUE "0999Mississippi".
03 FILLER PIC X(18) VALUE "1236Missouri".
03 FILLER PIC X(18) VALUE "1192Montana".
03 FILLER PIC X(18) VALUE "1261Nebraska".
03 FILLER PIC X(18) VALUE "1379Nevada".
03 FILLER PIC X(18) VALUE "1571New Hampshire".
03 FILLER PIC X(18) VALUE "1743New Jersey".
03 FILLER PIC X(18) VALUE "1148New Mexico".
03 FILLER PIC X(18) VALUE "1547New York".
03 FILLER PIC X(18) VALUE "1237North Carolina".
03 FILLER PIC X(18) VALUE "1290North Dakota".
03 FILLER PIC X(18) VALUE "1256Ohio".
03 FILLER PIC X(18) VALUE "1155Oklahoma".
03 FILLER PIC X(18) VALUE "1309Oregon".
03 FILLER PIC X(18) VALUE "1352Pennsylvania".
03 FILLER PIC X(18) VALUE "1435Rhode Island".
03 FILLER PIC X(18) VALUE "1172South Carolina".
03 FILLER PIC X(18) VALUE "1206South Dakota".
03 FILLER PIC X(18) VALUE "1186Tennessee".
03 FILLER PIC X(18) VALUE "1244Texas".
03 FILLER PIC X(18) VALUE "1157Utah".
03 FILLER PIC X(18) VALUE "1374Vermont".
03 FILLER PIC X(18) VALUE "1607Virginia".
03 FILLER PIC X(18) VALUE "1487Washington".
03 FILLER PIC X(18) VALUE "1062West Virginia".
494
Chapter 18 ■ the COBOL repOrt Writer
03 FILLER PIC X(18) VALUE "1393Wisconsin".
03 FILLER PIC X(18) VALUE "1393Wyoming".
02 FILLER REDEFINES StateNameValues.
03 State OCCURS 50 TIMES.
04 BaseSalary PIC 9(4).
04 StateName PIC X(14).
01 MiscVariables.
02 SalesCommission PIC 9(5)V99.
02 Percentage PIC V99 VALUE .08.
02 FullSalary PIC 9(6)V99.
02 ActualStateNum PIC 99.
REPORT SECTION.
RD SolaceSalesReport
CONTROLS ARE FINAL
StateNum
SalesAgentNum
PAGE LIMIT IS 66
HEADING 1
FIRST DETAIL 6
LAST DETAIL 54
FOOTING 56.
01 TYPE IS PAGE HEADING.
02 LINE 1.
03 COLUMN 20 PIC X(32)
VALUE "Solace Solar Solutions".
02 LINE 2.
03 COLUMN 6 PIC X(51)
VALUE "Sales Agent - Sales and Salary Report Monthly Report".
02 LINE 4.
03 COLUMN 2 PIC X(5) VALUE "State".
03 COLUMN 16 PIC X(5) VALUE "Agent".
03 COLUMN 32 PIC X(8) VALUE "Value".
02 LINE 5.
03 COLUMN 2 PIC X(4) VALUE "Name".
03 COLUMN 16 PIC X(6) VALUE "Number".
03 COLUMN 31 PIC X(8) VALUE "Of Sales".
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.
495
Chapter 18 ■ the COBOL repOrt Writer
01 SalesAgentGrp
TYPE IS CONTROL FOOTING SalesAgentNum NEXT GROUP PLUS 2.
02 LINE IS PLUS 1.
03 COLUMN 15 PIC X(21) VALUE "Sales for sales agent".
03 COLUMN 37 PIC 999 SOURCE SalesAgentNum.
03 COLUMN 43 PIC X VALUE "=".
03 TotalAgentSales COLUMN 45 PIC $$$$$,$$$.99 SUM ValueOfSale.
02 LINE IS PLUS 1.
03 COLUMN 15 PIC X(19) VALUE "Sales commission is".
03 COLUMN 43 PIC X VALUE "=".
03 COLUMN 45 PIC $$$$$,$$$.99 SOURCE SalesCommission.
02 LINE IS PLUS 1.
03 COLUMN 15 PIC X(22) VALUE "Sales agent salary is".
03 COLUMN 43 PIC X VALUE "=".
03 COLUMN 45 PIC $$$$$,$$$.99 SOURCE FullSalary.
01 StateGrp TYPE IS CONTROL FOOTING StateNum NEXT GROUP PLUS 2.
02 LINE IS PLUS 2.
03 COLUMN 15 PIC X(15) VALUE "Total sales for".
03 COLUMN 31 PIC X(14) SOURCE StateName(StateNum).
03 TotalStateSales COLUMN 45 PIC $$$$$,$$$.99 SUM TotalAgentSales.
02 LINE IS PLUS 1.
03 COLUMN 15 PIC X(15) VALUE "Base salary for".
03 COLUMN 31 PIC X(14) SOURCE StateName(StateNum).
03 COLUMN 48 PIC $$,$$$.99 SOURCE BaseSalary(StateNum).
02 LINE IS PLUS 1.
03 COLUMN 15 PIC X(26)
VALUE "Actual state number is -".
03 COLUMN 42 PIC Z9 SOURCE ActualStateNum.
02 LINE IS PLUS 1.
03 COLUMN 15 PIC X(26)
VALUE "Supplied state number is -".
03 COLUMN 42 PIC Z9 SOURCE StateNum.
02 LINE IS PLUS 1.
03 COLUMN 1 PIC X(58) VALUE ALL "-".
01 TotalSalesGrp TYPE IS CONTROL FOOTING FINAL.
02 LINE IS PLUS 4.
03 COLUMN 15 PIC X(11)
VALUE "Total sales".
03 COLUMN 46 PIC X VALUE "=".
03 COLUMN 48 PIC $$,$$$,$$$.99 SUM TotalStateSales.
496
Chapter 18 ■ the COBOL repOrt Writer
01 TYPE IS PAGE FOOTING.
02 LINE IS 58.
03 COLUMN 1 PIC X(29) VALUE "Programmer - Michael Coughlan".
03 COLUMN 55 PIC X(6) VALUE "Page :".
03 COLUMN 62 PIC ZZ9 SOURCE PAGE-COUNTER.
PROCEDURE DIVISION.
DECLARATIVES.
Calc SECT
ION.
USE BEFORE REPORTING SalesAgentGrp.
Calculate-Salary.
MULTIPLY TotalAgentSales BY Percentage
GIVING SalesCommission ROUNDED
ADD SalesCommission, BaseSalary(StateNum)
GIVING FullSalary.
END DECLARATIVES.
Main SECTION.
Begin.
OPEN INPUT SalesFile
OPEN OUTPUT PrintFile
READ SalesFile
AT END SET EndOfFile TO TRUE
END-READ
INITIATE SolaceSalesReport
PERFORM PrintSalaryReport
UNTIL EndOfFile
TERMINATE SolaceSalesReport
CLOSE SalesFile, PrintFile
STOP RUN.
PrintSalaryReport.
GENERATE DetailLine
READ SalesFile
AT END SET EndOfFile TO TRUE
END-READ
MOVE StateNum TO ActualStateNum.
Example 18-5. Report Showing Commission Earned and Total Salary
Solace Solar Solutions
Sales Agent - Sales and Salary Report Monthly Report
State Agent Value
Name Number Of Sales
Alabama 038 $9,325.14
$11,839.19
$19,102.61
Sales for sales agent 038 = $40,266.94
Sales commission is = $3,221.36
Sales agent salary is = $4,370.36
497
Chapter 18 ■ the COBOL repOrt Writer
Alabama 073 $4,503.71
$11,659.87
$19,540.19
Sales for sales agent 073 = $35,703.77
Sales commission is = $2,856.30
Sales agent salary is = $4,005.30
Total sales for Alabama $75,970.71
Base salary for Alabama $1,149.00
Actual state number is - 2
Supplied state number is - 1
----------------------------------------------------------
Alaska 055 $18,981.84
$3,065.97
$10,686.92
Sales for sales agent 055 = $32,734.73
Sales commission is = $2,618.78
Sales agent salary is = $4,154.78
Alaska 089 $11,187.72
$14,145.82
Sales for sales agent 089 = $25,333.54
Sales commission is = $2,026.68
Sales agent salary is = $3,562.68
Alaska 104 $18,005.42
$17,614.20
Sales for sales agent 104 = $35,619.62
Sales commission is = $2,849.57
Sales agent salary is = $4,385.57
Total sales for Alaska $93,687.89
Base salary for Alaska $1,536.00
Actual state number is - 3
Supplied state number is - 2
----------------------------------------------------------
Programmer - Michael Coughlan Page : 1
The major differences between Listing 18-2 and Listing 18-3 are shown in bold. To print the agent commission and total salary, I have added a number of entries to SalesAgentGrp. Note, though, that the sources of these items are data items declared outside the REPORT SECTION. The reason is that these items require calculations beyond what the Report Writer can handle automatically. To calculate these items, you must use declaratives. I discuss declaratives presently; but for now, I want to discuss another issue.
Look at the StateGrp CONTROL FOOTING and in particular at these lines:
03 COLUMN 31 PIC X(14) SOURCE StateName(StateNum).
03 COLUMN 48 PIC $$,$$$.99 SOURCE BaseSalary(StateNum).
498
Chapter 18 ■ the COBOL repOrt Writer
Notice anything strange? This footer is printed when there is a control break on StateNum—in other words, when the value of StateNum changes. This means StateNum in the previous lines should refer to the next state and not the one for which the totals have just been accumulated. And yet, if you examine the report, you see that the correct state name and base salary are printed. How can this be? Remember this:
In a CONTROL FOOTING or in the DECLARATIVES SECTION, when a control data item is
referenced, the value supplied is the previous value and not the value that has just
caused the control break.
To emphasize this point, I have printed the actual state number value (the one in the record buffer) and the state number supplied by the Report Writer. To get the actual state number, each time a record is read, the StateNum in the record is moved to the ActualStateNum in the WORKING-STORAGE SECTION. This data item is used as a SOURCE when the CONTROL FOOTING is printed.
Report Writer Declaratives
The Report Writer is a wonderful tool if the structure of the required report fits the way the Report Writer does things. But sometimes the structure or requirements of a report are such that the standard Report Writer alone is not sufficient. In these cases, you can use declaratives to extend the functionality of the Report Writer.
The USE BEFORE REPORTING phrase allows code specified in the declaratives to be executed just before the
report group mentioned in the USE BEFORE REPORTING phrase is printed. The code in the declaratives extends 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).
In Listing 18-3, declaratives are used to calculate SalesCommission and FullSalary before SalesAgentGrp is printed.
Report Writer Syntax and Semantics
I have shown you a number of example programs that use the Report Writer. That informal introduction should have given you a good idea of the new verbs and declarations required when you write a Report Writer program. This section deals with the syntax and semantics of Report Writer elements.
ENVIRONMENT DIVISION Entries
Just like ordinary reports, the reports generated by the Report Writer are written to an external device—usually a report file. The ENVIRONMENT DIVISION entries for a report file are the same as those for an ordinary file. The same SELECT and ASSIGN clauses apply. You can either omit the ORGANIZATION phrase as in the example programs, in which case the default of ORGANIZATION IS SEQUENTIAL applies, or you can specify ORGANIZATION IS SEQUENTIAL explicitly, as in the following example:
FILE-CONTROL.
SELECT SalesFile ASSIGN TO "Listing18-4-Sales.DAT"
ORGANIZATION IS LINE SEQUENTIAL.
SELECT PrintFile ASSIGN TO "Listing18-4.Rpt"
ORGANIZATION IS SEQUENTIAL.
499
Chapter 18 ■ the COBOL repOrt Writer
FILE SECTION Entries
The entries in the ENVIRONMENT DIVISION are the same as those for ordinary print files. But in the FILE SECTION, the normal file description is replaced by the REPORT IS phrase, which points to the RD in the REPORT SECTION. The metalanguage for the phrase is
where ReportName must be the same as the ReportName used in the RD entry. You can see this in Listing 18-3, where the REPORT IS SolaceSalesReport phrase links the PrintFile with the RD in the REPORT SECTION.
Note that before the report can be used, it must be opened for output. For instance, in Listing 18-3, the PrintFile is opened for output before the SolaceSalesReport is generated.
Report Description (RD) Entries
The RD entry in the REPORT SECTION defines the report. There must be a separate RD entry for each report you want to print. The RD entry names the report, specifies the format of the printed page, and identifies the control-break items.
Each RD entry is followed by one or more 01 level-number entries. Each 01 level-number entry identifies a report group and consists of a hierarchical structure similar to a COBOL record. Each report group is a unit consisting of one or more print lines and cannot be split across pages. The metalanguage for the RD is given in Figure 18-2.
Figure 18-2. Metalanguage for the Report Description (RD) entr
y
Keep the following points in mind:
• ReportName can appear in only one RD entry.
• When more than one report is declared in the REPORT SECTION, ReportName may be used to
qualify the LINE-COUNTER and PAGE-COUNTER report registers.
• ControlName$#i must not be a data item defined in the REPORT SECTION.
• Each occurrence of ControlName$#i must identify a different data item.
500
Chapter 18 ■ the COBOL repOrt Writer
• ControlName$#i must not have a variable-length table subordinate to it.
• ControlName$#i and FINAL specify the levels of the control-break hierarchy, where FINAL (if
specified) is the highest, the first ControlName$#i is the next highest, and so on.
• When the value in any ControlName$#i changes, a control break occurs. The level of the
control break depends on the position of the ControlName$#i in the control-break hierarchy.
• HeadingLine#l must be greater than or equal to 1.
• The following must hold: HeadingLine#l <= FirstDetailLine#l <= LastDetailLine#l <=
FootingLine#l <= PageSize#l
• The line numbers used in a REPORT HEADING or PAGE HEADING group must be greater than or
equal to HeadingLine#l and less than FirstDetailLine#l. But when a REPORT HEADING appears
on a page by itself, any line number between HeadingLine#l and PageSize#l may be used.
• The line numbers used in a DETAIL or CONTROL HEADING group must be in the range
FirstDetailLine#l to LastDetailLine#l, inclusive.
• The line numbers used in CONTROL FOOTING groups must be in the range FirstDetailLine#l
to FootingLine#l, inclusive.
• The line numbers used in a REPORT FOOTING or PAGE FOOTING group must be greater than
FootingLine#l and less than or equal to PageSize#l. But when a REPORT FOOTING appears on
a page by itself, any line number between HeadingLine#l and PageSize#l may be used.
• All the report groups must be defined so that they can be presented on one page. The Report
Writer never splits a multiline group across page boundaries.
Report Group Entries
The RD entry specifies the name of the report, identifies the control items, and lays down the basics of how the page is to be formatted. After the RD entry, you specify the report groups to be used in the report. Each report group is represented by a report-group record. As with all record descriptions in COBOL, a report-group record starts with level number 01. The subordinate items in the record describe the report lines and columns in the report group.