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 lifetime
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 to consider when writing your exit program:
- For performance reasons, 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 OS/390 storage protection feature, your program
must run in CICS execution key. That is, you must specify EXECKEY(CICS(R)) 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. Ensure 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 attempts 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).