There are three Compaq COBOL programming capabilities for producing formatted reports: conventional, linage file, and Report Writer. This chapter presents the following topics to help you format and produce reports:

• Designing a report ( Section 10.1)
• Components of a report ( Section 10.2)
• Methods of reporting accumulation and control totals ( Section 10.3)
• The logical page and the physical page ( Section 10.4)
• Programming a conventional file report ( Section 10.5)
• Programming a linage-file Compaq COBOL report ( Section 10.6)
• Modes for printing reports ( Section 10.7)
• Programming a Report Writer report ( Section 10.8)
• Report Writer examples ( Section 10.9)
• Solving report problems ( Section 10.10)

The design of a report is dictated by the data you must include in the report. If you have a general idea of what the report is to contain, you can produce a rough outline using a report layout worksheet.

To create the worksheet, either use an online text editor or draw a layout worksheet like the one displayed in Figure 10-1.

Figure 10-1 Sample Layout Worksheet

The layout worksheet in Figure 10-1 has 132 characters on a line and 60 lines on a page. When you outline your worksheet, include specifics such as page headings, rows and columns, and column sizes.

Section 10.2 describes other report components that you must plan for when you design a report. Note that you can use your worksheet later when you write the Compaq COBOL program that produces the report.

10.2 Components of a Report

There are seven components of a report. Example 10-1 illustrates them.

Example 10-1 Components of a Report

(1) ********************** COMPANY CONFIDENTIAL ********************** ********************** COMPANY CONFIDENTIAL ********************** ********************** COMPANY CONFIDENTIAL ********************** ****************** * * * YEAR TO DATE * * SALES REPORT * * * ****************** FOR INTERNAL USE ONLY DO NOT COPY FOR SECURITY CLEARANCE LEVELS 1, 2, AND 3 ********************** COMPANY CONFIDENTIAL ********************** ********************** COMPANY CONFIDENTIAL ********************** (1) ********************** COMPANY CONFIDENTIAL ********************** . . . (2) 04-NOVEMBER-96 Year To Date Sales Report Page 1 Salesman Salary/Bonus Client Name Client Address Total Sales (3) ************************ JANUARY REPORT ************************** (4) SMITH $30,000.00 STREN 2742 NORTH ST. $225,000.00 JOHN $10,000.00 TOM MANCHESTER, NH . . . . . . . . . . (4) . . . . . (5) TOTAL JANUARY SALES: $ 2,000,000.00 ****************************************************************** ************************ FEBRUARY REPORT ************************* . . . . . . . . . . . . . . . (6) ********************** COMPANY CONFIDENTIAL ********************** ********************** COMPANY CONFIDENTIAL ********************** ********************** COMPANY CONFIDENTIAL ********************** (6) <<<<<<<<<<<<<<<<<<<<<<<CONTINUED ON NEXT PAGE>>>>>>>>>>>>>>>>>>>>> . . . 04-NOVEMBER-96 Year To Date Sales Report Page 1324 (7) ********************** COMPANY CONFIDENTIAL ********************** ********************** COMPANY CONFIDENTIAL ********************** ********************** COMPANY CONFIDENTIAL ********************** ****************** * * * END OF * * YEAR TO DATE * * SALES REPORT * * * ****************** Total Records: 123456 Total Salesmen: 6754 Total Sales: $123,456,789.99 Total Salaries: $ 9,876,543.21 Total Bonus: $ 6,789,012.34 Total Report Pages: 1324 ********************** COMPANY CONFIDENTIAL ********************** ********************** COMPANY CONFIDENTIAL ********************** (7) ********************** COMPANY CONFIDENTIAL **********************

The numbers in the following list correspond to the circled numbers in Example 10-1:

1. Report Heading (RH)---The report heading (the lines marked with 1 and all the lines between) consists of information printed before the main body of a report. It can be printed on a separate page, or as the first page heading, with the remaining page headings abbreviated to save paper. The report heading can include information such as handling and distribution instructions. It can also include the selection criteria, sort order, and assumptions made when creating the report.
2. Page Heading (PH)---The page heading (the line marked with 2 and the line following) consists of information printed on the top one or more lines of every page in the report. It usually names and dates the report, gives the report page number, and produces a title for each column of information in the detail line.
3. Control Heading (CH)---The control heading consists of one or more lines of information identifying the beginning of a new logical area on a page.
4. Detail Lines (DL)---The detail (the lines marked with 4 and all the lines between) consists of one or more lines of the primary data of the report.
5. Control Footing (CF)---The control footing (the line marked with 5 and the following line) consists of one or more lines of information identifying the end of a logical area. The control footing can contain one or more totals and an accompanying message.
6. Page Footing (PF)---The page footing (the lines marked with 6 and all the lines between) consists of one or more lines of information at the bottom of each page.
7. Report Footing (RF)---The report footing (the lines marked with 7 and all the lines between) consists of information printed after the main body of the report. It can be continued on the same page of the report body, or it can be on a separate page. It may contain information such as hash or control totals. A report footing is a convenient place to print run-time statistics, such as the number of records read and written for each file. It can also provide warning messages, such as when a table is close to overflowing.
   It is suggested that all reports have an END OF REPORT message or other indicator at the end of the report, so that you can tell at a glance that you have all the pages. (The consecutive page numbers tell if a page is missing, but they do not indicate which page is the last.)

