Compaq COBOL
Reference Manual

Function

The report group description entry specifies the characteristics of a report group and of the individual items within a report group.

Syntax Rules

All Formats

1. The report group description entry can appear only in the Report Section.
2. Except for the group-data-name clause, which when present must immediately follow level-number, the clauses may be in any sequence.
3. The description of a report group may consist of one, two, or three hierarchical levels:
   1. The first entry that describes a report group must be a Format 1 entry.
   2. Both Format 2 and Format 3 entries may be immediately subordinate to a Format 1 entry.
   3. At least one Format 3 entry must be immediately subordinate to a Format 2 entry.
   4. Format 3 entries must define elementary data items.
4. In the Report Section, the USAGE clause is used only to declare the usage of printable items.
   1. If the USAGE clause appears in a Format 1 or Format 2 entry, at least one subordinate entry must define a printable item.
   2. In Format 3, the USAGE clause must define a printable item.
5. An entry containing a LINE NUMBER clause must not have a subordinate entry that also contains a LINE NUMBER clause.

Format 1

6. group-data-name is required only when:
   1. A GENERATE statement references a DETAIL report group.
   2. An UPON phrase of a SUM clause references a DETAIL report group.
   3. A USE BEFORE REPORTING sentence references a DETAIL report group.
   4. The name of a CONTROL FOOTING report group qualifies a reference to a sum counter.
   
   If specified, group-data-name can be used as a sum counter qualifier and can be referenced only by:
   • GENERATE statements
   • UPON phrases of the SUM clause
   • USE BEFORE REPORTING declaratives

Format 2

7. level-number can be any integer from 02 to 48 inclusive.
8. A Format 2 entry must contain at least one optional clause.
9. In a Format 2 entry, group-data-name is optional. It can only qualify a sum counter reference.

Format 3

10. level-number can be any integer from 02 to 49 inclusive.
11. A GROUP INDICATE clause can appear only in a DETAIL report group.
12. A SUM clause can appear only in a CONTROL FOOTING report group.
13. An entry containing a COLUMN NUMBER clause but no LINE NUMBER clause must be subordinate to an entry containing a LINE NUMBER clause.
14. group-data-name is optional but can be specified in any entry. group-data-name can be referenced only if the entry defines a sum counter.
15. A LINE NUMBER clause must not be the only clause specified. Refer to Syntax Rule 3d.
16. An entry containing a VALUE clause must also have a COLUMN NUMBER clause.
17. A printable item is a data item whose size and content are specified by an elementary report entry.
18. An elementary report entry contains a COLUMN NUMBER clause, a PICTURE clause, and a SOURCE, SUM, or VALUE clause.
19. Figure 5-7 shows all permissible clause combinations for Format 3. You read the table from left to right along the selected row.

Figure 5-7 Format 3 Clause Combinations

General Rules

1. Format 1 is the Report Group entry. The report group is defined by the contents of this entry and all of its subordinate entries.
2. The BLANK WHEN ZERO clause, the JUSTIFIED clause, and the PICTURE clause for Report Writer are the same as those in the Data Description Section.

Examples

The Compaq COBOL User Manual contains examples of each report group description entry format.

5.3.6 Screen Description

Function

A screen description entry describes a video form or a portion of a video form and specifies the attributes, behavior, size, and location of screen items within the video form. The screen description entry is referenced in the Procedure Division by the ACCEPT and DISPLAY statements.

Syntax Rules

All Formats

1. level-number can be any number from 01 to 49.
2. Each elementary screen description entry must contain at least one of the following clauses:

   BELL
   BLANK
   COLUMN
   LINE
   PICTURE
   VALUE

3. If the FOREGROUND-COLOR, BACKGROUND-COLOR, or SIGN clauses are specified in both the group screen description entry and the subordinate description entry for a screen item, then the subordinate screen description entry's clauses will take effect.
4. screen-name assigns a name to the screen item described in the screen description entry and must conform to the rules for user-defined names. If either the optional screen-name or the key word FILLER is specified, it must be the first word following the level number in each screen description entry.
5. If both screen-name and FILLER are omitted, the screen item being described is treated as though FILLER had been specified, and cannot be referenced in an ACCEPT or DISPLAY statement.
6. Each level 01 item must have a screen name.
7. A screen item can be referenced only in an ACCEPT or DISPLAY statement.
8. color-num-1 and color-num-2 are integers in the range 0--7. color-num-1 and color-num-2 represent specific colors as described in Table 5-5:

   Table 5-5 Color Table

   Color	Color Value	Color	Color Value
   Black	0	Red	4
   Blue	1	Magenta	5
   Green	2	Yellow/Brown	6
   Cyan	3	White	7

9. The USING phrase is equivalent to the combination of FROM and TO phrases, each specifying the same identifier.
10. identifier-3, identifier-4 and identifier-5 must be defined in the File, Working-Storage, or Linkage Section.
11. identifier-1 and identifier-2 must be described as elementary unsigned numeric integer data items.
12. literal-1 must be a nonnumeric literal.
13. For a description of picture-string-1, see the Section 5.3.37 Clause section of this chapter.

