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.

In summary, DFH$FCBF performs the following processing:
  • 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.

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.