Retrieve information about UOWs that have updated CICS file control-managed data sets.
The INQUIRE UOWDSNFAIL command can be used only in browse mode.
INQUIRE UOWDSNFAIL >>-INQUIRE UOWDSNFAIL--+-------------+--DSNAME(data-area)-------> '-CAUSE(cvda)-' >--+--------------------+--+--------------+---------------------> '-NETNAME(data-area)-' '-REASON(cvda)-' >--+-----------------+--+------------------+--UOW(data-area)--->< '-RLSACCESS(cvda)-' '-SYSID(data-area)-'
Conditions: END, ILLOGIC, NOTAUTH
This command enables you to inquire on the reasons why UOWs were shunted because of a failure during syncpoint associated with a specified data set. Failures during syncpoint processing result in locks held by the UOW against the data set (or data sets) which suffered the failure being retained. Thus, when a failure is reported by this command, it also indicates the presence of retained locks.
The UOWDSNFAIL command returns UOWs that are shunted and also UOWs that are in the process of being retried. In the latter case, the only data sets returned are those that have not yet been processed as part of the retry.
Note that there may be failures against the data set by other CICS regions. The command needs to be issued on all regions in the sysplex to get a full picture of the state of the data set. See the CICS® Recovery and Restart Guide for information about the CICS batch-enabling sample programs that assist you in doing this, and about the AMS SHCDS LIST subcommands that allow you to investigate retained locks held by CICS regions that are down.
You can use the browse options (START, NEXT, and END) to find all the units of work with syncpoint failures, together with the data sets that have suffered failures. In addition, the reason is given for each unique UOW/data set combination (a UOW can have syncpoint failures for several data sets but, for each data set within the UOW, the cause of the failure is the same). See Browsing resource definitions for general information about browsing, including syntax, exception conditions, and examples.
Because this command returns information about UOWs that are currently failed with respect to data sets (with associated retained locks held against those data sets), it does not return information about failures that are in the process of being retried when the command is issued. For example, if a UOW suffered a backout failure with respect to a particular data set, and a SET DSNAME RETRY command was issued for that data set, that particular UOW/data set combination would not appear in the browse. The backout retry might either be successful, in which case the failure condition will have been cleared, or it might fail again, in which case the UOW/data set combination would appear if a new INQUIRE UOWDSNFAIL browse were started.
One important use of this command is to enable you to write a transaction that helps operators to identify and remove retained locks, so that data sets can be quiesced and used for batch application programs. There are several CICS-supplied sample programs that you can use unmodified, or use as a basis for writing your own programs. See the sample application programs, DFH0BAT1 through DFH0BAT8, for a working illustration of the use of this command. These are supplied in the CICSTS31.CICS.SDFHSAMP library, and are described in the CICS Operations and Utilities Guide.
The INQUIRE UOWDSNFAIL function is in effect a two dimensional, or nested, browse: the first (outer) browse loops through all the UOWs, and within each UOW, the second (inner) browse loops though all the failed datasets associated with that UOW. Note that, in common with all browse functions, CICS does not lock resources during a browse operation. For each failed UOW, CICS obtains a snapshot of all the data sets that are failed for the UOW, and returns one UOW/data set pair for each NEXT operation. It is theoretically possible that the status of some data sets associated with an INQUIRE UOWDSNFAIL NEXT command could have changed by the time the information is returned to your program.
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.
Each REASON (except for NOTAPPLIC) corresponds with only one CAUSE value. The mappings are as follows:
Cause | Reason |
---|---|
CACHE | NOTAPPLIC |
CONNECTION | INDOUBT |
CONNECTION | RRINDOUBT |
DATASET | BACKUPNONBWO |
DATASET | DELEXITERROR |
DATASET | DATASETFULL |
DATASET | DEADLOCK |
DATASET | FAILEDBKOUT |
DATASET | INDEXRECFULL |
DATASET | LCKSTRUCFULL |
DATASET | IOERROR |
DATASET | OPENERROR |
RLSSERVER | COMMITFAIL |
RLSSERVER | RRCOMMITFAIL |
RLSSERVER | RLSGONE |
UNDEFINED | NOTAPPLIC |