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.

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.

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.

Wildcard characters in topic strings

• 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 we 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.

We should not use a wildcard character in the topic string of a defined topic object. If you 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);