Retrieve information about an external data set.
INQUIRE DSNAME .----------------------------. V | >>-INQUIRE DSNAME(data-value)----+------------------------+-+-->< +-ACCESSMETHOD(cvda)-----+ +-AVAILABILITY(cvda)-----+ +-BACKUPTYPE(cvda)-------+ +-BASEDSNAME(data-area)--+ +-FILECOUNT(data-area)---+ +-FWDRECOVLOG(data-area)-+ +-FWDRECOVLSN(data-area)-+ +-OBJECT(cvda)-----------+ +-LOSTLOCKS(cvda)--------+ +-QUIESCESTATE(cvda)-----+ +-RECOVSTATUS(cvda)------+ +-RETLOCKS(cvda)---------+ '-VALIDITY(cvda)---------'
Conditions: DSNNOTFOUND, END, ILLOGIC, IOERR, NOTAUTH
For more information about the use of CVDAs, see CICS-value data areas (CVDAs).
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 option 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 has been opened by the CICS region in which the command is issued. Where an attribute is not valid until a file has been opened, the NOTAPPLIC state is returned.
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.
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.
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.
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.
FWDRECOVLOG is undefined if the data set is not forward-recoverable. A data set can be defined as being forward recoverable in the ICF catalog or, if it is accessed in non-RLS mode, in the file definition.
This option is valid for data sets accessed only in non-RLS mode, and for which the recovery attributes are obtained from the file resource definition.
CICS returns a value of zero for forward-recoverable data sets accessed in RLS mode, or for non-RLS mode data sets for which CICS obtains the recovery attribute from the ICF catalog.
The log stream name returned is either:
See the RESETLOCKS and the FORCE|COMMIT|BACKOUT options on the EXEC CICS SET DSNAME command for information about purging UOWs that might be holding up lost locks recovery.
CVDA values are:
NOTAPPLIC is also returned if CICS is running without RLS support (the RLS=NO system initialization parameter is specified or implied).
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.
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.