Интерфейс быстрого пути

QHB предоставляет интерфейс для передачи серверу простых вызовов функций по быстрому пути.

Совет
Этот интерфейс в некотором роде устарел, так как подобной производительности и более высокой функциональности можно добиться, создав подготовленный оператор для определения вызова функции. Последующее выполнение этого оператора с передачей параметров и результатов в двоичном виде заменяет вызов функции по быстрому пути.

Функция 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 структуры параметра равно true, значение поля u.integer передается серверу в виде целого числа указанной длины (это должно быть 2 или 4 байта); при этом происходит перестановка байтов. Когда isint равно false, указанное количество байтов из поля *u.ptr передается без обработки; эти данные должны быть представлены в формате, ожидаемом сервером для передачи в двоичном виде типа данных аргументов функции. (Объявление поля u.ptr как имеющего тип int * является историческим; было бы лучше рассматривать его как тип void *.) Аргумент result_buf указывает на буфер, в который должно быть помещено возвращаемое значение функции. Вызывающая функция должна выделить достаточно места для сохранения возвращаемого значения. (Это не проверяется!) Фактическая длина результата в байтах будет возвращена в виде целого числа, на которое указывает result_len. Если ожидается двух- или четырехбайтовый целочисленный результат, установите в result_is_int значение 1; в противном случае установите там 0. Когда значение result_is_int равно 1, libpq при необходимости переставляет байты в передаваемом значении, чтобы оно доставлялось на клиентскую машину в виде правильного значения типа int; обратите внимание, что четырехбайтовое целое доставляется в *result_buf для любого допустимого размера результата. Когда значение result_is_int равно 0, строка байтов в двоичном формате, передаваемая сервером, возвращается немодифицированной. (В этом случае лучше рассматривать result_buf как имеющий тип void *.)

Функция PQfn всегда возвращает действительный указатель на PGresult со статусом PGRES_COMMAND_OK при успехе или PGRES_FATAL_ERROR при столкновении с какой-либо проблемой. Перед использованием результата обязательно нужно проверить его статус. Вызывающая функция отвечает за освобождение с помощью функции PQclear памяти, занимаемой PGresult, когда в этом объект больше нет необходимости.

Чтобы передать функции аргумент NULL, установите в поле len этой структуры параметра значение -1; при этом поля isint и u не важны.

Если функция возвращает NULL, в *result_len устанавливается значение -1, а *result_buf не модифицируется.

Обратите внимание, что при использовании этого интерфейса невозможно обработать результаты с множеством значений. Кроме того, функция должна быть простой функцией, а не агрегатом, оконной функцией или процедурой.