Workload balancing

 

When you have clusters containing more than one instance of the same queue, WebSphere MQ uses a workload management algorithm to determine the best queue manager to route a message to. The workload management algorithm selects the local queue manager as the destination whenever possible. If there is no instance of the queue on the local queue manager, the algorithm determines which destinations are suitable. Suitability is based on the state of the channel (including any priority you might have assigned to the channel), and also the availability of the queue manager and queue. The algorithm uses a round-robin approach to finalize its choice between the suitable queue managers.

 

Cluster workload user exit

In most cases the workload management algorithm will be 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.

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

The cluster workload exit is called when a cluster queue is opened using the MQOPEN or MQPUT1 call, and when a message is put to a queue using the MQPUT call. The target queue manager selected at MQOPEN time is fixed if MQOO_BIND_ON_OPEN is specified. In this case, even if the target queue manager fails, the exit is not run again. In cases where the target queue manager is not fixed, if the target queue manager chosen at the time of an MQPUT call is unavailable, or fails while the message is still on the transmission queue, the exit is called again to select a new target queue manager.

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

ALTER QMGR CLWLEXIT(myexit)

On platforms other than z/OS, the queue manager will load the new CLWLEXIT the next time the queue manager is started.

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

Cluster workload exits are called with an exit parameter structure (MQWXP), a message definition structure (MQMD), a message length parameter, and a copy of the message (or part of the message). See Chapter 10, Cluster workload exit call and data structures for reference information about the cluster workload exit and the associated data structures.

For more information on using your own cluster workload exit see Chapter 11, Using your own cluster workload exits

 

Writing and compiling cluster workload exit programs

The following guidance applies specifically to cluster workload exit programs. Read it in conjunction with the general application-programming guidance given in the WebSphere MQ Application Programming Guide.

 

WebSphere MQ for z/OS

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 WebSphere MQ for z/OS, the following rules apply:

  • You must write exits must be written in assembler or C. If you use C, it must conform to the C systems programming environment for system exits, described in the z/OS C/C++ Programming Guide, SC09-2362.

  • 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 when 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 it will be freed by a subsequent exit invocation.

  • No MQI calls are allowed.

  • Exits must not use any system services that could cause a wait, because this would severely degrade the performance of the queue manager. In general, therefore, avoid SVCs, PCs, and I/O.

  • Exits must not issue ESTAEs or SPIEs, apart from within any subtasks they attach.

Note that there are no absolute restrictions on what you can do in an exit. However, most SVCs involve waits, so avoid them, except for the following:

  • GETMAIN/FREEMAIN

  • LOAD/DELETE

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

The system parameter EXITLIM, which is described in the WebSphere MQ for z/OS System Setup Guide, limits the amount of time an exit may 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 may be looping. If you think the exit needs more than 30 seconds to complete, increase the value of EXITLIM.

 

MQSeries for Compaq OpenVMS Alpha

When linking a workload exit on Compaq OpenVMS Alpha, specify the following in the linker options file: 

sys$share:mqm/share 
sys$share:mqutl/share
SYMBOL_VECTOR=(clwlFunction=PROCEDURE,MQStart=PROCEDURE)

You need a system-wide executive logical name to reference the exit image. For example, if the exit name is SYS$SHARE:AMQSWLM.EXE, define the following logical name: 

$DEFINE/SYSTEM/EXEC AMQSWLM SYS$SHARE:AMQSWLM

Do not specify the .EXE file extension in the logical name definition.

For this logical name to be defined during system startup, define it in SYS$MANAGER:MQS_SYSTARTUP.COM.

 

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 similar to the rules that apply to channel exit programs. These are described in detail in the WebSphere MQ Intercommunication book.

For information about building your application, see the WebSphere MQ Application Programming Guide and the WebSphere MQ Intercommunication book. However you need to resolve the MQXCLWLN function by linking with the mqutl library on Windows NT or the libmqutl library on the UNIX platforms.

 

Sample cluster workload exit

WebSphere MQ includes a sample cluster workload exit program. You can copy this sample and use it as a basis for your own programs.

WebSphere MQ for z/OS
The sample cluster workload exit program is supplied in Assembler and in C. The Assembler version is called CSQ4BAF1 and can be found in the library thlqual.SCSQASMS. The C version is called CSQ4BCF1 and can be found in the library thlqual.SCSQC37S. (thlqual is the target library high-level qualifier for WebSphere MQ data sets in your installation.)

On platforms other than z/OS
The sample cluster workload exit program is supplied in C and is called amqswlm0.c. It can be found in:

Table 3. Sample cluster workload exit program location (not z/OS)

AIX /usr/mqm/samp
Compaq Tru64 UNIX, HP-UX, and Sun Solaris /opt/mqm/samp
OS/2 Warp C:\mqm\tools\c\samples
Windows C:\Program Files\Websphere MQ\Tools\c\Samples

(Where C is the drive on which you have installed the product.)

iSeries The qmqm library
Compaq OpenVMS Alpha sys&sysroot:[syshlp.examples.mqseries.bin]
Compaq NonStop Kernel $volume.ZMQSSMPL

(Where $volume is the drive on which you have installed MQSeries.)

This sample exit routes all messages to a particular queue manager, unless that queue manager becomes unavailable. It reacts to the failure of the queue manager by routing messages to another queue manager.

You indicate which queue manager you want messages to be sent to by supplying the name of its cluster-receiver channel in the CLWLDATA attribute on the queue-manager definition. For example: 

ALTER QMGR CLWLDATA('TO.myqmgr')

To enable the exit, supply its full path and name in the CLWLEXIT attribute:

On UNIX systems: 

ALTER QMGR CLWLEXIT('path/amqswlm(clwlFunction)')

On OS/2 Warp and Windows NT: 

ALTER QMGR CLWLEXIT('path\amqswlm(clwlFunction)')

On z/OS: 

ALTER QMGR CLWLEXIT(CSQ4BxF1)

where x is either 'A' or 'C', depending on the programming language of the version you are using.

On OS/400(R):

Enter the MQSC command: 

ALTER QMGR CLWLEXIT('AMQSWLM   library   ')

(both the program name and the library name occupy 10 characters and are blank-padded to the right if necessary). Alternatively, use the CL command: 

CHGMQM MQMNAME(qmgrname) CLWLEXIT('library/AMQSWLM')

Now, instead of using the supplied workload management algorithm, WebSphere MQ calls this exit to route all messages to your chosen queue manager.

On Compaq OpenVMS Alpha: 

ALTER QMGR CLWLEXIT('sys$share:AMQSWLM(clwlFunction)')

On Compaq NonStop Kernel: 

ALTER QMGR CLWLEXIT('$volume.subvol.amqswlm(clwlFunction)')

 

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

 

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.

 

AIX is a trademark of the IBM Corporation in the United States, other countries, or both.