File control recovery program exits XFCBFAIL, XFCBOUT, XFCBOVER, and XFCLDEL

CICS® provides four global user exits that you can use in connection with file control recovery operations. These are:

XFCBFAIL
Invoked when an error occurs during backout.
XFCBOUT
Invoked when CICS is about to back out a file update.
XFCBOVER
Invoked when CICS is about to skip unit-of-work (UOW) backout because a batch program has overridden RLS retained lock protection and opened a data set for batch processing.
XFCLDEL
Invoked when backing out a write to a BDAM or a VSAM ESDS data set.

Order of invocation

Each of the exits in the file control recovery program may or may not be invoked during an attempt to backout a file update. If the backout fails, each may (or may not) be reinvoked when the backout is retried. If an exit program needs to know whether it is being invoked during the original backout attempt, or during a retry, it can check the value of the RE_ATTACHED_TRANSACTION field returned by an XPI INQUIRE_TRANSACTION call.

The way in which the exits interact, and the order in which they are invoked, is shown in the following list. Assuming that all the exits are enabled, for each backout attempt or retried backout attempt:

  1. If an open during backout fails, XFCBFAIL is invoked. None of the other exits is invoked.
  2. If the SHCDS PERMITNONRLSUPDATE command has been issued for the data set being backed out, XFCBOVER is invoked. If it returns UERCNORM (do not perform the backout), no further exits are invoked.
  3. Unless item 1 applies, or XFCBOVER has been invoked and returned UERCNORM, XFCBOUT is invoked.
  4. Backout issues a read update request for the record being backed out.

    If the read update fails, XFCBFAIL is invoked, followed by no further exits.

  5. If the update to be backed out was a write to a data set which does not support physical deletes (that is, a BDAM data set or a VSAM ESDS), XFCLDEL is invoked.
  6. If a failure occurs after this point, XFCBFAIL is invoked.
Start of change

Enabling the exit programs

To enable these exits, you must do one of the following:

If you use the TBEXITS parameter to enable the exits, a global work area of 4 bytes is provided. If you use a PLTPI program, you can select the size of the global work area. You can also enable more than one exit program for use at each exit point; the TBEXITS parameter allows only one exit program at each exit point. PLTPI processing is described in Writing initialization and shutdown programs.

End of change

Exit XFCBFAIL, file control backout failure 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:

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:

  1. Do not issue any recoverable operations.
  2. Do not use operations that access systems or resource owners external to this CICS, even if the target resource is non-recoverable.
  3. Do not disable or close files, because this could cause further error conditions.
  4. 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.

Values of the error-type byte referenced by UEPERR

The UEPERR field in the XFCBFAIL parameter list points to an error-type byte, which contains one of the following values:

XBFERU
An error response has been returned from the file control file-request-handler program while processing a READ UPDATE request. This request is issued by file control backout to retrieve the existing copy of the record before backing it out.

Use UEPFCRSP in combination with the type of record, shown in the file control portion of the log record addressed by parameter UEPBLOGR, to determine the specific problem. The storage area addressed by UEPBLOGR contains either the before-image of a "read-update" record or the new copy of a "write-add" to be deleted. The type-of-record field, FLJB_RECORD_TYPE, is defined in DSECT DFHFCLGD.

XBFERE
An error response has been returned from the file control file-request-handler program while processing a REWRITE request. This request is issued by file control backout to replace the existing copy of the record on the data set with the "before-image" held in the log record addressed by UEPBLOGR. Use parameter UEPFCRSP to determine which error occurred.
XBFEWR
An error response has been returned from the file control file-request-handler program while processing a WRITE request. This request is issued by file control backout to add the "before-image" of a deleted record. Use parameter UEPFCRSP to determine which error occurred.
XBFEDL
An error response has been returned from the file control file-request-handler program while processing a REWRITE DELETE request. This request is issued by file control backout to delete a new record added to a VSAM data set. Use parameter UEPFCRSP to determine which error occurred.
XBFENO
The failure that occurred during file control backout was not as a result of an error response from the file control file-request-handler program. Use parameter UEPFCRSP to determine which error occurred.

DFH$FCBF sample global user exit program

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:

Exit XFCBOUT, file control backout exit

XFCBOUT is invoked when a file control update is about to be backed out. The log record containing the before-image of the record being backed out is passed to the exit program.

XFCBOUT does not provide a return code to allow your exit program to bypass the backout of the update, because this would result in data corruption.

Migration note

XFCBOUT replaces the function provided for file control, in releases before CICS Transaction Server for OS/390®, Version 1 Release 1, by the XDBIN and XRCINPT exits. In earlier releases:

Because the same backout code is executed following an emergency restart as at any other time, XFCBOUT replaces both XRCINPT and XDBIN for file data. The address of an FBO entry is not supplied (there is no FBO table in CICS Transaction Server for z/OS®, Version 3 Release 1). However, the file name is in the log record, so your exit program can use an EXEC CICS INQUIRE FILE command to get information about the file.

When invoked
Invoked when an update (represented by a before-image log record) is being backed out by File Control.
Exit-specific parameters
UEPFLOGR
The address of the file control portion of the log record that is being presented for backout. This is mapped by the DSECT DFHFCLGD.
Return codes
UERCNORM
Continue processing.

A return code of UERCPURG is not allowed. There is no need to set a UERCPURG return code, because this exit is invoked during syncpoint phase 2, and therefore cannot get a purged response from any calls it makes.

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:

  1. Do not issue any recoverable operations.
  2. Do not use operations that access systems or resource owners external to this CICS, even if the target resource is non-recoverable.
  3. Do not disable or close files, because this could cause further error conditions.
  4. 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.

