Configuring streaming queues

The streaming queues feature allows you to have a duplicate copy of each message put to a queue, delivered to a second queue. Configuration of streaming queues is done on a queue by queue basis.

Local and model queues have two new attributes related to streaming queues:

STREAMQ

This is the name of the queue to which streamed messages should be delivered. You should set the STREAMQ attribute to the name of another queue.

There are restrictions on which queues can be configured to stream messages to other queues, and there are restrictions on which queues can be set as a destination for streamed messages. For information on message streaming restrictions see Stream queue restrictions.

STRMQOS

This is the quality-of-service to use when delivering streamed messages.

You can set the STRMQOS attribute to one of two values:

BESTEF: Best effort, which is the default value.; The queue manager attempts to deliver a copy of each message to the queue specified in the STREAMQ attribute. If there is a problem delivering the streamed message, this does not affect delivery of the original message.
MUSTDUP: The queue manager attempts to deliver a copy of each message to the streaming queue.; If there is a problem delivering the streamed message, the original message is not delivered to its queue and the application receives MQCC_FAILED along with an appropriate reason code.

See the ALTER queues, DEFINE queues, and DISPLAY QUEUE MQSC commands, and the Change, Copy, and Create Queue, Inquire Queue, and Inquire Queue (Response) PCF commands for more details.

If more than one copy of each message is required, you can configure the STREAMQ attribute to refer to the name of an IBM® MQ alias queue whose target refers to an IBM MQ topic. When a message is put to the original queue, a copy of the message is published to the named topic.

You must ensure you have API or administered subscriptions to the topic object as each subscription receives a copy of the message. The message delivered to subscribers follows the same rules as other publish/subscribe messages. For example, each message has a new message identifier and the context fields of the MQMD are different from those in the original message. For more information on the similarities and differences between original and streamed messages see Streamed messages.

Important: Altering the STREAMQ or STRMQOS attributes is dynamic and will affect existing applications (that is, they might start streaming, or might start streaming to a different queue).

Examples

Best effort example

In the following example, a local queue ORDERS.QUEUE is altered to put streamed messages to a second queue ANALYTICS.QUEUE. The BESTEF quality of service is used to ensure that if there is a problem putting the streamed message to ANALYTICS.QUEUE, for example, if ANALYTICS.QUEUE is full, the original message can still be put to the ORDERS.QUEUE.

This sort of configuration can be used to perform analytics on the orders being received, by analyzing the streamed messages, while the original messages are put to the order queue and are processed. A benefit of the streaming queue feature is that you can leave the streamed messages on the ANALYTICS.QUEUE waiting to be processed, without affecting the actual orders being satisfied by the business.

DEFINE QLOCAL(ANALYTICS.QUEUE)

ALTER
QLOCAL(ORDERS.QUEUE) STRMQOS(BESTEF) STREAMQ(ANALYTICS.QUEUE)

Note: In the example STRMQOS has been set to BESTEF, although you can leave this attribute out of the ALTER command, because BESTEF is the default quality of service.

Must duplicate example

In this example, a local queue PAYMENTS.QUEUE is altered to put streamed copies of every message to another local queue AUDIT.QUEUE. It is important that every message put to the payment queue is streamed to the audit queue, so the MUSTDUP quality of service is used.

If there is a problem delivering the streamed message to its queue, the original message is not delivered either, and the application receives a suitable completion and reason code. The application must retry the put in the same way that it would if there was only a single queue involved.

DEFINE QLOCAL(AUDIT.QUEUE)

ALTER
QLOCAL(PAYMENTS.QUEUE) STRMQOS(MUSTDUP) STREAMQ(AUDIT.QUEUE)

Notes:

It is not necessary for the streaming queue to exist when altering the original queue. However, it is important to note that because the quality of service being used is MUSTDUP, attempts to put messages to the original queue fail until you have defined the streaming queue.
When using a queue alias with a target of a topic object, if there are no subscribers, then delivery of the streamed message is still considered successful, and the original message is delivered to its queue.
If a streamed message cannot be delivered to its queue, the queue manager does not attempt to deliver it to the dead letter queue. However, if a streamed message is sent to a remote queue, when it travels over a channel to another queue manager, it can be delivered to a dead letter queue following existing dead letter rules.

Configuring the streaming queue

No additional configuration needs to be performed on the streaming queue. It receives messages from any queues that name it as a streaming queue. However it might be sensible to consider the attribute values configured on the streaming queue.

For example, if the original queue has a maximum depth of 100,000 and the streaming queue only has a maximum depth of 5000, streamed messages might be lost if STRMQOS is set to BESTEF, or fail at put time if STRMQOS is set to MUSTDUP, with an MQRC_Q_FULL error, even though the original queue has plenty of space left on it.

Consider which attributes on the streaming queue might need to be changed to have appropriate values, based on how the original queue is configured.