MQTopic.NET class

Use MQTopic to publish or subscribe messages on a topic, or to query or set attributes of a topic. Create an MQTopic object for publishing or subscribing by using a constructor or the MQQueueManager.AccessTopic method.

Class

System.Object
        |
        └─ IBM.WMQ.MQBase
                |
                └─ IBM.WMQ.MQBaseObject
                        |
                        └─ IBM.WMQ.MQManagedObject
                                |
                                └─ IBM.WMQ.MQDestination
                                        |
                                        └─ IBM.WMQ.MQTopic

public class IBM.WMQ.MQTopic extends IBM.WMQ.MQDestination;

Properties
Methods
Constructors

Properties

Test for MQException being thrown when getting properties.

public Boolean IsDurable {get;}: Read only property that returns True if the subscription is durable or False otherwise. If the topic was opened for publication, the property is ignored and would always return False.
public Boolean IsManaged {get;};: Read only property that returns True if the subscription is managed by the queue manager, or False otherwise. If the topic was opened for publication, the property is ignored and would always return False.
public Boolean IsSubscribed {get;};: Read only property that returns True if the topic was opened for subscription and False if the topic was opened for publication.
public MQSubscription SubscriptionReference {get;};: Read only property that returns the MQSubscription object associated with a topic object opened for subscription. The reference is available if we want to modify the close options or start any of the objects methods.
public MQDestination UnmanagedDestinationReference {get;};: Read only property that returns the MQQueue associated with an unmanaged subscription. It is the destination specified when the topic object was created. The property returns null for any topic objects opened for publication or with a managed subscription.

Methods

public void Put(MQMessage message);

public void Put(MQMessage message, MQPutMessageOptions putMessageOptions);

Throws MQException.

Publishes a message to the topic.

Modifications to the MQMessage object after the Put call has been accomplished do not affect the actual message on the IBM MQ queue or publication topic.

Put updates the MessageId and CorrelationId properties of the MQMessage object and does not clear message data. Further Put or Get calls refer to the updated information in the MQMessage object. For example, in the following code snippet, the first message contains a and the second ab.

msg.WriteString("a");
q.Put(msg,pmo);
msg.WriteString("b");
q.Put(msg,pmo);

message

An MQMessage object containing the message descriptor data, and message to be sent. The message descriptor can be altered as a consequence of this method. The values in the message descriptor immediately after the completion of this method are the values that were put to the queue or published to the topic.

The following reason codes are returned to a reconnectable client:

MQRC_CALL_INTERRUPTED if the connection is broken while running a Put call on a persistent message and the reconnection is successful.
MQRC_NONE if the connection is successful while running a Put call on a non-persistent message (see Application Recovery ).

putMessageOptions

Options controlling the action of the put.

If putMessageOptions is not specified the default instance of MQPutMessageOptons is used.

If we use the MQPMO_LOGICAL_ORDER option in a reconnectable client, the MQRC_RECONNECT_INCOMPATIBLE reason code is returned.

Note: For simplicity and performance, if we want to put a single message to a queue, use MQQueueManager.Put object. We should have an MQQueue object for this.

public void Get(MQMessage message);

public void Get(MQMessage message, MQGetMessageOptions getMessageOptions);

public void Get(MQMessage message, MQGetMessageOptions getMessageOptions, int MaxMsgSize);

Throws MQException.

Retrieves a message from the topic.

This method uses a default instance of MQGetMessageOptions to do the get. The message option used is MQGMO_NOWAIT.

If the get fails, the MQMessage object is unchanged. If it succeeds, the message descriptor and message data portions of the MQMessage are replaced with the message descriptor and message data from the incoming message.

All calls to IBM MQ from a particular MQQueueManager are synchronous. Therefore, if you perform a get with wait, all other threads using the same MQQueueManager are blocked from making further IBM MQ calls until the Get call is accomplished. For multiple threads to access IBM MQ simultaneously, each thread must create its own MQQueueManager object.

message

Contains the message descriptor and the returned message data. Some of the fields in the message descriptor are input parameters. It is important to ensure that the MessageId and CorrelationId input parameters are set as required.

A reconnectable client returns the reason code MQRC_BACKED_OUT after successful reconnection, for messages received under MQGM_SYNCPOINT.

getMessageOptions

Options controlling the action of the get.

Use option MQC.MQGMO_CONVERT might result in an exception with reason code MQC.MQRC_CONVERTED_STRING_TOO_BIG when converting from single-byte character codes to double byte codes. In this case, the message is copied into the buffer without conversion.

If getMessageOptions is not specified, the message option used is MQGMO_NOWAIT.

If we use the MQGMO_LOGICAL_ORDER option in a reconnectable client, the MQRC_RECONNECT_INCOMPATIBLE reason code is returned.

MaxMsgSize

The largest message this message object is to receive. If the message on the queue is larger than this size, one of two things occurs:

If the MQGMO_ACCEPT_TRUNCATED_MSG flag is set in the MQGetMessageOptions object, the message is filled with as much of the message data as possible. An exception is thrown with the MQCC_WARNING completion code and MQRC_TRUNCATED_MSG_ACCEPTED reason code.
If the MQGMO_ACCEPT_TRUNCATED_MSG flag is not set, the message remains on the queue. An exception is thrown with the MQCC_WARNING completion code and MQRC_TRUNCATED_MSG_FAILED reason code.

If MaxMsgSize is not specified, the whole message is retrieved.

Constructors

public MQTopic(MQQueueManager queueManager, MQDestination destination, string topicName, string topicObject, int options);

public MQTopic(MQQueueManager queueManager, MQDestination destination, string topicName, string topicObject, int options, string alternateUserId);

