File Description Clauses COBOL

The file description clauses are placed between the FD or SD file-name-1 declaration and the first of the subordinate record description entries. They serve to specify or document characteristics that are relevant to the file as a whole rather than to particular records.

BLOCK CONTAINS Clause

BLOCK CONTAINS Clause

The BLOCK CONTAINS clause specifies the size of a physical record.

This clause is required except when:

  • A physical record contains only one complete logical record.
  • The device assigned to the file has only one physical record size.
  • The number of records contained in a block is specified in the runtime environment.

The size of the physical record may be stated in terms of RECORDS, unless one of the following situations exists, in which case the RECORDS phrase must not be used:

  • In mass storage files where logical records may extend across physical records.
  • The physical record contains padding.
  • If logical records are grouped in such a manner that an inaccurate physical record size would be implied.

When the word CHARACTERS is specified, the physical record size is specified in terms of the number of character positions required to store the physical record, regardless of the types of characters used to represent the items within the physical record.

If only integer-2 is specified, it represents the exact size of the physical record. If integer-1 and integer-2 are specified, they refer to the minimum and maximum size of the physical record, respectively.

If the associated file connector is an external file connector, all BLOCK CONTAINS clauses in the run unit that are associated with that file connector must have the same value for integer-1 and integer-2.

CODE-SET Clause

CODE-SET IS alphabet-name-1

The CODE-SET clause specifies the character code convention used to represent data on the external media.

When the CODE-SET clause is specified for a file, all data in that file must be described as usage is DISPLAY and any signed numeric data must be described with the SIGN IS SEPARATE clause.

If the CODE-SET clause is specified, alphabet-name-1 specifies the character code convention used to represent data on the external media. It also specifies the algorithm for converting the character codes on the external media to or from the native character codes. This code conversion occurs during the execution of an input or output operation.

If the CODE-SET clause is not specified, the native character code set is assumed for data on the external media.

If the CODE-SET clause is specified in both the file control entry and the file description entry for a file, the two alphabet-names must be the same. If the associated file connector is an external file connector, all CODE-SET clauses in the run unit which are associated with that file connector must have the same character set.

DATA RECORDS Clause

DATA RECORDS Clause

The DATA RECORDS clause serves only as documentation for the names of data records with their associated file.

data-name-3 is the name of a data record and must have a 01 level-number record description, with the same name, associated with it.

The presence of more than one data-name indicates that the file contains more than one type of data record. These records may be of different sizes, different formats, and so forth. The order in which they are listed is not significant.

All data records within a file share the same area, whether or not they are of the same type.

EXTERNAL Clause

IS EXTERNAL

The EXTERNAL clause specifies that a file connector is external.

Use of the EXTERNAL clause does not imply that the associated file-name is a global name.

The file connector associated with this description entry is an external file connector. The data records described subordinate to this file description entry, as well as any data items described subordinate to the data description entries for such records, attain the external attribute.

GLOBAL Clause

IS GLOBAL

The GLOBAL clause specifies that a file-name is a global name. A global name is available to every program contained within the program which declares it.

A file-name described using a GLOBAL clause is a global name. All data-names subordinate to a global name are global names. All condition-names and split-key-names associated with a global name are global names.

A statement in a program contained directly or indirectly within a program which describes a global name may reference that name without describing it again.

If the SAME RECORD AREA clause is specified for several files, the record description entries or the file description entries for these files must not include the GLOBAL clause.

LABEL RECORDS Clause

LABEL RECORDS Clause

The LABEL RECORDS clause specifies whether labels are present.

The OMITTED option specifies that no explicit labels exist for the file or the device to which the file is assigned. The STANDARD option specifies that labels exist for the file or the device to which the file is assigned and that they conform to the conventions of the runtime environment.

Omission of the LABEL RECORDS clause from a file description entry is equivalent to specifying LABEL RECORDS OMITTED.

If a VALUE OF clause is present in a file description entry, a LABEL RECORDS OMITTED clause is not allowed.

