spi.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Dernière modification
     le       $Date$
     par      $Author$
     révision $Revision$ -->

<chapter id="spi">
 <title>Interface de programmation serveur</title>

 <indexterm zone="spi">
  <primary>SPI</primary>
 </indexterm>

 <para>
  L'<firstterm>interface de programmation serveur</firstterm>
  (<acronym>SPI</acronym>) donne aux auteurs de fonctions
  <acronym>C</acronym> la capacité de lancer des commandes
  <acronym>SQL</acronym> au sein de leurs fonctions.
  <acronym>SPI</acronym> est une série de
  fonctions d'interface simplifiant l'accès à l'analyseur, au planificateur
  et au lanceur. <acronym>SPI</acronym> fait aussi de la
  gestion de mémoire.
 </para>

 <note>
  <para>
   Les langages procéduraux disponibles donnent plusieurs moyens
   de lancer des commandes SQL à partir de procédures. La plupart est basée
   à partir de SPI. Cette documentation présente donc également un intérêt pour
   les utilisateurs de ces langages.
  </para>
 </note>

 <para>
  Pour assurer la compréhension, nous utiliserons le terme de <quote>fonction</quote>
  quand nous parlerons de fonctions d'interface <acronym>SPI</acronym> et
  <quote>procédure</quote> pour une fonction C définie par l'utilisateur et
  utilisant <acronym>SPI</acronym>.
 </para>

 <para>
  Notez que si une commande appelée via SPI échoue, alors le contrôle ne sera
  pas redonné à votre procédure. Au contraire, la transaction ou
  sous-transaction dans laquelle est exécutée votre procédure sera annulée.
  (Ceci pourrait être surprenant étant donné que les fonctions SPI ont pour
  la plupart des conventions documentées de renvoi d'erreur. Ces conventions
  s'appliquent seulement pour les erreurs détectées à l'intérieur des
  fonctions SPI.) Il est possible de récupérer le contrôle après une erreur
  en établissant votre propre sous-transaction englobant les appels SPI qui
  pourraient échouer. Ceci n'est actuellement pas documenté parce que les
  mécanismes requis sont toujours en flux.
 </para>

 <para>
  Les fonctions <acronym>SPI</acronym> renvoient un résultat positif en cas de
  succès (soit par une valeur de retour entière, soit dans la variable
  globale <varname>SPI_result</varname> comme décrit ci-dessous). En cas
  d'erreur, un résultat négatif ou <symbol>NULL</symbol> sera retourné.
 </para>

 <para>
  Les fichiers de code source qui utilisent SPI doivent inclure le fichier
  d'en-tête <filename>executor/spi.h</filename>.
 </para>


<sect1 id="spi-interface">
 <title>Fonctions d'interface</title>

 <refentry id="spi-spi-connect">
  <refmeta>
   <refentrytitle>SPI_connect</refentrytitle>
   <manvolnum>3</manvolnum>
  </refmeta>

  <refnamediv>
   <refname>SPI_connect</refname>
   <refpurpose>connecter une procédure au gestionnaire SPI</refpurpose>
 </refnamediv>


 <refsynopsisdiv>
<synopsis>int SPI_connect(void)</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>
  <indexterm><primary>SPI_connect</primary></indexterm>

  <para>
   <function>SPI_connect</function> ouvre une connexion au gestionnaire SPI lors
   de l'appel d'une procédure. Vous devez appeler cette
   fonction si vous voulez lancer des commandes au travers du SPI. Certaines
   fonctions SPI utilitaires peuvent être appelées à partir de procédures non connectées.
  </para>

  <para>
   Si votre procédure est déjà connectée,
   <function>SPI_connect</function> retournera le code d'erreur
   <returnvalue>SPI_ERROR_CONNECT</returnvalue>. Cela peut arriver si
   une procédure qui a appelé <function>SPI_connect</function>
   appelle directement une autre procédure qui appelle
   <function>SPI_connect</function>.  Bien que des appels récursifs au
   gestionnaire <acronym>SPI</acronym> soient permis lorsqu'une commande SQL
   appelée au travers du SPI invoque une autre fonction qui utilise
   <acronym>SPI</acronym>, les appels directement intégrés à
   <function>SPI_connect</function> et
   <function>SPI_finish</function> sont interdits
   (mais voir <function>SPI_push</function> et <function>SPI_pop</function>).
  </para>
 </refsect1>

 <refsect1>
  <title>Valeur de retour</title>

  <variablelist>
   <varlistentry>
    <term><symbol>SPI_OK_CONNECT</symbol></term>
    <listitem>
     <para>
      en cas de succès
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><symbol>SPI_ERROR_CONNECT</symbol></term>
    <listitem>
     <para>
      en cas d'échec
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-finish">
 <refmeta>
  <refentrytitle>SPI_finish</refentrytitle>
   <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_finish</refname>
  <refpurpose>déconnecter une procédure du gestionnaire SPI</refpurpose>
 </refnamediv>


 <refsynopsisdiv>
<synopsis>int SPI_finish(void)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>
  <indexterm><primary>SPI_finish</primary></indexterm>

  <para>
   <function>SPI_finish</function> ferme une connexion existante au
   gestionnaire SPI. Vous devez appeler cette fonction après avoir terminé les
   opérations SPI souhaitées pendant l'invocation courante de votre procédure.
   Vous n'avez pas à vous préoccuper de ceci, sauf si vous
   terminez la transaction via <literal>elog(ERROR)</literal>. Dans ce
   cas, SPI terminera automatiquement.
  </para>

  <para>
   Si <function>SPI_finish</function> est appelée sans avoir une connexion
   valable, elle retournera <symbol>SPI_ERROR_UNCONNECTED</symbol>.
   Il n'y a pas de problème fondamental avec cela&nbsp;; le
   gestionnaire SPI n'a simplement rien à faire.
  </para>
 </refsect1>

 <refsect1>
  <title>Valeur de retour</title>

  <variablelist>
   <varlistentry>
    <term><symbol>SPI_OK_FINISH</symbol></term>
    <listitem>
     <para>
      si déconnectée correctement
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><symbol>SPI_ERROR_UNCONNECTED</symbol></term>
    <listitem>
     <para>
      si appel à partir d'une procédure non connectée
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-push">
  <refmeta>
    <refentrytitle>SPI_push</refentrytitle>
   <manvolnum>3</manvolnum>
  </refmeta>
  
  <refnamediv>
    <refname>SPI_push</refname>
    <refpurpose>pousse la pile SPI pour autoriser une utilisation récursive de
     SPI</refpurpose>
  </refnamediv>
  
  <refsynopsisdiv>
    <synopsis>void SPI_push(void)
    </synopsis>
  </refsynopsisdiv>
  
  <refsect1>
    <title>Description</title>
    <indexterm><primary>SPI_push</primary></indexterm>
    
    <para>
      <function>SPI_push</function> devrait être appelé avant d'exécuter une
      autre procédure qui pourrait elle-même souhaiter utiliser SPI.
      Après <function>SPI_push</function>, SPI n'est plus dans un état
      <quote>connecté</quote> et les appels de fonction SPI seront rejetés sauf
      si un nouveau <function>SPI_connect</function> est exécuté. Ceci nous
      assure une séparation propre entre l'état SPI de votre procédure et
      celui d'une autre procédure que vous appelez. Après le retour de cette
      dernière, appelez <function>SPI_pop</function> pour restaurer
      l'accès à votre propre état SPI.
    </para>
  
    <para>
      Notez que <function>SPI_execute</function> et les fonctions
      relatives font automatiquement l'équivalent de
      <function>SPI_push</function> avant de repasser le contrôle au moteur
      d'exécution SQL, donc il n'est pas nécessaire de vous inquiéter de cela
      lors de l'utilisation de ces fonctions. Vous aurez besoin d'appeler
      <function>SPI_push</function> et <function>SPI_pop</function>
      seulement quand vous appelez directement un code arbitraire qui
      pourrait contenir des appels <function>SPI_connect</function>.
    </para>
</refsect1>

