MQPMO 选项 (MQLONG)

"选项" 字段控制 MQPUT 和 MQPUT1 调用的操作。

作用域选项。 可以指定任何 MQPMO 选项，也可以不指定任何 MQPMO 选项。 要指定多个选项，请将值一起添加 (请勿多次添加相同的常量) ，或者使用按位 OR 运算来组合值 (如果编程语言支持位运算)。 将记录无效的组合; 任何其他组合都有效。

以下选项控制发送的发布的范围:
mqpmo_scope_qmgr
发布仅发送给已在此队列管理器上预订的订户。 发布不会转发到任何已预订此队列管理器的远程发布/预订队列管理器，这将覆盖使用 PUBSCOPE 主题属性设置的任何行为。
注: 如果未设置，那么发布范围由 PUBSCOPE 主题属性确定。
发布选项。 以下选项控制将消息发布到主题的方式:
mqpmo_suppress_replyto

此出版物的 MQMD 的 ReplyToQ 和 ReplyToQMgr 字段中指定的任何信息都不会传递给订户。 如果此选项与需要 ReplyToQ的报告选项一起使用，那么调用将失败并返回 MQRC_MISSING_REPLY_TO_Q。

MQPMO_RETAIN

要发送的发布将由队列管理器保留。 此保留时间允许订户使用 MQSUBRQ 调用在发布此发布后请求此发布的副本。 它还允许将发布发送到在创建此发布之后进行其预订的应用程序 (除非他们选择不使用选项 MQSO_NEW_publicATIONS_ONLY 发送此发布)。 如果向应用程序发送了保留的发布，那么该发布由该发布的 MQIsRetained 消息属性指示。

在主题树的每个节点上只能保留一个发布内容。 因此，如果已存在此主题的保留出版物 (由任何其他应用程序发布) ，那么会将其替换为此出版物。 因此，最好避免有多个发布程序保留同一主题上的消息。

当订户请求保留发布时，所使用的预订可能在主题中包含通配符，在这种情况下，许多保留发布可能匹配 (在主题树中的各个节点上) ，并且可能会将多个发布发送到请求应用程序。 请参阅 MQSUBRQ-预订请求 调用的描述以获取更多详细信息。

有关保留发布如何与预订级别交互的信息，请参阅 拦截发布。

如果使用此选项并且无法保留发布，那么将不会发布消息，并且调用将失败并返回MQRC_PUT_NOT_保留。

MQPMO_NOT_OWN_SUBS
告知队列管理器，应用程序不希望将其任何发布发送到它拥有的预订。 如果连接句柄相同，那么会将预订视为由同一应用程序拥有。
mqpmo_warn_if_noo_subs_matched
如果没有预订与发布内容匹配，请返回完成代码 (CompCode) MQCC_WARNING 和原因码 MQRC_NO_SUBS_MATCHES。

如果 put 操作返回了 MQRC_NO_SUBS_MODIFIED ，那么发布未传递到任何预订。 但是，如果在 put 操作上指定了 MQPMO_RETAIN 选项，那么将保留该消息并将其传递到随后定义的任何匹配预订。

如果满足以下任何条件，那么主题上的预订将与发布匹配:
  • 消息已传递到预订队列
  • 消息将已传递到预订队列，但队列存在问题意味着无法将消息放入队列，因此将其放置在死信队列上或将其废弃。
  • 定义了路由出口，禁止将消息传递到预订
如果满足以下任何条件，那么该主题的预订与发布不匹配:
  • 预订具有与发布不匹配的选择字符串
  • 预订指定了 MQSO_PUBLIC ICATION_ON_REQUEST 选项
  • 未交付发布内容，因为在 put 操作上指定了 MQPMO_NOT_OWN_SUBS 选项，并且预订与发布者的身份相匹配
同步点选项。 以下选项与 MQPUT 或 MQPUT1 调用在工作单元中的参与相关:
mqpmo_syncpoint
请求是在正常工作单元协议中运行。 在落实工作单元之前，该消息在工作单元外部不可见。 如果工作单元已回退，那么将删除该消息。

如果未指定 MQPMO_SYNCPOINT 和 MQPMO_NO_SYNCPOINT ，那么在工作单元协议中包含 put 请求由运行队列管理器的环境而不是运行应用程序的环境确定。 在 z/OS®上， put 请求位于工作单元中。 在所有其他环境中， put 请求不在工作单元中。

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

请勿将 MQPMO_SYNCPOINT 与 MQPMO_NO_SYNCPOINT 一起指定。

mqpmo_noo_syncpoint
请求是在正常工作单元协议之外运行。 消息立即可用，无法通过回退工作单元将其删除。

