MQPUT-放置消息
MQPUT 调用将消息放入队列或分发列表中，或放入主题中。 队列，分发列表或主题必须已打开。
语法
MQPUT（Hconn、Hobj、MsgDesc、PutMsgOpts、BufferLength、Buffer、CompCode、Reason）
参数
- Hconn
- 类型 :MQHCONN-输入
此句柄表示与队列管理器的连接。 先前的 MQCONN 或 MQCONNX 调用返回了
Hconn的值。![[z/OS]](ngzos.gif)
在 z/OS® for CICS® 应用程序上，可以省略 MQCONN 调用，并为 Hconn指定以下值:- MQHC_DEF_HCONN
- 缺省连接句柄。
- Hobj
- 类型 :MQHOBJ-输入
此句柄表示将消息添加到的队列或将消息发布到的主题。
Hobj的值由先前指定了 MQOO_OUTPUT 选项的 MQOPEN 调用返回。 - MsgDesc
- 类型 :MQMD-输入/输出
此结构描述要发送的消息的属性，并在 put 请求完成后接收有关消息的信息。 请参阅 MQMD-消息描述符 以获取详细信息。
如果应用程序提供了 version-1 MQMD ，那么可以使用 MQMDE 结构作为消息数据的前缀，以指定 version-2 MQMD 中存在但 version-1中不存在的字段的值。 MQMD 中的 格式 字段必须设置为 MQFMT_MD_EXTENSION ，以指示存在 MQMDE。 有关更多详细信息，请参阅 MQMDE-消息描述符扩展 。
如果在 MQPMO 结构的
OriginalMsgHandle或NewMsgHandle字段中提供了有效的消息句柄，那么应用程序不需要提供 MQMD 结构。 如果在其中一个字段中未提供任何内容，那么将从与消息句柄关联的描述符中获取消息描述符。如果您使用或计划使用 API 出口，那么建议您显式提供 MQMD 结构，而不要使用与消息句柄关联的消息描述符。 这是因为与 MQPUT 或 MQPUT1 调用关联的 API 出口无法确定队列管理器使用哪些 MQMD 值来完成 MQPUT 或 MQPUT1 请求。
- PutMsgOpts
- 类型 :MQPMO-输入/输出
请参阅 MQPMO-放置消息选项 以获取详细信息。
- BufferLength
- 类型 :MQLONG-输入
Buffer中消息的长度。 零有效，指示消息不包含应用程序数据。BufferLength的上限取决于各种因素:- 如果目标是本地队列或解析为本地队列，那么上限取决于是否:
- 本地队列管理器支持分段。
- 发送应用程序指定允许队列管理器对消息进行分段的标志。 此标志是 MQMF_SEGMENTATION_ALLOWED ，可以在 version-2 MQMD 中指定，也可以在与 version-1 MQMD 配合使用的 MQMDE 中指定。
BufferLength不能超过 999 999 减去 MQMD 中Offset字段的值。 因此，可放入的最长逻辑消息为 999 999 999 字节 (当Offset为零时)。 但是，运行应用程序的操作系统或环境施加的资源约束可能会导致下限。如果未满足一个或两个先前条件，那么
BufferLength不能超过队列的 MaxMsgLength 属性和队列管理器的 MaxMsgLength 属性中的较小者。 - 如果目标是远程队列或解析为远程队列，那么本地队列的条件适用，但必须在每个队列管理器上传递消息才能到达目标队列; 特别是:
- 用于在本地队列管理器中临时存储消息的本地传输队列
- 用于在本地队列管理器与目标队列管理器之间的路由上的队列管理器上存储消息的中间传输队列 (如果有)
- 目标队列管理器上的目标队列
当消息位于传输队列上时，附加信息与消息数据一起存在，这将减少可携带的应用程序数据量。 在此情况下，在确定
BufferLength的限制时，请从传输队列的MaxMsgLength值中减去 MQ_MSG_HEADER_LENGTH 字节。注: 只有在放入消息时，才能同步诊断不符合条件 1 (原因码为 MQRC_MSG_TOO_BIG_FOR_Q 或 MQRC_MSG_TOO_BIG_FOR_Q_MGR)。 如果不满足条件 2 或 3 ，那么会将消息重定向到中间队列管理器或目标队列管理器上的死信 (未传递消息) 队列。 如果发生这种情况，那么如果发件人请求了报告消息，那么将生成报告消息。
- 如果目标是本地队列或解析为本地队列，那么上限取决于是否:
- 缓冲区
- 类型：MQBYTExBufferLength- 输入
这是一个缓冲区，其中包含要发送的应用程序数据。 缓冲区必须在适合于消息中数据的性质的边界上对齐。 4 字节对齐适用于大多数消息 (包括包含 IBM® MQ 头结构的消息) ，但某些消息可能需要更严格的对齐。 例如，包含 64 位二进制整数的消息可能需要 8 字节对齐。
如果
Buffer包含字符或数字数据，请将 MsgDesc 参数中的CodedCharSetId和Encoding字段设置为适合于数据的值; 这使消息接收方能够将数据 (如果需要) 转换为接收方使用的字符集和编码。注: MQPUT 调用上的所有其他参数必须采用本地队列管理器的字符集和编码 (由 CodedCharSetId 队列管理器属性和 MQENC_NATIVE 提供)。在 C 编程语言中，该参数被声明为指向 void 的指针; 任何类型数据的地址都可以被指定为该参数。
如果 BufferLength 参数为零，那么不会引用
Buffer; 在这种情况下，以 C 或 System/390 汇编程序编写的程序传递的参数地址可以为空。 - CompCode
- 类型：MQLONG - 输出完成代码；此完成代码为以下其中一项：
- MQCC_OK
- 成功完成。
- MQCC_WARNING
- 警告（部分完成）。
- MQCC_FAILED
- 调用失败。
- 原因
- 类型：MQLONG - 输出
限定
CompCode的原因码。如果CompCode为 MQCC_OK:- MQRC_NONE
- (0, X'000') 没有要报告的原因。
如果CompCode为 MQCC_WARNING:- MQRC_INCOMPLETE_GROUP
- (2241，X'8C1'）报文组未完成。
- MQRC_INCOMPLETE_MSG
- (2242，X'8C2'）逻辑报文未完成。
- MQRC_INCONSISTENT_PERSISTENCE
- (2185 ， X'889 ') 持久性规范不一致。
- MQRC_INCONSISTENT_UOW
- (2245，X'8C5'）工作单位规格不一致。
- MQRC_MULTIPLE_原因
- (2136 ， X'858 ') 返回了多个原因码。
- MQRC_PRIORITY_EXCEEDS_MAXIMUM
- (2049 ， X'801 ') 消息优先级超过支持的最大值。
- MQRC_UNKNOWN_REPORT_OPTION
- (2104 ， X'838 ') 无法识别消息描述符中的报告选项。
如果CompCode是 MQCC_FAILED:- MQRC_ADAPTER_NOT_AVAILABLE
- (2204, X'89C') 适配器不可用。
- MQRC_ADAPTER_SERV_LOAD_ERROR
- (2130, X'852') 无法装入适配器服务模块。
- MQRC_ALIAS_TARGTYPE_CHANGED
- (2480,X'09B0')订阅目标类型已从队列变为主题对象。
- MQRC_API_EXIT_ERROR
- (2374, X'946') API 出口失败。
- MQRC_API_EXIT_LOAD_ERROR
- (2183 ， X'887 ') 无法装入 API 出口。
- MQRC_ASID_MISMATCH
- (2157, X'86D') 主 ASID (Primary ASID) 与主 ASID (home ASID) 不同。
- MQRC_BACKED_OUT
- (2003，X'7D3'）工作单位退出。
- MQRC_BUFFER_ERROR
- (2004，X'7D4'）缓冲区参数无效。
- MQRC_BUFFER_LENGTH_ERROR
- (2005, X'7D5') 缓冲区长度参数无效。
- MQRC_CALL_IN_PROGRESS
- (2219, X'8AB') 在先前调用完成前输入了 MQI 调用。
- MQRC_CALL_中断
- (2549，X'9F5'）MQPUT 或 MQCMIT 中断，重新连接处理无法重新确定结果。
- MQRC_CF_NOT_AVAILABLE
- (2345 ， X' 929 ') 耦合设施不可用。
- MQRC_CF_STRUC_FAILED
- (2373 ， X' 945 ') 耦合设施结构失败。
- MQRC_CF_STRUC_IN_USE
- (2346，X'92A'）使用中的耦合设施结构。
- MQRC_CFGR_ERROR
- (2416 ， X' 970 ') 消息数据中的 PCF 组参数结构 MQCFGR 无效。
- MQRC_CFH_ERROR
- (2235，X'8BB'） PCF 报头结构无效。
- MQRC_CFIF_ERROR
- (2414，X'96E'）报文数据中的 PCF 整数滤波器参数结构无效。
- MQRC_CFIL_ERROR
- (2236,X'8BC') PCF 整数列表参数结构或PCIF*64整数列表参数结构无效。
- MQRC_CFIN_ERROR
- (2237，X'8BD'） PCF 整数参数结构或PCIF*64整数参数结构无效。
- MQRC_CFSF_ERROR
- (2415，X'96F'）报文数据中的 PCF 字符串过滤器参数结构无效。
- MQRC_CFSL_ERROR
- (2238，X'8BE'） PCF 字符串列表参数结构无效。
- MQRC_CFST_ERROR
- (2239，X'8BF'） PCF 字符串参数结构无效。
- MQRC_CICS_WAIT_FAILED
- (2140,X'85C') 等待请求被 "CICS拒绝 .
- MQRC_CLUSTER_EXIT_ERROR
- (2266,X'8DA') 集群工作负载退出失败。
- MQRC_CLUSTER_RESOLUTION_ERROR
- (2189,X'88D') 集群名称解析失败。
- MQRC_CLUSTER_RESOURCE_ERROR
- (2269,X'8DD') 集群资源错误。
- MQRC_COD_NOT_VALID_FOR_XCF_Q
- (2106,X'83A') COD 报告选项对 XCF 队列无效。
- MQRC_CONNECTION_BROKEN
- (2009, X'7D9') 与队列管理器的连接丢失。
- MQRC_CONNECTION_NOT_AUTHORIZED
- (2217，X'8A9'）未授权连接。
- MQRC_CONNECTION_QUIESCING
- (2202, X'89A') 连接正在停顿。
- MQRC_CONNECTION_STOPPING
- (2203, X'89B') 连接正在关闭。
- MQRC_CONTENT_ERROR
- 2554X'09FA'）无法对报文内容进行解析，以确定是否应将报文发送给具有扩展报文选择器的订户。
- MQRC_CONTEXT_HANDLE_ERROR
- (2097 ， X'831 ') 引用的队列句柄不保存上下文。
- MQRC_CONTEXT_NOT_AVAILABLE
- (2098 ， X'832 ') 上下文不可用于引用的队列句柄。
- MQRC_DATA_LENGTH_ERROR
- (2010，X'7DA'）数据长度参数无效。
- MQRC_DH_ERROR
- (2135 ， X'857 ') 分发头结构无效。
- MQRC_DLH_ERROR
- (2141，X'85D'）死字母报头结构无效。
- MQRC_EPH_ERROR
- (2420 ， X' 974 ') 嵌入式 PCF 结构无效。
- MQRC_EXPIRY_ERROR
- (2013,X'7DD') 失效时间无效。
- MQRC_FEEDBACK_ERROR
- (2014，X'7DE'）反馈代码无效。
- MQRC_GLOBAL_UOW_CONFLICT
- (2351，X'92F'）全球工作单位冲突。
- MQRC_GROUP_ID_ERROR
- (2258，X'8D2'）组标识符无效。
- MQRC_HANDLE_IN_USE_FOR_UOW
- (2353 ， X' 931 ') 用于全局工作单元的句柄。
- MQRC_HCONN_ERROR
- (2018, X'7E2') 连接句柄无效。
- MQRC_HEADER_ERROR
- (2142，X'85E'）MQ报头结构无效。
- MQRC_HOBJ_ERROR
- (2019，X'7E3'）对象句柄无效。
- MQRC_IIH_ERROR
- (2148 ， X'864 ') IMS 信息头结构无效。
- MQRC_INCOMPLETE_GROUP
- (2241，X'8C1'）报文组未完成。
- MQRC_INCOMPLETE_MSG
- (2242，X'8C2'）逻辑报文未完成。
- MQRC_INCONSISTENT_PERSISTENCE
- (2185 ， X'889 ') 持久性规范不一致。
- MQRC_INCONSISTENT_UOW
- (2245，X'8C5'）工作单位规格不一致。
- MQRC_LOCAL_UOW_CONFLICT
- (2352 ， X' 930 ') 全局工作单元与本地工作单元冲突。
- MQRC_MD_ERROR
- (2026，X'7EA'）报文描述符无效。
- MQRC_MDE_ERROR
- (2248，X'8C8'）报文描述符扩展名无效。
- MQRC_MISSING_REPLY_TO_Q
- (2027，X'7EB') 缺少回复到队列或使用了 MQPMO_SUPPRESS_REPLYTO
- MQRC_MISSING_WIH
- (2332，X'91C'）报文数据不以 MQWIH 开头。
- MQRC_MSG_FLAGS_ERROR
- (2249，X'8C9'）报文标志无效。
- MQRC_MSG_SEQ_NUMBER_ERROR
- (2250，X'8CA'）报文序列号无效。
- MQRC_MSG_TOO_BIG_FOR_Q
- (2030，X'7EE'）报文长度超过队列最大值。
- MQRC_MSG_TOO_BIG_FOR_Q_MGR
- (2031,X'7EF') 报文长度超过队列管理器的最大值。
- MQRC_MSG_TYPE_ERROR
- (2029，X'7ED'）报文描述符中的报文类型无效。
- MQRC_MULTIPLE_原因
- (2136 ， X'858 ') 返回了多个原因码。
- MQRC_NO_DESTINATIONS_AVAILABLE
- (2270，X'8DE'）没有可用的目标队列。
- MQRC_NOT_OPEN_FOR_OUTPUT
- (2039，X'7F7'）队列未开放输出。
- MQRC_NOT_OPEN_FOR_PASS_ALL
- (2093，X'82D') 队列未打开，无法通过所有上下文。
- MQRC_NOT_OPEN_FOR_PASS_制
- (2094，X'82E'）队列未为通行证身份上下文打开。
- MQRC_NOT_OPEN_FOR_SET_ALL
- (2095,X'82F')队列未对全部设置打开。
- MQRC_NOT_OPEN_FOR_SET_制
- (2096 ， X'830 ') 未针对设置的身份上下文打开队列。
- MQRC_OBJECT_CHANGED
- (2041，X'7F9'）打开后对象定义已更改。
- MQRC_OBJECT_DAMAGED
- (2101 ， X'835 ') 对象已损坏。
- MQRC_OFFSET_ERROR
- (2251，X'8CB'）报文段偏移无效。
- MQRC_OPEN_FAILED
- (2137, X'859') 对象未成功打开。
- MQRC_OPTIONS_ERROR
- (2046,X'7FE') 选项无效或不一致。
- MQRC_ORIGINAL_LENGTH_ERROR
- (2252，X'8CC'）原始长度无效。
- MQRC_PAGESET_ERROR
- (2193 ， X'891 ') 访问页集数据集时出错。
- MQRC_PAGESET_FULL
- (2192 ， X'890 ') 外部存储介质已满。
- MQRC_PCF_ERROR
- (2149 ， X'865 ') PCF 结构无效。
- MQRC_PERSISTENCE_ERROR
- (2047,X'7FF') 持久性无效。
- MQRC_PERSISTENT_NOT_ALLOWED
- (2048 ， X'800 ') 队列不支持持久消息。
- MQRC_PMO_ERROR
- (2173,X'87D') 看跌期权结构无效。
- MQRC_PMO_RECORD_FLAGS_ERROR
- (2158，X'86E'）报文记录标志无效。
- MQRC_PRIORITY_ERROR
- (2050 ， X'802 ') 消息优先级无效。
- MQRC_PUBLICATION_FAILURE
- (2502，X'9C6'）该出版物尚未交付给任何订户。
- MQRC_PUT_禁止
- (2051 ， X'803 ') 对队列，此队列解析到的队列或主题禁止 Put 调用。
- MQRC_PUT_MSG_RECORDS_ERROR
- (2159，X'86F'）输入的报文记录无效。
- MQRC_PUT_NOT_留存
- (2479，X'09AF'）无法保留出版物
- MQRC_Q_DELETED
- (2052 ， X'804 ') 队列已删除。
- MQRC_Q_FULL
- (2053 ， X'805 ') 队列已包含最大消息数。
- MQRC_Q_MGR_NAME_ERROR
- (2058, X'80A') 队列管理器名称无效或者未知。
- MQRC_Q_MGR_NOT_AVAILABLE
- (2059, X'80B') 队列管理器针对连接不可用。
- MQRC_Q_MGR_QUIESCING
- (2161, X'871') 队列管理器正在停顿。
- MQRC_Q_MGR_STOPPING
- (2162, X'872') 队列管理器正在关闭。
- MQRC_Q_SPACE_NOT_AVAILABLE
- (2056 ， X'808 ') 磁盘上没有可用于队列的空间。
- MQRC_RECONNECT_FAILED
- (2548，X'9F4'）重新连接后，为可重新连接的连接恢复句柄时发生错误。
- MQRC_RECS_PRESENT_ERROR
- (2154，X'86A'）当前记录数无效。
- MQRC_REPORT_OPTIONS_ERROR
- (2061,X'80D') 报文描述符中的报告选项无效。
- MQRC_RESOURCE_PROBLEM
- (2102, X'836') 没有足够系统资源可用。
- MQRC_RESPONSE_RECORDS_ERROR
- (2156,X'86C') 响应记录无效。
- MQRC_RFH_ERROR
- (2334，X'91E'） MQRFH 或MQRFH2结构无效。
- MQRC_RMH_ERROR
- (2220，X'8AC'）参考报文头结构无效。
- MQRC_SEGMENT_LENGTH_ZERO
- (2253，X'8CD'）报文段中的数据长度为零。
- MQRC_SEGMENTS_NOT_SUPPORTED
- (2365，X'93D'）不支持分段。
- MQRC_SELECTION_NOT_AVAILABLE
- 2551X'09F7') 该出版物可能有一个订阅者，但队列管理器无法检查是否将出版物发送给该订阅者。
- MQRC_STOPPED_BY_CLUSTER_EXIT
- (2188,X'88C') 集群工作负载退出拒绝调用。
- MQRC_STORAGE_CLASS_ERROR
- (2105 ， X'839 ') 存储类错误。
- MQRC_STORAGE_MEDIUM_FULL
- (2192 ， X'890 ') 外部存储介质已满。
- MQRC_STORAGE_NOT_AVAILABLE
- (2071, X'817') 没有足够的存储空间可用。
- MQRC_SUPPRESSED_BY_EXIT
- (2109，X'83D'）退出程序抑制了调用。
- MQRC_SYNCPOINT_LIMIT_已达到
- (2024，X'7E8'）当前工作单元内无法处理更多信息。
- MQRC_SYNCPOINT_NOT_AVAILABLE
- (2072 ， X'818 ') 同步点支持不可用。
- MQRC_TM_ERROR
- (2265，X'8D9'）触发报文结构无效。
- MQRC_TMC_ERROR
- (2191，X'88F'）字符触发报文结构无效。
- MQRC_UNEXPECTED_ERROR
- (2195, X'893') 发生了意外错误。
- MQRC_UOW_ENLISTMENT_ERROR
- (2354 ， X' 932 ') 在全局工作单元中登记失败。
- MQRC_UOW_MIX_NOT_SUPPORTED
- (2355 ， X' 933 ') 不支持混合工作单元调用。
- MQRC_UOW_NOT_AVAILABLE
- (2255，X'8CF'）队列管理器无法使用的工作单位。
- MQRC_WIH_ERROR
- (2333，X'91D'）MQWIH 结构无效。
- MQRC_不法 _md_version
- (2257，X'8D1'）提供的 MQMD 版本错误。
- MQRC_XQH_ERROR
- (2260，X'8D4'）传输队列标头结构无效。
有关这些代码的详细信息，请参阅 消息和原因码。
主题使用说明
- 以下说明适用于主题的使用:
- 使用 MQPUT 来发布主题上的消息时，如果该主题的一个或多个订户由于其订户队列存在问题 (例如已满) 而无法获得发布，那么返回到 MQPUT 调用的原因码和传递行为取决于 TOPIC 上的 PMSGDLV 或 NPMSGDLV 属性的设置。 请注意，当指定了 MQRO_DEAD_LETTER_Q 时，将发布内容传递到死信队列，或者当指定了 MQRO_DISCARD_MSG 时，将废弃消息视为成功传递消息。 如果未交付任何发布，那么 MQPUT 将返回 MQRC_PUBLICATION_FAILURE。 在下列情况下就会发生上述情况：
- 将消息发布到将 PMSGDLV 或 NPMSGDLV (取决于消息的持久性) 设置为 ALL 的 TOPIC ，并且任何预订 (持久或非持久) 都具有无法接收发布的队列。
- 将消息发布到将 PMSGDLV 或 NPMSGDLV (取决于消息的持久性) 设置为 ALLDUR 的 TOPIC ，并且持久预订具有无法接收发布的队列。
- 将消息发布到将 PMSGDLV 或 NPMSGDLV (取决于消息的持久性) 设置为 ALLAVAIL 的 TOPIC ，并且任何持久或非持久预订都具有无法接收发布的队列。
- 将消息发布到将 PMSGDLV 或 NPMSGDLV (取决于消息的持久性) 设置为 ALLDUR 的 TOPIC ，并且非持久预订具有无法接收发布的队列。
- 如果没有正在使用的主题的订户，那么不会将已发布的消息发送到任何队列并将其废弃。 无论消息是持久的还是非持久的，还是具有无限的到期时间，如果没有订户，那么仍会将其废弃。 此情况的例外情况是要保留消息，在这种情况下，虽然不会将其发送到任何订户的队列，但会根据要传递到任何新预订或使用 MQSUBRQ 请求保留发布的任何订户的主题来存储此消息。
- 使用 MQPUT 来发布主题上的消息时，如果该主题的一个或多个订户由于其订户队列存在问题 (例如已满) 而无法获得发布，那么返回到 MQPUT 调用的原因码和传递行为取决于 TOPIC 上的 PMSGDLV 或 NPMSGDLV 属性的设置。 请注意，当指定了 MQRO_DEAD_LETTER_Q 时，将发布内容传递到死信队列，或者当指定了 MQRO_DISCARD_MSG 时，将废弃消息视为成功传递消息。 如果未交付任何发布，那么 MQPUT 将返回 MQRC_PUBLICATION_FAILURE。 在下列情况下就会发生上述情况：
MQPUT 和 MQPUT1
您可以使用 MQPUT 和 MQPUT1 调用将消息放入队列; 要使用的调用取决于环境
- 使用 MQPUT 调用将多条消息放置在同一队列上。
首先发出指定 MQOO_OUTPUT 选项的 MQOPEN 调用，然后发出一个或多个 MQPUT 请求以向队列添加消息; 最后使用 MQCLOSE 调用关闭队列。 这比重复使用 MQPUT1 调用提供更好的性能。
- 使用 MQPUT1 调用仅将一条消息放入队列中。
此调用将 MQOPEN ， MQPUT 和 MQCLOSE 调用封装到单个调用中，从而最大限度减少必须发出的调用数。
目标队列
以下说明适用于目标队列的使用:
- 如果应用程序在不使用消息组的情况下将消息序列放在同一队列上，那么在满足详细条件的情况下，将保留这些消息的顺序。 某些条件同时适用于本地和远程目标队列; 其他条件仅适用于远程目标队列。适用于本地和远程目标队列的条件
- 所有 MQPUT 调用都在同一工作单元内，或者都不在工作单元内。
请注意，将消息放入单个工作单元中的特定队列时，来自其他应用程序的消息可能与队列上的消息序列相互交织。
- 所有 MQPUT 调用都是使用同一对象句柄
Hobj进行的。在某些环境中，如果调用来自同一应用程序，那么在使用不同的对象句柄时，也会保留消息序列。 同一应用程序 的含义由环境确定:- 在 z/OS上，应用程序为:
- 对于 CICS， CICS 任务
- 对于 IMS，此任务
- 对于 z/OS 批处理，此任务
![[IBM i]](ngibmi.gif)
在 IBM i上，应用程序是作业。![[AIX、Linux 和 Windows]](ngalw.gif)
在 AIX®, Linux®, and Windows上，应用程序是线程。
- 所有消息都具有相同的优先级。
- 不会将消息放入指定了 MQOO_BIND_NOT_FIXED 的集群队列中 (或者在 DefBind 队列属性具有值 MQBND_BIND_NOT_FIXED 时 MQOO_BIND_AS_Q_DEF 生效)。
适用于远程目标队列的其他条件- 从发送队列管理器到目标队列管理器只有一条路径。
如果序列中的某些消息可能采用不同的路径 (例如，由于重新配置，流量均衡或基于消息大小的路径选择) ，那么无法保证消息在目标队列管理器中的顺序。
- 消息不会临时放置在发送队列管理器，中间队列管理器或目标队列管理器的死信队列上。
如果一个或多个消息临时放在死信队列上 (例如，由于传输队列或目标队列暂时已满) ，那么这些消息可以按顺序到达目标队列。
- 这些消息都是持久消息或所有非持久消息。
如果发送队列管理器与目标队列管理器之间的路由上的通道将其 NonPersistentMsgSpeed 属性设置为 MQNPMS_FAST ，那么非持久消息可能会跳转至持久消息之前，从而导致持久消息相对于未保留的非持久消息的顺序。 但是，将保留相对于彼此的持久消息和相对于彼此的非持久消息的顺序。
如果不满足这些条件，那么可以使用消息组来保留消息顺序，但这需要发送和接收应用程序都使用消息分组支持。 有关消息组的更多信息，请参阅: - 所有 MQPUT 调用都在同一工作单元内，或者都不在工作单元内。
分发列表
以下说明适用于分发列表的使用。
在以下环境中支持分发列表:
![[AIX]](ngaix.gif)
AIX- IBM i
![[Linux]](nglinux.gif)
Linux![[Windows]](ngwin.gif)
Windows
- 您可以使用 version-1 或 version-2 MQPMO 将消息放入分发列表。 如果使用 version-1 MQPMO (或
RecsPresent等于零的 version-2 MQPMO) ，那么应用程序无法提供放置消息记录或响应记录。 如果成功将消息发送到分发列表中的某些队列而不是其他队列，那么无法识别迂到错误的队列。如果应用程序提供了放置消息记录或响应记录，请将
Version字段设置为 MQPMO_VERSION_2。您还可以使用 version-2 MQPMO 通过确保
RecsPresent为零，将消息发送到不在分发列表中的单个队列。 - 完成代码和原因码参数设置如下:
- 如果对分发列表中的队列的放入都以相同方式成功或失败，那么将设置完成代码和原因码参数以描述公共结果。 在这种情况下，未设置 MQRR 响应记录 (如果由应用程序提供)。
例如，如果每次放置成功，那么完成代码和原因码都将设置为 MQCC_OK 和 MQRC_NONE; 如果每次放置失败，因为所有队列都禁止放置，那么参数将设置为 MQCC_FAILED 和MQRC_PUT_禁止。
- 如果对分发列表中的队列的放入并非都以相同方式成功或失败:
- 如果至少有一个 put 成功，那么完成代码参数将设置为 MQCC_WARNING ，如果所有 put 都失败，那么将设置为 MQCC_FAILED。
- 原因码参数设置为 MQRC_MULTIPLE_REASON。
- 响应记录 (如果由应用程序提供) 将设置为分发列表中队列的各个完成代码和原因码。
如果由于针对该目标打开失败而导致放入目标失败，那么响应记录中的字段将设置为 MQCC_FAILED 和 MQRC_OPEN_FAILED; 该目标包含在
InvalidDestCount中。
- 如果对分发列表中的队列的放入都以相同方式成功或失败，那么将设置完成代码和原因码参数以描述公共结果。 在这种情况下，未设置 MQRR 响应记录 (如果由应用程序提供)。
- 如果分发列表中的目标解析为本地队列，那么消息将以正常格式 (即，不作为分发列表消息) 放置在该队列上。 如果多个目标解析为同一本地队列，那么对于每个此类目标，将在队列上放置一条消息。
如果分发列表中的目标解析为远程队列，那么会将消息放置在相应的传输队列上。 如果多个目标解析为同一个传输队列，那么可以将包含这些目标的单个分发列表消息放在传输队列上，即使这些目标在应用程序提供的目标列表中不相邻也是如此。 但是，仅当传输队列支持分发列表消息时，才能执行此操作 (请参阅 DistLists)。
如果传输队列不支持分发列表，那么将在使用该传输队列的每个目标的传输队列上放置一个正常格式的消息副本。
如果具有应用程序消息数据的分发列表对于传输队列过大，那么分发列表消息将拆分为更小的分发列表消息，每个消息包含更少的目标。 如果应用程序消息数据仅适合队列，那么根本无法使用分发列表消息，并且队列管理器会为使用该传输队列的每个目标生成一个正常格式的消息副本。
如果不同的目标具有不同的消息优先级或消息持久性 (当应用程序指定 MQPRI_PRIORITY_AS_Q_DEF 或 MQPER_PERSISTENCE_AS_Q_DEF 时，可能会发生此情况) ，那么消息不会保存在同一分发列表消息中。 相反，队列管理器会根据需要生成尽可能多的分发列表消息，以适应不同的优先级和持久性值。
- 放入分发列表可能导致:
- 单个分发列表消息，或者
- 一些较小的分发列表消息，或者
- 将分发列表消息与正常消息混合使用，或者
- 仅正常消息。
- 列表中的目标是本地的，远程的或混合的。
- 目标具有相同的消息优先级和消息持久性。
- 传输队列可以保存分发列表消息。
- 传输队列的最大消息长度足以容纳分发列表形式的消息。
- 检查应用程序是否已超过工作单元中允许的最大消息数 (请参阅 MaxUncommittedMsgs 队列管理器属性)。
- 正在检查是否满足触发条件。
- 增大队列深度并检查是否将超过队列的最大队列深度。
- 如果对队列定义的任何更改 (例如，解析路径中的更改) 会导致在单独打开队列时句柄变为无效) ，那么这些更改不会导致分发列表句柄变为无效。 但是，在后续 MQPUT 调用上使用分发列表句柄时，会导致该特定队列发生故障。
头
如果在应用程序消息数据的开头放置了一个或多个 IBM MQ 头结构的消息，那么队列管理器将对头结构执行某些检查以验证它们是否有效。 如果队列管理器检测到错误，那么调用将失败并产生相应的原因码。 所执行的检查根据存在的特定结构而有所不同:
- 仅当在 MQPUT 或 MQPUT1 调用上使用 version-2 或更高版本的 MQMD 时，才会执行检查。 如果使用 version-1 MQMD ，那么不会执行检查，即使消息数据开头存在 MQMDE 也是如此。
- 不会验证本地队列管理器不支持的结构以及消息中第一个 MQDLH 之后的结构。
- MQDH 和 MQMDE 结构由队列管理器完全验证。
- 其他结构由队列管理器部分验证 (并非检查所有字段)。
队列管理器执行的常规检查包括以下内容:
StrucId字段必须有效。Version字段必须有效。StrucLength字段必须指定足够大的值，以包含结构以及构成结构一部分的任何变长数据。CodedCharSetId字段不得为零，或者为无效的负值 (MQCCSI_DEFAULT ， MQCCSI_EMBEDDED ， MQCCSI_Q_MGR 和 MQCCSI_UNDEFINED 在大多数 IBM MQ 头结构中无效)。- 调用的 BufferLength 参数必须指定足以包含该结构的值 (该结构不得超出消息末尾)。
除了对结构进行常规检查外，还必须满足以下条件:
- PCF 消息中结构的长度总和必须等于 MQPUT 或 MQPUT1 调用上的 BufferLength 参数指定的长度。 PCF 消息是格式名为 MQFMT_ADMIN ， MQFMT_EVENT 或 MQFMT_PCF 的消息。
- 不得截断 IBM MQ 结构，但在允许截断结构的以下情况下除外:
- 报告消息的消息。
- PCF 消息。
- 包含 MQDLH 结构的消息。 (可以截断第一个 MQDLH 之后的结构; 不能截断 MQDLH 之前的结构。)
- IBM MQ 结构不得拆分为两个或多个段; 该结构必须完全包含在一个段中。
缓冲区
对于 Visual Basic 编程语言，以下要点适用:
- 如果 Buffer 参数的大小小于 BufferLength 参数指定的长度，那么调用将失败，原因码为 MQRC_BUFFER_LENGTH_ERROR。
- Buffer 参数声明为类型为
String。 如果要放置在队列上的数据不是String类型，请使用 MQPUTAny 调用来代替 MQPUT。MQPUTAny 调用与 MQPUT 调用具有相同的参数，但 Buffer 参数声明为
Any类型，允许将任何类型的数据放入队列中。 但是，这意味着无法检查Buffer以确保其大小至少为BufferLength字节。
C 调用
MQPUT (Hconn, Hobj, &MsgDesc, &PutMsgOpts, BufferLength, Buffer,
&CompCode, &Reason);
按如下所示声明参数：
MQHCONN Hconn; /* Connection handle */
MQHOBJ Hobj; /* Object handle */
MQMD MsgDesc; /* Message descriptor */
MQPMO PutMsgOpts; /* Options that control the action of MQPUT */
MQLONG BufferLength; /* Length of the message in Buffer */
MQBYTE Buffer[n]; /* Message data */
MQLONG CompCode; /* Completion code */
MQLONG Reason; /* Reason code qualifying CompCode */
COBOL 调用
CALL 'MQPUT' USING HCONN, HOBJ, MSGDESC, PUTMSGOPTS, BUFFERLENGTH,
BUFFER, COMPCODE, REASON.
按如下所示声明参数：
** Connection handle
01 HCONN PIC S9(9) BINARY.
** Object handle
01 HOBJ PIC S9(9) BINARY.
** Message descriptor
01 MSGDESC.
COPY CMQMDV.
** Options that control the action of MQPUT
01 PUTMSGOPTS.
COPY CMQPMOV.
** Length of the message in BUFFER
01 BUFFERLENGTH PIC S9(9) BINARY.
** Message data
01 BUFFER PIC X(n).
** Completion code
01 COMPCODE PIC S9(9) BINARY.
** Reason code qualifying COMPCODE
01 REASON PIC S9(9) BINARY.
PL/I 调用
call MQPUT (Hconn, Hobj, MsgDesc, PutMsgOpts, BufferLength, Buffer,
CompCode, Reason);
按如下所示声明参数：
dcl Hconn fixed bin(31); /* Connection handle */
dcl Hobj fixed bin(31); /* Object handle */
dcl MsgDesc like MQMD; /* Message descriptor */
dcl PutMsgOpts like MQPMO; /* Options that control the action of
MQPUT */
dcl BufferLength fixed bin(31); /* Length of the message in Buffer */
dcl Buffer char(n); /* Message data */
dcl CompCode fixed bin(31); /* Completion code */
dcl Reason fixed bin(31); /* Reason code qualifying CompCode */
高级汇编程序调用
CALL MQPUT,(HCONN,HOBJ,MSGDESC,PUTMSGOPTS,BUFFERLENGTH, X
BUFFER,COMPCODE,REASON)
按如下所示声明参数：
HCONN DS F Connection handle
HOBJ DS F Object handle
MSGDESC CMQMDA , Message descriptor
PUTMSGOPTS CMQPMOA , Options that control the action of MQPUT
BUFFERLENGTH DS F Length of the message in BUFFER
BUFFER DS CL(n) Message data
COMPCODE DS F Completion code
REASON DS F Reason code qualifying COMPCODE
Visual Basic 调用
MQPUT Hconn, Hobj, MsgDesc, PutMsgOpts, BufferLength, Buffer, CompCode,
Reason
按如下所示声明参数：
Dim Hconn As Long 'Connection handle'
Dim Hobj As Long 'Object handle'
Dim MsgDesc As MQMD 'Message descriptor'
Dim PutMsgOpts As MQPMO 'Options that control the action of MQPUT'
Dim BufferLength As Long 'Length of the message in Buffer'
Dim Buffer As String 'Message data'
Dim CompCode As Long 'Completion code'
Dim Reason As Long 'Reason code qualifying CompCode'