File control recovery sample exit program: DFH$FCBF
DFH$FCBF is a sample exit program that is designed to be invoked at the XFCBAIL exit for handling backout failures.
About DFH$FCBF
DFH$FCBF provides sample processing for the file control backout failure global user exit, XFCBFAIL. The exit program, if enabled at the XFCBFAIL exit point, is invoked if an error occurs during backout of a file control update.
There is more information about using the XFCBFAIL user exit, and the sample program, in the comments within the DFH$FCBF source code. The comments also include some suggested extensions to the sample program.
- If tracing is active for file control, makes a user trace entry.
This has trace point id
X'01D0'
and traces:- An eye-catcher ‘DFH$FCBF ENTRY'
- The file control response byte
- The error type
- The file control portion of the log record.
- Issues an EXEC CICS INQUIRE FILE command to check the access method to see if the data set is BDAM. If it is, CICS® does not support backout retries. Therefore, a message is written to the console advising that either this file and any other files using the base data set (named in message DFHFC4702) should be closed, or CICS should be shut down to prevent further corruption. Sets a response of UERCNORM and takes the normal exit from the program.
- If the access method is neither BDAM nor VSAM, takes the error exit from the program.
- Checks whether the file is one for which it has been decided that
backout failures will be ignored, by checking the filename (field
FLJB_FILE_NAME in the log record). The sample program writes a message
to the console to this effect, then sets a response of UERCBYP and
takes the normal exit from the program. A return code of UERCBYP specifies
that the error should be ignored. This causes CICS not
to retry the backout; the result is as if the data were committed
instead of being backed out.
The sample program takes this step to demonstrate the use of the UERCBYP return code. It is not recommended that you use UERCBYP with important data sets.
- Examines the file control response code and issues a message to the console describing the procedure to be followed for this error. The sample program provides slots for each possible file control response code, and includes suggested messages for some of them. The sample program should be customized by expanding the set of messages to describe procedures that are appropriate for your installation for each error, or to take other action within the exit program. If you do not add a message for any particular response code, the operator still sees message DFHFC4701, which advises on any action that needs to be taken. This is issued as part of CICS backout failure processing.
- Sets a response code of UERCNORM and takes the normal exit from the program. A return code of UERCNORM specifies that CICS backout failure processing is to be carried out. This means that CICS issues a backout failure error message and, for a VSAM data set, ensures that the record remains locked until the backout can be retried and saves the log record for later retry.
- Normal exit from the program writes a user trace entry if tracing
is active for file control and there were no errors during processing.
This has trace point id X'01D1' and traces:
- An eye-catcher ‘DFH$FCBF EXIT OK'
- The file control portion of the log record
- Some text: ‘Handle backout failure' or ‘Bypass backout failure' as appropriate.
- Error exit from the program (taken if errors occur during processing
or if CICS functions fail):
- Writes a user exception trace entry regardless of the trace setting.
This has trace point id X'01D2' and traces:
- An eye-catcher ‘USEREXC'
- An eye-catcher ‘DFH$FCBF EXIT FAIL'
- The file control portion of the log record.
- Returns a response of UERCNORM so that, although an error has occurred in the exit, CICS still performs its normal backout failure processing.
- Writes a user exception trace entry regardless of the trace setting.
This has trace point id X'01D2' and traces:
Setting up DFH$FCBF
To define file control recovery sample exit programs including DFH$FCBF, specify the supplied resource group DFH$FCB in your startup grouplist, or use CEDA to install DFH$FCB.