第六章 创建Callout Library

Callout library 库是一个共享库，其中包含自定义Callout函数和允许 IRIS使用它们的启用代码。本章描述如何创建Callout库并在运行时访问它。
- Callout library 简介-描述如何创建和访问Callout library 。
- ZFEntry链接选项 - 提供了决定如何传递函数参数的链接选项的详细描述。
- 兼容语言和编译器-描述如何使用C以外的语言创建Callout库。
- Callout Library运行和运行函数-描述两个可选函数，可将其设置为在加载或卸载标注库时自动运行。
- 故障排除和错误处理-列出了一些应该避免的编码实践，并描述了处理UNIX信号处理错误的特殊函数。

注:共享库和标注库的术语，共享库shared library是指动态链接的文件(Windows上的DLL文件或UNIX及相关操作系统上的SO文件)。Callout library是一个共享库，它包含到$ZF Callout接口的钩子，允许各种$ZF函数在运行时加载和访问它。

Callout库简介

从ObjectScript代码访问Callout库有几种不同的方法，但一般原则是指定库名、函数名和任何必需的参数(请参阅“调用Callout库函数”)。例如，下面的代码调用一个简单的Callout库函数:

从Callout库simplecallout.dll调用AddInt函数

下面的ObjectScript代码在终端上执行。它加载一个名为simplecallout.dll的Callout库，并调用一个名为AddInt的库函数，该函数将两个整数参数相加并返回总和。

   USER> set sum = $ZF(-3,"simplecallout.dll","AddInt",2,2)
   USER> write "The sum is ",sum,!
   The sum is 4

simplecallout.dll Callout 库并不比调用它的代码复杂多少。它包含所有 Callout 库所需的三个元素：
1. 包含 iris-cdzf.h Callout 头文件时提供的标准代码。
2. 具有正确指定参数的一个或多个函数。
3. ZFEntry 表的宏代码，它生成 IRIS 将在加载库时用来定位 Callout 函数的机制。

以下是编译生成 simplecallout.dll Callout 库的代码：

simplecallout.dll 的标注代码

#define ZF_DLL  /* Required for all Callout code. */
#include <iris-cdzf.h>  /* Required for all Callout code. */

int AddTwoIntegers(int a, int b, int *outsum) {
   *outsum = a+b;   /* set value to be returned by the $ZF function call */
   return IRIS_SUCCESS;   /* set the exit status code */
}
ZFBEGIN
   ZFENTRY("AddInt","iiP",AddTwoIntegers)
ZFEND

• 前两行必须定义 ZF_DLL 并包含 iris-cdzf.h 文件。这两行始终是必需的。

• 接下来定义 AddTwoIntegers() 函数。它具有以下特点：

  • 两个输入参数，整数 a 和 b，以及一个输出参数，整数指针 *outsum。
  • 为输出参数 *outsum 赋值的语句。这将是调用 $ZF(-3) 返回的值。
  • return 语句不返回函数输出值。相反，它指定如果 $ZF 调用成功， IRIS 将接收的退出状态代码。如果该功能失败， IRIS 将收到系统生成的退出状态代码。

• 最后三行是宏调用，生成 IRIS 用来定位 Callout 库函数的 ZFEntry 表。此示例只有一个条目，其中：

  • “AddInt”是用于标识 $ZF 调用中的函数的字符串。
  • “iiP”是一个字符串，指定两个输入值和输出值的数据类型。
  • AddTwoIntegers 是 C 函数的入口点名称。

ZFEntry 表是允许通过 $ZF Callout Interface 加载和访问共享库的机制。 ZFENTRY 声明指定 C 函数和 ObjectScript $ZF 调用之间的接口。以下是该示例中接口的工作原理：

• C 函数声明指定了三个参数：

   int AddTwoIntegers(int a, int b, int *outsum)

参数a和b是输入，outsum将接收输出值。 AddTwoIntegers 的返回值是退出状态代码，而不是输出值。

• ZFENTRY 宏定义了如何在 IRIS 中识别该函数以及如何传递参数：

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

“AddInt”是库函数标识符，用于在 $ZF 调用中指定 C 函数 AddTwoIntegers。链接声明（“iiP”）将参数 a 和 b 声明为链接类型 i（仅输入整数），并将 outsum 声明为链接类型 P（可用于输入和输出的整数指针）。

• $ZF(-3) 函数调用指定库名称、库函数标识符和输入参数，并返回输出参数的值：

   set sum = $ZF(-3,"simplecallout.dll","AddInt",2,2)

参数 a 和 b 由最后两个参数指定。第三个参数 outsum 不需要参数，因为它仅用于输出。当 $ZF(-3) 调用返回时，outsum 的值被分配给 sum 。