Control Clause

This clause should be coded in your RD if your report has additional lines, such as total lines and subheadings, that are to be produced upon a change of value in one or more "key" fields (known as control fields or simply controls).

Control Clause: Coding Rules

• As the format shows, you may code either the special keyword REPORT (or its equivalent, FINAL), or a list of identifiers (control-ids), or both. Commas are optional but helpful separators here, but you should code at least one space or new line between the operands. At least one operand must be coded.

• REPORT, if present, must appear first in the list of control-ids. You may omit REPORT even if you refer to it in the Report Description. FINAL is an alternative name for REPORT.

• Each control-id must be REPORT/FINAL or the name of an unedited data item in the DATA DIVISION of your program. It must not be a special register in the REPORT SECTION, such as PAGE-COUNTER. You may include qualifiers and subscripts if necessary. A PICTURE of a control-id should not have a "V" (implied decimal point) symbol.

• You cannot use the same control-id more than once in the same CONTROL clause (unless a redefinition is used), but you can use the same control-id in different RDs.

• If the OSVS option is in effect, control-ids may be required to be either group items or unedited alphanumeric or numeric DISPLAY items with a maximum size. Thus edited items and items with a USAGE of COMPUTATIONAL or INDEX are prohibited. Details will be found in Installation and Operation. If you would like to use such an item as a control without restrictions on its format, you can simply REDEFINE it or use a group level item containing only the item in question:

  

  It is acceptable for your control fields to overlap. The following usage is therefore allowed:

  

• Coding the CONTROL clause enables you to include some additional elements in your report description, namely:

  • You can specify a CONTROL HEADING and/or a CONTROL FOOTING group for each control-id, if needed. (See TYPE clause.)

  • You can code PRESENT/ABSENT AFTER clauses (formerly known as GROUP INDICATE) with any of the control-ids as operand to cause report fields, lines etc. to appear or disappear after a change in its value. (See PRESENT AFTER clause.)

  • You can defer the RESETting (zeroing) of a total field until after a change in a higher control. (See SUM clause.)

Control Clause: Operation

You code a CONTROL clause when your report has a structure based on changes in the value of one or more "key" or control fields, whose names you list in the CONTROL(S) clause. Report writer does not sort your data (to do that you could use COBOL SORT) but, assuming that your data is sequenced according to the control fields, report writer can perform certain actions automatically, such as the production of a CONTROL FOOTING and a CONTROL HEADING group when its contents change. It is also possible for a single CONTROL FOOTING group to be used for more than one level of control. (See TYPE clause.) In the following diagram, there are two levels of control. Two CONTROL HEADING groups and one CONTROL FOOTING have been coded. (There is no CONTROL FOOTING FOR YEAR.) The "boxes" around each of these groups shows their extent. We have used some abbreviations in the following code - for example omitting the SOURCE and TYPE keywords - to save space. To shorten it further, you could abbreviate CONTROL HEADING FOR YEAR and CONTROL FOOTING FOR YEAR as CH YEAR and CF YEAR.

The preceding diagram illustrates the following important points:

• Your CONTROL HEADING and CONTROL FOOTING groups are coded as separate 01-level report groups.

• You can lay out CH and CF groups exactly as you like, just as you would for a DETAIL; report writer imposes no pre-defined format on any groups.

• If you need a different CONTROL HEADING at more than one level (YEAR and MONTH in our example), you must code a new group for each level. This means that all groups may have different layouts. In this example, this applies also to the CONTROL FOOTING groups. (However, you can if you wish use the same group description for both levels by coding TYPE CF FOR YEAR, MONTH.)

• Report writer produces your CONTROL HEADING group at the start of each new value of the control. Similarly, it produces your CONTROL FOOTING group at the end of each new value of the control.

• CONTROL FOOTING groups are produced using the control values that existed before the control break. (See next item below for a fuller description of this.)

• Both the CONTROL HEADING and the CONTROL FOOTING groups are optional for each control-id. You may code just a CONTROL HEADING group, or just a CONTROL FOOTING group, or neither.

• The reserved word REPORT (or FINAL) is a special case representing the highest possible control. It is not a data-name. Include this as the first of your set of controls if you need special action to be taken once only at the beginning and end of the report; for example, if you require grand totals to be produced for the entire report.

• Report writer keeps an internal copy of the pre-break contents of each control so that it special case REPORT or FINAL for the moment, whenever your program issues a GENERATE statement, the CONTROL clause causes report writer to compare the contents of each control with its contents when the previous GENERATE was executed. The first control is examined first, then the second and so on. If no changes are found in any of the controls, no special action is taken. As soon as a change is found in a control, no further controls are examined. A break in a higher control always implies a break in all the lower controls , whether their contents have actually changed or not. (Obviously, 1991's JANUARY is a different month from 1992's JANUARY.) If you have more than one control, they must therefore have a hierarchy. Here are some examples:

  

  Your control-names must exist somewhere as data-names in the program outside the REPORT SECTION. For example, if in the last case the data-names in your file layout are actually written CUST-STATE, CUST-COUNTY, CUST-CITY, then your CONTROL clause would have to be written: CONTROLS ARE CUST-STATE, CUST-COUNTY, CUST-CITY.

