Getting a particular message
There are a number of ways of getting a particular message from a queue. These are: selecting on the MsgId and CorrelId, selecting on the GroupId, MsgSeqNumber and Offset, and selecting on the MsgToken. We can also use a selection string when you open the queue.
To get a particular message from a queue, use the MsgId and CorrelId fields of the MQMD structure. However, applications can explicitly set these fields, so the values that you specify might not identify a unique message. Table 1 shows which message is retrieved for the possible settings of these fields. These fields are ignored on input if we specify MQGMO_MSG_UNDER_CURSOR in the GetMsgOpts parameter of the MQGET call.| 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 of the message returned, if any.
If you set the Version field of the MQMD structure to 2, we can use the GroupId, MsgSeqNumber, and Offset fields. Table 2 shows which message is retrieved for the possible settings of these fields.| 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 |
- 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 that we 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 Options.
The MQGET call usually retrieves the first message from a queue. If you specify a particular message when we use the MQGET call, the queue manager must search the queue until it finds that message. This can affect the performance of the application.
If we are using Version 2 or later of the MQGMO structure and do not specify the MQMO_MATCH_MSG_ID or MQMO_MATCH_CORREL_ID flags, we do not need to reset the MsgId or CorrelId fields between MQGETs.
On IBM 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.
We can get a specific message from a queue by specifying its MsgToken and the MatchOption MQMO_MATCH_MSG_TOKEN in the MQGMO structure. The MsgToken is returned by the MQPUT call that originally put that message on the queue, or by previous MQGET operations and remains constant unless the queue manager is restarted.
If we are interested in only a subset of messages on the queue, we can specify which messages we want to process by using a selection string with the MQOPEN or MQSUB call. MQGET then retrieves the next message that satisfies that selection string. For more information about selection strings, see Selectors.
Parent topic: Getting messages from a queue