Using the API-crossing exit

You can use the API-crossing exit to:

Defining the exit program

Before the exit can be used, an exit program load module must be available when the CICS adapter connects to WebSphere MQ for z/OS. The exit program is a CICS program that must be named CSQCAPX and reside in a library in the DFHRPL concatenation. CSQCAPX must be defined in the CICS system definition file (CSD), and the program must be enabled.

When CSQCAPX is loaded, a confirmation message is written to the CKQC adapter control panel or to the console. If the program cannot be loaded, a diagnostic message is displayed.

How the exit is invoked

When enabled, the API-crossing exit is invoked:

This means that using the API-crossing exit degrades the performance of WebSphere MQ for z/OS, so plan your use of it carefully.

The exit program can be invoked once before a call is executed, and once after the call is executed. On the before type of exit call, the exit program can modify any of the parameters on the MQI call, suppress the call completely, or allow the call to be processed. If the call is processed, the exit is invoked again after the call has completed.

Note:
The exit program is not recursive. Any MQI calls made inside the exit do not invoke the exit program for a second time.

Communicating with the exit program

After it has been invoked, the exit program is passed a parameter list in the CICS communication area pointed to by a field called DFHEICAP. The CICS Exec Interface Block field EIBCALEN shows the length of this area. The structure of this communication area is defined in the CMQXPA assembler-language macro that is supplied with WebSphere MQ for z/OS :

*
MQXP_COPYPLIST       DSECT
                     DS  0D         Force doubleword alignment
MQXP_PXPB            DS   AL4       Pointer to exit parameter block
MQXP_PCOPYPARM       DS 11AL4       Copy of original plist
*
                        ORG  MQXP_PCOPYPARM
MQXP_PCOPYPARM1      DS   AL4       Copy of 1st parameter
MQXP_PCOPYPARM2      DS   AL4       Copy of 2nd parameter
MQXP_PCOPYPARM3      DS   AL4       Copy of 3rd parameter
MQXP_PCOPYPARM4      DS   AL4       Copy of 4th parameter
MQXP_PCOPYPARM5      DS   AL4       Copy of 5th parameter
MQXP_PCOPYPARM6      DS   AL4       Copy of 6th parameter
MQXP_PCOPYPARM7      DS   AL4       Copy of 7th parameter
MQXP_PCOPYPARM8      DS   AL4       Copy of 8th parameter
MQXP_PCOPYPARM9      DS   AL4       Copy of 9th parameter
MQXP_PCOPYPARM10     DS   AL4       Copy of 10th parameter
MQXP_PCOPYPARM11     DS   AL4       Copy of 11th parameter
*
MQXP_COPYPLIST_LENGTH  EQU  *-MQXP_PXPB
                       ORG  MQXP_PXPB
MQXP_COPYPLIST_AREA    DS   CL(MQXP_COPYPLIST_LENGTH)
*

Field MQXP_PXPB points to the exit parameter block, MQXP.

Field MQXP_PCOPYPARM is an array of addresses of the call parameters. For example, if the application issues an MQI call with parameters P1, P2, or P3, the communication area contains:

  PXPB,PP1,PP2,PP3

where P denotes a pointer (address) and XPB is the exit parameter block.