USE BEFORE REPORTING statement

Function

The USE BEFORE REPORTING statement introduces Procedure Division statements that are to be executed just before the specified report group is printed by the Report Writer.

Format

---

USE [GLOBAL] BEFORE REPORTING report-group-name.

---

Syntax rules

1. The report-group-name must be defined as a name (data-name) in a 01-level entry of a REPORT SECTION report group entry in the Data Division. Any report group type except the detail report group may be specified in the USE BEFORE PRINTING statement.

2. The report-group-name identifies the report group for which the USE declaratives (USE BEFORE REPORTING procedures) following the USE BEFORE REPORTING statement are to be carried out.

3. The USE BEFORE REPORTING statement itself is never executed; it merely defines the conditions calling for the execution of the subsequently declared USE procedures.

4. The USE procedures declared for a report group are executed immediately before that report group is created.

5. No more than 39 USE BEFORE REPORTING statements may appear in the Procedure Division.

6. A USE procedure with a GLOBAL phrase is allowed only if the corresponding FD or RD entry contains the GLOBAL attribute and if the USE procedure is declared in the same program as the associated FD or RD entry. More details on using the GLOBAL clause can be found in "Format 3 USE statement with GLOBAL phrase" in section "USE statement".

General rules

1. The name of a given report group may be specified in one declarative section only.

2. The INITIATE, GENERATE, EXIT PROGRAM, GOBACK, CANCEL and TERMINATE statements must not appear in a paragraph within any declarative section.

3. A USE BEFORE REPORTING procedure must not alter the value of any control data item, nor any value of the subscripts used by the Report Writer to access the control data item.

4. The rules on references between a USE BEFORE REPORTING declarative and the remainder of the Procedure Division are the same as for other USE procedures.

5. The following are typical applications of USE BEFORE REPORTING procedures:

   1. Suppressing the printing of a report group:
      If the statement MOVE 1 TO PRINT-SWITCH is executed in a USE BEFORE REPORTING declarative, the Report Writer will not print the report group the USE procedure was associated with. Since the Report Writer always resets the PRINT-SWITCH special register (see section "PRINT-SWITCH special register") to zero immediately after suppressing the report group, this register must be set to 1 again each time that printing is to be suppressed; with report groups that are written automatically, this can only be done by means of USE BEFORE REPORTING declaratives.

   2. Modifying the contents of a data item specified in a SOURCE clause: In editing a line with a printable item whose description includes a SOURCE clause, the contents of the item defined by the SOURCE clause is transferred to the printable item by means of an implicit MOVE statement. A USE BEFORE REPORTING procedure may be used to modify the contents of the sending field just prior to the execution of the implicit MOVE statement.

   3. Rounding sum counters:
      If the value of a sum counter is to be rounded before it is transferred to the associated print item for editing, by an implicit MOVE statement, this can only be achieved by means of a USE BEFORE REPORTING declarative for the control footing in which the sum counter was defined.

   4. If special actions depending on the level within the control hierarchy at which a control break has occurred are to be taken before writing a page heading, control heading, control footing, or page footing, this can only be effected via USE BEFORE REPORTING declaratives for this report group, owing to their automatic generation (see section "SOURCE clause" and section "CBL-CTR special register").