If the file connector associated with this file description entry is an external file connector, all LABEL RECORDS clauses in the run unit that are associated with this file connector must have the same specification.

LINAGE Clause

LINAGE Clause

The LINAGE clause provides a means for specifying the depth of a logical page in number of lines. It also allows for the specification of the top and bottom margins on the logical page and the line number at which the footing area begins.

data-name-4, data-name-5, data-name-6, data-name-7 must reference unsigned numeric integer data items.
data-name-4, data-name-5, data-name-6, data-name-7 may be qualified.

If any of data-name-4, data-name-5, data-name-6, or data-name-7 is specified, is not qualified, and is not defined in the Data Division, the compiler assumes a Working-Storage Section data description entry for that respective data-name of the following form:

01 data-name-n PIC 9(9) BINARY(4).

The LINAGE clause may only be used in a file description entry for a sequential organization file.

The LINAGE clause provides a means for specifying the size of a logical page in terms of number of lines. The logical page size is the sum of the values referenced by each phrase except the FOOTING phrase. If the LINES AT TOP or LINES AT BOTTOM phrases are not specified, the values of these items are zero. If the FOOTING phrase is not specified, no end-of-page condition independent of the page overflow condition exists.

There is not necessarily any relationship between the size of the logical page and the size of the physical page. Each logical page is contiguous to the next with no additional spacing provided. When a LINAGE file is written, form feed characters are not used because they cause the printer to advance to the next physical page. The LINAGE-PAGES-PER-PHYSICAL-PAGE in the PRINT-ATTR runtime configuration record may be used to cause form feeds to be generated between a specified number of logical pages, that is, the option specifies the number of logical pages that fit on a physical page.

integer-7 or the value of the data item referenced by data-name-4 specifies the number of lines that can be written, spaced, or both, on the logical page. The value must be greater than zero. That part of the logical page in which these lines can be written or spaced is called the page body.

integer-8 or the value of the data item referenced by data-name-5 specifies the line number within the page body at which the footing area begins. The value must be greater than zero and not greater than integer-7
or the value of the data item referenced by data-name-4.

The footing area comprises the area of the page body between the line represented by integer-8 or the value of the data item referenced by data-name-5, and the line represented by integer-7 or the value of the data item referenced by data-name-4, inclusive. When lines are written or spaced in the footing area, an end-of-page condition occurs. The end-of-page condition can be detected by the END-OF-PAGE (or EOP) phrase of the WRITE statement.

integer-9 or the value of the data item referenced by data-name-6 specifies the number of lines that comprise the top margin on the logical page. The value may be zero.

integer-10 or the value of the data item referenced by data-name-7 specifies the number of lines that comprise the bottom margin on the logical page. The value may be zero.

integer-7, integer-9 and integer-10, if specified, are used at the time the file is opened by the execution of an OPEN statement with the OUTPUT phrase, to specify the number of lines that make up each of the indicated sections of a logical page.

integer-8, if specified, is used at that time to define the footing area. These values are used for all logical pages written for that file during an execution of the program.

The values of the data items referenced by data-name-4, data-name-6 and data-name-7, if specified, are used as follows:

  • The values of the data items, at the time an OPEN statement with the OUTPUT phrase is executed for the file, are used to specify the number of lines that make up each of the indicated sections for the first logical page.
  • The values of the data items, at the time a WRITE statement with the ADVANCING PAGE phrase is executed or a page overflow condition occurs, are used to specify the number of lines that make up each of the indicated sections for the next logical page.

The value of the data item referenced by data-name-5, if specified, at the time an OPEN statement with the OUTPUT phrase is executed for the file, is used to define the footing area for the first logical page. At the time a WRITE statement with the ADVANCING PAGE phrase is executed or a page overflow condition occurs, it is used to define the footing area for the next logical page.