</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-pop">
  <refmeta>
    <refentrytitle>SPI_pop</refentrytitle>
   <manvolnum>3</manvolnum>
  </refmeta>
  
  <refnamediv>
    <refname>SPI_pop</refname>
    <refpurpose>récupère la pile SPI pour revenir de l'utilisation récursive
     de SPI</refpurpose>
  </refnamediv>
  
  <refsynopsisdiv>
    <synopsis>void SPI_pop(void)
    </synopsis>
  </refsynopsisdiv>
  
  <refsect1>
    <title>Description</title>
    <indexterm><primary>SPI_pop</primary></indexterm>
    
    <para>
      <function>SPI_pop</function> enlève l'environnement précédent de la pile
      d'appel SPI. Voir <function>SPI_push</function>.
    </para>
  </refsect1>
  
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-execute">
 <refmeta>
  <refentrytitle>SPI_execute</refentrytitle>
   <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_execute</refname>
  <refpurpose>exécute une commande</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>int SPI_execute(const char * <parameter>command</parameter>, bool <parameter>read_only</parameter>, long <parameter>count</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>
  <indexterm><primary>SPI_execute</primary></indexterm>

  <para>
   <function>SPI_exec</function> lance la commande SQL spécifiée
   pour <parameter>count</parameter> lignes. Si <parameter>read_only</parameter>
   est <literal>true</literal>, la commande doit être en lecture seule et la surcharge
   de l'exécution est quelque peu réduite.
  </para>

  <para>
   Cette fonction ne devrait être appelée qu'à partir d'une procédure connectée.
  </para>

  <para>
   Si <parameter>count</parameter> vaut zéro, alors la commande est exécutée
   pour toutes les lignes auxquelles elle s'applique. Si
   <parameter>count</parameter> est supérieur à 0, alors pas plus de
   <parameter>count</parameter> lignes seront récupérées. L'exécution s'arrêtera
   quand le compte est atteint, un peu comme l'ajout d'une clause
   <literal>LIMIT</literal> à une requête. Par exemple&nbsp;:
<programlisting>SPI_execute("SELECT * FROM foo", true, 5);
</programlisting>
   récupérera 5 lignes tout au plus à partir de la table. Notez qu'une telle
   limite n'est efficace qu'à partir du moment où la requête renvoie des lignes.
   Par exemple :
<programlisting> SPI_execute("INSERT INTO foo SELECT * FROM bar", false, 5);
 </programlisting>
   insérera toutes les lignes de <structname>bar</structname>, en ignorant le
   paramètre <parameter>count</parameter>. Cependant, avec
<programlisting>SPI_execute("INSERT INTO foo SELECT * FROM bar RETURNING *", false, 5);
</programlisting>
   au plus cinq lignes seront insérées car l'exécution s'arrêtera après la
   cinquième ligne renvoyée par <literal>RETURNING</literal>.
  </para>

  <para>
   Vous pourriez passer plusieurs commandes dans une chaîne.
   <function>SPI_execute</function> renvoie le résultat pour la dernière
   commande exécutée. La limite <parameter>count</parameter> s'applique à
   chaque commande séparément (même si seul le dernier résultat sera renvoyé).
   La limite n'est pas appliquée à toute commande cachée générée par les règles.
  </para>

  <para>
   Quand <parameter>read_only</parameter> vaut <literal>false</literal>,
   <function>SPI_execute</function> incrémente le compteur de la commande
   et calcule une nouvelle <firstterm>image</firstterm> 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
   <literal>SERIALIZABLE</literal> ou <literal>REPEATABLE READ</literal> mais, en mode
   <literal>READ COMMITTED</literal>, 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.
  </para>

  <para>
   Quand <parameter>read_only</parameter> vaut <literal>true</literal>,
   <function>SPI_execute</function> ne met à jour ni l'image ni le compteur de
   commandes, et il autorise seulement les commandes <command>SELECT</command> 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 <firstterm>stable</firstterm>&nbsp; comme les exécutions successives
   utiliseront toutes la même image, il n'y aura aucune modification dans les
   résultats.
  </para>

  <para>
   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&nbsp;; 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.
  </para>

  <para>
   Le nombre réel de lignes pour lesquelles la (dernière) commande a été
   lancée
   est retourné dans la variable globale <varname>SPI_processed</varname>.
   Si la valeur de retour de la fonction est <symbol>SPI_OK_SELECT</symbol>,
   <symbol>SPI_OK_INSERT_RETURNING</symbol>, <symbol>SPI_OK_DELETE_RETURNING</symbol>
   ou <symbol>SPI_OK_UPDATE_RETURNING</symbol>, alors vous pouvez utiliser le
   pointeur global <literal>SPITupleTable *SPI_tuptable</literal> pour
   accéder aux lignes de résultat. Quelques commandes (comme
   <command>EXPLAIN</command>) renvoient aussi des ensembles de lignes et
   <literal>SPI_tuptable</literal> contiendra aussi le résultat dans ces cas.
   Some utility commands
   (<command>COPY</command>, <command>CREATE TABLE AS</command>) don't return a row set, so
   <literal>SPI_tuptable</literal> is NULL, but they still return the number of
   rows processed in <varname>SPI_processed</varname>.
  </para>

  <para>
   La structure <structname>SPITupleTable</structname> est définie
   comme suit&nbsp;:
<programlisting>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;
</programlisting>
   <structfield>vals</structfield> est un tableau de pointeurs vers des lignes (le
   nombre d'entrées valables est donné par <varname>SPI_processed</varname>).
   <structfield>tupdesc</structfield> est un descripteur de ligne que vous pouvez passer
   aux fonctions SPI qui traitent des lignes.  <structfield>tuptabcxt</structfield>,
   <structfield>alloced</structfield> et <structfield>free</structfield> sont des champs
   internes non conçus pour être utilisés par des routines SPI appelantes.
  </para>

  <para>
   <function>SPI_finish</function> libère tous les
   <structname>SPITupleTable</structname>s 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 <function>SPI_freetuptable</function>.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>const char * <parameter>command</parameter></literal></term>
    <listitem>
     <para>
      chaîne contenant la commande à exécuter
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>bool <parameter>read_only</parameter></literal></term>
    <listitem>
     <para>
      <literal>true</literal> en cas d'exécution en lecture seule
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>long <parameter>count</parameter></literal></term>
    <listitem>
     <para>
      nombre maximum de lignes à traiter ou <literal>0</literal> pour aucune
      limite
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Valeur de retour</title>

  <para>
   Si l'exécution de la commande a réussi, alors l'une des
   valeurs (positives) suivantes sera renvoyée&nbsp;:

   <variablelist>
    <varlistentry>
     <term><symbol>SPI_OK_SELECT</symbol></term>
     <listitem>
      <para>
       si un <command>SELECT</command> (mais pas <command>SELECT
       INTO</command>) a été lancé
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><symbol>SPI_OK_SELINTO</symbol></term>
     <listitem>
      <para>
       si un <command>SELECT INTO</command> a été lancé
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><symbol>SPI_OK_INSERT</symbol></term>
     <listitem>
      <para>
       si un <command>INSERT</command> a été lancé
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><symbol>SPI_OK_DELETE</symbol></term>
     <listitem>
      <para>
       si un <command>DELETE</command> a été lancé
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><symbol>SPI_OK_UPDATE</symbol></term>
     <listitem>
      <para>
       si un <command>UPDATE</command> a été lancé
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><symbol>SPI_OK_INSERT_RETURNING</symbol></term>
     <listitem>
      <para>
       si un <command>INSERT RETURNING</command> a été lancé
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><symbol>SPI_OK_DELETE_RETURNING</symbol></term>
     <listitem>
      <para>
       si un <command>DELETE RETURNING</command> a été lancé
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><symbol>SPI_OK_UPDATE_RETURNING</symbol></term>
     <listitem>
      <para>
       si un <command>UPDATE RETURNING</command> a été lancé
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><symbol>SPI_OK_UTILITY</symbol></term>
     <listitem>
      <para>
       si une commande utilitaire (c'est-à-dire <command>CREATE TABLE</command>)
       a été lancée
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><symbol>SPI_OK_REWRITTEN</symbol></term>
     <listitem>
      <para>
       si la commande a été réécrite dans un autre style de commande
       (c'est-à-dire que <command>UPDATE</command> devient un
       <command>INSERT</command>) par une <link linkend="rules">règle</link>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>

  <para>
   Sur une erreur, l'une des valeurs négatives suivante est renvoyée&nbsp;:

   <variablelist>
    <varlistentry>
     <term><symbol>SPI_ERROR_ARGUMENT</symbol></term>
     <listitem>
      <para>
       si <parameter>command</parameter> est <symbol>NULL</symbol> ou
       <parameter>count</parameter> est inférieur à 0
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><symbol>SPI_ERROR_COPY</symbol></term>
     <listitem>
      <para>
       si <command>COPY TO stdout</command> ou <command>COPY FROM stdin</command>
       ont été tentés
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><symbol>SPI_ERROR_TRANSACTION</symbol></term>
     <listitem>
      <para>
       Si une commande de manipulation de transaction a été
       tentée
       (<command>BEGIN</command>,
       <command>COMMIT</command>,
       <command>ROLLBACK</command>,
       <command>SAVEPOINT</command>,
       <command>PREPARE TRANSACTION</command>,
       <command>COMMIT PREPARED</command>,
       <command>ROLLBACK PREPARED</command>
       ou toute variante de ces dernières)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><symbol>SPI_ERROR_OPUNKNOWN</symbol></term>
     <listitem>
      <para>
       si le type de commande est inconnu (ce qui ne devrait pas arriver)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><symbol>SPI_ERROR_UNCONNECTED</symbol></term>
     <listitem>
      <para>
       si appel à partir d'une procédure non connectée
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1>
  <title>Notes</title>

  <para>
   Toutes les fonctions d'exécution de requêtes SPI changent à la fois
   <varname>SPI_processed</varname> et
   <varname>SPI_tuptable</varname> (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
   <function>SPI_execute</function> ou d'une fonction d'exécution de requêtes
   sur plusieurs appels.
  </para>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-exec">
  <refmeta>
    <refentrytitle>SPI_exec</refentrytitle>
   <manvolnum>3</manvolnum>
  </refmeta>
  
  <refnamediv>
    <refname>SPI_exec</refname>
    <refpurpose>exécute une commande en lecture/écriture</refpurpose>
  </refnamediv>
  
  <refsynopsisdiv>
    <synopsis>int SPI_exec(const char * <parameter>command</parameter>, long <parameter>count</parameter>)</synopsis>
  </refsynopsisdiv>
  
  <refsect1>
    <title>Description</title>
    <indexterm><primary>SPI_exec</primary></indexterm>
    
    <para>
      <function>SPI_exec</function> est identique à
      <function>SPI_execute</function>, mais le paramètre
      <parameter>read_only</parameter> de ce dernier est bloqué sur la valeur
      <literal>false</literal>.
  </para>
</refsect1>

<refsect1>
  <title>Arguments</title>
  
  <variablelist>
    <varlistentry>
      <term><literal>const char * <parameter>command</parameter></literal></term>
      <listitem>
        <para>
          chaîne contenant la commande à exécuter
        </para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><literal>long <parameter>count</parameter></literal></term>
      <listitem>
        <para>
          nombre maximum de lignes à renvoyer ou <literal>0</literal> pour
          aucune limite
        </para>
      </listitem>
    </varlistentry>
  </variablelist>
</refsect1>

<refsect1>
  <title>Valeur de retour</title>
  
  <para>
    Voir <function>SPI_execute</function>.
  </para>
</refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-execute-with-args">
 <refmeta>
  <refentrytitle>SPI_execute_with_args</refentrytitle>
   <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_execute_with_args</refname>
  <refpurpose>exécute une commande avec des paramètres hors ligne</refpurpose>
 </refnamediv>

 <indexterm><primary>SPI_execute_with_args</primary></indexterm>

 <refsynopsisdiv>
<synopsis>
int SPI_execute_with_args(const char *<parameter>command</parameter>,
                          int <parameter>nargs</parameter>, Oid *<parameter>argtypes</parameter>,
                          Datum *<parameter>values</parameter>, const char *<parameter>nulls</parameter>,
                          bool <parameter>read_only</parameter>, long <parameter>count</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_execute_with_args</function> exécute une commande qui pourrait
   inclure des références à des paramètres fournis en externe. Le texte de
   commande fait référence à un paramètre avec
   <literal>$<replaceable>n</replaceable></literal> et l'appel spécifie les
   types et valeurs des données pour chaque symbole de ce type.
   <parameter>read_only</parameter> et <parameter>count</parameter> ont la
   même interprétation que dans <function>SPI_execute</function>.
  </para>

  <para>
   Le principal avantage de cette routine comparé à
   <function>SPI_execute</function> est que les valeurs de données peuvent être
   insérées dans la commande sans mise entre guillemets et échappements, et donc
   avec beaucoup moins de risques d'attaques du type injection SQL.
  </para>

  <para>
   Des résultats similaires peuvent être réalisés avec <function>SPI_prepare</function>
   suivi par <function>SPI_execute_plan</function>&nbsp;; néanmoins, lors de
   l'utilisation de cette fonction, le plan de requête est toujours personnalisé avec les
   valeurs de paramètres spécifiques fournies. Pour une exécution simple, cette
   fonction doit être préférée. Si la même commande doit être exécutée avec
   plusieurs paramètres différents, chaque méthode peut être la plus rapide,
   le coût de la planification pouvant contre-balancer les bénéfices des plans
   personnalisés.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>const char * <parameter>command</parameter></literal></term>
    <listitem>
     <para>
      chaîne de commande
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>int <parameter>nargs</parameter></literal></term>
    <listitem>
     <para>
      nombre de paramètres en entrée (<literal>$1</literal>, <literal>$2</literal>, etc.)
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>Oid * <parameter>argtypes</parameter></literal></term>
    <listitem>
     <para>
      un tableau of length <parameter>nargs</parameter>, contenant les <acronym>OID</acronym> des types de données
      des paramètres
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>Datum * <parameter>values</parameter></literal></term>
    <listitem>
     <para>
      un tableau of length <parameter>nargs</parameter>, containing des valeurs réelles des paramètres
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>const char * <parameter>nulls</parameter></literal></term>
    <listitem>
     <para>
      un tableau décrivant les paramètres NULL
     </para>

     <para>
      Si <parameter>nulls</parameter> vaut <symbol>NULL</symbol>, alors
      <function>SPI_execute_with_args</function> suppose qu'aucun paramètre
      n'est NULL. Otherwise, each entry of the <parameter>nulls</parameter>
      array should be <literal>'&nbsp;'</literal> if the corresponding parameter
      value is non-null, or <literal>'n'</literal> if the corresponding parameter
      value is null.  (In the latter case, the actual value in the
      corresponding <parameter>values</parameter> entry doesn't matter.)  Note
      that <parameter>nulls</parameter> is not a text string, just an array:
      it does not need a <literal>'\0'</literal> terminator.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>bool <parameter>read_only</parameter></literal></term>
    <listitem>
     <para>
      <literal>true</literal> pour les exécutions en lecture seule
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>long <parameter>count</parameter></literal></term>
    <listitem>
     <para>
      nombre maximum de lignes à renvoyer ou <literal>0</literal> pour aucune
      limite
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Valeur de retour</title>

  <para>
   La valeur de retour est identique à celle de <function>SPI_execute</function>.
  </para>

  <para>
   <varname>SPI_processed</varname> et
   <varname>SPI_tuptable</varname> sont configurés comme dans
   <function>SPI_execute</function> en cas de succès.
  </para>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-prepare">
 <refmeta>
  <refentrytitle>SPI_prepare</refentrytitle>
   <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_prepare</refname>
  <refpurpose>prépare une instruction sans l'exécuter tout de
suite</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>SPIPlanStr SPI_prepare(const char * <parameter>command</parameter>, int <parameter>nargs</parameter>, Oid * <parameter>argtypes</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>
  <indexterm><primary>SPI_prepare</primary></indexterm>

  <para>
   <function>SPI_prepare</function> crée et retourne une requête préparée
   pour la commande spécifiée mais ne lance pas la commande.
   La requête préparée peut être appelée plusieurs fois en utilisant
   <function>SPI_execute_plan</function>.
  </para>

  <para>
   Lorsque la même commande ou une commande semblable doit être lancée à
   plusieurs reprises, il est généralement avantageux de réaliser une
   analyse du plan d'exécution une fois et de ré-utiliser le plan
   d'exécution pour la commande.
   <function>SPI_prepare</function> convertit une chaîne de commande en une
   requête préparée qui encapsule le résultat de l'analyse du plan. La
   requête préparée fournit aussi une place pour mettre en cache un plan
   d'exécution s'il s'avère que la génération d'un plan personnalisé pour
   chaque exécution n'est pas utile.
  </para>

  <para>
   Une commande préparée peut être généralisée en utilisant les paramètres
   (<literal>$1</literal>, <literal>$2</literal>, etc.) en lieu et place de ce qui serait des
   constantes dans une commande normale. Les valeurs actuelles des paramètres
   sont alors spécifiées lorsque <function>SPI_executeplan</function> est appelée.
   Ceci permet à la commande préparée d'être utilisée sur une plage plus grande
   de situations que cela ne serait possible sans paramètres.
  </para>

  <para>
   La requête renvoyée par <function>SPI_prepare</function> ne peut être utilisé
   que dans l'invocation courante de la procédure puisque
   <function>SPI_finish</function> libère la mémoire allouée pour la requête.
   Mais l'instruction peut être sauvegardée plus longtemps par l'utilisation des
   fonctions <function>SPI_keepplan</function> ou <function>SPI_saveplan</function>.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>const char * <parameter>command</parameter></literal></term>
    <listitem>
     <para>
      chaîne contenant la commande à planifier
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>int <parameter>nargs</parameter></literal></term>
    <listitem>
     <para>
      nombre de paramètres d'entrée (<literal>$1</literal>, <literal>$2</literal>, etc.)
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>Oid * <parameter>argtypes</parameter></literal></term>
    <listitem>
     <para>
      pointeur vers un tableau contenant les <acronym>OID</acronym>
      des types de données des paramètres
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Valeurs de retour</title>

  <para>
   <function>SPI_prepare</function> retourne un pointeur non nul vers un
   plan d'exécution. En cas d'erreur, <symbol>NULL</symbol> sera retourné
   et <varname>SPI_result</varname> sera positionnée à un des mêmes codes
   d'erreur utilisés par <function>SPI_execute</function> sauf qu'il
   est positionné à <symbol>SPI_ERROR_ARGUMENT</symbol> si
   <parameter>command</parameter> est <symbol>NULL</symbol> ou si
   <parameter>nargs</parameter> est inférieur à 0 ou si <parameter>nargs</parameter> est
   supérieur à 0 et <parameter>typesargs</parameter> est <symbol>NULL</symbol>.
  </para>
 </refsect1>

 <refsect1>
  <title>Notes</title>

  <para>
   Si aucun paramètre n'est défini, un plan générique sera créé lors de la
   première utilisation de <function>SPI_execute_plan</function>, et utilisé
   aussi pour toutes les exécutions suivantes. Si des paramètres sont fournis,
   les premières utilisations de <function>SPI_execute_plan</function> génèreront
   des plans personnalisés qui sont spécifiques aux valeurs fournies pour les
   paramètres. Après suffisamment d'utilisation de la même requête préparée,
   <function>SPI_execute_plan</function> construira un plan générique et, si
   ce n'est pas beaucoup plus coûteux que les plans personnalisés, cette fonction
   commencera à utiliser le plan générique au lieu de re-planifier à chaque fois.
   Si le comportement par défaut n'est pas tenable, vous pouvez le modifier en
   passant le drapeau <literal>CURSOR_OPT_GENERIC_PLAN</literal> ou
   <literal>CURSOR_OPT_CUSTOM_PLAN</literal> à
   <function>SPI_prepare_cursor</function> pour forcer l'utilisation,
   respectivement, de plans génériques ou personnalisés.
  </para>

  <para>
   Although the main point of a prepared statement is to avoid repeated parse
   analysis and planning of the statement, <productname>PostgreSQL</productname> will
   force re-analysis and re-planning of the statement before using it
   whenever database objects used in the statement have undergone
   definitional (DDL) changes since the previous use of the prepared
   statement.  Also, if the value of <xref linkend="guc-search-path"/> changes
   from one use to the next, the statement will be re-parsed using the new
   <varname>search_path</varname>.  (This latter behavior is new as of
   <productname>PostgreSQL</productname> 9.3.)  See <xref
   linkend="sql-prepare"/> for more information about the behavior of prepared
   statements.
  </para>

  <para>
   Cette fonction doit seulement être appelée à partir d'une procédure connectée.
  </para>

  <para>
   <type>SPIPlanPtr</type> est déclaré comme un pointeur vers un type de
   structure opaque dans <filename>spi.h</filename>. Il est déconseillé d'essayer
   d'accéder à son contenu directement car cela rend votre code plus fragile aux
   futures versions de <productname>PostgreSQL</productname>.
  </para>

  <para>
   Le nom <type>SPIPlanPtr</type> est historique principalement car la structure
   des données ne contient plus nécessairement un plan d'exécution.
  </para>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-prepare-cursor">
 <refmeta>
  <refentrytitle>SPI_prepare_cursor</refentrytitle>
   <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_prepare_cursor</refname>
  <refpurpose>prépare une requête, sans l'exécuter pour l'instant</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  <indexterm><primary>SPI_prepare_cursor</primary></indexterm>
<synopsis>
SPIPlanPtr SPI_prepare_cursor(const char * <parameter>command</parameter>, int <parameter>nargs</parameter>, Oid * <parameter>argtypes</parameter>, int <parameter>cursorOptions</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_prepare_cursor</function> est identique à
   <function>SPI_prepare</function>, sauf qu'il permet aussi la spécification
   du paramètre des <quote>options du curseur</quote> du planificateur. Il
   s'agit d'un champ de bits dont les valeurs sont indiquées dans
   <filename>nodes/parsenodes.h</filename> pour le champ
   <structfield>options</structfield> de <structname>DeclareCursorStmt</structname>.
   <function>SPI_prepare</function> utilise zéro pour les options du curseur.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>const char * <parameter>command</parameter></literal></term>
    <listitem>
     <para>
      chaîne commande
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>int <parameter>nargs</parameter></literal></term>
    <listitem>
     <para>
      nombre de paramètres en entrée (<literal>$1</literal>, <literal>$2</literal>, etc.)
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>Oid * <parameter>argtypes</parameter></literal></term>
    <listitem>
     <para>
      pointeur vers un tableau contenant l'<acronym>OID</acronym> des types
      de données des paramètres
     </para>
    </listitem>
   </varlistentry>
 
   <varlistentry>
    <term><literal>int <parameter>cursorOptions</parameter></literal></term>
    <listitem>
     <para>
      champ de bits précisant les options du curseur&nbsp;; zéro est le
      comportement par défaut
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Valeur de retour</title>

  <para>
   <function>SPI_prepare_cursor</function> a les mêmes conventions pour la
   valeur de retour que <function>SPI_prepare</function>.
  </para>
 </refsect1>

 <refsect1>
  <title>Notes</title>

  <para>
   Les bits utiles pour <parameter>cursorOptions</parameter> incluent
   <symbol>CURSOR_OPT_NO_SCROLL</symbol>,
   <symbol>CURSOR_OPT_FAST_PLAN</symbol>,
   <symbol>CURSOR_OPT_GENERIC_PLAN</symbol> et
   <symbol>CURSOR_OPT_CUSTOM_PLAN</symbol>. Notez en particulier que
   <symbol>CURSOR_OPT_HOLD</symbol> est ignoré.
  </para>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-prepare-params">
 <refmeta>
  <refentrytitle>SPI_prepare_params</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_prepare_params</refname>
  <refpurpose>prépare une requête, mais sans l'exécuter</refpurpose>
 </refnamediv>

 <indexterm><primary>SPI_prepare_params</primary></indexterm>

 <refsynopsisdiv>
<synopsis>
SPIPlanPtr SPI_prepare_params(const char * <parameter>command</parameter>,
                              ParserSetupHook <parameter>parserSetup</parameter>,
                              void * <parameter>parserSetupArg</parameter>,
                              int <parameter>cursorOptions</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_prepare_params</function> crée et renvoie une requête
   préparée
   pour la commande indiquée mais n'exécute pas la commande. Cette fonction
   est équivalente à <function>SPI_prepare_cursor</function> avec en plus le
   fait que l'appelant peut indiquer des fonctions pour contrôler l'analyse
   de références de paramètres externes.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>const char * <parameter>command</parameter></literal></term>
    <listitem>
     <para>
      chaîne correspondant à la commande
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>ParserSetupHook <parameter>parserSetup</parameter></literal></term>
    <listitem>
     <para>
      fonction de configuration de l'analyseur
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>void * <parameter>parserSetupArg</parameter></literal></term>
    <listitem>
     <para>
      argument passé à <parameter>parserSetup</parameter>
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>int <parameter>cursorOptions</parameter></literal></term>
    <listitem>
     <para>
      masque de bits des options du curseur, sous la forme d'un entier&nbsp;;
      zéro indique le comportement par défaut
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Code de retour</title>

  <para>
   <function>SPI_prepare_params</function> a les mêmes conventions de retour
   que <function>SPI_prepare</function>.
  </para>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-getargcount">
  <refmeta>
    <refentrytitle>SPI_getargcount</refentrytitle>
  <manvolnum>3</manvolnum>
  </refmeta>
  
  <refnamediv>
    <refname>SPI_getargcount</refname>
    <refpurpose>renvoie le nombre d'arguments nécessaire à une requête
      par <function>SPI_prepare</function></refpurpose>
  </refnamediv>
  
  <refsynopsisdiv>
    <synopsis>int SPI_getargcount(SPIPlanPtr <parameter>plan</parameter>)</synopsis>
  </refsynopsisdiv>
  
  <refsect1>
    <title>Description</title>
    <indexterm><primary>SPI_getargcount</primary></indexterm>
    
    <para>
      <function>SPI_getargcount</function> renvoie le nombre d'arguments
      nécessaires pour exécuter une requête préparée par
      <function>SPI_prepare</function>.
    </para>
  </refsect1>
  
  <refsect1>
    <title>Arguments</title>
    
    <variablelist>
      <varlistentry>
        <term><literal>SPIPlanPtr <parameter>plan</parameter></literal></term>
        <listitem>
          <para>
            requête préparée (renvoyée par <function>SPI_prepare</function>)
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  
  <refsect1>
    <title>Code de retour</title>
    <para>
      Le nombre d'arguments attendus par le <parameter>plan</parameter>.
      Si <parameter>plan</parameter> est <symbol>NULL</symbol> ou invalide,
    <varname>SPI_result</varname> est initialisé à <symbol>SPI_ERROR_ARGUMENT</symbol>
    et -1 est renvoyé.
    </para>
  </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-getargtypeid">
  <refmeta>
    <refentrytitle>SPI_getargtypeid</refentrytitle>
  <manvolnum>3</manvolnum>
  </refmeta>
  
  <refnamediv>
    <refname>SPI_getargtypeid</refname>
    <refpurpose>renvoie l'OID du type de données pour un argument de la
      requête préparée par <function>SPI_prepare</function></refpurpose>
  </refnamediv>
  
  <refsynopsisdiv>
    <synopsis>Oid SPI_getargtypeid(SPIPlanPtr <parameter>plan</parameter>, int <parameter>argIndex</parameter>)</synopsis>
  </refsynopsisdiv>
  
  <refsect1>
    <title>Description</title>
    <indexterm><primary>SPI_getargtypeid</primary></indexterm>
    
    <para>
      <function>SPI_getargtypeid</function> renvoie l'OID représentant
      le type pour le <parameter>argIndex</parameter>-ième
      argument d'une requête préparée par <function>SPI_prepare</function>. Le
      premier argument se trouve à l'index zéro.
    </para>
  </refsect1>
  
  <refsect1>
    <title>Arguments</title>
    
    <variablelist>
      <varlistentry>
        <term><literal>SPIPlanPtr <parameter>plan</parameter></literal></term>
        <listitem>
          <para>
            requête préparée (renvoyée par <function>SPI_prepare</function>)
          </para>
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term><literal>int <parameter>argIndex</parameter></literal></term>
        <listitem>
          <para>
            index de l'argument (à partir de zéro)
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  
  <refsect1>
    <title>Code de retour</title>
    <para>
      L'OID du type de l'argument à l'index donné.
      Si le <parameter>plan</parameter> est <symbol>NULL</symbol> ou invalide,
      ou <parameter>argIndex</parameter> inférieur à 0 ou pas moins que le
      nombre d'arguments déclaré pour le <parameter>plan</parameter>,
      <varname>SPI_result</varname> est initialisé à
      <symbol>SPI_ERROR_ARGUMENT</symbol> et <symbol>InvalidOid</symbol> est
      renvoyé.
    </para>
  </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-is-cursor-plan">
  <refmeta>
    <refentrytitle>SPI_is_cursor_plan</refentrytitle>
  <manvolnum>3</manvolnum>
  </refmeta>
  
  <refnamediv>
    <refname>SPI_is_cursor_plan</refname>
    <refpurpose>renvoie <symbol>true</symbol> si la requête préparée par
      <function>SPI_prepare</function> peut être utilisé avec
      <function>SPI_cursor_open</function></refpurpose>
  </refnamediv>
  
  <refsynopsisdiv>
    <synopsis>bool SPI_is_cursor_plan(SPIPlanPtr <parameter>plan</parameter>)</synopsis>
  </refsynopsisdiv>
  
  <refsect1>
    <title>Description</title>
    <indexterm><primary>SPI_is_cursor_plan</primary></indexterm>
    
    <para>
      <function>SPI_is_cursor_plan</function> renvoie <symbol>true</symbol>
      si une requête préparée par <function>SPI_prepare</function> peut être
      passé comme un argument à <function>SPI_cursor_open</function> ou
      <symbol>false</symbol> si ce n'est pas le cas. Les critères sont que le
      <parameter>plan</parameter> représente une seule commande et que cette
      commande renvoit des lignes à l'appelant&nbsp;; par l'exemple,
      <command>SELECT</command> est autorisé sauf s'il contient une clause
      <literal>INTO</literal> et <command>UPDATE</command> est autorisé seulement
      s'il contient un <literal>RETURNING</literal>
    </para>
  </refsect1>
  
  <refsect1>
    <title>Arguments</title>
    
    <variablelist>
      <varlistentry>
		  <term><literal>SPIPlanPtr <parameter>plan</parameter></literal></term>
        <listitem>
          <para>
            requête préparée (renvoyée par <function>SPI_prepare</function>)
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  
  <refsect1>
    <title>Valeur de retour</title>
    <para>
      <symbol>true</symbol> ou <symbol>false</symbol> pour indiquer si
      <parameter>plan</parameter> peut produire un curseur ou non, avec
      <varname>SPI_result</varname> initialisé à zéro. S'il nest pas
      possible de déterminer la réponse (par exemple, si le
      <parameter>plan</parameter> vaut <symbol>NULL</symbol> ou est invalide,
      ou s'il est appelé en étant déconnecté de SPI), alors
      <varname>SPI_result</varname> est configuré avec un code d'erreur
      convenable et <symbol>false</symbol> est renvoyé.
    </para>
  </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-execute-plan">
  <refmeta>
    <refentrytitle>SPI_execute_plan</refentrytitle>
  <manvolnum>3</manvolnum>
  </refmeta>
  
  <refnamediv>
    <refname>SPI_execute_plan</refname>
    <refpurpose>exécute une requête préparée par 
    <function>SPI_prepare</function></refpurpose>
  </refnamediv>
  
  <refsynopsisdiv>
    <synopsis>int SPI_execute_plan(SPIPlanPtr <parameter>plan</parameter>, Datum * <parameter>values</parameter>, const char * <parameter>nulls</parameter>, bool <parameter>read_only</parameter>, long <parameter>count</parameter>)</synopsis>
  </refsynopsisdiv>
  
  <refsect1>
    <title>Description</title>
    <indexterm><primary>SPI_execute_plan</primary></indexterm>
    
    <para>
      <function>SPI_execute_plan</function> exécute une requête préparée par
      <function>SPI_prepare</function> ou une fonction du même type.
      <parameter>read_only</parameter> et
      <parameter>count</parameter> ont la même interprétation que dans
      <function>SPI_execute</function>.
    </para>
  </refsect1>
  
 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>SPIPlanPtr <parameter>plan</parameter></literal></term>
    <listitem>
     <para>
      requête préparée (retournée par <function>SPI_prepare</function>)
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>Datum *<parameter>values</parameter></literal></term>
    <listitem>
     <para>
      Un tableau des vraies valeurs des paramètres. Doit avoir la même longueur
      que le nombre d'arguments de la requête.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>const char * <parameter>nulls</parameter></literal></term>
    <listitem>
     <para>
      Un tableau décrivant les paramètres nuls. Doit avoir la même longueur que
      le nombre d'arguments de la requête.
     </para>

     <para>
      Si <parameter>nulls</parameter> est <symbol>NULL</symbol>, alors
      <function>SPI_executeplan</function> part du principe qu'aucun paramètre
      n'est nul. Otherwise, each entry of the <parameter>nulls</parameter>
      array should be <literal>'&nbsp;'</literal> if the corresponding parameter
      value is non-null, or <literal>'n'</literal> if the corresponding parameter
      value is null.  (In the latter case, the actual value in the
      corresponding <parameter>values</parameter> entry doesn't matter.)  Note
      that <parameter>nulls</parameter> is not a text string, just an array:
      it does not need a <literal>'\0'</literal> terminator.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>bool <parameter>read_only</parameter></literal></term>
    <listitem>
     <para>
      <literal>true</literal> pour une exécution en lecture seule
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>long <parameter>count</parameter></literal></term>
    <listitem>
     <para>
      nombre maximum de lignes à renvoyer ou <literal>0</literal> pour aucune
      ligne à renvoyer
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Valeur de retour</title>

  <para>
   La valeur de retour est la même que pour <function>SPI_execute</function>
   avec les résultats d'erreurs (négatif) possibles&nbsp;:

   <variablelist>
    <varlistentry>
     <term><symbol>SPI_ERROR_ARGUMENT</symbol></term>
     <listitem>
      <para>
       si <parameter>plan</parameter> est <symbol>NULL</symbol> ou invalide
       ou <parameter>count</parameter> est inférieur à 0
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><symbol>SPI_ERROR_PARAM</symbol></term>
     <listitem>
      <para>
       si <parameter>values</parameter> est <symbol>NULL</symbol> et
       <parameter>plan</parameter> est préparé avec des paramètres
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>

  <para>
   <varname>SPI_processed</varname> et
   <varname>SPI_tuptable</varname> sont positionnés comme dans
   <function>SPI_execute</function> en cas de réussite.
  </para>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-execute-plan-with-paramlist">
 <refmeta>
  <refentrytitle>SPI_execute_plan_with_paramlist</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_execute_plan_with_paramlist</refname>
  <refpurpose>exécute une requête préparée par <function>SPI_prepare</function></refpurpose>
 </refnamediv>

 <indexterm><primary>SPI_execute_plan_with_paramlist</primary></indexterm>

 <refsynopsisdiv>
<synopsis>
int SPI_execute_plan_with_paramlist(SPIPlanPtr <parameter>plan</parameter>,
                                    ParamListInfo <parameter>params</parameter>,
                                    bool <parameter>read_only</parameter>,
                                    long <parameter>count</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_execute_plan_with_paramlist</function> exécute une requête
   préparée par <function>SPI_prepare</function>. Cette fonction est
   l'équivalent de <function>SPI_execute_plan</function>, sauf que les
   informations sur les valeurs des paramètres à passer à la requête sont
   présentées différemment. La représentation <literal>ParamListInfo</literal>
   peut être utilse pour passer des valeurs qui sont déjà disponibles dans ce
   format. Elle supporte aussi l'utilisation d'ensemble de paramètres
   dynamiques indiqués via des fonctions dans <literal>ParamListInfo</literal>.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>SPIPlanPtr <parameter>plan</parameter></literal></term>
    <listitem>
     <para>
      requête préparée (renvoyée par <function>SPI_prepare</function>)
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>ParamListInfo <parameter>params</parameter></literal></term>
    <listitem>
     <para>
      structure de données contenant les types et valeurs de paramètres&nbsp;;
      NULL si aucune structure
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>bool <parameter>read_only</parameter></literal></term>
    <listitem>
     <para>
      <literal>true</literal> pour une exécution en lecture seule
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>long <parameter>count</parameter></literal></term>
    <listitem>
     <para>
      nombre maximum de lignes à renvoyer ou <literal>0</literal> pour aucune
      ligne à renvoyer
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Code de retour</title>

  <para>
   La valeur de retour est identique à celle de <function>SPI_execute_plan</function>.
  </para>

  <para>
   <varname>SPI_processed</varname> et <varname>SPI_tuptable</varname> sont
   initialisés de la même façon que pour <function>SPI_execute_plan</function>
   en cas de réussite.
  </para>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-execp">
  <refmeta>
    <refentrytitle>SPI_execp</refentrytitle>
  <manvolnum>3</manvolnum>
  </refmeta>
  
  <refnamediv>
    <refname>SPI_execp</refname>
    <refpurpose>exécute une requête en mode lecture/écriture</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <synopsis>int SPI_execp(SPIPlanPtr <parameter>plan</parameter>, Datum * <parameter>values</parameter>, const char * <parameter>nulls</parameter>, long <parameter>count</parameter>)</synopsis>
  </refsynopsisdiv>
  
  <refsect1>
    <title>Description</title>
    <indexterm><primary>SPI_execp</primary></indexterm>
    
    <para>
      <function>SPI_execp</function> est identique à
      <function>SPI_execute_plan</function> mais le paramètre
      <parameter>read_only</parameter> de ce dernier vaut toujours
      <literal>false</literal>.
  </para>
</refsect1>

<refsect1>
  <title>Arguments</title>
  
  <variablelist>
    <varlistentry>
      <term><literal>SPIPlanPtr <parameter>plan</parameter></literal></term>
      <listitem>
        <para>
          requête préparée (renvoyée par <function>SPI_prepare</function>)
        </para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><literal>Datum * <parameter>values</parameter></literal></term>
      <listitem>
        <para>
          Un tableau des vraies valeurs de paramètre. Doit avoir la même
          longueur que le nombre d'arguments de la requête.
        </para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><literal>const char * <parameter>nulls</parameter></literal></term>
      <listitem>
        <para>
          Un tableau décrivant les paramètres NULL. Doit avoir la même
          longueur que le nombre d'arguments de la requête.
        </para>
    
        <para>
          Si <parameter>nulls</parameter> est <symbol>NULL</symbol>, alors
          <function>SPI_execp</function> suppose qu'aucun paramètre n'est
          NULL. Otherwise, each entry of the <parameter>nulls</parameter>
      array should be <literal>'&nbsp;'</literal> if the corresponding parameter
      value is non-null, or <literal>'n'</literal> if the corresponding parameter
      value is null.  (In the latter case, the actual value in the
      corresponding <parameter>values</parameter> entry doesn't matter.)  Note
      that <parameter>nulls</parameter> is not a text string, just an array:
      it does not need a <literal>'\0'</literal> terminator.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><literal>long <parameter>count</parameter></literal></term>
      <listitem>
        <para>
          nombre maximum de lignes à renvoyer ou <literal>0</literal> pour aucune
          ligne à renvoyer
        </para>
      </listitem>
    </varlistentry>
    </variablelist>
</refsect1>

<refsect1>
  <title>Valeur de retour</title>
  
  <para>
    Voir <function>SPI_execute_plan</function>.
  </para>
  
  <para>
    <varname>SPI_processed</varname> et <varname>SPI_tuptable</varname> sont
    initialisées comme dans <function>SPI_execute</function> en cas de succès.
  </para>
</refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-cursor-open">
 <refmeta>
  <refentrytitle>SPI_cursor_open</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_cursor_open</refname>
  <refpurpose>met en place un curseur en utilisant une requête créée avec
<function>SPI_prepare</function></refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>Portal SPI_cursor_open(const char * <parameter>name</parameter>, SPIPlanPtr <parameter>plan</parameter>,
Datum * <parameter>values</parameter>, const char * <parameter>nulls</parameter>,
bool <parameter>read_only</parameter>)</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>
  <indexterm><primary>SPI_cursor_open</primary></indexterm>

  <para>
   <function>SPI_cursor_open</function> met en place un curseur (en interne,
   un portail) qui lancera une requête préparée par
   <function>SPI_prepare</function>. Les paramètres ont la même signification
   que les paramètres correspondant à <function>SPI_execute_plan</function>.
  </para>

  <para>
   Utiliser un curseur au lieu de lancer une requête directement a deux
   avantages. Premièrement, les lignes de résultats peuvent être récupérées un
   certain nombre à la fois, évitant la saturation de mémoire pour les requêtes
   qui retournent trop de lignes. Deuxièmement,
   un portail peut survivre à la procédure courante (elle peut, en fait, vivre
   jusqu'à la fin de la transaction courante). Renvoyer le nom du portail
   à l'appelant de la procédure donne un moyen de retourner une série de ligne
   en tant que résultat.
  </para>

  <para>
   Les données passées seront copiées dans le portail du curseur, donc il peut
   être libéré alors que le curseur existe toujours.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>const char * <parameter>name</parameter></literal></term>
    <listitem>
     <para>
      nom pour le portail ou <symbol>NULL</symbol> pour laisser le système
      choisir un nom
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>SPIPlanPtr <parameter>plan</parameter></literal></term>
    <listitem>
     <para>
      requête préparée (retournée par <function>SPI_prepare</function>)
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>Datum * <parameter>values</parameter></literal></term>
    <listitem>
     <para>
      Un tableau des valeurs de paramètres actuelles. Doit avoir la même
      longueur que le nombre d'arguments de la requête.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>const char *<parameter>nulls</parameter></literal></term>
    <listitem>
     <para>
      Un tableau décrivant quels paramètres sont NULL. Doit avoir la même
      longueur que le nombre d'arguments de la requête.
     </para>
     <para>
      Si <parameter>nulls</parameter> est <symbol>NULL</symbol>, alors
      <function>SPI_cursor_open</function> part du principe qu'aucun paramètre
      n'est nul. Otherwise, each entry of the <parameter>nulls</parameter>
      array should be <literal>'&nbsp;'</literal> if the corresponding parameter
      value is non-null, or <literal>'n'</literal> if the corresponding parameter
      value is null.  (In the latter case, the actual value in the
      corresponding <parameter>values</parameter> entry doesn't matter.)  Note
      that <parameter>nulls</parameter> is not a text string, just an array:
      it does not need a <literal>'\0'</literal> terminator.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>bool <parameter>read_only</parameter></literal></term>
    <listitem>
     <para>
      <literal>true</literal> pour les exécutions en lecture seule
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Valeur de retour</title>

  <para>
   Pointeur vers le portail contenant le curseur. Notez qu'il n'y a pas de
   convention pour le renvoi d'une erreur&nbsp;; toute erreur sera rapportée
   via <function>elog</function>.
  </para>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-cursor-open-with-args">
 <refmeta>
  <refentrytitle>SPI_cursor_open_with_args</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_cursor_open_with_args</refname>
  <refpurpose>ouvre un curseur en utilisant une requête et des paramètres</refpurpose>
 </refnamediv>

 <indexterm><primary>SPI_cursor_open_with_args</primary></indexterm>

 <refsynopsisdiv>
<synopsis>
Portal SPI_cursor_open_with_args(const char *<parameter>name</parameter>,
                                 const char *<parameter>command</parameter>,
                                 int <parameter>nargs</parameter>, Oid *<parameter>argtypes</parameter>,
                                 Datum *<parameter>values</parameter>, const char *<parameter>nulls</parameter>,
                                 bool <parameter>read_only</parameter>, int <parameter>cursorOptions</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_cursor_open_with_args</function> initialise un curseur
   (en interne, un portail) qui exécutera la requête spécifié. La plupart des
   paramètres ont la même signification que les paramètres correspondant de
   <function>SPI_prepare_cursor</function> et <function>SPI_cursor_open</function>.
  </para>

  <para>
   Pour une exécution seule, cette fonction sera préférée à
   <function>SPI_prepare_cursor</function> suivie de
   <function>SPI_cursor_open</function>. Si la même commande doit être exécutée
   avec plusieurs paramètres différents, il n'y a pas de différences sur les
   deux méthode, la replanification a un coût mais bénéficie de plans
   personnalisés.
  </para>

  <para>
   Les données passées seront copiées dans le portail du curseur, donc elles
   seront libérées alors que le curseur existe toujours.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>const char * <parameter>name</parameter></literal></term>
    <listitem>
     <para>
      nom du portail, ou <symbol>NULL</symbol> pour que le système sélectionne
      un nom de lui-même
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>const char * <parameter>command</parameter></literal></term>
    <listitem>
     <para>
      chaîne de commande
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>int <parameter>nargs</parameter></literal></term>
    <listitem>
     <para>
      nombre de paramètres en entrée (<literal>$1</literal>,
      <literal>$2</literal>, etc.)
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>Oid * <parameter>argtypes</parameter></literal></term>
    <listitem>
     <para>
      un tableau of length <parameter>nargs</parameter>, contenant les <acronym>OID</acronym> des types de données
      des paramètres
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>Datum * <parameter>values</parameter></literal></term>
    <listitem>
     <para>
      un tableau of length <parameter>nargs</parameter>, containing des valeurs actuelles des paramètres
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>const char * <parameter>nulls</parameter></literal></term>
    <listitem>
     <para>
      un tableau of length <parameter>nargs</parameter>, décrivant les paramètres NULL
     </para>

     <para>
      Si <parameter>nulls</parameter> vaut <symbol>NULL</symbol>, alors
      <function>SPI_cursor_open_with_args</function> suppose qu'aucun
      paramètre n'est NULL. Otherwise, each entry of the <parameter>nulls</parameter>
      array should be <literal>'&nbsp;'</literal> if the corresponding parameter
      value is non-null, or <literal>'n'</literal> if the corresponding parameter
      value is null.  (In the latter case, the actual value in the
      corresponding <parameter>values</parameter> entry doesn't matter.)  Note
      that <parameter>nulls</parameter> is not a text string, just an array:
      it does not need a <literal>'\0'</literal> terminator.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>bool <parameter>read_only</parameter></literal></term>
    <listitem>
     <para>
      <literal>true</literal> pour une exécution en lecture seule
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>int <parameter>cursorOptions</parameter></literal></term>
    <listitem>
     <para>
      masque de bits des options du curseur&nbsp;: zéro cause le comportement
      par défaut
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Valeur de retour</title>

  <para>
   Pointeur du portail contenant le curseur. Notez qu'il n'y a pas de convention
   pour le renvoi des erreurs&nbsp;; toute erreur sera rapportée par
   <function>elog</function>.
  </para>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-cursor-open-with-paramlist">
 <refmeta>
  <refentrytitle>SPI_cursor_open_with_paramlist</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_cursor_open_with_paramlist</refname>
  <refpurpose>ouvre un curseur en utilisant les paramètres</refpurpose>
 </refnamediv>

 <indexterm><primary>SPI_cursor_open_with_paramlist</primary></indexterm>

 <refsynopsisdiv>
<synopsis>
Portal SPI_cursor_open_with_paramlist(const char *<parameter>name</parameter>,
                                      SPIPlanPtr <parameter>plan</parameter>,
                                      ParamListInfo <parameter>params</parameter>,
                                      bool <parameter>read_only</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_cursor_open_with_paramlist</function> prépare un curseur (en
   interne un portail), qui exécutera une requête préparée par
   <function>SPI_prepare</function>. Cette fonction est équivalente à
   <function>SPI_cursor_open</function> sauf que les informations sur les
   valeurs des paramètres passées à la requête sont présentées différemment.
   La représentation de <literal>ParamListInfo</literal> peut être utile pour
   fournir des valeurs déjà disponibles dans ce format. Elle supporte aussi
   l'utilisation d'ensemble de paramètres dynamiques via des fonctions
   spécifiées dans <literal>ParamListInfo</literal>.
  </para>

  <para>
   Les données passées en paramètre seront copiées dans le portail du curseur
   et peuvent donc être libérées alors que le curseur existe toujours.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>const char * <parameter>name</parameter></literal></term>
    <listitem>
     <para>
      nom d'un portail ou <symbol>NULL</symbol> pour que le système en
      choisisse un lui-même
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>SPIPlanPtr <parameter>plan</parameter></literal></term>
    <listitem>
     <para>
      requête préparée (renvoyée par <function>SPI_prepare</function>)
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>ParamListInfo <parameter>params</parameter></literal></term>
    <listitem>
     <para>
      structure de données contenant les types et valeurs de paramètres&nbsp;;
      NULL sinon
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>bool <parameter>read_only</parameter></literal></term>
    <listitem>
     <para>
      <literal>true</literal> pour une exécution en lecture seule
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Valeur de retour</title>

  <para>
   Pointeur vers le portail contenant le curseur. Notez qu'il n'existe pas de
   convention pour le retour d'erreur&nbsp;; toute erreur sera renvoyée via
   <function>elog</function>.
  </para>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-cursor-find">
 <refmeta>
  <refentrytitle>SPI_cursor_find</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_cursor_find</refname>
  <refpurpose>recherche un curseur existant par nom</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>Portal SPI_cursor_find(const char * <parameter>name</parameter>)</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>
  <indexterm><primary>SPI_cursor_find</primary></indexterm>

  <para>
   <function>SPI_cursor_find</function> recherche un portail par nom.
   Ceci est principalement utile pour résoudre un nom de curseur renvoyé
   en tant que texte par une autre fonction.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>const char * <parameter>name</parameter></literal></term>
    <listitem>
     <para>
      nom du portail
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Valeur de retour</title>

  <para>
   Pointeur vers le portail portant le nom spécifié ou
   <symbol>NULL</symbol> si aucun n'a été trouvé
  </para>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-cursor-fetch">
 <refmeta>
  <refentrytitle>SPI_cursor_fetch</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_cursor_fetch</refname>
  <refpurpose>extrait des lignes à partir d'un curseur</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>void SPI_cursor_fetch(Portal <parameter>portal</parameter>, bool <parameter>forward</parameter>, long <parameter>count</parameter>)</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>
  <indexterm><primary>SPI_cursor_fetch</primary></indexterm>

  <para>
   <function>SPI_cursor_fetch</function> extrait des lignes à partir d'un
   curseur. Ceci est équivalent à un sous-ensemble de la commande SQL
   <command>FETCH</command> (voir <function>SPI_scroll_cursor_fetch</function>
   pour plus de détails).
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>Portal <parameter>portal</parameter></literal></term>
    <listitem>
     <para>
      portail contenant le curseur
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>bool <parameter>forward</parameter></literal></term>
    <listitem>
     <para>
     vrai pour une extraction en avant, faux pour une extraction en arrière
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>long <parameter>count</parameter></literal></term>
    <listitem>
     <para>
      nombre maximum de lignes à récupérer
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Valeur de retour</title>

  <para>
   <varname>SPI_processed</varname> et
   <varname>SPI_tuptable</varname> sont positionnés comme dans
   <function>SPI_execute</function> en cas de réussite.
  </para>
 </refsect1>

 <refsect1>
  <title>Notes</title>

  <para>
   Récupérer en sens inverse pourrait échouer si le plan du curseur n'était pas
   créé avec l'option <symbol>CURSOR_OPT_SCROLL</symbol>.
  </para>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-cursor-move">
 <refmeta>
  <refentrytitle>SPI_cursor_move</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_cursor_move</refname>
  <refpurpose>déplace un curseur</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>void SPI_cursor_move(Portal <parameter>portal</parameter>, bool <parameter>forward</parameter>, long <parameter>count</parameter>)</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>
  <indexterm><primary>SPI_cursor_move</primary></indexterm>

  <para>
   <function>SPI_cursor_move</function> saute un certain nombre de lignes
   dans un curseur. Ceci est équivalent à un sous-ensemble de la commande SQL
   <command>MOVE</command> (voir <function>SPI_scroll_cursor_move</function>
   pour plus de détails).
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>Portal <parameter>portal</parameter></literal></term>
    <listitem>
     <para>
      portail contenant le curseur
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>bool <parameter>forward</parameter></literal></term>
    <listitem>
     <para>
      vrai pour un saut en avant, faux pour un saut en arrière
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>long <parameter>count</parameter></literal></term>
    <listitem>
     <para>
      nombre maximum de lignes à déplacer
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Notes</title>

  <para>
   Se déplacer en sens inverse pourrait échouer si le plan du curseur n'a pas
   été créé avec l'option <symbol>CURSOR_OPT_SCROLL</symbol> option.
  </para>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-scroll-cursor-fetch">
 <refmeta>
  <refentrytitle>SPI_scroll_cursor_fetch</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_scroll_cursor_fetch</refname>
  <refpurpose>récupère quelques lignes à partir d'un curseur</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  <indexterm><primary>SPI_scroll_cursor_fetch</primary></indexterm>
<synopsis>
void SPI_scroll_cursor_fetch(Portal <parameter>portal</parameter>, FetchDirection <parameter>direction</parameter>, long <parameter>count</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_scroll_cursor_fetch</function> récupère quelques lignes à
   partir d'un curseur. C'est équivalent à la commande SQL <command>FETCH</command>.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>Portal <parameter>portal</parameter></literal></term>
    <listitem>
     <para>
      portail contenant le curseur
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>FetchDirection <parameter>direction</parameter></literal></term>
    <listitem>
     <para>
      un parmi <symbol>FETCH_FORWARD</symbol>,
      <symbol>FETCH_BACKWARD</symbol>,
      <symbol>FETCH_ABSOLUTE</symbol> ou
      <symbol>FETCH_RELATIVE</symbol>
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>long <parameter>count</parameter></literal></term>
    <listitem>
     <para>
      nombre de lignes à récupérer pour <symbol>FETCH_FORWARD</symbol> ou
      <symbol>FETCH_BACKWARD</symbol>&nbsp;; nombre de lignes absolu à récupérer
      pour <symbol>FETCH_ABSOLUTE</symbol>&nbsp;; ou nombre de lignes relatif
      à récupérer pour <symbol>FETCH_RELATIVE</symbol>
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Valeur de retour</title>

  <para>
   <varname>SPI_processed</varname> et
   <varname>SPI_tuptable</varname> sont configurés comme
   <function>SPI_execute</function> en cas de succès.
  </para>
 </refsect1>

 <refsect1>
  <title>Notes</title>

  <para>
   Voir la commande SQL <xref linkend="sql-fetch"/>
   pour des détails sur l'interprétation des paramètres
   <parameter>direction</parameter> et <parameter>count</parameter>.
  </para>

  <para>
   Les valeurs de direction autres que <symbol>FETCH_FORWARD</symbol>
   peuvent échouer si le plan du curseur n'a pas été créé avec l'option
   <symbol>CURSOR_OPT_SCROLL</symbol>.
  </para>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-scroll-cursor-move">
 <refmeta>
  <refentrytitle>SPI_scroll_cursor_move</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_scroll_cursor_move</refname>
  <refpurpose>déplacer un curseur</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
   <indexterm><primary>SPI_scroll_cursor_move</primary></indexterm>
<synopsis>
void SPI_scroll_cursor_move(Portal <parameter>portal</parameter>, FetchDirection <parameter>direction</parameter>, long <parameter>count</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_scroll_cursor_move</function> ignore un certain nombre de
   lignes dans un curseur. C'est l'équivalent de la commande SQL
   <command>MOVE</command>.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>Portal <parameter>portal</parameter></literal></term>
    <listitem>
     <para>
      portail contenant le curseur
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>FetchDirection <parameter>direction</parameter></literal></term>
    <listitem>
     <para>
      un parmi <symbol>FETCH_FORWARD</symbol>,
      <symbol>FETCH_BACKWARD</symbol>,
      <symbol>FETCH_ABSOLUTE</symbol> et
      <symbol>FETCH_RELATIVE</symbol>
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>long <parameter>count</parameter></literal></term>
    <listitem>
     <para>
      nombre de lignes à déplacer pour <symbol>FETCH_FORWARD</symbol> ou
      <symbol>FETCH_BACKWARD</symbol>&nbsp;; nombre de lignes absolu à déplacer
      pour <symbol>FETCH_ABSOLUTE</symbol>&nbsp;; ou nombre de lignes relatif
      à déplacer pour <symbol>FETCH_RELATIVE</symbol>
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Valeur de retour</title>

  <para>
   <varname>SPI_processed</varname> est configuré comme
   <function>SPI_execute</function> en cas de succès.
   <varname>SPI_tuptable</varname> est configuré à <symbol>NULL</symbol> car
   aucune ligne n'est renvoyée par cette fonction.
  </para>
 </refsect1>

 <refsect1>
  <title>Notes</title>

  <para>
   Voir la commande SQL <xref linkend="sql-fetch"/>
   pour des détails sur l'interprétation des paramètres
   <parameter>direction</parameter> et <parameter>count</parameter>.
  </para>

  <para>
   Les valeurs de direction autres que <symbol>FETCH_FORWARD</symbol> peuvent
   échouer si le plan du curseur n'a pas été créé avec l'option 
   <symbol>CURSOR_OPT_SCROLL</symbol>.
  </para>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-cursor-close">
 <refmeta>
  <refentrytitle>SPI_cursor_close</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_cursor_close</refname>
  <refpurpose>ferme un curseur</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>void SPI_cursor_close(Portal <parameter>portal</parameter>)</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>
  <indexterm><primary>SPI_cursor_close</primary></indexterm>

  <para>
   <function>SPI_cursor_close</function> ferme un curseur créé précédemment
   et libère la mémoire du portail.
  </para>

  <para>
   Tous les curseurs ouverts sont fermés automatiquement à la fin de la
   transaction. <function>SPI_cursor_close</function> n'a besoin d'être
   invoqué que s'il est désirable de libérer les ressources plus tôt.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>Portal <parameter>portal</parameter></literal></term>
    <listitem>
     <para>
      portail contenant le curseur
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-keepplan">
 <refmeta>
  <refentrytitle>SPI_keepplan</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_keepplan</refname>
  <refpurpose>sauvegarde une instruction préparée</refpurpose>
 </refnamediv>

 <indexterm><primary>SPI_keepplan</primary></indexterm>

 <refsynopsisdiv>
<synopsis>
int SPI_keepplan(SPIPlanPtr <parameter>plan</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_keepplan</function> sauvegarde une instruction passée (préparée
   par <function>SPI_prepare</function>) pour qu'elle ne soit pas libérée par
   <function>SPI_finish</function> ou par le gestionnaire des transactions.
   Cela vous donne la possibilité de ré-utiliser les instructions préparées dans
   les prochains appels à votre procédure dans la session courante.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>SPIPlanPtr <parameter>plan</parameter></literal></term>
    <listitem>
     <para>
      l'instruction préparée à sauvegarder
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Valeur de retour</title>

  <para>
   0 en cas de succès&nbsp;;
   <symbol>SPI_ERROR_ARGUMENT</symbol> si <parameter>plan</parameter>
   vaut <symbol>NULL</symbol> ou est invalide
  </para>
 </refsect1>

 <refsect1>
  <title>Notes</title>

  <para>
   L'instruction passée est relocalisée dans un stockage permanent par
   l'ajustement de pointeur (pas de copie de données requise). Si vous souhaitez
   la supprimer plus tard, utilisez <function>SPI_freeplan</function>.
  </para>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-saveplan">
 <refmeta>
  <refentrytitle>SPI_saveplan</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_saveplan</refname>
  <refpurpose>sauvegarde une requête préparée</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>SPIPlanPtr SPI_saveplan(SPIPlanPtr <parameter>plan</parameter>)</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>
  <indexterm><primary>SPI_saveplan</primary></indexterm>

  <para>
   <function>SPI_saveplan</function> copie une instruction passée (préparée par
   <function>SPI_prepare</function>) en mémoire qui ne serait pas libérée par
   <function>SPI_finish</function> ou par le gestionnaire de transactions, et
   renvoie un pointeur vers l'instruction copiée. Cela vous donne la possibilité
   de réutiliser des instructions préparées dans les appels suivants de votre
   procédure dans la session courante.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>SPIPlanPtr <parameter>plan</parameter></literal></term>
    <listitem>
     <para>
      la requête préparée à sauvegarder
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Valeur de retour</title>

  <para>
   Pointeur vers la requête copiée&nbsp;; <symbol>NULL</symbol> en cas d'échec.
   En cas d'erreur, <varname>SPI_result</varname> est positionnée comme
   suit&nbsp;:

   <variablelist>
    <varlistentry>
     <term><symbol>SPI_ERROR_ARGUMENT</symbol></term>
     <listitem>
      <para>
       si <parameter>plan</parameter> est <symbol>NULL</symbol> ou invalide
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><symbol>SPI_ERROR_UNCONNECTED</symbol></term>
     <listitem>
      <para>
       si appelé d'une procédure non connectée
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1>
  <title>Notes</title>

  <para>
   La requête passée n'est pas libérée, donc vous pouvez souhaiter exécuter
   <function>SPI_freeplan</function> sur ce dernier pour éviter des pertes
   mémoire jusqu'à <function>SPI_finish</function>.
  </para>

  <para>
   Dans la plupart des cas, <function>SPI_keepplan</function> est préférée à
   cette fonction car elle accomplit largement le même résultat sans avoir
   besoin de copier physiquement la structure de données des instructions
   préparées.
  </para>
 </refsect1>
</refentry>

</sect1>

<sect1 id="spi-interface-support">
 <title>Fonctions de support d'interface</title>

 <para>
  Les fonctions décrites ici donnent une interface pour extraire
  les informations des séries de résultats renvoyés par <function>SPI_execute</function> et
  les autres fonctions SPI.
 </para>

 <para>
  Toutes les fonctions décrites dans cette section peuvent être utilisées par
  toutes les procédures, connectées et non connectées.
 </para>

<!-- *********************************************** -->

<refentry id="spi-spi-fname">
 <refmeta>
  <refentrytitle>SPI_fname</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_fname</refname>
  <refpurpose>détermine le nom de colonne pour le numéro de colonne
spécifié</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>char * SPI_fname(TupleDesc <parameter>rowdesc</parameter>, int <parameter>colnumber</parameter>)</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>
  <indexterm><primary>SPI_fname</primary></indexterm>

  <para>
   <function>SPI_fname</function> retourne une copie du nom de colonne d'une
   colonne spécifiée (vous pouvez utiliser <function>pfree</function> pour
   libérer la copie du nom lorsque vous n'en avez plus besoin).
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
    <listitem>
     <para>
      description de rangée d'entrée
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>int <parameter>colnumber</parameter></literal></term>
    <listitem>
     <para>
      nombre de colonne (le compte commence à 1)
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Valeur de retour</title>

  <para>
   Le nom de colonne&nbsp;; <symbol>NULL</symbol> si
   <parameter>colnumber</parameter> est hors de portée.
   <varname>SPI_result</varname> est positionnée à
   <symbol>SPI_ERROR_NOATTRIBUTE</symbol> en cas d'échec.
  </para>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-fnumber">
 <refmeta>
  <refentrytitle>SPI_fnumber</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_fnumber</refname>
  <refpurpose>détermine le numéro de colonne pour le nom de colonne
spécifiée</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>int SPI_fnumber(TupleDesc <parameter>rowdesc</parameter>, const char * <parameter>colname</parameter>)</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>
  <indexterm><primary>SPI_fnumber</primary></indexterm>

  <para>
   <function>SPI_fnumber</function> renvoie le numéro de colonne pour la
   colonne portant le nom spécifié.
  </para>

  <para>
   Si <parameter>colname</parameter> réfère à une colonne système
   (c'est-à-dire <literal>oid</literal>), alors le numéro de colonne négatif approprié
   sera renvoyé. L'appelant devra faire attention à tester la valeur de retour
   pour égalité exacte à <symbol>SPI_ERROR_NOATTRIBUTE</symbol> pour
   détecter une erreur&nbsp;; tester le résultat pour une valeur inférieure ou
   égale à 0 n'est pas correcte sauf si les colonnes systèmes doivent être
   rejetées.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
    <listitem>
     <para>
      description de la rangée d'entrée
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>const char *
     <parameter>colname</parameter></literal></term>
    <listitem>
     <para>
      nom de colonne
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Valeur de retour</title>

  <para>
   Numéro de colonne (le compte commence à 1) ou
   <symbol>SPI_ERROR_NOATTRIBUTE</symbol> si la colonne nommée n'est
   trouvée.
  </para>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-getvalue">
 <refmeta>
  <refentrytitle>SPI_getvalue</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_getvalue</refname>
  <refpurpose>renvoie la valeur de chaîne de la colonne spécifiée</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>char * SPI_getvalue(HeapTuple <parameter>row</parameter>, TupleDesc <parameter>rowdesc</parameter>, int <parameter>colnumber</parameter>)</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>
  <indexterm><primary>SPI_getvalue</primary></indexterm>

  <para>
   <function>SPI_getvalue</function> retourne la représentation chaîne
   de la valeur de la colonne spécifiée.
  </para>

  <para>
   Le résultat est retourné en mémoire allouée en utilisant
   <function>palloc</function> (vous pouvez utiliser
   <function>pfree</function> pour libérer la mémoire lorsque vous n'en avez
   plus besoin).
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>HeapTuple <parameter>row</parameter></literal></term>
    <listitem>
     <para>
      ligne d'entrée à examiner
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
    <listitem>
     <para>
      description de la ligne en entrée
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>int <parameter>colnumber</parameter></literal></term>
    <listitem>
     <para>
      numéro de colonne (le compte commence à 1)
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Valeur de retour</title>

  <para>
   Valeur de colonne ou <symbol>NULL</symbol> si la colonne est NULL,
   si <parameter>colnumber</parameter> est hors de portée
   (<varname>SPI_result</varname> est positionnée à
   <symbol>SPI_ERROR_NOATTRIBUTE</symbol>) ou si aucune fonction de sortie
   n'est disponible (<varname>SPI_result</varname> est positionnée à
   <symbol>SPI_ERROR_NOOUTFUNC</symbol>).
  </para>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-getbinval">
 <refmeta>
  <refentrytitle>SPI_getbinval</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_getbinval</refname>
  <refpurpose>retourne la valeur binaire de la colonne spécifiée</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>Datum SPI_getbinval(HeapTuple <parameter>row</parameter>, TupleDesc <parameter>rowdesc</parameter>, int <parameter>colnumber</parameter>, bool * <parameter>isNULL</parameter>)</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>
  <indexterm><primary>SPI_getbinval</primary></indexterm>

  <para>
   <function>SPI_getbinval</function> retourne la valeur de la
   colonne spécifiée dans le format interne (en tant que type
   <type>Datum</type>).
  </para>

  <para>
   Cette fonction n'alloue pas de nouvel espace pour le datum. Dans le
   cas d'un type de données passé par référence, la valeur de retour sera un
   pointeur dans la ligne passée.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>HeapTuple <parameter>row</parameter></literal></term>
    <listitem>
     <para>
      ligne d'entrée à examiner
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
    <listitem>
     <para>
      description de la ligne d'entrée
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>int <parameter>colnumber</parameter></literal></term>
    <listitem>
     <para>
      numéro de colonne (le compte commence à 1)
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>bool * <parameter>isNULL</parameter></literal></term>
    <listitem>
     <para>
      indique une valeur NULL dans la colonne
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Valeur de retour</title>

  <para>
   La valeur binaire de la colonne est retournée. La variable vers laquelle
   pointe <parameter>isNULL</parameter> est positionnée à vrai si la colonne
   est NULL et sinon à faux.
  </para>

  <para>
   <varname>SPI_result</varname> est positionnée à
   <symbol>SPI_ERROR_NOATTRIBUTE</symbol> en cas d'erreur.
  </para>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-gettype">
 <refmeta>
  <refentrytitle>SPI_gettype</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_gettype</refname>
  <refpurpose>retourne le nom du type de donnée de la colonne
spécifiée</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>char * SPI_gettype(TupleDesc <parameter>rowdesc</parameter>, int <parameter>colnumber</parameter>)</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>
  <indexterm><primary>SPI_gettype</primary></indexterm>

  <para>
   <function>SPI_gettype</function> retourne une copie du nom du type de donnée de la
   colonne spécifiée (vous pouvez utiliser <function>pfree</function> pour
   libérer la copie du nom lorsque vous n'en avez plus besoin).
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
    <listitem>
     <para>
      description de ligne d'entrée
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>int <parameter>colnumber</parameter></literal></term>
    <listitem>
     <para>
      numéro de colonne (le compte commence à 1)
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Valeur de retour</title>

  <para>
   Le nom de type de donnée de la colonne spécifiée ou
   <symbol>NULL</symbol> en cas d'erreur.  <varname>SPI_result</varname> est
   positionnée à <symbol>SPI_ERROR_NOATTRIBUTE</symbol> en cas d'erreur.
  </para>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-gettypeid">
 <refmeta>
  <refentrytitle>SPI_gettypeid</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_gettypeid</refname>
  <refpurpose>retourne l'<acronym>OID</acronym> de type de donnée de la colonne
spécifiée</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>Oid SPI_gettypeid(TupleDesc <parameter>rowdesc</parameter>, int <parameter>colnumber</parameter>)</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>
  <indexterm><primary>SPI_gettypeid</primary></indexterm>

  <para>
   <function>SPI_gettypeid</function> retourne
   l'<acronym>OID</acronym> du type de donnée de la colonne spécifiée.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
    <listitem>
     <para>
      description de ligne d'entrée
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>int <parameter>colnumber</parameter></literal></term>
    <listitem>
     <para>
      numéro de colonne (le compte commence à 1)
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Valeur de retour</title>

  <para>
   L'<acronym>OID</acronym> du type de donnée de la colonne spécifiée
   ou <symbol>InvalidOid</symbol> en cas d'erreur. En cas d'erreur,
   <varname>SPI_result</varname> est positionnée à
   <symbol>SPI_ERROR_NOATTRIBUTE</symbol>.
  </para>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-getrelname">
 <refmeta>
  <refentrytitle>SPI_getrelname</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_getrelname</refname>
  <refpurpose>retourne le nom de la relation spécifiée</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>char * SPI_getrelname(Relation <parameter>rel</parameter>)</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>
  <indexterm><primary>SPI_getrelname</primary></indexterm>


  <para>
   <function>SPI_getrelname</function> retourne une copie du nom de la
   relation spécifiée (vous pouvez utiliser <function>pfree</function> pour
   libérer la copie du nom lorsque vous n'en avez plus besoin).
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>Relation <parameter>rel</parameter></literal></term>
    <listitem>
     <para>
      relation d'entrée
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Valeur de retour</title>

  <para>
   Le nom de la relation spécifiée.
  </para>
 </refsect1>
</refentry>

<refentry id="spi-spi-getnspname">
 <refmeta>
  <refentrytitle>SPI_getnspname</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_getnspname</refname>
  <refpurpose>renvoie l'espace de noms de la relation spécifiée</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>char * SPI_getnspname(Relation <parameter>rel</parameter>)</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>
  <indexterm><primary>SPI_getnspname</primary></indexterm>

  <para>
   <function>SPI_getnspname</function> renvoie une copie du nom de l'espace de
   nom auquel appartient la <structname>Relation</structname> spécifiée. Ceci
   est équivalent au schéma de la relation. Vous devriez libérer
   (<function>pfree</function>) la valeur de retour de cette fonction lorsque
   vous en avez fini avec elle.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>Relation <parameter>rel</parameter></literal></term>
    <listitem>
     <para>
      relation en entrée
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Valeur de retour</title>

  <para>
   Le nom de l'espace de noms de la relation spécifiée.
  </para>
 </refsect1>
</refentry>

 </sect1>

 <sect1 id="spi-memory">
  <title>Gestion de la mémoire</title>

  <para>
    <indexterm>
     <primary>contexte mémoire</primary>
     <secondary>dans SPI</secondary>
    </indexterm>
   <productname>PostgreSQL</productname> alloue de la mémoire dans des
   <firstterm>contextes mémoire</firstterm> qui
   donnent une méthode pratique pour
   gérer les allocations faîtes dans plusieurs endroits qui ont besoin de
   vivre pour des durées différentes. Détruire un contexte libère
   toute la mémoire qui y était allouée. Donc, il n'est pas nécessaire
   de garder la trace des objets individuels pour éviter les fuites de
   mémoire&nbsp;; à la place,
   seul un petit nombre de contextes doivent être gérés.
   <function>palloc</function> et les fonctions liées allouent de la mémoire
   du contexte <quote>courant</quote>.
  </para>

  <para>
   <function>SPI_connect</function> crée un nouveau contexte mémoire et
   le rend courant. <function>SPI_finish</function> restaure le
   contexte mémoire précédant et détruit le contexte créé par
   <function>SPI_connect</function>. Ces actions garantissent que les
   allocations temporaires de mémoire faîtes dans votre procédure soient
   réclamées lors de la sortie de la procédure, évitant les fuites de mémoire.
  </para>

  <para>
   En revanche, si votre procédure a besoin de renvoyer un objet dans de la
   mémoire allouée (tel que la valeur d'un type de donné passé par référence),
   vous ne pouvez pas allouer cette mémoire en utilisant
   <function>palloc</function>, au
   moins pas tant que vous êtes connecté à SPI. Si vous essayez, l'objet
   sera désalloué par <function>SPI_finish</function> et votre procédure
   ne fonctionnera pas de manière fiable. Pour résoudre ce problème, utilisez
   <function>SPI_palloc</function> pour allouer de la mémoire pour votre objet
   de retour. <function>SPI_palloc</function> alloue de la mémoire dans le
   <quote>contexte de mémoire courant</quote>, c'est-à-dire le contexte de
   mémoire qui était courant lorsque <function>SPI_connect</function> a été
   appelée, ce qui est précisément le bon contexte pour une valeur renvoyée à
   partir de votre procédure.
  </para>

  <para>
   Si <function>SPI_palloc</function> est appelé pendant que la procédure n'est
   pas connectée à SPI, alors il agit de la même manière qu'un
   <function>palloc</function>
   normal. Avant qu'une procédure ne se connecte au gestionnaire
   SPI, toutes les allocations faîtes par la procédure via
   <function>palloc</function> ou par une fonction utilitaire SPI sont faîtes
   dans le contexte de mémoire courant.
  </para>

  <para>
   Quand <function>SPI_connect</function> est appelée, le contexte
   privé de la procédure, qui est créée par
   <function>SPI_connect</function>, est nommé le contexte courant. Toute
   allocation faîte par <function>palloc</function>,
   <function>repalloc</function> ou une fonction utilitaire SPI (à part pour
   <function>SPI_copytuple</function>,
   <function>SPI_returntuple</function>,
   <function>SPI_modifytuple</function>, et
   <function>SPI_palloc</function>) sont faîtes dans ce contexte. Quand une
   procédure se déconnecte du gestionnaire SPI (via
   <function>SPI_finish</function>), le contexte courant est restauré au
   contexte de mémoire courant et toutes les allocations faîtes dans
   le contexte de mémoire de la procédure sont libérées et ne peuvent plus être
   utilisées.
  </para>

  <para>
   Toutes les fonctions couvertes dans cette section peuvent être utilisées par
   des procédures connectées comme non connectées. Dans une procédure non
   connectée, elles agissent de la même façon que les fonctions serveur
   sous-jacentes (<function>palloc</function>, etc.).
  </para>

<!-- *********************************************** -->

<refentry id="spi-spi-palloc">
 <refmeta>
  <refentrytitle>SPI_palloc</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_palloc</refname>
  <refpurpose>alloue de la mémoire dans le contexte de mémoire
courant</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>void * SPI_palloc(Size <parameter>size</parameter>)</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>
  <indexterm><primary>SPI_palloc</primary></indexterm>

  <para>
   <function>SPI_palloc</function> alloue de la mémoire dans le contexte
   de mémoire courant.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>Size <parameter>size</parameter></literal></term>
    <listitem>
     <para>
      taille en octets du stockage à allouer
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Valeur de retour</title>

  <para>
   Pointeur vers le nouvel espace de stockage de la taille spécifiée
  </para>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-realloc">
 <refmeta>
  <refentrytitle>SPI_repalloc</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_repalloc</refname>
  <refpurpose>ré-alloue de la mémoire dans le contexte de mémoire
courant</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>void * SPI_repalloc(void * <parameter>pointer</parameter>, Size <parameter>size</parameter>)</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>
  <indexterm><primary>SPI_repalloc</primary></indexterm>

  <para>
   <function>SPI_repalloc</function> change la taille d'un segment de mémoire
   alloué auparavant en utilisant <function>SPI_palloc</function>.
  </para>

  <para>
   Cette fonction n'est plus différente du <function>repalloc</function>
   standard. Elle n'est gardée que pour la compatibilité
   du code existant.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>void * <parameter>pointer</parameter></literal></term>
    <listitem>
     <para>
      pointeur vers l'espace de stockage à modifier
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>Size <parameter>size</parameter></literal></term>
    <listitem>
     <para>
      taille en octets du stockage à allouer
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Valeur de retour</title>

  <para>
   Pointeur vers le nouvel espace de stockage de taille spécifiée avec le
   contenu copié de l'espace existant
  </para>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-pfree">
 <refmeta>
  <refentrytitle>SPI_pfree</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_pfree</refname>
  <refpurpose>libère de la mémoire dans le contexte de mémoire
courant</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>void SPI_pfree(void * <parameter>pointer</parameter>)</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>
  <indexterm><primary>SPI_pfree</primary></indexterm>

  <para>
   <function>SPI_pfree</function> libère de la mémoire allouée auparavant
   par <function>SPI_palloc</function> ou
   <function>SPI_repalloc</function>.
  </para>

  <para>
   Cette fonction n'est plus différente du <function>pfree</function>
   standard. Elle n'est conservée que pour la compatibilité
   du code existant.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>void * <parameter>pointer</parameter></literal></term>
    <listitem>
     <para>
      pointeur vers l'espace de stockage à libérer
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-copytuple">
 <refmeta>
  <refentrytitle>SPI_copytuple</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_copytuple</refname>
  <refpurpose>effectue une copie d'une ligne dans le contexte de mémoire
courant</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>HeapTuple SPI_copytuple(HeapTuple <parameter>row</parameter>)</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>
  <indexterm><primary>SPI_copytuple</primary></indexterm>

  <para>
   <function>SPI_copytuple</function> crée une copie d'une ligne dans le
   contexte de mémoire courant. Ceci est normalement utilisé pour renvoyer une
   ligne modifiée à partir d'un déclencheur. Dans une fonction déclarée pour
   renvoyer un type composite, utilisez <function>SPI_returntuple</function> à
   la place.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>HeapTuple <parameter>row</parameter></literal></term>
    <listitem>
     <para>
      ligne à copier
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Valeur de retour</title>

  <para>
   la ligne copiée&nbsp;; <symbol>NULL</symbol> seulement si
   <parameter>row</parameter> est <symbol>NULL</symbol>
  </para>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-returntuple">
  <refmeta>
    <refentrytitle>SPI_returntuple</refentrytitle>
  <manvolnum>3</manvolnum>
  </refmeta>
  
  <refnamediv>
    <refname>SPI_returntuple</refname>
    <refpurpose>prépare le renvoi d'une ligne en tant que Datum</refpurpose>
  </refnamediv>
  
  <refsynopsisdiv>
    <synopsis>HeapTupleHeader SPI_returntuple(HeapTuple <parameter>row</parameter>, TupleDesc <parameter>rowdesc</parameter>)</synopsis>
  </refsynopsisdiv>
  
  <refsect1>
    <title>Description</title>
    <indexterm><primary>SPI_returntuple</primary></indexterm>
    
    <para>
      <function>SPI_returntuple</function> crée une copie d'une ligne dans
      le contexte de l'exécuteur supérieur, la renvoyant sous la forme d'une
      ligne de type <type>Datum</type>. Le pointeur renvoyé a seulement besoin
      d'être converti en <type>Datum</type> via 
      <function>PointerGetDatum</function> avant d'être renvoyé.
    </para>
    
    <para>
      Notez que ceci devrait être utilisé pour les fonctions qui déclarent
      renvoyer des types composites. Ce n'est pas utilisé pour les
      déclencheurs&nbsp;; utilisez pour renvoyer une ligne modifiée
      dans un déclencheur.
    </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>HeapTuple <parameter>row</parameter></literal></term>
    <listitem>
     <para>
      ligne à copier
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>TupleDesc <parameter>rowdesc</parameter></literal></term>
    <listitem>
     <para>
      descripteur pour la ligne (passez le même descripteur chaque fois pour un
      cache plus efficace)
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Valeur de retour</title>

  <para>
   <type>HeapTupleHeader</type> pointant vers la ligne copiée&nbsp;;
   <symbol>NULL</symbol> seulement si
   <parameter>row</parameter> ou <parameter>rowdesc</parameter> est
   <symbol>NULL</symbol>
  </para>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-modifytuple">
 <refmeta>
  <refentrytitle>SPI_modifytuple</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_modifytuple</refname>
  <refpurpose>crée une ligne en remplaçant les champs sélectionnés d'une ligne
donnée</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>HeapTuple SPI_modifytuple(Relation <parameter>rel</parameter>, HeapTuple <parameter>row</parameter>, <parameter>ncols</parameter>, <parameter>colnum</parameter>, Datum * <parameter>values</parameter>, const char * <parameter>nulls</parameter>)</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>
  <indexterm><primary>SPI_modifytuple</primary></indexterm>

  <para>
   <function>SPI_modifytuple</function> crée une nouvelle ligne en
   retirant les nouvelles valeurs pour les colonnes sélectionnées et en copiant
   les colonnes de la ligne d'origine à d'autres positions. La ligne d'entrée
   n'est pas modifiée.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>Relation <parameter>rel</parameter></literal></term>
    <listitem>
     <para>
      Utilisé seulement en tant que source du descripteur de ligne pour la
      ligne (passez une relation plutôt qu'un descripteur de ligne est une
      erreur).
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>HeapTuple <parameter>row</parameter></literal></term>
    <listitem>
     <para>
      rangée à modifier
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>int <parameter>ncols</parameter></literal></term>
    <listitem>
     <para>
      nombre de numéros de colonnes à changer
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>int * <parameter>colnum</parameter></literal></term>
    <listitem>
     <para>
      tableau of length <parameter>ncols</parameter>, contenant les numéros de colonnes à modifier
      (le numéro des colonnes commence à 1)
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>Datum * <parameter>values</parameter></literal></term>
    <listitem>
     <para>
      an array of length <parameter>ncols</parameter>, containing the nouvelles valeurs pour les colonnes spécifiées
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>const char * <parameter>nulls</parameter></literal></term>
    <listitem>
     <para>
      an array of length <parameter>ncols</parameter>, describing which
      new values are null
     </para>

     <para>
      If <parameter>nulls</parameter> is <symbol>NULL</symbol> then
      <function>SPI_modifytuple</function> assumes that no new values
      are null.  Otherwise, each entry of the <parameter>nulls</parameter>
      array should be <literal>'&nbsp;'</literal> if the corresponding new value is
      non-null, or <literal>'n'</literal> if the corresponding new value is
      null.  (In the latter case, the actual value in the corresponding
      <parameter>values</parameter> entry doesn't matter.)  Note that
      <parameter>nulls</parameter> is not a text string, just an array: it
      does not need a <literal>'\0'</literal> terminator.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Valeur de retour</title>

  <para>
   nouvelle ligne avec modifications, allouée dans le contexte de mémoire
   courant&nbsp;; <symbol>NULL</symbol> seulement si
   <parameter>row</parameter> est <symbol>NULL</symbol>
  </para>

  <para>
   En cas d'erreur, <varname>SPI_result</varname> est positionnée comme
   suit&nbsp;:
   <variablelist>
    <varlistentry>
     <term><symbol>SPI_ERROR_ARGUMENT</symbol></term>
     <listitem>
      <para>
       si <parameter>rel</parameter> est <symbol>NULL</symbol> ou si
       <parameter>row</parameter> est <symbol>NULL</symbol> ou si <parameter>ncols</parameter>
       est inférieur ou égal à 0 ou si <parameter>nocolonne</parameter> est
       <symbol>NULL</symbol> ou si <parameter>values</parameter> est <symbol>NULL</symbol>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><symbol>SPI_ERROR_NOATTRIBUTE</symbol></term>
     <listitem>
      <para>
       si <parameter>nocolonne</parameter> contient un numéro de colonne invalide
       (inférieur ou égal à 0 ou supérieur au numéro de colonne dans
       <parameter>row</parameter>)
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-freetuple">
 <refmeta>
  <refentrytitle>SPI_freetuple</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_freetuple</refname>
  <refpurpose>libère une ligne allouée dans le contexte de mémoire
courant</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>void SPI_freetuple(HeapTuple <parameter>row</parameter>)</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>
  <indexterm><primary>SPI_freetuple</primary></indexterm>

  <para>
   <function>SPI_freetuple</function> libère une rangée allouée auparavant
   dans le contexte de mémoire courant.
  </para>

  <para>
   Cette fonction n'est plus différente du standard
   <function>heap_freetuple</function>. Elle est gardée juste pour la
   compatibilité du code existant.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>HeapTuple <parameter>row</parameter></literal></term>
    <listitem>
     <para>
      rangée à libérer
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-freetupletable">
 <refmeta>
  <refentrytitle>SPI_freetuptable</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_freetuptable</refname>
  <refpurpose>libère une série de lignes créée par <function>SPI_execute</function> ou une
fonction semblable</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>void SPI_freetuptable(SPITupleTable * <parameter>tuptable</parameter>)</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>
  <indexterm><primary>SPI_freetuptable</primary></indexterm>

  <para>
   <function>SPI_freetuptable</function> libère une série de lignes créée
   auparavant par une fonction d'exécution de commandes SPI, tel que
   <function>SPI_execute</function>. Par conséquent, cette fonction est souvent appelée
   avec la variable globale <varname>SPI_tupletable</varname> comme
   argument.
  </para>

  <para>
   Cette fonction est utile si une procédure SPI a besoin d'exécuter
   de multiples commandes et ne veut pas garder les résultats de commandes
   précédentes en mémoire jusqu'à sa fin. Notez que toute série de lignes non
   libérées est libérée quand même lors de <function>SPI_finish</function>.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>SPITupleTable *
<parameter>tuptable</parameter></literal></term>
    <listitem>
     <para>
      pointeur vers la série de lignes à libérer
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-freeplan">
 <refmeta>
  <refentrytitle>SPI_freeplan</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_freeplan</refname>
  <refpurpose>libère une requête préparée sauvegardée auparavant</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>int SPI_freeplan(SPIPlanPtr <parameter>plan</parameter>)</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>
  <indexterm><primary>SPI_freeplan</primary></indexterm>

  <para>
   <function>SPI_freeplan</function> libère une requête préparée
   retournée auparavant par <function>SPI_prepare</function> ou sauvegardée par
   <function>SPI_keepplan</function> ou <function>SPI_saveplan</function>.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>SPIPlanPtr <parameter>plan</parameter></literal></term>
    <listitem>
     <para>
      pointeur vers la requête à libérer
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Valeur de retour</title>

  <para>
   0 en cas de succès&nbsp;;
   <symbol>SPI_ERROR_ARGUMENT</symbol> si <parameter>plan</parameter>
   est <symbol>NULL</symbol> ou invalide.
  </para>
 </refsect1>
</refentry>

 </sect1>

 <sect1 id="spi-visibility">
  <title>Visibilité des modifications de données</title>

  <para>
   Les règles suivantes gouvernent la visibilité des modifications de données dans
   les fonctions qui utilisent SPI (ou tout autre fonction C)&nbsp;:

   <itemizedlist>
    <listitem>
     <para>
      Pendant l'exécution de la commande SQL, toute modification de données faite par
      la commande est invisible à la commande. Par exemple, dans la commande&nbsp;:
<programlisting>INSERT INTO a SELECT * FROM a;
</programlisting>
      les lignes insérées sont invisibles à la partie <command>SELECT</command>.
     </para>
    </listitem>

    <listitem>
     <para>
      Les modifications effectuées par une commande C sont visibles par toutes
      les commandes qui sont lancées après C, peu importe qu'elles soient
      lancées à l'intérieur de C (pendant l'exécution de C) ou après que C soit
      terminée.
     </para>
    </listitem>

    <listitem>
      <para>
        Les commandes exécutées via SPI à l'intérieur d'une fonction appelée
        par une commande SQL (soit une fonction ordinaire soit un déclencheur)
        suivent une des règles ci-dessus suivant le commutateur
        lecture/écriture passé à SPI. Les commandes exécutées en mode lecture
        seule suivent la première règle&nbsp;: elles ne peuvent pas voir
        les modifications de la commande appelante. Les commandes exécutées
        en mode lecture/écriture suivent la deuxième règle&nbsp;: elles
        peuvent voir toutes les modifications réalisées jusqu'à maintenant.
      </para>
    </listitem>

    <listitem>
      <para>
        Tous les langages standards de procédures initialisent le mode
        lecture/écriture suivant l'attribut de volatilité de la fonction.
        Les commandes des fonctions <literal>STABLE</literal> et
        <literal>IMMUTABLE</literal> sont réalisées en mode lecture seule alors que
        les fonctions <literal>VOLATILE</literal> sont réalisées en mode
        lecture/écriture. Alors que les auteurs de fonctions C sont capables
        de violer cette convention, il est peu probable que cela soit une
        bonne idée de le faire.
      </para>
    </listitem>
   </itemizedlist>
  </para>

  <para>
   La section suivante contient un exemple qui illustre
   l'application de ces règles.
  </para>
 </sect1>

 <sect1 id="spi-exemples">
  <title>Exemples</title>

  <para>
   Cette section contient un exemple très simple d'utilisation de SPI. La
   procédure <function>execq</function> prend une commande SQL comme
   premier argument et un compteur de lignes comme second, exécute la commande
   en utilisant <function>SPI_exec</function> et renvoie le nombre de lignes
   qui ont été traitées par la commande. Vous trouverez des exemples plus
   complexes pour SPI dans l'arborescence source dans
   <filename>src/test/regress/regress.c</filename> et dans le module
   <xref linkend="contrib-spi"/>.
  </para>

<programlisting>#include "postgres.h"

#include "executor/spi.h"
#include "utils/builtins.h"

#ifdef PG_MODULE_MAGIC
PG_MODULE_MAGIC;
#endif

int execq(text *sql, int cnt);

int
execq(text *sql, int cnt)
{
    char *command;
    int ret;
    int proc;

    /* Convertir l'objet texte donné en chaîne C */
    command = text_to_cstring(sql);

    SPI_connect();
    
    ret = SPI_exec(command, cnt);
    
    proc = SPI_processed;
    /*
     * Si des lignes ont été récupérées,
     * alors les afficher via elog(INFO).
     */
    if (ret &gt; 0 &amp;&amp; SPI_tuptable != NULL)
    {
        TupleDesc tupdesc = SPI_tuptable-&gt;tupdesc;
        SPITupleTable *tuptable = SPI_tuptable;
        char buf[8192];
        int i, j;
        
        for (j = 0; j &lt; proc; j++)
        {
            HeapTuple tuple = tuptable-&gt;vals[j];
            
            for (i = 1, buf[0] = 0; i &lt;= tupdesc-&gt;natts; i++)
                snprintf(buf + strlen (buf), sizeof(buf) - strlen(buf), " %s%s",
                        SPI_getvalue(tuple, tupdesc, i),
                        (i == tupdesc-&gt;natts) ? " " : " |");
            elog(INFO, "EXECQ: %s", buf);
        }
    }

    SPI_finish();
    pfree(command);

    return (proc);
}
</programlisting>

  <para>
   (Cette fonction utilisera la convention d'appel version 0 pour rendre l'exemple
   plus simple à comprendre. Dans des applications réelles, vous devriez utiliser la nouvelle
   interface version 1.)
  </para>

  <para>
   Voici comment déclarer la fonction après l'avoir compilée en
   une bibliothèque partagée (les détails sont dans <xref
   linkend="dfunc"/>)&nbsp;:

<programlisting>CREATE FUNCTION execq(text, integer) RETURNS integer
    AS '<replaceable>filename</replaceable>'
    LANGUAGE C;
</programlisting>
  </para>

  <para>
   Voici une session d'exemple&nbsp;:

<programlisting>=&gt; SELECT execq('CREATE TABLE a (x integer)', 0);
 execq
-------
     0
(1 row)

=&gt; INSERT INTO a VALUES (execq('INSERT INTO a VALUES (0)', 0));
INSERT 0 1
=&gt; SELECT execq('SELECT * FROM a', 0);
INFO:  EXECQ:  0    -- inséré par execq
INFO:  EXECQ:  1    -- retourné par execq et inséré par l'INSERT précédant

 execq
-------
     2
(1 row)

=&gt; SELECT execq('INSERT INTO a SELECT x + 2 FROM a', 1);
 execq
-------
     1
(1 row)

=&gt; SELECT execq('SELECT * FROM a', 10);
INFO:  EXECQ:  0
INFO:  EXECQ:  1
INFO:  EXECQ:  2    -- 0 + 2, une seule ligne insérée - comme spécifié

 execq
-------
     3              -- 10 est la valeur max seulement, 3 est le nombre réel de rangées
(1 row)

=&gt; DELETE FROM a;
DELETE 3
=&gt; INSERT INTO a VALUES (execq('SELECT * FROM a', 0) + 1);
INSERT 0 1
=&gt; SELECT * FROM a;
 x
---
 1                  -- aucune rangée dans a (0) + 1
(1 row)

=&gt; INSERT INTO a VALUES (execq('SELECT * FROM a', 0) + 1);
INFO:  EXECQ:  1
INSERT 0 1
=&gt; SELECT * FROM a;
 x
---
 1
 2                  -- il y a une rangée dans a + 1
(2 rows)

-- Ceci montre la règle de visibilité de modifications de données :

=&gt; INSERT INTO a SELECT execq('SELECT * FROM a', 0) * x FROM a;
INFO:  EXECQ:  1
INFO:  EXECQ:  2
INFO:  EXECQ:  1
INFO:  EXECQ:  2
INFO:  EXECQ:  2
INSERT 0 2
=&gt; SELECT * FROM a;
 x
---
 1
 2
 2                  -- 2 rangées * 1 (x dans la première rangée)
 6                  -- 3 rangées (2 + 1 juste insérée) * 2 (x dans la deuxième rangée)
(4 rows)                 ^^^^^^^
                         rangées visible à execq() dans des invocations différentes
</programlisting>
  </para>
 </sect1>
</chapter>