A GENERATE SALES-DETAIL statement does more than write one output record. The Report Writer Control System selects the applicable report groups, places source values in their columns, handles page boundaries, and prints control footings when a control value changes.
On current IBM Enterprise COBOL for z/OS, Report Writer source requires the optional COBOL Report Writer Precompiler. The compiler does not directly accept the older Report Writer language items. Check that requirement before copying a REPORT SECTION example into a production program.
What COBOL Report Writer Does
Report Writer separates report layout from the record-reading loop. You describe the report in the REPORT SECTION, associate that report with an output file, and call Report Writer statements from the PROCEDURE DIVISION. The facility can manage page headings, detail lines, control headings and footings, page numbering, line placement, edited numeric fields, and accumulated totals.
It does not fetch business data for you. The program still opens files, reads input records, checks file status, handles end of file, and supplies the values referenced by report groups.
Report Writer Processing Flow
- Define the report output file in the
FILE SECTION. - Describe the report and its groups in the
REPORT SECTION. - Open the input and report files.
- Run
INITIATEfor the report. - Read an input record and run
GENERATEfor its detail group. - Run
TERMINATEafter the final record, then close the files.
Core Report Writer Entries and Statements
| Item | Where it appears | Purpose |
|---|---|---|
REPORT IS | Output-file FD | Associates a file with a report description. |
RD | REPORT SECTION | Names the report and sets page and control rules. |
TYPE | Report-group entry | Identifies a page heading, detail line, or control group. |
SOURCE | Printable field | Moves a program data item into the report field. |
SUM | Printable numeric field | Maintains and prints a report total. |
INITIATE, GENERATE, TERMINATE | PROCEDURE DIVISION | Starts, feeds, and ends report processing. |
COBOL Report Writer Example
The following shortened example shows the structure of a departmental sales report. Exact options can differ by Report Writer level, so compile the sample against the precompiler installed at your site.
File and report definitions
FILE SECTION.
FD SALES-IN.
01 SALES-RECORD.
05 IN-DEPT PIC X(04).
05 IN-EMPLOYEE PIC X(20).
05 IN-AMOUNT PIC 9(7)V99.
FD SALES-REPORT-FILE
REPORT IS SALES-REPORT.
REPORT SECTION.
RD SALES-REPORT
CONTROLS ARE FINAL IN-DEPT
PAGE LIMIT IS 60 LINES
FIRST DETAIL 6
LAST DETAIL 55.
01 SALES-PAGE-HEADING TYPE PAGE HEADING.
03 COLUMN 1 PIC X(25)
VALUE "DEPARTMENT SALES REPORT".
03 COLUMN 70 PIC Z9 SOURCE PAGE-COUNTER.
01 SALES-DETAIL TYPE DETAIL.
03 COLUMN 1 PIC X(04) SOURCE IN-DEPT.
03 COLUMN 10 PIC X(20) SOURCE IN-EMPLOYEE.
03 COLUMN 40 PIC $$$,$$$,$$9.99 SOURCE IN-AMOUNT.
01 DEPT-TOTAL TYPE CONTROL FOOTING IN-DEPT.
03 COLUMN 10 PIC X(17) VALUE "DEPARTMENT TOTAL".
03 COLUMN 40 PIC $$$,$$$,$$9.99 SUM IN-AMOUNT.Procedure Division sequence
OPEN INPUT SALES-IN
OUTPUT SALES-REPORT-FILE
INITIATE SALES-REPORT
PERFORM UNTIL END-OF-FILE
READ SALES-IN
AT END
SET END-OF-FILE TO TRUE
NOT AT END
GENERATE SALES-DETAIL
END-READ
END-PERFORM
TERMINATE SALES-REPORT
CLOSE SALES-IN SALES-REPORT-FILEEach successful read makes the current input fields available to SALES-DETAIL. When IN-DEPT changes, Report Writer prints the control footing and resets the applicable sum. Page headings are emitted when a new page is required.
Report Group Types
- PAGE HEADING: printed at the top of a report page.
- DETAIL: normally generated once for each selected input record.
- CONTROL HEADING: printed when a control group begins.
- CONTROL FOOTING: printed when a control value changes or final processing occurs.
A control clause detects a change; it does not sort the input. If departmental totals must be contiguous, sort the data by department before the reporting step. See SORT in COBOL for the program-level sort flow.
Using Report Writer with Enterprise COBOL
IBM documents three practical paths for older Report Writer applications: keep the source and run it through the precompiler, use the precompiler to convert the source permanently to Enterprise COBOL statements, or continue running an existing OS/VS COBOL-compiled module under Language Environment where the documented restrictions permit it.
The precompiler can check Report Writer statements, process COPY members containing those statements, create a consolidated listing, and convert the Report Writer source into COBOL accepted by Enterprise COBOL. For Enterprise COBOL 5.1 or later, IBM requires Report Writer Precompiler 1.6.01 or later.
IGZPROUT DD statement.
Common COBOL Report Writer Mistakes
Assuming CONTROLS sorts input
Control processing depends on the sequence of records presented to Report Writer. Sort the input or read it through an access path that supplies the required order.
Compiling Report Writer statements directly
Enterprise COBOL does not directly implement the Report Writer statements listed in IBM's migration guidance. Route the source through the optional precompiler or convert the program.
Generating after end of file
Place GENERATE only in the successful-read branch. Otherwise, the last input values can be processed again after the end-of-file condition.
Skipping TERMINATE
Run TERMINATE before closing the report file. Final control footings and other end-of-report groups depend on report termination.
Ignoring edited numeric capacity
Confirm that the report PIC can display the largest expected amount and sign. A format that is too small can replace digits with asterisks or create output that cannot be reconciled. The COBOL PICTURE clause guide explains display and edited fields.
Production Checklist
- Confirm the installed Report Writer Precompiler version and local compile procedure.
- Verify the input sort sequence for every control field.
- Check the FD-to-RD association and output DD allocation.
- Exercise page overflow, control breaks, zero-detail input, maximum values, and final totals.
- Check file status after input operations; refer to the COBOL FILE STATUS guide.
- Review the generated COBOL and the consolidated listing when diagnosing a precompile failure.
Frequently Asked Questions
Does Enterprise COBOL support REPORT SECTION directly?
No. IBM supports the Report Writer feature for Enterprise COBOL through the optional COBOL Report Writer Precompiler and Libraries.
Does the CONTROLS clause sort records?
No. It defines control-break processing. Input records must already arrive in the required control-field sequence.
What is the normal statement sequence?
Open the files, run INITIATE, run GENERATE for each selected record, run TERMINATE, and then close the files.
Can Report Writer source be converted permanently?
Yes. IBM states that the precompiler can run in stand-alone mode and convert Report Writer statements into non-Report Writer COBOL source accepted by Enterprise COBOL.
IBM References
- IBM: Report Writer support in Enterprise COBOL
- IBM: COBOL Report Writer Precompiler
- IBM: Enterprise COBOL industry specifications
Treat the precompiler and the input sort sequence as part of the program design. If either is missing, a correct-looking REPORT SECTION will not produce the expected report.
