Cluster workload exit programming for IBM MQ for z/OS

Cluster workload exits are invoked as if by a z/OS® LINK command. Exits are subject to a number of stringent programming rules. Avoid using most SVC commands that involve waits, or using a STAE or ESTAE in a workload exit.

Cluster workload exits are invoked as if by a z/OS LINK in:

  • Non-authorized problem program state
  • Primary address space control mode
  • Non-cross-memory mode
  • Non-access register mode
  • 31 bit addressing mode
  • Storage key 8
  • Program Key Mask 8
  • TCB key 8

Put the link-edited modules in the data set specified by the CSQXLIB DD statement of the queue manager address space procedure. The names of the load modules are specified as the workload exit names in the queue manager definition.

When writing workload exits for IBM MQ for z/OS, the following rules apply:

  • You must write exits in assembler or C. If we use C, it must conform to the C systems programming environment for system exits, described in the z/OS C/C++ Programming Guide, SC09-4765.
  • If using the MQXCLWLN call, link edit with CSQMFCLW, supplied in thlqual.SCSQLOAD.
  • Exits are loaded from the non-authorized libraries defined by a CSQXLIB DD statement. Providing CSQXLIB has DISP=SHR, exits can be updated while the queue manager is running, with the new version used in the next MQCONN thread the queue manager starts.
  • Exits must be reentrant, and capable of running anywhere in virtual storage.
  • Exits must reset the environment on return to that at entry.
  • Exits must free any storage obtained, or ensure that storage is freed by a subsequent exit invocation.
  • No MQI calls are allowed.
  • Exits must not use any system services that could cause a wait, because a wait severely degrades the performance of the queue manager. In general, therefore, avoid an SVC, PC, or I/O.
  • Exits must not issue an ESTAE or SPIE, apart from within any subtasks they attach.
Note: There are no absolute restrictions on what we can do in an exit. However, most SVCs involve waits, so avoid them, except for the following commands:

  • GETMAIN / FREEMAIN
  • LOAD / DELETE

Do not use ESTAEs and ESPIEs because their error handling might interfere with the error handling performed by IBM MQ. IBM MQ might not be able to recover from an error, or your exit program might not receive all the error information.

The system parameter EXITLIM limits the amount of time an exit might run for. The default value for EXITLIM is 30 seconds. If you see the return code MQRC_CLUSTER_EXIT_ERROR, 2266 X'8DA' your exit might be looping. If you think the exit needs more than 30 seconds to complete, increase the value of EXITLIM.