MatchOptions (MQLONG)
MsgDesc
parameter to use to select the
message returned by the MQGET call. The application sets
the required options in this field, and then sets the corresponding
fields in the MsgDesc
parameter
to the values required for those fields. Only messages that have those
values in the MQMD for the message are candidates for retrieval using
that MsgDesc
parameter
on the MQGET call. Fields for which the corresponding match
option is not specified are ignored when selecting the message
to be returned. If you specify no selection criteria on the MQGET
call (that is, any message is acceptable), set
MatchOptions
to MQMO_NONE. - On z/OS®, the selection criteria that can be used
might be restricted by the type of index used for the queue. See the
IndexType
queue attribute for further details.
- If there is no current group or logical message, only messages
that have
MsgSeqNumber
equal to1
andOffset
equal to0
are eligible for return. In this situation, you can use one or more of the following match options to select which of the eligible messages is returned:- MQMO_MATCH_MSG_ID
- MQMO_MATCH_CORREL_ID
- MQMO_MATCH_GROUP_ID
- If there is a current group or logical message, only the next message in the group or next segment in the logical message is eligible for return, and this cannot be altered by specifying MQMO_* options.
MsgDesc
parameter must match the value
of the corresponding field in the message to be returned; the call
fails with reason code MQRC_MATCH_OPTIONS_ERROR is this condition
is not satisfied.MatchOptions
is ignored if you specify either MQGMO_MSG_UNDER_CURSOR or MQGMO_BROWSE_MSG_UNDER_CURSOR.
Getting messages based on message property is not done using match options; for more information, see SelectionString (MQCHARV) .
- MQMO_MATCH_MSG_ID
- The message to be retrieved must have a message identifier that
matches the value of the
MsgId
field in theMsgDesc
parameter of the MQGET call. This match is in addition to any other matches that might apply (for example, the correlation identifier).If you omit this option, the
MsgId
field in theMsgDesc
parameter is ignored, and any message identifier will match.Note: The message identifier MQMI_NONE is a special value that matches any message identifier in the MQMD for the message. Therefore, specifying MQMO_MATCH_MSG_ID with MQMI_NONE is the same as not specifying MQMO_MATCH_MSG_ID. - MQMO_MATCH_CORREL_ID
- The message to be retrieved must have a correlation identifier
that matches the value of the
CorrelId
field in theMsgDesc
parameter of the MQGET call. This match is in addition to any other matches that might apply (for example, the message identifier).If you omit this option, the
CorrelId
field in theMsgDesc
parameter is ignored, and any correlation identifier will match.Note: The correlation identifier MQCI_NONE is a special value that matches any correlation identifier in the MQMD for the message. Therefore, specifying MQMO_MATCH_CORREL_ID with MQCI_NONE is the same as not specifying MQMO_MATCH_CORREL_ID. - MQMO_MATCH_GROUP_ID
- The message to be retrieved must have a group identifier that
matches the value of the
GroupId
field in theMsgDesc
parameter of the MQGET call. This match is in addition to any other matches that might apply (for example, the correlation identifier).If you omit this option, the
GroupId
field in theMsgDesc
parameter is ignored, and any group identifier will match.Note: The group identifier MQGI_NONE is a special value that matches any group identifier in the MQMD for the message. Therefore, specifying MQMO_MATCH_GROUP_ID with MQGI_NONE is the same as not specifying MQMO_MATCH_GROUP_ID. - MQMO_MATCH_MSG_SEQ_NUMBER
- The message to be retrieved must have a message sequence number
that matches the value of the
MsgSeqNumber
field in theMsgDesc
parameter of the MQGET call. This match is in addition to any other matches that might apply (for example, the group identifier).If you omit this option, the
MsgSeqNumber
field in theMsgDesc
parameter is ignored, and any message sequence number will match. - MQMO_MATCH_OFFSET
- The message to be retrieved must have an offset that matches the
value of the
Offset
field in theMsgDesc
parameter of the MQGET call. This match is in addition to any other matches that might apply (for example, the message sequence number).If you omit this option is not specified, theOffset
field in theMsgDesc
parameter is ignored, and any offset will match.- This option is not supported on z/OS.
- MQMO_MATCH_MSG_TOKEN
- The message to be retrieved must have a message token that matches
the value of the
MsgToken
field in the MQGMO structure specified on the MQGET call.You can specify this option for all local queues. If you specify it for a queue that has an
IndexType
of MQIT_MSG_TOKEN (a WLM-managed queue), you can specify no other match options with MQMO_MATCH_MSG_TOKEN.You cannot specify MQMO_MATCH_MSG_TOKEN with MQGMO_WAIT or MQGMO_SET_SIGNAL. If the application wants to wait for a message to arrive on a queue that has an
IndexType
of MQIT_MSG_TOKEN, specify MQMO_NONE.If you omit this option, the
MsgToken
field in MQGMO is ignored, and any message token will match.
- MQMO_NONE
- Use no matches in selecting the message to be returned; all messages
on the queue are eligible for retrieval (but subject to control by
the MQGMO_ALL_MSGS_AVAILABLE, MQGMO_ALL_SEGMENTS_AVAILABLE, and MQGMO_COMPLETE_MSG
options).
MQMO_NONE aids program documentation. It is not intended that this option be used with any other MQMO_* option, but as its value is zero, such use cannot be detected.
This is an input field. The initial value of this field
is MQMO_MATCH_MSG_ID with MQMO_MATCH_CORREL_ID. This field is ignored
if Version
is less than
MQGMO_VERSION_2.
MatchOptions
field is defined for compatibility with earlier MQSeries® queue managers. However, when reading a series of messages
from a queue without using selection criteria, this initial value
requires the application to reset the MsgId
and CorrelId
fields to MQMI_NONE and MQCI_NONE before each MQGET call.
Avoid the need to reset MsgId
and CorrelId
by setting
Version
to MQGMO_VERSION_2, and
MatchOptions
to MQMO_NONE.