Messages

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:

Unique ID
MQE_MSG_ORIGIN_QMGR + MQE_MSG_TIME

Message ID
MQE_MSG_MSGID

Correlation ID
MQE_MSG_CORRELID

Priority
MQE_MSG_PRIORITY

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.

Note:
WebSphere MQ Everyplace does not check or enforce the uniqueness of queue manager names. It is the responsibility of an individual solution to ensure that its queue manager names are unique.

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.

Storing messages

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

Diagram showing stored message status flow

Message states

The possible message states are:

Start
The initial state of a message before it is added to the message store.

Put Unconfirmed
A message has been placed in the message store under a confirmID but its addition has not been confirmed. The message is effectively hidden from all actions except confirmPutMessage, confirm, or undo.

Unlocked
A message has been added to the message store. There is no lock on it, and it is visible to all queries.

Locked for Browse
A browse with lock has retrieved the message. The message is now hidden from all queries except getMessage, unlockMessage, and undo.

Get Unconfirmed
A get message has been made with a confirmID but the get has not been confirmed. The message is invisible to all queries except confirmGetMessage, confirm, or undo. Each of these actions requires the matching confirmID to be included to confirm the get.

Browse Get Unconfirmed
A message has been got while it is locked for browse. This can only be done by passing the correct lockID to the getMessage function.

Deleted
The final state, after a message has been removed from the database.

Message events

Messages pass from one state to another as a result of an event. The possible message events (as shown in Figure 7) are:

putMessage
Message placed on message store, no confirm required.

getMessage
Message retrieved from message store, no confirm required.

putMessage with confirmId>0
Message placed on message store, confirm required.

confirmPutMessage
A confirm for an earlier putMessage with confirmId>0.

getMessage with confirmId>0
Message retrieved from message store, confirm required.

confirmGetMessage
A confirm for an earlier getMessage with confirmId>0.

browseWithLock
Browse messages and lock those that match. Prevents messages changing while browse is in operation.

unlockMessage
Unlock a message locked with a browsewithLock command.

undo
Unlock a message locked with a browse, or undo a getMessage with confirmId>0 or putMessage with confirmId>0.

deleteMessage
Remove a message from the message store.

More detailed descriptions of message events and states are included in Assured message delivery, and Browse and Lock and

Message index fields

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:

Unique ID
MQE_MSG_ORIGIN_QMGR + MQE_MSG_TIME

Message ID
MQE_MSG_MSGID

Correlation ID
MQE_MSG_CORRELID

Priority
MQE_MSG_PRIORITY

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.

Filters

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.

Message Expiry

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



© IBM Corporation 2002. All Rights Reserved