File control domain exits, XFCFRIN and XFCFROUT
The XFCFRIN exit is invoked on entry to the main file control request gate, FCFR, and the XFCFROUT exit runs after the completion of a file control request. The XFCFRIN and XFCFROUT exits must be coded to threadsafe standards and declared threadsafe to take advantage of threadsafe remote file support.
- XFCFRIN
- XFCFRIN allows you to write a program to perform one or more of
the following tasks:
- Monitor file control requests and allow them to continue, to be processed by CICS® file control
- Intercept file control requests and bypass CICS file control processing altogether
- Redirect the request to a remote region.
If the exit program passes the request to CICS file control (without choosing to redirect it to a remote region), it is not allowed to make changes to any of the parameters. If the exit program intercepts the request and bypasses file control:
- It must return all the responses and output parameters that would otherwise have been returned by file control. These are marked output in the descriptions of the exit-specific parameters.
- It must indicate whether, if the request was function-shipped, the mirror transaction is permitted to terminate. Certain file control requests require that another request has been executed previously in the same transaction. (For example, READNEXT must be preceded by a matching STARTBR; REWRITE must be preceded by a matching READ, READNEXT, or READPREV with the UPDATE option). If the mirror transaction terminates between two such requests, the second is likely to fail. Conversely, a mirror transaction that is retained unnecessarily will hold on to CICS resources and may contribute to storage and locking problems.
- CICS terminates file browses and outstanding updates as part of syncpoint processing. However, the XFCFRIN exit is not invoked for syncpoint. If you want to emulate this aspect of CICS behavior accurately, or you want to support recoverable resources, you must invoke a task-related user exit program which schedules the syncpoint manager—see Coding a program to be started by the CICS sync point manager.
To redirect the request to a remote region, the exit program must add or change the value of the SYSID parameter. In this case, it may also need to supply the values of the key length and record length. It is not permitted to make changes to any of the other parameters.
- XFCFROUT
- XFCFROUT allows you to monitor the results of completed file control
requests. For example, if you didn't choose to bypass CICS file
control processing, you can analyze the (CICS-internal) file control
request to determine its type, the parameters passed to file control,
and the values returned. It is invoked in both the following cases:
- After CICS file control has completed its processing, either normally or with an error
- If your XFCFRIN exit program chooses to bypass CICS file control processing.
All parameters are input-only; your exit program cannot modify any of the values.
To use IPIC connections for function shipping file control requests, ensure that XFCFRIN and XFCFROUT check that the UEPTERM parameter is a non-zero value before trying to use it as an address. The UEPTERM parameter is a zero for file control requests that have been function shipped over an IPIC connection.