SPI_cursor

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

SPI_cursor_open

SPI_cursor_open — configura um cursor usando uma instrução preparada por SPI_prepare

Sinopse

Portal SPI_cursor_open(const char * name, SPIPlanPtr plan,
                       Datum * values, const char * nulls,
                       bool read_only)

Descrição

A função SPI_cursor_open configura um cursor (internamente, um portal), que executa uma instrução preparada por SPI_prepare. Os parâmetros têm os mesmos significados que os parâmetros correspondentes na função SPI_execute_plan.

Usar um cursor em vez de executar a instrução diretamente traz dois benefícios. Primeiro, as linhas de resultados podem ser recuperadas algumas de cada vez, evitando sobrecarga de memória para consultas que retornam muitas linhas. Em segundo lugar, o portal pode viver para além da função C corrente (pode, de fato, durar até o final da transação corrente). Retornar o nome do portal ao chamador da função C fornece uma maneira de retornar um conjunto de linhas como resultado.

Os dados dos parâmetros passados são copiados para o portal do cursor, para poderem ser liberados enquanto o cursor ainda existir.

Argumentos

const char * name

nome para o portal, ou NULL para permitir que o sistema selecione o nome

SPIPlanPtr plan

instrução preparada (retornada por SPI_prepare)

Datum * values

Matriz contendo os valores dos parâmetros. Deve ter o mesmo comprimento que o número de argumentos da instrução.

const char * nulls

Matriz descrevendo quais parâmetros são nulos. Deve ter o mesmo comprimento que o número de argumentos da instrução.

Se o parâmetro nulls for NULL, então a função SPI_cursor_open assume que nenhum parâmetro é nulo. Caso contrário, cada entrada na matriz nulls deverá ser ' ' se o valor do parâmetro correspondente não for nulo, ou 'n' se o valor do parâmetro correspondente for nulo. (Neste último caso, o valor real na entrada correspondente em values não importa.) Note que nulls não é uma cadeia de caracteres de texto, e sim uma matriz: não há necessidade do terminador '\0'.

bool read_only

true para execução de leitura-apenas

Valor retornado

Ponteiro para o portal que contém o cursor. Note não haver convenção de retorno de erro; qualquer erro será relatado via elog.