MQ

This is part of a series of small blog posts which will cover some of the smaller, perhaps less likely to be noticed, features of IBM MQ. Read other posts in this series.

Depending on your application requirements, when publishing a message to a topic, you may need to retain a copy of the message that the application publishes for any future subscribers. This post is going to look at when you might use a retained publication, how to create one, and the administrative interfaces involved in working with retained publications.

When you might use a retained publication

A retained publication is useful when your application publishes information that has a decent longevity, but is only published occasionally. Cited examples include a daily weather forecast; the latest price list; or monthly sales targets. This is data that applications would subscribe to, but where new subscribers would like to be able to pick up without waiting for the next publication - it might be a monthly thing after all! By indicating that your publication message is to be retained, a subscriber can come along after the fact and subscribe to topic and be sent your message, hours, days or weeks after you published it. Each time you publish a new message on that topic, and retain it, it replaces the previous retained message.

Coding a retained publication

Here's a small code snippet to illustrate how to publish a message and indicate that it should be retained. I'm using an MQPUT1 in this example for brevity, but you can also use this with an MQOPEN followed by an MQPUT.

pmo.Options = MQPMO_FAIL_IF_QUIESCING
            | MQPMO_NO_SYNCPOINT
            | MQPMO_RETAIN 
ObjDesc.ObjectType            = MQOT_TOPIC;
ObjDesc.Version               = MQOD_VERSION_4;
ObjDesc.ObjectString.VSPtr    = "MyTopicString";
ObjDesc.ObjectString.VSLength = MQVS_NULL_TERMINATED;

MQPUT1(hConn,
       &ObjDesc,
       &MsgDesc,
       &pmo,
       MsgLen,
       Message
       &CompCode,
       &Reason);

All you need to do to indicate that your publication message should be retained, is to code the put message option, MQPMO_RETAIN.

Administration of retained publications

When working with topics that have retained publications, you have a couple of administrative commands that are of interest.

To see whether a topic has a retained publication, you can use the following command.

DISPLAY TPSTATUS('MyTopicString') TYPE(TOPIC) RETAINED

The RETAINED attribute will simply show YES or NO.

If an application has published a retained publication by mistake, or perhaps the data in the retained publication is now out of date and you don't want any more subscribers to be able to receive it, you can remove a retained publication with the following command.

CLEAR TOPICSTR('MyTopicString') CLRTYPE(RETAINED)

Summary

Retained publications are not going to be used by every pub/sub style application, but for certain requirements they are very useful. Now you know how to use them, and how to look after them administratively.