MatchOptions (MQLONG)
These options allow the application
to choose which fields in the 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 you specify MQGMO_LOGICAL_ORDER, only certain messages are eligible
for return by the next MQGET call:
- If there is no current group or logical message, only messages that have MsgSeqNumber equal to 1 and Offset equal
to 0 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.
In both of the above cases, you can specify match options that do not
apply, but the value of the relevant field in the 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.
You can specify one or more of the following match options:
- MQMO_MATCH_MSG_ID
- The message to be retrieved must have a message identifier that matches
the value of the MsgId field in the MsgDesc 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 the MsgDesc 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 the MsgDesc 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 the MsgDesc 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 the MsgDesc 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 the MsgDesc 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 the MsgDesc 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 the MsgDesc 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 the MsgDesc 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, the Offset field
in the MsgDesc 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.
- This option is supported on z/OS only.
If you specify none of the options described, you can use the following
option:
- 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.
Note:
The initial value of the MatchOptions field
is defined for compatibility with earlier MQSeries(R) 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 prior to each MQGET call. Avoid the need to reset MsgId and CorrelId by setting Version to MQGMO_VERSION_2,
and MatchOptions to MQMO_NONE.