Micro Focus Studio Enterprise Edition for Windows > General Reference > COBOL Language Reference > Part 2. Program Definition > Environment Division > Input-Output Section > The File Control Entry

The File Control Entry

The file control entry names a file and can specify other file-related information.

Although they are a part of the standard COBOL definition, the RECORD DELIMITER and RESERVE phrases and ellipses in the ASSIGN clause are explicitly excluded from the X/Open COBOL language definitions and should not be used in a conforming X/Open COBOL source program.

General Formats for Format 1 (Record Sequential Files)

General Formats for Format 2 (Line Sequential Files)

General Formats for Format 3 (Relative Files)

General Formats for Format 4 (Indexed Files)

General Formats for Format 5 (Sort-Merge Files)

Directives

In addition to Compiler directives which provide flagging and modify the reserved word list, the following directives may impact either the syntax or the semantics described in this section.
- ASSIGN - determines how the literal, data-name, or external-file-reference is evaluated.
- SEQUENTIAL - determines whether files defined as ORGANIZATION IS SEQUENTIAL are considered LINE SEQUENTIAL or RECORD SEQUENTIAL.

Syntax Rules for All Formats (All Files)

The SELECT clause must be specified first in the file control entry. The clauses which follow the SELECT clause can appear in any order.
Each file described in the Data Division must be named once, and only once, as file-name in the File-Control paragraph. Each file specified in the file control entry must have a file description entry in the Data Division of the same factory, method, object, function or program.
If the ACCESS MODE clause is not specified, the ACCESS MODE IS SEQUENTIAL clause is implied.
Data-name-1 can be declared in the Data Division as an alphanumeric or group data item long enough to hold the external name of the file. If it is not explicitly declared within the source element, your COBOL system declares it implicitly as an alphanumeric data item long enough to hold the maximum permissible size of file-name. If data-name-1 occurs in the FROM phrase, the data item must be explicitly declared in the Data Division.
The NOT OPTIONAL phrase has effect only when the file is opened input-output.
External-file-reference, data-name-1, or literal-1 specifies the external name of the file. If the EXTERNAL or DYNAMIC option is used, literal-1 must not be specified. If the DYNAMIC option is used, the word specified for the external file-name is interpreted as external-file-reference.
Data-name-2 must be defined in the Data Division as a two-character, alphanumeric data item
or a two-character numeric data item with USAGE DISPLAY

and must not be defined in the File Section

or Local-Storage Section

of the Data Division.
Data-name-3 must be defined as a group item of 6 bytes in the Working-Storage or Linkage Section of the Data Division.
Data-name-4 must be defined in the Working-Storage Section as an alphanumeric data item.
All data-names can be qualified.

Syntax Rules for Format 1 (Record Sequential Files only)

Literal-2 must be a one-character nonnumeric literal.
Data-name-5 can be qualified. It must be defined in the Data Division as a one-character data item of category alphanumeric. It cannot be defined in the File or Report Sections of the Data Division.
Character-string must not be a reserved word, a user-defined word that is defined elsewhere, or a literal.

Syntax Rules for Formats 1 and 2 (Record and Line SequentialFiles)

When the ORGANIZATION clause is not specified, sequential organization is assumed.
KEYBOARD means console input.
DISPLAY means console output.
PRINTER specifies the system's main printer.
PRINTER-1 specifies the system's second printer.

Syntax Rules for Format 3 (Relative Files)

If a relative file is to be referenced by a START statement, the RELATIVE KEY phrase must be specified for that file.
Data-name-5 must not be defined in a record description entry associated with that file-name.
The data item referenced by data-name-5 must be defined as an unsigned integer.

Syntax Rules for Format 4 (Indexed Files)

Split-key-name is a concatenation of one or more data items within a record associated with that file-name. It can be referenced only in START and READ statements.
The data items referenced by data-name-5 and data-name-8
and any data-names referenced by split-key-name-1 and split-key-name-2

must be defined within a record description entry associated with the file-name.

Any of these data items can be defined as any supported data category. However, the key is still treated as an alphanumeric item for the input and output statements against the file named in the SELECT clause.
Data-name-5 and data-name-8
and any data-names referenced by split-key-name-1 and split-key-name-2

cannot describe an item whose size is variable. See the topic The OCCURS Clause.
Data-name-8 cannot reference an item whose leftmost character position corresponds to the leftmost character position of the item referenced by data-name-5 or by another data-name-8 specified for the same file.
If the indexed file contains variable-length records, data-name-5 and data-name-8
and any data-names referenced by split-key-name-1 and split-key-name-2
shallbe contained within the first x bytes of the record, where x equals theminimum record size specified for the file. See the topic The RECORD Clause.
If the PASSWORD clause is specified, it must immediately follow its associated RECORD KEY or ALTERNATE RECORD KEY clause.

Syntax Rules for Format 5 (Sort-Merge Files)

Each sort or merge file described in the Data Division must be named once and once only as file-name in the File-Control paragraph. Each sort or merge file specified in the file control entry must have a sort-merge file description entry in the Data Division.
Since file-name represents a sort or merge file, only the ASSIGN clause is permitted to follow file-name in the File-Control paragraph.

