SPI_execute_extended

SPI_execute_extended
Prev	Up	45.1. Funciones de interfaz	Home	Next

SPI_execute_extended — ejecuta un comando con parámetros externos (out-of-line)

Synopsis

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

Descripción

SPI_execute_extended ejecuta un comando que puede incluir referencias a parámetros suministrados externamente. El texto del comando se refiere a un parámetro como $n, y el objeto options->params (si se proporciona) proporciona los valores y la información de tipo para cada uno de esos símbolos. También se pueden especificar varias opciones de ejecución en la estructura options.

El objeto options->params normalmente debería marcar cada parámetro con la bandera PARAM_FLAG_CONST, ya que siempre se utiliza un plan de un solo uso (one-shot plan) para la consulta.

Si options->dest no es NULL, entonces las tuplas de resultado se pasan a ese objeto a medida que las genera el ejecutor, en lugar de acumularse en SPI_tuptable. Utilizar un objeto DestReceiver proporcionado por el llamador es particularmente útil para consultas que podrían generar muchas tuplas, ya que los datos se pueden procesar sobre la marcha en lugar de acumularse en la memoria.

Argumentos

const char * command: cadena de comando
const SPIExecuteOptions * options: estructura que contiene los argumentos opcionales

Los llamadores siempre deben inicializar en cero toda la estructura options y luego rellenar los campos que deseen establecer. Esto garantiza la compatibilidad futura del código, ya que cualquier campo que se añada a la estructura en el futuro se definirá para comportarse de manera compatible con versiones anteriores si está en cero. Los campos de options actualmente disponibles son:

ParamListInfo params: estructura de datos que contiene los tipos y valores de los parámetros de la consulta; NULL si no hay ninguno
bool read_only: true para una ejecución de solo lectura
bool allow_nonatomic: true permite la ejecución no atómica de sentencias CALL y DO (pero este campo se ignora a menos que se haya pasado la bandera SPI_OPT_NONATOMIC a SPI_connect_ext)
bool must_return_tuples: si es true, lanza un error si la consulta no es del tipo que devuelve tuplas (esto no prohíbe el caso en el que resulte devolver cero tuplas)
uint64 tcount: número máximo de filas a devolver, o 0 para ilimitado
DestReceiver * dest: objeto DestReceiver que recibirá las tuplas emitidas por la consulta; si es NULL, las tuplas de resultado se acumulan en una estructura SPI_tuptable, al igual que en SPI_execute
ResourceOwner owner: Este campo está presente por consistencia con SPI_execute_plan_extended, pero se ignora, ya que el plan utilizado por SPI_execute_extended nunca se guarda.

Valor de retorno

El valor de retorno es el mismo que para SPI_execute.

Cuando options->dest es NULL, SPI_processed y SPI_tuptable se establecen como en SPI_execute. Cuando options->dest no es NULL, SPI_processed se establece en cero y SPI_tuptable se establece en NULL. Si se requiere un conteo de tuplas, el objeto DestReceiver del llamador debe calcularlo.