Writing your own exit program

We can use the sample API-crossing exit program (CSQCAPX) that is supplied with IBM MQ for z/OS as a framework for the own program.

This is described in 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. We 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.

If we are using CICS Transaction Server V3.2, we must write your exit program to be threadsafe and declare your exit program as threadsafe. If we are using earlier CICS releases, we are also recommended to write and declare your exit programs as threadsafe to be ready for migrating to CICS Transaction Server V3.2.

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 IBM MQ for z/OS, we 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.
  • Specify CONCURRENCY(THREADSAFE) when you define your exit program and any programs that your exit program calls.
  • If we are using the CICS Transaction Server for z/OS storage protection feature, your program must run in CICS execution key. That is, we 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 IBM MQ for z/OS code. Ensure that your exit does not disrupt any IBM MQ for z/OS programs or transactions that use the MQI. These are typically 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 IBM 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).

Parent topic: The API-crossing exit for z/OS