Your program can report three types of totals in the control footings and report footings of your report:

• Subtotals---Subtotaling is the process of summing a detail item from each detail line. For example, in Figure 10-2, Salary, Bonus, and Total Sales are subtotaled. To get the first salary subtotal for January on page 1 ($75,000.00), the program must add each salesman's salary ($30,000+$25,000+$20,000). After printing the salary total, the program must zero the total to begin subtotaling for the next month.
• Crossfoot Totals---Crossfooting is the process of summing subtotals from a common group of totals. For example, in Figure 10-2, TOTAL SALARY EXPENSE is crossfooted by adding TOTAL SALARY and TOTAL BONUS. To get the first TOTAL SALARY EXPENSE crossfoot total for the January report, the program must add the salary subtotal and the bonus subtotal before the program clears the subtotals.
• Rolled Forward Totals---Rolling-forward is the process of summing either subtotals or crossfoot totals. For example, in Figure 10-2, the YEAR TO DATE TOTALS at the bottom of page 1 are rolled forward from both the JANUARY and FEBRUARY totals. The program computes the salary and bonus YEAR TO DATE TOTALS from the previous salary and bonus subtotals. It computes the total salary expense figure from the previous total salary expense crossfoot totals.

Figure 10-2 Subtotals, Crossfoot Totals, and Rolled Forward Totals

A physical page is the paper page printed by your printer.

A logical page is conceptual, consisting of a page body and optionally a top margin, footing, and bottom margin. Figure 10_3 and Figure 10-6 illustrate the logical page structure for the conventional file report and linage file report, respectively.

The number of lines on a logical page is defined by the number of lines on the target physical page. Thus, the number of lines determines the size of the logical page. When you design a report, you must choose those lines within the logical page that are to be page headers (PH), control headers (CH), detail lines (DL), control footings (CF), and page footings (PF). Once the framework of the logical page is defined, your program must stay within those bounds; otherwise, the printed report may not contain the correct information.

You can program two types of reports: a conventional file report or a linage file report. Section 10.5 and Section 10.5.1 discuss these reports in detail.

10.5 Programming a Conventional File Report

A conventional file report is contained in a file that has sequential organization and access mode, and that contains variable-length with fixed control records. This type of report consists of one or more logical pages. The program that produces the report uses ordinary syntax for writing sequential files, for example, OPEN, WRITE...AFTER ADVANCING, and CLOSE statements. The conventional report does not use linage or Report Writer facilities.

To program a conventional report, you should understand how to do the following:

• Define the logical page.
• Advance to the next logical page.
• Program for the page-overflow condition.
• Use a line counter.

The following sections discuss these topics in detail. Additionally, Section 10.5.5 contains an example of a Compaq COBOL program that produces a conventional file report.

10.5.1 Defining the Logical Page in a Conventional Report

Your program specifies the format of your report. Using the report layout worksheet you created, you can write a Compaq COBOL program that defines the logical page area for a conventional report. Figure 10-3 shows the logical page area for a conventional report. The conventional report logical page area consists of the page areas discussed in Section 10.4.

Figure 10-3 Logical Page Area for a Conventional Report

Once you have defined the logical page, you must handle vertical spacing, horizontal spacing, and the number of lines that appear on each page so that you can advance to the next logical page. The following sections discuss these subjects.

10.5.2 Controlling the Spacing in a Conventional Report

To control the horizontal spacing on a logical page, define every report item from your report layout worksheet in the Working-Storage Section of your Compaq COBOL program.

To control the vertical spacing on a logical page, use the WRITE statement. The WRITE statement controls whether one or more lines are skipped before or after your program writes a line of the report. For example, to print a line before advancing five lines, use the following:

WRITE... BEFORE ADVANCING 5 LINES.

To print a line after advancing two lines, use the following:

WRITE... AFTER ADVANCING 2 LINES.

10.5.3 Advancing to the Next Logical Page in a Conventional Report

To advance to the next logical page and position the printer to the page heading area, you must be able to track the number of lines that your program writes on a page. The Compaq COBOL compiler lets you control the number of lines written on a page with the WRITE statement.

