INQUIRE

Purpose

The INQUIRE statement obtains information about the properties of a named file or the connection to a particular unit.

There are three forms of the INQUIRE statement:

Syntax



>>-INQUIRE--+-(--inquiry_list--)-----------------------+-------><
            '-(--IOLENGTH--=--iol--)--output_item_list-'
 
 

iol
indicates the number of bytes of data that would result from the use of the output list in an unformatted output statement. iol is a scalar integer variable.

output_item
See the PRINT or WRITE statement

inquiry_list
is a list of inquiry specifiers for the inquire-by-file and inquire-by-unit forms of the INQUIRE statement. The inquire-by-file form cannot contain a unit specifier, and the inquire-by-unit form cannot contain a file specifier. No specifier can appear more than once in any INQUIRE statement. The inquiry specifiers are:

[UNIT=] u
is a unit specifier. It specifies the unit about which the inquire-by-unit form of the statement is inquiring. u must be an external unit identifier whose value is not an asterisk. An external unit identifier refers to an external file that is represented by an integer expression, whose value is in the range 0 through 2147483647. If the optional characters UNIT= are omitted, u must be the first item in inquiry_list.

ACCESS= char_var
indicates whether the file is connected for direct access, sequential access, FORTRAN 2003 Begins or stream access. FORTRAN 2003 Ends char_var is a scalar character variable that is assigned the value SEQUENTIAL if the file is connected for sequential access. The value assigned is DIRECT if the file is connected for direct access. FORTRAN 2003 Begins The value assigned is STREAM if the file is connected for stream access. FORTRAN 2003 Ends If there is no connection, char_var is assigned the value UNDEFINED.

ACTION= act
indicates if the file is connected for read and/or write access. act is a scalar character variable that is assigned the value READ if the file is connected for input only, WRITE if the file is connected for output only, READWRITE if the file is connected for both input and output, and UNDEFINED if there is no connection.

+-------------------------------IBM Extension--------------------------------+

ASYNCH= char_variable
indicates whether the unit is connected for asynchronous access.

char_variable is a character variable that returns the value:

+----------------------------End of IBM Extension----------------------------+

BLANK= char_var
indicates the default treatment of blanks for a file connected for formatted input/output. char_var is a scalar character variable that is assigned the value NULL if all blanks in numeric input fields are ignored, or the value ZERO if all nonleading blanks are interpreted as zeros. If there is no connection, or if the connection is not for formatted input/output, char_var is assigned the value UNDEFINED.

DELIM= del
indicates the form, if any, that is used to delimit character data that is written by list-directed or namelist formatting. del is a scalar character variable that is assigned the value APOSTROPHE if apostrophes are used to delimit data, QUOTE if quotation marks are used to delimit data, NONE if neither apostrophes nor quotation marks are used to delimit data, and UNDEFINED if there is no file connection or no connection to formatted data.

DIRECT= dir
indicates if the file is connected for direct access. dir is a scalar character variable that is assigned the value YES if the file can be accessed directly, the value NO if the file cannot be accessed directly, or the value UNKNOWN if access cannot be determined.

ERR= stmt_label
is an error specifier that specifies the statement label of an executable statement in the same scoping unit to which control is to transfer in the case of an error. Coding the ERR= specifier suppresses error messages.

EXIST= ex
indicates if a file or unit exists. ex is an integer variable that is assigned the value true or false. For the inquire-by-file form of the statement, the value true is assigned if the file specified by the FILE= specifier exists. The value false is assigned if the file does not exist. For the inquire-by-unit form of the statement, the value true is assigned if the unit specified by UNIT= exists. The value false is assigned if it is an invalid unit.

FILE= char_expr

is a file specifier. It specifies the name of the file about which the inquire-by-file form of the statement is inquiring. char_expr is a scalar character expression whose value, when any trailing blanks are removed, is a valid Linux operating system file name. The named file does not have to exist, nor does it have to be associated with a unit.

+-------------------------------IBM Extension--------------------------------+

Note:
A valid Linux operating system file name must have a full path name of total length <= 1023 characters, with each file name <= 255 characters long (though the full path name need not be specified).

+----------------------------End of IBM Extension----------------------------+

FORM= char_var
indicates whether the file is connected for formatted or unformatted input/output. char_var is a scalar default character variable that is assigned the value FORMATTED if the file is connected for formatted input/output. The value assigned is UNFORMATTED if the file is connected for unformatted input/output. If there is no connection, char_var is assigned the value UNDEFINED.