Because it is anticipated that XFCBOUT will be used for specific applications, no general-purpose sample exit program is provided. You could use any of samples for the other file control recovery exits--DFH$FCBF, DFH$FCBV, or DFH$FCLD--as the basis for an XFCBOUT exit program.

Exit XFCBOVER, file control backout override exit

XFCBOVER is part of the support CICS file control provides for "batch windows" in a VSAM RLS environment.

VSAM RLS locks individual records within a data set, and these locks are converted to retained locks for those UOWs that are not completed because of backout or in-doubt failures, thus preserving data integrity. To avoid corruption of a data set by a non-RLS batch job, which is not aware of the retained record locks, a data set cannot normally be opened for update in non-RLS mode if it has any locked records.

Retained lock override for batch

There may be circumstances in which you want to override these locks and force the open of a data set for batch processing. For example, when:

To override the open restriction, VSAM RLS provides the SHCDS PERMITNONRLSUPDATE command, to allow a non-RLS batch job to open a sphere for update even when there are retained locks.

Effect of retained lock override on CICS

VSAM records the use of the option to override retained locks, so that it can notify a CICS region when the region next opens the data set. Because data could have been altered by the non-RLS batch job, the results of CICS performing any recovery (on UOWs that were in a backout-failed or indoubt-failed state at the time of the batch job) are unpredictable. In this situation, therefore, the default CICS action is not to back out any updates that were outstanding at the time that locks were overridden, and to write diagnostic information about each backout ignored to the CSFL transient data queue.

The XFCBOVER global user exit is provided to enable you, for each UOW log record for which backout is being ignored, to:

When invoked
Whenever CICS is about to ignore a UOW log record that is due to be backed out, because the lock that protected the updated record could have been overridden by a non-RLS batch program.
Exit-specific parameters
UEPOLOGR
Address of the file control portion of a shunted log record that represents an update to a data set for which retained locks may have been overridden. The file control portion of the log record can be mapped using the DSECT DFHFCLGD.
UEPODSN
Address of a 44-byte area of storage containing the name of the data set whose locks were overridden.
Return codes
UERCNORM
Do not perform the backout of this log record. Any updates performed by the batch run should take precedence.
UERCBCKO
Perform the backout. It is known that the actions of the batch job could not have affected this update.
A return code of UERCPURG is not allowed. There is no need to set a UERCPURG return code, because this global user exit is invoked during syncpoint phase 2, and therefore cannot get a purged response from any calls that it makes.
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:

  1. Do not issue any recoverable operations.
  2. Do not use operations that access systems or resource owners external to this CICS, even if the target resource is non-recoverable.
  3. Do not disable or close files, because this could cause further error conditions.
  4. 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.

DFH$FCBV sample global user exit program

DFH$FCBV provides sample processing for the file control backout override global user exit, XFCBOVER. The exit program, if enabled at the XFCBOVER exit point, is invoked when a log record is presented to file control for backing out an update to a data set in RLS access mode, after the data set has been used in a batch update despite the existence of retained locks. A consequence of running a batch program while there are retained locks is that a lock that protected a record updated by CICS could have been overridden by a non-RLS batch program.

There is more information about using the XFCBOVER exit, and about the DFH$FCBV sample program, in the comments within the DFH$FCBV source code. The comments also include some suggested extensions that you can make to the sample program to reflect the pattern of batch usage at your installation.

In summary, DFH$FCBV performs the following processing:

Exit XFCLDEL, file control logical delete exit

XFCLDEL is invoked whenever a WRITE to a VSAM ESDS, or to a BDAM data set, is being backed out. Because these types of data set do not support deletion, you can use XFCLDEL to perform a logical delete by amending the record in some way that flags it as deleted.

When invoked
Invoked when backing out a WRITE to a VSAM ESDS or a BDAM data set.
Exit-specific parameters
UEPBLOGR
Address of the file control portion of the log record representing the update that is to be backed out by logical deletion. The log record can be mapped using the DSECT DFHFCLGD.
UEPTRANS
Address of the 4-byte 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) task number for the task under which the update that is being backed out was made.
UEPFDATA
Address of a variable-length field containing the data in the file control request. The exit program can amend the record data addressed by this field, marking it in some way that applications can recognize as representing a logically deleted record.
UEPFLEN
Address of a fullword containing the length of the data in the file control request.
Return codes
UERCFAIL
Do not perform the logical delete, and treat this as a backout failure. This is the default action taken if the exit is not enabled.
UERCLDEL
Perform the logical delete by reapplying the updated record.

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 should mean that "purged" 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:

  1. Do not issue any recoverable operations.
  2. Do not use operations that access systems or resource owners external to this CICS, even if the target resource is non-recoverable.
  3. Do not disable or close files, because this could cause further error conditions.
  4. 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.

DFH$FCLD sample global user exit program

DFH$FCLD provides sample processing for the file control logical delete global user exit, XFCLDEL. The exit program, if enabled at the XFCLDEL exit point, is invoked when a WRITE to a VSAM ESDS or BDAM data set is being backed out. Because these access methods do not support a physical delete operation, special action must be taken to provide a logical delete function. Normally this involves flagging the record in a way that application programs that use the data set recognize as meaning the record has been deleted.

There is more information about using the XFCLDEL user exit, and about the DFH$FCLD sample program, in the comments within the DFH$FCLD source code.

In summary, DFH$FCLD performs the following processing:

Related concepts
Overview -- what is a global user exit?
Overview of the XPI
Global user exit XPI examples, showing the use of storage
Related tasks
Writing global user exit programs
Making an XPI call
Related reference
List of global user exit points
The XPI functions
[[ Contents Previous Page | Next Page Index ]]