General Rules

All Formats

1. An input screen item is one whose description contains a TO clause.
2. An output screen item is one whose description contains a FROM clause.
3. A literal screen item is one whose description contains a VALUE clause.
4. An update screen item is one whose description contains a USING clause.
5. An input-output screen item is one whose description contains both a FROM phrase and a TO phrase that may or may not reference the same identifier. The rules for update screen items also apply to input-output screen items.
6. The LINE and COLUMN clauses should not be specified within a screen description entry in such a way that fields overlap on the screen or fall beyond the screen boundaries.

Format 1

7. Format 1 is used for group screen items.
8. All clauses within a group screen description entry are inherited by subordinate screen description entries with the exception of the BLANK SCREEN clause.
9. If the SECURE clause is specified, it applies to each subordinate input screen item.
10. If the AUTO, FULL, or REQUIRED clauses are specified, they apply to each subordinate input and update screen item.
11. If the BACKGROUND-COLOR, FOREGROUND-COLOR, or SIGN clauses are specified, they apply to each subordinate input, output, and update screen item.

Format 2

12. Format 2 is used to describe a literal screen item.

Format 3

13. Format 3 is used to describe input, output, or update screen items.

Function

The ACCESS MODE clause specifies the order of access for a file's records.

rel-key

is the file's RELATIVE KEY data item.

Syntax Rules

1. rel-key must be the data-name of an unsigned integer data item whose description does not contain a PICTURE symbol (P). It can be qualified but cannot be in a record description entry for the same file-name.
2. The ACCESS MODE clause can be in the file's SELECT clause. However, it cannot be in both the SELECT clause and file description entry for the same file.
3. If the USING or GIVING phrases of a SORT or MERGE statement contain the name of the file, the ACCESS MODE RANDOM clause cannot be used for the file.
4. If rel-key is associated with an external file connector, rel-key must reference the same data item in every program in the run unit.
5. If a START statement references a relative file, the program must specify the RELATIVE KEY phrase for that file.

General Rules

All Formats

1. If there is no ACCESS MODE clause, the access mode is sequential.
2. For sequential access, the sequence in which the program accesses the records depends on the organization of the file, as follows:
   • Sequential files---The sequence is the same as that established by the execution of WRITE statements that created or extended the file.
   • Relative files---The sequence is the order of ascending relative record numbers of the file's existing records.
   • Indexed files---The sequence is the sort order (ascending or descending) of record key values in the established Key of Reference.

Formats 2 and 3

3. For random access, the value of rel-key (for relative files) or a Record Key data item (for indexed files) indicates the record to be accessed.
4. For dynamic access, the program can access records sequentially and randomly.

Format 2

5. Relative record numbers uniquely identify records in relative files. A record's relative record number identifies its ordinal position in the file. The first record in the file has a relative record number of 1. Subsequent records have consecutively higher relative record numbers.
6. The Relative Key data item associated with the execution of an Input/Output statement is rel-key in the file description entry (or SELECT clause) associated with the statement.

Function

The ALTERNATE RECORD KEY clause specifies an alternate access path to indexed file records.

General Format

alt-key

is the Record Key for the file. It is the data-name of a data item in a record description entry for the file. It can be qualified, but it cannot be a group item that contains a variable-occurrence data item. The data item must be described as one of the following:

• Alphanumeric item
• Alphabetic item
• Group item
• Unsigned numeric display item
• COMP-3 integer
• COMP integer

seg-key

is a segmented-key name that represents the concatenation of one or more (up to eight) occurrences of seg.

seg

is the data-name of a data item in a record description entry for the file. It can be qualified, but it cannot be a group item that contains a variable-occurrence data item. The data item must be described as one of the following:

• Alphanumeric item
• Alphabetic item
• Group item
• Unsigned numeric display item

Syntax Rules

1. The ALTERNATE RECORD KEY clause can be in the file's SELECT clause. However, for the same file, it cannot be in both the SELECT clause and file description entry.
2. alt-key or the segments of seg-key cannot have the same leftmost character position as that of the Prime Record Key data item or any other alt-key or segment of seg-key for the same file.

General Rules

1. seg-key is the concatenation of all specified key segments in the order specified.
2. seg-key can be referenced only in a READ (Format 3) or START statement.
3. When a program creates an indexed file with one or more ALTERNATE RECORD KEY clauses, each subsequent program referencing this indexed file must:
   • Use the same data description for alt-key or the segments of seg-key.
   • Define the same relative location in the record as alt-key or the segments of seg-key.
   • Specify the same number (or less) of ALTERNATE RECORD KEY clauses.
     On Tru64 UNIX and Windows NT systems, you can specify a different number of keys than was specified when the file was created, if the relaxed key check option ( -relax_key_checking ) is used. <>
   • Maintain the same order of ALTERNATE RECORD KEY clauses.
   • Specify the same order of keys (ASCENDING or DESCENDING) in each ALTERNATE RECORD KEY clause as the order used when the file was created.
