Use topic strings

A topic is constructed from the subtopic identified in a topic object, and a subtopic provided by an application. We can use either subtopic as the topic name, or combine them to form a new topic name.

In an MQI program the full topic name is created by MQOPEN. It is composed of two fields used in publish/subscribe MQI calls, in the order listed:

  1. The TOPICSTR attribute of the topic object, named in the ObjectName field.
  2. The ObjectString parameter defining the subtopic provided by the application.

The resulting topic string is returned in the ResObjectString parameter.

These fields are considered to be present if the first character of each field is not a blank or null character, and the field length is greater than zero. If only one of the fields is present, it is used unchanged as the topic name. If neither field has a value, the call fails with reason code MQRC_UNKNOWN_OBJECT_NAME, or MQRC_TOPIC_STRING_ERROR if the full topic name is not valid.

If both fields are present, a ' / ' character is inserted between the two elements of the resultant combined topic name.

Table 1 shows examples of topic string concatenation:

TOPICSTR ObjectString Full topic name Comment
Football/Scores '' Football/Scores The TOPICSTR is used alone
'' Football/Scores Football/Scores The ObjectString is used alone
Football Scores Football/Scores A '/' character is added at the concatenation point
Football /Scores Football//Scores An 'empty node' is produced between the two strings
/Football Scores /Football/Scores The topic starts with an 'empty node'

The ' / ' character is considered as a special character, providing structure to the full topic name in Topic trees, and must not be used for any other reason as the structure of the topic tree is affected. The topic " /Football " is not the same as the topic " Football ".

The following wildcard characters are special characters:

  • plus sign ' + '
  • number sign ' # '
  • asterisk ' * '
  • question mark ' ? '

These characters are not considered as invalid, however we must ensure to understand how they are used. We might prefer not to use these characters in your topic strings when publishing. Publishing on a topic string with ' # ' or ' + ' mixed in with other characters (including themselves) within a topic level, can be subscribed to with either wildcard scheme. Publishing on a topic string with ' # ' or ' + ' as the only character between two ' / ' characters produces a topic string that cannot be subscribed to explicitly by an application using the wildcard scheme MQSO_WILDCARD_TOPIC. This situation results in the application getting more publications than expected.


Example code snippet

This code snippet, extracted from the example program Example 2: Publisher to a variable topic, combines a topic object with a variable topic string. 
MQOD     td = {MQOD_DEFAULT};  /* Object Descriptor          */
td.ObjectType = MQOT_TOPIC;    /* Object is a topic          */
td.Version = MQOD_VERSION_4;   /* Descriptor needs to be V4  */
strncpy(td.ObjectName, topicName,  MQ_TOPIC_NAME_LENGTH);
td.ObjectString.VSPtr = topicString;
td.ObjectString.VSLength = (MQLONG)strlen(topicString);
td.ResObjectString.VSPtr = resTopicStr;
td.ResObjectString.VSBufSize = sizeof(resTopicStr)-1;
MQOPEN(Hconn, &td, MQOO_OUTPUT | MQOO_FAIL_IF_QUIESCING, &Hobj, &CompCode, &Reason);
Parent topic: MQSD - Subscription descriptor