The OPEN statement connects a unit number with an external file and allows you to explicitly specify file attributes and run-time options using OPEN statement specifiers. Once you open a file, you should close it before opening it again unless it is a preconnected file.

If you open a unit number that was opened previously (without being closed), one of the following occurs:

• If you specify a file specification that does not match the one specified for the original open, the Compaq Fortran run-time system closes the original file and then reopens the specified file.
  This resets the current record position for the second file.
• If you specify a file specification that does match the one specified for the original open, the file is reconnected without the internal equivalent of the CLOSE and OPEN.
  This lets you change one or more OPEN statement run-time specifiers while maintaining the record position context.

You can use the INQUIRE statement (see Section 6.6) to obtain information about a whether or not a file is opened by your program.

Especially when creating a new file using the OPEN statement, examine the defaults (see the description of the OPEN statement in the Compaq Fortran Language Reference Manual) or explicitly specify file attributes with the appropriate OPEN statement specifiers.

Table 6-5 lists the OPEN statement functions and their specifiers.

Table 6-5 OPEN Statement Functions and Specifiers

Category, Functions, and OPEN Statement Specifiers
Identify File and Unit
	UNIT specifies the logical unit number.
	FILE (or NAME 1) and DEFAULTFILE 1 specify the directory and/or file name of an external file.
	STATUS or TYPE 1 indicates whether to create a new file, overwrite an existing file, open an existing file, or use a scratch file.
	STATUS or DISPOSE 1 specifies the file existence status after CLOSE.
File and Record Characteristics
	ORGANIZATION 1 indicates the file organization (sequential, relative, or indexed).
	RECORDTYPE 1 indicates which record type to use.
	FORM indicates whether records are formatted or unformatted. See Section 6.4.4 and Section 6.3.
	CARRIAGECONTROL 1 indicates the terminal control type.
	KEY 1 indicates (when creating an indexed file) the key number, its type, and its location.
	NOSPANBLOCKS 1 indicates that the records should not span block boundaries.
	RECL or RECORDSIZE 1 specifies the record size. See Section 6.4.4.
Special File Open Routine
	USEROPEN 1 names the routine that will open the file to establish special context that changes the effect of subsequent Compaq Fortran I/O statements (see Chapter 11).
File Access, Processing, and Position
	ACCESS indicates the access mode (direct, keyed, or sequential). See Section 6.8.2.
	ACTION or READONLY 1 indicates whether statements will be used to only read records, only write records, or read and write records. See Section 6.8.3.
	POSITION indicates whether to position the file at the beginning of file, before the end-of-file record, or leave it as is (unchanged). See Section 6.8.4.
	SHARED 1 indicates that other users can access the same file and activates record locking. See Section 6.8.3.
	MAXREC 1 specifies the maximum record number for direct access.
	ASSOCIATEVARIABLE 1 specifies the variable containing next record number for direct access.
File Allocation
	INITIALSIZE 1 indicates the allocation unit (in blocks) when creating a file.
	EXTENDSIZE 1 indicates the allocation unit (in blocks) when allocation additional file space.
Record Transfer Characteristics
	BLANK indicates whether to ignore blanks in numeric fields.
	DELIM specifies the delimiter character for character constants in list-directed or namelist output.
	PAD, when reading formatted records, indicates whether padding characters should be added if the item list and format specification require more data than the record contains.
	BLOCKSIZE 1 specifies the block physical I/O buffer size.
	BUFFERCOUNT 1 specifies the number of physical I/O buffers.
	CONVERT 1 specifies the format of unformatted numeric data. See Chapter 9.
Error Handling Capabilities
	ERR specifies a label to branch to if an error occurs. See Chapter 7.
	IOSTAT specifies the integer variable to receive the error (IOSTAT) number if an error occurs. See Chapter 7.
File Close Action
	DISPOSE 1 identifies the action to take when the file is closed.

For More Information:

• On specifier syntax and complete information, see the Compaq Fortran Language Reference Manual.
• On the FORM specifier, see Section 6.3.
• On file organizations, see Section 6.4.1.
• On available record types, see Section 6.4.3.
• On the CARRIAGECONTROL specifier, see Section 6.4.4.
• On the RECL (record length) specifier, see Section 6.4.4.
• On shared access to files, see Section 6.8.3.
• On the ERR and IOSTAT specifiers, see Chapter 7.
• On obtaining file information using the INQUIRE statement, see Section 6.6.
• On closing files, see Section 6.7.
• Record I/O transfer, see Section 6.8.6.
• Record advancement, see Section 6.8.5.
• Record positioning, see Section 6.8.4.
• On I/O performance considerations, see Section 5.5.

The INQUIRE statement returns information about a file and has three forms:

