HP OpenVMS Systems Documentation

HP COBOL
Reference Manual

Function

In a report group description, the COLUMN NUMBER clause identifies a printable item and specifies the position of the item on a print line. In a screen description, the COLUMN NUMBER clause specifies the horizontal screen coordinate for a screen item.

column-num

is a positive integer greater than zero.

identifier-1

is an elementary unsigned numeric integer data item. It cannot be subscripted.

integer-1

is an unsigned integer value.

Syntax Rules (Report Description)

1. The COLUMN NUMBER clause can be specified only at the elementary level within a report group. The COLUMN NUMBER clause, if present, must appear in a Format 3 Report Group Description entry, or be subordinate to an entry that contains a LINE NUMBER clause in a Format 2 Report Group Description entry.
2. A printable item is a data item whose size and content is specified by an elementary report entry.
3. An elementary report entry contains a COLUMN NUMBER clause, a PICTURE clause, and a SOURCE, SUM, or VALUE clause.
4. Each printable item within a given print line must be defined in ascending column number order such that each printable item occupies a unique sequence of contiguous character positions.

Syntax Rules (Screen Description)

1. The COLUMN clause can be specified only in an elementary screen description entry.
2. identifier-1 cannot be subscripted.

General Rules (Report Description)

1. The presence of a COLUMN NUMBER clause indicates that these items, if present, are to be presented on the print line:
   • The object of a SOURCE clause
   • The object of a VALUE clause
   • The sum counter in a SUM clause
   
   The absence of a COLUMN NUMBER clause indicates that the entry is not printable.
2. Column number 1 is the leftmost position of the print line.
3. column-num specifies the column number of the leftmost character position of the printable item.
4. The Report Writer Control System supplies space characters for all positions of a print line not occupied by printable items.

General Rules (Screen Description)

1. The COLUMN clause, in conjunction with the LINE clause, establishes the starting position for a screen item. This position is an offset from the starting screen coordinates specified in the ACCEPT or DISPLAY statement. The COLUMN clause specifies the horizontal coordinate.
2. The COLUMN clause without the PLUS phrase specifies the absolute column position of the screen item.
3. The COLUMN clause with the PLUS phrase specifies a column number relative to that at which the preceding item ends, regardless of whether or not the ACCEPT or DISPLAY statement displays the preceding item on the screen.
4. A setting of COLUMN 1 is assumed in screen description entries that specify the LINE clause but omit the COLUMN clause.
5. If both the LINE clause and the COLUMN clause are omitted, the following apply:
   • If no previous elementary screen item is defined, LINE 1 COLUMN 1 is assumed.
   • If a previous screen item is defined, the ending line of that previous item and COLUMN PLUS 1 is assumed. The screen item then starts immediately following the preceding screen item.

Additional References

• Section 5.3.5
• Section 5.3.32 clause
• Section 6.8.1 statement in Chapter 6
• Section 6.8.10 statement in Chapter 6

Examples (Report Description)

1. The following is an example of the COLUMN NUMBER clause in a LINE NUMBER clause:

   02 LINE 10 COLUMN 1 PIC X(11) VALUE "TOTAL ITEMS". 1 2 3 4 column: 1234567890123456789012345678901234567890 TOTAL ITEMS

2. The following is an example of the COLUMN NUMBER clause subordinate to a LINE NUMBER clause:

   02 LINE 5 ON NEXT PAGE. 03 COLUMN 1 PIC X(10) VALUE "(Id Number". 03 COLUMN 12 PIC 9999 VALUE 1234. 03 COLUMN 16 PIC X VALUE ")". 03 COLUMN 18 PIC X(11) VALUE "TOTAL SALES". 03 TSAL COLUMN 30 PIC $$$$,$$$.99- VALUE 123456.78. 1 2 3 4 column: 123456789012345678901234567890123456789012345 (Id Number 1234) TOTAL SALES $123,456.78

Function

The CONTROL clause establishes the levels of the control hierarchy for the report.

control-name

is any data-name in the Subschema, File, Working-Storage, or Linkage Section.

Syntax Rules

1. control-name can be qualified.
2. Each occurrence of control-name must identify a different data item.
3. control-name must not have a variable-occurrence data item subordinate to it.
4. If the associated report file connector is an external file connector, control-name must reference the same external data item in all programs in the run unit.

General Rules

