Handling messages

Messages are handled using the methods of the queue or topic classes. To build a new message, create a new MQMessageobject.

Put messages onto queues or topics using the Put() method of the MQQueue or MQTopic class. Get messages from queues or topics using the Get() method of the MQQueue or MQTopic class. Unlike the procedural interface, where MQPUT and MQGET put and get arrays of bytes, the IBM MQ classes for .NET put and get instances of the MQMessage class. The MQMessage class encapsulates the data buffer that contains the actual message data, together with all the MQMD (message descriptor) parameters that describe that message.

To build a new message, create a new instance of the MQMessage class and use the WriteXXX methods to put data into the message buffer.

When the new message instance is created, all the MQMD parameters are automatically set to their default values, as defined in Initial values and language declarations for MQMD. The Put() method of MQQueue also takes an instance of the MQPutMessageOptions class as a parameter. This class represents the MQPMO structure. The following example creates a message and puts it onto a queue:

// Build a new message containing my age followed by my name
MQMessage myMessage = new MQMessage();
myMessage.WriteInt(25);

String name = "Charlie Jordan";
myMessage.WriteUTF(name);

// Use the default put message options...
MQPutMessageOptions pmo = new MQPutMessageOptions();

// put the message
!queue.Put(myMessage,pmo);

The Get() method of MQQueue returns a new instance of MQMessage, which represents the message just taken from the queue. It also takes an instance of the MQGetMessageOptions class as a parameter. This class represents the MQGMO structure.

You do not need to specify a maximum message size, because the Get() method automatically adjusts the size of its internal buffer to fit the incoming message. Use the ReadXXX methods of the MQMessage class to access the data in the returned message.

The following example shows how to get a message from a queue:

// Get a message from the queue
MQMessage theMessage    = new MQMessage();
MQGetMessageOptions gmo = new MQGetMessageOptions();
queue.Get(theMessage,gmo);  // has default values
 
// Extract the message data
int age = theMessage.ReadInt();
String name1 = theMessage.ReadUTF();

We can alter the number format that the read and write methods use by setting the encoding member variable.

We can alter the character set to use for reading and writing strings by setting the characterSet member variable.

See MQMessage.NET class for more details.

Note: The WriteUTF() method of MQMessage automatically encodes the length of the string as well as the Unicode bytes it contains. When your message will be read by another .NET program (using ReadUTF()), this is the simplest way to send string information.

Handling message properties
Message properties allow you to select messages, or to retrieve information about a message without accessing its headers. The MQMessage class contains methods to get and set properties.

Parent topic: Writing and deploying IBM MQ .NET programs