SPI_execute_plan_extended

SPI_execute_plan_extended — выполнить оператор, подготовленный функцией SPI_prepare

Синтаксис

int SPI_execute_plan_extended(SPIPlanPtr plan,
                              const SPIExecuteOptions * options)

Описание

SPI_execute_plan_extended выполняет оператор, подготовленный функцией SPI_prepare или родственными ей. Данная функция равнозначна SPI_execute_plan, не считая того, что по-другому представляется информация о значениях параметров, передаваемых запросу. Также ей могут передаваться дополнительные параметры для управления выполнением запроса.

Значения параметров запроса передаются в структуре ParamListInfo; это удобно, когда имеющиеся значения уже представлены в этом формате. Через функции-обработчики, устанавливаемые в ParamListInfo, можно также передавать динамические наборы параметров.

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

Аргументы

SPIPlanPtr plan

подготовленный оператор (возвращаемый функцией SPI_prepare)

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_plan

ResourceOwner owner

Владелец ресурса, который будет содержать счётчик ссылок на план во время его выполнения. Если NULL, используется текущий владелец ресурса. Параметр игнорируется для несохранённых планов, поскольку SPI не получает счётчики ссылок на них.

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

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

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