The OPEN Statement

The OPEN statement initiates the processing of files. It also performs checking and/or writing of labels and other input-output operations.

ANS85The REVERSED phrase of the OPEN statement is classed as an obsolete element in the ANSI'85 standard and is scheduled to be deleted from the next full revision of the ANSI Standard.

MFAll dialects in this COBOL implementation fully support this syntax. The FLAGSTD Compiler directive can be used to detect all occurrences of this syntax.

XOPENAlthough it is a part of the standard COBOL definition, the REVERSED phrase of the OPEN statement is explicitly excluded from the X/Open COBOL language definitions and should not be used in a conforming X/Open COBOL source program.

MFThe OPEN statement allocates system resources for a synchronization data item and initializes the data item.

General Formats
Format 1 (Record Sequential Files)

Format 2 ( MF Line Sequential,
Relative and Indexed Files)

where sharing-phrase is:

MFFormat 3 (Synchronization Data Items)

MF

Syntax Rules
    All Formats (All Files)
  1. The files referenced in the OPEN statement need not all have the same organization or access.
  2. ISO2002MFIf SHARING ALL is specified and the INPUT phrase is not specified, the LOCK MODE clause must be specified in the file control entry for file-name-1.
    3. Format 1 (Record Sequential Files)
  3. MFNO REWIND is documentary only.
  4. The I-O phrase can be used only for disk files.
  5. The EXTEND phrase must be used only for files for which the LINAGE clause has not been specified.
  6. The EXTEND phrase must not be specified with multiple file reels.
  7. The REVERSED phrase can be used only for fixed-length record sequential files.
    8. Format 2 ( MF Line Sequential,
    Relative and Indexed Files)
  8. ANS85The EXTEND phrase can be used for files in sequential access mode.
  9. ISO2002MFThe SHARING phrase must not be specified for files with line sequential organization.
    10. MFFormat 3 (Synchronization Data Items)
  10. MFIdentifier-1 must reference an elementary data item with a USAGE of EVENT-POINTER, MONITOR-POINTER, MUTEX-POINTER or SEMAPHORE-POINTER.