如果未指定 MQPMO_NO_SYNCPOINT 和 MQPMO_SYNCPOINT ，那么在工作单元协议中包含 put 请求由运行队列管理器的环境而不是运行应用程序的环境确定。 在 z/OS上， put 请求位于工作单元中。 在所有其他环境中， put 请求不在工作单元中。

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

请勿将 MQPMO_NO_SYNCPOINT 与 MQPMO_SYNCPOINT 一起指定。

消息标识和相关标识选项。 以下选项请求队列管理器生成新的消息标识或相关标识:
mqpmo_new_msg_id
队列管理器将 MQMD 中 MsgId 字段的内容替换为新的消息标识。 此消息标识随消息一起发送，并在 MQPUT 或 MQPUT1 调用的输出时返回到应用程序。

将消息放入分发列表时，也可以指定 MQPMO_NEW_MSG_ID 选项; 请参阅 MQPMR 结构中 MsgId 字段的描述以获取详细信息。

使用此选项将使应用程序无需在每次 MQPUT 或 MQPUT1 调用之前将 MsgId 字段重置为 MQMI_NONE。

MQPMO_NEW_CORREL_ID
队列管理器将 MQMD 中 CorrelId 字段的内容替换为新的相关标识。 此相关标识随消息一起发送，并在 MQPUT 或 MQPUT1 调用的输出时返回到应用程序。

在将消息放入分发列表时，还可以指定 MQPMO_NEW_CORREL_ID 选项; 请参阅 MQPMR 结构中 CorrelId 字段的描述以获取详细信息。

MQPMO_NEW_CORREL_ID 在应用程序需要唯一相关标识的情况下很有用。

组和段选项。 以下选项与处理逻辑消息的组和段中的消息相关。 请阅读以下定义，以帮助您了解该选项。
注意: 不能将分段或分组的消息与发布/预订配合使用。
物理消息
这是可以放在队列上或从队列中除去的最小信息单元; 它通常对应于在单个 MQPUT ， MQPUT1或 MQGET 调用上指定或检索的信息。 每条物理消息都有自己的消息描述符 (MQMD)。 通常，物理消息由消息标识 (MQMD 中的MsgId 字段) 的不同值进行区分，尽管队列管理器未实施此操作。
逻辑消息
逻辑消息是仅适用于非 z/OS 平台的单个应用程序信息单元。 在没有系统约束的情况下，逻辑消息与物理消息相同。 但是，如果逻辑消息非常大，那么系统约束可能建议或需要将逻辑消息拆分为两个或多个物理消息 (称为 段)。

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

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

消息组
消息组是一组具有相同非空组标识的一个或多个逻辑消息。 该组中的逻辑消息由消息序号的不同值区分，该值是 1 到 n范围内的整数，其中 n 是该组中的逻辑消息数。 如果对一个或多个逻辑消息进行分段，那么组中有多个 n 物理消息。
MQPMO_LOGICAL_ORDER
此选项告诉队列管理器应用程序如何将消息放入逻辑消息的组和段中。 只能对 MQPUT 调用指定此选项；它对于 MQPUT1 调用是无效的。
如果指定 MQPMO_LOGICAL_ORDER，那么指示应用程序使用连续的 MQPUT 调用来执行以下操作：
  1. 按段偏移量的递增顺序（从 0 开始，无间隔）放置每条逻辑消息中的段。
  2. 先放置一条逻辑消息中的所有段，然后再放置下一条逻辑消息中的段。
  3. 按消息序号的递增顺序（从 1 开始，无间隔）放置每个消息组中的逻辑消息。 IBM® MQ 会自动递增消息序号。
  4. 先放置一个消息组中的所有逻辑消息，然后再放置下一个消息组中的逻辑消息。

有关 MQPMO_LOGICAL_ORDER 的详细信息，请参阅 逻辑和物理排序

上下文选项。 以下选项控制消息上下文的处理:
mqpmo_noo_context
标识和源上下文都设置为指示无上下文。 这意味着 MQMD 中的上下文字段设置为:
  • 字符字段的空白
  • 字节字段的空值
  • 数字字段的零
mqpmo_default_context
对于身份和源，此消息将具有与其关联的缺省上下文信息。 队列管理器按如下所示设置消息描述符中的上下文字段:
MQMD 中的字段 使用的值
UserIdentifier 如果可能，根据环境确定; 否则设置为空白。
AccountingToken 根据环境确定 (如果可能); 否则设置为 MQACT_NONE。
ApplIdentityData 设置为空白。
PutApplType 从环境中确定。
PutApplName 如果可能，根据环境确定; 否则设置为空白。
PutDate 设置为放入消息的日期。
PutTime 设置为放入消息的时间。
ApplOriginData 设置为空白。
有关消息上下文的更多信息，请参阅 消息上下文。

