MQ: Getting a particular message

Getting a particular message

To get a particular message from a queue, use the MsgId and CorrelId fields of the MQMD structure. Note, however, that applications can explicitly set these fields, so the values you specify may not identify a unique message. Table 4 shows which message is retrieved for the possible settings of these fields. These fields are ignored on input if you specify MQGMO_MSG_UNDER_CURSOR in the GetMsgOpts parameter of the MQGET call.

Table 4. Using message and correlation identifiers

To retrieve ... MsgId CorrelId

First message in the queue MQMI_NONE MQCI_NONE

First message that matches MsgId Nonzero MQCI_NONE

First message that matches CorrelId MQMI_NONE Nonzero

First message that matches both MsgId and CorrelId Nonzero Nonzero

In each case, first means the first message that satisfies the selection criteria (unless MQGMO_BROWSE_NEXT is specified, when it means the next message in the sequence satisfying the selection criteria).
On return, the MQGET call sets the MsgId and CorrelId fields to the message and correlation identifiers (respectively) of the message returned (if any).
If you set the Version field of the MQMD structure to 2 or 3, you can use the GroupId, MsgSeqNumber, and Offset fields. Table 5 shows which message is retrieved for the possible settings of these fields.

Table 5. Using the group identifier

To retrieve ... Match options

First message in the queue MQMO_NONE

First message that matches MsgId MQMO_MATCH_MSG_ID

First message that matches CorrelId MQMO_MATCH_CORREL_ID

First message that matches GroupId MQMO_MATCH_GROUP_ID

First message that matches MsgSeqNumber MQMO_MATCH_MSG_SEQ_NUMBER

First message that matches MsgToken MQMO_MATCH_MSG_TOKEN

First message that matches Offset MQMO_MATCH_OFFSET

Notes:

MQMO_MATCH_XXX implies that the XXX field in the MQMD structure is set to the value to be matched.
The MQMO flags can be used in combination. For example, MQMO_MATCH_GROUP_ID, MQMO_MATCH_MSG_SEQ_NUMBER, and MQMO_MATCH_OFFSET can be used together to give the segment identified by the GroupId, MsgSeqNumber, and Offset fields.
If you specify MQGMO_LOGICAL_ORDER, the message you are trying to retrieve is affected because the option depends on state information controlled for the queue handle. For information about this, see Logical and physical ordering and WebSphere MQ Application Programming Reference.
MQMO_MATCH_MSG_TOKEN is used only on queues managed by the z/OS workload manager.

Notes:

The MQGET call usually retrieves the first message from a queue. If you specify a particular message when you use the MQGET call, the queue manager has to search the queue until it finds that message. This can affect the performance of your application.
If you are using Version 2 or 3 of the MQMD structure, you can use the MQMO_MATCH_MSG_ID and MQMO_MATCH_CORREL_ID flags. This avoids having to reset the MsgId and CorrelId fields between MQGETs.

On WebSphere MQ for z/OS, the queue attribute, IndexType, can be used to increase the speed of MQGET operations on the queue. For more information, see Type of index.

WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.

IBM is a trademark of the IBM Corporation in the United States, other countries, or both.

To retrieve ...	MsgId	CorrelId
First message in the queue	MQMI_NONE	MQCI_NONE
First message that matches MsgId	Nonzero	MQCI_NONE
First message that matches CorrelId	MQMI_NONE	Nonzero
First message that matches both MsgId and CorrelId	Nonzero	Nonzero

To retrieve ...	Match options
First message in the queue	MQMO_NONE
First message that matches MsgId	MQMO_MATCH_MSG_ID
First message that matches CorrelId	MQMO_MATCH_CORREL_ID
First message that matches GroupId	MQMO_MATCH_GROUP_ID
First message that matches MsgSeqNumber	MQMO_MATCH_MSG_SEQ_NUMBER
First message that matches MsgToken	MQMO_MATCH_MSG_TOKEN
First message that matches Offset	MQMO_MATCH_OFFSET
Notes: MQMO_MATCH_XXX implies that the XXX field in the MQMD structure is set to the value to be matched. The MQMO flags can be used in combination. For example, MQMO_MATCH_GROUP_ID, MQMO_MATCH_MSG_SEQ_NUMBER, and MQMO_MATCH_OFFSET can be used together to give the segment identified by the GroupId, MsgSeqNumber, and Offset fields. If you specify MQGMO_LOGICAL_ORDER, the message you are trying to retrieve is affected because the option depends on state information controlled for the queue handle. For information about this, see Logical and physical ordering and WebSphere MQ Application Programming Reference. MQMO_MATCH_MSG_TOKEN is used only on queues managed by the z/OS workload manager.