INQUIRE DSNAME
Retrieve information about an external data set.
Conditions: DSNNOTFOUND, END, ILLOGIC, IOERR, NOTAUTH,
For more information about the use of CVDAs, see CICS-value data areas (CVDAs).
Description
The INQUIRE DSNAME command returns information about the object associated with a FILE resource definition, which can be a BDAM data set, a VSAM data set, or a VSAM path to a data set through an alternate index.
Data sets are associated with files either dynamically, through the DSNAME attribute in the FILE definition, or statically, through the DSN option on the associated JCL DD statement. Many of the attributes of a data set cannot be determined until the first file that references the data set is opened by the CICS® region in which the command is issued. Where an attribute is not valid until a file is opened, the NOTAPPLIC state is returned.
Browsing
You can also browse through all the objects associated with files installed in your system, by using the browse options (START, NEXT, and END) on INQUIRE DSNAME 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 used
with this data set. CVDA values are:
- BDAM
- The access method is BDAM.
- NOTAPPLIC
- The data set has not been opened by the CICS region in which the command is issued.
- VSAM
- The access method is VSAM.
- AVAILABILITY(cvda) (VSAM only)
- Returns a CVDA value indicating whether the data set
is currently flagged, in this CICS region, as available or unavailable for use. The availability indicator
is a local flag that a CICS region maintains in a data set name block (DSNB) for each data set.
CVDA values are:
- AVAILABLE
- The data set is available for use according to the CICS data set name block. CICS can issue both RLS and non-RLS open requests
for this data set. Note: Although a data set is available according to information held by CICS, an open request can still fail if the ICF catalog indicates otherwise. This can occur, for example, if data set recovery is pending or in progress.
- NOTAPPLIC
- The data set is not a VSAM data set, or the data set has not been opened by the CICS region in which this command is issued.
- UNAVAILABLE
- Returned for a data set that CICS has marked as not available for use. The CICS region is unable to open the data set in either RLS or non-RLS mode.
- BACKUPTYPE(cvda) (VSAM only)
- Returns a CVDA value identifying the type of backup used
for this data set. CVDA values are:
- DYNAMIC
- The data set is eligible for “backup while open” (BWO) processing;
that is, a data set manager with the required function can take a
backup of the data set while it is open for output. The data set can
also be backed up while it is closed. The data set is eligible for
BWO and it is accessed in non-RLS mode.
If the data set is opened in RLS mode, you need to look in the VSAM catalog to find out whether the data set is eligible for BWO. NOTAPPLIC is returned as the BACKUPTYPE for data sets opened RLS mode.
- NOTAPPLIC
- The data set has not been opened by the CICS region in which the command is issued, or the data set is BDAM or a VSAM PATH. Also, if the data set has been opened in RLS mode, NOTAPPLIC is returned. The VSAM catalog should be referred to get the BWO status.
- STATIC
- The data set is accessed in non-RLS mode, and is not eligible
for BWO processing. All CICS files open for output against this data set must be closed before
a data set manager, such as DFSMShsm or DFSMSdss, can take a backup
copy. Hierarchical storage manager (DFSMShsm) and data set services
(DFSMSdss) are components of Data Facility Storage Management Subsystem
(DFSMS/MVS).
If the data set is opened in RLS mode, you need to look in the VSAM catalog to find out whether the data set is eligible for BWO.
- UNDETERMINED
- Returned for base files if RECOVSTATUS is UNDETERMINED.
- BASEDSNAME(data-area) (VSAM only)
- Returns the 44-character name of the base cluster associated
with a VSAM path, when the object of the inquiry is a path. When the
object is a VSAM data set, this option returns the same value as the
DSNAME option.
Blanks are returned if the access method is BDAM, or if the data set has not been opened by the CICS region in which the command is issued.
- DSNAME(data-value)
- Specifies the 44-character identifier of the object about which you are inquiring. It must be associated with a FILE definition installed in CICS, named either in the DSNAME option of that definition or the JCL DD statement specified in the DDNAME option.
- FILECOUNT(data-area)
- Returns a fullword binary field indicating the number of installed file definitions that refer to this data set.
- FWDRECOVLOG(data-area) (VSAM only)
- FWDRECOVLSN(data-area) (VSAM only)
- LOGREPSTATUS(cvda)
- Returns a CVDA value identifying whether the data set
was defined with LOGREPLICATE. The valid values are:
- LOGREPLICATE
- All updates to the data set are logged for replication.
- NOLOGREPLICA
- Updates to the data set are not logged for replication.
- NOTAPPLIC
- The data set has not been opened by the CICS region in which the command is issued, or the data set is BDAM .
- LOSTLOCKS(cvda) (RLS only)
- Returns a CVDA value indicating whether there are any
lost locks for this data set. CVDA values are:
- NOTAPPLIC
- This is not an RLS data set, or the data set has not been opened by the CICS region in which the command is issued.
- NOLOSTLOCKS
- The data set has no lost locks.
- REMLOSTLOCKS
- The data set has lost locks, hence is unavailable, but no recovery is required on this CICS region.
- RECOVERLOCKS
- The data set has lost locks, hence is unavailable, and the CICS region is performing lost-locks recovery.
See the RESETLOCKS and the FORCE|COMMIT|BACKOUT options on the EXEC CICS SET DSNAME command for information about purging units of work that might be holding up lost locks recovery.
- OBJECT(cvda) (VSAM only)
- Returns a CVDA value indicating whether the object of
the inquiry is a real data set containing records (a VSAM KSDS, ESDS,
or RRDS, or an alternate index used directly) or a VSAM path definition
that links an alternate index to its base cluster. CVDA values are:
- BASE
- This is a data set containing records.
- NOTAPPLIC
- The data set has not been opened by the CICS region in which the command is issued, or it is a BDAM data set.
- PATH
- This is a path.
- QUIESCESTATE(cvda) (VSAM only)
- Returns a CVDA value indicating the RLS quiesce state
of the data set. The information is obtained from the ICF catalog
entry for the data set. Note: This option is returned, whether the data set has been opened by the CICS region in which the command is issued.CVDA values are:
- NOTAPPLIC
- This data set is:
- Migrated
- Accessed using BDAM
- Accessed using a level of VSAM that does not support RLS (that is, DFSMS/MVS is earlier than 1.3)
NOTAPPLIC is also returned if CICS is running without RLS support (the RLS=NO system initialization parameter is specified or implied).
- QUIESCED
- This data set has been quiesced. CICS cannot open files in RLS mode against the data set, and no CICS region has a file currently open against this data set. However, the data set can be opened in non-RLS mode.
- QUIESCING
- This data set is in the process of quiescing. It applies only to the CICS region that initiated the quiesce; for other CICS regions, UNQUIESCED is returned.
- UNQUIESCED
- The normal value for a data set that is not quiescing or is not quiesced. It indicates that files can be opened in RLS or non-RLS mode against the data set, the mode being established by the first open. After a file is opened in one mode, other files can be opened only in the same mode.
- RECOVSTATUS(cvda)
- Returns a CVDA value identifying the recovery characteristics
of the data set. CVDA values are:
- FWDRECOVABLE
- All updates to the data set are logged for both backout and forward recovery.
- NOTAPPLIC
- This is a BDAM data set or a VSAM path, or the data set has not been opened by the CICS region in which the command is issued.
- NOTRECOVABLE
- Updates to the data set are not logged.
This response may also be returned as the result of use of the XFCNREC global user exit. A program enabled at XFCNREC may indicate that file opens should proceed even if there is a mismatch in the backout recovery requirements for different files associated with same data set. In these circumstances, the data set is marked as NOTRECOVABLE to indicate that its data integrity can no longer be guaranteed. The condition remains until cleared by a CEMT SET DSNAME REMOVE or EXEC CICS SET DSNAME REMOVE command, or by an initial or cold start.
While the data set is in this state, backout logging is performed for a particular request based on the specification in the file definition. Therefore backout logging may occur for requests via one file and not via another.
- RECOVERABLE
- All updates to the data set are logged for backout.
- UNDETERMINED
- The recovery status is unknown because no files associated with this data set have been opened, or because the only files opened were defined as coupling facility data tables or as user-maintained data tables (where the recovery attributes are independent of the associated data set).
- RETLOCKS(cvda)
- Returns a CVDA value indicating whether there are any
retained record locks, as a result of deferred recovery work by this CICS region, for the specified
data set. CVDA values are:
- NOTAPPLIC
- This data set has not been opened by the CICS region in which the command is issued.
- NORETAINED
- This CICS region:
- Has no deferred recovery work for the base data set, and therefore no retained locks, or
- Has recovery work currently in progress.
- RETAINED
- This CICS region has deferred
recovery work causing retained locks for the data set. One effect
of this is that, if the data set was last opened in RLS mode, the
locks are RLS locks and, therefore, the data set cannot be opened
in non-RLS mode.
Another effect is that any FILE definitions that specify this data set cannot be changed to specify a different data set.
If the data set is a BDAM data set, or a VSAM data set accessed in non-RLS mode, the locks are CICS record locks, otherwise they are RLS record locks. The UOW that has retained locks is usually shunted, but it may be in the process of being retried.
- VALIDITY(cvda)
- Returns a CVDA value identifying whether the data set
name has been validated against the VSAM catalog by opening a file
associated with the data set. CVDA values are:
- INVALID
- The data set name has not been validated (validation has not yet occurred or has failed).
- VALID
- The data set name has been validated.
Conditions
- DSNNOTFOUND
- RESP2 values:
- 1
- The data set cannot be found.
- END
- RESP2 values:
- 2
- There are no more resource definitions of this type.
- ILLOGIC
- RESP2 values:
- 1
- You issued a START command when a browse of this resource type is already in progress, or you issued a NEXT or an END command when a browse of this resource type is not in progress.
- IOERR
- RESP2 values:
- 40
- QUIESCESTATE was specified, but an error was raised by DFSMS/MVS when reading the ICF catalog.
- 48
- The specified operation cannot be completed because the data set is migrated. Recall the data set and reissue the command.
- 49
- An error was raised by DFSMS/MVS when reading the ICF catalog to establish the base data set name.
Note: If an IOERR occurs within a browse it does not terminate the browse operation, and CICS attempts to return as many parameter values as possible. - NOTAUTH
- RESP2 values:
- 100
- The user associated with the issuing task is not authorized to use this command.