如果未指定任何上下文选项，那么这些是缺省值和操作。

mqpmo_pass_identity_context
该消息将具有与其关联的上下文信息。 身份上下文取自 Context 字段中指定的队列句柄。 源上下文信息由队列管理器以与 MQPMO_DEFAULT_CONTEXT 相同的方式生成 (请参阅上表以了解值)。 有关消息上下文的更多信息，请参阅 消息上下文。

对于 MQPUT 调用，必须已使用 MQOO_PASS_IDENTITY_CONTEXT 选项 (或暗示该选项的选项) 打开队列。 对于 MQPUT1 调用，将执行与使用 MQOO_PASS_IDENTITY_CONTEXT 选项的 MQOPEN 调用相同的授权检查。

mqpmo_pass_all_context
该消息将具有与其关联的上下文信息。 上下文取自 Context 字段中指定的队列句柄。 有关消息上下文的更多信息，请参阅 控制上下文信息。

对于 MQPUT 调用，必须已使用 MQOO_PASS_ALL_CONTEXT 选项 (或暗示该选项的选项) 打开队列。 对于 MQPUT1 调用，将执行与使用 MQOO_PASS_ALL_CONTEXT 选项的 MQOPEN 调用相同的授权检查。

mqpmo_set_identity_context
该消息将具有与其关联的上下文信息。 应用程序在 MQMD 结构中指定身份上下文。 源上下文信息由队列管理器以与 MQPMO_DEFAULT_CONTEXT 相同的方式生成 (请参阅上表以了解值)。 有关消息上下文的更多信息，请参阅 消息上下文。

对于 MQPUT 调用，必须已使用 MQOO_SET_IDENTITY_CONTEXT 选项 (或暗示该选项的选项) 打开队列。 对于 MQPUT1 调用，将执行与使用 MQOO_SET_IDENTITY_CONTEXT 选项的 MQOPEN 调用相同的授权检查。

mqpmo_set_all_context
该消息将具有与其关联的上下文信息。 应用程序在 MQMD 结构中指定身份，源和用户上下文。 有关消息上下文的更多信息，请参阅 消息上下文。

对于 MQPUT 调用，必须已使用 MQOO_SET_ALL_CONTEXT 选项打开队列。 对于 MQPUT1 调用，将执行与使用 MQOO_SET_ALL_CONTEXT 选项的 MQOPEN 调用相同的授权检查。

只能指定其中一个 MQPMO_ * _CONTEXT 上下文选项。 如果未指定任何值，那么将采用 MQPMO_DEFAULT_CONTEXT。

属性选项。 以下选项与消息的属性相关:
mqpmo_md_for_output_only
必须仅将消息描述符参数用于输出以返回放入的消息的消息描述符。 必须将与 MQPMO 结构的 NewMsgHandle和/或 OriginalMsgHandle字段相关联的消息描述符字段用于输入。

如果未提供有效的消息句柄，那么调用将失败，原因码为 MQRC_MD_ERROR。

放置响应选项。 以下选项控制返回到 MQPUT 或 MQPUT1 调用的响应。 只能指定其中一个选项。 如果未指定 MQPMO_ASYNC_RESPONSE 和 MQPMO_SYNC_RESPONSE ，那么将采用 MQPMO_RESPONSE_AS_Q_DEF 或 MQPMO_RESPONSE_AS_TOPIC_DEF。
mqpmo_async_response
MQPMO_ASYNC_RESPONSE 选项请求完成 MQPUT 或 MQPUT1 操作，而无需应用程序等待队列管理器完成调用。 使用此选项可以提高消息传递性能，尤其是对于使用客户机绑定的应用程序。 应用程序可以使用 MQSTAT 动词定期检查在任何先前异步调用期间是否发生了错误。
使用此选项时，仅保证在 MQMD 中完成以下字段;
  • ApplIdentityData
  • PutApplType
  • PutApplName
  • ApplOriginData