• Inquiry by unit
• Inquiry by file name
• Inquiry by output item list

An inquiry by unit is usually done for an opened (connected) file. An inquiry by unit causes the Compaq Fortran RTL to check whether the specified unit is connected or not. One of the following occurs:

• If the unit is connected:
  • The EXIST and OPENED specifier variables indicate a true value
  • The file specification is returned in the NAME specifier variable (if the file is named)
  • Other information requested on the previously connected file is returned
  • Default values are usually returned for the INQUIRE specifiers also associated with the OPEN statement (see Table 6-5)
  • The RECL value unit for connected formatted files is always 1-byte units. For unformatted files, the RECL unit is 4-byte units, unless you specify the /ASSUME=BYTERECL qualifier to request 1-byte units (see Section 2.3.6
• If the unit is not connected:
  • The OPENED specifier indicates a false value
  • The unit NUMBER specifier variable is returned as a value of --1
  • Any other information returned will be undefined or default values for the various specifiers

For example, the following INQUIRE statement shows whether unit 3 has a file connected (OPENED specifier) in logical variable I_OPENED, the name (case sensitive) in character variable I_NAME, and whether the file is opened for READ, WRITE, or READWRITE access in character variable I_ACTION:

INQUIRE (3, OPENED=I_OPENED, NAME=I_NAME, ACTION=I_ACTION)

6.6.2 Inquiry by File Name

An inquiry by name causes the Compaq Fortran RTL to scan its list of open files for a matching file name. One of the following occurs:

• If a match occurs:
  • The EXIST and OPENED specifier variables indicate a true value.
  • The full file specification is returned in the NAME specifier variable.
  • The UNIT number is returned in the NUMBER specifier variable.
  • Other information requested on the previously connected file is returned.
  • Default values are usually returned for the INQUIRE specifiers also associated with the OPEN statement (see Table 6-5).
  • The RECL value unit for connected formatted files is always 1-byte units. For unformatted files, the RECL unit is 4-byte units, unless you specify the /ASSUME=BYTERECL qualifier to request 1-byte units (see Section 2.3.6.
• If no match occurs:
  • The OPENED specifier variable indicates a false value.
  • The unit NUMBER specifier variable is returned as a value of --1.
  • The EXIST specifier variable indicates (true or false) whether the named file exists on the device or not.
  • If the file does exist, the NAME specifier variable contains the full file specification.
  • Any other information returned will be file characteristics maintained in the file header or default values for the various specifiers, based on any information specified when calling INQUIRE.

The following INQUIRE statement returns whether the file named LOG_FILE is a file connected in logical variable I_OPENED, whether the file exists in logical variable I_EXIST, and the unit number in integer variable I_NUMBER.

INQUIRE (FILE='log_file', OPENED=I_OPEN, EXIST=I_EXIST, NUMBER=I_NUMBER)

6.6.3 Inquiry by Output Item List

Unlike inquiry by unit or inquiry by name, inquiry by output item list does not attempt to access any external file. It returns the length of a record for a list of variables that would be used for unformatted WRITE, READ, and REWRITE statements (REWRITE is a Compaq Fortran extension).

The following INQUIRE statement returns the maximum record length of the variable list in integer variable I_RECLENGTH. This variable is then used to specify the RECL value in the OPEN statement:

INQUIRE (IOLENGTH=I_RECLENGTH) A, B, H OPEN (FILE='test.dat', FORM='UNFORMATTED', RECL=I_RECLENGTH, UNIT=9)

For an unformatted file, the RECL value is returned using 4-byte units, unless you specify the /ASSUME=BYTERECL qualifier to request 1-byte units.

For More Information:

• On the INQUIRE statement and its specifiers, see the Compaq Fortran Language Reference Manual.
• On record I/O, see Section 6.8.
• On OPEN statement specifiers, see Table 6-5.
• On the /ASSUME=BYTERECL qualifier, see Section 2.3.6.

Usually, any external file opened should be closed by the same program before it completes. The CLOSE statement disconnects the unit and its external file. You must specify the unit number (UNIT specifier) to be closed.

You can also specify:

• Whether the file should be deleted or kept (STATUS specifier)
• Error handling information (ERR and IOSTAT specifiers)

To delete a file when closing it:

• In the OPEN statement, specify the ACTION keyword (such as ACTION='READ'). Avoid using the READONLY keyword, because a file opened using the READONLY keyword cannot be deleted when it is closed.
• In the CLOSE statement, specify the keyword STATUS='DELETE'. (Other STATUS keyword values include 'SUBMIT' and 'PRINT'.)

If you opened an external file and did an inquire by unit, but do not like the default value for the ACCESS specifier, you can close the file and then reopen it, explicitly specifying the ACCESS desired.

There usually is no need to close preconnected units. Internal files are neither opened nor closed.

For More Information:

• On a list of Compaq Fortran I/O statements, see Table 6-1.
• On changing default I/O characteristics before using Compaq Fortran I/O statements, see Chapter 11.
• On OPEN statement specifiers, see Section 6.5.3.
• On statement syntax and specifier values (such as other STATUS values), see the Compaq Fortran Language Reference Manual.

After you open a file or use a preconnected file, you can use the following statements:

• READ, WRITE and PRINT to perform record I/O.
• BACKSPACE, ENDFILE, REWIND to set record position within the file.
• ACCEPT, DELETE, REWRITE, TYPE, DEFINE FILE, and FIND to perform various operations. These statements are Compaq extensions.

These statements are described in Section 6.2 and the Compaq Fortran Language Reference Manual.

The record I/O statement must use the appropriate record I/O form (formatted, list-directed, namelist, or unformatted), as described in Section 6.3.

6.8.1 Record I/O Statement Specifiers

You can use the following specifiers with the READ and WRITE record I/O statements:

• UNIT specifies the unit number to or from which input or output will occur.
• END specifies a label to branch to if an error occurs; only applies to input statements like READ.
• ERR specifies a label to branch to if an error occurs.
• IOSTAT specifies an integer variable to contain the IOSTAT number if an error occurs.
• FMT specifies a label of a FORMAT statement.
• NML specifies the name of a NAMELIST group.
• For direct access, REC specifies a record number.
• For keyed access:
  • KEYID specifies the key of reference.
  • KEY, KEYNXT, KEYNXTNE, KEYLT, KEYEQ, KEYLE, and KEYGT specify the key value and key match characteristics.

When using nonadvancing I/O, use the ADVANCE, EOR, and SIZE specifiers, as described in Section 6.8.5.

When using the REWRITE statement (a Compaq Fortran extension), you can use the UNIT, FMT, ERR, and IOSTAT specifiers.

For More Information

• On specifier syntax and complete information, see the Compaq Fortran Language Reference Manual.
• On available record types, see Section 6.4.3.
• On the error-related record I/O specifiers ERR, END, and IOSTAT, see Chapter 7.
• On the ADVANCE, EOR, and SIZE specifiers, see Section 6.8.5.
• On record positioning, see Section 6.8.4.
• On record I/O transfer, see Section 6.8.6.
• On record advancement, see Section 6.8.5.

Record access refers to how records will be read from or written to a file, regardless of its organization. Record access is specified each time you open a file; it can be different each time.

The type of record access permitted is determined by the combination of file organization and record type. Access mode is the method a program uses to retrieve and store records in a file. The access mode is specified as part of each I/O statement.

Compaq Fortran supports three record access modes:

• Sequential access---transfers records sequentially to or from files (sequential, relative, or indexed) or I/O devices such as terminals.
• Direct access---transfers records selected by record number to and from fixed-length sequential files or relative organization files.
• Keyed access---transfers records to and from indexed files, based on data values (keys) contained in the records, using the current key-of-reference.

Your choice of record access mode is affected by the organization of the file to be accessed. For example, the keyed access mode can be used only with indexed organization files.

Table 6-6 shows all of the valid combinations of access mode and file organization.

Table 6-6 Valid Combinations of Record Access Mode and File Organization

File Organization	Record Access Mode
	Sequential	Direct	Keyed
Sequential	Yes	Yes 1	No
Relative	Yes	Yes	No
Indexed	Yes	No	Yes

If you select the sequential access mode for sequential or relative files, records are written to or read from the file starting at the beginning and continuing through the file, one record after another. For indexed files, sequential access can be used to read or write all records according to the direction of the key and the key values. Sequential access to indexed files can also be used with keyed access to read or write a group of records at a specified point in the file.

When you use sequential access for sequential and relative files, a particular record can be retrieved only after all of the records preceding it have been read.

Writing records by means of sequential access also varies according to the file organization:

• For sequential files, new records can be written only at the end of the file.
• For relative files, a new record can be written at any point, replacing the existing record in the specified cell. For example, if two records are read from a relative file and then a record is written, the new record occupies cell 3 of the file.
• For indexed files, records must be written in primary key order, and READ operations refer to the next record meeting the key selection criteria.

If you select direct access mode, you determine the order in which records are read or written. Each READ or WRITE statement must include the relative record number, indicating the record to be read or written.

You can access relative files directly. You can also access a sequential disk file directly if it contains fixed-length records. Because direct access uses cell numbers to find records, you can issue successive READ or WRITE statements requesting records that either precede or follow previously requested records. The following statements read record 24, then read record 10.

READ (12,REC=24) I READ (12,REC=10) J

6.8.2.3 Keyed Access

If you select keyed access mode, you determine the order in which records are read or written by means of character values or integer values called keys. Each READ statement contains the key that locates the record. The key value in the I/O statement is compared with index entries until the record is located.

When you insert a new record, the values contained in the key fields of the record determine the record's placement in the file; you do not have to indicate a key.

You can use keyed access only for indexed files.

Your program can mix keyed access and sequential access I/O statements on the same file. You can use keyed I/O statements to position the file to a particular record, then use sequential I/O statements to access records with either increasing or decreasing key values (depending on the key chosen).

For More Information

On using indexed files, see Chapter 12.

6.8.3 Shared File Use

There are two kinds of file sharing:

• Read sharing occurs when multiple programs are reading a file at the same time.
• Write sharing takes place when at least one program is writing a file and at least one other program is either reading or writing the same file.

All three file organizations---relative, indexed, and sequential---permit read and write access to shared files.

The extent to which file sharing can take place is determined by two factors: the type of device on which the file resides and the explicit information supplied by the user. These factors have the following effects:

• Device type---Sharing is possible only on disk files.
• Explicit file-sharing information supplied by accessing programs---Whether file sharing actually takes place depends on information provided to OpenVMS RMS by each program accessing the file. In Compaq Fortran programs, this information is supplied by the ACTION specifier (or Compaq extension READONLY specifier) and the SHARED specifier in the OPEN statement.
  Read sharing is accomplished when the OPEN statement specifies the ACTION='READ' (or READONLY) specifier by all programs accessing the file.
  Write sharing is accomplished when the program specifies SHARED with either ACTION='WRITE' or ACTION='READWRITE' (the default is ACTION='READWRITE' unless you specify ACTION='READ' or 'READONLY').
  Programs that specify ACTION='READ' (or 'READONLY') or 'SHARED' can access a file simultaneously, with the exception that a file opened for ACTION='READ' (READONLY) cannot be accessed by a program that specifies SHARED.

Depending on the value specified by the ACTION (or READONLY) specifier in the OPEN statement, the file will be opened by your program for reading, writing, or both reading and writing records. This simply checks that the program itself executes the type of statements intended, unless the OPEN statement specifies the SHARED specifier.

To allow other users to access the same file once you have opened it, specify the OPEN statement SHARED specifier when you open the file. If you specify the SHARED specifier when opening a file that is already opened by another process, your program will be allowed to access the file.

If you omit the SHARED specifier when opening a file that is already opened by another process, your program will be denied access to the file. If you omit the SHARED specifier and are the first to open that files, file access might be denied to other users later requesting access to the file.

For performance reasons, when writing records to the file, avoid specifying the SHARED qualifier when you are certain that no other processes will access that file. Similarly, unless you will be writing records when specifying the SHARED qualifier, specify ACTION='READ'.

When two or more programs are write sharing a file, each program should use one of the error-processing mechanisms described in Chapter 14.

Use of one of these controls, the RMS record-locking facility, prevents program failure due to a record-locking error.

The RMS record-locking facility, along with the logic of the program, prevents two processes from accessing the same record at the same time. Record locking ensures that a program can add, delete, or update a record without having to check whether the same record is simultaneously being accessed by another process.

When a program opens a relative, sequential, or indexed file specifying SHARED, RMS locks each record as it is accessed. When a record is locked, any program attempting to access it fails with a record-locked error. A subsequent I/O operation on the logical unit unlocks the previously accessed record, so no more than one record on a logical unit is ever locked.

In the case of a WRITE to a sequential or relative organization file opened for shared access, Compaq Fortran uses an RMS option that causes the record to be updated if it already exists in the file. This option has the side-effect of momentarily releasing the record lock, if any, and then relocking the target record. There is a small possibility that if another program is trying to access the same record at the same time, it may succeed in locking the record while it is unlocked by the first program, resulting in a record-locked error for the WRITE statement.

Locked records can be explicitly unlocked by means of Compaq Fortran's UNLOCK statement. The use of this statement minimizes the amount of time that a record is locked against access by other programs. The UNLOCK statement should be used in programs that retrieve records from a shared file but do not attempt to update them.

For More Information

• About the UNLOCK statement and its syntax, see the Compaq Fortran Language Reference Manual.
• About record locking for shared files, see the Guide to OpenVMS File Applications.
• On how to handle record locking for indexed files, see the section on condition handling in Chapter 12.
• On specifier syntax and complete information, see the Compaq Fortran Language Reference Manual.
• On file sharing and record locking, see the Guide to OpenVMS File Applications.