Program control exits XPCREQ, XPCERES, XPCREQC

These exits are called by the EXEC interface program before a link request is processed, before CICS processes dynamically routed link requests, or after a link request has completed.

XPCREQ
XPCREQ is called by the EXEC interface program before a link request is processed. If the request is a distributed program link, the XPCREQ exit is driven on both sides of the link; that is, in both the client and the server regions. The exit program is passed the address of the application's parameter list (in UEPCLPS), and can modify this list as required. For example, you can use this exit to modify the SYSID at the time of a distributed program link request. You can write an application program to manage a list of SYSIDs in a global work area (GWA). The global user exit program can obtain access to the GWA, and use the information stored there to redirect DPL requests.
Note:
  1. The attributes of the local PROGRAM resource are not passed to the exit program. If the exit program requires the value of an attribute, it can issue an EXEC CICS INQUIRE PROGRAM command.
  2. If you use XPCREQ to change the target SYSID, remember that:
    1. If SYSID specifies a remote region, no reference is made to the local PROGRAM resource. In the remote region the program runs under the TRANSID of the transaction in the client region, not under the TRANSID specified on the PROGRAM resource in the client region.
    2. If SYSID specifies the local region, CICS treats the link request as if SYSID was not specified. The local PROGRAM resource is honored.
    3. The XPCREQ exit is called by internal requests made by CICS code, in addition to requests made by applications.
XPCERES
XPCERES is called by the EXEC interface program before CICS processes either of the following kinds of dynamically routed link request:
  • A distributed program link (DPL) call
  • A Link3270 bridge request
XPCERES is called:
  • After exit XPCREQ and before XPCREQC if these exits are enabled:
    • If an XPCREQ exit program chooses to bypass the request, XPCERES is not called.
    • If an XPCREQ exit program modifies the command parameter list, XPCERES must deal with the modified request.
  • On the target region to which the request has been routed.
  • Only if it is enabled. Enable this exit only in application-owning regions when DPL and Link3270 bridge requests can be dynamically routed.
  • By internal requests made by CICS code, in addition to requests made by applications.
The XPCERES exit is not called:
  • For statically routed requests.
  • If it is disabled.
  • If an XPCREQ exit program chooses to bypass the request.
You can use XPCERES to check that all resources required by the linked-to program are available on the target region. If the program is disabled or a required file is missing, your exit program can give the dynamic routing program the opportunity to route the request to a different region. Set a return code of UERCRESU. CICS performs the following processing:
  1. In the COMMAREA of the routing program, CICS sets the DYRERROR field to 'F' - resource unavailable.
  2. CICS calls the routing program, on the routing region, for route selection failure.
  3. CICS returns a RESUNAVAIL condition on the EXEC CICS LINK command that was run by the mirror on the target region. This condition is not returned to the application program.

CICS ignores any changes made by the exit program to the values of any of the exit parameters. Your exit program can set a return code, but not change any parameters.

For guidance information about dynamically routing DPL requests, see Dynamically routing DPL requests. For guidance information about dynamically routing Link3270 bridge requests, see Using Link3270 bridge load balancing. For programming information about writing a dynamic routing program to route DPL requests, see Routing DPL requests dynamically. For programming information about writing a dynamic routing program to route Link3270 bridge requests, see Routing bridge requests dynamically.

XPCREQC
XPCREQC is called after a link request has completed. You can use this exit to pass back a response to the application by using the EIBRESP or EIBRESP2 fields. Such responses might be used to keep status information about a link request up-to-date. For example, if a link request fails because a connection is unavailable, XPCREQC can set EIBRESP=500 (a response code not used by CICS) to indicate the failure, enabling the application, with the other exit XPCREQ, to determine a suitable course of action.
Note: The XPCREQC exit is called by internal requests made by CICS code, in addition to requests made by applications.