MatchOptions (MQLONG)

这些选项允许应用程序选择 MsgDesc 参数中的哪些字段用于选择 MQGET 调用返回的消息。 应用程序在此字段中设置必需选项，然后将 MsgDesc 参数中的相应字段设置为这些字段所需的值。 只有在消息的 MQMD 中具有这些值的消息才是在 MQGET 调用上使用该 MsgDesc 参数进行检索的候选者。 选择要返回的消息时，将忽略 未 指定相应匹配选项的字段。 如果在 MQGET 调用上未指定选择标准 (即， any 消息可接受) ，请将 MatchOptions 设置为 MQMO_NONE。
  • 在 z/OS®上，可以使用的选择标准可能受到用于队列的索引类型的限制。 请参阅 IndexType 队列属性以获取更多详细信息。
如果指定 MQGMO_LOGICAL_ORDER ，那么下一次 MQGET 调用仅可返回某些消息:
  • 如果没有当前组或逻辑消息，那么只有 MsgSeqNumber 等于 1 且 Offset 等于 0 的消息才有资格返回。 在这种情况下，您可以使用以下一个或多个匹配选项来选择返回哪些符合条件的消息:
    • MQMO_MATCH_MSG_ID
    • MQMO_MATCH_CORREL_ID
    • MQMO_MATCH_GROUP_ID
  • 如果 存在 当前组或逻辑消息，那么只有组中的下一条消息或逻辑消息中的下一个段才适合返回，并且不能通过指定 MQMO_ * 选项来改变此情况。
在上述两种情况下，您都可以指定不适用的匹配选项，但是 MsgDesc 参数中相关字段的值必须与要返回的消息中相应字段的值相匹配; 调用失败，原因码为 MQRC_MATCH_OPTIONS_ERROR ，表示不满足此条件。

如果指定 MQGMO_MSG_UNDER_CURSOR 或 MQGMO_BROWSE_MSG_UNDER_CURSOR ，那么将忽略 MatchOptions 。

不使用匹配选项来获取基于消息属性的消息; 有关更多信息，请参阅 SelectionString (MQCHARV)。

可以指定以下一个或多个匹配选项:
MQMO_MATCH_MSG_ID
要检索的消息必须具有与 MQGET 调用的 MsgDesc 参数中 MsgId 字段的值匹配的消息标识。 此匹配是对可能应用的任何其他匹配项 (例如，相关标识) 的补充。

如果省略此选项，那么将忽略 MsgDesc 参数中的 MsgId 字段，并且任何消息标识都将匹配。

注: 消息标识 MQMI_NONE 是与消息的 MQMD 中的 任何 消息标识匹配的特殊值。 因此，使用 MQMI_NONE 指定 MQMO_MATCH_MSG_ID 与 不 指定 MQMO_MATCH_MSG_ID 相同。
MQMO_MATCH_CORREL_ID
要检索的消息必须具有与 MQGET 调用的 MsgDesc 参数中 CorrelId 字段的值匹配的相关标识。 此匹配是对可能应用的任何其他匹配项 (例如，消息标识) 的补充。

如果省略此选项，那么将忽略 MsgDesc 参数中的 CorrelId 字段，并且任何相关标识都将匹配。

注: 相关标识 MQCI_NONE 是与消息的 MQMD 中的 任何 相关标识匹配的特殊值。 因此，使用 MQCI_NONE 指定 MQMO_MATCH_CORREL_ID 与 不 指定 MQMO_MATCH_CORREL_ID 相同。
MQMO_MATCH_GROUP_ID
要检索的消息必须具有与 MQGET 调用的 MsgDesc 参数中 GroupId 字段的值匹配的组标识。 此匹配是对可能应用的任何其他匹配项 (例如，相关标识) 的补充。

如果省略此选项，那么将忽略 MsgDesc 参数中的 GroupId 字段，并且任何组标识都将匹配。

注: 组标识 MQGI_NONE 是与消息的 MQMD 中的 任何 组标识匹配的特殊值。 因此，使用 MQGI_NONE 指定 MQMO_MATCH_GROUP_ID 与 不 指定 MQMO_MATCH_GROUP_ID 相同。
MQMO_MATCH_MSG_SEQ_NUMBER
要检索的消息必须具有与 MQGET 调用的 MsgDesc 参数中的 MsgSeqNumber 字段值匹配的消息序号。 此匹配项是对可能应用的任何其他匹配项 (例如，组标识) 的补充。

如果省略此选项，那么将忽略 MsgDesc 参数中的 MsgSeqNumber 字段，并且任何消息序号都将匹配。

MQMO_MATCH_OFFSET
要检索的消息必须具有与 MQGET 调用的 MsgDesc 参数中 Offset 字段的值匹配的偏移量。 此匹配项是对可能应用的任何其他匹配项 (例如，消息序号) 的补充。
如果未指定此选项，那么将忽略 MsgDesc 参数中的 Offset 字段，并且任何偏移量都将匹配。
  • 此选项在 z/OS 上不受支持。
MQMO_MATCH_MSG_TOKEN
要检索的消息必须具有与 MQGET 调用上指定的 MQGMO 结构中 MsgToken 字段的值匹配的消息令牌。

可以对所有本地队列指定此选项。 如果为 IndexType 为 MQIT_MSG_TOKEN (WLM 管理的队列) 的队列指定此参数，那么不能使用 MQMO_MATCH_MSG_TOKEN 指定其他匹配选项。

不能将 MQMO_MATCH_MSG_TOKEN 与 MQGMO_WAIT 或 MQGMO_SET_SIGNAL 一起指定。 如果应用程序要等待消息到达 IndexType 为 MQIT_MSG_TOKEN 的队列，请指定 MQMO_NONE。

如果省略此选项，那么将忽略 MQGMO 中的 MsgToken 字段，并且任何消息令牌都将匹配。

如果未指定所描述的任何选项，那么可以使用以下选项:
MQMO_NONE
在选择要返回的消息时不使用任何匹配项; 队列上的所有消息都适合检索 (但受 MQGMO_ALL_MSGS_AVAILABLE ， MQGMO_ALL_SEGMENTS_AVAILABLE 和 MQGMO_COMPLETE_MSG 选项的控制)。

MQMO_NONE 帮助程序文档。 不打算将此选项与任何其他 MQMO_ * 选项一起使用，但由于其值为零，因此无法检测到此类使用。

这是一个输入字段。 此字段的初始值是具有 MQMO_MATCH_CORREL_ID 的 MQMO_MATCH_MSG_ID。 如果 Version 小于 MQGMO_VERSION_2，那么将忽略此字段。

注: MatchOptions 字段的初始值是为了与较早的 MQSeries® 队列管理器兼容而定义的。 但是，在不使用选择标准从队列中读取一系列消息时，此初始值要求应用程序在每次 MQGET 调用之前将 MsgId 和 CorrelId 字段重置为 MQMI_NONE 和 MQCI_NONE。 避免需要通过将 Version 设置为 MQGMO_VERSION_2和将 MatchOptions 设置为 MQMO_NONE 来重置 MsgId 和 CorrelId 。