# INQUIRE

Statement: Returns information on the status of specified properties of a file, logical unit, or directory. It takes one of the following forms:

Inquiring by File:

INQUIRE (FILE=name[, ERR=label] [, ID=id-var] [, IOMSG=msg-var] [, SIZE=sz] [, IOSTAT=i-var] [, DEFAULTFILE=def] slist)

Inquiring by Unit:

INQUIRE ([UNIT=]io-unit [, ERR=label] [, ID=id-var] [, IOMSG=msg-var] [, SIZE=sz] [, IOSTAT=i-var] slist)

Inquiring by Directory:

INQUIRE (DIRECTORY=dir, EXIST=ex [, DIRSPEC=dirspec] [, ERR=label] [, ID=id-var] [, IOMSG=msg-var] [, SIZE=sz] [, IOSTAT=i-var])

Inquiring by Output List:

INQUIRE (IOLENGTH=len) out-item-list

name | Is a scalar default character expression specifying the name of the file for inquiry. For more information, see FILE Specifier and STATUS Specifier.
label | Is the label of the branch target statement that receives control if an error occurs. For more information, see Branch Specifiers.
id-var | Is a scalar integer expression identifying a data transfer operation that was returned using the ID= specifier in a previous asynchronous READ or WRITE statement. For more information, see ID Specifier.
msg-var | Is a scalar default character variable that is assigned an explanatory message if an I/O error occurs. For more information, see I/O Message Specifier.
sz | Is a scalar integer variable that is assigned the size of the file in file storage units. For more information, see Size Specifier.
i-var | Is a scalar integer variable that is defined as a positive integer if an error occurs and zero if no error occurs. For more information, see I/O Status Specifier.
def | Is a scalar default character expression specifying a default file pathname string. (For more information, see the DEFAULTFILE specifier.)
slist | Is one or more of the following inquiry specifiers (each specifier can appear only once):
ACCESS | DELIM | NEXTREC | RECL
ACTION | DIRECT | NUMBER | RECORDTYPE
ASYNCHRONOUS | ENCODING | OPENED | ROUND
BINARY | EXIST | ORGANIZATION | SEQUENTIAL
BLANK | FORM | PAD | SHARE
BLOCKSIZE | FORMATTED | PENDING | SIGN
BUFFERED | IOFOCUS | POS | SIZE
CARRIAGECONTROL | MODE | POSITION | UNFORMATTED
CONVERT | NAME | READ | WRITE
DECIMAL | NAMED | READWRITE |
io-unit | Is an external unit specifier. The unit does not have to exist, nor does it need to be connected to a file. If the unit is connected to a file, the inquiry encompasses both the connection and the file.
dir | Is a scalar default character expression specifying the name of the directory for inquiry. If you are inquiring by directory, it must be present.
ex | Is a scalar default logical variable that is assigned the value .TRUE. if dir names a directory that exists; otherwise, ex is assigned the value .FALSE.. If you are inquiring by directory, it must be present. For more information, see the EXIST Specifier.
dirspec | Is a scalar default character variable that is assigned the value of the full directory specification of dir if ex is assigned the value .TRUE.. This specifier can only be used when inquiring by directory.
len | (Output) Is a scalar integer variable that is assigned a value corresponding to the length of an unformatted, direct-access record resulting from the use of the out-item-list in a WRITE statement. The value is suitable to use as a RECL specifier value in an OPEN statement that connects a file for unformatted, direct access. The unit of the value is 4-byte longwords, by default. However, if you specify compiler option assume byterecl, the unit is bytes.
out-item-list | (Output) Is a list of one or more output items (see I/O Lists).

## Description

The control specifiers ([UNIT=] io-unit, ERR= label, and IOSTAT= i-var) and inquiry specifiers can appear anywhere within the parentheses following INQUIRE. However, if the UNIT keyword is omitted, the io-unit must appear first in the list.

An INQUIRE statement can be executed before, during, or after a file is connected to a unit. The specifier values returned are those that are current when the INQUIRE statement executes.

To get file characteristics, specify the INQUIRE statement after opening the file.

## Examples

The following shows examples of INQUIRE statements.

In the last statement, you can use the length returned in LEN as the value for the RECL specifier in an OPEN statement that connects a file for unformatted direct access. If you have already specified a value for RECL, you can check LEN to verify that A and B are less than or equal to the record length you specified.

    INQUIRE (FILE='FILE_B', EXIST=EXT)
    INQUIRE (4, FORM=FM, IOSTAT=IOS, ERR=20)
    INQUIRE (IOLENGTH=LEN) A, B

In the following example, the program prompts for the name of a data file. The INQUIRE statement then determines whether the file exists. If it does not, the program prompts for another file name.

          CHARACTER*12 fname
          LOGICAL exists

    !     Get the name of a file:
    100   WRITE (*, '(1X, A\)') 'Enter the file name: '
          READ (*, '(A)') fname

    !     INQUIRE about file's existence:
          INQUIRE (FILE = fname, EXIST = exists)

          IF (.NOT. exists) THEN
            WRITE (*,'(2A/)') ' >> Cannot find file ', fname
            GOTO 100
          END IF
          END

Parent topic: H to I

## See Also

OPEN statement
UNIT control specifier
ERR control specifier
ID control specifier
IOMSG control specifier
IOSTAT control specifier
RECL specifier in OPEN statements
FILE specifier in OPEN statements
DEFAULTFILE specifier in OPEN statements
assume:byterecl compiler option