FORMATTED= fmt
indicates if the file can be connected for formatted input/output. fmt is a scalar character variable that is assigned the value YES if the file can be connected for formatted input/output, the value NO if the file cannot be connected for formatted input/output, or the value UNKNOWN if formatting cannot be determined.

IOMSG= iomsg_variable
is an input/output status specifier that specifies the message returned by the input/output operation. iomsg_variable is a scalar default character variable. It must not be a use-associated nonpointer protected variable. When the input/output statement containing this specifier finishes execution, iomsg_variable is defined as follows:

IOSTAT= ios
is an input/output status specifier that specifies the status of the input/output operation. ios is an integer variable. When the input/output statement containing this specifier is finished executing, ios is defined with:

Coding the IOSTAT= specifier suppresses error messages.

NAME= fn
indicates the name of the file. fn is a scalar character variable that is assigned the name of the file to which the unit is connected.

NAMED= nmd
indicates if the file has a name. nmd is an integer variable that is assigned the value true if the file has a name. The value assigned is false if the file does not have a name.

NEXTREC= nr

indicates where the next record can be read or written on a file connected for direct access. nr is an integer variable that is assigned the value n + 1, where n is the record number of the last record read or written on the file connected for direct access. If the file is connected but no records were read or written since the connection, nr is assigned the value 1. If the file is not connected for direct access or if the position of the file cannot be determined because of a previous error, nr becomes undefined.

+-------------------------------IBM Extension--------------------------------+

Because record numbers can be greater than 2**31-1, you may choose to make the scalar variable specified with the NEXTREC= specifier of type INTEGER(8). This could be accomplished in many ways, two examples include:

+----------------------------End of IBM Extension----------------------------+

NUMBER= num
indicates the external unit identifier currently associated with the file. num is an integer variable that is assigned the value of the external unit identifier of the unit that is currently connected to the file. If there is no unit connected to the file, num is assigned the value -1.

OPENED= od
indicates if a file or unit is connected. od is an integer variable that is assigned the value true or false. For the inquire-by-file form of the statement, the value true is assigned if the file specified by FILE= char_var is connected to a unit. The value false is assigned if the file is not connected to a unit. For the inquire-by-unit form of the statement, the value true is assigned if the unit specified by UNIT= is connected to a file. The value false is assigned if the unit is not connected to a file. For preconnected files that have not been closed, the value is true both before and after the first input/output operation.

PAD= pd
indicates if the connection of the file had specified PAD=NO. pd is a scalar character variable that is assigned the value NO if the connection of the file had specified PAD=NO, and YES for all other cases.

POS=integer_var
FORTRAN 2003 Begins integer_var is an integer variable that indicates the value of the file position for a file connected for stream access. integer_var is assigned the number of the file storage unit immediately following the current position of a file connected for stream access. If the file is positioned at its terminal position, integer_var is assigned a value one greater than the highest-numbered storage unit in the file. integer_var becomes undefined if the file is not connected for stream access or if the position of the file can not be determined because of previous error conditions. FORTRAN 2003 Ends

POSITION= pos
indicates the position of the file. pos is a scalar character variable that is assigned the value REWIND if the file is connected by an OPEN statement for positioning at its initial point, APPEND if the file is connected for positioning before its endfile record or at its terminal point, ASIS if the file is connected without changing its position, or UNDEFINED if there is no connection or if the file is connected for direct access.

If the file has been repositioned to its initial point since it was opened, pos is assigned the value REWIND. If the file has been repositioned just before its endfile record since it was opened (or, if there is no endfile record, at its terminal point), pos is assigned the value APPEND. If both of the above are true and the file is empty, pos is assigned the value APPEND. If the file is positioned after the endfile record, pos is assigned the value ASIS.

READ= rd
indicates if the file can be read. rd is a scalar character variable that is assigned the value YES if the file can be read, NO if the file cannot be read, and UNKNOWN if it cannot be determined if the file can be read.

READWRITE= rw
indicates if the file can be both read from and written to. rw is a scalar character variable that is assigned the value YES if the file can be both read from and written to, NO if the file cannot be both read from and written to, and UNKNOWN if it cannot be determined if the file can be both read from and written to.

RECL= rcl

indicates the value of the record length of a file connected for direct access, or the value of the maximum record length of a file connected for sequential access.

