Inquiring About Files

Fortran Language Reference Manual, Volume 2 - S-3693-50
Prev Section	Chapter 1. Input and Output (I/O) Processing	Next Section

1.7. Inquiring About Files

An inquiry can be made about a file's existence, connection, access method, or other properties. For each property inquired about, a scalar variable of default kind must be supplied; that variable is given a value that answers the inquiry. The variable can be tested and optional execution paths can be selected based on the answer returned. The inquiry specifiers are determined by keywords in the INQUIRE statement. The only exception is the unit specifier, which, if no keyword is specified, must be the first specifier. A file inquiry can be made by unit number, file name, or an output item list. When inquiring by an output item list, an output item list that might be used in an unformatted direct access output statement must be present.

1.7.1. `INQUIRE` Statement

There are three kinds of INQUIRE statements: inquiry by unit, by name, and by an output item list. The first two kinds use the inquire_spec_list form of the INQUIRE statement. The third kind uses the IOLENGTH form. Inquiry by unit uses a unit specifier. Inquiry by file uses a file specifier with the keyword FILE=. These statements are defined as follows:

Table 1-13.

inquire_stmt

INQUIRE (inquire_spec_list)

INQUIRE (IOLENGTH = scalar_default_int_variable) output_item_list

inquire_spec

[UNIT = ] external_file_unit

FILE = file_name_expr

IOSTAT = scalar_default_int_variable

ERR = label

EXIST = scalar_default_logical_variable

OPENED = scalar_default_logical_variable

NUMBER = scalar_default_int_variable

NAMED = scalar_default_logical_variable

NAME = scalar_char_variable

SEQUENTIAL = scalar_char_variable

ACCESS = scalar_char_variable

DIRECT = scalar_char_variable

FORM = scalar_char_variable

FORMATTED = scalar_char_variable

UNFORMATTED = scalar_char_variable

RECL = scalar_default_int_variable

NEXTREC = scalar_default_int_variable

BLANK = scalar_char_variable

POSITION = scalar_char_variable

ACTION = scalar_char_variable

READ = scalar_char_variable

WRITE = scalar_char_variable

READWRITE = scalar_char_variable

DELIM = scalar_char_variable

PAD = scalar_char_variable

An INQUIRE statement with an inquire_spec_list must have a unit specifier or a FILE= specifier, but not both. If the keyword UNIT is omitted, a scalar integer expression must be the first item in the list and must have a nonnegative value.

No specifier can appear more than once in a given inquiry specifier list.

For an inquiry by an output item list, the output item list must be a valid output list for an unformatted, direct-access, output statement. The length value returned in the scalar default integer variable must be a value that is acceptable when used as the value of the RECL= specifier in an OPEN statement. This value can be used in a RECL= specifier to connect a file whose records will hold the data indicated by the output list of the INQUIRE statement.

An INQUIRE statement can be executed before or after a file is connected to a unit. The specifier values returned by the INQUIRE statement are those current at the time at which the INQUIRE statement is executed.

A variable appearing in a specifier or any entity associated with it must not appear in another specifier in the same INQUIRE statement if that variable can become defined or undefined as a result of executing the INQUIRE statement. That is, do not try to assign two inquiry results to the same variable.

Except for the NAME= specifier, character values are returned in uppercase.

If an error condition occurs during the execution of an INQUIRE statement, all the inquiry specifier variables become undefined except the IOSTAT= specifier. The following are examples of INQUIRE statements:

INQUIRE (9, EXIST = EX) INQUIRE (FILE = "T123", OPENED = OP, ACCESS = AC) INQUIRE (IOLENGTH = IOLEN) X, Y, CAT

1.7.2. Specifiers for Inquiry by Unit or File Name

This section describes the format and effect of the inquiry specifiers that may appear in the inquiry by unit and file forms of the INQUIRE statement.

1.7.2.1. `UNIT=` Specifier

The format of the UNIT= specifier is as follows:

[ UNIT= ] scalar_int_expr

The scalar_int_expr indicates an external unit. The value of scalar_int_expr must be nonnegative.

To inquire by unit, a unit specifier must be present, and a file specifier cannot be present. If the keyword UNIT is omitted, scalar_int_expr must be the first item in the list.

A unit number identifies one and only one external unit in all program units in a Fortran program.

The file is the file connected to the unit, if one is connected; otherwise, the file does not exist.

1.7.2.2. `ACCESS=` Specifier

The format of the ACCESS= specifier is as follows:

ACCESS= scalar_char_variable

One of the following is returned in scalar_char_variable:

Value		Function
`SEQUENTIAL`		Indicates that the file is connected for sequential access.
`DIRECT`		Indicates that the file is connected for direct access.
`UNDEFINED`		Indicates that the file is not connected.

1.7.2.3. `ACTION=` Specifier

The format of the ACTION= specifier is as follows:

ACTION= scalar_char_variable

One of the following is returned in scalar_char_variable:

