选项 (MQLONG)

如果 MQGET 个请求被禁止，或者 MQGET 个请求在等待时被禁止，那么将取消等待。 无论队列上是否存在适当的消息，调用都将完成 MQCC_FAILED 和原因码 MQRC_GET_INHIBITED。

可以将 MQGMO_WAIT 与 MQGMO_BROWSE_FIRST 或 MQGMO_BROWSE_NEXT 选项配合使用。

如果多个应用程序正在同一共享队列上等待，那么以下规则将选择在合适的消息到达时激活哪个应用程序:

1. 只能由特定消息 (例如，具有特定 MsgId 和/或 CorrelId 的消息) 满足的特定 get-wait 请求。
2. 可由任何消息满足的常规 get-wait 请求。

如果与 MQGMO_BROWSE_MSG_UNDER_CURSOR 或 MQGMO_MSG_UNDER_CURSOR 一起指定，那么将忽略 MQGMO_WAIT ; 不会产生任何错误。

如果当前没有满足消息描述符中指定的条件的消息可用，那么控制权将返回到应用程序，而不会等待消息到达。 CompCode 和 Reason 参数设置为 MQCC_WARNING 和 MQRC_SIGNAL_REQUEST_ACCEPTED。 未设置消息描述符中的其他输出字段以及 MQGET 调用的输出参数。 当适当的信息稍后到达时，将通过发布 ECB 来传递该信号。

然后，调用者必须重新发出 MQGET 调用以检索消息。 应用程序可以使用操作系统提供的功能来等待此信号。

如果操作系统提供了多重等待机制，那么您可以使用它来等待消息到达多个队列中的任何一个队列。

如果指定了非零 WaitInterval ，那么将在等待时间间隔到期后传递信号。 队列管理器还可以取消等待，在这种情况下，将传递信号。

多个 MQGET 调用可以为同一消息设置信号。 应用程序的激活顺序与针对 MQGMO_WAIT描述的顺序相同。

如果多个 MQGET 调用正在等待同一消息，那么将平等地考虑每个正在等待的调用。 这些调用可以包含等待和信号选项的混合。

在某些情况下， MQGET 调用可以检索消息，并且可以传递来自同一消息到达的信号。 在传递信号时，必须准备应用程序以确保没有消息可用。

队列句柄不能有多个未完成的信号请求。

对于共享队列上的 MQGET 调用，该调用是浏览请求或组消息的破坏性获取，并且 MsgId 或 CorrelId 都不匹配，用户的信号 ECB 将在 200 毫秒后发布 MQEC_MSG_ARRIVED 。

即使在使用 MQEC_WAIT_INTERVAL_EXPIRED发布队列时，在等待时间间隔到期之前，合适的消息可能尚未到达队列中，也会发生此情况。 发布 MQEC_MSG_ARRIVED 时，必须重新发出另一个 MQGET 调用以检索消息 (如果有)。

此方法用于确保及时通知您消息到达，但在与非共享队列上的类似调用序列进行比较时，可能会显示为意外的处理开销。

当不经常添加消息时，这不是高效的消息检索方法。 要避免浏览案例的此开销，请在 MQGET 调用上指定 MsgId (如果未建立索引或由 MsgId建立索引) 或 CorrelId (如果由 CorrelId建立索引) 匹配。

此选项仅在 z/OS 上受支持。

在 z/OS上，如果连接 (对于 CICS® 或 IMS 应用程序) 处于停顿状态，那么此选项还会强制 MQGET 调用失败。

您可以使 MQGMO_SYNCPOINT 和 MQGMO_NO_SYNCPOINT 保持未设置状态。 在这种情况下，在工作单元协议中包含 get 请求由运行队列管理器的环境确定。 它不是由运行应用程序的环境确定的。 在 z/OS上，获取请求位于工作单元中。 在所有其他环境中，获取请求不在工作单元中。

由于这些差异，要移植的应用程序不得允许此选项为缺省值; 请显式指定 MQGMO_SYNCPOINT 或 MQGMO_NO_SYNCPOINT 。

• 如果消息是持久消息，那么队列管理器会像应用程序已指定 MQGMO_SYNCPOINT一样处理调用。
• 如果消息不是持久消息，那么队列管理器将处理调用，就像应用程序指定了 MQGMO_NO_SYNCPOINT一样。

