HP OpenVMS Systems Documentation

HP COBOL
Reference Manual

Function

The OPEN statement creates an access stream to the file, makes the file available to the program, begins the processing of a file, and specifies file sharing.

file-name

is the name of a file described in the Data Division. It cannot be the name of a sort or merge file.

Leading and trailing blanks are removed from file specifications on all platforms before an OPEN is attempted. Embedded blanks and tabs are removed on OpenVMS systems only.

Syntax Rules

Format 1---Sequential, Line Sequential (Alpha, I64), Relative, or Indexed Files

1. The NO REWIND phrase can be used only for files with sequential organization.
2. The I-O phrase can be used only for mass storage files.
3. The I-O phrase cannot be used with LINE SEQUENTIAL.
4. The EXTEND phrase can be used for sequential access mode files only.
5. The WITH LOCK phrase cannot be used with the ALLOWING phrase, because it is invalid to specify both X/Open standard (WITH [NO] LOCK or LOCK MODE) and Hewlett-Packard standard (LOCK-HOLDING, ALLOWING, or REGARDLESS) file sharing for the same file connector.

Format 2---Report Writer Files

6. file-name must be in a file description entry containing a REPORT clause.

General Rules

All Files

1. Successful OPEN statement execution:
   • Creates an access stream to the file
   • Makes the file available to the program
   • Puts the file in an open mode
   • Associates the file with file-name through the file connector
2. An executable image can open a file-name more than once with the INPUT, OUTPUT, I-O, and EXTEND phrases. After the first OPEN statement, each later OPEN for the same file-name must follow the execution of a CLOSE statement for the file-name. However, the CLOSE statement must not have a REEL, UNIT, or LOCK phrase.
3. The OPEN statement does not get or release the first data record.
4. For an OPEN statement with the INPUT, I-O, or EXTEND phrases, file-name's file description entry must be equivalent to that used when the file was created.
5. The NO REWIND phrase applies only to sequential single-reel/unit files. If the concept of rewinding does not apply to the file's storage medium, then the open is successful and an I-O status is set.
6. If the file's storage medium allows rewinding, and:
   • There is neither an EXTEND nor a NO REWIND phrase, then OPEN statement execution positions the file at its beginning.
   • There is a NO REWIND phrase, then the OPEN statement does not reposition the file. The file must already be positioned at its beginning before the OPEN statement executes.
7. Successful execution of an OPEN statement sets the Current Volume Pointer to:
   • The first or only reel/unit for an available input or input-output file
   • The reel/unit containing the last logical record for an extend file
   • The new reel/unit for an unavailable output, input-output, or extend file
8. If more than one file-name is in the OPEN statement, execution is the same as if there were a separate OPEN statement for each file-name.
9. A file's maximum record size is established when the file is created and must not subsequently be changed.

Format 1---Sequential, Line Sequential (Alpha, I64), Relative, or Indexed Files

10. A file is available if it is both:
    • Physically present
    • Recognized by the I-O system
    
    Table 6-14 shows the result of opening available and unavailable sequential, relative, and indexed files.

    Table 6-14 Opening Available and Unavailable Sequential, Line Sequential (Alpha, I64), Relative, and Indexed Files

    Open Mode	File Is Available	File Is Unavailable
    INPUT	Normal open	Error
    INPUT (Optional File)	Normal open	Normal open The first read causes the at end condition or invalid key condition
    I-O	Normal open	Error
    I-O (Optional File)	Normal open	The OPEN creates the file
    OUTPUT	Creates a new version of the file See General Rule 24	The OPEN creates the file
    EXTEND	Normal open	Error
    EXTEND (Optional File)	Normal open	The OPEN creates the file

11. Successful OPEN statement execution makes the file's record area available to the program. If the file connector is an external file connector, the file has only one record area for the executable image.
12. When a file is not in an open mode, no statement that references the file can execute either implicitly or explicitly, except for:
    • A MERGE statement
    • An OPEN statement
    • A SORT statement with the USING or GIVING phrase
