第十六章 调用Callout Library函数

Callout 库是一个共享库（DLL 或 SO 文件），其中包含 $ZF Callout 接口的挂钩，允许各种 $ZF 函数在运行时加载它并调用其函数。 $ZF Callout 接口提供了四种不同的接口，可用于在运行时加载 Callout 库并从该库调用函数。这些接口的主要区别在于如何识别库并将其加载到内存中：

• 使用 $ZF() 访问 iriszf 标注库描述了如何使用名为 iriszf 的特殊共享库。当该库可用时，可以通过 $ZF("funcname",args) 形式的调用来访问其函数，而无需事先加载该库或指定库名称。
• 使用 $ZF(-3) 进行简单库函数调用描述了如何通过指定库文件路径和函数名来加载库并调用函数。它使用简单，但虚拟内存中一次只能有一个库。与其他接口不同，它在调用库函数之前不需要任何初始化。
• 使用 $ZF(-5) 通过系统 ID 访问库描述了一种可用于一次有效维护和访问多个库的接口。可以同时加载和使用多个库，每个库所需的处理开销比 $ZF(-3) 少得多。内存中的库由加载库时生成的系统定义的 ID 来标识。
• 使用 $ZF(-6) 按用户索引访问库描述了处理大量标注库的最有效接口。该接口通过Global定义的索引表提供对库的访问。该索引可供 IRIS 实例中的所有进程使用，并且多个库可以同时位于内存中。每个索引库都被赋予一个唯一的、用户定义的索引号，并且可以在运行时定义和修改索引表。当库文件被重命名或重新定位时，与给定库 ID 关联的文件名可以更改，并且此更改对于按索引号加载库的应用程序来说是透明的。

使用 $ZF() 访问 iriszf 标注库

当名为 iriszf 的 Callout 库在实例的 <install_dir>/bin 目录中可用时，可以通过仅指定函数名称和参数的 $ZF 调用来调用其函数（例如，$ZF("functionName",arg1, arg2)).。无需事先加载库即可调用 iriszf 函数，并且实例中的所有进程都可以使用 iriszf 函数。

自定义 iriszf 库是通过创建标准 Callout 库、将其移动到实例的 <install_dir>/bin 目录并将其重命名为 iriszf（具体为 iriszf.dll 或 iriszf.so，具体取决于平台）来定义的。

以下是编译 simplecallout.c 示例（请参阅“创建 Callout 库”）并将其设置为 iriszf 库的步骤。这些示例假设实例在 Linux 下运行，安装在名为 /intersystems/iris 的目录中，但所有平台上的过程基本相同：

1. 编写并保存 simplecallout.c：

#define ZF_DLL
#include "iris-cdzf.h"
int AddTwoIntegers(int a, int b, int *outsum) {
  *outsum = a+b;  /* set value to be returned by $ZF function call */
  return IRIS_SUCCESS;  /* set the exit status code */
}

ZFBEGIN
  ZFENTRY("AddInt","iiP",AddTwoIntegers)
ZFEND

2. 生成Callout库文件（simplecallout.so）：

gcc -c -fPIC simplecallout.c -I /intersystems/iris/dev/iris-callin/include/ -o simplecallout.o
gcc simplecallout.o -shared -o simplecallout.so

3. 从 IRIS 终端会话中使用 $ZF(-3) 测试库：

USER>write $ZF(-3,"/mytest/simplecallout.so","AddInt",1,4)
5

4. 现在安装该库以与 $ZF() 一起使用。将 simplecallout.so 复制到 <install_dir>/bin中，并将其重命名为 iriszf.so：

cp simplecallout.so /intersystems/iris/bin/iriszf.so

5. 确认可以从 IRIS 会话中使用 $ZF() 调用代码：

USER>write $zf("AddInt",1,4)
5

iriszf 库在首次使用时加载一次，并且永远不会卸载。它完全独立于本章前面描述的其他 $ZF 加载和卸载操作。

注意：静态链接库 $ZF Callout Interface 的早期版本允许将代码静态链接到 InterSystems 内核并使用 $ZF() 进行调用。不再支持静态链接，但 irisz 库提供相同的功能，无需重新链接内核。