SPI_execute_plan

SPI_execute_plan_extended
Prev	Up	45.1. Funciones de interfaz	Home	Next

SPI_execute_plan_extended

SPI_execute_plan_extended — ejecuta una sentencia preparada por SPI_prepare

Synopsis

int SPI_execute_plan_extended(SPIPlanPtr plan,
                              const SPIExecuteOptions * options)

Descripción

SPI_execute_plan_extended ejecuta una sentencia preparada por SPI_prepare o una de sus funciones hermanas. Esta función es equivalente a SPI_execute_plan, excepto que la información sobre los valores de los parámetros que se pasarán a la consulta se presenta de manera diferente, y se pueden pasar opciones adicionales de control de ejecución.

Los valores de los parámetros de la consulta se representan mediante una estructura ParamListInfo, que es conveniente para pasar valores que ya están disponibles en ese formato. También se pueden utilizar conjuntos de parámetros dinámicos, a través de funciones de gancho especificadas en ParamListInfo.

Además, en lugar de acumular siempre las tuplas de resultado en una estructura SPI_tuptable, las tuplas se pueden pasar a un objeto DestReceiver proporcionado por el llamador a medida que las genera el ejecutor. Esto 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

SPIPlanPtr plan: sentencia preparada (devuelta por SPI_prepare)
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_plan
ResourceOwner owner: El propietario del recurso que mantendrá un recuento de referencias en el plan mientras se ejecuta. Si es NULL, se utiliza CurrentResourceOwner. Se ignora para planes no guardados, ya que SPI no adquiere recuentos de referencias en ellos.

Valor de retorno

El valor de retorno es el mismo que para SPI_execute_plan.

Cuando options->dest es NULL, SPI_processed y SPI_tuptable se establecen como en SPI_execute_plan. 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.