File control open/close program exit XFCNREC

You can use XFCNREC to suppress the open failure that occurs when either of the following occurs:

Note:
This exit is not invoked for RLS opens. For RLS, recovery is a property of the data set. Therefore it is not possible for files and their base data set to have unmatched recovery attributes.

Using XFCNREC with a back out recovery setting mismatch

XFCNREC is intended for those who want to continue with open processing even though the backout recovery settings for different files associated with the same base data set are not consistent.

After an open failure has been suppressed, CICS® can no longer guarantee integrity for the data set and marks it accordingly. Any subsequent EXEC CICS INQUIRE DSNAME OR CEMT INQUIRE DSNAME RECOVSTATUS command returns NOTRECOVABLE. Logging continues for the data set for requests via any file that has BACKOUT on its definitions, but not for those that do not have BACKOUT.

The mismatched state of the data set continues until an EXEC CICS or CEMT SET DSNAME REMOVE command is issued, or until an initial or cold start of CICS. (if the associated data set is not in backout failed state).

At the point at which the mismatch is accepted, CICS issues a message to warn that integrity can no longer be guaranteed.

The order in which files are opened for the same base data set will determine the content of the message received on suppression of an open failure using XFCNREC. If the base cluster block is set as unrecoverable and a mismatch has been allowed, access may be allowed to the data set, via an unrecoverable file, before the data set is fully recovered.

To provide a means of selecting which mismatches to accept and which to reject, three parameters are passed to the exit. These are the address of the filename, the address of the base data set name, and the address of a byte containing the file backout indicator. Because the exit is driven only if there is a mismatch, the data set backout indicator can be derived from the setting for the file.

Note:
If XFCNREC is used to suppress an open failure due to a mismatch, the global user exit XFCSREQC will pass the base data set backout setting as the exit parameter UEFBCRV, and not the file backout setting, which may be different.

Using XFCNREC with a BWO mismatch

Exit XFCNREC can allow the file to be opened and CICS will continue to run normally. However, forward recovery will not be available for the opened dataset.

For more information about writing an XFCNREC exit program, see the CICS Recovery and Restart Guide.

Exit XFCNREC

When invoked
Before file open, when a mismatch is detected:
  1. Between the backout recovery setting for the file and its associated non-RLS data set.
  2. Because BWO is required but the recovery attributes indicate that no associated forward recovery file has been specified.
Exit-specific parameters
UEFILE
Address of the 8-bit file name. If the file name is less than 8 characters in length, it will be padded with blanks.
UEDSETN
Address of the 44-byte base data set name. If the data set name is less than 44 characters in length, it will be padded with blanks.
UEPFRCV
Address of a 1-byte field containing the backout recovery setting for the file, as specified in the FILE definition. The possible value is:
UEPFLOG
Backout logging specified.

If RECOV(NONE) is specified in the FILE definition, the addressed field contains hexadecimal zeros.

This field has no meaning if the exit is driven due to a BWO mismatch.

UEPFAIL
Address of a 1-byte field containing the reason for the mismatch. The possible values are:
UEPBWOF
A BWO mismatch
UEPATTF
A mismatch in the backout recovery settings
UEPOPEN
Address of a 1-byte field. Its default value is 'N'. To bypass an open failure caused by a BWO mismatch, set the addressed field to 'Y'.
Note:
In releases of CICS before 4.1, UEDSETN was called UEDSNAME, and UEPFLOG was called UEFBCLOG. If you are migrating exit programs from CICS/ESA 3.3 or earlier to CICS Transaction Server for z/OS®, Version 3 Release 1, all references to these parameters must be changed.
Return codes
UERCNORM
Fail open as normal.
UERCBYP
Bypass open failure--accept mismatch.
XPI calls
Must not be used.
SPI calls
Must not be used.
API and SPI calls
Must not be used.

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 ]]