Compaq COBOL
Reference Manual

Function

The BLANK WHEN ZERO clause replaces zeros with spaces when a data item's value is zero. In the context of the Screen Section, it displays spaces when the value of a screen item to be displayed on the screen is zero.

Syntax Rules

1. The BLANK WHEN ZERO clause can be used only for a numeric or numeric edited elementary item.
2. A data item or screen item containing the BLANK WHEN ZERO clause must be implicitly or explicitly described with DISPLAY usage.
3. The syntax for a data item allows the spelling ZERO or ZEROES or ZEROS. The syntax for a screen item allows the spelling ZERO only.

General Rules

1. The BLANK WHEN ZERO clause causes a data item or screen item to contain spaces when its value is zero.
2. When the data item or screen item has a numeric PICTURE string, the BLANK WHEN ZERO clause makes the item's category numeric edited.
3. The BLANK WHEN ZERO clause is ignored in the description of an input screen item.

Additional Reference

Section 6.8.10 statement in Chapter 6

5.3.14 BLINK

Function

The BLINK clause displays characters on the screen with the blink on character attribute.

Syntax Rule

The BLINK clause can be specified only in an elementary screen description entry.

General Rule

Blinking is only detectable when any of the following conditions are true:

• Nonspace characters are displayed.
• The underline and/or reverse-video attributes are specified.
• The terminal screen is set to light background.

Additional References

• Section 6.8.10 statement in Chapter 6
• Section 6.8.1 statement in Chapter 6

Function

The CODE clause specifies a two-character literal that identifies each print line as belonging to a specific report.

report-code

must be a two-character nonnumeric literal.

Syntax Rule

If the CODE clause is specified for any report in a file, it must be specified for all reports in that file.

General Rules

1. When the CODE clause is specified, report-code is automatically placed in the first two character positions of each Report Writer logical record.
2. The positions occupied by report-code are not included in the description of the print line, but are included in the logical record size.

Additional Reference

Section 5.3.3

Example

The following file contains three reports:

FILE SECTION. FD REPORT-FILE LABEL RECORDS ARE STANDARD REPORTS ARE REPORT1 REPORT2 REPORT3. REPORT SECTION. RD REPORT1 ... CODE "AA". RD REPORT2... CODE "BB". RD REPORT3... CODE "CC".

5.3.16 COLUMN NUMBER

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...

Function

data-name specifies a data item that your program can explicitly reference. FILLER specifies an item that cannot be explicitly referenced.

data-name

Syntax Rules

1. In the File, Working-Storage, and Linkage Sections, data-name or the key word FILLER (if present) must be the first word after the level-number in each data description entry.
2. In the Report Section, data-name need not appear in a report group description entry and the key word FILLER must not be used.

General Rules

1. If there is no data-name or FILLER clause, the compiler treats the data item as a FILLER item.
2. The key word FILLER can name a data item. However, a program cannot explicitly refer to FILLER items.
3. The key word FILLER can name a conditional variable. A program cannot refer to the conditional variable. However, it can refer to the value of the conditional variable by referring to its associated condition-names.
4. In the Report Section, data-name must be used when:
   1. data-name represents a report group to be referred to by a GENERATE or a USE statement in the Procedure Division.
   2. Reference will be made to the sum counter in the Procedure Division or Report Section.
   3. The UPON phrase of the SUM clause references a DETAIL report group.
   4. data-name provides sum counter qualification.
5. If this clause is omitted, the Report Writer Control System does not allow explicit references to the data item.

Examples

1. Elementary FILLER items:
   In this example, the program can refer only to the group item, ITEMA.

   01 ITEMA. 03 FILLER PIC X(10) VALUE SPACES. 03 PIC X(2) VALUE "AB". 03 PIC 9 VALUE 6.

2. Group FILLER items:
   In this example, the program can refer to any elementary item. However, it cannot refer to the record or to the group item that contains ITEMC and ITEMD.

   01 FILLER. 03 ITEMA PIC X(4). 03 ITEMB PIC 9(7). 03 FILLER. 05 ITEMC PIC X. 05 ITEMD PIC 9(8)V99. 03 ITEME PIC X.

3. Report Writer items:
   In this Report Writer example, the program can refer to DL-NAME and DETAIL-LINE, but not to the data beginning in LINE 10, COLUMN 25. Note that FILLER cannot be used in place of a Report Writer data-name.

   01 DETAIL-LINE TYPE IS DETAIL. 02 LINE 10. 03 DL-NAME COLUMN 1 SOURCE INPUT-NAME. 03 COLUMN 25 SOURCE INPUT-ADDRESS.

Function

The DATA RECORDS clause documents the names of a file's record description entries.

