[UNIX、Linux、Windows、IBM i]

编写 API 出口

您可以使用 C 编程语言为每个 API 调用编写出口。

可用出口

出口可用于每个 API 调用，具体如下：
  • MQCB，为指定对象句柄重新注册回调并控制对回调的激活和更改
  • MQCTL，对为连接打开的对象句柄执行控制操作
  • MQCONN/MQCONNX，提供后续 API 调用使用的队列管理器连接句柄
  • MQDISC，断开与队列管理器的连接
  • MQBEGIN，开始全局工作单元（UOW）
  • MQBACK，回退工作单元
  • MQCMIT，落实工作单元
  • MQOPEN ，打开 IBM® MQ 资源以进行后续访问
  • MQCLOSE ，用于关闭先前已打开以进行访问的 IBM MQ 资源
  • MQGET，检索先前为进行访问而打开的队列中的消息
  • MQPUT1，将消息放入队列
  • MQPUT，将消息放入先前为了访问而打开的队列
  • MQINQ ，用于查询先前已打开用于访问的 IBM MQ 资源的属性
  • MQSET，设置先前为了访问而打开的队列的属性
  • MQSTAT，检索状态信息
  • MQSUB，向特定主题注册应用程序预订
  • MQSUBRQ，发出预订请求

MQ_CALLBACK_EXIT 提供出口函数以在回调处理之前和之后执行。 有关更多信息，请参阅 Callback-MQ_CALLBACK_EXIT。

编写 API 出口

在 API 出口内，调用采用一般形式：
MQ_call_EXIT (parameters, context, ApiCallParameters)
其中 call 是不带 MQ 前缀的 MQI 调用名称；例如，PUT、GET。 parameters 控制出口的功能，主要提供出口与外部控制块之间的通信 MQAXP (API 出口参数结构) 和 MQAXC (API 出口上下文结构)。 context 描述调用 API 出口的上下文，ApiCallParameters 表示 MQI 调用的参数。

为了帮助您编写 API 出口，提供了样本出口 amqsaxe0.c，此出口可为您指定的文件生成跟踪条目。 编写出口时，可以使用此样本作为起点。 有关使用样本出口的更多信息，请参阅 API 出口样本程序。

有关 API 出口调用，外部控制块和关联主题的更多信息，请参阅 API 出口参考。

有关如何编写，编译和配置出口的常规信息，请参阅 在 AIX， Linux和 Windows 上编写出口和可安装服务。

在 API 出口中使用消息句柄

您可以控制 API 出口对哪些消息属性有访问权。 属性与 ExitMsgHandle 相关联。 PUT 出口中的属性集在放入消息时设置，但 GET 出口中检索到的属性不会返回到应用程序。

使用 MQXEP MQI 调用（Function 设置为 MQXF_INIT，ExitReason 设置为 MQXR_CONNECTION）注册 MQ_INIT_EXIT 出口函数时，作为 ExitOpts 参数传入 MQXEPO 结构。 MQXEPO 结构包含 ExitProperties 字段，该字段指定可设置为用于此出口的属性集。 该字段指定为表示属性前缀的字符串，此字符串与 MQRFH2 文件夹名称对应。

每个 API 出口都会收到包含 ExitMsgHandle 字段的 MQAXP 结构。 此字段设置为 IBM MQ 生成的值，并且特定于连接。 因此，句柄在同一连接上相同类型或不同类型的 API 出口间保持不变。

在 ExitReason 为 MQXR_BEFORE 的 MQ_PUT_EXIT 或 MQ_PUT1_EXIT 中（即放入消息之前执行的 API 出口中），出口完成时与 ExitMsgHandle 关联的任何属性（除消息描述符属性外）将在放入消息时进行设置。 为了防止出现此情况，请将 ExitMsgHandle 设置为 MQHM_NONE。 您也可以提供其他消息句柄。

在 MQ_GET_EXIT 和 MQ_CALLBACK_EXIT 中，除消息描述符属性外，ExitMsgHandle的属性将被清除，并用注册 MQ_INIT_EXIT 时在ExitProperties字段中指定的属性填充。 这些属性不可用于获取应用程序。 如果获取应用程序在 MQGMO（获取消息选项）字段中指定了消息句柄，那么与该句柄关联的任何属性（包括消息描述符属性）都可用于 API 出口。 为了防止使用属性填充 ExitMsgHandle，请将其设置为 MQHM_NONE。
注: 对于要处理的出口消息属性:
  • 在 MQ_GET_EXIT 函数之后，必须为出口定义 MQ_GET_EXIT 函数之前的函数。
  • MQ_CALLBACK_EXIT 之前的函数，必须为该出口定义 MQ_CB_EXIT 之前的函数。

[MQ 9.3.2 2023 年 2 月]从 IBM MQ 9.3.2开始，先前有关 MQ-GET-EXIT 和 MQ_CALLBACK_EXIT 的语句不再适用。

提供了样本程序 amqsaem0.c 来展示 API 出口中消息句柄的使用。