Combining topic strings

When creating subscriptions, or opening topics so we can publish messages to them, the topic string can be formed by combining two separate sub-topic strings, or subtopics. One subtopic is provided by the application or administrative command as a topic string, and the other is the topic string associated with a topic object. We can use either subtopic as the topic string on its own, or combine them to form a new topic name.

For example, when you define a subscription using the MQSC command DEFINE SUB, the command can take either TOPICSTR (topic string) or TOPICOBJ (topic object) as an attribute, or both together. If only TOPICOBJ is provided, the topic string associated with that topic object is used as the topic string. If only TOPICSTR is provided, that is used as the topic string. If both are provided, they are concatenated to form a single topic string in the form TOPICOBJ / TOPICSTR, where the TOPICOBJ configured topic string is always first and the two parts of the string are always separated by a / character.

Similarly, 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:
Table 1. Topic string concatenation examples
TOPICSTR of the topic object Topic string provided by application or DEFINE SUB command Full topic name Comment
Football/Scores '' Football/Scores The TOPICSTR of the topic object is used alone.
'' Football/Scores Football/Scores The ObjectString/TOPICSTR 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. This is different to Football/Scores.
/Football Scores /Football/Scores The topic starts with an 'empty node'. This is different to Football/Scores.

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

Note: If we use a topic object when creating a subscription, the value of the topic object topic string is fixed in the subscription at define time. Any subsequent change to the topic object does not affect the topic string that the subscription is defined to.


Wildcard characters in topic strings

The following wildcard characters are special characters:

  • plus sign ( +)
  • number sign ( #)
  • asterisk ( *)
  • question mark ( ?)
Wildcard characters only have special meaning when used by a subscription. These characters are not considered as invalid when used elsewhere, however you must ensure you understand how they are used and you might prefer not to use these characters in your topic strings when publishing or defining topic objects.

If you publish on a topic string with # or + mixed in with other characters (including themselves) within a topic level, the topic string can be subscribed to with either wildcard scheme.

If you publish on a topic string with # or + as the only character between two / characters, the topic string 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.

You should not use a wildcard character in the topic string of a defined topic object. If we do this, the character is treated as a literal character when the object is used by a publisher, and as a wildcard character when used by a subscription. This can lead to confusion.


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);