INQUIRE FILE

Retrieve information about a file.

Read syntax diagramSkip visual syntax diagramINQUIRE FILE
 
                             .-----------------------------.
                             V                             |
>>-INQUIRE FILE(data-value)----+-------------------------+-+---><
                               +-ACCESSMETHOD(cvda)------+
                               +-ADD(cvda)---------------+
                               +-BASEDSNAME(data-area)---+
                               +-BLOCKFORMAT(cvda)-------+
                               +-BLOCKKEYLEN(data-area)--+
                               +-BLOCKSIZE(data-area)----+
                               +-BROWSE(cvda)------------+
                               +-CFDTPOOL(data-area)-----+
                               +-DELETE(cvda)------------+
                               +-DISPOSITION(cvda)-------+
                               +-DSNAME(data-area)-------+
                               +-EMPTYSTATUS(cvda)-------+
                               +-ENABLESTATUS(cvda)------+
                               +-EXCLUSIVE(cvda)---------+
                               +-FWDRECSTATUS(cvda)------+
                               +-JOURNALNUM(data-area)---+
                               +-KEYLENGTH(data-area)----+
                               +-KEYPOSITION(data-area)--+
                               +-LOADTYPE(cvda)----------+
                               +-LSRPOOLID(data-area)----+
                               +-MAXNUMRECS(data-area)---+
                               +-OBJECT(cvda)------------+
                               +-OPENSTATUS(cvda)--------+
                               +-READ(cvda)--------------+
                               +-READINTEG(cvda)---------+
                               +-RECORDFORMAT(cvda)------+
                               +-RECORDSIZE(data-area)---+
                               +-RECOVSTATUS(cvda)-------+
                               +-RELTYPE(cvda)-----------+
                               +-REMOTENAME(data-area)---+
                               +-REMOTESYSTEM(data-area)-+
                               +-REMOTETABLE(cvda)-------+
                               +-RLSACCESS(cvda)---------+
                               +-STRINGS(data-area)------+
                               +-TABLE(cvda)-------------+
                               +-TABLENAME(data-area)----+
                               +-TYPE(cvda)--------------+
                               +-UPDATE(cvda)------------+
                               '-UPDATEMODEL(cvda)-------'
 

Conditions: END, FILENOTFOUND, ILLOGIC, NOTAUTH

For more information about the use of CVDAs, see CICS-value data areas (CVDAs).

Description

The INQUIRE FILE command returns information about a FILE resource definition.

When the file is associated with a VSAM or BDAM object, INQUIRE FILE returns information about the associated object as well.

