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. You 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 you 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, you 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 |
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 must search the queue until it finds that message. This can affect the performance of your application.
If you 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,
you do not need to reset the MsgId
or CorrelId
fields
between MQGETs.
You 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 you are interested in only a subset of messages on the queue, you can specify which messages you 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.