rec-name

is the name of a data record. It must be defined by a level 01 data description entry subordinate to the file description entry.

Syntax Rule

The order of appearance of multiple rec-name entries is not significant.

General Rule

The DATA RECORDS clause is for documentation only.

5.3.20 ERASE

Function

The ERASE clause clears from the starting cursor position to the end of either the line or the screen.

Syntax Rule

The ERASE clause can be specified only for elementary screen description entries.

General Rules

1. Blanking begins at the starting position of the screen item in whose description the ERASE EOL clause is included, and continues to the end of the line.
2. Blanking begins at the starting position of the screen item in whose description the ERASE EOS clause is included, and continues through to the end of the screen.
3. If you specify neither the BLANK nor the ERASE clause, only the particular character positions corresponding to the screen item are modified when the element is displayed. The rest of the screen content remains the same.
4. The ERASE clause is ignored in an ACCEPT statement.

Additional References

Section 6.8.10 statement in Chapter 6

5.3.21 EXTERNAL

Function

The EXTERNAL clause specifies that a data item or a file connector in a defining program is common to other programs in the run unit if the program defines it identically. The group and elementary data items of an external data record and files associated with an external file connector are available to every program in the image that describes them.

Syntax Rules

1. The EXTERNAL clause can appear only in file description entries or in record description entries in the Working-Storage Section.
2. In a record description entry, only level numbers 01 and 77 can specify the EXTERNAL clause.
3. A program and any program it contains, cannot define identical data-names if their data description entries or file description entries have EXTERNAL clauses.
4. The VALUE clause or the REDEFINES clause cannot be in a data description entry that contains or is subordinate to, an entry that contains the EXTERNAL clause.
5. When using the SAME RECORD AREA clause for several files, the Record Description entries or the file description entries for these files must not include the EXTERNAL clause.
6. Entries that contain the EXTERNAL clause must be named.

General Rules

1. Data in a record either subordinate to an external FD, or named by the subject of the EXTERNAL clause, is external. Any program in the image that describes and optionally redefines this data may access and process this data subject to the following general rules.
2. If two or more programs in the image describe the same external data record, the associated data description entries (except the GLOBAL clause) must be identical. All subordinate data-names, data items, and redefinitions must also be identical.
3. A program that describes an external data record can contain a Data Description entry that redefines the complete external record. This redefinition need not be the same in other programs in the image.
4. Use of the EXTERNAL clause does not imply that the associated file-name or data-name is a global name.
5. The file connector associated with a file description entry is an external file connector.
6. If two or more programs in an image describe the same external file connector, the clauses associated with the description of that file must be functionally identical and any data items referenced by those clauses must be external.

Technical Notes

• Each external sequential file becomes a print format file.
• Each external data record becomes a PSECT (on OpenVMS Alpha systems) or a global (on Tru64 UNIX and Windows NT systems), whose name is the 01-level record.
  Each file connector for external files becomes a PSECT (on OpenVMS Alpha systems) or a global (on Tru64 UNIX and Windows NT systems), whose name is the name of the file. The records associated with this file become external data records.
  External record items and files are implemented as overlayable shared PSECTs (on OpenVMS Alpha systems) or globals (on Tru64 UNIX and Windows NT systems). Therefore, the same storage area is shared among all separately compiled programs for that named external record or file. The PSECT or global is created for compatibility with BASIC COMMON/MAP and FORTRAN labeled COMMON.
  On OpenVMS, for more information on overlayable PSECTs, refer to the LINK documentation in the OpenVMS Alpha documentation set. <>
  On Tru64 UNIX, for more information on globals, refer to the ld documentation in the Tru64 UNIX documentation set. <>
• On Windows NT and Tru64 UNIX systems, an external data item is case-sensitive. By default, an external data item is converted to lowercase for all separately compiled program units. Other programs (Compaq COBOL as well as other languages) must specify the data item in lowercase.
  However, if the names option is set to uppercase on the command line, other programs must specify the data item in uppercase. If the names option is set to as_is , the effect on an external data item is as if uppercase were specified. (The as_is setting is used for calling non-COBOL programs with mixed case.) <>

Additional References

• Section 5.3.25 clause
• Section 5.3.40 clause

Examples

In the following Working-Storage entries, the data items in RECORD-A are available to any program in the run unit that also describes RECORD-A and its data items. RECORD-B and the data items in it are not available to any other program.

01 RECORD-A EXTERNAL. 03 ITEMA PIC X. 03 ITEMB PIC X(22). 03 ITEMC PIC 999. 01 RECORD-B. 03 ITEMA PIC X(12). 03 ITEMD PIC X. 03 ITEME PIC 9(18).