(You cannot use INQUIRE FILE to get information about DL/I data sets or data sets associated with other CICS resources or functions. However, see the INQUIRE DUMPDS, JOURNALNAME, and TDQUEUE commands if you need information about dump data sets, journals, or TD queues.

The values returned depend on:

Some options for the INQUIRE FILE command are specific to one or another of the file objects supported by CICS, such as VSAM or BDAM data sets, and data tables. Many of these parameters can be specified even when the file refers to a different object from that to which the parameters apply. This is intended to make it easier to switch file definitions between different objects; for example, between non-RLS and RLS access, or between a user-maintained data table and a coupling facility data table. When a parameter is specified for an object to which the file does not currently refer, it is ignored.

Browsing

You can also browse through all of the files installed in your system by using the browse options (START, NEXT, and END) on INQUIRE FILE commands. See Browsing resource definitions for general information about browsing, including syntax, exception conditions, and examples.

Options

ACCESSMETHOD(cvda)
returns a CVDA value identifying the access method for this file. CVDA values are:
BDAM
The access method is BDAM.
REMOTE
The file is defined as remote, and therefore the access method is not known to the local CICS system.
VSAM
The access method is VSAM. Access to a data table (except while it is being loaded or, for a CICS-maintained data table, when the source data set is being updated or searched for a record that is not in the table), is through CICS data table services. Because this access is still based on VSAM keys, CICS returns VSAM as the access method for any kind of data table.
ADD(cvda)
returns a CVDA value identifying whether new records can be added to the file. CVDA values are:
ADDABLE
New records can be added to the file.
NOTADDABLE
New records cannot be added to the file.
BASEDSNAME(data-area) (VSAM only)
returns the 44-character name of the base cluster associated with a VSAM path, if the object associated with the file is a path. If the object is other than a path, this option returns the same value as the DSNAME option.

The BASEDSNAME is blank if the file has not been opened since the last initial or cold start of this CICS. If the file has been opened at least once since the last initial or cold start, CICS returns the 44-character name, even though the file may not be open at the time the command is issued. This is because the name is preserved in the CICS catalog and recovered on a restart.

If the object is a coupling facility data table loaded from a source data set, the 44-character name returned on BASEDSNAME is the same as that returned on DSNAME. BASEDSNAME is blank for a coupling facility data table that is not associated with a source data set.

Note:
The translator still accepts BASENAME for this option, but you should use BASEDSNAME in new code.
BLOCKFORMAT(cvda) (BDAM only)
returns a CVDA value identifying whether records on the file are blocked or unblocked. CVDA values are:
BLOCKED
The records on the file are blocked, or this is a VSAM file.
UNBLOCKED
The records on the file are unblocked.
BLOCKKEYLEN(data-area) (BDAM only)
returns a fullword binary field indicating the physical block key length for the file.
BLOCKSIZE(data-area) (BDAM only)
returns a fullword binary field indicating the length in bytes of a block. If the blocks are of variable length or are undefined, the value returned is the maximum.
BROWSE(cvda)
returns a CVDA value identifying whether you can browse the file. CVDA values are:
BROWSABLE
You can browse the file.
NOTBROWSABLE
You cannot browse the file.
CFDTPOOL(data-area) (CFDT only)
returns the 8-character name of the coupling facility data table pool in which the coupling facility data table resides. CICS returns blanks if the file does not refer to a coupling facility data table and no pool name has been specified.
DELETE(cvda) (VSAM only)
returns a CVDA value identifying whether you can delete records from the file. CVDA values are:
DELETABLE
You can delete records from the file.
NOTDELETABLE
You cannot delete records from the file.
DISPOSITION(cvda)
returns a CVDA value indicating the value of the DISPOSITION option for the file (from the DISPOSITION option in the FILE definition or the JCL DD statement to which it points). CVDA values are:
OLD
Disposition is OLD.
SHARE
Disposition is SHARE.
DSNAME(data-area)
returns the 44-character name of the BDAM data set or VSAM object associated with the FILE definition.

If the file has not been opened since the last initial or cold start, the name is taken from the file resource definition. CICS returns blanks if the data set name is not defined on the file definition.

For a coupling facility data table loaded from a data set, CICS returns the 44-character source data set name, and blanks for a coupling facility data table that is not loaded from a data set.

EMPTYSTATUS(cvda) (VSAM only)
returns a CVDA value indicating whether EMPTYREQ has been set for the file. EMPTYREQ causes the object associated with this file to be set to empty, if eligible, when the file is opened. VSAM data sets defined as reusable, and defined to be used in non-RLS mode, are the only ones that you can make empty in this way; EMPTYREQ has no effect on other objects. CVDA values are:
EMPTYREQ
The data set should be made empty.
NOEMPTYREQ
The data set should not be made empty.
ENABLESTATUS(cvda)
returns a CVDA value identifying whether application programs can access the file. CVDA values are:
DISABLED
The file is unavailable for access by application programs because it has been explicitly disabled. It must be explicitly enabled by a SET FILE ENABLED command or its CEMT equivalent before it can be accessed by application programs.
DISABLING
A request to disable the file has been received, but tasks are executing that had previously accessed the file. These tasks are allowed to complete their use of the file, but new tasks are not allowed access.
ENABLED
The file is available for access by application programs.
UNENABLED
The file is unavailable for access by application programs because it is closed. It must be explicitly enabled by a SET FILE OPEN command or its CEMT equivalent before it can be accessed by application programs.
UNENABLING
A request to close the file has been received, but tasks are executing that had previously accessed the file. These tasks are allowed to complete their use of the file, but new tasks are not allowed access.
EXCLUSIVE(cvda) (BDAM only)
returns a CVDA value identifying whether records on this file are to be placed under exclusive control when a read for update is issued. CVDA values are:
EXCTL
A record on this file is placed under exclusive control of the reading task when it is read for update.
NOEXCTL
A record on this file is not placed under exclusive control when it is read for update.
FILE(data-value)
specifies the 8-character name of the file about which you are inquiring.
FWDRECSTATUS(cvda) (VSAM only)
returns a CVDA value identifying whether the file is forward-recoverable.

The value CICS returns for FWDRECSTATUS depends on whether the file has been opened since the last initial or cold start:

  • If the file has not been opened since the last initial or cold start, CICS returns the value from the file definition.
  • If the file has been opened at least once since the last initial or cold start, CICS returns the value that was used when the file was last opened. This can be different from the value on the file definition because, for example, the file definition may be overridden by a value from the ICF catalog.

CVDA values are:

FWDRECOVABLE
The file is forward-recoverable. The RECOVERY option of the FILE definition specifies that updates to the file are to be recorded, to make forward recovery of the file possible. The forward-recovery log can be found using INQUIRE DSNAME.
NOTFWDRCVBLE
The file is not forward-recoverable. CICS returns NOTFWDRCVBLE for a coupling facility data table and a user-maintained data table.
JOURNALNUM(data-area)
returns a halfword binary field indicating the number of the journal to which CICS writes the information required for autojournaling. The value returned in JOURNALNUM is the number specified by the JOURNAL parameter in the file resource definition.

Journal numbers are between 1 and 99 and correspond to journal names DFHJ01 through DFHJ99. A value of 0 means that JOURNAL(NO) is specified and CICS does not perform autojournaling for the file.

JOURNALNUM is ignored for user-maintained and coupling facility data tables: There is no autojournalling of requests made to these tables.

KEYLENGTH(data-area)
returns a fullword binary field indicating the length of the record key for a file associated with a VSAM KSDS or a file associated with a coupling facility data table. If the file is associated with a BDAM data set, the value is the length of the logical key used for deblocking.
Notes:
  1. If the file is closed and the key length is not defined in the file definition, the value returned is 0 (zero).
  2. If the file is closed and a key length is defined on the file definition, CICS returns the value from the file definition.
  3. If the file is open, most files get their key length from the associated data set, in which case CICS returns the value from the data set. However, files that refer to coupling facility data tables defined with LOAD(NO) must get their keylength from the file definition, in which case CICS returns the value from the file definitions for such files. This value must also match that of the coupling facility data table if it has already been created.
KEYPOSITION(data-area)
returns a fullword binary field indicating the starting position of the key field in each record relative to the beginning of the record. The start is made at position 0. If there is no key, or if the file is not open, CICS returns a value of zero for the key position.

For a coupling facility data table associated with a source data set, where the file is open, the key position is obtained from the source data set. If the coupling facility data table is not associated with a source data set CICS returns zero.

LOADTYPE(cvda) (VSAM only)
returns a CVDA value indicating the load type for a coupling facility data table. CVDA values are:
LOAD
The coupling facility data table is, or is to be, preloaded from a source data set.
NOLOAD
The coupling facility data table is not preloaded from a source data set.
NOTAPPLIC
The file is not defined as a coupling facility data table, and no value is defined in the file resource definition.

CICS returns LOAD or NOLOAD if the file is not defined as a coupling facility data table, but one of these options is specified on the LOAD attribute of the file resource definition. In this case, the LOADTYPE CVDA indicates the load type that applies if the file definition is altered to specify TABLE(CF).

LOADTYPE has no significance for a CICS-maintained or user-maintained shared data table. A shared data table is always loaded from a source data set when the first file to reference the table is opened.

LSRPOOLID(data-area) (VSAM only)
returns a fullword binary field indicating the number of the VSAM LSR pool associated with this file, in the range 1-8. If the file does not share buffers, this value is 0.
MAXNUMRECS(data-area) (data tables only)
returns a fullword binary field indicating the maximum number of records that the data table for this file can hold. The value returned by CICS is affected by the following factors:
  • If the file resource definition specifies a MAXNUMRECS numeric value, even though the object is not a table (NOTTABLE CVDA is returned on the TABLE option), CICS returns the specified value.
  • If the file resource definition is specified with MAXNUMRECS(NOLIMIT), meaning the number of records is unlimited, CICS returns a value of zero. (Internally, CICS holds NOLIMIT as the maximum positive fullword value (+2147483647 or X'7FFFFFFF').
  • If the file is remote, CICS returns a value of minus 1 (-1).
  • If the object is a coupling facility data table:
    • The maximum number of records can be altered by a coupling facility data table server command, leaving the file definition MAXNUMRECS value unchanged. CICS returns the value in the file definition until the file is opened, after which CICS returns the actual MAXNUMRECS value defined to the server.
    • If the value is changed again by a coupling facility data table server command, CICS obtains and returns the new value only after the file is next opened or inquired upon. Until then, CICS continues to return the old value.
    • You can use the server DISPLAY TABLE console command to obtain the current value for a coupling facility data table.
OBJECT(cvda) (VSAM only)
returns a CVDA value indicating whether the file is associated with a data set (a VSAM KSDS, ESDS, or RRDS, or an alternate index used directly) or a VSAM path that links an alternate index to its base cluster. CVDA values are:
BASE
The file is associated with a data set that is a VSAM base. CICS also returns BASE for data tables (data table access provides primary key access only, not access though a path).
PATH
The file is associated with a path.
You get a value of PATH only if the file defines a path to a VSAM base data set through an alternate index. If the file definition allows direct access to an alternate index, or if the path is used merely as an alias to a base data set, you get a value of BASE. Also, if the file has not been opened since the last initial or cold start, CICS returns a default value of BASE.

If the file is a data table, the OBJECT option refers to its source data set.

OPENSTATUS(cvda)
returns a CVDA value identifying whether the file is open, closed, or in a transitional state. The OPENSTATUS value affects the ability of application tasks to access the file, but only indirectly; see the ENABLESTATUS option description for the rules. CVDA values are:
CLOSED
The file is closed.
CLOSING
The file is in the process of being closed. Closing a file may require dynamic deallocation of data sets and deletion of shared resources, in which case close processing may last a significant length of time.
CLOSEREQUEST
The file is open and in use by one or more application tasks. An EXEC CICS SET FILE CLOSED or a CEMT SET FILE CLOSED request has been received, but closing is not complete (the ENABLESTATUS of the file is DISABLING).
NOTAPPLIC
The OPENSTATUS value does not apply to this type of file. For example, it does not apply to a remote file.
OPEN
The file is open.
OPENING
The file is in the process of being opened.
READ(cvda)
returns a CVDA value identifying whether you can read records from the file. CVDA values are:
NOTREADABLE
You cannot read records from the file.
READABLE
You can read records from the file.
READINTEG(cvda)
returns a CVDA value indicating the default level of read integrity that is active for the file if a read integrity option is not explicitly coded on a file read request command. CVDA values are:
CONSISTENT
Read requests for this file are subject to consistent read integrity (unless otherwise specified on the read request).
NOTAPPLIC
Read integrity is not applicable for this file for one of the following reasons:
  • The file is a VSAM file accessed in non-RLS mode
  • The file is a remote file
  • The file refers to a BDAM data set
  • The file refers to a coupling facility data table.
Note:
If you switch a file from RLS to non-RLS mode, the read integrity option specified for RLS mode is preserved. In this case, CICS returns NOTAPPLIC. If you switch the file back to RLS mode, CICS returns the saved read integrity in response to an INQUIRE FILE command.
REPEATABLE
Read requests for this file are subject to repeatable read integrity (unless otherwise specified on the read request).
UNCOMMITTED
No read integrity is specified for this file.
RECORDFORMAT(cvda)
returns a CVDA value identifying the format of the records on the file. CVDA values are:
FIXED
The records are of fixed length.
UNDEFINED
The format of records on the file is undefined. The UNDEFINED value is possible for BDAM data sets only.
VARIABLE
The records are of variable length. If the file is associated with a user-maintained data table, the record format is always variable length, even if the source data set contains fixed-length records.
RECORDSIZE(data-area)
returns a fullword binary field indicating the actual size of fixed-length records, or the maximum size of variable-length records.

If the file is not open, CICS returns the value specified in the installed file definition.

If the file is open, most files get their record size from the associated data set, in which case CICS returns the value from the data set. However, files that refer to coupling facility data tables defined with LOAD(NO) must get their record size from the file definition, in which case CICS returns the value from the file definitions for such files. This value must also match that of the coupling facility data table if it has already been created.

RECOVSTATUS(cvda)
returns a CVDA value identifying whether the file is recoverable.

The value CICS returns for RECOVSTATUS depends on whether the file has been opened since the last initial or cold start of the CICS region:

  • If the file has not been opened since the last initial or cold start, CICS returns the value from the file definition.
  • If the file has been opened at least once since the last initial or cold start, CICS returns the value that was used when the file was last opened. This can be different from the value on the file definition because, for example, the file definition may be overridden by a value from the ICF catalog (but any value from the ICF catalog is ignored for a user-maintained or CICS-maintained data table)..

CVDA values are:

NOTRECOVABLE
The file is not recoverable.
RECOVERABLE
The file is recoverable.
RELTYPE(cvda) (BDAM only)
returns a CVDA value indicating whether relative or absolute addressing is used to access the file and, if relative, the type of relative addressing. CVDA values are:
BLK
Relative block addressing is being used.
DEC
The zoned decimal format is being used.
HEX
The hexadecimal relative track and record format is being used.
NOTAPPLIC
Absolute (MBBCCHHR) addressing is being used (or the file is a VSAM file).
REMOTENAME(data-area)
returns the 8-character name by which the file is known in the CICS region named in the REMOTESYSTEM option of its FILE definition. Blanks are returned if the file is not remote.
REMOTESYSTEM(data-area)
returns a 4-character name of the CICS region in which the file is defined (from the REMOTESYSTEM value in the FILE definition). Blanks are returned if the file is not remote.
REMOTETABLE(cvda) (VSAM only)
returns a CVDA value indicating whether the file represents an open remote data table. CVDA value can be:
REMTABLE
The file represents an open remote data table.
RLSACCESS(cvda)
returns a CVDA value indicating whether the file is defined to be opened in RLS mode. CVDA values are:
NOTAPPLIC
The file is not eligible to be accessed in RLS mode because:
  • It is a remote file, or
  • It refers to a BDAM data set.
NOTRLS
The file refers to a data set defined to be accessed in non-RLS mode.
RLS
The file refers to a data set defined to be accessed in RLS mode.
STRINGS(data-area) (VSAM only)
returns a fullword binary field indicating the number of strings (concurrent operations) specified for the file in its FILE definition.
TABLE(cvda) (VSAM and CFDT only)
returns a CVDA value indicating whether the file represents a data table. CVDA values are:
CFTABLE
The file represents a coupling facility data table.
CICSTABLE
The file represents a CICS-maintained data table.
NOTTABLE
The file does not represent a data table.
USERTABLE
The file represents a user-maintained data table.
TABLENAME(data-area) (CFDT only)
returns the 8-character table name specified for the coupling facility data table on the file resource definition, if one is specified, or returns the file name if the table name is omitted from the file resource definition.

CICS returns blanks if the file does not refer to a coupling facility data table

TYPE(cvda)
returns a CVDA value identifying the type of data set that corresponds to this file. The data set must be open to return the type of data set. CVDA values are:
ESDS
The data set is an entry-sequenced data set.
KEYED
The data set is addressed by physical keys.
KSDS
The data set is a key-sequenced data set or the file refers to a data table.
NOTKEYED
The data set is not addressed by physical keys.
RRDS
The data set is a relative record data set.
VRRDS
The data set is a variable--length relative record data set.
NOTAPPLIC
The data set is not open.
UPDATE(cvda)
returns a CVDA value identifying whether the file is updatable. CVDA values are:
NOTUPDATABLE
You cannot update records.
UPDATABLE
You can update records.
UPDATEMODEL(cvda) (CFDT only)
returns a CVDA value indicating the update model specified for the coupling facility data table in the installed file definition. CVDA values are:
CONTENTION
The coupling facility data table is updated using the contention model.
LOCKING
The coupling facility data table is updated using the locking model.
NOTAPPLIC
The file does not refer to a coupling facility data table and UPDATEMODEL on the file resource definition does not specify a value.

It is possible to define a file that specifies LOCKING or CONTENTION on the UPDATEMODEL attribute when the file does not refer to a coupling facility data table. In this case, CICS returns the specified UPDATEMODEL value on the INQUIRE FILE command, and not NOTAPPLIC. If you redefine the command to refer to a coupling facility data table, the specified UPDATEMODEL takes effect.

For information about the contention and locking models, see the CICS® Resource Definition Guide.

Conditions

END
RESP2 values:
2
There are no more resource definitions of this type.
FILENOTFOUND
RESP2 values:
1
The file cannot be found.
ILLOGIC
RESP2 values:
1
You have issued a START command when a browse of this resource type is already in progress, or you have issued a NEXT or an END command when a browse of this resource type is not in progress.
NOTAUTH
RESP2 values:
100
The user associated with the issuing task is not authorized to use this command.
101
The user associated with the issuing task is not authorized to access this particular resource in the way required by this command.
[[ Contents Previous Page | Next Page Index ]]