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.

When writing an application that subscribes to a topic, you use the MQSUB verb. There are various options you can choose to provide, to change the way that MQSUB call works. These options can be found in the MQSD (Subscription Descriptor) structure that is passed as parameter 2 on the MQSUB call.

MQSUB(hConn,        /* Connection Handle                  */
      &SubDesc,     /* Subscription Descriptor            */
      &hObj,        /* Object handle for subscriber queue */
      &hSub,        /* Object handle for subscription     */
      &CompCode,    /* Completion Code                    */
      &Reason);     /* Reason Code                        */

In this post I'm going to look at a couple of the main options you might come across and how they can be combined.

Creating a new subscription

When you code an MQSUB call to make a new subscription, you make use of the MQSO_CREATE option. If you choose a durable subscription, using the MQSO_DURABLE option, you also need to provide a subscription name. So you'd have code something like this.

MQSD SubDesc = {MQSD_DEFAULT};
SubDesc.Options = MQSO_CREATE
                | MQSO_DURABLE;
SubDesc.SubName.VSCCSID  = MQCCSI_APPL;
SubDesc.SubName.VSLength = (MQLONG)strlen(ParmSubName);
SubDesc.SubName.VSPtr    = ParmSubName;

If the subscription name you used already existed, you'd be given a MQRC_SUB_ALREADY_EXISTS (2432) reason code.

Resuming an existing subscription

If your application is going to resume a previously created durable subscription, say because the application had been stopped and restarted, then you'd need to provide the subscription name as above, but your options would be slightly different, like this:-

SubDesc.Options = MQSO_RESUME
                | MQSO_DURABLE;

If you used such code and the subscription didn't already exist, you'd be give a MQRC_NO_SUBSRIPTION (2428) reason code.

Handy combination of the subscription options

If you want to write an application that is able to create a durable subscription the first time it runs but resume an existing subscription on subsequent runs, you might imagine that you'd need code that looked something like this:-

MQSD SubDesc = {MQSD_DEFAULT};
SubDesc.SubName.VSCCSID = MQCCSI_APPL;
SubDesc.SubName.VSLength = (MQLONG)strlen(ParmSubName);
SubDesc.SubName.VSPtr = ParmSubName;
SubDesc.Options = MQSO_CREATE
                | MQSO_DURABLE;
MQSUB(hConn,        /* Connection Handle                  */
      &SubDesc,     /* Subscription Descriptor            */
      &hObj,        /* Object handle for subscriber queue */
      &hSub,        /* Object handle for subscription     */
      &CompCode,    /* Completion Code                    */
      &Reason);     /* Reason Code                        */
if (Reason == MQRC_SUB_ALREADY_EXISTS)
{
  SubDesc.Options = MQSO_RESUME
                  | MQSO_DURABLE;

  MQSUB(hConn,        /* Connection Handle                  */
        &SubDesc,     /* Subscription Descriptor            */
        &hObj,        /* Object handle for subscriber queue */
        &hSub,        /* Object handle for subscription     */
        &CompCode,    /* Completion Code                    */
        &Reason);     /* Reason Code                        */
}

However, that's not the case. The IBM MQ queue manager allows you to use the following set of options:-

SubDesc.Options = MQSO_CREATE
                | MQSO_RESUME
                | MQSO_DURABLE;

which means, create the subscription if it doesn't already exist, and resume the subscription if it does already exist. So your application doesn't need to try one way and when it fails, try the other.

With this combination of options, you should never see either of the reason codes, MQRC_SUB_ALREADY_EXISTS (2432) or MQRC_NO_SUBSRIPTION (2428).

So bear this in mind when you're using the MQSO_ options in your next publish/subscribe application.