General Rules for All Formats (All Files)

The ASSIGN clause specifies the association of the file referenced by file-name-1 to a storage medium. The first assignment takes effect.
Subsequent assignments within any one ASSIGN clause are documentary only.
The RESERVE clause allows you to specify the required number of input-output areas.
The RESERVE clause is documentary only, unless the COBOL system documentation specific to your operating system indicates otherwise.
The ORGANIZATION clause specifies the logical structure of a file. The file organization is established at the time a file is created and cannot subsequently be changed.
When the FILE STATUS clause is specified, a value is moved by the run-time system into the data item specified by data-name-2 after the execution of every statement that references that file either explicitly or implicitly. This value indicates the status of execution of the statement. (See the topic I-O Status in the chapter Procedure Division.)
Data-name-3, if specified, is documentary only.
The PASSWORD clause is documentary only.
Use of the reserved word DYNAMIC in an ASSIGN clause indicates that the value of literal-1 or data-name-1 in that ASSIGN clause is the specified file's name in the external file-storage environment.
Use of the reserved word EXTERNAL in an ASSIGN clause indicates that external-file-reference identifies the specified file to the external environment for possible further mapping to an external file-storage environment-name. (See your COBOL system documentation on file handling for details on setting up external-file-name for your particular operating environment.)
If external-file-reference contains the character "-", then only that part of the name following the last "-" is used to identify the file to the external environment.
The DISK option without external-file-reference, data-name-1 or literal-1 and without the FROM option, specifies a disk file whose name is given in a VALUE OF FILE-ID clause in the file description for the file. If that file description contains no VALUE OF FILE-ID clause, the name of the disk file is assumed to be the same as file-name-1 (known as the internal file-name).
If any of the keywords DISK, KEYBOARD, DISPLAY, PRINTER or PRINTER-1 are followed by external-file-reference, data-name-1 or literal-1, that keyword is ignored.
The DISK option with the FROM option specifies a disk file whose name on the disk is the value of data-name-1. However, if when an OPEN statement is executed for that file, data-name-1 contains all spaces, the name of the disk file is assumed to be the same as file-name-1 (known as the internal-file-name).
The OPTIONAL phrase applies only to files opened in the INPUT, I-O or EXTEND mode. Its specification is required for files that are not necessarily present each time the runtime element is executed.
The SHARING clause specifies the sharing mode to be used for the file unless it is overridden by the SHARING phrase of the OPEN statement. This clause also specifies whether record locks have an effect. Additional details are specified in the topic Sharing Mode in the chapter Language Fundamentals.

General Rules for Formats 1, 3 and 4 (Record Sequential, Relative and Indexed files)

The LOCK MODE clause is an optional clause in the file control entry and is used to specify the locking technique used for the file.
If this clause is omitted, opening the file causes it to become exclusive, with the exception of OPEN INPUT.

When LOCK MODE IS EXCLUSIVE is specified, the run unit acquires a lock on the whole file when it opens the file.

When LOCK MODE IS AUTOMATIC or LOCK MODE IS MANUAL is specified, the file that the run unit opens is shareable. Files opened OUTPUT, and indexed and relative files opened EXTEND are, however, always exclusive.
The ROLLBACK clause requests transaction logging for a file under those COBOL systems that support that feature. See your COBOL system documentation on file handling for details of how it is implemented in your system.
If the ROLLBACK clause is specified then WITH LOCK ON MULTIPLE RECORDS is automatically in effect.
The WITH LOCK ON RECORD clause specifies single record locking for the file.
The WITH LOCK ON MULTIPLE RECORDS clause specifies multiple record locking for the file. This clause must be present if multiple record locking is required.
If LOCK MODE IS AUTOMATIC WITH LOCK ON RECORD is specified for a file, a record lock is acquired by the execution of the READ statement and is released upon execution of a subsequent I/O operation on this file, with the exception of a START statement.
If LOCK MODE IS AUTOMATIC WITH LOCK ON MULTIPLE RECORD is specified for a file, a record lock is acquired by the execution of the READ statement and is not released until a CLOSE, COMMIT, ROLLBACK or UNLOCK statement is executed, or until an individual lock is released by a DELETE statement.
If LOCK MODE IS MANUAL WITH LOCK ON RECORD is specified, a lock is acquired by a READ statement only if it includes the WITH LOCK phrase, and is released upon execution of a subsequent I/O operation on this file, with the exception of a START statement.
If LOCK MODE IS MANUAL WITH LOCK ON MULTIPLE RECORDS is specified, a record lock is acquired by the READ WITH KEPT LOCK statement and is not released until a CLOSE, COMMIT, ROLLBACK or UNLOCK statement is executed.
When the lock mode is MANUAL or AUTOMATIC, single record locking is assumed unless the WITH LOCK ON MULTIPLE RECORDS phrase is included.
If a file is defined as EXTERNAL and the operating system file-name is assigned by means of a file-name, for example, by use of the ASSIGN directive or keyword, using data-name-1 in the SELECT/ ASSIGN statement, or using Format 2 of the VALUE OF phrase of an FD, then the following rules should be followed:
1. An identifier with the same name should be used to contain the physical file-name in all source elements which reference the file.
2. The definition of the identifier which contains the physical file-name should also contain the EXTERNAL attribute.
No violation of these rules is detected at compile time, but, if any runtime element in the run unit violates these rules, the results at run time are undefined.