此选项在以下连接到这些系统的环境中受支持: AIX®， HP-UX， z/OS， IBM® i， Solaris和 Linux®以及 IBM MQ MQI clients 。

如果指定 MQGMO_BROWSE_FIRST 或 MQGMO_BROWSE_NEXT，那么将采用此选项。

您可以使 MQGMO_SYNCPOINT 和 MQGMO_NO_SYNCPOINT 保持未设置状态。 在这种情况下，在工作单元协议中包含 get 请求由运行队列管理器的环境确定。 它不是由运行应用程序的环境确定的。 在 z/OS上，获取请求位于工作单元中。 在所有其他环境中，获取请求不在工作单元中。

由于这些差异，要移植的应用程序不得允许此选项为缺省值; 请显式指定 MQGMO_SYNCPOINT 或 MQGMO_NO_SYNCPOINT 。

带有 MQGMO_BROWSE_FIRST 的 MQGET 调用将忽略浏览光标的先前位置。 检索队列上满足消息描述符中指定的条件的第一条消息。 消息保留在队列上，浏览光标位于此消息上。

在此调用之后，浏览光标位于已返回的消息上。 在发出下一个带有 MQGMO_BROWSE_NEXT 的 MQGET 调用之前，可能会从队列中除去该消息。 在这种情况下，浏览光标将保留在消息占用的队列中的位置，即使该位置现在为空。

将 MQGMO_MSG_UNDER_CURSOR 选项与非浏览 MQGET 调用配合使用，以从队列中除去消息。

非浏览 MQGET 调用不会移动浏览光标，即使使用同一 Hobj 句柄也是如此。 它也不会被返回完成代码 MQCC_FAILED或原因码 MQRC_TRUNCATED_MSG_FAILED的浏览 MQGET 调用移动。

指定带有此选项的 MQGMO_LOCK 选项，以锁定浏览的消息。

您可以使用 MQGMO_* 和 MQMO_* 选项的任何有效组合来指定 MQGMO_BROWSE_FIRST ，这些选项用于控制对逻辑消息的组和段中的消息的处理。

如果指定 MQGMO_LOGICAL_ORDER，那么将按逻辑顺序浏览消息。 如果省略该选项，那么将按物理顺序浏览消息。 如果指定 MQGMO_BROWSE_FIRST，那么可以在逻辑顺序和物理顺序之间切换。 使用 MQGMO_BROWSE_NEXT 的后续 MQGET 调用将以与为队列句柄指定 MQGMO_BROWSE_FIRST 的最新调用相同的顺序浏览队列。

队列管理器保留 MQGET 调用的两组组和段信息。 浏览调用的组和段信息与从队列中除去消息的调用的信息分别保留。 如果指定 MQGMO_BROWSE_FIRST，那么队列管理器将忽略要浏览的组和段信息。 它会像没有当前组和当前逻辑消息一样扫描队列。 如果 MQGET 调用成功，完成代码为 MQCC_OK 或 MQCC_WARNING，那么用于浏览的组和段信息将设置为返回的消息的组和段信息。 如果调用失败，那么组和段信息将与调用之前的组和段信息保持相同。

浏览光标指向的消息是上次使用 MQGMO_BROWSE_FIRST 或 MQGMO_BROWSE_NEXT 选项检索的消息。

如果 MQGMO_COMPLETE_MSG 与 MQGMO_MSG_UNDER_CURSOR一起指定，那么浏览光标必须标识 MQMD 中的 Offset 字段为零的消息。 如果不满足此条件，那么调用将失败，原因码为 MQRC_INVALID_MSG_UNDER_CURSOR。

未从队列中除去消息。

协作级别标记是对可能已设置的任何句柄级别标记的补充。

未从队列中除去消息。

如果已标记该消息，并且未指定选项 MQGMO_UNMARKED_BROWSE_MSG ，那么调用将失败，并返回 MQCC_FAILED 和原因码 MQRC_MSG_MARKED_BROWSE_CO_OP。

仅当使用选项 MQOO_CO_OP成功调用 MQOPEN 所返回的句柄时，使用 MQGMO_UNMARK_BROWSE_CO_OP 才有效。 即使消息未被视为由协作的句柄集标记， MQGET 也会成功。

即使未对此句柄标记消息，调用也会成功。

