Possible reasons for VSAM backout failure
There are many reasons why back out can fail, and these are described in this topic. In general, each of these descriptions corresponds with a REASON returned on an INQUIRE UOWDSNFAIL command.
- I/O error
- You must take the data set offline to repair it, but there may
be occasions when the problem is localized and use of the data set
can continue until it is convenient to carry out the repair. Message DFHFC4701 with a failure code of X'24' indicates that an I/O error (a physical media error) has occurred while backing out a VSAM data set. This indicates that there is some problem with the data set, but it might be that the problem is localized. A better indication of the state of a data set is given by message DFHFC0157 (followed by DFHFC0158), which CICS® issues whenever an I/O error occurs (not just during backout). Depending on the data set concerned, and other factors, your policy might be to repair the data set:
- After a few I/O errors
- After the first backout failure
- After a number of I/O errors that you consider to be significant
- After a significant number of backout failures
- Not at all
It might be worth initially deciding to leave a data set online for some time after a backout failure, to evaluate the level of impact the failures have on users.
To recover from a media failure, re-create the data set by applying forward recovery logs to the latest backup. The steps you take depend on whether the data set is opened in RLS or non-RLS mode:- For data sets opened in non-RLS mode, set the data set offline
to all CICS applications by closing all open files
against the data set.
Perform forward recovery using a forward recovery utility.
When the new data set is ready, use the CEMT (or EXEC CICS) SET DSNAME RETRY command to drive backout retry against the data set for all the units of work in backout-failed state.
- For data sets opened in RLS mode, use the CEMT (or EXEC CICS)
SET DSNAME QUIESCED command to quiesce the data set.
Perform forward recovery using CICS VSAM Recovery for z/OS® as your forward recovery utility.
CICS regions are notified through the quiesce protocols when CICS VSAM Recovery for z/OS has completed the forward recovery. This causes backout to be automatically retried. The backout retry fails at this attempt because the data set is still quiesced, and the UOWs are again shunted as backout-failed.
Unquiesce the data set as soon as you know that forward recovery is complete. Completion of the unquiesce is notified to the CICS regions, which causes backout to be automatically retried again, and this time it should succeed.
This mechanism, in which the backout retry is performed within CICS, supersedes the batch backout facility supported by releases of CICS VSAM Recovery for z/OS earlier than CICS VSAM Recovery for z/OS 2.3. You do not need a batch backout utility.
- Logical delete not performed
- This error occurs if, during backout of a write to an ESDS, the
XFCLDEL logical delete exit was either not enabled, or requested that
the backout be handled as a backout failure.
You can correct this by enabling a suitable exit program and manually retrying the backout. There is no need to take the data set offline.
- Open error
- Investigate the cause of any error that occurs in a file open
operation. A data set is normally already open during dynamic backout,
so an open error should occur only during backout processing if the
backout is being retried, or is being carried out following an emergency restart.
Some possible causes are:
- The data set has been quiesced, in which case the backout is automatically retried when the data set is unquiesced.
- It is not possible to open the data set in RLS mode because the SMSVSAM server is not available, in which case the backout is automatically retried when the SMSVSAM server becomes available.
For other cases, manually retry the backout after the cause of the problem has been resolved. There is no need to take the data set offline.
- SMSVSAM server failure
- This error can occur only for VSAM data sets opened in RLS access
mode. The failure of the SMSVSAM server might be detected by the backout
request, in which case CICS file control starts to close
the failed SMSVSAM control ACB and issues a console message. If the
failure has already been detected by some other (earlier) request, CICS has
already started to close the SMSVSAM control ACB when the backout
request fails.
The backout is normally retried automatically when the SMSVSAM server becomes available. (See Dynamic RLS restart.) There is no need to take the data set offline.
- SMSVSAM server recycle during backout
- This error can occur only for VSAM data sets opened in RLS access
mode.
This is an unlikely cause of a backout failure. CICS issues message DFHFC4701 with failure code X'C2'. Retry the backout manually: there is no need to take the data set offline.
- Coupling facility cache structure failure
- This error can occur only for VSAM data sets opened in RLS access
mode. The cache structure to which the data set is bound has failed,
and VSAM has been unable to rebuild the cache, or to re-bind the data
set to an alternative cache.
The backout is retried automatically when a cache becomes available again. (See Cache failure support.) There is no need to take the data set offline.
- DFSMSdss non-BWO backup in progress
- This error can occur only for VSAM data sets opened in RLS access
mode.
DFSMSdss uses the VSAM quiesce protocols when taking non-BWO backups of data sets that are open in RLS mode. While a non-BWO backup is in progress, the data set does not need to be closed, but updates to the data set are not allowed. This error means that the backout request was rejected because it was issued while a non-BWO backup was in progress.
The backout is retried automatically when the non-BWO backup completes.
- Data set full
- The data set ran out of storage during backout processing.
Take the data set offline to reallocate it with more space. (See Moving recoverable data sets that have retained locks for information about preserving retained locks in this situation.) You can then retry the backout manually, using the CEMT, or EXEC CICS, SET DSNAME(…) RETRY command.
- Non-unique alternate index full
- Take the data set offline to rebuild the data set with a larger record size for the alternate index. (See Moving recoverable data sets that have retained locks for information about preserving retained locks in this situation.) You can then retry the backout manually, using the CEMT, or EXEC CICS, SET DSNAME(…) RETRY command.
- Deadlock detected
- This error can occur only for VSAM data sets opened in non-RLS
access mode.
This is a transient condition, and a manual retry should enable backout to complete successfully. There is no need to take the data set offline.
- Duplicate key error
- The backout involved adding a duplicate key value to a unique
alternate index. This error can occur only for VSAM data sets opened
in non-RLS access mode.
This situation can be resolved only by deleting the rival record with the duplicate key value.
- Lock structure full error
- The backout required VSAM to acquire a lock for internal processing,
but it was unable to do so because the RLS lock structure was full.
This error can occur only for VSAM data sets opened in RLS access
mode.
To resolve the situation, you must allocate a larger lock structure in an available coupling facility, and rebuild the existing lock structure into the new one. The failed backout can then be retried using SET DSNAME RETRY.
- None of the previous errors
- If any other error occurs, it indicates a possible error in CICS or
VSAM code, or a storage overwrite in the CICS region.
Diagnostic information is given in message DFHFC4700, and a system
dump is provided.
If the problem is only transient, a manual retry of the backout should succeed.