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.

Note: CEMT has to retrieve QUIESCESTATE information from the ICF catalog. This can slow down processing of this command. QUIESCESTATE is not supplied by default but is retrieved and displayed if requested.

Input

Press the Clear key to clear the screen. You can start this transaction in two ways:

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 enter cemt 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.

You can tab to the highlighted or blank fields and overtype them with the required values.

ALL: The default.
(value): Specifies one or more names (1 - 44 characters) of an external data set.

Sample screen

Figure 1. CEMT INQUIRE DSNAME screen

 IN DSN
 STATUS:  RESULTS - OVERTYPE TO MODIFY
  Dsn(CICSTS52.CICS.CICSH###.DFHCSD                     ) Vsa
     Fil(0001) Val Bas     Sta         Ava
  Dsn(CICSTS52.CICS.CICSHT61.FILEA                      ) Vsa
     Fil(0001) Val Bas     Sta         Ava

Note: When a value does not apply, or is negative (the value begins with No), the fields on the screen are blank. To modify these fields, locate them by tabbing (they appear in the same sequence as in the expanded format), and overtype with input valid for that field. You might find it more convenient to use the expanded format when setting one of these values.

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:

Figure 2. The expanded display of an individual entry

IN DSN
RESULT - OVERTYPE TO MODIFY
  Dsname(CICSTS52.CICS.CICSH###.DFHCSD)
  Accessmethod(Vsam)
  Action(              )
  Filecount(0001)
  Validity(Valid)
  Object(Base)
  Recovstatus(Notrecovable)
  Backuptype(Static)
  Frlog()
  Logrepstatus()
  Availability( Available )
  Lostlocks()
  Retlocks(Noretained)
  Uowaction(              )
  Basedsname(CICSTS52.CICS.CICSH###.DFHCSD)
  Quiescestate( Unquiesced )
  Fwdrecovlsn()

CEMT INQUIRE DSNAME

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.

If you have a base data set with one or more alternate indexes, you cannot remove the data set name block for the base until you have removed all references to the base data set and all references to paths.

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. 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.
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) program product.
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.