13. An OPEN statement for a file must successfully execute before any allowable input-output statement executes for the file. Table 6-15 shows allowable input-output statements by file organization, access mode, and open mode for sequential, line sequential, relative, and indexed files.

    Table 6-15 Allowable Input-Output Statements for Sequential, Line Sequential (Alpha, I64), Relative, and Indexed Files

    			Open Mode
    File Organization	Access Mode	Statement	INPUT	OUTPUT	I-O	EXTEND
    SEQUENTIAL	SEQUENTIAL	READ REWRITE WRITE UNLOCK	Yes No No Yes	No No Yes Yes	Yes Yes No Yes	No No Yes Yes
    LINE SEQUENTIAL (Alpha, I64)	SEQUENTIAL	READ REWRITE WRITE UNLOCK	Yes No No Yes	No No Yes Yes	No No No No	No No Yes Yes
    RELATIVE	SEQUENTIAL	DELETE READ REWRITE START WRITE UNLOCK	No Yes No Yes No Yes	No No No No Yes Yes	Yes Yes Yes Yes No Yes	No No No No Yes Yes
    	RANDOM	DELETE READ REWRITE WRITE UNLOCK	No Yes No No Yes	No No No Yes Yes	Yes Yes Yes Yes Yes	No No No No No
    	DYNAMIC	DELETE READ READ NEXT REWRITE START WRITE UNLOCK	No Yes Yes No Yes No Yes	No No No No No Yes Yes	Yes Yes Yes Yes Yes Yes Yes	No No No No No No No
    INDEXED	SEQUENTIAL	DELETE READ REWRITE START WRITE UNLOCK	No Yes No Yes No Yes	No No No No Yes Yes	Yes Yes Yes Yes No Yes	No No No No Yes Yes
    	RANDOM	DELETE READ REWRITE WRITE UNLOCK	No Yes No No Yes	No No No Yes Yes	Yes Yes Yes Yes Yes	No No No No No
    	DYNAMIC	DELETE READ READ NEXT READ PRIOR REWRITE START WRITE UNLOCK	No Yes Yes Yes No Yes No Yes	No No No No No No Yes Yes	Yes Yes Yes Yes Yes Yes Yes Yes	No No No No No No No No

14. If the file opened with the INPUT phrase is an optional file that is not present, the OPEN statement sets the File Position Indicator to indicate this condition.
15. An OPEN statement with the EXTEND phrase positions the file immediately after its last logical record. The definition of last logical record differs by file organization:
    • For sequential and line sequential files, it is the last record written in the file.
    • For relative files, it is the currently existing record with the highest relative record number.
    • For indexed files in ascending sort order, it is the currently existing record with the highest prime record key value.
      For indexed files in descending sort order, it is the currently existing record with the lowest prime record key.
    • For Report Writer files, the last logical record is the last record written in the file.
16. Files for which the LINAGE clause has been specified must not be opened in the EXTEND mode.
17. The I-O phrase opens a mass storage file for both input and output operations.
18. The ALLOWING phrase specifies a file-sharing option for the file.
    Automatic record-locking is the system default.
    The ALLOWING phrase, which specifies Hewlett-Packard standard manual record-locking, must be used if the program names this file in the LOCK-HOLDING syntax of the I-O-CONTROL paragraph.
19. When LOCK MODE IS AUTOMATIC or LOCK MODE IS MANUAL is specified and WITH LOCK is not specified, the file is shareable, and can be opened by more than one access stream (except for files opened in OUTPUT mode, which cannot be shared).
20. The NO OTHERS option or WITH LOCK option specifies exclusive file access by this access stream. The access stream created by the OPEN ALLOWING NO OTHERS or OPEN WITH LOCK statement has exclusive access to the file and, therefore, no other concurrent access stream can access (or open) the file.
21. The READERS option permits read-only access to the file for concurrent access streams.
    However, on Tru64 UNIX systems, the ALLOWING READERS phrase is minimally supported for indexed files, and should not be used. Refer to the description of file handling for indexed files in the HP COBOL User Manual, in the section on sharing files. <>
