The API-crossing exit for z/OS

This section contains product-sensitive programming interface information.

An exit is a point in IBM-supplied code where you can run your own code. WebSphere MQ for z/OS provides an API-crossing exit that you can use to intercept calls to the MQI, and to monitor or modify the function of the MQI calls. This section describes how to use the API-crossing exit, and describes the sample exit program that is supplied with WebSphere MQ for z/OS.

Using the API-crossing exit

You could use the API-crossing exit to:

• Operate additional security checks by examining the contents of each message before and after each MQI call
• Replace the queue name supplied in the message with another queue name
• Cancel the call and either issue a return code of 0 to simulate a successful call, or another value to indicate that the call was not performed
• Monitor the use of MQI calls in an application
• Gather statistics
• Modify input parameters on specific calls
• Modify the results of specific calls

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:

• By all applications that use the CICS adapter of WebSphere MQ for z/OS
• For the following MQI calls:
  • MQCLOSE
  • MQGET
  • MQINQ
  • MQOPEN
  • MQPUT
  • MQPUT1
  • MQSET
• Every time one of these MQI calls is made
• Both before and after a call

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.

Writing your own exit program

You can use the sample API-crossing exit program (CSQCAPX) that is supplied with WebSphere MQ for z/OS as a framework for your own program. This is described in topic "The sample API-crossing exit program, CSQCAPX".

When writing an exit program, to find the name of an MQI call issued by an application, examine the ExitCommand field of the MQXP structure. To find the number of parameters on the call, examine the ExitParmCount field. You can use the 16-byte ExitUserArea field to store the address of any dynamic storage that the application obtains. This field is retained across invocations of the exit and has the same life time as a CICS task.

Your exit program can suppress execution of an MQI call by returning MQXCC_SUPPRESS_FUNCTION or MQXCC_SKIP_FUNCTION in the ExitResponse field. To allow the call to be executed (and the exit program to be reinvoked after the call has completed), your exit program must return MQXCC_OK.

When invoked after an MQI call, an exit program can inspect and modify the completion and reason codes set by the call.

Usage notes

Here are some general points you should bear in mind when writing your exit program:

• For performance reasons, you should write your program in assembler language. If you write it in any of the other languages supported by WebSphere MQ for z/OS, you must provide your own data definition file.
• Link-edit your program as AMODE(31) and RMODE(ANY).
• To define the exit parameter block to your program, use the assembler-language macro, CMQXPA.
• If you are using the CICS Transaction Server for z/OS storage protection feature, your program must run in CICS execution key. That is, you must specify EXECKEY(CICS) when defining both your exit program and any programs to which it passes control. For information about CICS exit programs and the CICS storage protection facility, see the CICS Customization Guide.
• Your program can use all the APIs (for example, IMS, DB2, and CICS) that a CICS task-related user exit program can use. It can also use any of the MQI calls except MQCONN, MQCONNX, and MQDISC. However, any MQI calls within the exit program do not invoke the exit program a second time.
• Your program can issue EXEC CICS SYNCPOINT or EXEC CICS SYNCPOINT ROLLBACK commands. However, these commands commit or roll back all the updates done by the task up to the point that the exit was used, and so their use is not recommended.
• Your program must end by issuing an EXEC CICS RETURN command. It must not transfer control with an XCTL command.
• Exits are written as extensions to the WebSphere MQ for z/OS code. You must take great care that your exit does not disrupt any WebSphere MQ for z/OS programs or transactions that use the MQI. These are usually indicated with a prefix of "CSQ" or "CK".
• If CSQCAPX is defined to CICS, the CICS system will attempt to load the exit program when CICS connects to WebSphere MQ for z/OS. If this attempt is successful, message CSQC301I is sent to the CKQC panel or to the system console. If the load is unsuccessful (for example, if the load module does not exist in any of the libraries in the DFHRPL concatenation), message CSQC315 is sent to the CKQC panel or to the system console.
• Because the parameters in the communication area are addresses, the exit program must be defined as local to the CICS system (that is, not as a remote program).

The sample API-crossing exit program, CSQCAPX

The sample exit program is supplied as an assembler-language program. The source file (CSQCAPX) is supplied in the library thlqual.SCSQASMS (where thlqual is the high-level qualifier used by your installation). This source file includes pseudocode that describes the program logic.

The sample program contains initialization code and a layout that you can use when writing your own exit programs.

The sample shows how to:

• Set up the exit parameter block
• Address the call and exit parameter blocks
• Determine for which MQI call the exit is being invoked
• Determine whether the exit is being invoked before or after processing of the MQI call
• Put a message on a CICS temporary storage queue
• Use the macro DFHEIENT for dynamic storage acquisition to maintain reentrancy
• Use DFHEIBLK for the CICS exec interface control block
• Trap error conditions
• Return control to the caller

Design of the sample exit program

The sample exit program writes messages to a CICS temporary storage queue (CSQ1EXIT) to show the operation of the exit. The messages show whether the exit is being invoked before or after the MQI call. If the exit is invoked after the call, the message contains the completion code and reason code returned by the call. The sample uses named constants from the CMQXPA macro to check on the type of entry (that is, before or after the call).

The sample does not perform any monitoring function, but simply places time-stamped messages into a CICS queue indicating the type of call it is processing. This provides an indication of the performance of the MQI, as well as the proper functioning of the exit program.

Note:

The sample exit program issues six EXEC CICS calls for each MQI call that is made while the program is running. If you use this exit program, WebSphere MQ for z/OS performance is degraded.

Preparing and using the API-crossing exit

The sample exit is supplied in source form only. To use the sample exit, or an exit program that you have written, you must create a load library, as you would for any other CICS program, as described in topic "Building CICS applications".

• For CICS Transaction Server for z/OS and CICS for MVS/ESA, when you update the CICS system definition (CSD) data set, the definitions you need are in the member thlqual.SCSQPROC(CSQ4B100).

  Note:

  The definitions use a suffix of MQ. If this suffix is already used in your enterprise, this must be changed before the assembly stage.

If you use the default CICS program definitions supplied, the exit program CSQCAPX is installed in a disabled state. This is because using the exit program can produce a significant reduction in performance.

To activate the API-crossing exit temporarily:

1. Issue the command CEMT S PROGRAM(CSQCAPX) ENABLED from the CICS master terminal.
2. Run the CKQC transaction, and use option 3 in the Connection pull-down to alter the status of the API-crossing exit to 'Enabled'.

If you want to run WebSphere MQ for z/OS with the API-crossing exit permanently enabled, do one of the following:

• For CICS Transaction Server for z/OS and CICS for MVS/ESA do one of the following:
  • Alter the CSQCAPX definition in member CSQ4B100, changing STATUS(DISABLED) to STATUS(ENABLED). You can update the CICS CSD definition using the CICS-supplied batch program DFHCSDUP.
  • Alter the CSQCAPX definition in the CSQCAT1 group by changing the status from DISABLED to ENABLED.

In both cases you must reinstall the group. You can do this by cold-starting your CICS system or by using the CICS CEDA transaction to reinstall the group while CICS is running.

Note:

Using CEDA may cause an error if any of the entries in the group are currently in use.

End of product-sensitive programming interface information.