SPI_execute_extended — Exécute une commande avec des paramètres hors ligne
int SPI_execute_extended(const char *command
, const SPIExecuteOptions *options
)
SPI_execute_extended
exécute une commande qui peut inclure
des références à des paramètres fournis en externe. Le texte de commande
se réfère à un paramètre sous la forme $
,
et l'objet n
options->params
(si fourni) donne des informations sur
les valeurs et le type de chacun des symboles.
De nombreuses options d'exécution peuvent aussi être spécifiées dans la structure
options
L'objet options->params
doit normalement
marquer chaque paramètre avec le drapeau PARAM_FLAG_CONST
,
dès qu'un plan unique est toujours utilisé pour cette requête.
Si options->dest
n'est pas NULL, alors les lignes de
résultats
sont passées à cet objet lors de leur génération par l'exécuteur, au lieu
d'être accumulées dans SPI_tuptable
. Employer un objet
DestReceiver
fourni par l'appelant est particulièrement
utile pour les requêtes qui peuvent générer de nombreuses lignes, dès lors que
les données sont traitées à la volée au lieu de s'accumuler en mémoire.
const char * command
Chaîne de caractères de la commande
const SPIExecuteOptions * options
Structure contenant les arguments optionnels
Les codes appelants doivent toujours mettre à zéro l'entièreté de la
structure options
, et ensuite remplir les champs
souhaités. Ceci permet d'assurer la compatibilité ascendante
du code, car tous les champs ajoutés à la structure dans le futur
seront définis comme étant rétro-compatibles s'ils sont mis à zéro.
Les champs de options
actuellement disponibles
sont :
ParamListInfo params
Structure de données contenant les types et valeurs des paramètres de requêtes ; NULL si aucun.
bool read_only
true
pour les exécutions en lecture seule
bool no_snapshots
à true
, autorise l'exécution non atomique des
instructions CALL et DO (mais ce champ est ignoré jusqu'à ce que le
drapeau SPI_OPT_NONATOMIC
soit passé à
SPI_connect_ext
)
bool must_return_tuples
si true
, lève une erreur si la requête n'est pas d'un
type qui renvoie des lignes (ceci n'interdit pas le cas où elle
pourrait renvoyer zéro lignes)
uint64 tcount
Nombre maximum de lignes à retourner, ou 0
pour aucune
limite
DestReceiver * dest
L'objet DestReceiver
qui recevra toutes les lignes
émises par la requête ; si NULL, les lignes de résultats sont
accumulés dans une structure SPI_tuptable
, comme avec
SPI_execute
ResourceOwner owner
Ce champ est présent pour la cohérence avec
SPI_execute_plan_extended
, mais est ignoré, puisque
le plan utilisé par SPI_execute_extended
n'est
jamais sauvegardé.
La valeur de retour est la même que pour SPI_execute
.
Quand options->dest
est NULL,
SPI_processed
et SPI_tuptable
sont affectés comme dans SPI_execute
.
Quand options->dest
n'est pas NULL,
SPI_processed
est mis à zéro et
SPI_tuptable
est mis à NULL. Si un comptage de lignes
est requis, l'objet DestReceiver
appelant doit s'en
occuper.