• MQGMO_BROWSE_FIRST
• MQGMO_BROWSE_NEXT
• MQGMO_BROWSE_MSG_UNDER_CURSOR

锁定的消息始终是浏览光标下的消息。 稍后指定 MQGMO_MSG_UNDER_CURSOR 选项的 MQGET 调用可将消息从队列中除去。 使用队列句柄的其他 MQGET 调用也可以除去消息 (例如，指定锁定消息的消息标识的调用)。

如果调用返回完成代码 MQCC_FAILED或 MQCC_WARNING (原因码为 MQRC_TRUNCATED_MSG_FAILED) ，那么不会锁定任何消息。

当您在 HP Integrity NonStop Server 上对 z/OS 队列管理器使用 IBM MQ 客户机 (由 TMF 协调) 时，无法使用 MQGMO_LOCK 。

如果指定 MQGMO_UNLOCK，那么不会检查或变更 MsgDesc， BufferLength， Buffer和 DataLength 参数。 Buffer中未返回任何消息。

无需特殊打开选项即可指定 MQGMO_UNLOCK (尽管首先需要 MQOO_BROWSE 来发出锁定请求)。

• 浏览消息时，浏览光标将前进到返回的消息。
• 除去消息时，将从队列中除去返回的消息。
• 如果未发生其他错误，那么将返回原因码 MQRC_TRUNCATED_MSG_RECEIVED。

• 浏览消息时，浏览光标不高级。
• 除去消息时，不会从队列中除去消息。
• 如果未发生其他错误，那么将返回原因码 MQRC_TRUNCATED_MSG_FAILED 。

请参阅 MQMD-消息描述符 中描述的 Format 字段，以获取队列管理器为其执行转换的格式名称的列表。

已分段的逻辑消息由两个或更多具有相同非空组标识的物理消息 ( MQMD中的 GroupId 字段) 组成。 它们具有相同的消息序号，即 MQMD中的 MsgSeqNumber 字段。 通过 MQMD中的段偏移量 Offset 字段的不同值来区分段。 段偏移是物理消息中的数据从逻辑消息中的数据开始的偏移量。 由于每个段都是物理消息，因此逻辑消息中的段通常具有不同的消息标识。

未分段但发送应用程序允许分段的逻辑消息也具有非空组标识。 在这种情况下，如果逻辑消息不属于消息组，那么只有一条具有该组标识的物理消息。 发送应用程序已禁止分段的逻辑消息具有空组标识 MQGI_NONE，除非逻辑消息属于消息组。

如果为同一队列句柄的连续 MQGET 调用指定了 MQGMO_LOGICAL_ORDER ，那么将按消息序号的顺序返回组中的消息。 逻辑消息的段按其段偏移量给定的顺序返回。 此顺序可能与这些消息和段在队列中出现的顺序不同。

要按所需顺序返回消息，队列管理器会在连续的 MQGET 调用之间保留组和段信息。 组和段信息标识队列句柄的当前消息组和当前逻辑消息。 它还标识组和逻辑消息中的当前位置，以及是否在工作单元中检索消息。 由于队列管理器保留此信息，因此应用程序无需在每次 MQGET 调用之前设置组和段信息。 具体而言，这意味着应用程序不需要在 MQMD中设置 GroupId， MsgSeqNumber和 Offset 字段。 但是，应用程序必须在每个调用上正确设置 MQGMO_SYNCPOINT 或 MQGMO_NO_SYNCPOINT 选项。

如果队列上存在多个符合返回条件的消息组，那么将按每个组中第一条逻辑消息的第一段在队列上的位置确定的顺序返回这些组。 即，消息序号为 1 且偏移量为 0 的物理消息确定返回合格组的顺序。

指定 MQGMO_LOGICAL_ORDER 时，在 MQGET 调用上提供的 MQGMO 不得小于 MQGMO_VERSION_2，并且 MQMD 不得小于 MQMD_VERSION_2。 如果未满足此条件，那么调用将失败，原因码为 MQRC_WRONG_GMO_VERSION 或 MQRC_WRONG_MD_VERSION(视情况而定)。