• When a control break is detected, if your report has CONTROL FOOTING groups, each control field is first saved in a temporary holding area and is then overwritten with the contents it had before the break for the duration of the production of the CONTROL FOOTINGs. This means that your program will use the before-the-break contents of any CONTROL field (for example in a SOURCE, or a PRESENT WHEN) in the following TYPEs of group:

  • a CONTROL FOOTING;
  • a PAGE HEADING or PAGE FOOTING, when the page advance was caused by
  • a CONTROL FOOTING;

  and in the following situations:

  • when it is used as a SOURCE or SUM operand, either as it is or as a subscript or qualifier, or as part of an expression;

  • when it is used as part of a condition;

  • when it appears in a parameter to a FUNCTION;

  • when it is referenced implicitly, that is, via a redefinition, or via a group field or subordinate field or an intersecting field.

  Only control fields exhibit their before-the-break values when referenced at CONTROL FOOTING time. To obtain the before-the-break value of a field other than a control field, you should use a Declarative procedure to save its current value (see USE BEFORE REPORTING Directive: Operation). After the lowest-level CONTROL FOOTING has been produced, and before any CONTROL HEADING or DETAIL groups are output, the current contents of all controls are restored . For a full description of the steps, see GENERATE statement.

• Report writer will not detect a control break until your program issues a GENERATE. If a control field in your input data changes several times but no GENERATE is issued during that time, no control breaks will be detected.

• Your CONTROL identifiers need not be chosen just from ready-made locations in your input files or database. You may also "manufacture" them in WORKINGSTORAGE. As a simple example, you may wish to print subtotals by quarter, although your main input gives just the months:

  

• You cannot define more than one CONTROL HEADING or CONTROL FOOTING for a given control-id in your report. However, cases sometimes occur when you would like two CONTROL FOOTING report groups for the same level of control. You may achieve this referring to the same control field under a different name, as in the following case, where we must have two groups because the second part begins on a new page:

  

  Here, the two controls W-ACCT-NO-1 and W-ACCT-NO-2 are physically the same field. Consequently, there will be a break in the higher control whenever there is a break in the lower control, and the two CONTROL FOOTING groups, GRP-A and GRP-B, will always appear together in that order.

• Report writer will consider a control break to have taken place if there is any change in the bit-pattern of the control field. For example, if the field is packed decimal (COMPUTATIONAL-3), a value of (hex) 123C and (hex) 123F will be considered different, even though they both represent the same numeric value. If this property is undesirable, your program should MOVE such a field to a DISPLAY field and use the DISPLAY field as the control field.

• If your program has several Report Descriptions, each report is processed independently of the others. You can decide separately for each report whether it will have a CONTROL clause and which controls to specify. When you issue a GENERATE for a report that has controls, report writer examines the controls for that report only, ignoring all the others.

• Non-Hierarchical Control Structures. In some report structures, there may appear to be controls which are in parallel rather than hierarchical arrangement. For example:

  

  The organization of records in your file might be:

  

  As you see, there is no hierarchical relationship between STUDENTs and TEACHERs. You might wish to print a CONTROL FOOTING group for the STUDENT records in each Department and a CONTROL FOOTING group of quite different appearance for the STUDENT records. To achieve this you must regard the two different CONTROL FOOTING groups as different versions of the same CONTROL FOOTING and use a PRESENT WHEN clause to distinguish them. Make the STUDENT-TEACHER indicator an extra lower control. Here is a skeleton solution:

  

• There may be other purposes for specifying an item as a control. You might include it for the following reasons:

  • To trigger a PRESENT AFTER clause (or a GROUP INDICATE clause), or The RESET Phrase of the SUM clause.

  • To force a control break even though a lower control has not changed. You might want to output just monthly totals over several years' data. If you then declare MONTH as a control you must include YEAR too as a higher control, because it is quite possible for JANUARY 1991 to be followed immediately by JANUARY 1992 if you happen to have no data for FEBRUARY to DECEMBER 1991. (Note: in this example, you could also solve the problem by having just one control, YEAR-MONTH, if they are contiguous.)

  • Because you may want to use the field as a SOURCE at CONTROL FOOTING time and you want to obtain the previous value of the field. (See item 4 above.) For example, you might have both CUSTOMER-NUMBER and CUSTOMER-NAME. By making CUSTOMER-NAME a control field following CUSTOMER-NUMBER (the "true" control field), you can be sure that you will see only the pre-break values of CUSTOMER-NAME at Control Footing time.

  • For documentary purposes. The lowest-level controls need not be used at all in the program.

  • If the program's SPECIAL-NAMES paragraph contains an ALPHABET clause, you may need to use the NOXCAL option to ensure that the specified collating sequence is used. See Installation and Operation.

Compatibility

• The use of REPORT as an alternative to FINAL is unique to new Report Writer.

• Only new Report Writer allows control fields to overlap.

• Only new Report Writer forbids the use of a COMPUTATIONAL item as a CONTROL field under certain circumstances. New Report Writer regards two instances of a COMP-3 control to be different if their sign is hex C in one case and hex F in the other, even though all the remaining digits may be equal.

• Only new Report Writer checks that all the control-ids in a given CONTROL clause are different.