A LINAGE-COUNTER is generated by the presence of a LINAGE clause. The value in the LINAGE-COUNTER at any given time represents the line number at which the device is positioned within the current page body. The rules governing the LINAGE-COUNTER are as follows:

  1. A separate LINAGE-COUNTER is supplied for each file whose file description entry contains a LINAGE clause.
  2. LINAGE-COUNTER may be referenced only in Procedure Division statements; however, only the runtime system may change the value of LINAGE-COUNTER. Since more than one LINAGE-COUNTER may exist in a program, the user must qualify LINAGE-COUNTER by file-name-1 when necessary.
  3. The LINAGE-COUNTER special register behaves as if it were described as PIC 9(n) BINARY, where n represents the number of 9's in the PICTURE character-string for data-name-4 or the number of digits specified in integer-7. The number of character positions (bytes) allocated for the LINAGE-COUNTER special register is determined by the value of n and the configured binary allocation scheme.

If the file description entry for a sequential file contains the LINAGE clause and the EXTERNAL clause, the LINAGE-COUNTER data item is an external data item. If the file description entry for a sequential file contains the LINAGE clause and the GLOBAL clause, the special register LINAGE-COUNTER is a global name.

LINAGE-COUNTER is automatically modified, according to the following rules, during the execution of a WRITE statement to an associated file:

  1. When the ADVANCING PAGE phrase of the WRITE statement is specified, the LINAGE-COUNTER is automatically reset to one. During the resetting of the LINAGE-COUNTER to the value one, the value of LINAGE-COUNTER is implicitly incremented to exceed the value specified by integer-7 or the data item referenced by data-name-4.
  2. When the ADVANCING id entifier-2 or integer-1 phrase of the WRITE statement is specified, the LINAGE-COUNTER is incremented by integer-1 or the value of the data item referenced by identifier-2.
  3. When the ADVANCING phrase of the WRITE statement is not specified, the LINAGE-COUNTER is incremented by the value one.
  4. The value of LINAGE-COUNTER is automatically reset to one when the device is repositioned to the first line that can be written on for each of the succeeding logical pages.

The value of LINAGE-COUNTER is automatically set to one at the time an OPEN statement with the OUTPUT phrase is executed for the associated file.

If the file connector associated with this file description entry is an external file connector, all file description entries in the run unit that are associated with this file connector must have:

  1. A LINAGE clause, if any file description entry has a LINAGE clause.
  2. The same corresponding values for integer-7, integer-8, integer-9 and integer-10, if specified.
  3. The same corresponding external data items referenced by data-name-4, data-name-5, data-name-6 and data-name-7.

Figures illustrate the logical page layout for the LINAGE clause.

General LINAGE Clause

General LINAGE Clause

Example LINAGE Clause

Example LINAGE Clause

RECORD Clause

RECORD Clause

The RECORD clause specifies the size of the data records. Record descriptions for the file must not describe records which contain less character positions than that specified by integer-3, integer-5 or records which contain more character positions than that specified by integer-4 or integer-6 .

integer-4 must be greater than or equal to integer-3.

integer-6 must be greater than integer-5.

data-name-1 must describe an elementary unsigned integer in the Working-Storage or Linkage Section. data-name-1 may be qualified. If data-name-1 is specified, is not qualified, and is not defined in the Data Division,the compiler assumes a Working-Storage Section data description entry of the following form:

01 data-name-1 PIC 9(9) BINARY(4).

If the RECORD clause is not specified, the size of each data record is fully defined in the record description entry.If all record description entries describe the same number of character positions—and none contain Format 2 of the OCCURS clause—the file will be a fixed-length record file; otherwise, the file will be a variable-length record file.

If the associated file connector is an external file connector, all file description entries in the run unit which are associated with that file connector must specify the same values for integer-3 and integer-4,or integer-5And integer-6. If the RECORD clause is not specified, all record description entries associated with this file connector must be the same length.

  1. integer-4, used by itself, indicates that all the data records in the file have the same size. In this case, integer-4 represents the exact number of characters in the data record. The file will be a fixed-length record file, even if varying length record descriptions are associated with it.
  2. If integer-3 and integer-4 are both shown, they refer to the minimum number of characters in the smallest size data record and the maximum number of characters in the largest size data record, respectively. If integer-3 is not equal to integer-4, the file will be a variable-length record file, even if fixed-length record descriptions are associated with it.
  3. The size is specified in terms of the number of character positions required to store the logical record, regardless of the types of characters used to represent the items within the logical record

