Multiple Reports

COBOL-IT Report Writer provides a means for producing either one physical file from several reports, or several physical files from one report description. The following sections describe each case:

Several Reports to One Physical File

This is indicated when you write the clause REPORTS ARE report-name-1 report-name-2 ... in the FD entry for the report file. The different reports may be written either successively, alternately, or concurrently to the file.

Successive Reports

This describes the case when each successive report is processed through from INITIATE to the final TERMINATE and is then not accessed again:

This method is free of complications and has useful applications. One example is the case where a report has a front section or a trailing section, too complex too describe as a REPORT HEADING or REPORT FOOTING:

The "Report Heading" might have several parts, and the "Report Footing" might have many complex parts, totals, etc. You might instinctively try to describe this complex layout using a single RD, because it has been designed as a single report. Remembering that a "report file" may be composed of several "logical reports", you now re-code the layout using three RDs:

and code the INITIATE, all the GENERATEs and the TERMINATE for each report in tandem. Assuming that each RD has a PAGE clause, each report will begin on a new page, as required.

This example assumes that you have no page numbering in the "Report Heading" or "Report Footing", and that you start with a page number of one in the main report. If you do require page numbering throughout, remember that each report has its own separate PAGE-COUNTER. Assuming that the page numbers are to run in sequence throughout the report, you must carry forward the PAGE-COUNTER after each TERMINATE, as follows:

Alternating-Page-Format Reports

You may encounter the case where a report consists of two or more alternating page formats, such as details of area A...summary page for area A details of area B...summary page for area B..., where each page format begins on a fresh page and has different PAGE HEADING, PAGE FOOTING and body groups from the others:

When approaching this problem, keep in mind the points made under Successive Reports above. This time, we keep both reports initiated. (If not, the page numbering will return to 1 after each INITIATE, and there will be problems if, say, we want to produce grand totals at the end of the reports.) The following is one possible solution.

An alternative solution is to use an expression made up from both PAGE-COUNTERs, for example:

Because you are not doing a TERMINATE and INITIATE on each occasion that you "switch reports", they will not necessarily always resume on a fresh page. Consider each report separately and decide how you would make it resume on a fresh page if the other report were not there. For example, you might begin after each "switch" with a GENERATE of a DETAIL group with a low absolute LINE number; or you might use the NEXT GROUP NEXT PAGE clause in a dummy CONTROL HEADING; or you might simply code MOVE footing-integer TO LINE-COUNTER IN next-report-name before resuming.

Concurrent Reports

There are two quite unconnected cases to discuss here:

One report built up from several alternating RD's

Here, you GENERATE output via two or more RDs associated with the samereport file without necessarily waiting for a page advance before switching fromone report to another. It can be difficult to use this method, because eachreport keeps its own LINE-COUNTER and control break information. Each reportwill therefore act as though it alone had control of the page format. Although no serious breakdown is likely at run time, you will have to take special steps toensure that pages terminate at the correct point. To do this, you will need toMOVE one LINE-COUNTER to another in much the same way that the PAGE-COUNTERs are dovetailed in the section on "Successive Reports" above. If you specify the same control-ids in each report, remember that each possible control break will occur in each report separately, when it is GENERATEd.

Distinct reports spooled to the same file

Here, several reports are written to the same file but are distinguished by meansof the CODE (see CODE clause). This technique was commonly used in thepast when print data was spooled onto tape or disk. Several reports could bewritten to the same spool file by marking the print records of each report with anidentifying character, characters, or identifier of any length. De-spooling software then passed through the spool file, each time selecting only those print records beginning with a certain identifying character. (It was possible to sortthe records, but this is usually much less efficient.) As example, you might have had two reports:

The reports were both written to the same file, but you there was no problem in separating them as the reports eventually appeared as separate outputs, thanks to their distinguishing codes. A utility to separate and print the physical reports is not provided as a part of the report writer software, and users who developed a utility program to handle the output produced by OS/VS and DOS/VS COBOL's built-in report writer with a CODE clause should use the same program to handle the output from report writer.

Several Outputs From the Same RD

There are two cases to be reviewed for this topic:

Identical copies of the same physical report

Following the ANS-74/85 standards, report writer does not allow you to assign your report to more than one file. This is more restrictive than the ANS-68standard used in OS/VS and DOS/VS COBOL, which allows up to two files. If you require two or more identical copies of the same physical report, you should try to achieve this through Operating System commands, or you should write an Independent Report File Handler (seeIndependent Report File Handlers) that executes a WRITE for each of several files for each report line.

Different reports with similar formats going to different files

In a program with several reports, you may find that two or more report layouts are identical, or nearly so, and you naturally want to avoid duplication of code.The DUPLICATED clause is designed for this purpose. The following diagram shows a case with three files.

Although the layouts are similar, the contents of the reports may be quite different (as distinct from case a where all output is simply printed twice). The DUPLICATED clause (see Report Files) sets up the given number of separate report control areas, each with its own PAGE-COUNTER, LINE-COUNTER , totals, control break indicators, Page Buffer, etc. They are distinguished by the value of the special register REPORT-NUMBER which is defined by report writer in every program that has a DUPLICATED clause. You may "switch" output to your selected report by storing a value from 1 to the maximum number of duplicates in REPORT-NUMBER. Output goes to only one of the reports at any given time. Although there are several separate physical files, only one SELECT clause and one FD entry are coded, and one OPEN and CLOSE is executed. Despite your own OPEN statement, a file is actually opened only when the report whose number is held in REPORT-NUMBER is first INITIATEd.

If REPORT-NUMBER is zero when the INITIATE is executed, all the reports are INITIATEd. The CLOSE operation (not the TERMINATEs) closes all the files that were opened. The value of REPORT-NUMBER is immaterial when you OPEN and CLOSE. You may MOVE ZERO to REPORT-NUMBER and do a single TERMINATE. This will TERMINATE all the reports that were INITIATEd. If REPORT-NUMBER is not zero when a TERMINATE is executed, only the corresponding report is terminated.

The report layouts need not be identical in all respects. You may vary the entries "present" from one report to the next by using the PRESENT WHEN clause, and you may vary the contents by the same means or by using SOURCE identifiers subscripted by REPORT-NUMBER. The DETAIL groups may even be different for each of the reports, since you can of course choose at any time which DETAIL groups to GENERATE. Therefore the DUPLICATED clause may still save you coding time even if there are notable differences in the layouts of the report groups.

At run time, report writer will vary the for each of your multiple print files by appending to it the two digits 01 (for the first file) up to nn for the last file, where nn is the integer in your DUPLICATED clause. If you specify a DDname of more than six characters, characters 7 and 8 of your DDname are overwritten. For example:

SELECT FILEA ASSIGN TO LST DUPLICATED 3 TIMES

expects your DDnames to be LST01, LST02 and LST03, and

SELECT...ASSIGN TO LISTINGF DUPLICATED 16 TIMES

expects your DDnames to be LISTIN01 through LISTIN16.

The following sample of coding shows how these techniques are used:

If you refer to LINE-COUNTER, PAGE-COUNTER, a total field, or any of the other special registers within the Report Control Area, the actual location accessed will be the one belonging to the report for which the most recent INITIATE, GENERATE, or TERMINATE was performed. For example, if you wish to reset PAGE-COUNTER in each of your reports in the multiple set, you should define a dummy DETAIL group (one having no LINEs) and code the following:

If you use a procedural statement, such as a MOVE, to store a value directly into a named field in one of your REPORT SECTION lines, the new contents will take effect for all the reports of the multiple set, because the report lines produced by report writer are shared by each of them.