MQI and clusters

 

The following WebSphere MQ application programming interface (API) calls have options to help use clusters:

The options on these calls that relate specifically to clustering are described here. This information should be read in conjunction with the WebSphere MQ Application Programming Reference book, which describes each call in full.

The remainder of this chapter contains general-use programming interface information.

 

MQOPEN

An option on the MQOPEN call, the MQOO_BIND_ON_OPEN option, allows you to specify that, when there are multiple instances of the same queue within a cluster, the target queue manager needs to be fixed. That is, all messages put to the queue specifying the object handle returned from the MQOPEN call must be directed to the same queue manager using the same route.

Use this option when you have messages with affinities. For example, if you need a batch of messages all to be processed by the same queue manager, specify MQOO_BIND_ON_OPEN when you open the queue. WebSphere MQ fixes the queue manager and the route to be taken by all messages put to that queue.

If you do not want to force all your messages to be written to the same destination, specify MQOO_BIND_NOT_FIXED on the MQOPEN call. This selects a destination at MQPUT time, that is, on a message-by-message basis.

Note:
Do not specify MQOO_BIND_NOT_FIXED and MQMF_SEGMENTATION_ALLOWED at the same time. If you do, the segments of your message might all be delivered to different queue managers, scattered throughout the cluster.

If you do not specify either MQOO_BIND_ON_OPEN or MQOO_BIND_NOT_FIXED, the default option is MQOO_BIND_AS_Q_DEF. Using MQOO_BIND_AS_Q_DEF causes the binding that is used for the queue handle to be taken from the DefBind queue attribute. See Queue definition commands.

You can also choose a destination queue manager, by specifying its name in the object descriptor on the MQOPEN call. In this way, you can select any queue manager, including the local one.

If you specify one or more of the options MQOO_BROWSE, MQOO_INPUT_*, or MQOO_SET on the MQOPEN call, there must be a local instance of the cluster queue for the open to succeed. If you specify one or more of the options MQOO_OUTPUT, MQOO_BIND_*, or MQOO_INQUIRE on the MQOPEN call, and none of the options MQOO_BROWSE, MQOO_INPUT_*, or MQOO_SET (which always select the local instance) the instance opened is either:

  • The instance on the local queue manager, if there is one, or

  • An instance elsewhere in the cluster, if there is no local queue-manager instance

For full details about the MQOPEN call and how to use it, see the WebSphere MQ Application Programming Reference book.

 

Resolved queue manager name

When a queue manager name is resolved at MQOPEN time, the resolved name is returned to the application. If the application tries to use this name on a subsequent MQOPEN call, it might find that is it not authorized to access the name.

 

MQPUT and MQPUT1

If MQOO_BIND_NOT_FIXED is specified on an MQOPEN call, each subsequent MQPUT call invokes the workload management routine to determine which queue manager to send the message to. The destination and route to be taken are selected on a message-by-message basis. The destination and route might change after the message has been put if conditions in the network change. The MQPUT1 call always operates as though MQOO_BIND_NOT_FIXED were in effect, that is, it always invokes the workload management routine.

When the workload management routine has selected a queue manager, the local queue manager completes the put operation. If the target queue manager is a member of the same cluster as the local queue manager, the local queue manager puts the message on the cluster transmission queue, SYSTEM.CLUSTER.TRANSMIT.QUEUE, for transmission to the destination. If the target queue manager is outside the cluster, and the local queue manager has a transmission queue with the same name as the target queue manager, it puts the message on that transmission queue.

If MQOO_BIND_ON_OPEN is specified on the MQOPEN call, MQPUT calls do not need to invoke the workload management routine because the destination and route have already been selected.

 

MQINQ

Before you can inquire on a queue, open it using the MQOPEN call and specifying MQOO_INQUIRE.

If you have clusters in which there are multiple instances of the same queue, the attributes that can be inquired depend on whether there is a local instance of the cluster queue, and on how the queue is opened.

If, on the MQOPEN call, in addition to specifying MQOO_INQUIRE, you also specify one of the options MQOO_BROWSE, MQOO_INPUT_*, or MQOO_SET, there must be a local instance of the cluster queue for the open to succeed. In this case you can inquire on all the attributes that are valid for local queues.

If, on the MQOPEN call, you specify only MQOO_INQUIRE, or MQOO_INQUIRE and MQOO_OUTPUT (but specify none of the options MQOO_BROWSE, MQOO_INPUT_*, or MQOO_SET, which always cause the local instance of a cluster queue to be selected), the instance opened is either:

  • The instance on the local queue manager, if there is one, or

  • An instance elsewhere in the cluster, if there is no local queue-manager instance

If the queue that is opened is not a local queue, only the attributes listed below can be inquired. The QType attribute has the value MQQT_CLUSTER in this case.

  • DefBind

  • DefPersistence

  • DefPriority

  • InhibitPut

  • QDesc

  • QName

  • QType

To inquire on the DefBind attribute of a cluster queue, use the MQINQ call with the selector MQIA_DEF_BIND. The value returned is either MQBND_BIND_ON_OPEN or MQBND_BIND_NOT_FIXED. To inquire on the CLUSTER and CLUSNL attributes of the local instance of a queue, use the MQINQ call with the selector MQCA_CLUSTER_NAME or the selector MQCA_CLUSTER_NAMELIST respectively.

Note:
If you open a cluster queue with no fixed binding (that is, specifying MQOO_BIND_NOT_FIXED on the MQOPEN call, or specifying MQOO_BIND_AS_Q_DEF when the DefBind attribute of the queue has the value MQBND_BIND_NOT_FIXED), successive MQINQ calls might inquire different instances of the cluster queue.

 

MQSET

If you open a cluster queue to set its attributes (specifying the MQOO_SET option), there must be a local instance of the cluster queue for the open to succeed. You cannot use the MQSET call to set the attributes of a queue elsewhere in the cluster. However, if you open an alias queue or a remote queue defined with the cluster attribute, you can use the MQSET call to set attributes of the alias queue or remote queue even if the target queue or remote queue it resolves to is a cluster queue.

 

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.