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, we 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 preceding cases, we 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.

Get messages based on message property is not done using match options; for more information, see SelectionString (MQCHARV).

We 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.

    We 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), we can specify no other match options with MQMO_MATCH_MSG_TOKEN.

    We 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.

If you specify none of the options described, we 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® 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.