public MQTopic(MQQueueManager queueManager, MQDestination destination, string topicName, string topicObject, int options, string alternateUserId, string subscriptionName);

public MQTopic(MQQueueManager queueManager, MQDestination destination, string topicName, string topicObject, int options, string alternateUserId, string subscriptionName, System.Collections.Hashtable properties);

public MQTopic(MQQueueManager queueManager, string topicName, string topicObject, int openAs, int options);

public MQTopic(MQQueueManager queueManager, string topicName, string topicObject, int openAs, int options, string alternateUserId);

public MQTopic(MQQueueManager queueManager, string topicName, string topicObject, int options, string alternateUserId, string subscriptionName);

public MQTopic(MQQueueManager queueManager, string topicName, string topicObject, int options, string alternateUserId, string subscriptionName, System.Collections.Hashtable properties);

Access a topic on queueManager.

MQTopic objects are closely related to administrative topic objects, which are sometimes called topic objects. On input, topicObject points to an administrative topic object. The MQTopic constructor obtains a topic string from the topic object and combines it with topicName to create a topic name. Either or both topicObject or topicName can be null. The topic name is matched to the topic tree, and the name of the closest matching administrative topic object is returned in topicObject.

The topics that are associated with the MQTopic object are the result of combining two topic strings. The first topic string is defined by the administrative topic object identified by topicObject. The second topic string is topicString. The resulting topic string associated with the MQTopic object can identify multiple topics by including wildcards.

Depending on whether the topic is opened for publishing or subscribing, we can use the MQTopic.Put methods to publish on topics, or MQTopic.Get methods to receive publications on topics. To publish and subscribe to the same topic, we must access the topic twice, once for publish and once for subscribe.

If you create an MQTopic object for subscription, without providing an MQDestination object, a managed subscription is assumed. If you pass a queue as an MQDestination object, an unmanaged subscription is assumed. We must ensure the subscription options you set are consistent with the subscription being managed or unmanaged.

queueManager: Queue manager to access a topic on.

destination

destination is an MQQueue instance. By providing destination, MQTopic is opened as an unmanaged subscription. Publications on the topic are delivered to the queue accessed as destination.

topicName

A topic string that is the second part of the topic name. topicName is concatenated with the topic string defined in the topicObject administrative topic object. We can set topicName to null, in which case the topic name is defined by the topic string in topicObject.

topicObject

On input, topicObject is the name of the topic object that contains the topic string that forms the first part of the topic name. The topic string in topicObject is concatenated with topicName. The rules for constructing topic strings are defined in Combining topic strings.

On output, topicObject contains the name of the administrative topic object that is the closest match in the topic tree to the topic identified by the topic string.

openAs

Access the topic to publish or subscribe. The parameter can contain only one of these options:

MQC.MQTOPIC_OPEN_AS_SUBSCRIPTION
MQC.MQTOPIC_OPEN_AS_PUBLICATION

options

Combine the options that control the opening of the topic for either publication or subscription. Use MQC.MQSO_* constants to access a topic for subscription and MQC.MQOO_* constants to access a topic for publication.

If more than one option is required, add the values together, or combine the option values using the bitwise OR operator.

alternateUserId

Specify the alternate user ID that is used to check for the required authorization to finish the operation. We must specify alternateUserId, if either MQC.MQOO_ALTERNATE_USER_AUTHORITY or MQC.MQSO_ALTERNATE_USER_AUTHORITY is set in the options parameter.

subscriptionName

subscriptionName is required if the options MQC.MQSO_DURABLE or MQC.MQSO_ALTER are provided. In both cases, MQTopic is implicitly opened for subscription. An exception is thrown if the MQC.MQSO_DURABLE is set, and the subscription exists, or if MQC.MQSO_ALTER is set, and the subscription does not exist.

properties

Set any of the special subscription properties listed using a hash table. Specified entries in the hash table are updated with output values. Entries are not added to the hash table to report output values.

MQC.MQSUB_PROP_ALTERNATE_SECURITY_ID
MQC.MQSUB_PROP_SUBSCRIPTION_EXPIRY
MQC.MQSUB_PROP_SUBSCRIPTION_USER_DATA
MQC.MQSUB_PROP_SUBSCRIPTION_CORRELATION_ID
MQC.MQSUB_PROP_PUBLICATION_PRIORITY
MQC.MQSUB_PROP_PUBLICATION_ACCOUNTING_TOKEN
MQC.MQSUB_PROP_PUBLICATION_APPLICATIONID_DATA

public MQTopic MQQueueManager.AccessTopic(MQDestination destination, string topicName, string topicObject, int options);

public MQTopic MQQueueManager.AccessTopic(MQDestination destination, string topicName, string topicObject, int options, string alternateUserId);

public MQTopic MQQueueManager.AccessTopic(MQDestination destination, string topicName, string topicObject, int options, string alternateUserId, string subscriptionName);

public MQTopic MQQueueManager.AccessTopic(MQDestination destination, string topicName, string topicObject, int options, string alternateUserId, string subscriptionName, System.Collections.Hashtable properties);

public MQTopic MQQueueManager.AccessTopic(string topicName, string topicObject, int openAs, int options);

public MQTopic MQQueueManager.AccessTopic(string topicName, string topicObject, int openAs, int options, string alternateUserId);

public MQTopic MQQueueManager.AccessTopic(string topicName, string topicObject, int options, string alternateUserId, string subscriptionName);

public MQTopic MQQueueManager.AccessTopic(string topicName, string topicObject, int options, string alternateUserId, string subscriptionName, System.Collections.Hashtable properties);

Access a topic on this queue manager.