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.
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:
- If an open during backout fails, XFCBFAIL is invoked. None of the other exits is invoked.
- 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.
- Unless item 1 applies, or XFCBOVER has been invoked
and returned UERCNORM, XFCBOUT is invoked.
- 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.
- 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.
- If a failure occurs after this point, XFCBFAIL is invoked.
To enable these exits, you must do one of the following:
- Specify the system initialization parameter TBEXITS=(name1,name2,name3,name4,name5,name6),
where name1 through name6 are the names of your user exit programs for XRCINIT,
XRCINPT, XFCBFAIL, XFCLDEL, XFCBOVER, and XFCBOUT.
- Enable the exits during the first stage of initialization using a PLTPI
program.
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.
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 the 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.
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:
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:
- XDBIN was invoked when a dynamic log record was processed during dynamic
backout. It was passed the log record being processed.
- XRCINPT was invoked when a log record from the restart data set was processed
during backout of in-flight work at emergency restart. It was passed the log
record, and the address of the FBO table entry.
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:
- 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.
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.
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:
- There is insufficient time available, before running the batch job, in
which to resolve the situation that caused the records to be locked, or
- It is known that the batch job cannot harm data integrity (because it
does not update existing records in the data set, or it does not update any
records that CICS may have updated).
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:
- Write application-related diagnostics to supplement those provided by CICS
- To perform application-related recovery actions
- To reverse the default by requesting that the backout should be carried
out after all. This option is required for the case where the batch job is
known not to corrupt data integrity (for example, because it only inserts
records).
- 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:
- 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.
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:
- Makes a user trace entry if tracing is active for file control. This has
trace point id X'01E0' and traces:
- An eye-catcher ‘DFH$FCBV ENTRY’
- The data set name
- The file control portion of the log record.
- Checks the data set name to see if it is one of those for which it is
known that batch programs never update existing records, but only insert new
records, or do not make updates at all. The sample program contains a table
of such data sets. If this data set is in the table, UERCBCKO is returned.
UERCBCKO means that CICS is to perform the backout, despite the override option
having been used, because the locked record cannot have been updated by a
batch job.
- For all other data sets, it must be assumed that the batch job could have
updated the record being backed out. The sample therefore returns UERCNORM,
which instructs CICS to take the default action of not backing out the
update.
- Exit from the program, making:
- A user trace entry if tracing is active for file control. This has trace
point id X'01E1' and traces:
- An eye-catcher ‘DFH$FCBV EXIT’
- The data set name
- Some text: ‘Update will be backed out’, or
‘Update
will not be backed out’ as appropriate.
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:
- 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.
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:
- Makes a user trace entry if tracing is active for file control. This has
trace point id X'01F0' and traces:
- An eye-catcher ‘DFH$FCLD ENTRY’
- The unmarked file control request data
- The file control portion of the log record.
- Issues an EXEC CICS INQUIRE FILE command to check the access method and
type to confirm that the file is a VSAM ESDS or BDAM data set. The logical
delete exit should have been invoked only if the file is one of these types.
- For a VSAM ESDS:
- Flags the record (whose address is passed to the exit in UEPFDATA) as
logically deleted. The sample adopts what is probably the most common convention,
which is to flag the first byte with a logical delete mark of X'FF'.
- Takes the normal exit from the program.
- For BDAM:
- Flags the record (whose address is passed to the exit in UEPFDATA) as
logically deleted. The sample adopts a convention for BDAM of flagging the
first byte with a logical delete mark of X'C0'.
- Takes the normal exit from the program.
- For any other combination of access method and type:
- Does not process the request, and the record is not flagged as deleted
- Takes the error exit from the program.
- Normal exit from the program:
- Makes a user trace entry if tracing is active for file control. This has
trace point id X'01F1' and traces:
- An eye-catcher ‘DFH$FCLD EXIT OK’
- An eye-catcher ‘RECORD MARKED AS DELETED’
- The marked file control request data
- The file control portion of the log record.
- Returns to CICS with return code UERCLDEL, which instructs CICS to rewrite
the marked record and therefore to logically delete it.
- Error exit from the program:
- Makes a user exception trace entry regardless of the trace setting. This
has trace point id X'01F2' and traces:
- An eye-catcher ‘USEREXC’
- An eye-catcher ‘DFH$FCLD EXIT FAIL’
- The unmarked file control request data
- The file control portion of the log record.
- Returns to CICS with return code UERCFAIL, which instructs CICS to regard the
logical delete as having failed. (The return code UERCNORM is not intended
for use by this exit. Returning UERCNORM has the same effect as UERCFAIL.)

[[ Contents Previous Page | Next Page Index ]]