File control EXEC interface API exits XFCREQ and XFCREQC

The XFCREQ exit allows you to intercept a file control application programming interface (API) request before any action has been taken on it by file control. The XFCREQC exit allows you to intercept a file control API request after file control has completed its processing. The XFCREQ and XFCREQC exits can be written only in assembler language.

Important: The XFCREQ and XFCREQC exits are not called, on the target region, for function-shipped requests. That is, if a file control API request is function-shipped to a remote region, the exits are not called on the remote region. To intercept a function-shipped file control API request on the target region, use the XFCFRIN exit; see File control domain exits, XFCFRIN and XFCFROUT.

What commands are intercepted

The file control API commands intercepted are:
  • READ
  • WRITE
  • REWRITE
  • DELETE
  • UNLOCK
  • STARTBR
  • READNEXT
  • READPREV
  • ENDBR
  • RESETBR

Usage of the exits

Using XFCREQ, you can:
  • Analyze the request, to determine its type, the keywords specified, and their values.
  • Modify values specified by the request before the command is executed.
  • Set return codes to specify that either:
    • CICS® should continue with the (possibly modified) request.
    • CICS should bypass the request. (Note that if you set this return code, you must also set up return codes for the EXEC interface block (EIB), as if you had processed the request yourself.)
Using XFCREQC, you can:
  • Analyze the request, to determine its type, the keywords specified, and their values.
  • Set return codes for the EIB.

Parameters passed to the exits

Both exits are passed nine parameters as follows:
  • The address of the command-level parameter structure
  • The address of a token (UEPFCTOK) used to pass 4 bytes of data from XFCREQ to XFCREQC
  • The addresses of copies of four pieces of return code and resource information from the EIB
  • The address of a token (UEPTSTOK) that is valid throughout the life of a task
  • The address of a recursion count field
  • The address of a 16-byte area that is used if the request has been function shipped.

EXEC interface block (EIB) passed to the exits

Copies of EIBRSRCE, EIBRCODE, EIBRESP, and EIBRESP2 are passed to the exit so you can modify/set the completion and resource information in XFCREQ and XFCREQC, and examine completion and resource information in XFCREQC.

You can update the copies of EIBRSRCE, EIBRCODE, EIBRESP, and EIBRESP2 that you are given in the parameter list. File Control copies your values into the real EIB after the completion of XFCREQC; or if you specify a return code of ‘bypass' in XFCREQ.

You must set valid file control responses. You must set all three of EIBRCODE, EIBRESP, and EIBRESP2 to a consistent set of values, such as would be set by File Control to describe a valid completion. File Control does not police the consistency of EIBRCODE, EIBRESP, and EIBRESP2. To aid you in setting the values of EIBRCODE, EIBRESP, and EIBRESP2, the values used by File Control are specified in DFHFCEDS.