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 5 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 5. 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 6 shows which message is retrieved for the possible settings of these fields.

Table 6. 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.