HP OpenVMS Systems Documentation

HP Fortran for OpenVMS
User Manual

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 HP 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 Section 6.6.3)
  • 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.7).
• 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)

An inquiry by name causes the HP 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 Section 6.6.3).
  • 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.7).
• 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_OPEN, 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)

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 an HP 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 HP Fortran for OpenVMS Language Reference Manual.
• On record I/O, see Section 6.9.
• On OPEN statement specifiers, see Section 6.6.3.
• On the /ASSUME=BYTERECL qualifier, see Section 2.3.7.

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 HP Fortran I/O statements, see Table 6-1.
• On changing default I/O characteristics before using HP Fortran I/O statements, see Chapter 11.
• On OPEN statement specifiers, see Section 6.6.3.
• On statement syntax and specifier values (such as other STATUS values), see the HP Fortran for OpenVMS 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 HP extensions.

These statements are described in Section 6.3 and the HP Fortran for OpenVMS 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.4.

6.9.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.9.5.

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

For More Information

• On specifier syntax and complete information, see the HP Fortran for OpenVMS Language Reference Manual.
• On available record types, see Section 6.5.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.9.5.
• On record positioning, see Section 6.9.4.
• On record I/O transfer, see Section 6.9.6.
• On record advancement, see Section 6.9.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.

HP 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-5 shows all of the valid combinations of access mode and file organization.

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

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.9.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 HP Fortran programs, this information is supplied by the ACTION specifier (or HP 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, HP 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 HP 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

• On the UNLOCK statement and its syntax, see the HP Fortran for OpenVMS Language Reference Manual.
• On record locking for shared files, see the Guide to OpenVMS File Applications.
• On how to handle record locking for indexed files, see Section 12.8.
• On specifier syntax and complete information, see the HP Fortran for OpenVMS Language Reference Manual.
• On file sharing and record locking, see the Guide to OpenVMS File Applications.

When you open a disk file, you can use the OPEN statement's POSITION specifier to request one of the following initial record positions within the file:

• The initial position before the first record (POSITION= ' REWIND ' ). A sequential access READ or WRITE statement will read or write the first record in the file.
• A point beyond the last record in the file (POSITION= ' APPEND ' ), just before the end-of-file record, if one exists. For a new file, this is the initial position before the first record (same as ' REWIND ' ). You might specify ' APPEND ' before you write records to an existing sequential file using sequential access.
• The current position (ASIS). This is usually used only to maintain the current record position when reconnecting a file. The second OPEN specifies the same unit number and specifies the same file name (or omits it), which leaves the file open, retaining the current record position.
  However, if a second OPEN statement specifies a different file name for the same unit number, the file will be closed and then opened, causing a loss of current record position.

The following I/O statements allow you to change the current record position:

• REWIND sets the record position to the initial position before the first record. A sequential access READ or WRITE statement would read or write the first record in the file.
• BACKSPACE sets the record position to the previous record in a file. Using sequential access, if you wrote record 5, issued a BACKSPACE to that unit, and then read from that unit, you would read record 5.
• ENDFILE writes an end-of-file marker. This is typically done after writing records using sequential access just before you close the file.

Unless you use nonadvancing I/O (see Section 6.9.5), reading and writing records usually advances the current record position by one record. As discussed in Section 6.9.6, more than one record might be transferred using a single record I/O statement.