Messages are simply collections of data sent by one application and intended for another application. WebSphere MQ Everyplace messages contain application-defined content. When stored, they are held in a queue and such messages may be moved across a WebSphere MQ Everyplace network.
WebSphere MQ Everyplace messages are a special type of MQeFields items, as described in MQeFields. Therefore, you can use methods that are applicable to MQeFields with messages.
Therefore, messages are Fields objects with the addition of some special fields. Java provides a subclass of MQeFields, MQeMsgObject which provides methods to manage these fields. The C codebase does not provide such a subclass. Instead, there are a number of mqeFieldsHelper_operation functions. The following fields form the Unique ID of a WebSphere MQ Everyplace message:
The Unique ID identifies a message within a WebSphere MQ Everyplace network provided all queue managers within the WebSphere MQ Everyplace network are named uniquely. However, WebSphere MQ Everyplace does not check or enforce the uniqueness of queue manager names.
In Java, the message is created when an instance of MQeMsgObject is created. In C, the Message is "created", that is UniqueID fields are added, when the message is put to a queue.
The getMsgUIDFields()method or mqeFieldsHelpers_getMsgUidFields() function accesses the UniqueID of a message, for example:
MQeFields msgUID = msgObj.getMsgUIDFields();
rc = mqeFieldsHelpers_getMsgUidFields(hMgsObj, &exceptBlock,&hUIDFields);
WebSphere MQ Everyplace adds property related information to a message (and subsequently removes it) in order to implement messaging and queuing operations. When sending a message between queue managers, you can add resend information to indicate that data is being retransmitted.
Typical application-based messages have additional properties in accordance
with their purpose. Some of these additional properties are generic and
common to many applications, such as the name of the reply-to queue
manager. Therefore, WebSphere MQ Everyplace supports the following
message properties:
Property name | Java type | C type | Description |
---|---|---|---|
Action | int | MQEINT32 | Used by administration to indicate actions such as inquire, create, and delete |
Correlation ID | byte[] | MQEBYTE[] | Byte string typically used to correlate a reply with the original message |
Errors | MQeFields | MQeFieldsHndl | Used by administration to return error information |
Expire time | int or long | MQEINT32 or MQEINT64 | Time after which the message can be deleted (even if it is not delivered) |
Lock ID | long | MQEINT64 | The key necessary to unlock a message |
Message ID | byte[] | MQEBYTE[] | A unique identifier for a message |
Originating queue manager | string | MQeStringHndl | The name of the queue manager that sent the message |
Parameters | MQeFields | MQeFieldsHndl | Used by administration to pass administration details |
Priority | byte | MQEBYTE | Relative order of priority for message transmission |
Reason | string | MQeStringHndl | Used by administration to return error information |
Reply-to queue | string | MQeStringHndl | Name of the queue to which a message reply should be addressed |
Reply-to queue manager | string | MQeStringHndl | Name of the queue manager to which a message reply should be addressed |
Resend | boolean | MQEBOOL | Indicates that the message is a resend of a previous message |
Return code | byte | MQEBYTE | Used by administration to return the status of an administration operation |
Style | byte | MQEBYTE | Distinguishes commands from request/reply for example |
Wrap message | byte[] | MQEBYTE[] | Message wrapped to ensure data protection |
The following table lists the symbolic names corresponding to the message
properties given in the previous table.
Table 2. Symbolic names that correspond to message property names
Property name | Java constant | C constant |
---|---|---|
Action | MQeAdminMsg.Admin_Action | MQE_ADMIN_ACTION |
Correlation ID | MQe.Msg_CorrelID | MQE_MSG_CORRELID |
Errors | MQeAdminMsg.Admin_Errors | MQE_ADMIN_ERRORS |
Expire time | MQe.Msg_ExpireTime | MQE_MSG_EXPIRETIME |
Lock ID | MQe.Msg_LockID | MQE_MSG_LOCKID |
Message ID | MQe.Msg_MsgID | MQE_MSG_MSGID |
Originating queue manager | MQe.Msg_OriginQMgr | MQE_MSG_ORIGIN_QMGR |
Parameters | MQeAdminMsg.Admin_Params | MQE_ADMIN_PARAMS |
Priority | MQe.Priority | MQE_MSG_PRIORITY |
Reason | MQeAdminMsg.Admin_Reason | MQE_ADMIN_REASON |
Reply-to-queue | MQe.Msg_ReplyToQ | MQE_MSG_REPLYTO_Q |
Reply-to queue manager | MQe.Msg_ReplyToQMgr | MQE_MSG_REPLYTO_QMGR |
Resend | MQe.Msg_Resend | MQE_MSG_RESEND |
Return code | MQeAdminMsg.Admin_RC | MQE_ADMIN_RC |
Style | MQe.Msg_Style | MQE_MSG_STYLE |
Wrap message | MQe.Msg_WrapMsg | MQE_MSG_WRAPMSG |
In all cases, a defined constant allows the property name to be carried in a single byte. For example, priority (if present) affects the order in which messages are transmitted, correlation ID triggers indexing of a queue for fast retrieval of information, expire time triggers the expiry of the message, and so on. Also, the default message dump command minimizes the size of the generated byte string for more efficient message storage and transmission.
The WebSphere MQ Everyplace Message ID and Correlation ID allow the application to provide an identity for a message. These are also used in interactions with the rest of the WebSphere MQ family:
MQeMsgObject msgObj = new MQeMsgObject; msgObj.putArrayOfByte( MQe.Msg_ID, MQe.asciiToByte( "1234" ));
rc = mqeFields_putArrayOfByte(hMsg,&exceptBlock, MQE_MSG_MSGID,pByteArray,sizeByteArray);
Priority contains message priority values. Message priority is defined as in other members of the WebSphere MQ family. It ranges from 9 (highest) to 0 (lowest):
MQeMsgObject msgObj = new MQeMsgObject(); msgObj.putByte( MQe.Msg_Priority, (byte)8 );
rc = mqeFields_putByte(hsg,&exceptBlock, MQE_MSG_PRIORITY, (MQEBYTE)8);
Applications can create fields for their own data within messages:
MQeMsgObject msgObj = new MQeMsgObject(); msgObj.putAscii( "PartNo", "Z301" ); msgObj.putAscii( "Colour", "Blue" ); msgObj.putInt( "Size", 350 );
MQeFieldsHndl hPartMsg; MQeStringHndl hSize_FieldLabel; rc = mqeFields_new(&exceptBlock,&hPartMsg); rc = mqeString_newUtf8(&exceptBlock, &hSize_FieldLabel,"Size"); rc = mqeFields_putInt32(hPartMsg, &exceptBlock,hSize_FieldLabel,350);
The priority of the message is used, in part, to control the order in which messages are removed from the queue. If the message does not specify any, then the queue default priority is used . This, unless changed, is 4. However, the application must interpret the different levels of priority.
In Java, you can extend the MQeMsgObject to include some methods that assist in creating messages, as shown in the following example:
package messages.order; import com.ibm.mqe.*; /*** This class defines the Order Request format */ public class OrderRequestMsg extends MQeMsgObject { public OrderRequestMsg() throws Exception { } /*** This method sets the client number */ public void setClientNo(long aClientNo) throws Exception { putLong("ClientNo", aClientNo); } /*** This method returns the client number */ public long getClientNo() throws Exception { return getLong("ClientNo"); }
To find out the length of a message, you can enumerate on the message as each data type has methods for getting its length.