Подсказка

Данный интерфейс является в некоторой степени устаревшим, так как аналогичной производительности и большей функциональности можно достичь путем создания подготовленного оператора для определения вызова функции. В этом случае выполнение оператора с бинарной передачей параметров и результатов заменяет собой вызов функции через интерфейс fast-path.

Функция PQfn запрашивает выполнение функции сервера через интерфейс fast-path:

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 не изменяется.

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