SPI_execute_plan

SPI_execute_plan_extended
Anterior	Acima	45.1. Funções de interface	Principal	Próxima

SPI_execute_plan_extended

SPI_execute_plan_extended — executa uma instrução preparada por SPI_prepare

Sinopse

int SPI_execute_plan_extended(SPIPlanPtr plan,
                              const SPIExecuteOptions * options)

Descrição

A função SPI_execute_plan_extended executa uma instrução preparada por SPI_prepare ou uma de suas irmãs. Esta função é equivalente à função SPI_execute_plan, exceto que as informações sobre os valores dos parâmetros a serem passados para a consulta são apresentadas de forma diferente, e podem ser passadas opções adicionais de controle de execução.

Os valores dos parâmetros da consulta são representados por uma estrutura ParamListInfo, conveniente para transmitir valores que já estão disponíveis neste formato. Também podem ser usados conjuntos de parâmetros dinâmicos, por meio de funções de gancho especificadas em ParamListInfo.

Além disso, em vez de sempre acumular as tuplas resultantes em uma estrutura SPI_tuptable, as tuplas podem ser passadas para um objeto DestReceiver fornecido pelo chamador à medida que são geradas pelo executor. Isto é particularmente útil para consultas que podem gerar muitas tuplas, uma vez que os dados podem ser processados dinamicamente em vez de serem acumulados na memória.

Argumentos

SPIPlanPtr plan: instrução preparada (retornada por SPI_prepare)
const SPIExecuteOptions * options: estrutura contendo argumentos opcionais

Os chamadores devem sempre zerar toda a estrutura de options e, em seguida, preencher os campos que desejam definir. Isto garante a compatibilidade futura do código, uma vez que quaisquer campos adicionados à estrutura no futuro serão definidos para se comportarem de maneira compatível com versões anteriores se forem zero. Os campos de options disponíveis no momento são:

ParamListInfo params: estrutura de dados contendo tipos de dados e valores dos parâmetros da consulta; NULL se nenhum
bool read_only: true para execução de leitura-apenas
bool allow_nonatomic: true permite a execução não atômica de instruções CALL e DO (mas este campo será ignorado a menos que tenha sido passado o sinalizador SPI_OPT_NONATOMIC para SPI_connect_ext)
bool must_return_tuples: Se for true, irá lançar um erro se a consulta não for do tipo que retorna tuplas. (Isto não impede o caso em que são retornadas zero tuplas.)
uint64 tcount: número máximo de linhas a serem retornadas, ou 0 para sem limite
DestReceiver * dest: objeto DestReceiver que irá receber quaisquer tuplas emitidas pela consulta; se NULL, as tuplas de resultados são acumuladas em uma estrutura SPI_tuptable, como em SPI_execute_plan
ResourceOwner owner: O dono do recurso que irá manter a contagem de referência no plano enquanto ele é executado. Se NULL, será usado CurrentResourceOwner. Ignorado para planos não salvos, porque a SPI não adquire contagens de referência sobre eles.

Valor retornado

O valor retornado é o mesmo que para SPI_execute_plan.

Quando options->dest é NULL, SPI_processed e SPI_tuptable são definidos como em SPI_execute_plan. Quando options->dest não é NULL, SPI_processed é definido como zero, e SPI_tuptable é definido como NULL. Se for requerida a contagem das tuplas, o objeto DestReceiver do chamador deverá calculá-la.