Value		Function
`READ`		Indicates that the file is connected with access limited to input only.
`WRITE`		Indicates that the file is connected with access limited to output only.
`READWRITE`		Indicates that the file is connected for both input and output.
`UNDEFINED`		Indicates that the file is not connected.

1.7.2.4. `BLANK=` Specifier

The format of the BLANK= specifier is as follows:

BLANK= scalar_char_variable

One of the following is returned in scalar_char_variable:

Value		Function
`NULL`		Indicates that null blank control is in effect.
`ZERO`		Indicates that zero blank control is in effect.
`UNDEFINED`		Indicates that the file is not connected for formatted I/O or the file is not connected at all.

See the BLANK= specifier for the OPEN statement in Section 1.5.5, for the meaning of null and zero blank control.

1.7.2.5. `DELIM=` Specifier

The format of the DELIM= specifier is as follows:

DELIM= scalar_char_variable

One of the following is returned in scalar_char_variable:

Value		Function
`APOSTROPHE`		Indicates that an apostrophe is used as the delimiter in list-directed and namelist-formatted output.
`QUOTE`		Indicates that the quotation mark is used as the delimiter in list-directed and namelist-formatted output.
`NONE`		Indicates that there is no delimiting character in list-directed and namelist-formatted output.
`UNDEFINED`		Indicates that the file is not connected or the file is not connected for formatted I/O.

1.7.2.6. `DIRECT=` Specifier

The format of the DIRECT= specifier is as follows:

DIRECT= scalar_char_variable

One of the following is returned in scalar_char_variable:

Value		Function
`YES`		Indicates that direct access is an allowed access method.
`NO`		Indicates that direct access is not an allowed access method.
`UNKNOWN`		Indicates that the system does not know if direct access is allowed.

1.7.2.7. `ERR=` Specifier

The format of the ERR= specifier is as follows:

ERR= label

The program branches to the label in the ERR= specifier if there is an error in the execution of the INQUIRE statement itself. The label must be the label of a branch target statement in the same scoping unit as the INQUIRE statement.

If an error condition occurs, the position of the file becomes indeterminate.

If an IOSTAT= specifier is present and an error condition occurs, the IOSTAT variable specified becomes defined with a positive value. All other inquiry specifier variables become undefined.

1.7.2.8. `EXIST=` Specifier

The format of the EXIST= specifier is as follows:

EXIST= scalar_default_logical_variable

The system returns either .TRUE. or .FALSE. in scalar_default_logical_variable. .TRUE. indicates that the file or unit exists. .FALSE. indicates that the file or unit does not exist.

1.7.2.9. `FILE=` Specifier

The format of the FILE= specifier is as follows:

FILE= scalar_char_expr

To inquire by file, a file specifier must be present, and a unit specifier cannot be present.

The value of scalar_char_expr must be an acceptable file name. Trailing blanks are ignored. Both uppercase and lowercase letters are acceptable. The use of uppercase and lowercase is significant for file names.

The file name can refer to a file not connected or to one that does not exist.

1.7.2.10. `FORM=` Specifier

The format of the FORM= specifier is as follows:

FORM= scalar_char_variable

The system returns one of the following in scalar_char_variable:

Value		Function
`FORMATTED`		Indicates that the file is connected for formatted I/O.
`UNFORMATTED`		Indicates that the file is connected for unformatted I/O.
`UNDEFINED`		Indicates that the file is not connected.

1.7.2.11. `FORMATTED=` Specifier

The format of the FORMATTED= specifier is as follows:

FORMATTED= scalar_char_variable

The system returns one of the following in scalar_char_variable:

Value		Function
`YES`		Indicates that formatted I/O is an allowed form for the file.
`NO`		Indicates that formatted I/O is not an allowed form for the file.
`UNKNOWN`		Indicates that the system cannot determine if formatted I/O is an allowed form for the file.

1.7.2.12. `IOSTAT=` Specifier

The format of the IOSTAT= specifier is as follows:

IOSTAT= scalar_default_int_variable

The I/O library returns an integer value in scalar_default_int_variable. If scalar_default_int_variable > 0, an error condition occurred. If scalar_default_int_variable = 0, no error condition occurred. Note that the value cannot be negative.

The IOSTAT= specifier applies to the execution of the INQUIRE statement itself.

1.7.2.13. `NAME=` Specifier

The format of the NAME= specifier is as follows:

NAME= scalar_char_variable

The I/O library returns either a file name or an undefined value in scalar_char_variable. If the value is a file name, it is the name of the file connected to the unit, if the file has a name. An undefined value indicates that either file does not have a name or no file is connected to the unit.

A name different from the one specified in the FILE= specifier on the OPEN statement may be returned.

1.7.2.14. `NAMED=` Specifier

The format of the NAMED= specifier is as follows:

NAMED= scalar_default_logical_variable

The system returns either .TRUE. or .FALSE. in scalar_default_logical_variable. .TRUE. indicates that the file has a name. .FALSE. indicates that the file does not have a name.

1.7.2.15. `NEXTREC=` Specifier