rcl is an integer variable that is assigned the value of the record length.

If the file is connected for formatted input/output, the length is the number of characters for all records that contain character data. If the file is connected for unformatted input/output, the length is the number of bytes of data. If there is no connection, rcl becomes undefined.

FORTRAN 2003 Begins If the file is connected for stream access, rcl becomes undefined. FORTRAN 2003 Ends

SEQUENTIAL= seq
indicates if the file is connected for sequential access. seq is a scalar character variable that is assigned the value YES if the file can be accessed sequentially, the value NO if the file cannot be accessed sequentially, or the value UNKNOWN if access cannot be determined.

SIZE=filesize
filesize is an integer variable that is assigned the file size in bytes.

STREAM=strm
is a scalar default character variable that indicates whether the file is connected for FORTRAN 2003 Begins stream access. FORTRAN 2003 Ends strm is assigned the value YES if the file can be accessed using stream access, the value NO if the file cannot be accessed using stream access, or the value UNKNOWN if access cannot be determined.

+-------------------------------IBM Extension--------------------------------+

TRANSFER= char_variable
is an asynchronous I/O specifier that indicates whether synchronous and/or asynchronous data transfer are permissible transfer methods for the file.

char_variable is a scalar character variable. If char_variable is assigned the value BOTH, then both synchronous and asynchronous data transfer are permitted. If char_variable is assigned the value SYNCH, then only synchronous data transfer is permitted. If char_variable is assigned the value UNKNOWN, then the processor is unable to determine the permissible transfer methods for this file.

+----------------------------End of IBM Extension----------------------------+

UNFORMATTED= unf
indicates if the file can be connected for unformatted input/output. fmt is a scalar character variable that is assigned the value YES if the file can be connected for unformatted input/output, the value NO if the file cannot be connected for unformatted input/output, or the value UNKNOWN if formatting cannot be determined.

WRITE= wrt
indicates if the file can be written to. wrt is a scalar character variable that is assigned the value YES if the file can be written to, NO if the file cannot be written to, and UNKNOWN if it cannot be determined if the file can be written to.

Rules

An INQUIRE statement can be executed before, while, or after a file is associated with a unit. Any values assigned as the result of an INQUIRE statement are values that are current at the time the statement is executed.

+-------------------------------IBM Extension--------------------------------+

If the unit or file is connected, the values returned for the ACCESS=, SEQUENTIAL=, STREAM=, DIRECT=, ACTION=, READ=, WRITE=, READWRITE=, FORM=, FORMATTED=, UNFORMATTED=, BLANK=, DELIM=, PAD=, RECL=, POSITION=, NEXTREC=, NUMBER=, NAME= and NAMED= specifiers are properties of the connection, and not of that file. Note that the EXIST= and OPENED= specifiers return true in these situations.

If a unit or file is not connected or does not exist, the ACCESS=, ACTION=, FORM=, BLANK=, DELIM=, POSITION= specifiers return the value UNDEFINED, the DIRECT=, SEQUENTIAL=, STREAM=, FORMATTED=, UNFORMATTED=, READ=, WRITE= and READWRITE= specifiers return the value UNKNOWN, the RECL= and NEXTREC= specifier variables are not defined, the PAD= specifier returns the value YES, and the OPENED specifier returns the value false. The value returned by the SIZE= specifier is -1.

If a unit or file does not exist, the EXIST= and NAMED= specifiers return the value false, the NUMBER= specifier returns the value -1, and the NAME= specifier variable is not defined.

If a unit or file exists but is not connected, the EXIST= specifier returns the value true. For the inquire-by-unit form of the statement, the NAMED= specifier returns the value false, the NUMBER= specifier returns the unit number, and the NAME= specifier variable is undefined. For the inquire-by-file form of the statement, the NAMED= specifier returns the value true, the NUMBER= specifier returns -1, and the NAME= specifier returns the file name.

+----------------------------End of IBM Extension----------------------------+

The same variable name must not be specified for more than one specifier in the same INQUIRE statement, and must not be associated with any other variable in the list of specifiers.

Examples

SUBROUTINE SUB(N)
  CHARACTER(N) A(5)
  INQUIRE (IOLENGTH=IOL) A(1)  ! Inquire by output list
  OPEN (7,RECL=IOL)
      
  ·
  ·
  ·
END SUBROUTINE

Related Information

IBM Copyright 2003