第八章 创建Callout Library - ZFentry 链接选项

第八章 创建Callout Library - ZFentry 链接选项

ZFentry 链接选项

每个 ZFENTRY 语句都需要一个字符串来确定函数参数的传递方式。本节提供可用链接选项的详细说明。

• 链接简介 — 概述了各种链接类型，并列出了本章讨论的所有链接选项。
• 使用数字链接 — 描述数字参数的链接选项。
• 使用 C 链接类型传递空终止字符串 — 描述空终止字符串的链接选项。
• 使用 B 链接类型传递短计数字符串 — 描述使用 ZARRAY 结构进行计数字符数组的链接。
• 使用 J 链接类型传递标准计数字符串 — 描述使用 IRIS IRIS_EXSTR 结构进行计数字符数组的链接。
• 为传统短字符串配置 $ZF 堆 — 描述控制传统短字符串参数传递的内存分配的 IRIS 系统设置。

链接简介

每个 ZFENTRY 语句都需要一个描述如何传递参数的字符串。例如，“iP”指定两个参数：一个整数和一个指向整数的指针。第二个字母大写以指定第二个参数可用于输入和输出。代码最多可以有 32 个实际参数和形式参数。

如果指定大写链接类型（允许用于除 i 之外的所有链接类型），则该参数可用于输入和输出。如果仅指定一个输出参数，则其最终值将用作函数的返回值。如果指定了多个输出参数，则所有输出参数都将以逗号分隔的字符串形式返回。

输出参数不必用作输入参数。如果在所有输入参数之后指定仅输出参数，则可以在不指定任何输出参数的情况下调用该函数。

从ObjectScript程序员的角度来看，参数只是输入。实际参数的值由 $ZF 调用计算并链接到 C 例程声明中的形式参数。对 C 形式参数的任何更改要么会丢失，要么可以复制到 $ZF 返回值。

如果 ZFENTRY 宏未指定用作返回值的形式参数，则 $ZF 调用将返回空字符串 ("")。链接声明可以包含多个输出参数。在这种情况下，所有返回值都将转换为单个逗号分隔的字符串。无法区分多个返回参数之间插入的逗号和任何一个返回值中存在的逗号，因此只有最终返回值才应包含逗号。

下表描述了可用选项：

C Datatype	Input	In/Out	Notes
int	i or 4i	none (use P)	指定 32 位整数。 i 链接类型仅用于输入。要返回整数类型，请使用 P 或 4P (int *)。输入参数可以是数字字符串（参见注释 1）。
int *	p or 4p	P or 4P	指向 32 位整数的指针。输入参数可以是数字字符串（参见注释 1）。
_int64	8i	none (use 8P)	指定 64 位整数。要返回 64 位整数类型，请使用 8P。输入参数可以是数字字符串（参见注释 1）。
_int64 *	8p	8P	指向 64 位整数的指针。输入参数可以是数字字符串（参见注释 1）。
double *	d	D	输入参数可以是数字字符串（参见注释 1）。使用 #D 以基数 2 格式保留双 *（参见注释 2）。
float *	f	F	输入参数可以是数字字符串（参见注释 1）。使用 #F 以基数 2 格式保留浮点数 *（参见注释 2）。
char *	1c or c	1C or C	这是常见的 C NULL 终止字符串（参见注释 3）。
unsigned short *	2c or w	2C or W	这是一个 C 风格的 NULL 终止 UTF-16 字符串（参见注释 3）。
wchar t *	4c	4C	这是一个以 NULL 结尾的 C 风格字符串，存储为 wchar_t 元素的向量（请参阅注释 3 和 4）。
ZARRAYP	1b or b	1B or B	短的8位国家字符串(最多32，767个字符)。
ZWARRAYP	2b or s	2B or S	16位Unicode短字符串(最多32,767个字符)。
ZHARRAYP	4b	4B	存储在 wchar_t 实现的元素中的短 Unicode 字符串（最多 32,767 个字符）（参见注释 4）
IRIS_EXSTR	1j or j	1J or J	8 位国家字符的标准字符串（不超过字符串长度限制）
IRIS_EXSTR	2j or n	2J or N	16 位 Unicode 字符的标准字符串（不超过字符串长度限制）
IRIS_EXSTR	4j	4J	wchar_t 字符的标准字符串（最多字符串长度限制）（参见注释 4）

1. i、p、d、f — 当指定数字参数时， IRIS 允许输入参数为字符串。有关详细信息，请参阅“使用数字链接”。
2. #F、#D — 要以基数 2 浮点格式保存数字，请使用 #F 表示 float * 或使用 #D 表示 double *。
3. 1C、2C、4C — 通过此链接传递的所有字符串都将在第一个空字符处被截断。
4. 4B、4C、4J — 虽然 wchar_t 通常为 32 位，但 IRIS 仅使用 16 位来存储每个 Unicode 字符。包含较大 wchar_t 值的输出参数将转换为 UTF-16 以分配给 $ZF 返回值。对于 $ZF 输入参数，包含 UTF-16（代理项对）的字符串将扩展为 wchar_t。可以使用 ObjectScript 函数 $WASCII() 和 $WCHAR() 访问真正的 wchar_t 值。

结构和参数原型定义（包括内部定义）可以在包含文件 iris-cdzf.h 中看到。