pgsql.cc 提供对 postgresql.org 官网内容的中文翻译,由 Pigsty 团队维护。
PostgreSQL提供一种快速路径接口来向服务器发送简单的函数调用。
此接口已显得有些过时,因为可以通过建立定义函数调用的预备语句,获得相近的性能和更多功能。随后使用二进制格式传输参数和结果来执行该语句,就可以替代快速路径函数调用。
PGresult *PQfn(PGconn *conn,
int fnid,
int *result_buf,
int *result_len,
int result_is_int,
const PQArgBlock *args,
int nargs);
typedef struct
{
int len;
int isint;
union
{
int *ptr;
int integer;
} u;
} PQArgBlock;
fnid 参数是要执行函数的 OID。args 和 nargs 指定传给函数的参数,必须与函数声明中的参数列表匹配。参数结构体的 isint 字段为真时,u.integer 值会以指定长度的整数发送到服务器,该长度必须是 2 或 4 字节,并会进行适当的字节序转换。isint 为假时,位于 *u.ptr 的指定数量字节会原样发送;数据必须符合服务器对该函数参数数据类型的二进制传输格式要求。(将 u.ptr 声明为 int * 是历史原因;将其视为 void * 更合适。)result_buf 指向用于存放函数返回值的缓冲区。调用者必须事先分配足够空间来保存返回值,这里不会检查!实际结果长度以字节为单位,返回到 result_len 指向的整数中。如果预期结果是 2 或 4 字节整数,将 result_is_int 设为 1,否则设为 0。将 result_is_int 设为 1 后,libpq 会按需转换字节序,使结果成为适合客户端机器的 int 值;注意,无论是哪种允许的结果大小,传入 *result_buf 的都是 4 字节整数。result_is_int 为 0 时,服务器发送的二进制格式字节串会原样返回。(此时,将 result_buf 视为 void * 更合适。)
PQfn 总是返回有效的 PGresult 指针:成功时状态为 PGRES_COMMAND_OK,遇到问题时为 PGRES_FATAL_ERROR。使用结果前应检查其状态。不再需要结果时,调用者负责使用 PQclear 释放 PGresult。
要向函数传入 NULL 参数,将该参数结构体的 len 字段设为 -1;此时,isint 和 u 字段便不再相关。(但这仅适用于使用协议 3.0 及更高版本的连接。)
如果函数返回 NULL,则将 *result_len 设为 -1,而不修改 *result_buf。(这仅适用于使用协议 3.0 及更高版本的连接;在协议 2.0 中,既不修改 *result_len,也不修改 *result_buf。)
注意,使用此接口时无法处理集合值结果。此外,函数必须是普通函数,不能是聚合函数或窗口函数。
译文有误、术语不当或页面显示问题,请到译文仓库 pgsty/pgdoc 报告译文问题。 英文原文本身的问题,请在当前版本的对应页面向上游反馈;上游不再修订已结束维护的版本。