The WRITE statement must appear in your Procedure Division and it should contain either the AFTER ADVANCING PAGE or BEFORE ADVANCING PAGE clause. Example 10-3 demonstrates the use of the WRITE statement with the AFTER ADVANCING PAGE clause.

The next two sections discuss how to handle a page-overflow condition and how to use a line counter to keep track of the number of lines your program writes on a logical page.

10.5.3.1 Programming for the Page-Overflow Condition in a Conventional Report

A page-overflow condition occurs when your program writes more lines than the logical page can accommodate. This normal condition lets your program know when to execute its top-of-page routines. Top-of-page routines should contain WRITE statements with either the AFTER ADVANCING PAGE or BEFORE ADVANCING PAGE clause.

These statements determine when a report's logical page is full, and when the program prints the last line on a logical page (if you do not want to use all the lines on a page). Example 10-2 shows two methods that check for the page-overflow condition:

• Paragraph A100-FIRST-REPORT-ROUTINES checks for a full page after it writes a report line. If the page-overflow condition exists, A901-HEADER-ROUTINE executes.
• Paragraph A500-SECOND-REPORT-ROUTINES checks if more than 50 lines exist on the current logical page. If more than 50 lines exist, A902-HEADER-ROUTINE executes.

In either case, the AFTER ADVANCING PAGE clause in the A901-HEADER-ROUTINE and A902-HEADER-ROUTINE paragraphs generates the characters needed for the printer to position itself at the top of the next page heading area.

Example 10-2 Checking for the Page-Overflow Condition

. . . PROCEDURE DIVISION. A000-BEGIN. . . . A100-FIRST-REPORT-ROUTINES. * * A901-HEADER-ROUTINE executes whenever the number of lines written exceeds * the number of lines on the 66-line default logical page. * WRITE A-LINE1 AFTER ADVANCING 2 LINES. ADD 2 TO REPORT1-LINE-COUNT. IF REPORT1-LINE-COUNT > 65 PERFORM A901-HEADER-ROUTINE. . . . A500-SECOND-REPORT-ROUTINES. * * This routine uses only the first 50 lines of the 66-line report. * WRITE A-LINE2 AFTER ADVANCING 2 LINES. ADD 2 TO REPORT2-LINE-COUNT. IF REPORT2-LINE-COUNT IS GREATER THAN 50 PERFORM A902-HEADER-ROUTINE. . . . A901-HEADER-ROUTINE. WRITE A-LINE1 FROM REPORT1-HEADER-LINE-1 AFTER ADVANCING PAGE. MOVE 0 TO REPORT1-LINE-COUNT. ADD 1 TO REPORT1-LINE-COUNT. . . . A902-HEADER-ROUTINE. WRITE A-LINE2 FROM REPORT2-HEADER-LINE-1 AFTER ADVANCING PAGE. MOVE 0 TO REPORT2-LINE-COUNT. ADD 1 TO REPORT2-LINE-COUNT. . . .

Although the WRITE statement allows you to check for a page-overflow condition, you can also use a line counter that tracks the number of lines that appear on a page. Section 10.5.3.2 describes this in more detail.

10.5.3.2 Using a Line Counter

A line counter is another method of tracking the number of lines that appear on a page. If you define a line counter in the Working-Storage Section of your program, each time a line is written or skipped the line counter value is incremented by one.

Your program should contain a routine that checks the line counter value before it writes or skips the next line. If the value is less than the limit you have set, it writes or skips. If the value equals or exceeds the limit you have set, the program executes header routines that allow it to advance to the next logical page.

10.5.4 Printing the Conventional Report

When you are ready to print your report, you must ensure that your system's line printer can accommodate the page size or form of your report. If the printer uses a different page size or form, contact your system manager. The system manager can change the page or form size to accommodate your report.

Section 10.7 describes the different modes for printing a report.

10.5.5 A Conventional File Report Example

Example 10-3 shows a Compaq COBOL program that produces two reports from the same input file.

Example 10-3 Page Advancing and Line Skipping

