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, or whether full access to
the data set is restricted to REPLICATOR programs. 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.
- RREPL
- Full access to the data set is restricted to programs that are defined as REPLICATION(REPLICATOR). Other programs have only read access.
- 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)
- Returns
the name (up to 26 characters) of the log stream that is used to log
the updates if this is a data set defined with forward-recovery attributes
or replication logging. CICS returns
blanks if the data set is not forward recoverable and not using replication
logging. The log stream name returned is either:
- The log stream name specified directly in the ICF catalog for forward recovery or replication logging
- For a non-RLS access mode data set that does not have forward recovery attributes in the ICF catalog, it is a log stream name identified by CICS through a journal name generated from the FWDRECOVLOG value.
- 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.