Writing and compiling cluster workload exits

Write a cluster workload exit program to customize the workload management of clusters. We might take the cost of using a channel at different times of day, or message content, into account when routing messages. These are factors that are not considered by the standard workload management algorithm.

In most cases the workload management algorithm is sufficient for the needs. However, so that we can provide your own user-exit program to tailor workload management, IBM MQ includes a user exit, the cluster workload exit.

We might have some particular information about your network or messages that you could use to influence workload balancing. We might know which are the high-capacity channels or the cheap network routes, or you might want to route messages depending upon their content. You could decide to write a cluster workload exit program, or use one supplied by a third party.

The cluster workload exit is called when accessing a cluster queue. It is called by MQOPEN, MQPUT1 and MQPUT.

The target queue manager selected at MQOPEN time is fixed if MQOO_BIND_ON_OPEN is specified. In this case the exit is run only once.

If the target queue manager is not fixed at MQOPEN time, the target queue manager is chosen at the time of the MQPUT call. If the target queue manager is not available, or fails while the message is still on the transmission queue, the exit is called again. A new target queue manager is selected. If the message channel fails while the message is being transferred, and the message is backed out, a new target queue manager is selected.

On Multiplatforms, the queue manager loads the new cluster workload exit the next time the queue manager is started.

If the queue manager definition does not contain a cluster workload exit program name, the cluster workload exit is not called.

• The message definition structure, MQMD.
• The message length parameter.
• A copy of the message, or part of the message.

On non-z/OS platforms, if we use CLWLMode=FAST, each operating system process loads its own copy of the exit. Different connections to the queue manager can cause different copies of the exit to be invoked. If the exit is run in the default safe mode, CLWLMode=SAFE, a single copy of the exit runs in its own separate process.

Writing cluster workload exits

For information about writing cluster workload exits for z/OS, see Cluster workload exit programming for IBM MQ for z/OS.

From Version 9.1.0, cluster workload exits run in the channel initiator address space, instead of the queue manager address space. If we have a cluster workload exit, we should remove the CSQXLIB DD statement from your queue manager started task procedure, and add the dataset containing the cluster workload exit to the CSQXLIB concatenation on your channel initiator started task procedure.

For Multiplatforms, cluster workload exits must not use MQI calls. In other respects, the rules for writing and compiling cluster workload exit programs are like the rules that apply to channel exit programs. Follow the steps in Writing exits and installable services on UNIX, Linux and Windows, and use the sample program, Sample cluster workload exit to help write and compile your exit.

For more information about channel exits, see Writing channel-exit programs.

Configure cluster workload exits

ALTER QMGR CLWLEXIT(myexit)

• Sample cluster workload exit
  IBM MQ includes a sample cluster workload exit program. We can copy the sample and use it as a basis for the own programs.
• 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.

Parent topic: User exits, API exits, and IBM MQ installable services

Related information

• Cluster workload exit call and data structures