4. The DUPLICATES phrase specifies that two or more records in the file can have duplicate values in the same alt-key or the segments of seg-key. If there is no DUPLICATES phrase, two records cannot have the same value in corresponding Alternate Record Keys.
   On OpenVMS, if the program was compiled with the /CHECK=DUPLICATE_KEYS qualifier on the command line, and the duplicate key specification on a file's FD (in other words, specified in the WITH DUPLICATES phrase) does not match that of the actual file, a run-time diagnostic will be issued when an attempt is made to open the file with an OPEN statement.
   The /CHECK=DUPLICATE_KEYS qualifier is not supported for remotely accessed files. Duplicate keys, key length, and number of keys are not checked for remote files, that is, files accessed over the network. <>
   On Tru64 UNIX and Windows NT systems, DUPLICATES must match the specification for DUPLICATES when the file was created, unless the relaxed key check option is used. <>
5. If a file has more than one record description entry, only one of these record description entries must describe alt-key or the segments of seg-key. The character positions referenced by alt-key or the segments of seg-key in that record description are implicitly referenced in all other record description entries for the file.
6. A file can have up to 254 Alternate Record Keys.
7. If the associated file connector is an external file connector, all File Description entries in the run unit that are associated with the file connector must define the same data description entry for alt-key or the segments of seg-key, with the same relative location within the record.
8. Each key can be specified as ASCENDING or DESCENDING (ASCENDING is the default). In an ASCENDING key, lower key values occur toward the beginning of the sorted file. In a DESCENDING key, higher key values occur toward the beginning of the sorted file.

Additional Reference

• Section 5.3.39 clause
• Section 6.8.33 statement in Chapter 6
• Section 6.8.21 statement in Chapter 6

Function

In the context of ACCEPT, the AUTO clause moves the cursor to the next field when the last character of an input or update field that was defined with the AUTO clause is entered.

Syntax Rule

The AUTO clause cannot be specified in the description of a literal screen item.

General Rules

1. If the AUTO clause is specified at group level, it applies to each input and update screen item in that group.
2. The AUTO clause is significant in the context of an ACCEPT.
3. The AUTO clause is ignored in the description of an output screen item.
4. If there is only one field to input, or if the field is the last one of the screen, the ACCEPT statement is completed when the last character of the field is entered.

Additional Reference

Section 6.8.1 statement in Chapter 6

Function

The BACKGROUND-COLOR clause specifies the background color for the screen item.

color-num

is an integer in the range 0--7 specifying a color as follows:

Color	Color Value	Color	Color Value
Black	0	Red	4
Blue	1	Magenta	5
Green	2	Yellow/Brown	6
Cyan	3	White	7

Syntax Rule

The BACKGROUND-COLOR clause can be specified in any screen description entry.

General Rules

1. The BACKGROUND-COLOR clause is effective only with color screens.
2. If the BACKGROUND-COLOR clause is omitted, the initial default background color is black.
3. If the clause is specified at group level, it applies to all subordinate screen items.
4. If the BLANK SCREEN clause is specified and the BACKGROUND-COLOR clause is specified or inherited, then when a DISPLAY statement displays the screen item, the specified color becomes the default background color. It remains the default background color until another screen item with this combination of options is displayed (whether in the same DISPLAY statement or in another).

Technical Note

The colors in the list above are supported only on terminals and workstations that support the ANSI Standard color sequences. ¹

Additional References

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

Function

The BELL clause sounds the workstation or terminal audio tone.

Syntax Rule

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

General Rule

The audio tone sounds when a DISPLAY statement displays a screen item whose description contains a BELL clause.

Additional Reference

Section 6.8.10 statement in Chapter 6

Function

The BLANK clause clears a screen line or clears the whole screen before displaying the screen item.

Syntax Rules

1. The BLANK SCREEN clause can be specified for any screen description entry.
2. The BLANK LINE clause can be specified only for elementary screen description entries.

General Rules

1. The BLANK SCREEN clause executes before a screen item displays, no matter where it appears in the screen item's description. When the BLANK SCREEN clause is specified, the screen is cleared and the cursor is placed at line 1, column 1.
2. When BLANK LINE is specified in an elementary screen item's description, blanking begins at column 1 of the specified line and continues through to the end of the line.
3. If neither the BLANK clause nor the ERASE clause is specified, only the particular character positions corresponding to the screen item are modified when the item is displayed. The remainder of the screen content is not changed.
4. The BLANK SCREEN clause returns the screen to the initial defaults for background and foreground color if the BACKGROUND-COLOR and FOREGROUND-COLOR clauses are not specified, respectively.
5. The BLANK clause is ignored in an ACCEPT statement.

Additional Reference

Section 6.8.10 statement in Chapter 6