SPI_execute_extended

» » » »

Précédent	Niveau supérieur	Suivant
SPI_exec	Sommaire	SPI_execute_with_args

SPI_execute_extended

SPI_execute_extended — Exécute une commande avec des paramètres hors ligne

Synopsis

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

Description

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 $n, et l'objet 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.

Arguments

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é.

Valeur de retour

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.