General Rules
    Formats 1 and 2 (All Files)
  1. Prior to the successful execution of an OPEN statement for a given file, no statement (except for a SORT or MERGE statement with the USING or GIVING phrases) can be executed that references that file, either explicitly or implicitly.
  2. ISO2002MFThe successful execution of an OPEN statement determines the availability of the file and results in the file connector referenced by the file-name being in an open mode. The successful execution of an OPEN statement associates the file with the file-name through a file connector.

    The key words INPUT, OUTPUT, I-O, and EXTEND specify the type of input-output operations intended for the file through the file connector and establish the open mode. (See table 14-4, Permissible Combinations of Statements and OPEN Modes.)

    A file is available if it is physically present and is recognized by the file handling system. Table 1, Opening Available and Unavailable Files (file not currently open), shows the results of opening available and unavailable files that are not currently open. Table 2, Opening Available Shared Files that are Currently Open by Another File Connector, shows the results of opening available and unavailable files that are currently open by another file connector.

    Open Mode File is Available File is Unavailable
    INPUT Normal open Open is unsuccessful
    INPUT (optional file) Normal open Normal open; the first read causes the at end condition or invalid key condition
    I-O Normal open Open is unsuccessful
    I-O (optional file) Normal open Open causes the file to be created
    OUTPUT Normal open; the file contains no records Open causes the file to be created
    EXTEND Normal open Open is unsuccessful
    EXTEND (optional file) Normal open Open causes the file to be created
    Table 1: Opening Available and Unavailable Files (File not Currently Open)

    Open request Most Restrictive Existing Sharing Mode and Open Mode
    Sharing with no Other Sharing with Read Only Sharing with All Other
    extend/ I-O/ input/ output extend/ I-O/ output input extend/ I-O/ output input
    SHARING WITH NO OTHER EXTEND/ I-O/ INPUT/ OUTPUT/ Unsuccessful open Unsuccessful open Unsuccessful open Unsuccessful open Unsuccessful open
    SHARING WITH READ ONLY EXTEND/ I-O Unsuccessful open Unsuccessful open Unsuccessful open Unsuccessful open Normal open
    INPUT Unsuccessful open Unsuccessful open Normal open Unsuccessful open Normal open
    OUTPUT Unsuccessful open Unsuccessful open Unsuccessful open Unsuccessful open Unsuccessful open
    SHARING WITH ALL OTHER EXTEND/ I-O Unsuccessful open Unsuccessful open Unsuccessful open Normal open Normal open
    INPUT Unsuccessful open Normal open Normal open Normal open Normal open
    OUTPUT Unsuccessful open Unsuccessful open Unsuccessful open Unsuccessful open Unsuccessful open
    Table 2: Opening Available Shared Files that are Currently Open by Another File Connector
  3. The successful execution of an OPEN statement makes the associated record area available .
  4. In Table 3, "X" at an intersection indicates that the specified statement, used in the access mode given for that row, can be used with the open mode given at the top of the column.
    File Access Mode OPEN Mode
    Statement Input Output Input-Output Extend
    Sequential READ X   X  
    WRITE   X   X
    REWRITE     X  
    Random (Non-Sequential Files) READ X   X  
    WRITE   X X  
    REWRITE     X  
    START        
    DELETE     X  
    Dynamic (Non-Sequential Files) READ X   X  
    WRITE   X X  
    REWRITE     X  
    START X   X  
    DELETE     X  
    Table 3: Permissible Combinations of Statements and OPEN Modes

    5. Note: The START and DELETE statements cannot be used with record

    MFor line

    sequential files.

  5. MFIf the WITH LOCK phrase is specified, the OPEN statement acquires a lock on the whole file. (This is equivalent to specifying LOCK MODE IS EXCLUSIVE in the SELECT statement for the file. See the topic The File Control Entry in the chapter Environment Division.)
  6. ANS85 If, during the execution of an OPEN statement, a file attribute conflict occurs, the execution of the OPEN statement is unsuccessful. Your COBOL system defines which of the fixed file attributes are validated during the execution of the OPEN statement. See your file handling documentation for more details. The validation of fixed file attributes can vary depending on the organization and/or storage medium of the file.
  7. ANS85A file can be opened with the INPUT, OUTPUT, EXTEND and I-O phrases in the same run unit. Following the initial execution of an OPEN statement for a file connector, each subsequent OPEN statement execution for that same file connector must be preceded by the execution of a CLOSE statement for that file connector, even if the file is optional.
  8. Execution of the OPEN statement does not obtain or release the first data record.
  9. The external name of the file specified in the SELECT clause for a file is processed as follows:
    1. When the INPUT phrase is specified, execution of the OPEN statement causes the name to be checked in accordance with the operating system conventions for opening files for input.
    2. When the OUTPUT phrase is specified, execution of the OPEN statement causes the name to be checked in accordance with the operating system conventions for opening files for output.
  10. The file description entry for file-name-1, file-name-2, file-name-3, and file-name-4 must be equivalent to that used when this file was created.
  11. For files being opened with the INPUT or I-O phrase, the OPEN statement sets the file position indicator to the first record currently existing in the file for indexed and sequential files, and record position one for relative files. If no records exist in the file, the file position indicator is set such that the next executed READ statement for an indexed or sequential file will result in an AT END condition. If the file does not exist, OPEN INPUT causes an error status, unless the file is optional.
  12. When the I-O phrase is specified and the LABEL RECORDS clause indicates label records are present, the execution of the OPEN statement includes the following steps:
    1. The labels are checked in accordance with the operating system-specified conventions for input-output label checking.
    2. The new labels are written in accordance with the operating system-specified conventions for input-output label writing.
  13. Upon successful execution of an OPEN statement with the OUTPUT phrase specified, a file is created. At that time the associated file contains no data records. If a file of the same name exists it is deleted. If the file is write-protected an error occurs.
  14. ANS85When the EXTEND phrase is specified, the OPEN statement positions the file immediately after the last logical record for that file. The last logical record for a sequential file is the last record written in the file. In a relative file it is the currently existing record with the highest relative record number, and in an indexed file it is the currently existing record with the highest prime key value.
  15. Execution of the OPEN statement causes the value of the FILE STATUS data item to be updated (see the topic I-O Status in the chapter Procedure Division).
  16. MFWhen LOCK MODE IS EXCLUSIVE is specified in the SELECT/ ASSIGN statement of a file, successful execution of an OPEN statement of that file locks the file exclusively to that run unit.
  17. MFWhen LOCK MODE IS AUTOMATIC or LOCK MODE IS MANUAL is specified in the SELECT/ASSIGN statement of a file, the file that is referred to is shareable. More than one run unit can successfully open such a file.
  18. MF A file opened for OUTPUT, and relative and indexed files opened EXTEND, are implicitly defined as files with an exclusive lock, that is, they are not shareable.
  19. MFOnly shareable files opened for I-O can acquire record locks.
  20. If execution of the OPEN statement is unsuccessful, the physical file is not affected and the following actions take place in this order:
    1. A value is placed in the I-O status associated with file-name to indicate the condition that caused the OPEN statement to be unsuccessful.
    2. Any applicable USE AFTER EXCEPTION procedure is executed. (See the topic The USE Statement.)
  21. The I-O phrase permits the opening of a file for both input and output operations. If the file does not exist, the following rules apply:
    1. If the OPTIONAL phrase is specified in the SELECT clause for the file, the file is created
    2. If the NOT OPTIONAL phrase is specified in the SELECT clause for the file, an error occurs
    3. If neither phrase is specified, and the directive OPTIONAL-FILE was specified when the source element was compiled, the file is created.
    4. If neither phrase is specified, and the directive NOOPTIONAL-FILE was specified when the source element was compiled, an error occurs.
  22. If an input file is designated with the OPTIONAL phrase in its SELECT clause, when the file is opened there is an interrogation for the presence or absence of this file. If the file is not present, the first READ statement for this file causes the AT END condition to occur.
  23. When the EXTEND phrase is specified, the OPEN statement positions the file immediately following the last logical record of that file. Subsequent WRITE statements referencing the file will add records to the file as though the file had been opened with the OUTPUT phrase. If the file does not exist it is created.
  24. ANS85When the EXTEND phrase is specified and the LABEL RECORDS clause in this file's FD indicates label records are present, the execution of the OPEN statement includes the following steps:
    1. The beginning file labels are processed only in the case of a single reel/unit file.
    2. The beginning reel/unit labels on the last existing reel/unit are processed as though the file was being opened with the INPUT phrase.
    3. The existing ending file labels are processed as though the file is being opened with the INPUT phrase. These labels are then deleted.
    4. Processing then proceeds as though the file had been opened with the OUTPUT phrase.
  25. The I-O phrase permits the opening of a file for both input and output operations,

    MFexcept files with ORGANIZATION LINE SEQUENTIAL.

    If the file does not exist, it is created and used as an empty file for input

    MFunless NOT OPTIONAL was specified in the SELECT statement.

    An attempt to READ from the newly created file causes an error.

  26. ISO2002MFThe SHARING phrase can be specified only for shared files. (See the topic Sharing Mode in the chapter Language Fundamentals.)
  27. ISO2002MFThe SHARING phrase specifies what operations may be performed on the file through other file connectors sharing the file. (See the topic Sharing Mode in the chapter Language Fundamentals.)
  28. ISO2002MFThe SHARING phrase overrides any SHARING clause in the file control entry of the file connector associated with the file-name. If there is no SHARING phrase on the OPEN statement, then file sharing is completely specified in the file control entry. If neither a SHARING phrase on the OPEN statement nor a SHARING clause in the file control entry is specified, the sharing mode is established for the file connector in accordance with the rules specified in the topic Sharing Mode in the chapter Language Fundamentals.
    29. Format 1 (Record Sequential Files)
  29. If the storage medium for the file permits rewinding, the following rules apply:
    1. Execution of the OPEN statement causes the file to be positioned at its beginning.
    2. When the REVERSED phrase is specified, the file is positioned at its end by execution of the OPEN statement.
  30. When the REVERSED phrase is specified, the subsequent READ statements for the file make the data available in reversed order; that is, starting with the last record.
    31. MF Format 2 ( Line Sequential Files)
  31. MF I-O mode is not allowed for line sequential files unless the REWRITE-LS Compiler directive is set.
    32. MFFormat 3 (Synchronization Data Items)
  32. MFPrior to the successful execution of an OPEN statement for a given synchronization data item, no statement can be executed that references that data item.
  33. MFThe successful execution of an OPEN statement determines the availability of the synchronization data item.
  34. MFExecution of the OPEN statement causes the RETURN-CODE special register to be updated with one of the values specified for the synchronization item library routines.
  35. MFFollowing the initial execution of an OPEN statement for a synchronization data item, each subsequent OPEN statement execution for that same data item must be preceded by the execution of a CLOSE statement for that data item.
  36. MFIf identifier-1 references an event data item, the execution of the OPEN statement initializes the data item to FALSE.
  37. MFIf identifier-1 references a monitor data item, the execution of the OPEN statement initializes the monitor to NOT BROWSING, NOT READING, and NOT WRITING.
  38. MFIf identifier-1 references a mutex data item, the execution of the OPEN statement initializes the data item to OFF.
  39. MFIf identifier-1 references a semaphore data item, the execution of the OPEN statement initializes the data item to zero.