如果对队列句柄的连续 MQGET 调用 未 指定 MQGMO_LOGICAL_ORDER ，那么将返回消息而不考虑它们是属于消息组还是属于逻辑消息段。 这意味着可能会返回来自特定组或逻辑消息的消息或段，或者与来自其他组或逻辑消息的消息或段混合，或者与不在组中且不是段的消息混合。 在这种情况下，后续 MQGET 调用返回的特定消息由这些调用上指定的 MQMO_* 选项控制 (请参阅 MQGMO-Get-message 选项 中描述的 MatchOptions 字段以获取这些选项的详细信息)。

这是在发生系统故障后，可用于在中间重新启动消息组或逻辑消息的方法。 当系统重新启动时，应用程序可以将 GroupId， MsgSeqNumber， Offset和 MatchOptions 字段设置为相应的值，然后在设置了 MQGMO_SYNCPOINT 或 MQGMO_NO_SYNCPOINT 的情况下发出 MQGET 调用，但 未 指定 MQGMO_LOGICAL_ORDER。 如果此调用成功，那么队列管理器将保留组和段信息，并且使用该队列句柄的后续 MQGET 调用可正常指定 MQGMO_LOGICAL_ORDER 。

建议要按逻辑顺序检索消息和段的应用程序指定 MQGMO_LOGICAL_ORDER，因为这是要使用的最简单选项。 该选项可使应用程序无需管理组和段信息，因为队列管理器会管理此信息。 但是，与 MQGMO_LOGICAL_ORDER 选项提供的控制相比，专用应用程序可能需要更多的控制，而这可以通过不指定该选项来实现。 然后，应用程序必须确保在每个 MQGET 调用之前正确设置 MQMD中的 MsgId， CorrelId， GroupId， MsgSeqNumber和 Offset 字段以及 MQGMO中的 MatchOptions 中的 MQMO_* 选项。

例如，要 转发 它接收的物理消息 (而不考虑这些消息是在逻辑消息的组还是段中) 的应用程序 不得 指定 MQGMO_LOGICAL_ORDER。 在发送和接收队列管理器间具有多条路径的复杂网络中，物理消息到达时可能杂乱无序。 通过在 MQPUT 调用上既不指定 MQGMO_LOGICAL_ORDER，也不指定相应的 MQPMO_LOGICAL_ORDER ，转发应用程序可以在到达时立即检索和转发每条物理消息，而不必按逻辑顺序等待下一条消息到达。

要使用此选项，应用程序必须提供足以容纳完整消息的缓冲区，或者指定 MQGMO_ACCEPT_TRUNCATED_MSG 选项。

如果队列包含缺少部分段的分段消息 (可能是因为它们在网络中已延迟并且尚未到达) ，那么指定 MQGMO_COMPLETE_MSG 将阻止检索属于不完整逻辑消息的段。 但是，这些消息段仍构成 CurrentQDepth 队列属性的值; 这意味着可能没有可检索的逻辑消息，即使 CurrentQDepth 大于零也是如此。

对于 非持久 消息，队列管理器不需要工作单元即可执行重新组装。

作为段的每条物理消息都有自己的消息描述符。 对于构成单个逻辑消息的段，消息描述符中的大多数字段对于逻辑消息中的所有段都是相同的; 通常只有 MsgId， Offset和 MsgFlags 字段在逻辑消息中的段之间有所不同。 但是，如果将段放在中间队列管理器中的死信队列上，那么 DLQ 处理程序将检索指定 MQGMO_CONVERT 选项的消息，这可能会导致更改段的字符集或编码。 如果 DLQ 处理程序在途中成功发送段，那么段可能具有与逻辑消息中的其他段不同的字符集或编码 (当段到达目标队列管理器时)。

由 CodedCharSetId 和 Encoding 字段不同的段组成的逻辑消息无法由队列管理器重新组合为单个逻辑消息。 相反，队列管理器会在逻辑消息开头重新组合并返回前几个连续段，这些段具有相同的字符集标识和编码，并且 MQGET 调用将完成代码为 MQCC_WARNING ，原因码为 MQRC_INCONSISTENT_CCSIDS 或 MQRC_INCONSISTENT_ENCODINGS(视情况而定)。 无论是否指定了 MQGMO_CONVERT ，都会发生此情况。 要检索其余段，应用程序必须在不使用 MQGMO_COMPLETE_MSG 选项的情况下重新发出 MQGET 调用，逐个检索段。 MQGMO_LOGICAL_ORDER 可用于按顺序检索其余段。

