Use Before Reporting Directive

The USE BEFORE REPORTING directive causes a SECTION in the DECLARATIVES of your PROCEDURE DIVISION to be performed automatically just before a selected specified report group is produced.

Use Before Reporting Directive: Coding Rules

• The format above shows the PROCEDURE DIVISION and DECLARATIVES headers for the sake of completeness. They are used not just by report writer, and your program might already have Declarative sections for some other purpose. It is the distinctive format of the USE BEFORE REPORTING directive that tells report writer that the section is part of its responsibility. If you also have other Declarative sections, they may be intermixed with your USE BEFORE REPORTING sections in any order.

• In order to code a USE BEFORE REPORTING section, you must ensure that the corresponding group has an 01-level data-name, so that you can refer to it as the report-group-name.

• Your USE BEFORE REPORTING section may also PERFORM other sections. These are normally additional sections within the DECLARATIVES portion (as required by all ANS Standards). For this purpose, you may code additional sections within DECLARATIVES that have no USE statement. Report writer also allows your USE BEFORE REPORTING section to PERFORM sections in your mainline PROCEDURE DIVISION.

  The example that follows shows how you may code one section to be performed when one of two report groups is about to be produced:

  

• Your USE BEFORE REPORTING section must not contain any INITIATE, GENERATE, or TERMINATE statements. Neither may any of the sections it may perform.

• If you specify GLOBAL, the named report group must exist either in the current program or in a contained program.

Use Before Reporting Directive: Operation

• If any of your report groups has a USE BEFORE REPORTING section, report writer will implicitly PERFORM the section during the processing of the group. Assuming that your report has every possible feature, the section will be implicitly performed:

  • After the testing of control breaks and the production of any CONTROL FOOTING and CONTROL HEADING groups (if your group is a DETAIL)

  • After the computation of your group's cross-foot totals (if any), so your USE BEFORE REPORTING section can reference them

  • If OSVS is in effect, after the rolling forward into your totals and subtotalling associated with your group

  • If NOOSVS is in effect, before the rolling forward into your totals and subtotalling associated with your group, so your USE BEFORE REPORTING section can alter values that are due to be added into other groups' totals

  • Before the moving of any CODE identifier, so your USE BEFORE REPORTING section can change the originating identifier

  • Before the page-fit test and the production of any PAGE FOOTING and PAGE HEADING groups (if your group is a body group), so you may alter the originating fields due to be moved into them, or suppress them along with the body group itself.

  • Before any of the SOURCE, SUM, or FUNCTION fields are set up in the lines of your group, so you may change any of the originating fields due to be displayed in your group.

• You may include the a SUPPRESS PRINTING statement or MOVE 1 TO PRINT-SWITCH in a USE BEFORE REPORTING Declarative, in order to prevent output for the group at that instant.

• USE BEFORE REPORTING sections were used a great deal in the ANS-68 and ANS-74 COBOL-IT Report Writer. So you may possess migrated programs that contain cases of their use. With report writer much of their functions are now performed by the PRESENT WHEN and PRESENT AFTER clauses. However, they can still be of considerable use. For example:

  • You could use your Declarative section to WRITE additional records to another file, using the automatic control break processing to "drive" the rest of your program.

  • You might use the USE BEFORE REPORTING section for a CONTROL HEADING group to READ an additional record at the start of each new CONTROL value, or fetch it from your database.

  • You might need to suppress the printing of certain totals without preventing them from being reset to zero. (The PRESENT clause will prevent the resetting of a total field if it was not output.)

  • You might want to force a CONTROL HEADING group to start on a new page under certain complex circumstances. Your USE BEFORE REPORTING section would then force page advance processing thus:

    IF complex-condition

    MOVE last-detail-value TO LINE-COUNTER.

  • You might want to search a table for a corresponding text field at the start of each CONTROL HEADING group, and move it to a WORKING-STORAGE field that is the operand of a SOURCE in a PAGE HEADING or the CONTROL HEADING itself. (If your group is a DETAIL, it will be clearer to do this in the main-line program.)

  • There may be an item associated with a control which is not itself a control (such as a STATE-NAME logically associated with a STATE-NO control) which you will want to output during CONTROL FOOTING time. Since the item is not a control you will not automatically obtain the before-the-break value. You could code a Declarative section for the corresponding CONTROL HEADING group. This would save the current value of the field in a WORKING-STORAGE location which is then used instead of the input item in all SOURCE clauses in PAGE HEADING, PAGE FOOTING and CONTROL FOOTING groups.

  • If you have no CONTROL HEADING group, you may code one as a "dummy" (see Coding Report Group Descriptions) with no LINE clauses, in order to take advantage of report writer's automatic control break checking, as suggested in the following example:

    

    You may find it desirable to suppress printing of a minor CONTROL FOOTING if only one DETAIL is printed above it, since a "total" of a single value will seem out of place. Here is one way to do it:

    

    Do not instead code an ABSENT WHEN clause at the 01-level of the CONTROL FOOTING group, as this would have the undesirable side-effect of preventing the resetting and rolling forward of any SUM fields that you might have defined in the CONTROL FOOTING group.

• If you specify GLOBAL, your Declarative section will apply both to the current program, if it contains a report group of that name, and also to any contained program that has a report group of that name but no USE BEFORE REPORTING section of its own for that name. If a contained program also has a USE GLOBAL BEFORE REPORTING section for the same report-group-name, this overrides the effect of original section until the end of the contained program.

Compatibility

Apart from the ANS-85 GLOBAL phrase, OS/VS and DOS/VS COBOL, and new Report Writer agree in their formats for this statement, but new Report Writer allows a USE BEFORE REPORTING section to be coded for a DETAIL group.