Using topic strings
A topic is constructed from the subtopic identified in a topic object, and a subtopic provided by an application. You 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:
- The TOPICSTR attribute of the topic object, named in the ObjectName field.
- 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.
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
".
- plus sign '
+
' - number sign '
#
' - asterisk '
*
' - question mark '
?
'
#
' 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);