IDENTIFICATION DIVISION. PROGRAM-ID. REP01. ENVIRONMENT DIVISION. INPUT-OUTPUT SECTION. FILE-CONTROL. SELECT INPUT-FILE ASSIGN TO "REPIN.DAT". SELECT FORM1-REPORT ASSIGN TO "FORM1.DAT". SELECT FORM2-REPORT ASSIGN TO "FORM2.DAT". DATA DIVISION. FILE SECTION. FD INPUT-FILE. 01 INPUT-RECORD. 02 I-NAME. 03 I-FIRST PIC X(10). 03 I-MID PIC X. 03 I-LAST PIC X(15). 02 I-ADDRESS. 03 I-STREET PIC X(20). 03 I-CITY PIC X(15). 03 I-STATE PIC XX. 03 I-ZIP PIC 99999. FD FORM1-REPORT. 01 FORM1-PRINT-LINE PIC X(80). FD FORM2-REPORT. 01 FORM2-PRINT-LINE PIC X(80). WORKING-STORAGE SECTION. 01 END-OF-FILE PIC X VALUE SPACE. 01 MAX-LINES-ON-FORM2 PIC 99 VALUE 55. 01 FORM2-LINE-COUNTER PIC 99 VALUE 00. 01 PAGE-NO PIC 99999 VALUE 0. 01 FORM1-LINE-3. 02 PIC X(9) VALUE SPACES. 02 FORM1-LAST PIC X(15). 01 FORM1-LINE-13. 02 PIC X(4) VALUE SPACES. 02 FORM1-NAME PIC X(26). 01 FORM1-LINE-14. 02 PIC X(4) VALUE SPACES. 02 FORM1-STREET PIC X(20). 01 FORM1-LINE-15. 02 PIC X(4) VALUE SPACES. 02 FORM1-CITY PIC X(15). 02 PIC X VALUE SPACE. 02 FORM1-STATE PIC XX. 02 PIC X VALUE SPACE. 02 FORM1-ZIP PIC 99999. 01 FORM2-HEADER-1. 02 PIC X(15) VALUE SPACES. 02 PIC X(30) VALUE " PERSONNEL MASTER LISTING ". 02 PIC X(10) VALUE SPACES. 02 PIC XXXXX VALUE "Page ". 02 F2H-PAGE PIC ZZZZZ. 01 FORM2-HEADER-2. 02 PIC X(15) VALUE SPACES. 02 PIC X(30) VALUE "**** COMPANY CONFIDENTIAL ****". PROCEDURE DIVISION. A000-BEGIN. OPEN INPUT INPUT-FILE OUTPUT FORM1-REPORT FORM2-REPORT. PERFORM A900-PRINT-HEADERS-ROUTINE. PERFORM A100-PRINT-REPORTS UNTIL END-OF-FILE = "Y". CLOSE INPUT-FILE FORM1-REPORT FORM2-REPORT. DISPLAY "END OF JOB". STOP RUN. A100-PRINT-REPORTS. READ INPUT-FILE AT END MOVE "Y" TO END-OF-FILE. IF END-OF-FILE NOT = "Y" PERFORM A200-PRINT-REPORTS. A200-PRINT-REPORTS. IF FORM2-LINE-COUNTER IS GREATER THAN MAX-LINES-ON-FORM2 PERFORM A900-PRINT-HEADERS-ROUTINE. WRITE FORM2-PRINT-LINE FROM INPUT-RECORD AFTER ADVANCING 2 LINES. ADD 2 TO FORM2-LINE-COUNTER. MOVE I-LAST TO FORM1-LAST. WRITE FORM1-PRINT-LINE FROM FORM1-LINE-3 AFTER ADVANCING 3 LINES. MOVE I-NAME TO FORM1-NAME. WRITE FORM1-PRINT-LINE FROM FORM1-LINE-13 AFTER ADVANCING 10 LINES. MOVE I-STREET TO FORM1-STREET. WRITE FORM1-PRINT-LINE FROM FORM1-LINE-14. MOVE I-CITY TO FORM1-CITY. MOVE I-STATE TO FORM1-STATE. MOVE I-ZIP TO FORM1-ZIP. WRITE FORM1-PRINT-LINE FROM FORM1-LINE-15. A900-PRINT-HEADERS-ROUTINE. * * This routine generates a form feed, writes two lines, * skips two lines, then resets the line counter to 4 to * indicate used lines on the current logical page. * Line 5 on this page is the next print line. * ADD 1 TO PAGE-NO. MOVE PAGE-NO TO F2H-PAGE. WRITE FORM2-PRINT-LINE FROM FORM2-HEADER-1 AFTER ADVANCING PAGE. WRITE FORM2-PRINT-LINE FROM FORM2-HEADER-2 BEFORE ADVANCING 2. MOVE 4 TO FORM2-LINE-COUNTER.

The first report, Figure 10-4, is a preprinted form letter that can be inserted into a business envelope. This report has a logical page length of 20 lines and a width of 80 characters. Note that this report uses only the first 15 lines on the page. Because this is a preprinted form, the program supplies only the following information:

• The date for line 3
• The customer's name for lines 3 and 13
• The customer's address for lines 14 and 15

Figure 10-4 A 20-Line Logical Page

The second report, Figure 10-5, is a double-spaced master listing of all input records. While this report's logical page is identical to the default logical page for the system (in this case, 66 vertical lines and 132 horizontal characters), this report uses only the first 55 lines on the page. Both reports are output to a disk for later printing.

Figure 10-5 A Double-Spaced Master Listing