File control file state program exits XFCSREQ and XFCSREQC

Two user exits are provided in the file control state program that you can call before and after a file request.

XFCSREQ: This exit is called before a file ENABLE, DISABLE, OPEN, CLOSE, or CANCEL CLOSE request is acted on. You can use XFCSREQ to gather information about the state of the file; for example, which file requests (SERVREQs) are valid and which journaling options are set. Based on this information, you can suppress the request, if appropriate. See return code UERCBYP for details.
XFCSREQC: This exit is called after the file request has been acted on. You can use XFCSREQC to gather information about the data set associated with the file; for example, which recovery options are set. XFCSREQC is invoked even if you have used XFCSREQ to suppress the file request.

For ENABLE, DISABLE, OPEN, and CANCEL CLOSE requests, each exit is invoked only once. However, for CLOSE requests, because a file can be quiesced before actual closure, the exits might be invoked more than once. There are two occasions when the user exits XFCSREQ and XFCSREQC are not invoked during a close request:

On a controlled, non-immediate shutdown of CICS®, when CICS closes all files.
After loading a user maintained data table. When the data table load has completed the source data set is no longer required. CICS subsequently closes and de-allocates the file, leaving the data table open.

A single CLOSE request

For a single CLOSE request, XFCSREQ and XFCSREQC are invoked more than once if closure is attempted while the file is being accessed by other tasks. For example, the result of a CLOSE NOWAIT command in these circumstances is that XFCSREQ is invoked before the closure is attempted. Because there are still users of the file, the closure is delayed. However, because it specified NOWAIT, the CLOSE request completes, and invokes XFCSREQC with UEPFSRSP set to ‘UEFSPEND’, meaning closure is pending. When all activity against the file is complete, the file is closed, and XFCSREQ and XFCSREQC are invoked under the task that closed it.

A CLOSE WAIT request

For a CLOSE WAIT request, the exits are invoked as follows. XFCSREQ is invoked, the task requests a closure of the file and waits for the closure to happen. When all activity against the file is complete, the file is closed, and XFCSREQ and XFCSREQC are invoked under the task that closed it. Finally, because the closure has now been completed, the task that issued the CLOSE WAIT is resumed, completes its CLOSE request, and invokes XFCSREQC.

A CANCEL CLOSE request

A CANCEL CLOSE request is issued by CICS in response to an UNQUIESCE command that cancels a pending QUIESCE command. A QUIESCE data set command immediately sets all files opened against the specified data set as unenabled, to prevent new tasks being allowed access to the data set. The close part of the operation, however, waits until the last user task finishes before a file is closed. (This is the same as any close operation against a file.) An UNQUIESCE issued while the close is still waiting causes a CANCEL CLOSE request and the invocation of the XFCSREQ and XFCSREQC exits. Note that a CANCEL CLOSE is issued only for close requests that were initiated by a QUIESCE command, not for any other close requests.