CEMT INQUIRE DSNAME
Retrieve information about an external data set.
Description
The INQUIRE DSNAME command returns information about the status of a data set managed by CICS® file control. The data set name is either the name specified on the DSN parameter of the DD statement of the data set, or the DSNAME attribute of the FILE resource definition of the data set. You can use this command to monitor failing VSAM data sets. Many of the attributes cannot be determined until a file that references the data set has been opened. If this has not happened, blank values are returned for most attributes.
Input
- Type
CEMT INQUIRE DSNAME
(or suitable abbreviations for the keywords). The resulting display the current status except for the QUIESCESTATE value. To retrieve the QUIESCESTATE value, place the cursor at the beginning of the displayed item (in front of the Dsn field) and press the Enter key. - Type
CEMT INQUIRE DSNAME
(or suitable abbreviations for the keywords), followed by the attributes that are necessary to limit the range of information that you require. For example, if you entercemt i dsn vs not
, the resulting display shows the details of only those external data sets that are VSAM data sets and are not recoverable.
- ALL
- The default.
- (value)
- Specifies one or more names (1 - 44 characters) of an external data set.
Sample screen for CEMT INQUIRE DSNAME (using CICS TS 6.2)
Because of the large number of keywords supported for this command, only two lines of information for each result are displayed. The full set of keywords can be displayed by moving the cursor to the beginning of a displayed item (in front of the Dsn field) and pressing the Enter key. The resulting display shows all the keyword information for the displayed item, as follows:
Displayed fields
- ACCESSMETHOD
- Displays
the access method of the data set. The values are as follows:
- VSAM
- Virtual storage access method (VSAM).
- BDAM
- Basic direct access method (BDAM).
- ACTION (input only field)
- Specifies
the action to take on this data set. The values are as follows:
- REMOVE
- Use
this option when a data set is no longer required on the local system.
It deletes the data set name block for the named data set. The REMOVE
option can be used only when there are no file control resource definition
entries that refer to the specified data set. If any file definitions
refer to the data set name when you enter SET DSNAME REMOVE, you receive
an error message indicating that the use count of the data set name
block is not zero. Use the following procedure to ensure that no file
definitions refer to the data set name:
- Close all files that refer to the data set. You can use the following
command to find these files:
CEMT INQUIRE FILE(*) DSNAME(dsname)
- Either remove the data set name from each file entry (by over-typing the data set name with blanks on the CEMT display), or discard the file definition entirely.
- Close all files that refer to the data set. You can use the following
command to find these files:
- RECOVERED
- The
data set has been restored from a backup version and forward recovery
has run and completed successfully. CICS normally updates the backup-while-open (BWO) attributes for the base cluster data set BASEDSNAME, using MVS™/DFP 3.2 Callable Services.
If the BWO attributes are not updated after the restore of a backup copy of a data set that was taken using BWO, CICS fails a subsequent file open because the data set is marked as down-level.
- RESETLOCKS (VSAM only)
- Purges
shunted unit of work (UOW) log records for backout-failed and commit-failed
UOWs that hold locks on this data set, and releases the retained locks:
- Backout-failed UOWs are those that failed during backout processing.
- Commit-failed UOWs are those that have updated record-level sharing (RLS) data sets, and have failed to release locks during the second phase of 2-phase commit syncpoint processing.
Use this option only as a last resort, because you are accepting backout failure and some loss of data integrity as an alternative to retaining locks and delaying transactions.
For backout-failed and commit-failed UOWs that hold locks on the data set, all records relating to this data set are removed from the system log and all retained record locks held by this CICS for the data set are released. Diagnostic messages are written to the CSFL transient data queue for each backout-failed log record that is removed as a result of the RESETLOCKS operation.
The RESETLOCKS option applies only to shunted UOW log records that are classed as backout-failed and commit-failed. Therefore it cannot be issued for a BDAM data set. Backout-failed and commit-failed log records are not shunted for BDAM data sets.
You might use RESETLOCKS if backout-failed or commit-failed log records are holding up lost locks recovery for the data set, and there is no other way to resolve them.Note:- This option does not apply to shunted indoubt UOWs. Try to resolve the shunted indoubt UOWs that hold locks on the data set in other ways before issuing RESETLOCKS; for example, by using COMMIT, BACKOUT, or FORCE (see the CEMT SET DSNAME command for information about these options).
- RESETLOCKS can fail during the commit phase (for example, if an error occurs while CICS is trying to release the RLS locks), in which case the UOWs revert to being shunted as commit-failed UOWs.
- RETRY
- Specifies
that shunted UOW log records, caused by failed backout and commit
processing as a result of the failure of this data set, should be
retried. This is similar in operation to the EXEC CICS RESYNC command,
but applies only to backout-failed and commit-failed UOWs, and not
to indoubt UOWs.
Use RETRY when the data set has shunted backout- or commit-failed UOWs associated with it, and you believe that some or all of the data set problems are either transient or have been resolved.
Messages, issued at the time of a data set failure that causes UOWs to be shunted, recommend the actions that are required to recover from the failure.
RETRY does not affect data integrity, and can be used safely at any time to enable some failed recovery work to complete.
- AVAILABILITY
- Displays information 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. If the file is a BDAM data set, no information is returned. The
values are as follows:
- AVAILABLE
- The data set is
available for use according to the CICS data set name block.
CICS can issue either RLS or non-RLS open requests for this
data set. Note: Although a data set is available according to information held by CICS, an open request could still fail if the ICF catalog indicates otherwise. This can occur, for example, if data set recovery is pending or in progress.
- RREPL
- Full access to the data set is restricted to programs that are defined as REPLICATION(REPLICATOR). Other programs have only read access.
- UNAVAILABLE
- The data set is marked by CICS as not available for use. The CICS region is unable to open the data set in either RLS or non-RLS mode.
AVAILABILITY can be reset by specifying AVAILABLE.
- BACKUPTYPE
- Displays
the backup type of the data set. The values are as follows:
- STATIC
- The data set is accessed in non-RLS mode and is not eligible for BWO processing. All the files in this data set must be closed and the data set serialized by a backup manager such as DFSMS/MVS before a data set backup copy can be made.
- DYNAMIC
- The data set is accessed in RLS mode and is eligible for BWO processing. Data set backup is allowed while it is open for output, using a data set backup manager such as DFSMShsm or DFSMSdss. Hierarchical storage manager (DFSMShsm) and data set services (DFSMSdss), which perform data set backup and recovery operations, are components of IBM® Data Facility Storage Management Subsystem (DFSMS/MVS) licensed program.
- UNDETERMINED
- 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. NOTAPPLIC is also returned if the data set has been opened in RLS mode. The VSAM catalog should be referred to get the BWO status.
- BASEDSNAME (value) (VSAM ONLY)
- When
PATH is displayed as well, this is the name of the base data set with
which this path is associated.
When BASE is displayed as well, this is the same as the name shown in the Dsn(value) field.
- DSNAME (value)
- Indicates that this panel relates to an external data set inquiry and displays the 44-character name of an external data set.
- FILECOUNT (value)
- Displays
information about how many different files are currently associated
with this data set. You can associate a file with a data set by a
job control DD statement, or dynamically by a DSNAME parameter on
the file definition. If a file has been associated by a job control
DD statement, the file name cannot be changed by a CEDA command, CEMT,
or an EXEC CICS SET FILE DSNAME command.
FILECOUNT does not show how many files are open against the data set; it only shows how many files are associated with the data set. If a file is associated with a data set and is then closed and associated with a different data set, the FILECOUNT of the first data set decreases by 1, and the FILECOUNT of the second data set increases by 1.
- FRLOG (value)
- Displays
the numeric journal identifier of the journal being used to log the
updates for forward recovery if this data set is forward recoverable
(FWDRECOVABLE). The FRLOG value is undefined if the data set is not
forward recoverable. You can define a data set as forward recoverable
either in the ICF catalog or, if it is accessed in non-RLS mode, in
the file resource definition. This option is meaningful only for data
sets accessed in LSR or NSR mode, and for which the forward recovery
attributes are obtained from the CICS file
resource definition.
For data sets accessed in RLS mode, or non-RLS mode data sets for which CICS obtains the recovery attributes from the ICF catalog, CICS displays a value of zero.
- FWDRECOVLSN (value)
- Displays
the name 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 nulls
if the data set is not forward recoverable and is not using replication
logging. The log stream name returned is either of the following:
- 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, a log stream name identified by CICS through a journal name generated from the FWDRECOVLOG value.
- LOGREPSTATUS (cvda)
- Returns
a CVDA value that identifies whether the data set was defined with
LOGREPLICATE. Valid values are as follows:
- 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
- Displays
whether there are any lost locks for this data set. The possible values
displayed are as follows:
- NOLOSTLOCKS
- The data set has no lost locks.
- REMLOSTLOCKS
- The data set has lost locks, therefore is unavailable, but no recovery is required on this CICS system. The lost locks belong to a another (remote) CICS region.
- RECOVERLOCKS
- The data set has lost locks and therefore is unavailable. This CICS system is performing lost-locks recovery.
- OBJECT
- Displays
the type of the data set. The values are as follows:
- PATH (VSAM only)
- This data set is a path leading to another data set.
- BASE
- The named data set is a base data set, rather than a path data set.
- QUIESCESTATE
- Displays
the RLS quiesce state of the data set. The information is obtained
from the ICF catalog entry for the data set. The values displayed
are as follows:
- QUIESCED
- A data set has been quiesced. It means that RLS access method control blocks (ACBs) cannot open against the data set and no CICS region has an RLS ACB currently open against this data set. However, the data set can be opened in non-RLS mode.
- UNQUIESCED
- This is the normal value for a data set that is not quiescing or has not been quiesced. It indicates that RLS or non-RLS ACBs can be opened against the data set, the mode being established by the first open. After an ACB is opened in one mode, other ACBs can be opened only in the same mode.
If a data set is quiescing because a SET DSNAME QUIESCE command was issued in the same region as the CEMT I DSN command, the words
BEING QUIESCED
are displayed.If a data set is quiescing, the words
BEING QUIESCED
are displayed for the CICS region in which the command was issued.If quiesce does not apply (for example, for a BDAM data set), nothing is displayed.
Quiescestate can be reset by specifying Quiesced|Unquiesced or:- IMMQUIESCED
- Causes all existing CICS open RLS ACBs throughout the sysplex to be closed and the data set to be marked as quiesced in the ICF catalog. Each CICS in the sysplex abends all in-flight UOWs that are accessing the data set before closing ACBs, causing in-flight UOWs to back out. Any OUWs that fail backout are shunted. No RLS ACBs can open against this data set, but non-RLS open requests are permitted.
- RECOVSTATUS
- Displays
the recovery status of the data set. The values are as follows:
- FWDRECOVABLE
- All updates to the data set are logged for both backout and forward recovery.
- 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 or EXEC CICS SET DSNAME REMOVE command, or by an initial or cold start of CICS (if the associated data set is not in backout-failed state). 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 of the data set is not known because files accessing the data set have not been opened for output.
- RETLOCKS
- Displays
whether there are any retained record locks, as a result of deferred
recovery work by this CICS region,
for the specified data set.
- 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.
- NORETAINED
- This CICS region has no deferred recovery
work for the base data set, and therefore no retained locks. Note: NORETAINED can also mean that the CICS region is currently processing deferred recovery work. When the recovery work is successfully completed, the value remains as NORETAINED until more deferred work is created. If the recovery work is not successfully completed, the value reverts to RETAINED.
- UOWACTION (input only field)
- Specifies
the action to take for all shunted units of work that reference this
data set. The values are as follows:
- BACKOUT
- Specifies that all shunted indoubt units of work that hold locks on the data set should be backed out.
- COMMIT
- Specifies that all shunted indoubt units of work that hold locks on the data set should be committed. Specifies that all shunted indoubt units of work that hold locks on the data set should be forced to BACKOUT or COMMIT, as specified by the ACTION attribute on the transaction resource definition.
- VALIDITY
- Displays
the validity of the data set name. The values are as follows:
- VALID
- The data set name has been validated against the VSAM catalog by opening a file against that data set.
- INVALID
- The data set name has not been validated against the VSAM catalog by opening a file against that data set.