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.

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

Table 2. 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:
  1. MQMO_MATCH_XXX implies that the XXX field in the MQMD structure is set to the value to be matched.
  2. 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.
  3. If you specify MQGMO_LOGICAL_ORDER, the message that 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 Options.

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.