The format of the NEXTREC= specifier is as follows:

NEXTREC= scalar_default_int_variable

The system returns one of the following in scalar_default_int_variable:

Value		Function
last record number + `1`		Indicates the next record number to be read or written in a file connected for direct access. The value is one more than the last record number read or written.
`1`		Indicates that no records have been processed.
undefined value		Indicates that the file is not connected for direct access or the file position is indeterminate because of a previous error condition.

This inquiry is used for files connected for direct access.

1.7.2.16. `NUMBER=` Specifier

The format of the NUMBER= specifier is as follows:

NUMBER= scalar_default_int_variable

The system returns either a unit number or -1 in scalar_default_int_variable. A unit number indicates the number of the unit connected to the file. -1 indicates that there is no unit connected to the file.

1.7.2.17. `OPENED=` Specifier

The format of the OPENED= specifier is as follows:

OPENED= scalar_default_logical_variable

The system returns either .TRUE. or .FALSE. in scalar_default_logical_variable. .TRUE. indicates that the file or unit is connected (that is, opened). .FALSE. indicates that the file or unit is not connected (that is, not opened).

1.7.2.18. `PAD=` Specifier

The format of the PAD= specifier is as follows:

PAD= scalar_char_variable

The system returns either NO or YES in scalar_char_variable. NO indicates that the file or unit is connected with the PAD= specifier set to NO. YES indicates that either the file or unit is connected with the PAD= specifier set to YES or that the file or unit is not connected.

1.7.2.19. `POSITION=` Specifier

The format of the POSITION= specifier is as follows:

POSITION= scalar_char_variable

The system returns one of the following in scalar_char_variable:

Value		Function
`REWIND`		Indicates that the file is connected with its position at the initial point.
`APPEND`		Indicates that the file is connected with its position at the terminal point.
`ASIS`		Indicates that the file is connected without changing its position.
`UNDEFINED`		Indicates that either the file is not connected or it is connected for direct access.

If any repositioning has occurred since the file was connected, the value returned is ASIS. It is not equal to REWIND unless positioned at the initial point, and it is not equal to APPEND unless positioned at the terminal point.

1.7.2.20. `READ=` Specifier

The format of the READ= specifier is as follows:

READ= scalar_char_variable

The system returns one of the following in scalar_char_variable:

Value		Function
`YES`		Indicates that `READ` is one of the allowed actions for the file.
`NO`		Indicates that `READ` is not one of the allowed actions for the file.
`UNKNOWN`		Indicates that the action for the file cannot be determined.

1.7.2.21. `READWRITE=` Specifier

The format of the READWRITE= specifier is as follows:

READWRITE= scalar_char_variable

The system returns one of the following in scalar_char_variable:

Value		Function
`YES`		Indicates that `READWRITE` is an allowed action for the file.
`NO`		Indicates that `READWRITE` is not an allowed action for the file.
`UNKNOWN`		Indicates that the action for the file cannot be determined.

1.7.2.22. `RECL=` Specifier

The format of the RECL= specifier is as follows:

RECL= scalar_default_int_variable

The system returns either a maximum record length or an undefined value in scalar_default_int_variable. The maximum record length is the record length, if the file is connected for sequential access, or the length of each record, if the file is connected for direct access. An undefined value indicates that the file does not exist.

For a formatted file, the length is the number of characters for all records.

For an unformatted file, the length is in 8-bit bytes.

1.7.2.23. `SEQUENTIAL=` Specifier

The format of the SEQUENTIAL= specifier is as follows:

SEQUENTIAL= scalar_char_variable

The system returns one of the following in scalar_char_variable:

Value		Function
`YES`		Indicates that sequential access is an allowed access method.
`NO`		Indicates that sequential access is not an allowed access method.
`UNKNOWN`		Indicates that the access is not known.

1.7.2.24. `UNFORMATTED=` Specifier

The format of the UNFORMATTED= specifier is as follows:

UNFORMATTED= scalar_char_variable

The system returns one of the following in scalar_char_variable:

Value		Function
`YES`		Indicates that unformatted I/O is an allowed form for the file.
`NO`		Indicates that unformatted I/O is not an allowed form for the file.
`UNKNOWN`		Indicates that the form cannot be determined.

1.7.2.25. `WRITE=` Specifier

The format of the WRITE= specifier is as follows:

WRITE= scalar_char_variable

The system returns one of the following in scalar_char_variable:

Value		Function
`YES`		Indicates that `WRITE` is an allowed action for the file.
`NO`		Indicates that `WRITE` is not an allowed action for the file.
`UNKNOWN`		Indicates that the action cannot be determined.

1.7.3. Table of Values Assigned by the `INQUIRE` Statement

Figure 1-6, summarizes the values assigned to the INQUIRE specifier variables by the execution of an INQUIRE statement.

Figure 1-6. Values for Specifier Variables in an INQUIRE Statement

Prev Section	Table of Contents \| Title Page \| Index	Next Section
`CLOSE` Statement	Up one level	File Positioning Statements