放置段的应用程序还可以将消息描述符中的其他字段设置为不同段之间不同的值。 但是，如果接收应用程序使用 MQGMO_COMPLETE_MSG 来检索逻辑消息，那么执行此操作没有任何优势。 当队列管理器重新组装逻辑消息时，它会在消息描述符中返回来自 第一个 段的消息描述符的值; 唯一的例外是 MsgFlags 字段，队列管理器设置此字段以指示重新组装的消息是唯一的段。

如果为报告消息指定了 MQGMO_COMPLETE_MSG ，那么队列管理器将执行特殊处理。 队列管理器检查队列以查看与逻辑消息中的不同段相关的该报告类型的所有报告消息是否都存在于队列中。 如果是，那么可以通过指定 MQGMO_COMPLETE_MSG将它们作为单一消息进行检索。 要实现此目的，必须由支持分段的队列管理器或 MCA 生成报告消息，或者发端应用程序必须请求至少 100 字节的消息数据 (即，必须指定相应的 MQRO_*_WITH_DATA 或 MQRO_*_WITH_FULL_DATA 选项)。 如果存在的应用程序数据量小于段的完整数据量，那么将在返回的报告消息中使用空值替换缺少的字节。

如果 MQGMO_COMPLETE_MSG 与 MQGMO_MSG_UNDER_CURSOR 或 MQGMO_BROWSE_MSG_UNDER_CURSOR一起指定，那么浏览光标必须位于 MQMD 中 Offset 字段的值为 0 的消息上。 如果不满足此条件，那么调用将失败，原因码为 MQRC_INVALID_MSG_UNDER_CURSOR。

MQGMO_COMPLETE_MSG 意味着 MQGMO_ALL_SEGMENTS_AVAILABLE，因此不需要指定。

成功完成指定 MQGMO_ALL_MSGS_AVAILABLE 的 MQGET 调用意味着在发出 MQGET 调用时，组中的所有消息都在队列中。 但是，请注意，其他应用程序仍可以从组中除去消息 (该组未锁定到检索组中第一条消息的应用程序)。

如果省略此选项，那么即使组不完整，也可以检索属于组的消息。

MQGMO_ALL_MSGS_AVAILABLE 意味着 MQGMO_ALL_SEGMENTS_AVAILABLE，因此不需要指定。

如果未指定此选项，那么即使逻辑消息不完整，也可以检索消息段。

虽然 MQGMO_COMPLETE_MSG 和 MQGMO_ALL_SEGMENTS_AVAILABLE 都要求所有段都可用，然后才能检索它们中的任何段，但前者返回完整的消息，而后者允许逐个检索这些段。

如果为报告消息指定了 MQGMO_ALL_SEGMENTS_AVAILABLE ，那么队列管理器将检查该队列，以查看组成完整逻辑消息的每个分段是否至少有一条报告消息。 如果存在，那么满足 MQGMO_ALL_SEGMENTS_AVAILABLE 条件。 但是，队列管理器不会检查存在的报告消息的 类型 ，因此报告消息中可能混用了与逻辑消息段相关的报告类型。 因此， MQGMO_ALL_SEGMENTS_AVAILABLE 的成功并不意味着 MQGMO_COMPLETE_MSG 将成功。 如果存在 为特定逻辑消息的段提供的报告类型的混合，那么必须逐个检索这些报告消息。

消息的属性 (消息描述符 (或扩展) 中包含的属性除外) 应由 PropertyControl 队列属性定义。 如果提供了 MsgHandle ，那么除非 PropertyControl 队列属性的值为 MQPROP_FORCE_MQRFH2，否则将忽略此选项并通过 MsgHandle提供消息属性。

如果未指定属性选项，那么这是缺省操作。

应通过 MsgHandle提供消息的属性。 如果未提供消息句柄，那么调用将失败，原因为 MQRC_HMSG_ERROR。

将不会检索消息的属性，但包含在消息描述符 (或扩展) 中的属性除外。 如果提供了 MsgHandle ，那么将忽略该值。

应该使用 MQRFH2 头来表示消息的属性 (消息描述符 (或扩展) 中包含的属性除外)。 对于期望检索属性但无法更改为使用消息句柄的应用程序，这将提供与先前版本的兼容性。 如果 MsgHandle 已提供，那么会将其忽略。