INQUIRE UOWDSNFAIL

Description

The INQUIRE UOWDSNFAIL command is for use only in browse mode. You can use this command to inquire on the reasons why UOWs were shunted because of a failure during syncpoint associated with a specified data set. If there are failures during syncpoint processing, the locks that the UOW holds against one or more data sets that experienced the failure are retained. Thus, when this command reports a failure, 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.

There can be failures against the data set by other CICS regions. To get a full picture of the state of the data set, the command must be issued on all regions in the sysplex. See Batch-enabling sample programs for RLS access-mode data sets (DFH0BATx) for information about the CICS batch-enabling sample programs that assist you in doing this, and about the AMS SHCDS LIST subcommands that you can use to investigate retained locks held by CICS regions that are down.

Browsing

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 experienced 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 experienced 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 CICSTS52.CICS.SDFHSAMP library.

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 data sets 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.

Options

CAUSE(cvda)

Returns a CVDA value that indicates which failed component has caused the UOW to have retained locks for this data set. CVDA values are as follows:

CACHE

A VSAM RLS cache structure, or a connection to it, has failed.

CONNECTION

An intersystem connection error 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 being retried. This can occur following a SET DSN RETRY command, or automatically when the failed resource returns. It can also occur following an emergency restart.

DSNAME(data-area)

Returns, as a 44-character value, the data set name of a data set that has experienced a backout failure in this UOW.

NETNAME(data-area)

Returns the 8-character netname (when the CVDA on the CAUSE parameter is CONNECTION) of the remote system to which connectivity has been lost.

REASON(cvda)

Returns a CVDA value (when the CVDA returned on the CAUSE parameter is RLSSERVER, CONNECTION, or DATASET) that indicates the specific reason for the error against this data set. CVDA values are as follows:

BACKUPNONBWO

Backout of the updates made to the data set by the UOW failed because a non-BWO backup of the data set 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 RLS locks were in the process of being released. This is an error that can normally be resolved by recycling the SMSVSAM 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..

DEADLOCK (non-RLS data sets only)

A deadlock was detected during backout. This is a transient condition that will probably go away if the backout 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 during backout, and is possibly an error in either CICS or VSAM. The problem may go away if the backout 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..

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 during backout. 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 SET DSNAME (…) RETRY 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 CVDA 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 SMSVSAM RLS server was inactive. This may 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 with an indoubt condition. 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 failure 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 (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

RLSACCESS(cvda)

Returns a CVDA value that indicates whether the data set was last opened in this CICS region in RLS or non-RLS mode. CVDA values are as follows:

NOTRLS

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

RLS

The last open in this CICS region was in RLS mode.

SYSID(data-area)

Returns the 4-character sysid (when the CVDA on the CAUSE parameter is CONNECTION) of the remote system to which connectivity has been lost.

UOW(data-area)

Returns the 16-byte UOW identifier of a shunted unit of work that has one or more data sets with retained locks. The last eight bytes are always null   (X'00').

Conditions

END

RESP2 values:

2

There are no more UOW/data set pairs.

ILLOGIC

RESP2 values:

1

A START has been given when a browse is already in progress, or a NEXT has been given without a preceding START.

NOTAUTH

RESP2 values:

100

The use of this command is not authorized.