Exit XFCBFAIL, file control backout failure exit

Exit XFCBFAIL is invoked whenever there is a failure during backout of an update made to a file record.

If, within a given UOW, there are backout failures for more than one record in the same file, or for records in multiple files, the exit is invoked:

For the first record in each data set for which backout fails.
If more than one file is associated with a single data set, only the first record in the first of the files to fail backout within UOW causes CICS® to invoke the exit. All subsequent records are failed with the same error, but the exit is not invoked again.
For the first record for each data set that fails during any retry of the backout for this UOW.

It is not invoked for backout failures to other (non-file-control) resources within the UOW.

For VSAM data sets, backout failure processing saves information that allows the backout to be retried later.

For BDAM data sets, the backout cannot be retried. If backout fails against a BDAM data set, you can use the XFCBFAIL exit to preserve data integrity by terminating CICS immediately. If the XFCBFAIL exit is not enabled, or does not terminate CICS, the BDAM data is committed and the locks are released. If the exit is enabled, you can use the XFCBFAIL global user exit program to save information that you can use to manually correct the data. However, you need to be careful that in doing this you do not back out other changes made between the time of the backout failure and the time of your own manual recovery action.

When invoked

If an error occurs during backout of a change made to a file (on the first failure in the UOW for the data set associated with the file).

Exit-specific parameters

UEPBLOGR

Address of the file control portion of the log record that represents the update that was being backed out when the file control failure occurred. The log record can be mapped using the DSECT DFHFCLGD.

UEPTRANS

Address of a 4-byte field containing the transaction id under which the update that is being backed out was made.

UEPTRMNL

Address of the 4-byte terminal id for the terminal or principal facility from which the update that is being backed out was made.

UEPTASK

Address of the 4-byte (packed decimal) field containing the task number for the task under which the update that is being backed out was made.

UEPFCRSP

Address of the file control response byte. This can have one of the following values:

UEAIXFUL: No space in non-unique alternate index.
UECACHE: RLS cache failure or cache connectivity failure.
UENBWBAK: Non-BWO backup in progress.
UEDLOCK: Deadlock detected.
UEDUPREC: Duplicate key on unique alternate index.
UEIOEROR: I/O error.
UELCKFUL: RLS lock structure full.
UENOLDEL: Logical delete not carried out (XFCLDEL exit point is either not enabled or the XFCLDEL global user exit program chose not to perform the logical delete).
UENOSPAC: Data set out of storage.
UEOPENER: Error opening the file.
UERLSERR: SMSVSAM RLS server failure.
UERLSDIS: RLS access is currently disabled.
UERLSCON: Attempt to continue a thread with a new instance of the SMSVSAM RLS server.
UEUNEXP: Unexpected error.

UEPERR

Address of a one-byte field containing the error type. The values of the error-byte and their meanings are described in Values of the error-type byte referenced by UEPERR.

Return codes

UERCNORM: Continue processing and invoke CICS backout failure control.
This causes a backout failure error message to be issued (DFHFC4701 for a VSAM data set, and DFHFC4702 for a BDAM data set). For a VSAM data set CICS converts the record lock into a retained lock, and the log record is saved for a later retry of the backout.
UERCBYP: Ignore the error (do not invoke CICS backout failure control) and continue. Setting this return code could be damaging to the integrity of your data.

A return code of UERCPURG is not allowed. There is no need to set a UERCPURG return code, because the conditions under which this exit is invoked mean that a purged condition cannot be returned by any XPI or API calls.

XPI calls

All can be used, but subject to the same caution as for API and SPI calls.

API and SPI calls

Although this exit is allowed to issue API and SPI calls, you should be very careful about which commands you use because the exit is invoked during file backout, which is part of syncpoint phase 2.

It is recommended that you restrict EXEC CICS commands to inquiries, and avoid commands that update CICS resources, because the resources may themselves be in a state of recovery. In particular, the following restrictions apply:

Do not issue any recoverable operations.
Do not use operations that access systems or resource owners external to this CICS, even if the target resource is non-recoverable.
Do not disable or close files, because this could cause further error conditions.
It is possible for this exit to be invoked under a different transaction environment from that under which the updates that are being backed out were originally made. If your exit program wants to perform any actions (such as writing a message to the terminal) that require it to be running under the original transaction environment, it must first check the value returned in the RE_ATTACHED_TRANSACTION parameter of a transaction manager INQUIRE_TRANSACTION XPI call.

Sample global user exit program for XFCBFAIL

DFH$FCBF provides sample processing for the file control backout failure global user exit XFCBFAIL. For more information, see File control recovery sample exit program: DFH$FCBF.