CEMT INQUIRE UOWDSNFAIL

Obtain information about failed units of work that have updated CICS® file-control-managed data sets.

Description

The INQUIRE UOWDSNFAIL command returns information about unit of work (UOW) failures that are associated with specific data sets. If you enter the basic command, CEMT INQUIRE UOWDSNFAIL, without any attributes, all failed UOWs for all data sets are displayed.

If a UOW that had suffered a failure is in the process of being retried when the INQUIRE UOWDSNFAIL command is issued, such a UOW is not listed (it is not currently shunted or failed). If the retry is successful, the UOW no longer has a failure with respect to that particular data set. If the retry is not successful, the UOW will be shunted again, and INQUIRE UOWDSNFAIL will display it as failed with respect to the data set.

Alternatively, if you are interested only in those failed UOWs for specific data sets, you can use the DSNAME parameter as a filter by specifying either a specific or generic data set name. You can also use other attributes as filters, for example, CONNECTION for UOWs that failed indoubt, or DATASET for UOWs that failed during backout. See the list of reasons for UOW failures, and the associated causes, that you can use to filter the results of INQUIRE UOWDSNFAIL commands.

Input

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

Type CEMT INQUIRE UOWDSNFAIL (or suitable abbreviations for the keywords). The resulting display lists all the failed UOWs, if any. Otherwise, CICS returns the NOT FOUND error condition.
Type CEMT INQUIRE UOWDSNFAIL (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 uowd ds(applb.*), the resulting display shows the details of only those failed UOWs that are associated with data sets with a high-level qualifier of APPLB.

Sample screen

Figure 1. CEMT INQUIRE UOWDSNFAIL screen

  INQ UOWDSN
  STATUS:  RESULTS
   Dsn(RLS.ACCOUNTS.ESDS.DBASE1                    ) Dat Del
      Uow(AA6DB080C40CEE01)                         Rls
   Dsn(RLS.ACCOUNTS.ESDS.DBASE1                    ) Dat Ind
      Uow(AA6DB08AC66B4000)                         Rls

Sample screen

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.

If you place the cursor against a specific entry in the list and press ENTER, CICS displays an expanded format, as shown in Figure 2.

Figure 2. The expanded display of an individual entry

 INQ UOWDSN
 RESULT
   Uowdsnfail
   Dsname(RLS.ACCOUNTS.ESDS.DBASE1)
   Cause(Dataset)
   Reason(Delexiterror)
   Uow(AA6DB080C40CEE01)
   Sysid()
   Netname()
   Rlsaccess(Rls)

CEMT INQUIRE UOWDSNFAIL

Displayed fields

CAUSE

Displays which failed component has caused the UOW to have retained locks for this data set. The values are as follows:

CACHE: A cache structure, or connection to it, has failed.
CONNECTION: There is an intersystem connection error, which has caused the UOW to fail while indoubt. The name of the system to which connectivity was lost is returned on the SYSID parameter and its netname is returned on the NETNAME parameter. CICS returns additional information in the REASON parameter about the CONNECTION failure.
DATASET: The backout of a UOW has failed for this data set. The reason for the data set failure is returned in the REASON parameter.
RLSSERVER: The SMSVSAM server has failed. The reason for the data set failure is returned in the REASON parameter.
UNDEFINED: The UOW is probably in-flight following an emergency restart.

DSNAME (value)

Displays the 44-character data set name of a data set that has retained locks for this UOW.

NETNAME (value)

Displays the 8-character netname (when the cause is CONNECTION) of the remote system to which connectivity has been lost.

REASON

Displays, when the cause is RLSSERVER, CONNECTION, or DATASET, the specific reason for the error against this data set. The values are as follows:

BACKUPNONBWO: A non-BWO backup was in progress while the UOW was being backed out. When the backup completes, CICS automatically retries the UOW.
COMMITFAIL: An error occurred at some point when the locks were in the process of being released. This is an error that can normally be resolved by recycling the server (which should happen automatically). The locks were acquired as a result of recoverable requests having been issued against the data set.
DATASETFULL: No space is available on the direct access device for adding records to a data set. You need to reallocate the data set with more space. You can then retry the backout using SET DSNAME RETRY.
See Moving recoverable data sets that have retained locks.
DEADLOCK (non-rls data sets only): A deadlock was detected. This may go away if the UOW is retried.
DELEXITERROR: Backout of a write to an ESDS failed because a logical delete global user exit program was not enabled, or a logical delete global user exit program decided not to execute the logical delete.
FAILEDBKOUT: This occurs as a result of a severe error being identified, and is possibly an error in either CICS or VSAM. The problem may go away if the UOW is retried. Note that CICS performs some first-failure data capture (FFDC) at the point where the error is first detected.
INDEXRECFULL: A larger alternate index record size needs to be defined for the data set. See Moving recoverable data sets that have retained locks.
This error can also occur when a unique alternate index key, for a non-RLS data set, has been reused and CICS is now backing out the request which had removed that key value.
INDOUBT: The unit of work had issued recoverable requests against the data set, and has now failed indoubt. The connection to the coordinating system needs to be reestablished.
IOERROR: A hard I/O error occurred. To correct this error, restore a full backup copy of the data set and perform forward recovery. If you use CICS VSAM Recovery as your forward recovery utility, the backout is automatically retried for an RLS data set. For a non-RLS data set, use the RETRY option of the SET DSNAME command to drive the backout retry.
LCKSTRUCFULL: An attempt to acquire a lock during backout of an update to this data set failed because the RLS lock structure was full. You must allocate a larger lock structure in an available coupling facility and rebuild the existing lock structure into it, then use the SET DSNAME (...) RETRY command to drive the backout retry.
NOTAPPLIC: The value for CAUSE is not CONNECTION, RLSSERVER, or DATASET.
OPENERROR: Error on opening the file for backout. A console message notifies you of the reason for the open error. One likely reason could be that the data set was quiesced.
RLSGONE: An error occurred when backing out the UOW because the RLS server is unavailable. This might also be the reason why the UOW went into backout originally. This is an error that can be resolved by recycling the server (which should happen automatically). Generally, when the server recovers, the UOWs are retried automatically. In very exceptional circumstances, it may be necessary to issue a SET DSNAME(…) RETRY command to retry UOWs that were not retried when the server returned.
RRCOMMITFAIL: An error occurred while RLS locks for the unit of work were being released. For this data set, the locks being released were all repeatable read locks so, if the failure was due to the RLS server being unavailable, the locks will have been released. If the failure was due to some other error from the SMSVSAM server, the locks may still be held.
RRINDOUBT: The unit of work had issued repeatable read requests against the data set, and has now failed indoubt. The locks will have been released, so this failure does not prevent you from running a batch job against the data set. However, if you want to open the data set in non-RLS mode from CICS, you need to resolve the indoubt failure before you can define the file as having RLSACCESS(NO). If the unit of work has updated any other data sets, or any other resources, you should try to resolve the indoubt correctly. If the unit of work has only performed repeatable reads against VSAM data sets and has made no updates to other resources, it is safe to force the unit of work using the SET DSNAME or SET UOW commands.

Each Reason corresponds to only one Cause value, as shown in the following table:

Cause	Reason
CACHE	NOTAPPLIC
CONNECTION	INDOUBT
CONNECTION	RRINDOUBT
DATASET	BACKUPNONBWO
DATASET	DELEXITERROR
DATASET	DATASETFULL
DATASET	DEADLOCK
DATASET	FAILEDBKOUT
DATASET	INDEXRECFULL
DATASET	IOERROR
DATASET	LCKSTRUCFULL
DATASET	OPENERROR
RLSSERVER	COMMITFAIL
RLSSERVER	RLSGONE
RLSSERVER	RRCOMMITFAIL
UNDEFINED	Not applicable

RLSACCESS

Displays whether the data set was last opened in this CICS region in RLS or non-RLS mode. The values are as follows:

RLS: The last open in this CICS region was in RLS mode.
NOTRLS: The last open in this CICS region was in non-RLS mode.

SYSID(value)

Displays the 4-character SYSID (when the cause is CONNECTION) of the remote system to which connectivity has been lost.

UOW (value)

Displays the 16-character local identifier of the associated unit of work.

UOWDSNFAIL

Indicates that this panel relates to an inquiry about the cause of a UOW failure.