34.8. 快速路径接口#

PostgreSQL提供了一个快速路径接口，用于向服务器发送简单的函数调用。

提示

此接口有点过时，因为可以通过设置预处理语句来定义函数调用，从而实现类似的性能和更强大的功能。然后，使用参数和结果的二进制传输执行语句，以代替快速路径函数调用。

函数PQfn通过快速路径接口请求执行服务器函数

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（如果遇到某些问题）。在使用结果之前，应检查结果状态。调用方负责在不再需要PGresult时使用PQclear释放它。

要向函数传递 NULL 参数，请将该参数结构的*len字段设置为-1；然后，isint和u*字段将变得无关紧要。

如果函数返回 NULL，则将**result_len设置为-1，并且不会修改*result_buf*。

请注意，使用此接口时无法处理集合值结果。此外，该函数必须是普通函数，而不是聚合函数、窗口函数或过程。