SPI_execute_extended

SPI_execute_extended
Пред.	Наверх	47.1. Интерфейсные функции	Начало	След.

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
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.