RECORD clause

Function

The RECORD clause defines the length of the records in a file and controls the external record format (for sequentially organized files, see also the "RECORDING MODE clause").

Format 1	Indicates fixed-length records by specifying the number of bytes in a record.
Format 2	Indicates variable-length records, whereby the size of the record must lie within a certain range.
Format 3	Indicates variable-length records, whereby the minimum and maximum number of bytes are specified.

Format 1

---

RECORD CONTAINS integer-1 CHARACTERS

---

Syntax rules

1. The length of each record is precisely defined by its record description entry. The length specification in the RECORD clause is ignored in this respect.

2. The number of bytes in each record description entry for the file must be equal to integer-1.

3. integer-1 must be at least 1 and at most 32767. When the RECORD clause is used in a sort file description entry, the maximum permitted value for integer-1 is equal to 32755 minus the sort key length.

Format 2

---

RECORD IS VARYING IN SIZE [[FROM integer-2] [TO integer-3] CHARACTERS]

    [DEPENDING ON file-name-1]

---

Syntax rules

1. In any record description entry, it is impermissible for the length specification to be less than integer-2 or more than integer-3.

2. integer-3 must be larger than integer-2.

3. integer-2 must be larger than 0 or equal 0, while integer-3 can be at most 32763. When the RECORD clause is used in a sort file description entry, the maximum permitted value for integer-3 is equal to 32751 minus the sort key length.

4. data-name-1 must be described as an unsigned integer data item in the WORKING-STORAGE, LOCAL-STORAGE or LINKAGE SECTION.

5. This format must not be specified for relative organized files which are to be processed using the DMS access method UPAM (see "COBOL2000 User Guide" [1]).

General rules

1. If integer-2 is omitted, it is assumed that the length of the shortest record is 1. For each SORT or MERGE statement, the sort key must lie completely within the range of this minimal length.

2. If integer-3 is omitted, the length of the longest record in the record description entry for this file is assumed. This number also provides the block size.

3. If data-name-1 is specified, the number of bytes in the record must be moved to data-name-1 before a RELEASE, REWRITE or WRITE statement is executed for this file.

4. If data-name-1 is specified, its contents remain unchanged when a RELEASE, REWRITE or WRITE statement is executed or when a READ or RETURN statement terminates abnormally.

5. During execution of a RELEASE, REWRITE or WRITE statement, the record length is determined as follows:

   1. If data-name-1 is specified: by the contents of the data item referenced by data-name-1.

   2. If data-name-1 is omitted and the record description entry has no OCCURS clause with DEPENDING ON phrase: by the number of bytes in the record.

   3. If data-name-1 is not specified and the record description entry contains no OCCURS clause with DEPENDING ON phrase: by the fixed portion of the record description entry (i.e. all data description entries without the DEPENDING ON phrase) and by the number of occurrences of the table elements during execution of the statement.

6. If data-name-1 is specified and a READ statement has been successfully executed, data-name-1 contains the number of bytes of the record just read. This number is, however, not greater than integer-3, but it may be larger than the largest record description entry.

7. If INTO is specified in a READ or RETURN statement, the number of bytes in the current record, which is the source field in the implicit MOVE, is determined as follows:

   1. If data-name-1 is specified: by the contents of the data item referenced by data-name-1.

   2. If data-name-1 is not specified: by the value that would have been transferred had data-name-1 been specified.

8. If the number of bytes determined is 0, the record is a zero-length item.

Format 3

---

RECORD CONTAINS integer-4 TO integer-5 CHARACTERS

---

Syntax rules

1. integer-4 describes the number of bytes in the shortest record; integer-5 the number in the longest.

2. In no record description entry for the file may the length be less than specified in integer-4 or greater than specified in integer-5.

3. integer-5 must be greater than integer-4.

4. integer-4 must be larger than 0 or equal to 0, integer-5 must not exceed 32763. When the RECORD clause is used in a sort file description entry, the maximum permitted value for integer-5 is 32751 minus the sort key length.

5. This format must not be specified for relative organized files which are to be processed using the DMS access method UPAM (see "COBOL2000 User Guide" [1]).

General rules for all formats

1. The length of each record is precisely defined by its record description entry. If the RECORD clause is specified, the length is compared with the specifications given in the clause (for sequentially organized files, see also the "RECORDING MODE clause").

2. The length of a record is determined by the sum of the bytes of all its elementary items and the slack bytes generated by the compiler. If the record contains a table, the minimum or maximum number of table elements is taken into account when calculating the length. For further details, see section "SYNCHRONIZED clause", section "USAGE clause" and section "Implementor-dependent representation and alignment of data".

3. If the RECORD clause is not specified, the minimum or maximum record length results from the specifications in the corresponding record description entry. If a record description entry contains an OCCURS clause with the DEPENDING phrase, the value 1 is assumed as the minimum record length for this.

4. If the RECORD clause is specified for an external file, a RECORD clause of the same format must be specified in all programs that describe this external file; the minimum and maximum record lengths calculated from the specifications in the RECORD clause must match those from the corresponding record description entries.

5. The following table shows which specifications in the formats of the RECORD clause are decisive in calculating the minimum and maximum record lengths.

   	Format 1	Format 2	Format 3	No RECORD clause
   Minimum record length	Longest record of record description entry	integer-2; if not specified: 1	integer-4	Shortest record of record description entry; with OCCURS DEPENDING: 1
   Maximum record length	as above	integer-3; if not specified: longest record of record description entry	integer-5	Longest record of record description entry

   Table 12: Specifications in the RECORD clause

6. The specified maximum limits are reduced by 8 bytes for files with relative organization.

7. If the number of bytes determined is 0, the record is a zero-length item.