文章
· 十二月 26, 2023 阅读大约需 4 分钟

第六章 创建Callout Library

第六章 创建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库函数:

Calloutsimplecallout.dll调用AddInt函数

下面的ObjectScript代码在终端上执行。它加载一个名为simplecallout.dllCallout库,并调用一个名为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() 函数。它具有以下特点:

    • 两个输入参数,整数 ab,以及一个输出参数,整数指针 *outsum
    • 为输出参数 *outsum 赋值的语句。这将是调用 $ZF(-3) 返回的值。
    • return 语句不返回函数输出值。相反,它指定如果 $ZF 调用成功, IRIS 将接收的退出状态代码。如果该功能失败, IRIS 将收到系统生成的退出状态代码。
  • 最后三行是宏调用,生成 IRIS 用来定位 Callout 库函数的 ZFEntry 表。此示例只有一个条目,其中:

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

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

  • C 函数声明指定了三个参数:
   int AddTwoIntegers(int a, int b, int *outsum)

参数ab是输入,outsum将接收输出值。 AddTwoIntegers 的返回值是退出状态代码,而不是输出值。

  • ZFENTRY 宏定义了如何在 IRIS 中识别该函数以及如何传递参数:
   ZFENTRY("AddInt","iiP",AddTwoIntegers)

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

  • $ZF(-3) 函数调用指定库名称、库函数标识符和输入参数,并返回输出参数的值:
   set sum = $ZF(-3,"simplecallout.dll","AddInt",2,2)

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

讨论 (0)1
登录或注册以继续