22. The ALL, WRITERS, and UPDATERS phrases allow concurrent access streams access to the file.
23. If there is no ALLOWING phrase or WITH LOCK phrase, the default file-sharing behavior for files depends on the open mode and whether X/Open standard (Alpha or I64) or Hewlett-Packard standard file sharing is in effect.
    For files opened in input mode:
    • Hewlett-Packard standard---The default is ALLOWING READERS (see General Rule 21 for the exception).
    • X/Open standard (Alpha, I64)---The default is to make the file fully shareable.
    
    For files opened in modes other than input mode, the default is always to make the file exclusive. (Also see General Rule 24.)
    The selection of X/Open (Alpha, I64) or Hewlett-Packard standard file-sharing default behavior is made as follows by the compiler:
    • On Alpha and I64, if X/Open standard syntax (LOCK MODE or WITH [NO] LOCK) has been specified for file-name prior to the OPEN statement, the compiler interprets the statement according to the X/Open standard. <>
    • If Hewlett-Packard standard syntax (LOCK-HOLDING, ALLOWING, or REGARDLESS) has been specified for file-name prior to the OPEN statement, the compiler interprets the statement according to the Hewlett-Packard standard.
    • If no file-sharing syntax (LOCK-HOLDING, ALLOWING, REGARDLESS, LOCK MODE, or WITH [NO] LOCK) has been specified for file-name prior to the OPEN statement, then the compiler uses the /STANDARD=[NO]XOPEN qualifier on OpenVMS Alpha and I64 (or the Tru64 UNIX equivalent -std [no]xopen flag) to determine whether the OPEN INPUT statement is interpreted as X/Open or Hewlett-Packard standard: a setting of xopen selects the X/Open standard, whereas a setting of noxopen selects the Hewlett-Packard standard.
    
    Any subsequent I-O locking syntax for the same file connector in your program must be consistent: X/Open standard locking (Alpha, I64) and Hewlett-Packard standard locking (implicit or explicit) cannot be mixed for the same file connector.
24. On Tru64 UNIX systems, files opened in OUTPUT mode adhere to the same file-sharing protocols as do files opened in the EXTEND and I-O modes. Access can be denied or granted depending on the file lock requested and the file lock held. <>
    On OpenVMS systems, file sharing is limited for OUTPUT mode. A higher-numbered version is always created by default. <>
    On Alpha and I64 systems, if X/Open standard file sharing is in effect, files opened in OUTPUT mode cannot be shared. <>
25. On Tru64 UNIX systems, when two file connectors in one process concurrently access the same physical file, a file-locked condition is not generated. <>
    On OpenVMS systems, when two file connectors in one process concurrently access the same physical file, a file-locked condition might be generated. <>
26. For files specified with a MULTIPLE FILE TAPE clause:
    • The NO REWIND phrase, if specified, is ignored.
    • Any required rewinding or positioning of the reel (or device) is accomplished according to the relative position of the file as specified in the MULTIPLE FILE TAPE clause.
27. An OPEN OUTPUT statement for a file specified with a POSITION phrase of a MULTIPLE FILE TAPE clause is invalid unless the tape contains all the files at positions prior to the position specified.
28. An OPEN OUTPUT statement for a file specified with a POSITION phrase of a MULTIPLE FILE TAPE clause is invalid if the tape already contains a file at the position specified.
29. An OPEN INPUT statement for a file specified with a POSITION phrase of a MULTIPLE FILE TAPE clause is invalid unless the tape contains a file at that position, as well as all the files at the positions prior to the position specified.
30. A file specified in a MULTIPLE FILE TAPE clause cannot be opened in either I-O or EXTEND mode.