31.8. Интерфейс Fast-Path#
31.8. Интерфейс Fast-Path #
Tantor BE предоставляет интерфейс быстрого доступа к серверу для отправки простых вызовов функций.
Подсказка
Этот интерфейс является устаревшим, так как можно достичь аналогичной производительности и большей функциональности, настроив подготовленный оператор для определения вызова функции. Затем выполнение оператора с двоичной передачей параметров и результатов заменяет вызов функции быстрого пути.
Функция 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. Если ожидается результат в виде 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 не изменяется.
Обратите внимание, что невозможно обрабатывать результаты, имеющие множественные значения, при использовании этого интерфейса. Кроме того, функция должна быть обычной функцией, а не агрегатной, оконной функцией или процедурой.