For further details of the effects of record locking, see your COBOL system documentation on file handling.

General Rules for Format 1 (Record Sequential Files)

The MULTIPLE REEL or MULTIPLE UNIT phrase must be specified if it is possible or intended that the file can be closed by use of the CLOSE REEL or CLOSE UNIT statement.
Records in the file are accessed in the sequence specified by predecessor-successor record relationships which are established by the execution of WRITE statements when the file is created or extended.
Using the LINE ADVANCING FILE phrase causes a file suitable for a printer to be produced. This file has an initial carriage-return character, and each record is written with AFTER ADVANCING 1 LINE as the default advancing phrase. See your COBOL system documentation on file handling for further details of the format.
The PADDING CHARACTER clause is documentary only.
If the associated file connector is an external file connector, all PADDING CHARACTER clauses in a run unit which are associated with that file connector must have the same specification. If data-name-5 is external, it must reference an external data item.
The RECORD DELIMITER clause is documentary only.

General Rules for Format 2 (Line SequentialFiles)

When LINE SEQUENTIAL ORGANIZATION is specified either implicitly or explicitly, the file is treated as consisting of fixed-length records, each containing one line of data. The records are stored with trailing spaces removed. The definition of a line of data varies among different operating systems. Some terminate line records with one or both of the carriage-return and line-feed characters, and some pad out as fixed length records. Your COBOL system, therefore, always produces files which are compatible in this respect with the editor software in any operating system.
The LOCK MODE IS clause is documentary only.

General Rules for Format 3 (Relative Files)

When access mode is sequential, records in the file are accessed in order of ascending relative record numbers of existing records in the file.
When access mode is random, the value of the RELATIVE KEY data item indicates the record to be accessed.
All records stored in a relative file are uniquely identified by relative record numbers, which also specify the record's logical ordinal position in the file. The first logical record has a relative record number of 1, and subsequent logical records have relative record numbers of 2, 3, 4, ... .
The data item specified by data-name-5 is used to communicate a relative record number between the run-time elementand the operating system.

General Rules for Format4 (Indexed Files)

When access mode is sequential, records in the file are accessed in order of ascending record key values within a given key of reference.
When access mode is random, the value of the record key data item indicates the record to be accessed.
The RECORD KEY clause specifies the record key that is the prime record key for the file. The values of the prime record key must be unique among records of the file. This prime record key provides an access path to records in an indexed file.
If the file has more than one record description entry, data-name-5
and any data-names referenced by split-key-name-1
need be describedonly in one of these record description entries. The identical character positionsreferenced by data-name-5
and any data-names referenced by split-key-name-1
in any one record descriptionentry are implicitly referenced as keys for all other record description entriesof that 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 data description entry for data-name-1 with the same relative location in the associated record.
The ALTERNATE RECORD KEY clause specifies a record key that is an alternative record key for the file. This alternate record key provides an alternative access path to records in an indexed file.
The data description of data-name-5
or split-key-name-1

and data-name-8

or split-key-name-2,

as well as of relative locations within a record, must be the same as that used when the file was created. The number of alternate keys for the file must also be the same as that used when the file was created. This checking is configurable in some environments. (Look up the KEYCHECK parameter in your COBOL system documentation.)
The DUPLICATES phrase specifies that the value of the associated record key can be duplicated within any of the records in the file. If the DUPLICATES phrase is not specified, the value of the associated record key must not be duplicated among any of the records in the file.
For duplicate values, the correct duplicate entry must be located using sequential reads from the first duplicate entry.
The SUPPRESS phrase requests the use of a sparse key for an alternate index. Sparse keys are available only through the File Handler and are not available on all systems (see your COBOL system documentation on file handling for details).
Split-key-name-1 defines a record key consisting of the concatenation of data-name-6 and all occurrences of data-name-7 in the order specified. Split-key-name-2 defines a record key consisting of the concatenation of data-name-9 and all occurrences of data-name-10 in the order specified.

General Rules for Format 5 (Sort-MergeFiles)

The file-control entry names a sort or merge file and specifies the association of the file to a storage medium.
When the SORT STATUS clause is specified, a value is placed into the two-character data item specified by data-name-2 after the execution of each sort or merge operation. This value indicates the status at completion of the operation. The following combinations of status keys are possible. Status key 1=0 and status key 2=0 indicates successful completion. Status key 1=3 and status key 2=0 indicates a permanent error. If status key 1=9, status key 2 contains an operating system error message number. For explanations of status keys 1 and 2 and definitions of status, see the topic I-O Status in the chapter Procedure Division. The FILE STATUS clause can be used instead of a SORT STATUS clause, but is treated as a synonym for it, when specified for a sort or merge file.
The ASSIGN clause is documentary only.