SPI_execute

Description

SPI_exec lance la commande SQL sp�cifi�e pour count lignes. Si read_only est true, la commande doit �tre en lecture seule et la surcharge de l'ex�cution est quelque peu r�duite.

Cette fonction ne devrait �tre appel�e qu'� partir d'une proc�dure connect�e.

Si count vaut z�ro, alors la commande est ex�cut�e pour toutes les lignes auxquelles elle s'applique. Si count est plus grand que 0, alors le nombre de lignes pour lesquelles la commande sera ex�cut�e est restreint (tr�s semblable � une clause LIMIT). Par exemple,

SPI_execute("INSERT INTO foo SELECT * FROM bar", 5);

autorisera au plus cinq lignes � �tre ins�r�es dans la table.

Vous pourriez passer plusieurs commandes dans une cha�ne. SPI_execute renvoie le r�sultat pour la derni�re commande ex�cut�e. La limite count s'applique � chaque commande s�par�ment mais n'est pas appliqu�e aux commandes cach�es par les r�gles.

Quand read_only vaut false, SPI_execute incr�mente le compteur de la commande et calcule une nouvelle image avant d'ex�cuter chaque commande dans la cha�ne. L'image n'est pas r�ellement modifi�e si le niveau d'isolation de la transaction en cours est SERIALIZABLE mais, en mode READ COMMITTED, la mise � jour de l'image permet � chaque commande de voir les r�sultats des transactions nouvellement valid�es � partir des autres sessions. Ceci est essentiel pour un comportement coh�rent quand les commandes modifient la base de donn�es.

Quand read_only vaut true, SPI_execute ne met � jour ni l'image ni le compteur de commandes, et il autorise seulement les commandes SELECT dans la cha�ne des commandes. Elles sont ex�cut�es en utilisant l'image pr�c�demment �tablie par la requ�te englobante. Ce mode d'ex�cution est un peu plus rapide que le mode lecture/�criture � cause de l'�limination de la surcharge par commande. Il autorise aussi directement la construction des fonctions stable  comme les ex�cutions successives utiliseront toutes la m�me image, il n'y aura aucune modification dans les r�sultats.

Il n'est g�n�ralement pas conseill� de mixer les commandes en lecture seule et les commandes en lecture/�criture � l'int�rieur d'une seule fonction utilisant SPI ; ceci pourrait causer un comportement portant confusion car les requ�tes en mode lecture seule devraient ne pas voir les r�sultats de toute mise � jour de la base de donn�es effectu�es par les requ�tes en lecture/�criture.

Le nombre r�el de lignes pour lesquelles la (derni�re) commande a �t� lanc�e est retourn� dans la variable globale SPI_processed (sauf si la valeur de retour de la fonction est SPI_OK_UTILITY). Si la valeur de retour de la fonction est SPI_OK_SELECT, alors vous pouvez utiliser le pointeur global SPITupleTable *SPI_tuptable pour acc�der aux lignes de r�sultat.

La structure SPITupleTable est d�finie comme suit :

typedef struct
{
    MemoryContext tuptabcxt;    /* contexte m�moire de la table de r�sultat */
    uint32      alloced;        /* nombre de valeurs allou�es */
    uint32      free;           /* nombre de valeurs libres */
    TupleDesc   tupdesc;        /* descripteur de rang�es */
    HeapTuple  *vals;           /* rang�es */
} SPITupleTable;

valeurs est un tableau de pointeurs vers des lignes (le nombre d'entr�es valables est donn� par SPI_processed). tupdesc est un descripteur de ligne que vous pouvez passer aux fonctions SPI qui traitent des lignes. tuptabcxt, alloced et free sont des champs internes non con�us pour �tre utilis�s par des routines SPI appelantes.

SPI_finish lib�re tous les SPITupleTables allou�es pendant la proc�dure courante. Vous pouvez lib�rer une table de r�sultats donn�e plus t�t, si vous en avez termin� avec elle, en appelant SPI_freetuptable.

Arguments

Valeur de retour

Si l'ex�cution de la commande a r�ussi, alors l'une des valeurs (positives) suivantes sera renvoy�e :

Sur une erreur, l'une des valeurs n�gatives suivante est renvoy�e :

Notes

Les fonctions SPI_execute, SPI_exec, SPI_execute_plan et SPI_execp changent � la fois SPI_processed et SPI_tuptable (juste le pointeur, pas le contenu de la structure). Sauvegardez ces deux variables globales dans des variables locales de proc�dures si vous voulez acc�der � la table des r�sultats de SPI_execute ou d'une fonction relative sur plusieurs appels.