SPI_execute_extended

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

SPI_execute_extended — executa um comando com parâmetros fora de linha

Sinopse

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

Descrição

A função SPI_execute_extended executa um comando que pode incluir referências a parâmetros fornecidos externamente. O texto do comando refere-se ao parâmetro como $n, e o objeto options->params (se fornecido) fornece valores e informações de tipo de dados para cada símbolo. Também podem ser especificadas várias opções de execução na estrutura options.

O objeto options->params normalmente deve marcar cada parâmetro com o sinalizador PARAM_FLAG_CONST, já que é sempre usado um plano de uma única vez para a consulta.

Se options->dest não for NULL, então as tuplas resultantes são passadas para este objeto à medida que são geradas pelo executor, em vez de serem acumuladas em SPI_tuptable. Usar um objeto DestReceiver fornecido pelo chamador é 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

const char * command: cadeia de caracteres de comando
const SPIExecuteOptions * options: estrutura contendo argumentos opcionais

Os chamadores sempre devem zerar toda a estrutura 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 opções atualmente disponíveis são:

ParamListInfo params: estrutura de dados contendo tipos de dados e valores de 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 é 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: o objeto DestReceiver que irá receber quaisquer tuplas produzidas pela consulta; se NULL, as tuplas de resultados serão acumuladas em uma estrutura SPI_tuptable, como em SPI_execute
ResourceOwner owner: este campo está presente para consistência com SPI_execute_plan_extended, mas é ignorado, porque o plano usado por SPI_execute_extended nunca é salvo.

Valor retornado

O valor retornado é o mesmo que para a função SPI_execute.

Quando options->dest é NULL, SPI_processed e SPI_tuptable são definidos como em SPI_execute. Quando options->dest não é NULL, SPI_processed é definido como zero, e SPI_tuptable é definido como NULL. Se houver necessidade uma contagem de tuplas, o objeto DestReceiver do chamador deverá calculá-la.