1. The word FINAL specifies the most major control item. From here, the hierarchy descends to control-name, which is the major control; to the next recurrence of control-name, which is an intermediate control; and so forth to the last recurrence of control-name, which is the minor control.
2. A control break is a change in the value of a control-name.
3. FINAL is used when the most inclusive control group in the report is not associated with a control-name.
4. The first time a GENERATE statement is executed, the Report Writer Control System (RWCS) saves the values of all control data items associated with that report. After that, every time a GENERATE statement is executed, the RWCS tests those control data items to see if their values have changed. If so, a control break occurs. This control break is associated with the highest level control item whose value has changed.
5. Control breaks cause the RWCS to present appropriate CONTROL HEADER and CONTROL FOOTING report groups for printing. Figure 5-8 shows the report groups the RWCS processes (X) when you define FINAL, major, intermediate, or minor control-name in a CONTROL HEADING or CONTROL FOOTING phrase in a Report Group Description entry. For example, if the value in a major control-name changes, the RWCS processes all major, intermediate, and minor control groups specified in CONTROL HEADING and CONTROL FOOTING report groups.

   Figure 5-8 Control Break Levels and Their Printed Report Groups

   ---

   
6. The RWCS tests for a control break by comparing the contents of each control data item with the prior contents of each control data item that were saved when the previous GENERATE statement for the same report was executed. The RWCS applies the inequality relation test as follows:
   • If the control data item is a numeric data item, the relation test is for the comparison of two numeric operands.
   • If the control data item is an index data item, the relation test is for the comparison of two index data items.
   • If the control data item is other than as described in Figure 5-8, the relation test is for the comparison of two nonnumeric operands.

Additional References

• Section 5.3.5
• Section 6.5.1, Relation Conditions

Examples

1. This example prints a total record count from TOTAL-LINE at the end of the report because control is FINAL. It is a major control break and prints only once.

   WORKING-STORAGE SECTION. 01 RECORD-COUNT PIC 9(9) VALUE 0. REPORT SECTION. RD MASTER-REPORT... CONTROL IS FINAL. 01 DETAIL-LINE TYPE IS DETAIL... 01 TOTAL-LINE TYPE IS CONTROL FOOTING FINAL. 02 COLUMN 20 PIC X(17) VALUE "TOTAL RECORDS: ". 02 COLUMN 40 PIC ZZZ,ZZZ,ZZ9 SOURCE RECORD-COUNT. PROCEDURE DIVISION. BEGIN. OPEN INPUT... OPEN OUTPUT... INITIATE MASTER-REPORT. 010-READ-FILE. READ... AT END GO TO 999-EOJ. GENERATE DETAIL-LINE. ADD 1 TO RECORD-COUNT. GO TO 010-READ-FILE. 999-EOJ. TERMINATE MASTER-REPORT. CLOSE... STOP RUN.

2. In the following example, a report defines four control totals in the control clause. The source of these control totals is in an input file---INPUT-FILE. The file is presorted in ascending sequence by MAJOR-CONTROL, INTERMEDIATE-CONTROL, and MINOR-CONTROL. The RWCS will monitor these fields in the input file for any changes. If a new record contains data different from the previous record read, the RWCS triggers a control break.
   In this example, if the value in MINOR-CONTROL changes, a break occurs and the RWCS processes the minor control report group CONTROL FOOTING MINOR-CONTROL. If the value in INTERMEDIATE-CONTROL changes, a break occurs and the RWCS processes the intermediate and minor control report groups CONTROL FOOTING INTERMEDIATE-CONTROL and CONTROL FOOTING MINOR-CONTROL. If the value in MAJOR-CONTROL changes, a break occurs and the RWCS processes the major, intermediate, and minor control report groups CONTROL FOOTING MAJOR-CONTROL, CONTROL FOOTING INTERMEDIATE-CONTROL, and CONTROL FOOTING MINOR-CONTROL.

   FILE SECTION. FD INPUT-FILE... 01 INPUT-RECORD. 02 MAJOR-CONTROL PIC... 02 ... 02 MINOR-CONTROL PIC... 02 ... 02 INTERMEDIATE-CONTROL PIC... 02 ... FD REPORT-FILE... REPORT IS SUMMARY-REPORT. REPORT SECTION. RD SUMMARY-REPORT... CONTROLS ARE FINAL MAJOR-CONTROL INTERMEDIATE-CONTROL MINOR-CONTROL. 01 DETAIL-LINE TYPE IS DETAIL... 01 TYPE IS CONTROL FOOTING FINAL ... 01 TYPE IS CONTROL FOOTING MINOR-CONTROL... 01 TYPE IS CONTROL FOOTING MAJOR-CONTROL... 01 TYPE IS CONTROL FOOTING INTERMEDIATE-CONTROL...