Writing and compiling cluster workload exits

Write a cluster workload exit program to customize the workload management of clusters. You 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 your needs. However, so that you can provide your own user-exit program to tailor workload management, WebSphere® MQ includes a user exit, the cluster workload exit.

You might have some particular information about your network or messages that you could use to influence workload balancing. You 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 whilst the message is being transferred, and the message is backed out, a new target queue manager is selected.

On platforms other than z/OS®, the queue manager will load 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.

Various data are passed to a cluster workload exit in the exit parameter structure, MQWXP:
  • 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 you 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 platforms other than z/OS, 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 and compiling exits and installable services, 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.

Configuring cluster workload exits

You name cluster workload exits in the queue manager definition by specifying the cluster workload exit attribute on the ALTER QMGR command. For example: 
ALTER QMGR CLWLEXIT(myexit)