HP OpenVMS Systems Documentation

HP COBOL
Reference Manual

Additional References

• Section 5.3.21 clause
• Section 5.3.49 clause
• Section 5.3.52 clause
• Section 5.3.4

Function

The RECORD KEY clause specifies the Prime Record Key access path to indexed file records.

rec-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 Rule

The RECORD KEY clause is required for indexed files. It can be in either the file description entry or in the file's Environment Division SELECT clause. However, it cannot be in both the SELECT clause and the file description entry 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. The RECORD KEY clause specifies the Prime Record Key for a file.
4. The order of keys, whether ASCENDING or DESCENDING, must be the same as the order used when the file was created.
5. 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.
6. The data description of rec-key, or the segments of seg-key, and their relative locations in the record, must be the same as those used when the file was created.
7. Only one record description entry for the file must describe rec-key or the segments of seg-key. The Prime Record Key has the same character positions in every record of the file.
8. If the associated file connector is an external file connector, all File Description entries in the run unit that are associated with that file connector must define the same data description entry for rec-key or the segments of seg-key with the same relative location within the record.
9. The DUPLICATES phrase specifies that two or more records in the file can have duplicate values in the same rec-key or the segments of seg-key. If there is no DUPLICATES phrase, two records cannot have the same value in corresponding Prime Record Key.
   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. <>
   On Tru64 UNIX systems, DUPLICATES must match the specification for DUPLICATES when the file is created, unless the relaxed key check option is used. <>

Additional Reference

Section 5.3.8

Function

The REDEFINES clause allows different data description entries to describe the same storage area.

other-data-item

is a data-name. It identifies the data description entry that first defines the storage area.

Note Level-number, data-name, and FILLER are not part of the REDEFINES clause. They are included in the general format only to clarify the relative position of the clause.

Syntax Rules

1. The subject of the REDEFINES clause is the data-name or FILLER in a Format 1 data description entry.
2. The REDEFINES clause must immediately follow its subject.
3. The level-numbers of the subject of the REDEFINES clause and other-data-item must be the same. However, they cannot be either 66 or 88.
4. The REDEFINES clause cannot be used in a level 01 entry in the File Section.
5. The data description entry for other-data-item cannot contain an OCCURS clause. However, other-data-item can be subordinate to an item whose data description entry contains an OCCURS clause. In that case, the reference to other-data-item in the REDEFINES clause cannot be subscripted or indexed.
6. Neither the original definition nor the redefinition can contain a variable occurrence data item.
7. If other-data-item is either an external record or anything other than a level 01 entry, the number of character positions it contains must be greater than or equal to the number in the subject of the REDEFINES clause. If other-data-item is a level 01 entry, and is not an external record, its description need not follow this rule; that is, other-data-item can contain fewer character positions than the subject of the REDEFINES clause.
8. Other-data-item cannot be qualified even if it is not unique. The reference to other-data-item is unique without qualification because of the placement of the REDEFINES clause.
9. A program can have multiple redefinitions of the same character positions. However, they must all refer to other-data-item, the data-name that originally defined the area.
10. The redefining entries cannot contain VALUE clauses except in condition-name entries.
11. No entry with a level-number lower than that of other-data-item can occur between the data description entry for other-data-item and the redefinition.
12. The entries redefining the storage area must immediately follow those that originally defined it. There can be no intervening entries that define additional storage areas.

General Rules

1. Storage allocation starts at the location of other-data-item. Storage allocation continues until it defines the number of character positions in the data item referred to by the subject of the REDEFINES clause.
2. If more than one data description entry defines the same character position, the program can refer to the character position using the data-name associated with any of those data description entries.

Additional References

• Section 5.3.4 entry
• Section 5.2.3, Additional Alignment Rules for Record Allocation

Example

This example shows the following:

• A sample program containing multiple redefinitions of the same area
• The results of the sample program statements
• The allowable subscripts and the contents for each data item in the program

Function

The RENAMES clause groups elementary items in alternative or overlapping ways.

new-name

is the data-name of the item being described. It identifies an alternate grouping of one or more items in a record.

rename-start

is the data-name of the leftmost data item in the area. It can be qualified.

rename-end

is the data-name of the rightmost data item in the area. It can be qualified.

Note Level-number 66 and new-name are not part of the RENAMES clause. They are in the general format only to clarify the relationship.

Syntax Rules

1. A logical record can have any number of RENAMES entries.
2. All RENAMES entries referring to data items in a logical record must immediately follow the last data description entry of the record description entry.
3. The program cannot qualify data-names with new-name.
4. The program can qualify new-name only by the names of the associated level 01, FD, or SD entries.
5. The data description entries for rename-start and rename-end:
   • Cannot have an OCCURS clause
   • Cannot be subordinate to an item whose data description entry has an OCCURS clause
6. rename-start and rename-end must be the names of elementary items or groups of elementary items in the same logical record. They cannot be the same data-name.
7. A level 66 entry cannot rename another level 66 entry. Nor can it rename a level 88, level 01, or level 77 entry.
8. None of the items in the range, including rename-start and rename-end, can be variable occurrence data items.
9. The words THRU and THROUGH are equivalent.
10. rename-end cannot be subordinate to rename-start. The beginning of rename-end cannot be to the left of the beginning of rename-start. The end of rename-end must be to the right of the end of rename-start.

General Rules

1. If rename-end is used, new-name includes all elementary items:
   • Starting with rename-start, if rename-start is an elementary item or the first elementary item in rename-start, or if rename-start is a group item
   • Ending with rename-end, if rename-end is an elementary item or the last elementary item in rename-end, or if rename-end is a group item
2. If rename-end is not used, all data attributes for rename-start become data attributes for new-name. In this case, you are renaming a single data item. If that item is a group item, new-name is also treated as a group item. If that item is an elementary item, new-name is also treated as an elementary item.