The size of a record is determined by the sum of the number of characters in all fixed-length elementary items, plus any filler characters generated between elementary items because of explicit or implicit synchronization. If the record is variable length, the minimum number of characters in a variable-occurrence data item is added to the fixed size to get the minimum record size. The maximum number is added to the fixed size to get the maximum record size.

The IS VARYING IN SIZE phrase is used to specify variable record lengths. integer-5 specifies the minimum number of character positions in any record of the file. integer-6 specifies the maximum number of character positions in any record in the file.

If data-name-1 is specified, the number of character positions in the record must be placed into the data item referenced by data-name-1 before any RELEASE, REWRITE or WRITE statement is executed for the file.

If data-name-1 is specified, the execution of a DELETE, RELEASE, REWRITE, START or WRITE statement or the unsuccessful execution of a READ or RETURN statement does not alter the content of the data item referenced by data-name-1.

During the execution of a RELEASE, REWRITE or WRITE statement, the number of character positions in the record is determined by one of the following conditions:

  • If data-name-1 is specified, by the content of the data item referenced by data-name-1.
  • If data-name-1 is not specified and the record does not contain a variable-occurrence data item, by the number of the character positions in the record.
  • If data-name-1 is not specified and the record contains a variable-occurrence data item, by the sum of the fixed portion and that portion of the table described by the number of occurrences at the time of the execution of the output statement.

If data-name-1 is specified, after the successful execution of a READ or RETURN statement for the file, the contents of the data item referenced by data-name-1 will indicate the number of character positions in the record just read or returned.

When an INTO phrase is specified in a READ or RETURN statement, the number of character positions in the current record that participate as the sending data item in the implied MOVE is the number of character positions in the record just read or returned.

VALUE OF Clause

VALUE OF Clause

The VALUE OF clause particularizes the description of an item in the label records associated with a file or specifies the file access name.

label-name-1 may be FILE-ID, LABEL or any user-defined word.

When label-name-1 is FILE-ID, data-name-2 or literal-1 specifies the file access name for the file. VALUE OF FILE-ID provides an alternative to specifying the file access name in the ASSIGN clause of the file control entry. If the file access name is specified in both alternatives, the same data-name or literal must be specified in each; otherwise, the value specified in the file control entry will take precedence. If the file access name is not specified in either the file control entry or the file description entry, then file-name-1 is used as the file access name. The value of the file access name, however specified, must be valid according to the requirements of the runtime input-output system. If data-name-2 is specified for the file access name, at the time of an OPEN statement execution for file-name-1 , the value of the data item to which data-name-2 refers will be used as the file access name.

When label-name-1 is LABEL, data-name-2 or literal-1 particularizes the description of an item in the label records associated with the file. The value of this data item or literal is available to the runtime input-output system, but is not currently used for any purpose. LABEL must not be specified for label-name-1 when the OMITTED option is specified in the LABEL RECORDS clause.

When label-name-1 is a user-defined, the phrase is treated as commentary. data-name-2 or literal-1 must by syntactically correct,but have no effect on the object program.

data-name-2 may be qualified.data-name-2 must be defined in the Working-Storage Section and must not be described with the USAGE IS INDEX clause. If data-name-2 is specified, is not qualified, and is not defined in the Data Division, the compiler assumes a Working-Storage Section data description entry of the following form:

01 data-name-2 PIC X(256).

A figurative constant may be substituted for literal-1.

If the associated file connector is an external file connector, all VALUE OF clauses in the run unit which are associated with that file connector must be consistent.


All rights reserved © 2018 Wisdom IT Services India Pvt. Ltd DMCA.com Protection Status

COBOL Topics