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值被传输,注意对任一种允许的结果大小都会传递一个 4 字节整数到*result_buf。当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。)
注意,使用此接口时无法处理集合值结果。此外,函数必须是普通函数,不能是聚合函数或窗口函数。