配置 API 出口

API 出口是您自己提供的代码模块或 .dll 文件,在执行 MQI 调用之前或之后将立即运行此模块或文件。

关于本任务

IBM® MQ 接收到程序对其某个 API 入口点的调用时, IBM MQ 会调用您的 API 出口。 根据您配置 API 出口的方式,该出口在运行 MQI 之前或之后运行。

您可以配置不调用任何出口、调用一个出口或调用多个出口,并且您可以配置多个出口的调用顺序。 在 窗口Linux® (x86 和 x86-64 平台) 上,可以使用 IBM MQ 资源管理器配置 API 出口。 配置详细信息存储在 .ini 文件中。

  1. IBM MQ Explorer中配置 API 出口。
  2. 使用本地 API 出口覆盖公共 API 出口。
有三种类型的 API 出口定义:
公共 (ApiExitCommon)
每台计算机的一组定义。 当队列管理器启动时,将读取已定义的 API 出口(如果有的话)并将这些出口应用于队列管理器。 在 IBM MQ 属性对话框中配置公共 API 出口。 公共出口显示在每个本地队列管理器的“属性”对话框的局部 API 出口表中。
模板 (ApiExitTemplate)
每台计算机的一组定义。 当创建队列管理器时,此处定义的 API 出口(如果有的话)将复制到新创建的队列管理器作为局部出口。 在 IBM MQ 属性对话框中配置模板 API 出口。
局部 (ApiExitLocal)
每个队列管理器的一组定义。 当队列管理器启动时,已定义的任何 API 出口会覆盖公共出口(如果它们的名称属性相同,并且指定了覆盖)。 覆盖公共 API 出口时,即使为可选的数据属性指定了值,也不会保存公共定义中的任何字段。 在队列管理器的“属性”对话框中配置局部 API 出口。
IBM MQ 和队列管理器属性对话框中配置 API 出口时,会将属性值添加到 ApiExitCommonApiExitTemplateApiExitLocal 节中 配置文件或 Windows 注册表。
表 1. API 出口属性
属性 含义 节键
名称 指定 API 出口的描述性名称,它传递至 MQAXP 结构的 ExitInfoName 字段中的 API 出口。 此名称必须唯一,长度限制为 48 个字符,并且必须仅包含对 IBM MQ 对象的名称有效的字符,例如队列名称。 名称
类型 指定出口的类型:commontemplatelocaloverride (不是单独的节键。)
顺序 此属性是一个无符号数值,它定义了此 API 出口相对于其他 API 出口的调用顺序。 先调用序号较低的 API 出口,然后调用序号较高的 API 出口。 具有相同序号的不同 API 出口的调用顺序未进行定义。 为队列管理器定义的 API 出口指定不连续的序号可以有效地避免这种情况。 顺序
模块 指定包含 API 出口代码的模块。 如果此字段包含模块的完整路径名,那么将照原样使用它。 如果此字段仅包含模块名称,那么会使用与查找通道出口相同的方法来找到模块;即,使用“队列管理器属性”对话框的出口页面上的出口缺省路径字段中的值。 模块
函数 指定模块的函数入口点的名称,该模块包含 API 出口的代码。 此入口点是 MQ_INIT_EXIT 函数。 此字段的长度受限于 MQ_EXIT_NAME_LENGTH。 函数
数据 如果指定了此属性,那么会除去开头和末尾的空格,剩余的字符串被截断为 32 个字符,并且将结果字符串传递到 MQAXP 结构的 ExitData 字段的出口。 如果未指定此属性,那么会将 32 个空白字符的缺省值传递至 MQAXP 结构的 ExitData 字段中的出口。 数据

过程

  • [OPTION 1] 在 IBM MQ Explorer中配置 API 出口。
    1. 打开相关的“属性”对话框:
    2. 在 " 出口 " 页面上,单击 添加 ...。 “添加 API 出口”对话框打开。
    3. 在 " 添加 API 出口 " 对话框的字段中输入必需信息。
    4. 单击 确定 以创建出口并关闭 " 添加 API 出口 " 对话框。
    新 API 出口的属性显示在“出口”页的表中。
  • [选项 2] 使用局部 API 出口覆盖公共 API 出口。

    在队列管理器中使用与某个公共出口相同的名称定义局部 API 出口时,将覆盖该公共出口。 也就是说,将不会调用该公共出口,而是调用进行覆盖的局部出口。 为了防止意外覆盖,用户界面会在您配置覆盖时提醒您慎重考虑;例如,您无法添加与现有出口同名的新出口,并且无法将出口的名称更改为与现有出口相同。 然而,您可能希望将局部 API 出口添加至队列管理器,以便不使用公共 API 出口,而改用局部 API 出口。 在这种情况下,您需要使用局部 API 出口覆盖公共 API 出口。

    1. 打开 "队列管理器属性" 对话框的 出口 页面。
    2. 本地 API 出口 表中单击要覆盖的公共出口。
    3. 单击 覆盖
      编辑 API 出口”对话框打开,同时显示公共 API 出口的名称。
    4. 在 " 编辑 API 出口 " 对话框中输入本地 API 出口的详细信息,然后单击 确定 以保存更改。
    局部出口现在将覆盖同名的公共出口。