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:
- Inquire by file, which requires the FILE= specifier.
- Inquire by output list, which requires the IOLENGTH= specifier
- Inquire by unit, which requires the UNIT= specifier.
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,
or stream access.
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.
The value assigned is STREAM if the file is connected for
stream access.
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:
- YES if the unit is connected for both synchronous and
asynchronous access;
- NO if the unit is connected for synchronous access only; or
- UNDEFINED if the unit is not connected.
+----------------------------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:
- If an error, end-of-file, or end-of-record condition occurs, the variable
is assigned an explanatory message as if by assignment.
- If no such condition occurs, the value of the variable is
unchanged.
- 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:
- A zero value if no error condition occurs
- A positive value if an error occurs.
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:
- Explicitly declaring nr as INTEGER(8)
- Changing the default kind of integers with the -qintsize=8
compiler option.
+----------------------------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
-
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.
- 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.
If the file is connected for stream access, rcl becomes
undefined.
- 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
stream access.
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
