WebSphere MQ Everyplace messages are descendant objects of MQeFields, as described in Fundamental objects. Applications can put data into the message as a <name, data> pairing.
MQeMessages are specializations of MQeFields objects, therefore the functions that are applicable to MQeFields can be used with MQeMessage. An example of creating a message plus adding a fields is shown below. This is a function from one of the examples:
MQERETURN creatAMessage(MQeExceptBlock *pErrorBlock, MQeMsgHndl * phOutMsg) { MQERETURN rc; /* create a message obj */ rc = mqeMsg_new(pErrorBlock, phOutMsg); if (MQERETURN_OK == rc) { MQeStringHndl hDataFieldName; rc = mqeString_newChar8(pErrorBlock, &DataFieldName, "myData"); if (MQERETURN_OK == rc) { /* put some data in */ rc = mqeFields_putInt32((MQeFieldsHndl)*phOutMsg, pErrorBlock, hDataFieldName, 1); } else { displayError("new MQeString error (for data field name)", pErrorBlock); } } else { displayError("new MQeMsg error", pErrorBlock); } return rc; }
This shows a message being created, a new field name being created, and an integer being placed into the field. The field can be retrieved using the mqeField_getXXX functions.
WebSphere MQ Everyplace defines some constant field names that are useful to messaging applications. These are:
The Unique ID is a combination of a unique (per process) timestamp generated by the message object when it is created, and the name of the queue manager to which the message was first given. The Unique ID is used by applications to retrieve messages. It cannot be changed by an application.
The Unique ID uniquely identifies a message within an WebSphere MQ Everyplace network so long as all queue managers within the WebSphere MQ Everyplace network are named uniquely.
The mqeMsg_getMsgUIDFields() function accesses the Unique ID of a message:
The mqeMsg_getMsgUIDFields() function returns an MQeFields object that contains two fields,
These fields can be individually retrieved as follows:
The WebSphere MQ Message ID and Correlation ID fields allow the application to provide an identity for a message. These two fields are also used in interactions with the rest of the WebSphere MQ family.
The Priority field contains message priority values. Message priority is defined in the same way as in other members of the WebSphere MQ family. It ranges from 9 (highest) to 0 (lowest). Applications use this field to deal with a message according to its priority.
Most queue types hold messages in a persistent store. While in the store, the state of the message varies as it is transferred into and out of the store. As shown in Figure 7:
Figure 7. Stored message state flow
The possible message states are:
Messages pass from one state to another as a result of an event. The possible message events (as shown in Figure 7) are:
More detailed descriptions of message events and states are included in Assured message delivery, and Browse and Lock and
Due to memory size constraints, complete messages are not held in memory, but, to enable faster message searching, WebSphere MQ Everyplace holds specific fields from each message in a message index. The fields that are held in the index are:
Providing these fields in a filter makes searching more efficient, since WebSphere MQ Everyplace may not have to load all the available messages into memory.
The concept of filters allows WebSphere MQ Everyplace to perform powerful message searches. Most of the major queue manager operations support the use of filters. The mqeQueueManager_getMessage function has an MQeFields parameter. This Fields object is the filter. If you pass 'null' in then no filter is used.
The use of a filter causes an application to return the first available message that contains the same fields and values as the filter. An example of using a filter on a getMessage() function is in Application example Ex2.
When a filter is applied to a search, the fields in the filter are compared with each index entry in turn. If a field is common to both the index entry and the filter, and the values in the field are different, then the message cannot possibly match the filter and it is excluded from consideration. If a field is not common to both filter and index entry, or if the field is common and the values are the same, then the message is included in the search.
Queues can be defined with an expiry interval. If a message has remained on a queue for a period of time longer than this interval then the message is marked as expired.
Messages can also have an expiry interval that overrides the value of any queue expiry interval. You can define this by adding an MQE_MSG_EXPIRETIME field to the message. The expiry time is either relative (expire 2 days after the message was created), or absolute (expire on November 25th 2000, at 08:00 hours).
To set a relative expiry time use the following on a message handle:
mqeFields_putInt32(pErrorBlock, hMsg, relativeTime);
To set an absolute expiry time use:
mqeFields_putInt64(pErrorBlock,hMsg, absoluteTime);
All Times are in milliseconds