PostgreSQL 提供了一种快速路径接口, 用于向服务器发送简单的函数调用。
这个接口是不安全的,
不应当被使用。
当 result_is_int
被设置为 0 时,
PQfn
可能会把数据写到
result_buf
的末尾之外,
而不管该缓冲区是否有足够的空间容纳所请求数量的字节。
此外,
它已经过时了,
因为通过建立一个已准备语句来定义函数调用,
可以获得类似的性能和更多的功能。
然后,
以二进制方式传输参数和结果来执行该语句,
就可以取代一次快速路径函数调用。
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。
在使用结果之前应当检查结果状态。
当不再需要该
PGresult 时,
调用者有责任用
PQclear
释放它。
要向函数传递一个 NULL 参数,
把那个参数结构的
len
字段设置为 -1;
此时 isint
和 u
字段就无关紧要了。
如果函数返回 NULL,
*result_len
会被设置为 -1,
并且 *result_buf
不会被修改。
注意,在使用这个接口时无法处理集合值的结果。 此外, 该函数必须是一个普通函数, 不能是聚集、窗口函数或过程。