SPI_execute_extended

SPI_execute_extended — выполнить команду с выделенными параметрами

Синтаксис

int SPI_execute_extended(const char *command,
                         const SPIExecuteOptions * options)

Описание

SPI_execute_extended выполняет команду, которая может включать ссылки на параметры, передаваемые извне. В тексте команды параметры обозначаются символами $n; тип и значение каждого такого параметра предоставляются в объекте options->params (если он передаётся). В options также могут передаваться различные параметры выполнения.

Как правило, в объекте options->params все параметры должны иметь пометку PARAM_FLAG_CONST, поскольку для запроса всегда используется одноразовый план.

Если значение options->dest не NULL, то результирующие кортежи передаются в этот объект по мере их формирования исполнителем, а не накапливаются в SPI_tuptable. Подготовить и использовать объект DestReceiver особенно полезно для запросов, при выполнении которых можно получить множество кортежей, так как этот объект позволяет обрабатывать данные «на лету», не дожидаясь их накопления в памяти.

Аргументы

const char * command

строка команды

const SPIExecuteOptions * options

структура, содержащая необязательные аргументы

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

ParamListInfo params

структура данных, содержащая типы и значения параметров запроса; NULL, если их нет

bool read_only

true для режима выполнения «только чтение»

bool allow_nonatomic

true для неатомарного выполнения операторов CALL и DO (но это поле игнорируется, если функции SPI_connect_ext не был передан флаг SPI_OPT_NONATOMIC)

bool must_return_tuples

если true, вызывает ошибку для типов запросов, не возвращающих кортежи (за исключением случая, когда возвращаются нулевые кортежи)

uint64 tcount

максимальное число строк, которое должно быть возвращено; с 0 ограничения нет

DestReceiver * dest

объект DestReceiver, получающий все кортежи, которые выдаёт запрос; если NULL, результирующие кортежи накапливаются в SPI_tuptable, как при выполнении SPI_execute

ResourceOwner owner

Это поле присутствует для согласованности с SPI_execute_plan_extended, но игнорируется, поскольку используемый SPI_execute_extended план никогда не сохраняется.

Возвращаемое значение

Возвращаемые значения те же, что и у SPI_execute.

Если options->dest имеет значение NULL, то SPI_processed и SPI_tuptable устанавливаются как при выполнении SPI_execute. Если options->dest — не­­ NULL, то SPI_processed принимает нулевое значение, а SPI_tuptable — NULL. Если необходимо подсчитать число кортежей, это нужно сделать в коде объекта DestReceiver.