此外，如果将 MQPMO_NEW_MSG_ID 或 MQPMO_NEW_CORREL_ID 指定为选项，那么还将完成返回的 MsgId 和 CorrelId 。 (可以通过指定空白 MsgId 字段来隐式指定 MQPMO_NEW_MSG_ID)。
仅完成前面指定的字段。 未定义通常在 MQMD 或 MQPMO 结构中返回的其他信息。
当请求异步放置响应时， MQPUT1、 ResolvedQName 和 ResolvedQMgrName 在MQOD结构中返回的响应是未定义的。
当针对 MQPUT 或 MQPUT1 请求异步放入响应时，CompCode 和 Reason 为 MQCC_OK 和 MQRC_NONE 不一定意味着消息已被成功放入队列中。 开发使用异步 put 响应的 MQI 应用程序时，如果需要确认消息已放入队列，那么必须从 put 操作中同时检查 CompCode 和 Reason 代码，并使用 MQSTAT 来查询异步错误信息。
虽然不会立即返回每个单独 MQPUT 或 MQPUT1 调用的成功或失败，但稍后可以通过调用 MQSTAT 来确定异步调用下发生的第一个错误。
如果使用异步 put 响应未能传递同步点下的持久消息，并且您尝试落实该事务，那么落实将失败，并且将使用完成代码 MQCC_FAILED 和原因 MQRC_BACKED_OUT 回退该事务。 应用程序可以调用 MQSTAT 以确定先前 MQPUT 或 MQPUT1 失败的原因。
mqpmo_sync_response
指定此 put 响应类型可确保始终同步发出 MQPUT 或 MQPUT1 操作。 如果 put 操作成功，那么将完成 MQMD 和 MQPMO 中的所有字段。
此选项确保同步响应，而不考虑在队列或主题对象上定义的缺省 put 响应值。
mqpmo_response_as_q_def
如果为 MQPUT 调用指定此值，那么所使用的 put 响应类型将从应用程序首次打开队列时在队列上指定的 DEFpresP 值中获取。 如果客户机应用程序以低于 V 7.0的级别连接到队列管理器，那么它的行为就像指定了 MQPMO_SYNC_RESPONSE 一样。
如果为 MQPUT1 调用指定了此选项，那么在将请求发送到服务器之前， DEFpresP 属性的值未知。 缺省情况下，如果 MQPUT1 调用使用的是 MQPMO_SYNCPOINT ，那么它的行为与 MQPMO_ASYNC_RESPONSE 一样，如果使用的是 MQPMO_NO_SYNCPOINT ，那么它的行为与 MQPMO_SYNC_RESPONSE 相同。 但是，您可以通过在客户机配置文件中设置 Put1DefaultAlwaysSync 属性来覆盖此缺省行为，请参阅 客户机配置文件的 CHANNELS 节。
mqpmo_response_as_topic_def
MQPMO_RESPONSE_AS_TOPIC_DEF 是 MQPMO_RESPONSE_AS_Q_DEF 的同义词，用于与主题对象配合使用。
其他选项。 以下选项控制授权检查，队列管理器停顿时发生的情况以及解析队列和队列管理器名称:
mqpmo_alternate_user_authority
MQPMO_ALTERNATE_USER_AUTHORITY 指示 MQPUT1 调用的 ObjDesc 参数中的 AlternateUserId 字段包含用于验证将消息放入队列的权限的用户标识。 仅当授权 AlternateUserId 使用指定的选项打开队列时，调用才能成功，而不管运行应用程序的用户标识是否有权执行此操作。 (这不适用于指定的上下文选项，但这些选项始终根据运行应用程序的用户标识进行检查。)

此选项仅对 MQPUT1 调用有效。

mqpmo_fail_if_quiescing
如果队列管理器处于停顿状态，那么此选项会强制 MQPUT 或 MQPUT1 调用失败。

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

调用返回完成代码 MQCC_FAILED ，原因码为 MQRC_Q_MGR_QUIESCING 或 MQRC_CONNECTION_QUIESCING。

MQPMO_RESOLVE_LOCAL_Q
使用此选项在 MQPMO 结构中填充 ResolvedQName ，其中包含要将消息放入的本地队列的名称，并在 ResolvedQMgrName 中填充托管本地队列的本地队列管理器的名称。 有关 MQPMO_RESOLVE_LOCAL_Q 的更多信息，请参阅主题 MQOO_RESOLVE_LOCAL_Q。

如果您有权放入队列，那么您具有在 MQPUT 调用上指定此标志的必需权限; 不需要特殊权限。

缺省选项。 如果不需要所描述的任何选项，请使用以下选项:
MQPMO_NONE
使用此值来指示未指定任何其他选项；所有选项均采用其缺省值。 MQPMO_NONE 定义为帮助程序文档; 不打算将此选项与任何其他选项一起使用，但由于其值为零，因此无法检测到此类使用。

MQPMO_NONE 是输入字段。 Options 字段的初始值为 MQPMO_NONE。