CONTROL clause

Function

The CONTROL clause defines the data items that are used as control data items of the report to determine the group hierarchy and, thus, the hierarchical structuring of the report.

Format

---

{CONTROL | CONTROLS} {IS | ARE} {{data-name-1}... | FINAL [data-name-1]...}

---

Syntax rules

1. No more than 31 data-names may be entered in the CONTROL clause, including the FINAL phrase if specified.

2. data-name-1... may be qualified but must not be indexed.

3. No data item may be subordinated to a data-name if its length is defined in the OCCURS clause as variable.

4. data-name-1... must not be defined in the REPORT SECTION but rather in the FILE SECTION, LOCAL-STORAGE SECTION or WORKING-STORAGE SECTION. A data-name entered in the CONTROL clause may be defined in the LINKAGE SECTION of the called program, provided that the called program is continuously available in memory from the time the report is initiated until its production is terminated.

5. The data item used may be up to 256 characters in length.

6. Each data-name-1 must identify a different data item.
   Two separate recurrences of data-name-1 must not refer to data items which (by redefinition) refer to the same memory locations.

7. A control data item is a data item which is specified in the CONTROL clause. It is tested whenever a GENERATE statement is executed for the same report in order to ascertain whether its value has changed since the last GENERATE statement was executed for that report.

   If such a change in value is found to have taken place, a "control break" occurs, i.e. special action (described below) will be taken before the detail report group specified by the GENERATE statement is written. If changes in value have occurred in several control data items when a GENERATE statement is executed, it is always the hierarchically supreme change in value to which all control break concepts (such as control break and control break level) are related.

8. FINAL, data-name-1... define the control hierarchy of the report.

9. The data-names, in the order in which they are listed from left to right, specify the levels of the control hierarchy from major to minor. The last (i.e. rightmost) data-name is assigned the lowest level, the last but one is assigned the lowest level, the last but one is assigned the second lowest level, and so on.

10. FINAL defines the hierarchically highest control break. The associated control heading is generated when the first GENERATE statement is executed; the associated control footing when the TERMINATE statement is executed.

General rules

1. The action implied by a control break depends on whether a control heading and/or a control footing, or neither of the two are defined for each control hierarchy level. If a control break occurs, the Report Writer creates the following control headings and control footings (as present), in the order shown below:

   1. Control footing of the lowest level.

   2. Control footing of the next higher level.

      .

      .

      .

   3. Control footing of the level responsible for the control break.

   4. Control heading of the level responsible for the control break.

   5. Control heading of the next lower level.
      .
      .
      .

   6. Control heading of the lowest level.

   Next, the Report Writer writes the detail report group initiated by the GENERATE statement.

   For example, when the control break data-names for a report are specified as YEAR, MONTH, and DAY (listed in this order in the CONTROL clause), associating each of these data-names with one control heading as well as one control footing, then, if a control break occurs for YEAR (that is, the contents of the data item YEAR has changed between two chronologically successive GENERATE statements), the body groups are printed in the following order:

   Control footing Control footing Control footing Control heading Control heading Control heading

   for DAY for MONTH for YEAR for YEAR for MONTH for DAY

   Detail report group produced by the GENERATE statement.

2. If the Report Writer starts creating a body group and detects that one of the conditions for a page break exists, it will first write the page footing (if specified), then skip to the next page, then write the page heading (if specified), and finally generate the body group.

3. The creation of a detail group must be requested by the programmer from the Report Writer by means of an appropriate GENERATE statement (to define the detail group) in the Procedure Division. All other report groups such as report heading, report footing, page heading, page footing, control headings, and control footings are written automatically by the Report Writer as soon the respective conditions are satisfied.

4. In order to determine a control break, an alphanumeric compare is performed, regardless of how the control data items are described. This means, for example, that the Report Writer will detect a change of value when the contents of a control data item described with COMPUTATIONAL-3 is changed from hexadecimal "7F" to hexadecimal "7C", although both variant representations print out the positive number 7.

5. When a CONTROL clause is not specified for a report, control headings and control footings must not, and cannot, be defined for the report.

Example 10-1

Extract from a report:

JANUARY 14  B10                   4  B    8.36
            B10                   1  C    9.00
PURCHASES & COST FOR 1-14         5     $17.36  $136.36
JANUARY 15  B10                   2  A   16.00

The relevant report description entry includes this CONTROL clause:

CONTROLS ARE FINAL MONTH WDAY

Except for the print line beginning with PURCHASES and constituting the control footing for WDAY, all other print lines from the above report extract are detail groups (same report description). The control footing of WDAY was written because the data changed from January 14 to January 15.