plpgsql.xml

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

<chapter id="plpgsql"> 
  <title><application>PL/pgSQL</application> - Langage de procédures <acronym>SQL</acronym></title>

 <indexterm zone="plpgsql">
  <primary>PL/pgSQL</primary>
 </indexterm>

 <sect1 id="plpgsql-overview">
  <title>Aperçu</title>

 <para>
  <application>PL/pgSQL</application> est un langage de procédures chargeable
  pour le système de bases de données <productname>PostgreSQL</productname>.
  Les objectifs de la conception de <application>PL/pgSQL</application> ont été de
  créer un langage de procédures chargeable qui 

    <itemizedlist>
     <listitem>
      <para>
       est utilisé pour créer des fonctions standards et triggers,
      </para>
     </listitem>
     <listitem>
      <para>
       ajoute des structures de contrôle au langage <acronym>SQL</acronym>,
      </para>
     </listitem>
     <listitem>
      <para>
       permet d'effectuer des traitements complexes,
      </para>
     </listitem>
     <listitem>
      <para>
       hérite de tous les types, fonctions et opérateurs définis par les
       utilisateurs,
      </para>
     </listitem>
     <listitem>
      <para>
       est défini comme digne de confiance par le serveur,
      </para>
     </listitem>
     <listitem>
      <para>
       est facile à utiliser.
      </para>
     </listitem>
    </itemizedlist>
   </para>

    <para>
     Les fonctions <application>PL/pgSQL</application> acceptent un nombre
     variable d'arguments en utilisant le marqueur <literal>VARIADIC</literal>.
     Cela fonctionne exactement de la même façon pour les fonctions SQL, comme
     indiqué dans <xref linkend="xfunc-sql-variadic-functions"/>.
    </para>

   <para>
    Les fonctions écrites en <application>PL/pgSQL</application> peuvent être
    utilisées partout où une fonction intégrée peut l'être.
    Par exemple, il est possible de créer des fonctions complexes de traitement
    conditionnel et, par la suite, de les utiliser pour définir des opérateurs
    ou de les utiliser dans des expressions d'index.
   </para>

  <sect2 id="plpgsql-advantages">
   <title>Avantages de l'utilisation de <application>PL/pgSQL</application></title>

    <para>
     <acronym>SQL</acronym> est le langage que <productname>PostgreSQL</productname>
     et la plupart des autres bases de données relationnelles utilisent comme
     langage de requête. Il est portable et facile à apprendre, mais chaque
     expression <acronym>SQL</acronym> doit être exécutée individuellement
     par le serveur de bases de données.
    </para>

    <para>
     Cela signifie que votre application client doit envoyer chaque requête 
     au serveur de bases de données, attendre que celui-ci la traite, recevoir
     et traiter les résultats, faire quelques calculs, et enfin envoyer d'autres requêtes
     au serveur. Tout ceci induit des communications interprocessus et induit aussi 
     une surcharge du réseau si votre client est sur une machine différente
     du serveur de bases de données.
    </para>

    <para>
     Grâce à <application>PL/pgSQL</application> vous pouvez grouper un bloc
     de traitement et une série de requêtes <emphasis>au sein</emphasis> du
     serveur de bases de données, et bénéficier ainsi de la puissance d'un
     langage de procédures, mais avec de gros gains en terme de communication
     client/serveur.
    </para>

    <itemizedlist>

     <listitem><para>Les allers/retours entre le
     client et le serveur sont éliminés</para></listitem>

     <listitem><para>Il n'est pas nécessaire de traiter ou transférer entre le
     client et le serveur les résultats intermédiaires dont le client n'a pas
     besoin</para></listitem>

     <listitem><para>Les va-et-vient des analyses de requêtes peuvent être
      évités</para></listitem>

    </itemizedlist>

    <para>
     Ceci a pour résultat une augmentation considérable des performances
     en comparaison à une application qui n'utilise pas les procédures stockées.
    </para>

    <para>
     Ainsi, avec <application>PL/pgSQL</application> vous pouvez utiliser tous les 
     types de données, opérateurs et fonctions du SQL.
    </para>
  </sect2>

  <sect2 id="plpgsql-args-results">
   <title>Arguments supportés et types de données résultats</title>

    <para>
     Les fonctions écrites en <application>PL/pgSQL</application> peuvent accepter
     en argument n'importe quel type de données supporté par le serveur, et 
     peuvent renvoyer un résultat de n'importe lequel de ces types. Elles peuvent
     aussi accepter ou renvoyer n'importe quel type composite (type ligne) spécifié
     par nom. Il est aussi possible de déclarer une fonction 
     <application>PL/pgSQL</application> renvoyant un type <type>record</type>, 
     signifiant que le résultat est un type ligne dont les colonnes sont déterminées
     par spécification dans la requête appelante (voir la
     <xref linkend="queries-tablefunctions"/>).
    </para>

    <para>
     Les fonctions <application>PL/pgSQL</application> acceptent en entrée et
     en sortie les types polymorphes <type>anyelement</type>,
     <type>anyarray</type>, <type>anynonarray</type> et <type>anyenum</type>.
     Le type de données réel géré par une fonction polymorphe peut varier
     d'appel en appel (voir la <xref linkend="extend-types-polymorphic"/>).
     Voir l'exemple de la <xref linkend="plpgsql-declaration-aliases"/>.
    </para>

    <para>
     Les fonctions <application>PL/pgSQL</application> peuvent aussi renvoyer
     un ensemble de lignes (ou une table) de n'importe lequel des type de
	 données dont les fonctions peuvent renvoyer une instance unique. Ces
     fonctions génèrent leur sortie en exécutant <literal>RETURN NEXT</literal> 
     pour chaque élément désiré de l'ensemble résultat ou en utilisant
     <command>RETURN QUERY</command> pour afficher le résultat de l'évaluation
     d'une requête.
    </para>

    <para>
     Enfin, une fonction <application>PL/pgSQL</application> peut être déclarée comme renvoyant 
     <type>void</type> si elle n'a pas de valeur de retour utile.
    </para>

    <para>
     Les fonctions <application>PL/pgSQL</application> peuvent aussi être déclarées
     avec des paramètres en sortie à la place de la spécification explicite
     du code de retour. Ceci n'ajoute pas de fonctionnalité fondamentale au
     langage mais c'est un moyen agréable principalement pour renvoyer
     plusieurs valeurs.
     La notation <literal>RETURNS TABLE</literal> peut aussi être utilisé à la
     place de <literal>RETURNS SETOF</literal>.
    </para>

    <para>
     Des exemples spécifiques apparaissent dans la
     <xref linkend="plpgsql-declaration-aliases"/> et la
     <xref linkend="plpgsql-statements-returning"/>.
    </para>
  </sect2>
 </sect1>

 <sect1 id="plpgsql-structure">
  <title>Structure de <application>PL/pgSQL</application></title>

  <para>
   <application>PL/pgSQL</application> est un langage structuré en blocs.
   Le texte complet de la définition d'une fonction doit être un 
   <firstterm>bloc</firstterm>. Un bloc est défini comme&nbsp;: 

<synopsis><optional> &lt;&lt;<replaceable>label</replaceable>&gt;&gt; </optional>
<optional> DECLARE
    <replaceable>déclarations</replaceable> </optional>
BEGIN
    <replaceable>instructions</replaceable>
END <optional> <replaceable>label</replaceable> </optional>;
</synopsis>
    </para>

    <para>
     Chaque déclaration et chaque expression au sein du bloc est terminé par un
     point-virgule. Un bloc qui apparaît à l'intérieur d'un autre bloc doit avoir
     un point-virgule après <literal>END</literal> (voir l'exemple ci-dessus)&nbsp;;
     néanmoins, le <literal>END</literal> final qui conclut le corps d'une fonction
     n'a pas besoin de point-virgule.
    </para>

    <tip>
     <para>
      Une erreur habituelle est d'écrire un point-virgule immédiatement
      après <literal>BEGIN</literal>. C'est incorrect et a comme résultat
      une erreur de syntaxe.
     </para>
    </tip>

    <para>
     Un <replaceable>label</replaceable> est seulement nécessaire si vous voulez
     identifier le bloc à utiliser dans une instruction <literal>EXIT</literal>
     ou pour qualifier les noms de variable déclarées dans le bloc. Si un label
     est écrit après <literal>END</literal>, il doit correspondre au label donné
     au début du bloc.
    </para>

    <para>
     Tous les mots clés sont insensibles à la casse. Les identifiants sont
     convertis implicitement en minuscule sauf dans le cas de l'utilisation
     de guillemets doubles. Le comportement est donc identique à celui des
     commandes SQL habituelles.
    </para>

    <para>
     Il y a deux types de commentaires dans <application>PL/pgSQL</application>. Un double
     tiret (<literal>--</literal>) débute une ligne de commentaire qui s'étend
     jusqu'à la fin de la ligne. Un <literal>/*</literal> débute un bloc de commentaire
     qui s'étend jusqu'à la prochaine occurrence de <literal>*/</literal>.
    </para>

    <para>
     Chaque expression de la section expression d'un bloc peut être un
     <firstterm>sous-bloc</firstterm>.  Les sous-blocs peuvent être utilisés pour
     des groupements logiques ou pour situer des variables locales dans un petit groupe
     d'instructions. Les variables déclarées dans un sous-bloc masquent toute
     variable nommée de façon similaire dans les blocs externes pendant toute la durée du
     sous-bloc. Cependant, vous pouvez accéder aux variables externes si vous
     qualifiez leur nom du label de leur bloc. Par exemple&nbsp;:
<programlisting>CREATE FUNCTION une_fonction() RETURNS integer AS $$
&lt;&lt; blocexterne &gt;&gt;
DECLARE
    quantite integer := 30;
BEGIN
    RAISE NOTICE 'quantité vaut ici %', quantite;  -- affiche 30
    quantite := 50;
    --
    -- Crée un sous-bloc
    --
    DECLARE
        quantite integer := 80;
    BEGIN
        RAISE NOTICE 'quantite vaut ici %', quantite;  -- affiche 80
	RAISE NOTICE 'la quantité externe vaut ici %', blocexterne.quantite;  -- affiche 50
    END;

    RAISE NOTICE 'quantité vaut ici %', quantite;  -- affiche 50

    RETURN quantite;
END;
$$ LANGUAGE plpgsql;
</programlisting>
    </para>

    <note>
     <para>
      Il existe un bloc externe caché entourant le corps de
      toute fonction <application>PL/pgSQL</application>. Ce bloc fournit la
      déclaration des paramètres de la fonction ainsi que quelques variables
      spéciales comme <literal>FOUND</literal> (voir la
      <xref linkend="plpgsql-statements-diagnostics"/>). Le bloc externe a pour
      label le nom de la fonction. Cela a pour conséquence que les paramètres et les
      variables spéciales peuvent être qualifiés du nom de la fonction.
     </para>
    </note>

    <para>
     Il est important de ne pas confondre l'utilisation de
     <command>BEGIN</command>/<command>END</command> pour grouper les instructions dans
     <application>PL/pgSQL</application> avec les commandes pour le
     contrôle des transactions. Les <command>BEGIN</command>/<command>END</command> de
     <application>PL/pgSQL</application> ne servent qu'au groupement&nbsp;; ils ne débutent
     ni ne terminent une transaction. Les fonctions standards et les fonctions triggers
     sont toujours exécutées à l'intérieur d'une transaction établie par une
     requête extérieure &mdash; ils ne peuvent pas être utilisés pour commencer
     ou valider une transaction car ils n'auraient pas de contexte pour s'exécuter.
     Néanmoins, un bloc contenant une clause <literal>EXCEPTION</literal> forme réellement
     une sous-transaction qui peut être annulée sans affecter la transaction
     externe. Pour plus d'informations sur ce point, voir la <xref
     linkend="plpgsql-error-trapping"/>.
    </para>
  </sect1>

  <sect1 id="plpgsql-declarations">
    <title>Déclarations</title>

    <para>
     Toutes les variables utilisées dans un bloc doivent être déclarées dans la
     section déclaration du bloc. Les seules exceptions sont que la variable de
     boucle d'une boucle <literal>FOR</literal> effectuant une itération sur
     des valeurs entières est automatiquement déclarée comme variable entière
     (type integer), et de la même façon une variable de boucle
     <literal>FOR</literal> effectuant une itération sur le résultat d'un
     curseur est automatiquement déclarée comme variable de type
     record.
     </para>

    <para>
     Les variables <application>PL/pgSQL</application> peuvent être de n'importe quel type de données
     tels que <type>integer</type>, <type>varchar</type> et
     <type>char</type>.
    </para>

    <para>
     Quelques exemples de déclaration de variables&nbsp;:
<programlisting>id_utilisateur integer;
quantité numeric(5);
url varchar;
ma_ligne nom_table%ROWTYPE;
mon_champ nom_table.nom_colonne%TYPE;
une_ligne RECORD;
</programlisting>
    </para>

    <para>
     La syntaxe générale d'une déclaration de variable est&nbsp;:
<synopsis><replaceable>nom</replaceable> <optional> CONSTANT </optional> <replaceable>type</replaceable> <optional> NOT NULL </optional> <optional> { DEFAULT | := } <replaceable>expression</replaceable> </optional>;
</synopsis>
      La clause <literal>DEFAULT</literal>, si indiquée, spécifie la valeur
      initiale affectée à la variable quand on entre dans le bloc.
      Si la clause <literal>DEFAULT</literal> n'est pas indiquée, la variable
      est initialisée à la valeur <acronym>SQL</acronym> NULL.
      L'option <literal>CONSTANT</literal> empêche la modification de la
      variable, de sorte que sa valeur reste constante pour la durée du bloc.
      Si <literal>NOT NULL</literal> est spécifié, l'affectation d'une valeur
      NULL aboutira à une erreur d'exécution. Les valeurs par défaut de toutes
      les variables déclarées <literal>NOT NULL</literal> doivent être
      précisées, donc non NULL.
     </para>

     <para>
      La valeur par défaut d'une variable est évaluée et affectée à la variable
      à chaque entrée du bloc (pas seulement une fois lors de l'appel de la
      fonction). Ainsi, par exemple, l'affectation de <literal>now()</literal>
      à une variable de type  <type>timestamp</type> donnera à la variable
      l'heure de l'appel de la fonction courante, et non l'heure au moment où
      la fonction a été précompilée.
      </para>

     <para>
      Exemples&nbsp;:
<programlisting>quantité integer DEFAULT 32;
url varchar := 'http://mysite.com';
id_utilisateur CONSTANT integer := 10;
</programlisting>
     </para>

    <sect2 id="plpgsql-declaration-aliases">
     <title>Alias de paramètres de fonctions</title>

     <para>
      Les paramètres passés aux fonctions sont nommés par les identifiants 
      <literal>$1</literal>, <literal>$2</literal>,
      etc.  Éventuellement, des alias peuvent être déclarés pour les noms de paramètres
      de type <literal>$<replaceable>n</replaceable></literal> afin d'améliorer la
      lisibilité. L'alias ou l'identifiant numérique peuvent être utilisés indifféremment
      pour se référer à la valeur du paramètre.
     </para>

     <para>
      Il existe deux façons de créer un alias. La façon préférée est de donner
      un nom au paramètre dans la commande <command>CREATE FUNCTION</command>,
      par exemple&nbsp;:

<programlisting>CREATE FUNCTION taxe_ventes(sous_total real) RETURNS real AS $$
BEGIN
    RETURN sous_total * 0.06;
END;
</programlisting>
      L'autre façon, la seule disponible pour les versions antérieures à
      <productname>PostgreSQL</productname> 8.0, est de déclarer explicitement
      un alias en utilisant la syntaxe de déclaration&nbsp;:

<synopsis><replaceable>nom</replaceable> ALIAS FOR $<replaceable>n</replaceable>;
</synopsis>

      Le même exemple dans ce style ressemble à ceci&nbsp;:
<programlisting>CREATE FUNCTION taxe_ventes(real) RETURNS real AS $$
DECLARE
    sous_total ALIAS FOR $1;
BEGIN
    RETURN sous_total * 0.06;
END;
$$ LANGUAGE plpgsql;
</programlisting>
     </para>

    <note>
     <para>
      Ces deux exemples ne sont pas complètement identiques. Dans le premier cas,
      <literal>sous_total</literal> peut être référencé comme
      <literal>taxe_ventes.sous_total</literal>, alors que ce n'est pas possible
      dans le second cas. (Si nous avions attaché un label au bloc,
      <literal>sous_total</literal> aurait pu utiliser ce label à la place.)
     </para>
    </note>

     <para>
      Quelques exemples de plus&nbsp;:
<programlisting>CREATE FUNCTION instr(varchar, integer) RETURNS integer AS $$
DECLARE
    v_string ALIAS FOR $1;
    index ALIAS FOR $2;
BEGIN
    -- quelques traitements utilisant ici v_string et index
END;
$$ LANGUAGE plpgsql;


CREATE FUNCTION concat_champs_selectionnes(in_t un_nom_de_table) RETURNS text AS $$
BEGIN
    RETURN in_t.f1 || in_t.f3 || in_t.f5 || in_t.f7;
END;
$$ LANGUAGE plpgsql;
</programlisting>
     </para>

     <para>
      Quand une fonction <application>PL/pgSQL</application> est déclarée avec
      des paramètres en sortie, ces derniers se voient attribués les noms
      <literal>$<replaceable>n</replaceable></literal> et des alias optionnels
      de la même façon que les paramètres en entrée. Un paramètre en sortie est
      une variable qui commence avec la valeur NULL&nbsp;; il
      devrait se voir attribuer une valeur lors de l'exécution de la fonction.
      La valeur finale du paramètre est ce qui est renvoyée. Par exemple,
      l'exemple taxe_ventes peut s'écrire de cette façon&nbsp;:

<programlisting>CREATE FUNCTION taxe_ventes(sous_total real, OUT taxe real) AS $$
BEGIN
    taxe := sous_total * 0.06;
END;
$$ LANGUAGE plpgsql;
</programlisting>

      Notez que nous avons omis <literal>RETURNS real</literal>. Nous aurions
      pu l'inclure mais cela aurait été redondant.
     </para>

     <para>
      Les paramètres en sortie sont encore plus utiles lors du retour de
      plusieurs valeurs. Un exemple trivial est&nbsp;:

<programlisting>CREATE FUNCTION somme_n_produits(x int, y int, OUT somme int, OUT produit int) AS $$
BEGIN
    somme := x + y;
    produit := x * y;
END;
$$ LANGUAGE plpgsql;
</programlisting>

      D'après ce qui a été vu dans la <xref linkend="xfunc-output-parameters"/>,
      ceci crée réellement un type d'enregistrement anonyme pour les résultats
      de la fonction. Si une clause <literal>RETURNS</literal> est donnée, elle doit
      spécifier <literal>RETURNS record</literal>.
     </para>

     <para>
      Voici une autre façon de déclarer une fonction
      <application>PL/pgSQL</application>, cette fois avec <literal>RETURNS
      TABLE</literal>&nbsp;:

<programlisting>
CREATE FUNCTION extended_sales(p_itemno int) RETURNS TABLE(quantity int, total numeric) AS $$
BEGIN
    RETURN QUERY SELECT quantity, quantity * price FROM sales WHERE itemno = p_itemno;
END;
$$ LANGUAGE plpgsql;
</programlisting>

      C'est exactement équivalent à déclarer un ou plusieurs paramètres
      <literal>OUT</literal> et à spécifier <literal>RETURNS SETOF
      <replaceable>un_type</replaceable></literal>.
     </para>

     <para>
      Lorsque le type de retour d'une fonction <application>PL/pgSQL</application>
      est déclaré comme type polymorphe (<type>anyelement</type>,
      <type>anyarray</type>, <type>anynonarray</type> et <type>anyenum</type>), un
      paramètre spécial <literal>$0</literal> est créé.
      Son type de donnée est le type effectif de retour de la fonction, déduit d'après
      les types en entrée (voir la <xref linkend="extend-types-polymorphic"/>).
      Ceci permet à la fonction d'accéder à son type de retour réel comme on le voit ici
      avec la <xref linkend="plpgsql-declaration-type"/>.
      <literal>$0</literal> est initialisé à NULL et peut être modifié par la fonction,
      de sorte qu'il peut être utilisé pour contenir la variable de retour si besoin est,
      bien que cela ne soit pas requis. On peut aussi donner un alias à
      <literal>$0</literal>. Par exemple, cette fonction s'exécute comme un
      opérateur <literal>+</literal> pour n'importe quel type de données&nbsp;:
<programlisting>CREATE FUNCTION ajoute_trois_valeurs(v1 anyelement, v2 anyelement, v3 anyelement)
RETURNS anyelement AS $$
DECLARE
    resultat ALIAS FOR $0;
BEGIN
    resultat := v1 + v2 + v3;
    RETURN resultat;
END;
$$ LANGUAGE plpgsql;
</programlisting>
     </para>

     <para>
      Le même effet peut être obtenu en déclarant un ou plusieurs paramètres
      polymorphes en sortie de types. Dans ce
      cas, le paramètre spécial <literal>$0</literal> n'est pas utilisé&nbsp;;
      les paramètres en sortie servent ce même but. Par exemple&nbsp;:

<programlisting>CREATE FUNCTION ajoute_trois_valeurs(v1 anyelement, v2 anyelement, v3 anyelement,
                                 OUT somme anyelement)
AS $$
BEGIN
    somme := v1 + v2 + v3;
END;
$$ LANGUAGE plpgsql;
</programlisting>
     </para>
    </sect2>

  <sect2 id="plpgsql-declaration-type">
   <title>Copie de types</title>

<synopsis><replaceable>variable</replaceable>%TYPE
</synopsis>

   <para>
    <literal>%TYPE</literal> fournit le type de données d'une variable ou d'une
    colonne de table. Vous pouvez l'utiliser pour déclarer des variables qui
    contiendront des valeurs de base de données. Par exemple, disons que vous
    avez une colonne nommée <literal>id_utilisateur</literal> dans votre table
    <literal>utilisateurs</literal>. Pour déclarer une variable du même type de
    données que <literal>utilisateurs.id_utilisateur</literal>, vous pouvez
    écrire&nbsp;:
<programlisting>id_utilisateur utilisateurs.id_utilisateur%TYPE;
</programlisting>
   </para>

   <para>
    En utilisant <literal>%TYPE</literal> vous n'avez pas besoin de connaître
    le type de données de la structure à laquelle vous faites référence et, plus
    important, si le type de données de l'objet référencé change dans le futur (par
    exemple&nbsp;: vous changez le type de <literal>id_utilisateur</literal> de
    <type>integer</type> à <type>real</type>), vous pouvez ne pas avoir besoin de
    changer votre définition de fonction.
   </para>

   <para>
    <literal>%TYPE</literal> est particulièrement utile dans le cas de fonctions
    polymorphes puisque les types de données nécessaires aux variables internes
    peuvent changer d'un appel à l'autre. Des variables appropriées peuvent être 
    créées en appliquant <literal>%TYPE</literal> aux arguments de la fonction ou à
    la variable fictive de résultat.
   </para>

  </sect2>

    <sect2 id="plpgsql-declaration-rowtypes">
     <title>Types ligne</title>

<synopsis><replaceable>nom</replaceable> <replaceable>nom_table</replaceable><literal>%ROWTYPE</literal>;
<replaceable>nom</replaceable> <replaceable>nom_type_composite</replaceable>;
</synopsis>

   <para>
    Une variable de type composite est appelée variable <firstterm>ligne</firstterm> (ou 
    variable <firstterm>row-type</firstterm>). Une telle variable peut contenir une ligne entière
    de résultat de requête <command>SELECT</command> ou <command>FOR</command>, du moment
    que l'ensemble de colonnes de la requête correspond au type déclaré de la variable.
    Les champs individuels de la valeur row sont accessibles en utilisant la notation
    pointée, par exemple <literal>varligne.champ</literal>.
   </para>

   <para>
    Une variable ligne peut être déclarée de façon à avoir le même type que les lignes 
    d'une table ou d'une vue existante, en utilisant la notation
    <replaceable>nom_table</replaceable><literal>%ROWTYPE</literal>.
    Elle peut aussi être déclarée en donnant un nom de type composite. Chaque table
    ayant un type de données associé du même nom, il importe peu dans 
    <productname>PostgreSQL</productname> que vous écriviez <literal>%ROWTYPE</literal> ou pas.
    Cependant, la forme utilisant <literal>%ROWTYPE</literal> est plus portable.
   </para>

   <para>
    Les paramètres d'une fonction peuvent être des types composites 
    (lignes complètes de tables). Dans ce cas, l'identifiant correspondant
    <literal>$<replaceable>n</replaceable></literal> sera une variable ligne à partir de laquelle
    les champs peuvent être sélectionnés avec la notation pointée, par exemple <literal>$1.id_utilisateur</literal>.
   </para>

   <para>
    Seules les colonnes définies par l'utilisateur sont accessibles 
    dans une variable de type ligne, et non l'OID ou d'autres colonnes systèmes (parce que
    la ligne pourrait être issue d'une vue). Les champs du type ligne héritent des tailles
    des champs de la table ou de leur précision pour les types de données tels que
    <type>char(<replaceable>n</replaceable>)</type>.
   </para>

   <para>
    Voici un exemple d'utilisation des types composites. <structname>table1</structname>
    et <structname>table2</structname> sont des tables ayant au moins les champs
    mentionnés&nbsp;:

<programlisting>CREATE FUNCTION assemble_champs(t_ligne table1) RETURNS text AS $$
DECLARE
    t2_ligne table2%ROWTYPE;
BEGIN
    SELECT * INTO t2_ligne FROM table2 WHERE ... ;
    RETURN t_ligne.f1 || t2_ligne.f3 || t_ligne.f5 || t2_ligne.f7;
END;
$$ LANGUAGE plpgsql;

SELECT assemble_champs(t.*) FROM table1 t WHERE ... ;
</programlisting>
   </para>
  </sect2>

    <sect2 id="plpgsql-declaration-records">
     <title>Types record</title>

    <para>
<synopsis><replaceable>nom</replaceable> RECORD;
</synopsis>
    </para>

   <para>
    Les variables record sont similaires aux variables de type ligne mais n'ont
    pas de structure prédéfinie. Elles empruntent la structure effective de
    type ligne de la ligne à laquelle elles sont affectées durant une commande
    <command>SELECT</command> ou <command>FOR</command>. La sous-structure d'une
    variable record peut changer à chaque fois qu'on l'affecte. Une conséquence
    de cela est qu'elle n'a pas de sous-structure jusqu'à ce qu'elle ait été
    affectée, et toutes les tentatives pour accéder à un de ses champs
    entraînent une erreur d'exécution.
   </para>

   <para>
    Notez que <literal>RECORD</literal> n'est pas un vrai type de données mais seulement un
    paramètre fictif (placeholder). Il faut aussi réaliser que lorsqu'une fonction 
    <application>PL/pgSQL</application> est déclarée renvoyer un type <type>record</type>, 
    il ne s'agit pas tout à fait du même concept qu'une variable record, même si 
    une telle fonction peut aussi utiliser une variable record pour contenir son 
    résultat. Dans les deux cas, la structure réelle de la ligne n'est pas connue quand
    la fonction est écrite mais, dans le cas d'une fonction renvoyant un type
    <type>record</type>, la structure réelle est déterminée quand la requête appelante est
    analysée, alors qu'une variable record peut changer sa structure de ligne à la volée.
   </para>
  </sect2>

    <sect2 id="plpgsql-declaration-renaming-vars">
     <title><literal>RENAME</literal></title>

<synopsis>RENAME <replaceable>ancien nom</replaceable> TO <replaceable>nouveau nom</replaceable>;
</synopsis>

     <para>
      En utilisant la déclaration <literal>RENAME</literal>, vous pouvez changer le nom d'une variable,
      d'un record ou d'un ligne (ROW). C'est particulièrement utile si
      <varname>NEW</varname> ou <varname>OLD</varname> doivent
      être référencés par un autre nom dans une procédure trigger. Voir
      aussi <literal>ALIAS</literal>.
     </para>

     <para>
      Exemples&nbsp;:
<programlisting>RENAME id TO id_utilisateur;
RENAME cette_var TO cette_autre_var;
</programlisting>
     </para>

    <note>
    <para>
	  <literal>RENAME</literal> semble ne pas fonctionner dans <productname>PostgreSQL</productname> 7.3. Cette
	  correction est de faible priorité, <literal>ALIAS</literal> couvrant la plupart des utilisations
	  pratiques de <literal>RENAME</literal>. 
    </para>
    </note>

    </sect2>
  </sect1>

  <sect1 id="plpgsql-expressions">
  <title>Expressions</title>

    <para>
     Toutes les expressions utilisées dans les instructions
     <application>PL/pgSQL</application> sont traitées par l'exécuteur 
     <acronym>SQL</acronym> classique du serveur. En effet, une requête
     comme
<synopsis>SELECT <replaceable>expression</replaceable>
</synopsis>
     est traité par le moteur SQL principal. Bien qu'utilisant la commande
     <command>SELECT</command>, tout nom de variable
     <application>PL/pgSQL</application> est remplacé par des paramètres
     (ceci est expliqué en détail dans la <xref linkend="plpgsql-var-subst"/>).
     Cela permet au plan de requête du <command>SELECT</command> d'être
     préparé une seule fois, puis d'être réutilisé pour les évaluations
     suivantes avec différentes valeurs des variables. Du coup, ce qui arrive
     réellement à la première utilisation d'une expression est simplement
     une commande <command>PREPARE</command>. Par exemple, si nous déclarons
     deux variables de type integer, <literal>x</literal> et
     <literal>y</literal>, et que nous écrivons&nbsp;:
<programlisting>
IF x &lt; y THEN ...
</programlisting>
     ce qui se passe en arrière plan est ceci&nbsp;:
<programlisting>
PREPARE <replaceable>nom_instruction</replaceable>(integer, integer) AS SELECT $1 &lt; $2;
</programlisting>
     puis cette instruction préparée est exécutée (via <command>EXECUTE</command>)
     pour chaque exécution de l'instruction <command>IF</command>, avec les
     valeurs actuelles des variables <application>PL/pgSQL</application> fournies
     en tant que valeurs des paramètres. Le plan de requête préparé de cette
     façon est sauvegardé pour toute la durée de la connexion à la base, comme
     le décrit la <xref linkend="plpgsql-plan-caching"/>. Généralement, ces détails
     ne sont pas importants pour un utilisateur de
     <application>PL/pgSQL</application>, mais ils sont utiles à connaître
     pour diagnostiquer un problème.
    </para>
  </sect1>

  <sect1 id="plpgsql-statements">
  <title>Instructions de base</title>

   <para>
    Dans cette section ainsi que les suivantes, nous décrirons tous les types 
    d'instructions explicitement compris par 
    <application>PL/pgSQL</application>.
    Tout ce qui n'est pas reconnu comme l'un de ces types d'instruction est présumé
    être une commande SQL et est envoyé au moteur principal de bases de données pour 
    être exécutée comme décrit dans la <xref linkend="plpgsql-statements-sql-noresult"/>
    et dans la <xref linkend="plpgsql-statements-sql-onerow"/>.

   </para>
   
   <sect2 id="plpgsql-statements-assignment">
    <title>Affectation</title>

    <para>
     L'affectation d'une valeur à une variable <application>PL/pgSQL</application>
     ou à un champ row/record s'écrit ainsi&nbsp;:
<synopsis><replaceable>variable</replaceable> := <replaceable>expression</replaceable>;
</synopsis>
     Comme expliqué plus haut, l'expression dans cette instruction est évaluée au 
     moyen de la commande SQL <command>SELECT</command> envoyée au moteur principal de
     bases de données. L'expression ne doit manier qu'une seule valeur.
    </para>

    <para>
     Si le type de données du résultat de l'expression ne correspond pas au type de donnée
     de la variable, ou que la variable a une taille ou une précision 
     (comme <type>char(20)</type>), la valeur résultat sera implicitement convertie
     par l'interpréteur <application>PL/pgSQL</application> en utilisant la fonction 
     d'écriture (output-function) du type du résultat, et la fonction d'entrée
     (input-function) du type de la variable. Notez que cela peut
     conduire à des erreurs d'exécution générées par la fonction d'entrée si la forme
     de la chaîne de la valeur résultat n'est pas acceptable pour cette fonction.
     </para>

    <para>
     Exemples&nbsp;:
<programlisting>taxe := sous_total * 0.06;
mon_enregistrement.id_utilisateur := 20;
</programlisting>
    </para>
   </sect2>

   <sect2 id="plpgsql-statements-sql-noresult">
    <title>Exécuter une commande sans résultats</title>

    <para>
     Pour toute commande SQL qui ne renvoie pas de lignes, par exemple
     <command>INSERT</command> sans clause <literal>RETURNING</literal>, vous
     pouvez exécuter la commande à l'intérieur d'une fonction
     <application>PL/pgSQL</application> rien qu'en écrivant la commande.
    </para>

    <para>
     Tout nom de variable <application>PL/pgSQL</application> apparaissant
     dans le texte de la commande est remplacé par un symbole de paramètre,
     puis la valeur actuelle de la variable est fournie comme valeur du
     paramètre à l'exécution. C'est le traitement exact décrit précédemment pour
     les expressions. Pour les détails, voir la <xref
     linkend="plpgsql-var-subst"/>. Par exemple, si vous écrivez
<programlisting>DECLARE
    cle TEXT;
    delta INTEGER;
BEGIN
    ...
    UPDATE matable SET val = val + delta WHERE id = cle;
</programlisting>
      le texte de la commande envoyée par le moteur SQL ressemble à ceci&nbsp;:
<programlisting>    UPDATE matable SET val = val + $1 WHERE id = $2;
</programlisting>
      Bien que vous n'ayez pas à y penser, il est utile de le savoir pour mieux
      comprendre les messages d'erreur de syntaxe.
     </para>

    <caution>
     <para>
      <application>PL/pgSQL</application> substitutera à tout identifiant
      une variable déclarée de la fonction. Du coup, une mauvaise idée serait
      d'utiliser un nom de variable identique à celui d'une table, d'une
      colonne ou d'une fonction que vous avez besoin d'utiliser dans des
	  commandes de la fonction. Pour plus d'informations, voir la <xref linkend="plpgsql-var-subst"/>.
     </para>
    </caution>

    <para>
     Lors de l'exécution d'une commande SQL de cette façon,
     <application>PL/pgSQL</application> planifie la commande une fois et
     ré-utilise ce plan lors des prochaines exécutions, pour la durée de vie
     de la connexion. Les implications de ceci sont discutées en détail dans
     la <xref linkend="plpgsql-plan-caching"/>.
    </para>

    <para>
     Parfois, il est utile d'évaluer une expression ou une requête
     <command>SELECT</command> mais sans récupérer le résultat, par
     exemple lors de l'appel d'une fonction qui a des effets de bord
     mais dont la valeur du résultat n'est pas utile. Pour faire cela
     en <application>PL/pgSQL</application>, utilisez l'instruction
     <command>PERFORM</command>&nbsp;:

<synopsis>PERFORM <replaceable>requête</replaceable>;
</synopsis>

     Ceci exécute la <replaceable>requête</replaceable> et ne tient pas compte
     du résultat. Écrivez la <replaceable>requête</replaceable> de la même
     façon que vous écririez une commande <command>SELECT</command> mais
     remplacez le mot clé initial <command>SELECT</command> avec
     <command>PERFORM</command>.
     Les variables <application>PL/pgSQL</application> seront substituées dans
     la requête comme pour les commandes qui ne renvoient pas de résultat. Le
     plan est mis en cache de la même façon. La variable spéciale
     <literal>FOUND</literal> est configurée à true si la requête a produit
	 au moins une ligne, false dans le cas contraire (voir la
     <xref linkend="plpgsql-statements-diagnostics"/>).
    </para>

    <note>
     <para>
      Vous pourriez vous attendre à ce que l'utilisation directe de
      <command>SELECT</command> aboutisse au même résultat mais, actuellement,
      la seule façon acceptée de le faire est d'utiliser
      <command>PERFORM</command>. Une commande SQL qui peut renvoyer des lignes
      comme <command>SELECT</command> sera rejetée comme une erreur si elle
      n'a pas de clause <literal>INTO</literal>, ce qui est discuté dans la
      section suivante.
     </para>
    </note>

    <para>
     Un exemple&nbsp;:
<programlisting>PERFORM creer_vuemat('cs_session_page_requests_mv', ma_requete);
</programlisting>
    </para>
   </sect2>

   <sect2 id="plpgsql-statements-sql-onerow">
    <title>Exécuter une requête avec une seule ligne de résultats</title>

    <indexterm zone="plpgsql-statements-sql-onerow">
     <primary>SELECT INTO</primary>
     <secondary>en PL/pgSQL</secondary>
    </indexterm>

    <indexterm zone="plpgsql-statements-sql-onerow">
     <primary>RETURNING INTO</primary>
     <secondary>en PL/pgSQL</secondary>
    </indexterm>

    <para>
     Le résultat d'une commande SQL ne ramenant qu'une seule ligne (mais avec une
     ou plusieurs colonnes) peut être affecté à une variable de type record, row ou
     à une liste de variables scalaires. Ceci se fait en écrivant la commande SQL
     de base et en ajoutant une clause <literal>INTO</literal>. Par exemple,

<synopsis>SELECT <replaceable>expressions_select</replaceable> INTO <optional>STRICT</optional> <replaceable>cible</replaceable> FROM ...;
INSERT ... RETURNING <replaceable>expressions</replaceable> INTO <optional>STRICT</optional> <replaceable>cible</replaceable>;
UPDATE ... RETURNING <replaceable>expressions</replaceable> INTO <optional>STRICT</optional> <replaceable>cible</replaceable>;
DELETE ... RETURNING <replaceable>expressions</replaceable> INTO <optional>STRICT</optional> <replaceable>cible</replaceable>;
</synopsis>

     où <replaceable>cible</replaceable> peut être une variable de type record,
     row ou une liste de variables ou de champs record/row séparées par
     des virgules. Les variables <application>PL/pgSQL</application> seront
     substituées dans le reste de la requête, et le plan est mis en cache
     comme décrit ci-dessus pour les commandes qui ne renvoient pas de lignes.
     Ceci fonctionne pour <command>SELECT</command>,
     <command>INSERT</command>/<command>UPDATE</command>/<command>DELETE</command>
     avec <literal>RETURNING</literal>, et les commandes utilitaires qui renvoient
     des résultats de type rowset (comme <command>EXPLAIN</command>).
     Sauf pour la clause <literal>INTO</literal>, la commande SQL est identique
     à celle qui aurait été écrite en dehors de <application>PL/pgSQL</application>.
    </para>

   <tip>
    <para>
     Notez que cette interprétation de <command>SELECT</command> avec <literal>INTO</literal>
     est assez différente de la commande habituelle <command>SELECT INTO</command> où la
     cible <literal>INTO</literal> est une table nouvellement créée. Si vous
     voulez créer une table à partir du résultat d'un
     <command>SELECT</command> à l'intérieur d'une fonction
     <application>PL/pgSQL</application>, utilisez la syntaxe
     <command>CREATE TABLE ... AS SELECT</command>.
    </para>
   </tip>

    <para>
     Si une ligne ou une liste de variables est utilisée comme cible, les
     colonnes du résultat de la requête doivent correspondre exactement à
     la structure de la cible (nombre de champs et types de données).
     Dans le cas contraire, une erreur sera rapportée à l'exécution.
     Quand une variable record est la cible, elle se configure
     automatiquement avec le type row des colonnes du résultat de la
     requête.
    </para>

    <para>
     La clause <literal>INTO</literal> peut apparaître pratiquement partout
     dans la commande SQL. Elle est écrite soit juste avant soit juste après
     la liste d'<replaceable>expressions_select</replaceable> dans une commande
     <command>SELECT</command>, ou à la fin de la commande pour d'autres types
     de commande. Il est recommandé de suivre cette convention au cas où
     l'analyseur <application>PL/pgSQL</application> devient plus strict dans
     les versions futures.
    </para>

    <para>
     Si <literal>STRICT</literal> n'est pas spécifié dans la clause
	 <literal>INTO</literal>, alors
     <replaceable>cible</replaceable> sera configuré avec la première ligne
     renvoyée par la requête ou à NULL si la requête n'a renvoyé aucune ligne.
     (Notez que <quote>la première ligne</quote> n'est bien définie que
     si vous avez utilisé <literal>ORDER BY</literal>.) Toute ligne résultat
     après la première ligne est annulée. Vous pouvez vérifier la valeur de la
     variable spéciale <literal>FOUND</literal> (voir la
     <xref linkend="plpgsql-statements-diagnostics"/>) pour déterminer si une
     ligne a été renvoyée&nbsp;:

<programlisting>SELECT * INTO monrec FROM emp WHERE nom = mon_nom;
IF NOT FOUND THEN
    RAISE EXCEPTION 'employé % introuvable', mon_nom;
END IF;
</programlisting>

     Si l'option <literal>STRICT</literal> est indiquée, la requête doit
     renvoyer exactement une ligne. Dans le cas contraire, une erreur sera rapportée à
     l'exécution, soit <literal>NO_DATA_FOUND</literal> (aucune ligne) soit
     <literal>TOO_MANY_ROWS</literal> (plus d'une ligne). Vous pouvez utiliser
     un bloc d'exception si vous souhaitez récupérer l'erreur, par exemple&nbsp;:

<programlisting>BEGIN
    SELECT * INTO STRICT monrec FROM emp WHERE nom = mon_nom;
    EXCEPTION
        WHEN NO_DATA_FOUND THEN
            RAISE EXCEPTION 'employé % introuvable', mon_nom;
        WHEN TOO_MANY_ROWS THEN
            RAISE EXCEPTION 'employé % non unique', mon_nom;
END;
</programlisting>
     Une exécution réussie de la commande avec <literal>STRICT</literal> renvoie
     toujours true pour <literal>FOUND</literal>.
    </para>

    <para>
     Pour <command>INSERT</command>/<command>UPDATE</command>/<command>DELETE</command>
     avec <literal>RETURNING</literal>, <application>PL/pgSQL</application>
     rapporte une erreur si plus d'une ligne est renvoyée, même quand
     <literal>STRICT</literal> n'est pas spécifié. Ceci est dû au fait qu'il
     n'y a pas d'option comme <literal>ORDER BY</literal> qui pourrait
     déterminer la ligne à renvoyer.
    </para>

    <note>
     <para>
      L'option <literal>STRICT</literal> correspond au comportement du
      <command>SELECT INTO</command> d'Oracle PL/SQL et des instructions
      relatives.
     </para>
    </note>

    <para>
     Pour gérer les cas où vous avez besoin de traiter plusieurs lignes de
     résultat à partir d'une requête SQL, voir la <xref linkend="plpgsql-records-iterating"/>.
    </para>

   </sect2>

   <sect2 id="plpgsql-statements-executing-dyn">
    <title>Exécuter des commandes dynamiques</title>

    <para>
     Créer dynamique des requêtes SQL est un besoin habituel dans les fonctions
     <application>PL/pgSQL</application>, par exemple des requêtes
     qui impliquent différentes tables ou différents types de données à chaque
     fois qu'elles sont exécutées. Les tentatives normales de
     <application>PL/pgSQL</application> pour garder en cache les planifications
     des commandes (voir la <xref linkend="plpgsql-plan-caching"/>) ne
     fonctionneront pas dans de tels scénarios. Pour gérer ce type
     de problème, l'instruction <command>EXECUTE</command> est proposée&nbsp;:

<synopsis>EXECUTE <replaceable class="command">command-string</replaceable> <optional> INTO <optional>STRICT</optional> <replaceable>target</replaceable> </optional> <optional> USING <replaceable>expression</replaceable> <optional>, ...</optional> </optional>;
</synopsis>

     où <replaceable>chaîne-commande</replaceable> est une expression manipulant
     une chaîne (de type <type>text</type>) contenant la commande à exécuter.
     La <replaceable>cible</replaceable> optionnelle est une variable record ou ligne ou
     même une liste de variables simples ou de champs de lignes/enregistrements
     séparées par des virgules, dans lesquels les résultats de la commande seront
     enregistrés. Les expressions <literal>USING</literal> optionnelles fournissent
     des valeurs à insérer dans la commande.
    </para>

    <para>
     Aucune substitution des variables <application>PL/pgSQL</application> ne
     se fait dans la chaîne de commande calculée. Toutes les valeurs des
     variables requises doivent être insérées dans la chaîne de commande au
     moment de sa construction&nbsp;; ou vous pouvez utiliser des paramètres
     comme décrits ci-dessous.
    </para>

    <para>
     De plus, il n'y a pas mise en cache des commandes exécutées via
     <command>EXECUTE</command>. À la
     place, la commande est préparée à chaque fois que l'instruction est lancée.
     La chaîne commande peut être créée dynamiquement à l'intérieur de la
     fonction pour agir sur des tables ou colonnes différentes.
    </para>

    <para>
     La clause <literal>INTO</literal> spécifie où devraient être affectés les
     résultats d'une commande SQL renvoyant des lignes. Si une ligne ou une
     liste de variable est fournie, elle doit correspondre exactement à la
     structure des résultats de la requête (quand
     une variable de type record est utilisée, elle sera automatiquement typée
     pour correspondre à la structure du résultat). Si plusieurs lignes sont
     renvoyées, alors seule la première sera assignée à la variable 
     <literal>INTO</literal>. Si aucune ligne n'est renvoyée, NULL est affectée
     à la variable <literal>INTO</literal>. Si aucune clause
     <literal>INTO</literal> n'est spécifiée, les résultats de la requête sont
     ignorés.
    </para>

    <para>
     Si l'option <literal>STRICT</literal> est indiquée, une erreur est
     rapportée sauf si la requête produit exactement une ligne.
    </para>

    <para>
     La chaîne de commande peut utiliser des valeurs de paramètres, référencées
     dans la commande avec <literal>$1</literal>, <literal>$2</literal>, etc.
     Ces symboles font référence aux valeurs fournies dans la clause
     <literal>USING</literal>. Cette méthode est souvent préférable à
     l'insertion des valeurs en texte dans une chaîne de commande&nbsp;: cela
     évite la surcharge à l'exécution pour la conversion des valeurs en texte
     et vice-versa. C'est aussi moins sensible aux attaques par injection SQL
     car il n'est pas nécessaire de mettre entre guillemets ou d'échapper les
     valeurs. Voici un exemple&nbsp;:
<programlisting>
EXECUTE 'SELECT count(*) FROM matable WHERE insere_par = $1 AND insere &lt;= $2'
   INTO c
   USING utilisateur_verifie, date_verifiee;
</programlisting>

     Notez que les symboles de paramètres peuvent seulement être utilisés pour
     des valeurs de données &mdash; si vous voulez utiliser des noms de tables
     et/ou colonnes déterminés dynamiquement, vous devez les insérer dans la
     chaîne de commande en texte. Par exemple, si la requête précédente devait
     se faire avec une table sélectionnée dynamiquement, vous devriez faire
     ceci&nbsp;:
<programlisting>
EXECUTE 'SELECT count(*) FROM '
    || tabname::regclass
    || ' WHERE insere_par = $1 AND insere &lt;= $2'
   INTO c
   USING utilisateur_verifie, date_verifiee;
</programlisting>
    </para>

    <para>
     Un <command>EXECUTE</command> avec une chaîne de commande constante et des
     paramètres <literal>USING</literal>, comme dans le premier exemple
     ci-dessus, est équivalent fonctionnellement à l'écriture simple d'une
     commande directement dans <application>PL/pgSQL</application> et permet
     le remplacement automatique des variables <application>PL/pgSQL</application>.
     La différence importante est que <command>EXECUTE</command> va planifier de
     nouveau la commande pour chaque exécution, générant un plan qui est
     spécifique aux valeurs actuelles des paramètres&nbsp;; alors que
     <application>PL/pgSQL</application> crée habituellement un plan générique
     et le stocke pour le réutiliser. Dans des situations où le meilleur plan
     dépend fortement des valeurs des paramètres, <command>EXECUTE</command>
     peut être beaucoup plus rapide&nbsp;: alors que lorsque le plan n'est pas
     sensible aux valeurs des paramètres, la replanification sera une perte.
    </para>

    <para>
     <command>SELECT INTO</command> n'est actuellement pas supporté à
     l'intérieur de <command>EXECUTE</command>&nbsp;; à la place, exécutez une
     commande <command>SELECT</command> et spécifiez <literal>INTO</literal>
     comme faisant parti lui-même d'<command>EXECUTE</command>.
    </para>

   <note>
    <para>
     L'instruction <command>EXECUTE</command> de
     <application>PL/pgSQL</application> n'a pas de relation avec l'instruction
     SQL <xref linkend="sql-execute" endterm="sql-execute-title"/> supportée
     par le serveur <productname>PostgreSQL</productname>. L'instruction
     <command>EXECUTE</command> du serveur ne peut pas être utilisée directement
     dans les fonctions <application>PL/pgSQL</application>. En fait, elle n'est pas
     nécessaire.
    </para>
   </note>

   <example id="plpgsql-quote-literal-example">
   <title>Mettre entre guillemets des valeurs dans des requêtes dynamiques</title>

    <indexterm>
     <primary>quote_ident</primary>
     <secondary>utilisation dans PL/PgSQL</secondary>
    </indexterm>

    <indexterm>
     <primary>quote_literal</primary>
     <secondary>utilisation dans PL/PgSQL</secondary>
    </indexterm>

    <indexterm>
     <primary>quote_nullable</primary>
     <secondary>utilisation dans PL/PgSQL</secondary>
    </indexterm>

    <para>
     En travaillant avec des commandes dynamiques, vous aurez souvent à gérer
     des échappements de guillemets simples. La méthode recommandée pour
     mettre entre guillemets un texte fixe dans le corps de votre fonction
     est d'utiliser les guillemets dollar (si votre code n'utilise pas les
     guillemets dollar, référez-vous à l'aperçu dans la <xref
     linkend="plpgsql-quote-tips"/>, ce qui peut vous faire gagner des efforts
     lors du passage de ce code à un schéma plus raisonnable).
    </para>

    <para>
     Les valeurs dynamiques qui sont à insérer dans la requête construite
     requièrent une gestion spéciale car elles pourraient elles-même contenir
     des guillemets. Un exemple (ceci suppose que vous utilisez les guillemets
     dollar pour la fonction dans sa globalité, du coup les guillemets n'ont
     pas besoin d'être doublés)&nbsp;:
<programlisting>EXECUTE 'UPDATE tbl SET '
    || quote_ident(nom_colonne)
    || ' = '
    || quote_literal(nouvelle_valeur)
    || ' WHERE cle = '
    || quote_literal(valeur_cle);</programlisting>
    </para>

    <para>
     Cet exemple démontre l'utilisation des fonctions
     <function>quote_ident</function> et <function>quote_literal</function> (voir <xref
     linkend="functions-string"/>).
     Pour plus de sûreté, les expressions contenant
     les identifiants des colonnes et des tables doivent être passées à la
     fonction <function>quote_ident</function> avant l'insertion dans une requête
     dynamique. Les expressions contenant des
     valeurs de type chaîne de caractères doivent être
     passées à <function>quote_literal</function>. Ce sont les étapes
     appropriées pour renvoyer le texte en entrée entouré par des guillemets 
     doubles ou simples respectivement, en échappant tout caractère spécial.
    </para>

    <para>
     Comme <function>quote_literal</function> est labelisé
     <literal>STRICT</literal>, elle renverra toujours NULL lorsqu'elle est
     appelée avec un argument NULL. Dans l'exemple ci-dessus, si
     <literal>nouvelle_valeur</literal> ou <literal>valeur_clé</literal>
     étaient NULL, la requête dynamique entière deviendrait NULL, amenant une
     erreur à partir du <command>EXECUTE</command>. Vous pouvez éviter ce
     problème en utilisant la fonction <function>quote_nullable</function> qui
     fonctionne de façon identique à <function>quote_literal</function> sauf
     si elle est appelée avec un argument NULL, elle renvoie la chaîne
     <literal>NULL</literal>.
     Par exemple,
<programlisting>
EXECUTE 'UPDATE tbl SET '
        || quote_ident(nom_colonne)
        || ' = '
        || quote_nullable(nouvelle_valeur)
        || ' WHERE key = '
        || quote_nullable(valeur_clé);
</programlisting>
     Si vous travaillez avez des valeurs qui peuvent être NULL, vous devez
     utiliser <function>quote_nullable</function> à la place de
     <function>quote_literal</function>.
    </para>

    <para>
     Comme toujours, il faut s'assurer que les valeurs NULL d'une requête ne
     ramènent pas des valeurs inattendues. Par exemple, la clause
     <literal>WHERE</literal>
<programlisting>
     'WHERE key = ' || quote_nullable(valeur_clé)
</programlisting>
     ne sera jamais vrai si <literal>valeur_clé</literal> est NULL car le résultat
     de l'opérateur d'égalité, <literal>=</literal>, avec au moins un des opérandes
     NULL est toujours NULL. Si vous souhaitez que NULL fonctionne comme toute
     autre valeur de clé ordinaire, vous devez ré-écrire la clause ci-dessus de
     cette façon&nbsp;:
<programlisting>
     'WHERE key IS NOT DISTINCT FROM ' || quote_nullable(keyvalue)
</programlisting>
     (Actuellement, <literal>IS NOT DISTINCT FROM</literal> est géré moins
     efficacement que <literal>=</literal>, donc ne l'utilisez pas sauf en cas
     d'extrême nécessité. Voir <xref linkend="functions-comparison"/> pour plus
     d'informations sur les NULL et <literal>IS DISTINCT</literal>.)
    </para>

    <para>
     Notez que les guillemets dollar sont souvent utiles pour placer un texte
     fixe entre guillemets. Ce serait une très mauvaise idée d'écrire l'exemple
     ci-dessus de cette façon&nbsp;:
    <programlisting>    EXECUTE 'UPDATE tbl SET '
    || quote_ident(nom_colonne)
    || ' = $$'
    || nouvelle_valeur
    || '$$ WHERE cle = '
    || quote_literal(valeur_cle);</programlisting>
     car cela casserait si le contenu de <literal>nouvelle_valeur</literal> pouvait contenir
     <literal>$$</literal>. La même objection s'applique à tout délimiteur dollar
     que vous pourriez choisir. Donc, pour mettre un texte inconnu entre
     guillemets de façon sûr, vous <emphasis>devez</emphasis> utiliser
     <function>quote_literal</function>,
     <function>quote_nullable</function> ou <function>quote_ident</function>,
     comme approprié.
    </para>
   </example>

    <para>
     Un exemple bien plus important d'une commande dynamique et
     d'<command>EXECUTE</command> est disponible dans l'<xref
     linkend="plpgsql-porting-ex2"/>, qui construit et exécute une commande
     <command>CREATE FUNCTION</command> pour définir une nouvelle fonction.
    </para>
   </sect2>

   <sect2 id="plpgsql-statements-diagnostics">
    <title>Obtention du statut du résultat</title>

    <para>
	 Il y a plusieurs moyens pour déterminer l'effet d'une commande. La première méthode
	 est d'utiliser <command>GET DIAGNOSTICS</command>&nbsp;:

<synopsis>GET DIAGNOSTICS <replaceable>variable</replaceable> = <replaceable>élément</replaceable> <optional> , ... </optional> ;
</synopsis>

     Cette commande permet la récupération des indicateurs d'état du système. Chaque
     <replaceable>élément</replaceable> est un mot clé identifiant une valeur d'état devant
     être affectée à la variable indiquée (qui doit être du bon type de donnée 
     pour que l'affectation puisse se faire sans erreur.) Les éléments d'état actuellement disponibles sont
     <varname>ROW_COUNT</varname>, le nombre de lignes traitées par la dernière commande
     <acronym>SQL</acronym> envoyée au moteur <acronym>SQL</acronym>, et 
     <varname>RESULT_OID</varname>, l'OID de la dernière ligne insérée par la commande 
     <acronym>SQL</acronym> la plus récente.  Notez que <varname>RESULT_OID</varname>
     n'est utile qu'après une commande <command>INSERT</command> dans une table
     contenant des OID.
    </para>

    <para>
     Exemple&nbsp;:
<programlisting>GET DIAGNOSTICS var_entier = ROW_COUNT;
</programlisting>
    </para>

    <para>
     La seconde méthode permettant de déterminer les effets d'une commande est la variable 
     spéciale nommée <literal>FOUND</literal>  de type <type>boolean</type>.  
     La variable <literal>FOUND</literal> est initialisée à false au début de chaque fonction 
     <application>PL/pgSQL</application>. Elle est positionnée par chacun des types
     d'instructions suivants&nbsp;:
	 <itemizedlist>
	  <listitem>
	   <para>
		Une instruction <command>SELECT INTO</command> positionne
		<literal>FOUND</literal> à true si une ligne est affectée, false
		si aucune ligne n'est renvoyée.
	   </para>
	  </listitem>
	  <listitem>
	   <para>
		Une instruction <command>PERFORM</command> positionne <literal>FOUND</literal>
		à true si elle renvoie une ou plusieurs lignes, false si aucune ligne n'est
		produite.
	   </para>
	  </listitem>
	  <listitem>
	   <para>
		Les instructions <command>UPDATE</command>, <command>INSERT</command>, et
		<command>DELETE</command> positionnent  <literal>FOUND</literal> à true 
		si au moins une ligne est affectée, false si aucune ligne n'est affectée.
	   </para>
	  </listitem>
	  <listitem>
	   <para>
		Une instruction <command>FETCH</command> positionne <literal>FOUND</literal>
		à true si elle renvoie une ligne, false si aucune ligne n'est renvoyée.
	   </para>
	  </listitem>
          <listitem>
           <para>
                Une instruction <command>MOVE</command> initialise
		<literal>FOUND</literal> à true si elle repositionne le curseur
		avec succès. Dans le cas contraire, elle le positionne à false.
           </para>
          </listitem>
	  <listitem>
	   <para>
		La commande <command>FOR</command> positionne <literal>FOUND</literal> à true
		si elle effectue une itération une ou plusieurs fois, sinon elle renvoie
		false. Ceci s'applique aux quatre variantes de l'instruction 
		<command>FOR</command> (boucles <command>FOR</command> integer,
		boucles <command>FOR</command> sur des ensembles d'enregistrements,
		boucles <command>FOR</command> sur des ensembles d'enregistrements
		dynamiques et boucles <command>FOR</command> sur des curseurs).
		<literal>FOUND</literal>
		n'est positionnée de cette façon que quand la boucle <command>FOR</command>
		s'achève&nbsp;;
		dans l'exécution de la chaîne, <literal>FOUND</literal> 
		n'est pas modifiée par l'instruction <command>FOR</command>, bien qu'elle 
		puisse être modifié par l'exécution d'autres instructions situées
		dans le corps de la boucle.
	   </para>
	  </listitem>
          <listitem>
           <para>
            Les instructions <command>RETURN QUERY</command> et <command>RETURN
	    QUERY EXECUTE</command> mettent à jour la variable <literal>FOUND</literal>
            à true si la requête renvoie au moins une ligne, et false si aucune
	    ligne n'est renvoyée.
           </para>
          </listitem>
	 </itemizedlist>
	 
     <literal>FOUND</literal> est une variable locale à l'intérieur de chaque
     fonction <application>PL/pgSQL</application>&nbsp;; chaque changement qui
     y est fait n'affecte que la fonction en cours.
    </para>

   </sect2>

   <sect2 id="plpgsql-statements-null">
     <title>Ne rien faire du tout</title>

     <para>
	Quelque fois, une instruction qui ne fait rien est utile. Par exemple,
	elle indique qu'une partie de la chaîne <command>IF</command>/<command>THEN</command>/<command>ELSE</command> est délibérément
	vide. Pour cela, utilisez l'instruction&nbsp;:

       <synopsis>NULL;</synopsis>
     </para>

     <para>
       Par exemple, les deux fragments de code suivants sont équivalents&nbsp;:
       <programlisting>BEGIN
  y := x / 0;
  EXCEPTION
  WHEN division_by_zero THEN
    NULL;  -- ignore l'erreur
  END;</programlisting>

       <programlisting>BEGIN
  y := x / 0;
  EXCEPTION
  WHEN division_by_zero THEN  -- ignore l'erreur
  END;</programlisting>
       Ce qui est préférable est une question de goût.
     </para>

     <note>
       <para>
         Dans le PL/SQL d'Oracle, les listes d'instructions vides ne sont pas
	 autorisées et, du coup, les instructions <command>NULL</command> sont
	 <emphasis>requises</emphasis> dans les situations telles que celles-ci.
	<application>PL/pgSQL</application> vous permet d'écrire simplement
	rien.
   </para>
   </note>

   </sect2>
  </sect1> 
  <sect1 id="plpgsql-control-structures">
   <title>Structures de contrôle</title>

   <para>
    Les structures de contrôle sont probablement la partie la plus utile (et importante)
    de <application>PL/pgSQL</application>. Grâce aux structures de contrôle de
    <application>PL/pgSQL</application>, vous pouvez manipuler les données 
    <productname>PostgreSQL</productname> de façon très flexible et puissante.
   </para>
   
   <sect2 id="plpgsql-statements-returning">
    <title>Retour d'une fonction</title>

    <para>
     Il y a deux commandes disponibles qui vous permettent de renvoyer des données
     d'une fonction&nbsp;: <command>RETURN</command> et <command>RETURN
     NEXT</command>.
    </para>

    <sect3>
     <title><command>RETURN</command></title>

<synopsis>RETURN <replaceable>expression</replaceable>;
</synopsis>

     <para>
      <command>RETURN</command> accompagné d'une expression termine la fonction et 
      renvoie le valeur de l'<replaceable>expression</replaceable> à l'appelant.
      Cette forme est à utiliser avec des fonctions <application>PL/pgSQL</application>
      qui ne renvoient pas d'ensemble de valeurs.
     </para>

     <para>
      Lorsqu'elle renvoie un type scalaire, n'importe quelle expression peut être 
      utilisée. Le résultat de l'expression sera automatiquement converti vers le type
      de retour de la fonction, comme décrit pour les affectations. Pour renvoyer une 
      valeur composite (ligne), vous devez écrire une variable record ou ligne comme 
      <replaceable>expression</replaceable>.
     </para>

     <para>
      Si vous déclarez la fonction avec des paramètres en sortie, écrivez
      seulement <command>RETURN</command> sans expression. Les valeurs
      courantes des paramètres en sortie seront renvoyées.
     </para>

     <para>
      Si vous déclarez que la fonction renvoie <type>void</type>, une
      instruction <command>RETURN</command> peut être utilisée pour quitter
      rapidement la fonction&nbsp;; mais n'écrivez pas d'expression après
      <command>RETURN</command>.
     </para>

     <para>
      La valeur de retour d'une fonction ne peut pas être laissée indéfinie.
      Si le contrôle atteint la fin du bloc de haut niveau de la fonction,
      sans parvenir à une instruction <command>RETURN</command>, une erreur
      d'exécution survient. Néanmoins, cette restriction ne s'applique pas
      aux fonctions sans paramètre de sortie et aux fonctions renvoyant 
      <type>void</type>. Dans ces cas, une instruction
      <command>RETURN</command> est automatiquement exécutée si le bloc de
      haut niveau est terminé.
     </para>
    </sect3>

    <sect3>
     <title><command>RETURN NEXT</command> et <command>RETURN QUERY</command></title>
    <indexterm>
     <primary>RETURN NEXT</primary>
     <secondary>dans PL/PgSQL</secondary>
    </indexterm>
    <indexterm>
     <primary>RETURN QUERY</primary>
     <secondary>dans PL/PgSQL</secondary>
    </indexterm>

<synopsis>
RETURN NEXT <replaceable>expression</replaceable>;
RETURN QUERY <replaceable>requete</replaceable>;
RETURN QUERY EXECUTE <replaceable class="command">command-string</replaceable> <optional> USING <replaceable>expression</replaceable> <optional>, ...</optional> </optional>;
</synopsis>

     <para>
      Quand une fonction <application>PL/pgSQL</application> déclare renvoyer
      <literal>SETOF <replaceable>un_certain_type</replaceable></literal>, la
      procédure à suivre est un peu différente. Dans ce cas, les éléments
      individuels à renvoyer sont spécifiés par une séquence de commandes
      <command>RETURN NEXT</command> ou <command>RETURN QUERY</command>, suivies
      de la commande finale <command>RETURN</command> sans argument qui est
      utilisée pour indiquer la fin de l'exécution de la fonction.
      <command>RETURN NEXT</command> peut être utilisé avec des types de données
      scalaires comme composites&nbsp;; avec un type de résultat composite, une
      <quote>table</quote> entière de résultats sera renvoyée.
      <command>RETURN QUERY</command> ajoute les résultats de l'exécution d'une
      requête à l'ensemble des résultats de la fonction. <command>RETURN
      NEXT</command> et <command>RETURN QUERY</command> peuvent être
      utilisés dans la même fonction, auquel cas leurs résultats seront
      concaténées.
     </para>

     <para>
      <command>RETURN NEXT</command> et <command>RETURN
      QUERY</command> ne quittent pas réellement la fonction &mdash; elles
      ajoutent simplement zéro ou plusieurs lignes à l'ensemble de résultats
      de la fonction. L'exécution continue ensuite avec l'instruction
      suivante de la fonction <application>PL/pgSQL</application>. Quand
      plusieurs commandes <command>RETURN NEXT</command> et/ou <command>RETURN
      QUERY</command> successives sont exécutées, l'ensemble de résultats
      augmente. Un <command>RETURN</command>, sans argument, permet
      de quitter la fonction mais vous pouvez aussi continuer jusqu'à la fin
      de la fonction.
     </para>

     <para>
      <command>RETURN QUERY</command> dispose d'une variante
      <command>RETURN QUERY EXECUTE</command>, qui spécifie la requête à exécuter
      dynamiquement. Les expressions de paramètres peuvent être insérées dans
      la chaîne calculée via <literal>USING</literal>, de la même façon que le
      fait la commande <command>EXECUTE</command>.
     </para>

     <para>
      Si vous déclarez la fonction avec des paramètres en sortie, écrivez
      <command>RETURN NEXT</command> sans expression. À chaque exécution,
      les valeurs actuelles des variables paramètres en sortie seront
      sauvegardées pour un renvoi éventuel en tant que résultat en sortie.
      Notez que vous devez déclarer la fonction en tant que
      <literal>SETOF record</literal> quand il y a plusieurs paramètres en
      sortie, ou <literal>SETOF <replaceable>un_certain_type</replaceable></literal>
      quand il y a un seul paramètre en sortie, et de type 
      <replaceable>un_certain_type</replaceable>, pour créer une fonction SRF
      avec des paramètres en sortie.
     </para>

     <para>
      Voici un exemple d'une fonction utilisant <command>RETURN
      NEXT</command>&nbsp;:

<programlisting>
CREATE TABLE truc (id_truc INT, sousid_truc INT, nom_truc TEXT);
INSERT INTO truc VALUES (1, 2, 'trois');
INSERT INTO truc VALUES (4, 5, 'six');

CREATE OR REPLACE FUNCTION obtenirTousLesTrucs() RETURNS SETOF foo AS
$BODY$
DECLARE
    r truc%rowtype;
BEGIN
    FOR r IN SELECT * FROM truc
    WHERE id_truc &gt; 0
    LOOP
        -- quelques traitements
        RETURN NEXT r; -- renvoie la ligne courante du SELECT
    END LOOP;
    RETURN;
END
$BODY$
LANGUAGE 'plpgsql' ;

SELECT * FROM obtenirTousLesTrucs();
</programlisting>
     </para>

     <note>
      <para>
       L'implémentation actuelle de <command>RETURN NEXT</command> et de
       <command>RETURN QUERY</command> pour
       <application>PL/pgSQL</application> récupère la totalité de l'ensemble des
       résultats avant 
       d'effectuer le retour de la fonction, comme vu plus haut. Cela signifie que
       si une fonction <application>PL/pgSQL</application> produit une structure résultat
       très grande, les performances peuvent être faibles&nbsp;: les données seront
       écrites sur le disque pour éviter un épuisement de la mémoire mais la fonction
       en elle-même ne renverra rien jusqu'à ce que l'ensemble complet des résultats
       soit généré. Une version future de  <application>PL/pgSQL</application>
       permettra aux utilisateurs de définir des fonctions renvoyant des ensembles qui
       n'auront pas cette limitation. Actuellement, le point auquel les données commencent
       à être écrites sur le disque est contrôlé par la variable de configuration 
       <xref linkend="guc-work-mem"/>. Les administrateurs
       ayant une mémoire suffisante pour enregistrer des ensembles de résultats
       plus importants en mémoire doivent envisager l'augmentation de ce
       paramètre.
      </para>
     </note>
    </sect3>
   </sect2>

   <sect2 id="plpgsql-conditionals">
    <title>Contrôles conditionnels</title>

    <para>
     Les instructions <command>IF</command> et <command>CASE</command> vous permettent d'exécuter des commandes
     basées sur certaines conditions. <application>PL/pgSQL</application> a trois formes de
     <literal>IF</literal>&nbsp;:
    <itemizedlist>
     <listitem>
      <para><literal>IF ... THEN</literal></para>
     </listitem>
     <listitem>
      <para><literal>IF ... THEN ... ELSE</literal></para>
     </listitem>
     <listitem>
      <para><literal>IF ... THEN ... ELSIF ... THEN ... ELSE</literal></para>
     </listitem>
    </itemizedlist>

    et deux formes de <command>CASE</command>&nbsp;:
    <itemizedlist>
     <listitem>
      <para><literal>CASE ... WHEN ... THEN ... ELSE ... END CASE</literal></para>
     </listitem>
     <listitem>
      <para><literal>CASE WHEN ... THEN ... ELSE ... END CASE</literal></para>
     </listitem>
    </itemizedlist>
    </para>

    <sect3>
     <title><literal>IF-THEN</literal></title>

<synopsis>IF <replaceable>expression-booleenne</replaceable> THEN
    <replaceable>instructions</replaceable>
END IF;
</synopsis>

       <para>
        Les instructions <literal>IF-THEN</literal> sont la forme la plus simple de 
	<literal>IF</literal>. Les instructions entre <literal>THEN</literal> et 
	<literal>END IF</literal> seront exécutées si la condition est vraie. Autrement,
	elles seront ignorées.
       </para>

       <para>
        Exemple&nbsp;:
<programlisting>IF v_id_utilisateur &lt;&gt; 0 THEN
    UPDATE utilisateurs SET email = v_email WHERE id_utilisateur = v_id_utilisateur;
END IF;
</programlisting>
       </para>
     </sect3>

     <sect3>
      <title><literal>IF-THEN-ELSE</literal></title>

<synopsis>IF <replaceable>expression-booleenne</replaceable> THEN
    <replaceable>instructions</replaceable>
ELSE
    <replaceable>instructions</replaceable>
END IF;
</synopsis>

       <para>
        Les instructions <literal>IF-THEN-ELSE</literal> s'ajoutent au
        <literal>IF-THEN</literal> en vous permettant de spécifier un autre ensemble
	d'instructions à exécuter si la condition n'est pas vraie (notez que ceci
	inclut le cas où la condition s'évalue à NULL.).
	</para>

       <para>
        Exemples&nbsp;:
<programlisting>IF id_parent IS NULL OR id_parent = ''
THEN
    RETURN nom_complet;
ELSE
    RETURN hp_true_filename(id_parent) || '/' || nom_complet;
END IF;
</programlisting>

<programlisting>IF v_nombre &gt; 0 THEN 
    INSERT INTO nombre_utilisateurs (nombre) VALUES (v_nombre);
    RETURN 't';
ELSE
    RETURN 'f';
END IF;
</programlisting>
     </para>
    </sect3>

     <sect3>
      <title><literal>IF-THEN-ELSIF</literal></title>

<synopsis>IF <replaceable>expression-booleenne</replaceable> THEN
    <replaceable>instructions</replaceable>
<optional> ELSIF <replaceable>expression-booleenne</replaceable> THEN
    <replaceable>instructions</replaceable>
<optional> ELSIF <replaceable>expression-booleenne</replaceable> THEN
    <replaceable>instructions</replaceable>
    ...
</optional>
</optional>
<optional> ELSE
    <replaceable>instructions</replaceable> </optional>
END IF;
</synopsis>

       <para>
        Quelques fois, il existe plus de deux alternatives.
        <literal>IF-THEN-ELSIF</literal> fournit une méthode agréable pour
	vérifier différentes alternatives. Les conditions
	<literal>IF</literal> sont testées successivement jusqu'à trouver la
	bonne. Alors les instructions associées sont exécutées, puis le
	contrôle est passé à la prochaine instruction après <literal>END
	IF</literal>. (Toute autre condition <literal>IF</literal> n'est
        <emphasis>pas</emphasis> testée.) Si aucune des conditions
        <literal>IF</literal> n'est vraie, alors le bloc
	<literal>ELSE</literal> (s'il y en a un) est exécuté.
       </para>

       <para>
        Voici un exemple&nbsp;: 

<programlisting>IF nombre = 0 THEN
    resultat := 'zero';
ELSIF nombre &gt; 0 THEN 
    resultat := 'positif';
ELSIF nombre &lt; 0 THEN
    resultat := 'negatif';
ELSE
    -- hmm, la seule possibilité est que le nombre soit NULL
    resultat := 'NULL';
END IF;
</programlisting>
       </para>

       <para>
        Le mot clé <literal>ELSIF</literal> peut aussi s'écrire
        <literal>ELSEIF</literal>.
       </para>

       <para>
        Une façon alternative d'accomplir la même tâche est d'intégrer les
	instructions <literal>IF-THEN-ELSE</literal>, comme dans l'exemple
        suivant&nbsp;:

<programlisting>
IF demo_row.sex = 'm' THEN
    pretty_sex := 'man';
ELSE
    IF demo_row.sex = 'f' THEN
        pretty_sex := 'woman';
    END IF;
END IF;
</programlisting>
       </para>

       <para>
        Néanmoins, cette méthode requiert d'écrire un <literal>END
        IF</literal> pour chaque <literal>IF</literal>, donc c'est un peu plus
	compliqué que d'utiliser <literal>ELSIF</literal> quand il y a beaucoup
	d'autres alternatives.
       </para>
     </sect3>

     <sect3>
      <title><literal>CASE</literal> simple</title>

<synopsis>
CASE <replaceable>expression_recherche</replaceable>
    WHEN <replaceable>expression</replaceable> <optional>, <replaceable>expression</replaceable> <optional> ... </optional></optional> THEN
      <replaceable>instructions</replaceable>
  <optional> WHEN <replaceable>expression</replaceable> <optional>, <replaceable>expression</replaceable> <optional> ... </optional></optional> THEN
      <replaceable>instructions</replaceable>
    ... </optional>
  <optional> ELSE
      <replaceable>instructions</replaceable> </optional>
END CASE;
</synopsis>

      <para>
       La forme simple de <command>CASE</command> fournit une exécution
       conditionnelle basée sur l'égalité des opérandes.
       L'<replaceable>expression-recherche</replaceable> est évaluée (une fois)
       puis comparée successivement à chaque <replaceable>expression</replaceable>
       dans les clauses <literal>WHEN</literal>. Si une correspondance est
       trouvée, alors les <replaceable>instructions</replaceable> correspondantes
       sont exécutées, puis le contrôle est passé à la prochaine instruction
       après <literal>END CASE</literal>. (Les autres expressions
       <literal>WHEN</literal> ne sont pas testées.) Si aucune correspondance
       n'est trouvée, les <replaceable>instructions</replaceable> du bloc
       <literal>ELSE</literal> sont exécutées&nbsp;; s'il n'y a pas de bloc
       <literal>ELSE</literal>, une exception <literal>CASE_NOT_FOUND</literal>
       est levée.
      </para>

      <para>
       Voici un exemple simple&nbsp;:

<programlisting>
CASE x
    WHEN 1, 2 THEN
        msg := 'un ou deux';
    ELSE
        msg := 'autre valeur que un ou deux';
END CASE;
</programlisting>
      </para>
     </sect3>

     <sect3>
      <title><literal>CASE</literal> recherché</title>

<synopsis>
CASE
    WHEN <replaceable>expression_booléenne</replaceable> THEN
      <replaceable>instructions</replaceable>
  <optional> WHEN <replaceable>expression_booléenne</replaceable> THEN
      <replaceable>instructions</replaceable>
    ... </optional>
  <optional> ELSE
      <replaceable>instructions</replaceable> </optional>
END CASE;
</synopsis>

      <para>
       La forme recherché de <command>CASE</command> fournit une exécution
       conditionnelle basée sur la vérification d'expressions booléennes.
       Chaque <replaceable>expression-booléenne</replaceable> de la clause
       <literal>WHEN</literal> est évaluée à son tour jusqu'à en trouver
       une qui est validée (<literal>true</literal>). Les
       <replaceable>instructions</replaceable> correspondantes sont exécutées,
       puis le contrôle est passé à la prochaine instruction après <literal>END
       CASE</literal>. (Les expressions <literal>WHEN</literal> suivantes ne
       sont pas testées.) Si aucun résultat vrai n'est trouvé, les
       <replaceable>instructions</replaceable> du bloc <literal>ELSE</literal>
       sont exécutées. Si aucun bloc <literal>ELSE</literal> n'est présent, une
       exception <literal>CASE_NOT_FOUND</literal> est levée.
      </para>

      <para>
       Voici un exemple&nbsp;:

<programlisting>
CASE
    WHEN x BETWEEN 0 AND 10 THEN
        msg := 'valeur entre zéro et dix';
    WHEN x BETWEEN 11 AND 20 THEN
        msg := 'valeur entre onze et vingt';
END CASE;
</programlisting>
      </para>

      <para>
       Cette forme de <command>CASE</command> est entièrement équivalente à
       <literal>IF-THEN-ELSIF</literal>, sauf pour la règle qui dit qu'atteindre
       une clause <literal>ELSE</literal> omise résulte dans une erreur plutôt
       que ne rien faire.
      </para>

     </sect3>
   </sect2>

   <sect2 id="plpgsql-control-structures-loops">
    <title>Boucles simples</title>

    <indexterm zone="plpgsql-control-structures-loops">
     <primary>boucle</primary>
     <secondary>en PL/pgSQL</secondary>
    </indexterm>

    <para>
     Grâce aux instructions <literal>LOOP</literal>, <literal>EXIT</literal>,
     <literal>CONTINUE</literal>, <literal>WHILE</literal>
     et <literal>FOR</literal>, vous pouvez faire en sorte que vos fonctions 
     <application>PL/pgSQL</application> répètent une série de commandes.
    </para>

    <sect3>
     <title><literal>LOOP</literal></title>

<synopsis><optional>&lt;&lt;<replaceable>label</replaceable>&gt;&gt;</optional>
LOOP
    <replaceable>instructions</replaceable>
END LOOP <optional> <replaceable>label</replaceable> </optional>;
</synopsis>

     <para>
      <literal>LOOP</literal> définit une boucle inconditionnelle répétée indéfiniment 
      jusqu'à ce qu'elle soit terminée par une instruction <literal>EXIT</literal> ou
      <command>RETURN</command>.  Le <replaceable>label</replaceable> optionnel
      peut être utilisé par les instructions <literal>EXIT</literal> et
      <literal>CONTINUE</literal> dans le cas de boucles imbriquées pour définir la
      boucle impliquée.
     </para>
    </sect3>

     <sect3>
      <title><literal>EXIT</literal></title>

     <indexterm>
      <primary>EXIT</primary>
      <secondary>en PL/pgSQL</secondary>
     </indexterm>

<synopsis>EXIT <optional> <replaceable>label</replaceable> </optional> <optional> WHEN <replaceable>expression-booléenne</replaceable> </optional>;
</synopsis>

       <para>
        Si aucun <replaceable>label</replaceable> n'est donné, la boucle la plus
	imbriquée se termine et l'instruction suivant <literal>END LOOP</literal> est
	exécutée.
        Si un <replaceable>label</replaceable> est donné, ce doit être 
	le label de la boucle, du bloc courant ou d'un niveau moins imbriqué.
	La boucle ou le bloc nommé se termine alors et le contrôle continue
	avec l'instruction située après le <literal>END</literal> de la boucle ou du bloc
	correspondant.
       </para>

       <para>
        Si <literal>WHEN</literal> est spécifié, la sortie de boucle ne s'effectue que
	si <replaceable>expression-booléenne</replaceable> est vraie. Sinon, le contrôle passe à
	l'instruction suivant le <literal>EXIT</literal>.
       </para>

       <para>
        <literal>EXIT</literal> peut être utilisé pour tous les types de
	boucles&nbsp;; il n'est pas limité aux boucles non conditionnelles.
       </para>

       <para>
	Lorsqu'il est utilisé avec un bloc <literal>BEGIN</literal>,
	<literal>EXIT</literal> passe le contrôle à la prochaine instruction
	après la fin du bloc. Notez qu'un label doit être utilisé pour
	cela&nbsp;; un <literal>EXIT</literal> sans label n'est jamais pris
	en compte pour correspondre à un bloc <literal>BEGIN</literal>.
	(Ceci est un changement de la version 8.4 de
	<productname>PostgreSQL</productname>. Auparavant, il était permis
	de faire correspondre un <literal>EXIT</literal> sans label avec un
	bloc <literal>BEGIN</literal>.)
       </para>

       <para>
        Exemples&nbsp;:
<programlisting>LOOP
    -- quelques traitements
    IF nombre > 0 THEN
        EXIT;  -- sortie de boucle
    END IF;
END LOOP;

LOOP
    -- quelques traitements
    EXIT WHEN nombre > 0;
END LOOP;

&lt;&lt;un_bloc&gt;&gt;
BEGIN
    -- quelques traitements
    IF stocks > 100000 THEN
        EXIT un_bloc;  -- cause la sortie (EXIT) du bloc BEGIN
    END IF;
    -- les traitements ici seront ignorés quand stocks &gt; 100000
END;
</programlisting>
       </para>
     </sect3>

     <sect3>
      <title><literal>CONTINUE</literal></title>

     <indexterm>
      <primary>CONTINUE</primary>
      <secondary>in PL/pgSQL</secondary>
     </indexterm>

<synopsis>CONTINUE <optional> <replaceable>label</replaceable> </optional> <optional> WHEN <replaceable>expression-booléenne</replaceable> </optional>;
</synopsis>

       <para>
        Si aucun <replaceable>label</replaceable> n'est donné, la prochaine
	itération de la boucle interne est commencée. C'est-à-dire que toutes
	les instructions restantes dans le corps de la boucle sont ignorées et
	le contrôle revient à l'expression de contrôle de la boucle pour
	déterminer si une autre itération de boucle est nécessaire.
        Si le <replaceable>label</replaceable> est présent, il spécifie le label
	de la boucle dont l'exécution va être continuée.
       </para>

       <para>
        Si <literal>WHEN</literal> est spécifié, la prochaine itération de la boucle
        est commencée seulement si l'<replaceable>expression-booléenne</replaceable> est vraie.
        Sinon, le contrôle est passé à l'instruction après
        <literal>CONTINUE</literal>.
       </para>

       <para>
        <literal>CONTINUE</literal> peut être utilisé avec tous les types de
        boucles&nbsp;; il n'est pas limité à l'utilisation des boucles
        inconditionnelles.
       </para>

       <para>
        Exemples&nbsp;:
<programlisting>LOOP
    -- quelques traitements
    EXIT WHEN nombre &gt; 100;
    CONTINUE WHEN nombre &lt; 50;
    -- quelques traitements pour nombre IN [50 .. 100] 
END LOOP;
</programlisting>
       </para>
     </sect3>


     <sect3>
      <title><literal>WHILE</literal></title>

     <indexterm>
      <primary>WHILE</primary>
      <secondary>en PL/pgSQL</secondary>
     </indexterm>

<synopsis><optional>&lt;&lt;<replaceable>label</replaceable>&gt;&gt;</optional>
WHILE <replaceable>expression-booléenne</replaceable> LOOP
    <replaceable>instructions</replaceable>
END LOOP <optional> <replaceable>label</replaceable> </optional>;
</synopsis>

       <para>
        L'instruction <literal>WHILE</literal> répète une séquence d'instructions aussi longtemps
		que <replaceable>expression-booléenne</replaceable> est évaluée à vrai. L'expression est vérifiée juste
	avant chaque entrée dans le corps de la boucle.
       </para>

       <para>
        Par exemple&nbsp;:
<programlisting>WHILE montant_possede > 0 AND balance_cadeau > 0 LOOP
    -- quelques traitements ici
END LOOP;

WHILE NOT termine LOOP
    -- quelques traitements ici
END LOOP;
</programlisting>
       </para>
     </sect3>

     <sect3 id="plpgsql-integer-for">
      <title><literal>FOR</literal> (variante avec entier)</title>

<synopsis><optional>&lt;&lt;<replaceable>label</replaceable>&gt;&gt;</optional>
FOR <replaceable>nom</replaceable> IN <optional> REVERSE </optional> <replaceable>expression</replaceable> .. <replaceable>expression</replaceable> <optional> BY <replaceable>expression</replaceable> </optional> LOOP
    <replaceable>instruction</replaceable>
END LOOP <optional> <replaceable>label</replaceable> </optional>;
</synopsis>

       <para>
        Cette forme de <literal>FOR</literal> crée une boucle qui effectue une itération
	sur une plage de valeurs entières. La variable <replaceable>nom</replaceable>
	est automatiquement définie comme un type <type>integer</type> et n'existe
	que dans la boucle (toute définition de la variable est ignorée à l'intérieur
	de la boucle). Les deux expressions donnant les limites inférieures et
	supérieures de la plage sont évaluées une fois en entrant dans la boucle.
	Si la clause <literal>BY</literal> n'est pas spécifiée, l'étape
	d'itération est de 1, sinon elle est de la valeur spécifiée dans la
	clause <literal>BY</literal>, qui est évaluée encore une fois à l'entrée
	de la boucle. Si <literal>REVERSE</literal> est indiquée,
	alors la valeur de l'étape est soustraite, plutôt qu'ajoutée, après chaque
	itération.
       </para>

       <para>
        Quelques exemples de boucles <literal>FOR</literal> avec entiers&nbsp;:
<programlisting>FOR i IN 1..10 LOOP
    -- prend les valeurs 1,2,3,4,5,6,7,8,9,10 dans la boucle
END LOOP;

FOR i IN REVERSE 10..1 LOOP
    -- prend les valeurs 10,9,8,7,6,5,4,3,2,1 dans la boucle
END LOOP;

FOR i IN REVERSE 10..1 BY 2 LOOP
    -- prend les valeurs 10,8,6,4,2 dans la boucle
END LOOP;

</programlisting>
       </para>

       <para>
        Si la limite basse est plus grande que la limite haute (ou moins grande
        dans le cas du <literal>REVERSE</literal>), le corps de la boucle
        n'est pas exécuté du tout. Aucune erreur n'est renvoyée.
       </para>


       <para>
        Si un <replaceable>label</replaceable> est attaché à la boucle
        <literal>FOR</literal>, alors la variable entière de boucle peut être
	référencée avec un nom qualifié en utilisant ce
        <replaceable>label</replaceable>.
       </para>
     </sect3>
   </sect2>

   <sect2 id="plpgsql-records-iterating">
    <title>Boucler dans les résultats de requêtes</title>

    <para>
     En utilisant un type de <literal>FOR</literal> différent, vous pouvez itérer au travers
     des résultats d'une requête et par là-même manipuler ces données. La 
     syntaxe est la suivante&nbsp;: 
<synopsis><optional>&lt;&lt;<replaceable>label</replaceable>&gt;&gt;</optional>
FOR <replaceable>cible</replaceable> IN <replaceable>requête</replaceable> LOOP
    <replaceable>instructions</replaceable>
END LOOP <optional> <replaceable>label</replaceable> </optional>;
</synopsis>
     La <replaceable>cible</replaceable> est une variable de type record, row
     ou une liste de variables scalaires séparées par une virgule. La
     <replaceable>cible</replaceable> est affectée successivement à chaque ligne
     résultant de la <replaceable>requête</replaceable> et le corps de la boucle
     est exécuté pour chaque ligne. Voici un exemple&nbsp;:
<programlisting>CREATE FUNCTION cs_rafraichir_vuemat() RETURNS integer AS $$
DECLARE
    vues_mat RECORD;
BEGIN
    PERFORM cs_log('Rafraichissement des vues matérialisées...');

    FOR vues_mat IN SELECT * FROM cs_vues_materialisees ORDER BY cle_tri LOOP

        -- À présent vues_mat contient un enregistrement de cs_vues_materialisees

	PERFORM cs_log('Rafraichissement de la vue matérialisée ' || quote_ident(vues_mat.vm_nom) || '...');
	EXECUTE 'TRUNCATE TABLE  ' || quote_ident(vues_mat.vm_nom);
	EXECUTE 'INSERT INTO ' || quote_ident(vues_mat.vm_nom) || ' ' || vues_mat.vm_requete;
    END LOOP;

    PERFORM cs_log('Fin du rafraichissement des vues matérialisées.');
    RETURN 1;
END;
$$ LANGUAGE plpgsql;
</programlisting>

     Si la boucle est terminée par une instruction <literal>EXIT</literal>, la dernière valeur
     ligne affectée est toujours accessible après la boucle.
    </para>

    <para>
     La <replaceable>requête</replaceable> utilisée dans ce type d'instruction
     <literal>FOR</literal> peut être toute commande SQL qui renvoie des lignes
     à l'appelant&nbsp;: <command>SELECT</command> est le cas le plus commun
     mais vous pouvez aussi utiliser <command>INSERT</command>, <command>UPDATE</command>
     ou <command>DELETE</command> avec une clause <literal>RETURNING</literal>.
     Certaines commandes comme <command>EXPLAIN</command> fonctionnent aussi.
    </para>

    <para>
     Les variables <application>PL/pgSQL</application> sont substituées dans le
     texte de la requête et le plan de requête est mis en cache pour une
     réutilisation possible. C'est couvert en détail dans la
     <xref linkend="plpgsql-var-subst"/> et dans la 
     <xref linkend="plpgsql-plan-caching"/>.
    </para>

    <para>
     L'instruction <literal>FOR-IN-EXECUTE</literal> est un moyen d'itérer sur des 
     lignes&nbsp;:
<synopsis><optional>&lt;&lt;<replaceable>label</replaceable>&gt;&gt;</optional>
FOR <replaceable>target</replaceable> IN EXECUTE <replaceable>text_expression</replaceable> <optional> USING <replaceable>expression</replaceable> <optional>, ...</optional> </optional> LOOP
    <replaceable>instructions</replaceable>
END LOOP <optional> <replaceable>label</replaceable> </optional>;
</synopsis>
     Ceci est identique à la forme précédente, à ceci près que l'expression 
     de la requête source est spécifiée comme une expression chaîne,
     évaluée et replanifiée à chaque entrée dans la boucle <literal>FOR</literal>. Ceci 
     permet au développeur de choisir entre la vitesse d'une requête préplanifiée et la 
     flexibilité d'une requête dynamique, uniquement avec l'instruction 
     <command>EXECUTE</command>.
     Comme avec <command>EXECUTE</command>, les valeurs de paramètres peuvent
     être insérées dans la commande dynamique via <literal>USING</literal>.
    </para>

    <para>
     Une autre façon de spécifier la requête dont les résultats devront être
     itérés est de la déclarer comme un curseur. Ceci est décrit dans
     <xref linkend="plpgsql-cursor-for-loop"/>.
    </para>
  </sect2>

  <sect2 id="plpgsql-error-trapping">
    <title>Récupérer les erreurs</title>

    <indexterm>
     <primary>exceptions</primary>
     <secondary>en PL/PgSQL</secondary>
    </indexterm>

    <para>
      Par défaut, toute erreur survenant dans une fonction
      <application>PL/pgSQL</application> annule l'exécution de la fonction mais
      aussi de la transaction qui l'entoure. Vous pouvez récupérer les erreurs
      en utilisant un bloc <command>BEGIN</command> avec une clause
      <literal>EXCEPTION</literal>. La syntaxe est une extension de la syntaxe
      habituelle pour un bloc <command>BEGIN</command>&nbsp;:

<synopsis>  <optional> &lt;&lt;<replaceable>label</replaceable>&gt;&gt; </optional>
  <optional> DECLARE
    <replaceable>declarations</replaceable> </optional>
  BEGIN
  <replaceable>instructions</replaceable>
  EXCEPTION
  WHEN <replaceable>condition</replaceable> <optional> OR <replaceable>condition</replaceable> ... </optional> THEN
  <replaceable>instructions_gestion_erreurs</replaceable>
  <optional> WHEN <replaceable>condition</replaceable> <optional> OR <replaceable>condition</replaceable> ... </optional> THEN
    <replaceable>instructions_gestion_erreurs</replaceable>
    ... </optional>
  END;
</synopsis>
    </para>

    <para>
      Si aucune erreur ne survient, cette forme de bloc exécute simplement
      toutes les <replaceable>instructions</replaceable> puis passe le
      contrôle à l'instruction suivant <literal>END</literal>. Mais si une erreur
      survient à l'intérieur des <replaceable>instructions</replaceable>,
      le traitement en cours des <replaceable>instructions</replaceable> est
      abandonné et le contrôle est passé à la liste d'<literal>EXCEPTION</literal>.
      Une recherche est effectuée sur la liste pour la première
      <replaceable>condition</replaceable> correspondant à l'erreur survenue.
      Si une correspondance est trouvée, les
      <replaceable>instructions_gestion_erreurs</replaceable> correspondantes
      sont exécutées puis le contrôle est passé à l'instruction suivant le
      <literal>END</literal>. Si aucune correspondance n'est trouvée, l'erreur se
      propage comme si la clause <literal>EXCEPTION</literal> n'existait pas du
      tout&nbsp;: l'erreur peut être récupérée par un bloc l'enfermant avec
      <literal>EXCEPTION</literal> ou, s'il n'existe pas, elle annule le traitement de
      la fonction.
    </para>

    <para>
      Les noms des <replaceable>condition</replaceable> sont indiquées dans
      l'<xref linkend="errcodes-appendix"/>. Un nom de catégorie correspond à toute
      erreur contenue dans cette catégorie. Le nom de condition spéciale
      <literal>OTHERS</literal> correspond à tout type d'erreur sauf
      <literal>QUERY_CANCELED</literal> (il est possible, mais pas recommandé, de
      récupérer <literal>QUERY_CANCELED</literal> par son nom). Les noms des
      conditions ne sont pas sensibles à la casse. De plus, une condition d'erreur
      peut être indiquée par un code <literal>SQLSTATE</literal>&nbsp;; par exemple,
      ces deux cas sont équivalents&nbsp;:
<programlisting>
        WHEN division_by_zero THEN ...
        WHEN SQLSTATE '22012' THEN ...
</programlisting>
    </para>

    <para>
      Si une nouvelle erreur survient à l'intérieur des
      <replaceable>instructions_gestion_erreurs</replaceable> sélectionnées, elle
      ne peut pas être récupérée par cette clause <literal>EXCEPTION</literal> mais
      est propagée en dehors. Une clause <literal>EXCEPTION</literal> l'englobant
      pourrait la récupérer.
    </para>

    <para>
      Quand une erreur est récupérée par une clause <literal>EXCEPTION</literal>, les
      variables locales de la fonction <application>PL/pgSQL</application> restent
      dans le même état qu'au moment où l'erreur est survenue mais toutes les
      modifications à l'état persistant de la base de données à l'intérieur
      du bloc sont annulées. Comme exemple, considérez ce fragment&nbsp;:

<programlisting>INSERT INTO mon_tableau(prenom, nom) VALUES('Tom', 'Jones');
BEGIN
  UPDATE mon_tableau SET prenom = 'Joe' WHERE nom = 'Jones';
  x := x + 1;
  y := x / 0;
  EXCEPTION
    WHEN division_by_zero THEN
      RAISE NOTICE 'récupération de l''erreur division_by_zero';
RETURN x;
END;
</programlisting>

      Quand le contrôle parvient à l'affectation de <literal>y</literal>, il échouera
      avec une erreur <literal>division_by_zero</literal>. Elle sera récupérée par la
      clause <literal>EXCEPTION</literal>. La valeur renvoyée par l'instruction
      <command>RETURN</command> sera la valeur incrémentée de <literal>x</literal> mais
      les effets de la commande <command>UPDATE</command> auront été annulés. La
      commande <command>INSERT</command> précédant le bloc ne sera pas annulée, du
      coup le résultat final est que la base de données contient
      <literal>Tom Jones</literal> et non pas <literal>Joe Jones</literal>.
    </para>

    <tip>
      <para>
        Un bloc contenant une clause <literal>EXCEPTION</literal> est
        significativement plus coûteuse en entrée et en sortie qu'un bloc
        sans. Du coup, n'utilisez pas <literal>EXCEPTION</literal> sans besoin.
      </para>
    </tip>

    <para>
     À l'intérieur d'un gestionnaire d'exceptions, la variable
     <varname>SQLSTATE</varname> contient le code d'erreur correspondant à
     l'exception qui a été levée (référez-vous au <xref
     linkend="errcodes-table"/> pour une liste des codes d'erreurs possibles).
     La variable <varname>SQLERRM</varname> contient le message d'erreur
     associé avec l'exception. Ces variables sont indéfinies à l'extérieur des
     gestionnaires d'exceptions.
    </para>

    <example id="plpgsql-upsert-example">
    <title>Exceptions avec <command>UPDATE</command>/<command>INSERT</command></title>
    <para>
    Cet exemple utilise un gestionnaire d'exceptions pour réaliser soit un
    <command>UPDATE</command> soit un <command>INSERT</command>, comme approprié&nbsp;:

<programlisting>CREATE TABLE base (a INT PRIMARY KEY, b TEXT);

CREATE FUNCTION fusionne_base(cle INT, donnee TEXT) RETURNS VOID AS
$$
BEGIN
    LOOP
        -- commençons par tenter la mise à jour de la clé
        UPDATE base SET b = donnee WHERE a = cle;
        IF found THEN
            RETURN;
        END IF;

        -- si elle n'est pas dispo, tentons l'insertion de la clé
        -- si quelqu'un essaie d'insérer la même clé en même temps,
        -- il y aura une erreur pour violation de clé unique
        BEGIN
            INSERT INTO base(a,b) VALUES (cle, donnee);
            RETURN;
        EXCEPTION WHEN unique_violation THEN
            -- ne rien faire, et tente de nouveau la mise à jour
        END;
    END LOOP;
END;
$$
LANGUAGE plpgsql;

SELECT fusionne_base(1, 'david');
SELECT fusionne_base(1, 'dennis');
</programlisting>

    </para>
    </example>
   </sect2>
  </sect1>

  <sect1 id="plpgsql-cursors">
   <title>Curseurs</title>

   <indexterm zone="plpgsql-cursors">
    <primary>curseur</primary>
    <secondary>en PL/pgSQL</secondary>
   </indexterm>

   <para>
    Plutôt que d'exécuter la totalité d'une requête à la fois, il est possible de 
    créer un <firstterm>curseur</firstterm> qui encapsule la requête, puis en lit le résultat
    quelques lignes à la fois. Une des raisons pour faire de la sorte est d'éviter les
    surcharges de mémoire quand le résultat contient un grand nombre de lignes (cependant,
    les utilisateurs <application>PL/pgSQL</application> n'ont généralement pas besoin de se
    préoccuper de cela puisque les boucles <literal>FOR</literal> utilisent automatiquement un
    curseur en interne pour éviter les problèmes de mémoire). Un usage plus intéressant est
    de renvoyer une référence à un curseur qu'une fonction a créé, permettant à l'appelant de
    lire les lignes. C'est un moyen efficace de renvoyer de grands ensembles de
    lignes à partir des fonctions.
   </para>
   
   <sect2 id="plpgsql-cursor-declarations">
    <title>Déclaration de variables curseur</title>

    <para>
     Tous les accès aux curseurs dans <application>PL/pgSQL</application> se font par les variables
     curseur, qui sont toujours du type de données spécial <type>refcursor</type>. Un des 
     moyens de créer une variable curseur est de simplement la déclarer comme une variable
     de type <type>refcursor</type>. Un autre moyen est d'utiliser la syntaxe de déclaration
     de curseur qui est en général&nbsp;:

<synopsis><replaceable>nom</replaceable> <optional> <optional> NO </optional> SCROLL </optional> CURSOR <optional> ( <replaceable>arguments</replaceable> ) </optional> FOR <replaceable>requête</replaceable>;
</synopsis>
     (<literal>FOR</literal> peut être remplacé par <literal>IS</literal> pour la compatibilité avec
     <productname>Oracle</productname>).
     Si <literal>SCROLL</literal> est spécifié, le curseur sera capable d'aller
     en sens inverse&nbsp;; si <literal>NO SCROLL</literal> est indiqué, les
     récupérations en sens inverses seront rejetées&nbsp;; si rien n'est
     indiqué, cela dépend de la requête.
     <replaceable>arguments</replaceable> est une liste de paires de
     <literal><replaceable>nom</replaceable> <replaceable>type-de-donnée</replaceable></literal>
     qui définit les noms devant être remplacés par les valeurs des paramètres dans la requête donnée. 
     La valeur effective à substituer pour ces noms sera indiquée plus tard lors de
     l'ouverture du curseur.
    </para>
    <para>
     Quelques exemples&nbsp;:
<programlisting>DECLARE
    curs1 refcursor;
    curs2 CURSOR FOR SELECT * FROM tenk1;
    curs3 CURSOR (cle integer) IS SELECT * FROM tenk1 WHERE unique1 = cle;
</programlisting>
     Ces variables sont toutes trois du type de données <type>refcursor</type>
     mais la première peut être utilisée avec n'importe quelle requête alors que
     la seconde a une requête complètement spécifiée qui lui est déjà
     <firstterm>liée</firstterm>, et la dernière est liée à une requête paramétrée
     (<literal>cle</literal> sera remplacée par un paramètre de valeur entière lors de
     l'ouverture du curseur).
     La variable <literal>curs1</literal> est dite <firstterm>non liée</firstterm> puisqu'elle
     n'est pas liée à une requête particulière.
      </para>
   </sect2>

   <sect2 id="plpgsql-cursor-opening">
    <title>Ouverture de curseurs</title>

    <para>
     Avant qu'un curseur puisse être utilisé pour rapatrier des lignes, il doit être
     <firstterm>ouvert</firstterm> (c'est l'action équivalente de la commande SQL 
     <command>DECLARE CURSOR</command>). <application>PL/pgSQL</application>
     dispose de trois formes pour
     l'instruction <command>OPEN</command>, dont deux utilisent des variables curseur non liées
     et la dernière une variable curseur liée.
    </para>

    <note>
     <para>
      Les variables des curseurs liés peuvent aussi être utilisés sans les ouvrir
      explicitement, via l'instruction <command>FOR</command> décrite dans
      <xref linkend="plpgsql-cursor-for-loop"/>.
     </para>
    </note>

    <sect3>
     <title><command>OPEN FOR</command> <replaceable>requête</replaceable></title>

<synopsis>OPEN <replaceable>var_curseur_nonlie</replaceable> <optional> <optional> NO </optional> SCROLL </optional> FOR <replaceable>requete</replaceable>;
</synopsis>

       <para>
    	La variable curseur est ouverte et reçoit la requête spécifiée à 
    	exécuter. Le curseur ne peut pas être déjà ouvert, et il doit avoir
    	été déclaré comme une variable de curseur non lié (c'est-à-dire comme
	une simple variable <type>refcursor</type>). La requête doit être un
        <command>SELECT</command> ou quelque chose d'autre qui renvoie des
        lignes (comme <command>EXPLAIN</command>). La requête est traitée de la même
        façon que les autres commandes SQL dans <application>PL/pgSQL</application>&nbsp;:
        les noms de variables <application>PL/pgSQL</application> sont substitués et
        le plan de requête est mis en cache pour une possible ré-utilisation.
        Quand une variable <application>PL/pgSQL</application> est substituée
	dans une requête de type curseur, la valeur qui est substituée est celle
	qu'elle avait au moment du <command>OPEN</command>&nbsp;; les modifications
	ultérieures n'auront pas affectées le comportement du curseur.
        Les options <literal>SCROLL</literal> et <literal>NO SCROLL</literal>
        ont la même signification que pour un curseur lié.
       </para>

       <para>
        Exemple&nbsp;:
<programlisting>OPEN curs1 FOR SELECT * FROM foo WHERE cle = ma_cle;
</programlisting>
       </para>
     </sect3>

    <sect3>
     <title><command>OPEN FOR EXECUTE</command></title>

<synopsis>OPEN <replaceable>var_curseur_nonlie</replaceable> <optional> <optional> NO </optional> SCROLL </optional> FOR EXECUTE <replaceable class="command">requete</replaceable>;
</synopsis>

	 <para>
	  La variable curseur est ouverte et reçoit la requête spécifiée à exécuter.
	  Le curseur ne peut pas être déjà ouvert et il doit avoir été déclaré comme
	  une variable de
	  curseur non lié (c'est-à-dire comme une simple variable <type>refcursor</type>).
	  La requête est spécifiée comme une expression chaîne de la même façon que
	  dans une commande <command>EXECUTE</command>. Comme d'habitude, ceci donne
	  assez de flexibilité pour que le plan de la requête puisse changer d'une
	  exécution à l'autre (voir la <xref linkend="plpgsql-plan-caching"/>),
	  et cela signifie aussi que la substitution de variable n'est pas faite
	  sur la chaîne de commande. Les options <literal>SCROLL</literal> et
	  <literal>NO SCROLL</literal> ont la même signification que pour un
	  curseur lié.
       </para>

       <para>
       Exemple&nbsp;:
<programlisting>OPEN curs1 FOR EXECUTE 'SELECT * FROM ' || quote_ident($1);
</programlisting>
       </para>
     </sect3>

    <sect3>
     <title>Ouverture d'un curseur lié</title>

<synopsis>OPEN <replaceable>var_curseur_lié</replaceable> <optional> ( <replaceable>arguments</replaceable> ) </optional>;
</synopsis>

	 <para>
	  Cette forme d'<command>OPEN</command> est utilisée pour ouvrir une variable
	  curseur à laquelle la requête est liée au moment de la déclaration.
	  Le curseur ne peut pas être déjà ouvert. Une liste des expressions arguments
	  doit apparaître si et seulement si le curseur a été déclaré comme acceptant 
	  des arguments. Ces valeurs seront remplacées dans la requête. Le plan de
	  requête pour un curseur lié est toujours considéré comme pouvant être mis 
	  en cache&nbsp;; il n'y a pas d'équivalent de la commande 
	  <command>EXECUTE</command> dans ce cas. Notez que
	  <literal>SCROLL</literal> et <literal>NO SCROLL</literal> ne peuvent
	  pas être indiqués car le comportement du curseur était déjà déterminé.
         </para>

         <para>
          Notez que, parce que la substitution de variables est faite sur la
	  requête du curseur lié, il y a deux façon de passer des valeurs au
	  curseur&nbsp;: soit explicitement avec un argument pour
	  <command>OPEN</command> soit implicitement en référençant une variable
	  <application>PL/pgSQL</application> dans la requête. Néanmoins, seules
	  les variables déclarées avant la déclaration du curseur lié pourront
	  être substituées. De toute façon, la valeur à passer est déterminé au
	  moment de l'exécution de <command>OPEN</command>.

         </para>

    <para>
     Exemples&nbsp;:
<programlisting>OPEN curs2;
OPEN curs3(42);
</programlisting>
       </para>
     </sect3>
   </sect2>

   <sect2 id="plpgsql-cursor-using">
    <title>Utilisation des curseurs</title>

    <para>
     Une fois qu'un curseur a été ouvert, il peut être manipulé grâce aux instructions
     décrites ci-dessous.
    </para>

    <para>
     Ces manipulations n'ont pas besoin de se dérouler dans la même fonction que celle
     qui a ouvert le curseur. Vous pouvez renvoyer une valeur <type>refcursor</type>
     à partir d'une fonction et laisser l'appelant opérer sur le curseur
     (d'un point de vue interne, une valeur <type>refcursor</type> est simplement
     la chaîne de caractères du nom d'un portail contenant la requête active 
     pour le curseur. Ce nom peut être passé à d'autres, affecté à d'autres variables
     <type>refcursor</type> et ainsi de suite, sans déranger le portail).
    </para>

    <para>
     Tous les portails sont implicitement fermés à la fin de la transaction. C'est pourquoi
     une valeur <type>refcursor</type> est utilisable pour référencer un curseur ouvert
     seulement jusqu'à la fin de la transaction. 
    </para>

    <sect3>
     <title><literal>FETCH</literal></title>

<synopsis>FETCH <optional> <replaceable>direction</replaceable> { FROM | IN } </optional> <replaceable>curseur</replaceable> INTO <replaceable>cible</replaceable>;
</synopsis>

    <para>
     <command>FETCH</command> récupère la prochaine ligne à partir d'un curseur
     et la place dans une cible, qui peut être une variable ligne, une variable
     record ou une liste de variables simples séparées par des virgules,
     comme dans un <command>SELECT INTO</command>. S'il n'y a pas de ligne
     suivante, la cible est mise à NULL. Comme avec <command>SELECT
     INTO</command>, la variable spéciale <literal>FOUND</literal> peut
     être lue pour voir si une ligne a été récupérée.
    </para>

    <para>
     La clause <replaceable>direction</replaceable> peut être une des
     variantes suivantes autorisées pour la commande SQL <xref linkend="sql-fetch"
     endterm="sql-fetch-title"/> sauf celles qui peuvent récupérer plus
     d'une ligne&nbsp;; nommément, cela peut être
     <literal>NEXT</literal>,
     <literal>PRIOR</literal>,
     <literal>FIRST</literal>,
     <literal>LAST</literal>,
     <literal>ABSOLUTE</literal> <replaceable>nombre</replaceable>,
     <literal>RELATIVE</literal> <replaceable>nombre</replaceable>,
     <literal>FORWARD</literal> ou
     <literal>BACKWARD</literal>.
     Omettre <replaceable>direction</replaceable> est identique à spécifier
     <literal>NEXT</literal>. Les valeurs <replaceable>direction</replaceable>
     qui nécessitent d'aller en sens inverse risquent d'échouer sauf si le
     curseur a été déclaré ou ouvert avec l'option <literal>SCROLL</literal>.
    </para>

    <para>
     <replaceable>curseur</replaceable> doit être le nom d'une variable
     <type>refcursor</type> qui référence un portail de curseur ouvert.
    </para>

    <para>
     Exemples&nbsp;:
<programlisting>
FETCH curs1 INTO rowvar;
FETCH curs2 INTO foo, bar, baz;
FETCH LAST FROM curs3 INTO x, y;
FETCH RELATIVE -2 FROM curs4 INTO x;
</programlisting>
       </para>
     </sect3>

    <sect3>
     <title><literal>MOVE</literal></title>

<synopsis>
MOVE <optional> <replaceable>direction</replaceable> { FROM | IN } </optional> <replaceable>curseur</replaceable>;
</synopsis>

    <para>
     <command>MOVE</command> repositionne un curseur sans récupérer de données.
     <command>MOVE</command> fonctionne exactement comme la commande
     <command>FETCH</command> sauf qu'elle ne fait que repositionner le curseur
     et ne renvoie donc pas les lignes du déplacement. Comme avec <command>SELECT
     INTO</command>, la variable spéciale <literal>FOUND</literal> peut être
     lue pour vérifier s'il y avait bien les lignes correspondant au déplacement.
    </para>

    <para>
     Les options pour la clause <replaceable>direction</replaceable> sont
     identiques à celles de la commande <command>FETCH</command>, nommément
     <literal>NEXT</literal>,
     <literal>PRIOR</literal>,
     <literal>FIRST</literal>,
     <literal>LAST</literal>,
     <literal>ABSOLUTE</literal> <replaceable>nombre</replaceable>,
     <literal>RELATIVE</literal> <replaceable>nombre</replaceable>,
     <literal>FORWARD</literal> ou
     <literal>BACKWARD</literal>.
     Omettre <replaceable>direction</replaceable> est identique à spécifier
     <literal>NEXT</literal>.
     Les valeurs <replaceable>direction</replaceable> qui nécessitent de se
     déplacer en arrière risquent d'échouer sauf si le curseur a été déclaré ou
     ouvert avec l'option <literal>SCROLL</literal>.
    </para>

    <para>
     Exemples&nbsp;:
<programlisting>
MOVE curs1;
MOVE LAST FROM curs3;
MOVE RELATIVE -2 FROM curs4;
</programlisting>
       </para>
     </sect3>

    <sect3>
     <title><literal>UPDATE/DELETE WHERE CURRENT OF</literal></title>

<synopsis>
UPDATE <replaceable>table</replaceable> SET ... WHERE CURRENT OF <replaceable>curseur</replaceable>;
DELETE FROM <replaceable>table</replaceable> WHERE CURRENT OF <replaceable>curseur</replaceable>;
</synopsis>

       <para>
        Quand un curseur est positionné sur une ligne d'une table, cette ligne
	peut être mise à jour ou supprimée en utilisant le curseur qui identifie
	la ligne. Il existe des restrictions sur ce que peut être la requête
	du curseur (en particulier, pas de regroupement) et il est mieux
	d'utiliser <literal>FOR UPDATE</literal> dans le curseur. Pour des
	informations supplémentaires, voir la page de référence
        <xref linkend="sql-declare" endterm="sql-declare-title"/>.
       </para>

       <para>
        Un exemple&nbsp;:
<programlisting>
UPDATE foo SET valdonnee = mavaleur WHERE CURRENT OF curs1;
</programlisting>
       </para>
     </sect3>

    <sect3>
     <title><literal>CLOSE</literal></title>

<synopsis>CLOSE <replaceable>curseur</replaceable>;
</synopsis>

       <para>
    <command>CLOSE</command> ferme le portail sous-tendant un curseur ouvert. Ceci peut
    être utilisé pour libérer des ressources avant la fin de la transaction ou pour
    libérer la variable curseur pour pouvoir la réouvrir.
       </para>

       <para>
        Exemple&nbsp;:
<programlisting>CLOSE curs1;
</programlisting>
       </para>
     </sect3>
 
    <sect3>
     <title>Renvoi de curseurs</title>

       <para>
        Les fonctions <application>PL/pgSQL</application> peuvent renvoyer des curseurs
        à l'appelant. Ceci est utile pour renvoyer plusieurs lignes ou
        colonnes, spécialement avec des ensembles de résultats très grands.
        Pour cela, la fonction ouvre le curseur et renvoie le nom du curseur
        à l'appelant (ou simplement ouvre le curseur en utilisant un nom de
        portail spécifié par ou autrement connu par l'appelant). L'appelant
        peut alors récupérer les lignes à partir du curseur. Le curseur
        peut être fermé par l'appelant ou il sera fermé automatiquement à la
        fin de la transaction.
       </para>

       <para>
        Le nom du portail utilisé pour un curseur peut être spécifié par le
        développeur ou peut être généré automatiquement. Pour spécifier un
        nom de portail, affectez simplement une chaîne à la variable
        <type>refcursor</type> avant de l'ouvrir. La valeur de la
        variable <type>refcursor</type> sera utilisée par <command>OPEN</command> comme
        nom du portail sous-jacent. Néanmoins, si la variable
        <type>refcursor</type> est NULL, <command>OPEN</command> génère automatiquement
        un nom qui n'entre pas en conflit avec tout portail existant et
        l'affecte à la variable <type>refcursor</type>.
       </para>

       <note>
        <para>
         Une variable curseur avec limites est initialisée avec la valeur de
         la chaîne représentant son nom, de façon à ce que le nom du portail
         soit identique au nom de la variable curseur, sauf si le développeur
         le surcharge par affectation avant d'ouvrir le curseur. Mais, une
         variable curseur sans limite aura par défaut la valeur NULL, dont il
         reçoit un nom unique généré automatiquement sauf s'il est surchargé.
        </para>
       </note>

       <para>
        L'exemple suivant montre une façon de fournir un nom de curseur par
        l'appelant&nbsp;:

<programlisting>CREATE TABLE test (col text);
INSERT INTO test VALUES ('123');

CREATE FUNCTION fonction_reference(refcursor) RETURNS refcursor AS $$
BEGIN
    OPEN $1 FOR SELECT col FROM test;
    RETURN $1;
END;
$$ LANGUAGE plpgsql;

BEGIN;
SELECT fonction_reference('curseur_fonction');
FETCH ALL IN curseur_fonction;
COMMIT;
</programlisting>
       </para>

       <para>
        L'exemple suivant utilise la génération automatique du nom du
curseur&nbsp;:

<programlisting>CREATE FUNCTION fonction_reference2() RETURNS refcursor AS $$
DECLARE
    ref refcursor;
BEGIN
    OPEN ref FOR SELECT col FROM test;
    RETURN ref;
END;
$$ LANGUAGE plpgsql;

BEGIN;
SELECT fonction_reference2();

   fonction_reference2
--------------------------
 &lt;unnamed cursor 1&gt;
(1 row)

FETCH ALL IN "&lt;unnamed cursor 1&gt;";
COMMIT;
</programlisting>
       </para>

       <para>
        L'exemple suivant montre une façon de renvoyer plusieurs curseurs à une
	seule fonction&nbsp;:

<programlisting>CREATE FUNCTION ma_fonction(refcursor, refcursor) RETURNS SETOF refcursor AS $$
BEGIN
    OPEN $1 FOR SELECT * FROM table_1;
    RETURN NEXT $1;
    OPEN $2 FOR SELECT * FROM table_2;
    RETURN NEXT $2;
END;
$$ LANGUAGE plpgsql;

-- doit être dans une transaction pour utiliser les curseurs.
BEGIN;

SELECT * FROM ma_fonction('a', 'b');

FETCH ALL FROM a;
FETCH ALL FROM b;
COMMIT;
</programlisting>
       </para>
     </sect3>
   </sect2>
   
   <sect2 id="plpgsql-cursor-for-loop">
    <title>Boucler dans les résultats d'un curseur</title>

    <para>
     C'est une variante de l'instruction <command>FOR</command> qui permet
     l'itération sur les lignes renvoyées par un curseur. La syntaxe est&nbsp;:

<synopsis>
<optional> &lt;&lt;<replaceable>label</replaceable>&gt;&gt; </optional>
FOR <replaceable>var_record</replaceable> IN <replaceable>var_curseur_lié</replaceable> <optional> ( <replaceable>valeurs_argument</replaceable> ) </optional> LOOP
    <replaceable>instructions</replaceable>
END LOOP <optional> <replaceable>label</replaceable> </optional>;
</synopsis>

     La variable curseur doit avoir été liée à une requête lors de sa déclaration
     et il <emphasis>ne peut pas</emphasis> être déjà ouvert. L'instruction
     <command>FOR</command> ouvre automatiquement le curseur, et il ferme
     le curseur en sortie de la boucle. Une liste des expressions de valeurs
     des arguments doit apparaître si et seulement si le curseur a été déclaré
     prendre des arguments. Ces valeurs seront substitutées dans la requête,
     de la même façon que lors d'un <command>OPEN</command>. La variable
     variable <replaceable>var_record</replaceable> est définie automatiquement
     avec le type <type>record</type> et existe seulement dans la boucle (toute
     définition existante d'un nom de variable est ignorée dans la boucle).
     Chaque ligne renvoyée par le curseur est successivement affectée à la variable
     d'enregistrement et le corps de la boucle est exécuté.
    </para>
   </sect2>

  </sect1>

  <sect1 id="plpgsql-errors-and-messages">
   <title>Erreurs et messages</title>

   <indexterm>
    <primary>RAISE</primary>
   </indexterm>

   <indexterm>
    <primary>rapporter des erreurs</primary>
    <secondary>en PL/PgSQL</secondary>
   </indexterm>

   <para>
    Utilisez l'instruction <command>RAISE</command> pour rapporter des messages et 
    lever des erreurs.

<synopsis>RAISE <optional> <replaceable class="parameter">niveau</replaceable> </optional> '<replaceable class="parameter">format</replaceable>' <optional>, <replaceable class="parameter">expression</replaceable> <optional>, ...</optional></optional> <optional> USING <replaceable class="parameter">option</replaceable> = <replaceable class="parameter">expression</replaceable> <optional>, ... </optional> </optional>;
RAISE <optional> <replaceable class="parameter">niveau</replaceable> </optional> <replaceable class="parameter">nom_condition</replaceable> <optional> USING <replaceable class="parameter">option</replaceable> = <replaceable class="parameter">expression</replaceable> <optional>, ... </optional> </optional>;
RAISE <optional> <replaceable class="parameter">niveau</replaceable> </optional> SQLSTATE '<replaceable class="parameter">état_sql</replaceable>' <optional> USING <replaceable class="parameter">option</replaceable> = <replaceable class="parameter">expression</replaceable> <optional>, ... </optional> </optional>;
RAISE <optional> <replaceable class="parameter">niveau</replaceable> </optional> USING <replaceable class="parameter">option</replaceable> = <replaceable class="parameter">expression</replaceable> <optional>, ... </optional>;
RAISE ;
</synopsis>

    L'option <replaceable class="parameter">niveau</replaceable> indique la
    sévérité de l'erreur. Les niveaux autorisés sont <literal>DEBUG</literal>,
    <literal>LOG</literal>, <literal>INFO</literal>, <literal>NOTICE</literal>,
    <literal>WARNING</literal> et <literal>EXCEPTION</literal>, ce dernier étant
    la valeur par défaut.
    <literal>EXCEPTION</literal> lève une erreur (ce qui annule habituellement
    la transaction en cours). Les autres niveaux ne font que générer des messages aux
    différents niveaux de priorité.
    Les variables de configuration <xref linkend="guc-log-min-messages"/> et
    <xref linkend="guc-client-min-messages"/> contrôlent l'envoi de messages
    dans les traces, au client ou aux deux. Voir le
    <xref linkend="runtime-config"/> pour plus d'informations.
   </para>

   <para>
    Après <replaceable class="parameter">niveau</replaceable>, vous pouvez
    écrire un <replaceable class="parameter">format</replaceable>
    (qui doit être une chaîne litérale, pas une expression). La chaîne format
    indique le texte du message d'erreur à rapporter. Elle peut être suivie
    par des expressions optionnelles à insérer dans le message. Dans la chaîne,
    <literal>%</literal> est remplacé par la représentation de la valeur du
    prochain argument. Écrivez <literal>%%</literal> pour saisir un
    <literal>%</literal> litéral.
   </para>

   <para>
    Dans cet exemple, la valeur de <literal>v_job_id</literal> remplace le <literal>%</literal>
    dans la chaîne.
<programlisting>RAISE NOTICE 'Appel de cs_creer_job(%)', v_job_id;
</programlisting>
   </para>

   <para>
    Vous pouvez attacher des informations supplémentaires au rapport d'erreur
    en écrivant <literal>USING</literal> suivi par des éléments <replaceable
    class="parameter">option</replaceable> = <replaceable
    class="parameter">expression</replaceable>. Les mots clés autorisées pour
    <replaceable class="parameter">option</replaceable> sont
    <literal>MESSAGE</literal>, <literal>DETAIL</literal>,
    <literal>HINT</literal> et
    <literal>ERRCODE</literal>, alors que chaque <replaceable
    class="parameter">expression</replaceable> peut être une expression de type
    chaîne. <literal>MESSAGE</literal> configure le texte de l'erreur (cette
    option ne peut pas être utilisée sous la forme de <command>RAISE</command>
    qui inclut une chaîne de format avant <literal>USING</literal>).
    <literal>DETAIL</literal> fournit un message détaillé de l'erreur,
    <literal>HINT</literal> propose une astuce.
    <literal>ERRCODE</literal> indique le code d'erreur (SQLSTATE) à rapporter,
    soit par le nom de la condition comme indiquée dans <xref
    linkend="errcodes-appendix"/>, soit directement sous la forme d'un code
    SQLSTATE à cinq caractères.
   </para>

   <para>
    Cet exemple annulera la transaction avec le message d'erreur et l'astuce
    donnés&nbsp;:
<programlisting>
RAISE EXCEPTION 'Nonexistent ID --> %', user_id USING HINT = 'Please check your user id';
</programlisting>
   </para>

   <para>
    Ces deux exemples affichent des façons équivalents pour initialiser
    SQLSTATE&nbsp;:
<programlisting>
RAISE 'Duplicate user ID: %', user_id USING ERRCODE = 'unique_violation';
RAISE 'Duplicate user ID: %', user_id USING ERRCODE = '23505';
</programlisting>
   </para>

   <para>
    Il existe une deuxième syntaxe <command>RAISE</command> pour laquelle
    l'argument principale est le nom de la condition ou le SQLSTATE à rapporter,
    par exemple&nbsp;:
<programlisting>
RAISE division_by_zero;
RAISE SQLSTATE '22012';
</programlisting>
    Dans cette syntaxe, <literal>USING</literal> peut être utilisé pour fournir
    un message d'erreur, un détail ou une astuce personnalisé. Voici une autre
    façon de faire l'exemple précédent&nbsp;:
<programlisting>
RAISE unique_violation USING MESSAGE = 'Duplicate user ID: ' || user_id;
</programlisting>
   </para>

   <para>
    Une autre variante est d'écrire <literal>RAISE USING</literal> ou <literal>RAISE
    <replaceable class="parameter">niveau</replaceable> USING</literal> et de placer
    tout le reste dans la liste <literal>USING</literal>.
   </para>

   <para>
    La dernière variante de <command>RAISE</command> n'a aucun paramètre. Cette
    forme peut seulement être utilisée dans un bloc <literal>BEGIN</literal>
    d'une clause <literal>EXCEPTION</literal>&nbsp;; cela fait que l'erreur est
    renvoyée au prochain bloc englobant.
   </para>

   <para>
    Si aucun nom de condition ou SQLSTATE n'est indiqué dans une commande
    <command>RAISE EXCEPTION</command>, la valeur par défaut est d'utiliser
    <literal>RAISE_EXCEPTION</literal> (<literal>P0001</literal>). Si aucun
    message texte n'est indiqué, la valeur par défaut est d'utiliser le nom
    de la condition ou le SQLSTATE comme texte de message.
   </para>

   <note>
    <para>
     Lors de la spécification du code d'erreur par un code SQLSTATE, vous n'êtes
     pas limité aux codes d'erreur prédéfinis, mais pouvez sélectionner tout
     code d'erreur consistant en cinq chiffres et/ou des lettres ASCII
     majuscules, autre que <literal>00000</literal>. Il est recommandé d'éviter
     d'envoyer des codes d'erreur qui se terminent avec trois zéros car il y a
     des codes de catégorie, et peuvent seulement être récupérés en filtrant
     la catégorie complète.
    </para>
   </note>
 </sect1>

 <sect1 id="plpgsql-trigger">
  <title>Procédures trigger</title>

  <indexterm zone="plpgsql-trigger">
   <primary>déclencheur (trigger)</primary>
   <secondary>en PL/pgSQL</secondary>
  </indexterm>

  <para>
	<application>PL/pgSQL</application> peut être utilisé pour définir des 
	procédures trigger. Une procédure trigger est créée grâce à la commande
	<command>CREATE FUNCTION</command> utilisée comme fonction sans arguments
	ayant un type de retour <type>trigger</type>.  Notez que la fonction 
	doit être déclarée avec aucun argument même si elle s'attend à recevoir
	les arguments spécifiés dans <command>CREATE TRIGGER</command> &mdash;
	les arguments trigger sont passés via <varname>TG_ARGV</varname>, comme décrit plus
	loin.
  </para>

  <para>
   Quand une fonction <application>PL/pgSQL</application> est appelée en tant que
   trigger, plusieurs variables spéciales sont créées automatiquement dans le bloc de 
   plus haut niveau. Ce sont&nbsp;:

   <variablelist>
    <varlistentry>
     <term><varname>NEW</varname></term>
     <listitem>
      <para>
       Type de données <type>RECORD</type>&nbsp;; variable contenant la nouvelle ligne 
       de base de données pour les opérations <command>INSERT</command>/<command>UPDATE</command> 
       dans les triggers de niveau ligne. Cette variable est
       <symbol>NULL</symbol> dans un trigger de niveau instruction
       et pour les opérations <command>DELETE</command>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><varname>OLD</varname></term>
     <listitem>
      <para>
       Type de données <type>RECORD</type>&nbsp;; variable contenant l'ancienne ligne de 
       base de données pour les opérations <command>UPDATE</command>/<command>DELETE</command> 
       dans les triggers de niveau ligne. Cette variable est <symbol>NULL</symbol>
       dans les triggers de niveau instruction et pour les opérations
       <command>INSERT</command>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><varname>TG_NAME</varname></term>
     <listitem>
      <para>
       Type de données <type>name</type>&nbsp;; variable qui contient le nom du trigger réellement
       lancé.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><varname>TG_WHEN</varname></term>
     <listitem>
      <para>
       Type de données <type>text</type>&nbsp;; une chaîne, soit  <literal>BEFORE</literal>
       soit <literal>AFTER</literal>, selon la définition du trigger.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><varname>TG_LEVEL</varname></term>
     <listitem>
      <para>
       Type de données <type>text</type>&nbsp;; une chaîne, soit <literal>ROW</literal> soit
       <literal>STATEMENT</literal>, selon la définition du trigger.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><varname>TG_OP</varname></term>
     <listitem>
      <para>
       Type de données <type>text</type>&nbsp;; une chaîne, <literal>INSERT</literal>,
       <literal>UPDATE</literal>, <literal>DELETE</literal> ou
       <literal>TRUNCATE</literal>
       indiquant pour quelle opération le trigger a été lancé.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><varname>TG_RELID</varname></term>
     <listitem>
      <para>
       Type de données <type>oid</type>&nbsp;; l'ID de l'objet de la table qui a causé
       le déclenchement du trigger.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><varname>TG_RELNAME</varname></term>
     <listitem>
      <para>
       Type de données <type>name</type>&nbsp;; le nom de la table qui a causé
       le déclenchement. C'est obsolète et pourrait disparaître dans une
       prochaine version. À la place, utilisez <literal>TG_TABLE_NAME</literal>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><varname>TG_TABLE_NAME</varname></term>
     <listitem>
      <para>
       Type de données <type>name</type>&nbsp;; le nom de la table qui a
       déclenché le trigger.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><varname>TG_TABLE_SCHEMA</varname></term>
     <listitem>
      <para>
       Type de données <type>name</type>&nbsp;; le nom du schéma de la table qui
       a appelé le trigger.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><varname>TG_NARGS</varname></term>
     <listitem>
      <para>
       Type de données <type>integer</type>&nbsp;; le nombre d'arguments donnés à la procédure 
       trigger dans l'instruction <command>CREATE TRIGGER</command>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><varname>TG_ARGV[]</varname></term>
     <listitem>
      <para>
       Type de donnée <type>text</type>&nbsp;; les arguments de l'instruction 
       <command>CREATE TRIGGER</command>.
       L'index débute à 0. Les indices invalides (inférieurs à 0 ou supérieurs ou égaux
       à <varname>tg_nargs</varname>) auront une valeur NULL.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>

   <para>
    Une fonction trigger doit renvoyer soit <symbol>NULL</symbol> soit une
    valeur record ayant
    exactement la structure de la table pour laquelle le trigger a été lancé.
    </para>

   <para>
    Les triggers de niveau ligne lancés <literal>BEFORE</literal> peuvent renvoyer NULL 
    pour indiquer au gestionnaire de trigger de sauter le reste de l'opération pour
    cette ligne (les triggers suivants ne sont pas lancés, et les
    <command>INSERT</command>/<command>UPDATE</command>/<command>DELETE</command> ne se font pas pour cette 
    ligne). Si une valeur non NULL est renvoyée alors l'opération se déroule avec cette
    valeur ligne. Renvoyer une valeur ligne différente de la valeur originale de 
    <varname>NEW</varname> modifie la ligne qui sera insérée ou mise à jour (mais n'a
    pas d'effet sur le cas <command>DELETE</command>). Pour modifier la ligne à
    stocker, il est possible de remplacer des valeurs seules directement dans
    <varname>NEW</varname> et de renvoyer <varname>NEW</varname>, ou de construire un nouveau
    record/ligne à renvoyer.
   </para>

   <para>
    La valeur de retour d'un trigger de niveau instruction <literal>BEFORE</literal> ou
    <literal>AFTER</literal> ou un trigger de niveau ligne <literal>AFTER</literal> est
    toujours ignoré&nbsp;; il pourrait aussi bien être NULL. Néanmoins, tous les
    types de triggers peuvent toujours annuler l'opération complète en
    envoyant une erreur.
   </para>

   <para>
    L'<xref linkend="plpgsql-trigger-example"/> montre un exemple d'une procédure
    trigger dans <application>PL/pgSQL</application>.
   </para>

   <example id="plpgsql-trigger-example">
    <title>Une procédure trigger <application>PL/pgSQL</application> </title>

    <para>
     Cet exemple de trigger assure qu'à chaque moment où une ligne est insérée ou 
     mise à jour dans la table, le nom de l'utilisateur courant et l'heure sont estampillés 
     dans la ligne. Et cela vous assure qu'un nom d'employé est donné et que le salaire
     est une valeur positive.
    </para>

<programlisting>CREATE TABLE emp (
    nom_employe text,
    salaire integer,
    date_dermodif timestamp,
    utilisateur_dermodif text
);

CREATE FUNCTION emp_stamp() RETURNS trigger AS $emp_stamp$
    BEGIN
        -- Verifie que nom_employe et salary sont donnés
        IF NEW.nom_employe IS NULL THEN
            RAISE EXCEPTION 'nom_employe ne peut pas être NULL';
        END IF;
        IF NEW.salaire IS NULL THEN
            RAISE EXCEPTION '% ne peut pas avoir un salaire', NEW.nom_employe;
        END IF;

        -- Qui travaille pour nous si la personne doit payer pour cela ?
        IF NEW.salaire &lt; 0 THEN
            RAISE EXCEPTION '% ne peut pas avoir un salaire négatif', NEW.nom_employe;
        END IF;

        -- Rappelons-nous qui a changé le salaire et quand
        NEW.date_dermodif := current_timestamp;
        NEW.utilisateur_dermodif := current_user;
        RETURN NEW;
    END;
$emp_stamp$ LANGUAGE plpgsql;

CREATE TRIGGER emp_stamp BEFORE INSERT OR UPDATE ON emp
    FOR EACH ROW EXECUTE PROCEDURE emp_stamp();
</programlisting>
   </example>

   <para>
    Une autre façon de tracer les modifications sur une table implique la
    création d'une nouvelle table qui contient une ligne pour chaque
    insertion, mise à jour ou suppression qui survient. Cette approche peut
    être vue comme un audit des modifications sur une table.
    L'<xref linkend="plpgsql-trigger-audit-example"/> montre un exemple d'une
    procédure d'audit par trigger en <application>PL/pgSQL</application>.
   </para>
    
    <example id="plpgsql-trigger-audit-example">
      <title>Une procédure d'audit par trigger en
       <application>PL/pgSQL</application></title>
      
      <para>
        Cet exemple de trigger nous assure que toute insertion,
        modification ou suppression d'une ligne dans la table 
        <literal>emp</literal> est enregistrée dans la
        table <literal>emp_audit</literal>. L'heure et le nom de l'utilisateur
        sont conservées dans la ligne avec le type d'opération réalisé.
      </para>
      
<programlisting>CREATE TABLE emp (
    nom_employe       text NOT NULL,
    salaire           integer
);
        
CREATE TABLE emp_audit( 
    operation         char(1)   NOT NULL,
    tampon            timestamp NOT NULL,
    id_utilisateur    text      NOT NULL,
    nom_employe       text      NOT NULL,
    salaire           integer
);
        
CREATE OR REPLACE FUNCTION audit_employe() RETURNS TRIGGER AS $emp_audit$
BEGIN
    --
    -- Ajoute une ligne dans emp_audit pour refléter l'opération réalisée
    -- sur emp,
    -- utilise la variable spéciale TG_OP pour cette opération.
    --
    IF (TG_OP = 'DELETE') THEN
        INSERT INTO emp_audit SELECT 'D', now(), user, OLD.*;
        RETURN OLD;
    ELSIF (TG_OP = 'UPDATE') THEN
        INSERT INTO emp_audit SELECT 'U', now(), user, NEW.*;
        RETURN NEW;
    ELSIF (TG_OP = 'INSERT') THEN
        INSERT INTO emp_audit SELECT 'I', now(), user, NEW.*;
        RETURN NEW;
    END IF;
    RETURN NULL; -- le résultat est ignoré car il s'agit d'un trigger AFTER
END;
$emp_audit$ language plpgsql;
        
CREATE TRIGGER emp_audit
    AFTER INSERT OR UPDATE OR DELETE ON emp
    FOR EACH ROW EXECUTE PROCEDURE audit_employe();
</programlisting>
    </example>
    
    <para>
      Une utilisation des triggers est le maintien d'une table résumée
      d'une autre table. Le résumé résultant peut être utilisé à la place de
      la table originale pour certaines requêtes &mdash; souvent avec des
      temps d'exécution bien réduits. Cette technique est souvent utilisée
      pour les statistiques de données où les tables de données mesurées ou
      observées (appelées des tables de faits) peuvent être extrêmement
      grandes. L'<xref linkend="plpgsql-trigger-summary-example"/> montre un
      exemple d'une procédure trigger en
      <application>PL/pgSQL</application> maintenant une table résumée pour
      une table de faits dans un système de données (data warehouse).
      </para>
      
      
      <example id="plpgsql-trigger-summary-example">
        <title>Une procédure trigger <application>PL/pgSQL</application>
         pour maintenir une table résumée</title>
        
        <para>
          Le schéma détaillé ici est partiellement basé sur l'exemple du
          <emphasis>Grocery Store</emphasis> provenant de <emphasis>The Data
          Warehouse Toolkit</emphasis> par Ralph Kimball.
        </para>
        
<programlisting>--
-- Tables principales - dimension du temps de ventes.
--
CREATE TABLE time_dimension (
  time_key                    integer NOT NULL,
  day_of_week                 integer NOT NULL,
  day_of_month                integer NOT NULL,
  month                       integer NOT NULL,
  quarter                     integer NOT NULL,
  year                        integer NOT NULL
);
CREATE UNIQUE INDEX time_dimension_key ON time_dimension(time_key);
          
CREATE TABLE sales_fact (
  time_key                    integer NOT NULL,
  product_key                 integer NOT NULL,
  store_key                   integer NOT NULL,
  amount_sold                 numeric(12,2) NOT NULL,
  units_sold                  integer NOT NULL,
  amount_cost                 numeric(12,2) NOT NULL
);
CREATE INDEX sales_fact_time ON sales_fact(time_key);
          
--
-- Table résumé - ventes sur le temps.
--
CREATE TABLE sales_summary_bytime (
  time_key                    integer NOT NULL,
  amount_sold                 numeric(15,2) NOT NULL,
  units_sold                  numeric(12) NOT NULL,
  amount_cost                 numeric(15,2) NOT NULL
);
CREATE UNIQUE INDEX sales_summary_bytime_key ON sales_summary_bytime(time_key);
          
--
-- Fonction et trigger pour amender les colonnes résumées
-- pour un UPDATE, INSERT, DELETE.
--
CREATE OR REPLACE FUNCTION maint_sales_summary_bytime() RETURNS TRIGGER AS $maint_sales_summary_bytime$
DECLARE
  delta_time_key          integer;
  delta_amount_sold       numeric(15,2);
  delta_units_sold        numeric(12);
  delta_amount_cost       numeric(15,2);
BEGIN
          
  -- Travaille sur l'ajout/la suppression de montant(s).
  IF (TG_OP = 'DELETE') THEN
          
    delta_time_key = OLD.time_key;
    delta_amount_sold = -1 * OLD.amount_sold;
    delta_units_sold = -1 * OLD.units_sold;
    delta_amount_cost = -1 * OLD.amount_cost;
          
  ELSIF (TG_OP = 'UPDATE') THEN
          
    -- interdit les mises à jour qui modifient time_key -
    -- (probablement pas trop cher, car DELETE + INSERT est la façon la plus
    -- probable de réaliser les modifications).
    IF ( OLD.time_key != NEW.time_key) THEN
      RAISE EXCEPTION 'Update of time_key : % -&gt; % not allowed', OLD.time_key, NEW.time_key;
    END IF;

    delta_time_key = OLD.time_key;
    delta_amount_sold = NEW.amount_sold - OLD.amount_sold;
    delta_units_sold = NEW.units_sold - OLD.units_sold;
    delta_amount_cost = NEW.amount_cost - OLD.amount_cost;

  ELSIF (TG_OP = 'INSERT') THEN

    delta_time_key = NEW.time_key;
    delta_amount_sold = NEW.amount_sold;
    delta_units_sold = NEW.units_sold;
    delta_amount_cost = NEW.amount_cost;

  END IF;


  -- Insertion ou mise à jour de la ligne de résumé avec les nouvelles valeurs.
  &lt;&lt;insert_update&gt;&gt;
  LOOP
  UPDATE sales_summary_bytime
  SET amount_sold = amount_sold + delta_amount_sold,
    units_sold = units_sold + delta_units_sold,
    amount_cost = amount_cost + delta_amount_cost
    WHERE time_key = delta_time_key;

    EXIT insert_update WHEN found;

    BEGIN
      INSERT INTO sales_summary_bytime (
        time_key, 
        amount_sold, 
        units_sold, 
        amount_cost)
        VALUES ( 
        delta_time_key,
        delta_amount_sold,
        delta_units_sold,
        delta_amount_cost
        );
      EXIT insert_update;

      EXCEPTION
      WHEN UNIQUE_VIOLATION THEN
      -- do nothing
      END;
      END LOOP insert_update;

  RETURN NULL;

END;
$maint_sales_summary_bytime$ LANGUAGE plpgsql;

CREATE TRIGGER maint_sales_summary_bytime
  AFTER INSERT OR UPDATE OR DELETE ON sales_fact
  FOR EACH ROW EXECUTE PROCEDURE maint_sales_summary_bytime();

INSERT INTO sales_fact VALUES(1,1,1,10,3,15);
INSERT INTO sales_fact VALUES(1,2,1,20,5,35);
INSERT INTO sales_fact VALUES(2,2,1,40,15,135);
INSERT INTO sales_fact VALUES(2,3,1,10,1,13);
SELECT * FROM sales_summary_bytime;
DELETE FROM sales_fact WHERE product_key = 1;
SELECT * FROM sales_summary_bytime;
UPDATE sales_fact SET units_sold = units_sold * 2;
SELECT * FROM sales_summary_bytime;
</programlisting>
      </example>

    </sect1>

  <sect1 id="plpgsql-implementation">
   <title>Les dessous de <application>PL/pgSQL</application></title>

   <para>
    Cette section discute des détails d'implémentation les plus importants
    à connaître pour les utilisateurs de <application>PL/pgSQL</application>.
   </para>

  <sect2 id="plpgsql-var-subst">
   <title>Substitution de variables</title>

   <para>
    Quand <application>PL/pgSQL</application> prépare l'exécution d'une
    instruction SQL ou d'une expression, tout nom de variable
    <application>PL/pgSQL</application> apparaissant dans l'instruction ou
    l'expression est remplacée par un symbole de paramètre,
    <literal>$<replaceable>n</replaceable></literal>. La valeur actuelle de
    la variable est alors fournie en tant que valeur du paramètre quand
    l'instruction ou l'expression est exécutée. Comme exemple, considérez
    la fonction suivante&nbsp;:
<programlisting>
CREATE FUNCTION logfunc(logtxt text) RETURNS void AS $$
    DECLARE
        curtime timestamp := now();
    BEGIN
        INSERT INTO logtable VALUES (logtxt, curtime);
    END;
$$ LANGUAGE plpgsql;
</programlisting>
    L'instruction <command>INSERT</command> sera en fait traitée comme&nbsp;:
<programlisting>
PREPARE <replaceable>nom_instruction</replaceable>(text, timestamp) AS
  INSERT INTO logtable VALUES ($1, $2);
</programlisting>
    suivie par chaque exécution (<command>EXECUTE</command>) avec les
    valeurs réelles des deux variables. (Note&nbsp;: ici nous parlons de la commande
    <xref linkend="sql-execute" endterm="sql-execute-title"/> du moteur SQL,
    pas du <command>EXECUTE</command> de <application>PL/pgSQL</application>.)
   </para>

   <para>
    <emphasis>Le mécanisme de substitution remplacera tout jeton qui correspond
    au nom d'une variable connue.</emphasis> Ceci est un risque pour le débutant.
    Par exemple, c'est une mauvaise idée d'utiliser un nom de variable qui est
    identique à un nom de table ou de colonne que vous comptez référencer dans
    les requêtes d'une fonction car ce que vous pensez être un nom de table ou
    de colonne sera toujours remplacé. Dans l'exemple ci-dessus, supposez que
    <structname>logtable</structname> a les colonnes
    <structfield>logtxt</structfield> et <structfield>logtime</structfield>,
    et que nous essayons d'écrire un <command>INSERT</command> ainsi&nbsp;:
<programlisting>
        INSERT INTO logtable (logtxt, logtime) VALUES (logtxt, curtime);
</programlisting>
    Ceci sera renvoyé à l'analyseur SQL de cette façon&nbsp;:
<programlisting>
        INSERT INTO logtable ($1, logtime) VALUES ($1, $2);
</programlisting>
    résultant en l'erreur de syntaxe suivante&nbsp;:
<screen>
ERROR:  syntax error at or near "$1"
LINE 1: INSERT INTO logtable ( $1 , logtime) VALUES ( $1 ,  $2 )
                               ^
QUERY:  INSERT INTO logtable ( $1 , logtime) VALUES ( $1 ,  $2 )
CONTEXT:  SQL statement in PL/PgSQL function "logfunc2" near line 5
</screen>
   </para>

   <para>
    Cet exemple est assez simple à diagnostiquer car il ramène une erreur de
    syntaxe évidente. Il existe des cas plus complexes où la substitution est
    syntaxiquement autorisée car le seul symptome est un comportement erroné
    de la fonction. Dans un cas, un utilisateur avait écrit ceci&nbsp;:
<programlisting>
    DECLARE
        val text;
        search_key integer;
    BEGIN
        ...
        FOR val IN SELECT val FROM table WHERE key = search_key LOOP ...
</programlisting>
    et se demandait pourquoi toutes ses entrées de table semblaient valoir
    NULL. Bien sûr, ce qui était survenu était la transformation suivante
    de la requête&nbsp;:
<programlisting>
        SELECT $1 FROM table WHERE key = $2
</programlisting>
    et, du coup, c'était juste une façon complexe d'affecter la valeur courante
    de <literal>val</literal> à elle-même pour chaque ligne.
   </para>

   <para>
    Une règle de codage généralement acceptée pour éviter ce type de problème
    est d'utiliser une convention de nommage différente pour les variables
    <application>PL/pgSQL</application> et pour celles de vos tables et
    colonnes. Par exemple, si toutes vos variables sont nommées
    <literal>v_<replaceable>quelquechose</replaceable></literal> alors qu'aucune
    de vos tables ou colonnes ne commence par <literal>v_</literal>, le risque
    est bien moindre.
   </para>

   <para>
    Un autre contournement est d'utiliser des noms qualifiés pour les entités
    SQL. Par exemple, l'exemple suivant peut être ré-écrit de la façon
    suivante&nbsp;:
<programlisting>
        FOR val IN SELECT table.val FROM table WHERE key = search_key LOOP ...
</programlisting>
    parce que <application>PL/pgSQL</application> ne substitutera pas une
    variable pour le composant de fin d'un nom qualifié. Néanmoins, cette
    solution ne fonctionne pas dans tous les cas &mdash; vous ne pouvez pas
    qualifier un nom dans la liste des colonnes d'une commande
    <command>INSERT</command> par exemple. Un autre point est que les noms
    de variables record ou ligne correspondront aux premiers composants des
    noms qualifiés, donc un nom SQL qualifié est toujours vulnérable dans
    certains cas. En fait, dans certains cas, choisir un nom de variable
    sans conflit est le seul moyen.
   </para>

   <para>
    Une autre technique que vous pouvez utiliser est d'attacher un label au
    bloc dans lequel sont déclarées vos variables, puis de qualifier les noms
    des variables dans vos commandes SQL (voir la <xref linkend="plpgsql-structure"/>).
    Par exemple&nbsp;:
<programlisting>
    &lt;&lt;pl&gt;&gt;
    DECLARE
        val text;
    BEGIN
        ...
        UPDATE table SET col = pl.val WHERE ...
</programlisting>
    Ce n'est pas en soi une solution au problème des conflits car un nom non
    qualifié dans une commande SQL courera toujours le risque d'être interprétée
    de la <quote>mauvaise</quote> façon. Par contre, c'est utile pour clarifier
    le but d'un code potentiellement ambigü.
   </para>

   <para>
    La substitution de variable n'arrive pas dans la chaîne de commande donnée
    à <command>EXECUTE</command> ou une de ces variantes. Si vous avez
    besoin d'insérer une valeur dans une telle commande, faites-le lors de la
    construction d'une valeur de chaîne, illustrée dans la
    <xref linkend="plpgsql-statements-executing-dyn"/>.
   </para>

   <para>
    La substitution de variable fonctionne seulement dans les commandes
    <command>SELECT</command>, <command>INSERT</command>, <command>UPDATE</command>
    et <command>DELETE</command> parce que le moteur SQL principal autorise
    les symboles de paramètres seulement dans ces commandes. Pour utiliser un
    nom variable ou une valeur dans les autres types d'instructions (généralement
    appelées des instructions utilitaires), vous devez construire l'instruction
    en question comme une chaîne et l'exécuter via <command>EXECUTE</command>.
   </para>

  </sect2>

  <sect2 id="plpgsql-plan-caching">
   <title>Mise en cache du plan</title>

   <para>
    L'interpréteur <application>PL/pgSQL</application> analyse le source d'une
    fonction et produit un arbre binaire interne d'instructions la première fois
    que la fonction est appelée (à l'intérieur de chaque session). L'arbre des
    instructions se traduit complètement par la structure d'instructions
    <application>PL/pgSQL</application> mais les expressions et les commandes
    <acronym>SQL</acronym> individuelles utilisées dans la fonction ne sont
    pas traduites immédiatement.
   </para>

   <para>
    Au moment où chaque expression et commande <acronym>SQL</acronym> est
    exécutée en premier lieu dans la fonction, l'interpréteur
    <application>PL/pgSQL</application> crée un plan d'exécution préparée (en
    utilisant les fonctions <function>SPI_prepare</function> et
    <function>SPI_saveplan</function> du gestionnaire
    <acronym>SPI</acronym> ).
    <indexterm><primary>préparer une requête</primary><secondary>en
    PL/pgSQL</secondary></indexterm>
    Les appels suivants à cette expression ou commande réutilisent le plan
    préparé. Du coup, une fonction avec du code conditionnel contenant de
    nombreuses instructions pour lesquels les plans d'exécutions pourraient
    être requis vont seulement préparer et sauvegarder ces plans qui sont
    utilisés tout au long de la durée de vie de la connexion à la base de
    données. Ceci peut réduire substantiellement le temps total requis
    pour analyser et générer les plans d'exécution pour les instructions
    d'une fonction <application>PL/pgSQL</application>. Un inconvénient
    est que les erreurs dans une expression ou commande spécifique ne peuvent
    pas être détectées avant que la fonction a atteint son exécution. (Les
    erreurs de syntaxe triviales seront détectées à la première passe d'analyse
    mais quelque chose de plus complexe ne sera pas détecté avant son
    exécution.)
   </para>

   <para>
    Une fois que <application>PL/pgSQL</application> a réalisé un plan
    d'exécution pour une commande particulière d'une fonction, il ré-utilisera
    ce plan pour toute la durée de vie de la connexion à la base. Ceci est
    un gain majeur pour les performances mais cela posera des problèmes si
    vous modifiez dynamiquement votre schéma de bases de données. Par
    exemple&nbsp;:

<programlisting>
CREATE FUNCTION peupler() RETURNS integer AS $$
DECLARE
    -- declarations
BEGIN
    PERFORM ma_fonction();
END;
$$ LANGUAGE plpgsql;
</programlisting>

    Si vous exécutez la fonction ci-dessus, elle référencera l'OID de la fonction
    <function>ma_fonction()</function> dans le plan d'exécution produit par
    l'instruction <command>PERFORM</command>. Plus tard, si vous supprimez
    puis re-créez la fonction <function>ma_fonction()</function>, alors
    <function>peupler()</function> ne sera plus capable de trouver
    <function>ma_fonction()</function>. Vous devrez alors commencer une
    nouvelle session à la base de données pour que <function>peupler()</function>
    soit compilée de nouveau et qu'elle soit de nouveau
    utilisable. Vous pouvez éviter ce problème en utilisant <command>CREATE
    OR REPLACE FUNCTION</command> lors de la mise à jour de la définition de
<function>ma_fonction</function> car, quand une fonction est
    <quote>remplacée</quote>, son OID n'est pas modifié.
   </para>

   <note>
    <para>
     Dans <productname>PostgreSQL</productname> 8.3 et ultérieur, les plans
     sauvegardés peuvent être remplacés quand des modifications du schéma
     surviennent sur les tables qu'elles référencent. Ceci élimine un des
     gros inconvénients des plans sauvegardés. Néanmoins, il n'existe pas
     le même type de mécanisme pour les références de fonction. Du coup,
     l'exemple ci-dessus impliquant la référence a une fonction supprimée
     est toujours valide.
    </para>
   </note>

   <para>
    Comme <application>PL/pgSQL</application> sauvegarde les plans d'exécution
    de cette façon, les commandes SQL qui apparaissent directement dans une
    fonction <application>PL/pgSQL</application> doivent faire référence aux
    même tables et aux mêmes colonnes à chaque exécution&nbsp;; c'est-à-dire
    que vous ne pouvez pas utiliser un paramètre comme le nom d'une table ou
    d'une colonne dans une commande SQL. Pour contourner cette restriction,
    vous pouvez construire des commandes dynamiques en utilisant l'instruction
    <command>EXECUTE</command> de <application>PL/pgSQL</application>
    &mdash; au prix de la construction d'un nouveau plan d'exécution à chaque
    exécution.
   </para>

   <para>
    Un autre point important est que les plans préparés utilisent des paramètres
    pour permettre le changement des valeurs des variables
    <application>PL/pgSQL</application> entre chaque exécution, comme indiqué
    en détail ci-dessus. Quelque fois, cela signifie qu'un plan est moins
    efficace que s'il avait été généré avec une valeur spécifique. Comme exemple,
    regardez&nbsp;:
<programlisting>
SELECT * INTO mon_enregistrement FROM dictionnaire WHERE mot LIKE terme_recherche;
</programlisting>
    où <literal>terme_recherche</literal> est une variable
    <application>PL/pgSQL</application>. Le plan caché pour cette requête
    n'utilisera jamais un index sur une variable. Le plan caché pour cette
    requête n'utilisera jamais un index sur un <structfield>mot</structfield>
    car le planificateur ne peut pas savoir si le modèle <literal>LIKE</literal>
    comprendra une ancre à gauche à l'exécution. Pour utiliser un index, la
    requête doit être planifiée avec un modèle spécifique pour <literal>LIKE</literal>.
    C'est un autre cas où <command>EXECUTE</command> peut être utilisé pour
    forcer la génération d'un nouveau plan à chaque exécution.
   </para>

    <para>
     La nature muable des variables de type record présente un autre problème
     dans cette connexion. Quand les champs d'une variable record sont utilisés
     dans les expressions ou instructions, les types de données des champs
     ne doivent pas modifier d'un appel de la fonction à un autre car chaque
     expression sera planifiée en utilisant le type de données qui est présent
     quand l'expression est atteinte en premier. <command>EXECUTE</command> peut
     être utilisé pour contourner ce problème si nécessaire.
    </para>

    <para>
     Si la même fonction est utilisée comme trigger pour plus d'une table,
     <application>PL/pgSQL</application> prépare et met en cache les plans
     indépendament pour chacune de ses tables &mdash; c'est-à-dire qu'il y a
     un cache pour chaque combinaison fonction trigger/table, pas
     uniquement pour chaque fonction. Ceci diminue certains des problèmes avec
     les types de données variables&nbsp;; par exemple, une fonction trigger
     pourra fonctionner correctement avec une colonne nommée
     <literal>cle</literal> même si cette colonne a différents types dans
     différentes tables.
    </para>

    <para>
     De la même façon, les fonctions ayant des types polymorphiques pour les
     arguments ont un cache séparé des plans pour chaque combinaison des types
     d'argument réél avec lesquels elles ont été appelées, donc les différences
     de type de données ne causent pas d'échecs inattendus.
    </para>

   <para>
    La mise en cache du plan peut parfois avoir des effets surprenants sur
    l'interprétation des valeurs sensibles à l'heure. Par exemple, il y a une
    différence entre ce que font ces deux fonctions&nbsp;:

<programlisting>
CREATE FUNCTION logfunc1(logtxt text) RETURNS void AS $$
    BEGIN
        INSERT INTO logtable VALUES (logtxt, 'now');
    END;
$$ LANGUAGE plpgsql;
</programlisting>

     et&nbsp;:

<programlisting>
CREATE FUNCTION logfunc2(logtxt text) RETURNS void AS $$
    DECLARE
        curtime timestamp;
    BEGIN
        curtime := 'now';
        INSERT INTO logtable VALUES (logtxt, curtime);
    END;
$$ LANGUAGE plpgsql;
</programlisting>
    </para>

    <para>
     Dans le cas de <function>logfunc1</function>, l'analyseur principal de
     <productname>PostgreSQL</productname> sait que, au moment de la préparation
     du plan pour <command>INSERT</command>, la chaîne <literal>'now'</literal>
     devra être interprétée comme une valeur de type <type>timestamp</type> car
     la colonne cible de <classname>logtable</classname> est de ce type. Du
     coup, <literal>'now'</literal> sera converti en une constante quand
     <command>INSERT</command> est planifié, puis utilisé dans tous les appels
     à <function>logfunc1</function> lors de la durée de vie de la session.
     Il n'est pas nécessaire de préciser que ce n'est pas le souhait du
     développeur.
    </para>

    <para>
     Dans le cas de <function>logfunc2</function>, l'analyseur principal de
     <productname>PostgreSQL</productname> ne connaît pas le type que deviendra
     <literal>'now'</literal> et, du coup, il renvoie une valeur de type
     <type>text</type> contenant la chaîne <literal>now</literal>. Lors de
     l'affectation à la variable <varname>curtime</varname> locale, l'interpréteur
     <application>PL/pgSQL</application> convertie cette chaîne dans le type
     <type>timestamp</type> en appelant les fonctions <function>text_out</function>
     et <function>timestamp_in</function> pour la conversion. Du coup, l'heure
     calculée est mise à jour à chaque exécution comme le suppose le développeur.
    </para>

  </sect2>

  </sect1>

 <sect1 id="plpgsql-development-tips">
  <title>Astuces pour développer en <application>PL/pgSQL</application></title>

   <para>
    Un bon moyen de développer en <application>PL/pgSQL</application> est d'utiliser
    l'éditeur de texte de votre choix pour créer vos fonctions, et d'utiliser 
    <application>psql</application> dans une autre fenêtre pour charger et tester
    ces fonctions. Si vous procédez ainsi, une bonne idée est d'écrire la fonction 
    en utilisant <command>CREATE OR REPLACE FUNCTION</command>. De cette façon vous pouvez simplement
    recharger le fichier pour mettre à jour la définition de la fonction.
    Par exemple&nbsp;:
<programlisting>CREATE OR REPLACE FUNCTION fonction_test(integer) RETURNS integer AS $$
	  ....
$$ LANGUAGE plpgsql;
</programlisting>
   </para>

   <para>
    Pendant que <application>psql</application> s'exécute, vous pouvez charger
    ou recharger des définitions de fonction avec&nbsp;:
    <programlisting>\i nom_fichier.sql
</programlisting>
    puis immédiatement soumettre des commandes SQL pour tester la fonction.
   </para>

   <para>
    Un autre bon moyen de développer en <application>PL/pgSQL</application> est d'utiliser
    un outil d'accès à la base de données muni d'une interface graphique qui facilite le
    développement dans un langage de procédures. Un exemple d'un tel outil est
    <application>pgAdmin</application>, bien que d'autres existent. Ces outils fournissent 
    souvent des fonctionnalités pratiques telles que la détection des guillemets ouverts
    et facilitent la re-création et le débogage des fonctions.
   </para>

  <sect2 id="plpgsql-quote-tips">
   <title>Utilisation des guillemets simples (quotes)</title>

  <para>
   Le code d'une fonction <application>PL/pgSQL</application> est spécifié dans la commande
   <command>CREATE FUNCTION</command> comme une chaîne de caractères.
   Si vous écrivez la chaîne littérale de la façon ordinaire en l'entourant
   de guillemets simples, alors tout guillemet simple dans le corps de la
   fonction doit être doublé&nbsp;; de la même façon, les antislashs doivent
   être doublés (en supposant que la syntaxe d'échappement de chaînes est
   utilisée). Doubler les guillemets devient rapidement difficile et, dans
   la plupart des cas compliqués, le code peut devenir rapidement
   incompréhensible parce que vous pouvez facilement vous trouver avec
   une douzaine, voire plus, de guillemets adjacents. À la place, il est
   recommandé d'écrire le corps de la fonction en tant qu'une chaîne littérale
   <quote>avec guillemets dollar</quote> (voir la <xref
   linkend="sql-syntax-dollar-quoting"/>). Dans cette approche, vous ne doublez
   jamais les marques de guillemets mais vous devez faire attention à
   choisir un délimiteur dollar différent pour chaque niveau d'imbrication
   dont vous avez besoin. Par exemple, vous pouvez écrire la commande
   <command>CREATE FUNCTION</command> en tant que&nbsp;:
<programlisting>CREATE OR REPLACE FUNCTION fonction_test(integer) RETURNS integer AS $PROC$
   ....
$PROC$ LANGUAGE plpgsql;
</programlisting>
   À l'intérieur de ceci, vous pouvez utiliser des guillemets pour les
   chaînes littérales simples dans les commandes SQL et <literal>$$</literal> pour
   délimiter les fragments de commandes SQL que vous assemblez comme des
   chaînes. Si vous avez besoin de mettre entre guillemets du texte qui inclut
   <literal>$$</literal>, vous pouvez utiliser <literal>$Q$</literal>, et ainsi de suite.
  </para>

  <para>
   Le graphe suivant montre ce que vous devez faire lors de l'écriture de
   guillemets simples sans guillemets dollar. Cela pourrait être utile lors
   de la traduction de code avec guillemets simples en quelque chose de
   plus compréhensible.
  </para>

  <variablelist>
   <varlistentry>
    <term>1 guillemet simple</term>
    <listitem>
     <para>
      Pour commencer et terminer le corps de la fonction, par exemple&nbsp;:
<programlisting>CREATE FUNCTION foo() RETURNS integer AS '
	.....
' LANGUAGE plpgsql;
</programlisting>
      Partout au sein du corps de la fonction entouré de guillemets simples,
      les guillemets simples <emphasis>doivent</emphasis> aller par paires.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>2 guillemets simples</term>
    <listitem>
     <para>
      Pour les chaînes de caractères à l'intérieur du corps de la fonction, par
      exemple&nbsp;:
<programlisting>une_sortie := ''Blah'';
SELECT * FROM utilisateurs WHERE f_nom=''foobar'';
</programlisting>
      Dans l'approche du guillemet dollar, vous devriez juste écrire&nbsp;:
<programlisting>une_sortie := 'Blah';
SELECT * FROM utilisateurs WHERE f_nom='foobar';
</programlisting>
      ce qui serait exactement ce que l'analyseur <application>PL/pgSQL</application> verrait dans les
      deux cas.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>4 guillemets simples</term>
    <listitem>
     <para>
      Quand vous avez besoin d'un guillemet simple dans une chaîne constante 
      à l'intérieur du corps de la fonction, par exemple&nbsp;:
<programlisting>une_sortie := une_sortie || '' AND nom LIKE ''''foobar'''' AND xyz''
</programlisting>
      La valeur effectivement concaténée à <literal>une_sortie</literal> 
      est&nbsp;:
      <literal> AND nom LIKE 'foobar' AND xyz</literal>.
     </para>
     <para>
      Dans l'approche du guillemet dollar, vous auriez écrit&nbsp;:
<programlisting>une_sortie := une_sortie || $$ AND nom LIKE 'foobar' AND xyz$$
</programlisting>
     Faites attention que chaque délimiteur en guillemet dollar ne soient pas
     simplement <literal>$$</literal>.
</para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>6 guillemets simples</term>
    <listitem>
     <para>
      Quand un simple guillemet dans une chaîne à l'intérieur du corps d'une fonction
      est adjacent à la fin de cette chaîne constante, par exemple&nbsp;:
<programlisting>une_sortie := une_sortie || '' AND nom LIKE ''''foobar''''''
</programlisting>
      La valeur effectivement concaténée à <literal>une_sortie</literal> est
alors&nbsp;:
      <literal> AND nom LIKE 'foobar'</literal>.
     </para>
     <para>
      Dans l'approche guillemet dollar, ceci devient&nbsp;:
<programlisting>une_sortie := une_sortie || $$ AND nom LIKE 'foobar'$$
</programlisting>
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>10 guillemets simples</term>
    <listitem>
     <para>
      Lorsque vous voulez deux guillemets simples dans une chaîne constante (qui
      compte pour huit guillemets simples) et qu'elle est adjacente à la fin de
      cette chaîne constante (deux de plus). Vous n'aurez probablement besoin de
      ceci que si vous écrivez une fonction qui génère d'autres fonctions comme
      dans l'<xref linkend="plpgsql-porting-ex2"/>. Par exemple&nbsp;:
      <programlisting>une_sortie := une_sortie || '' if v_'' || 
    referrer_keys.kind || '' like '''''''''' 
    || referrer_keys.key_string || '''''''''' 
    then return ''''''  || referrer_keys.referrer_type 
    || ''''''; end if;''; 
</programlisting>
      La valeur de <literal>une_sortie</literal> sera alors&nbsp;:
<programlisting>if v_... like ''...'' then return ''...''; end if;
</programlisting>
     </para>
     <para>
      Dans l'approche du guillemet dollar, ceci devient&nbsp;:
<programlisting>une_sortie := une_sortie || $$ if v_$$ || referrer_keys.kind || $$ like '$$
|| referrer_keys.key_string || $$'
then return '$$  || referrer_keys.referrer_type 
|| $$'; end if;$$; 
</programlisting>
      où nous supposons que nous avons seulement besoin de placer des marques
      de guillemets simples dans <literal>une_sortie</literal> parce que les
      guillemets seront recalculés avant utilisation.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>

  </sect2>
 </sect1>

  <!-- **** Porting from Oracle PL/SQL **** -->

 <sect1 id="plpgsql-porting">
  <title>Portage d'<productname>Oracle</productname> PL/SQL</title>

  <indexterm zone="plpgsql-porting">
   <primary>Oracle</primary>
   <secondary>porter de PL/SQL vers PL/pgSQL</secondary>
  </indexterm>

  <indexterm zone="plpgsql-porting">
   <primary>PL/SQL</primary>
   <secondary>porter vers PL/pgSQL</secondary>
  </indexterm>

  <para>
   Cette section explicite les différences entre le <application>PL/pgSQL</application>
   de <productname>PostgreSQL</productname> et le langage <application>PL/SQL</application>
   d'Oracle, afin d'aider les développeurs qui portent des applications d'<trademark
   class="registered">Oracle</trademark> vers <productname>PostgreSQL</productname>.
  </para>

  <para>
   <application>PL/pgSQL</application> est similaire à PL/SQL sur de nombreux aspects.
   C'est un langage itératif structuré en blocs et toutes les variables doivent
   être déclarées. Les affectations, boucles, conditionnelles sont similaires. Les 
   principales différences que vous devez garder à l'esprit quand vous portez de 
   <application>PL/SQL</application> vers <application>PL/pgSQL</application> sont:

    <itemizedlist>
     <listitem>
      <para>
       Si un nom utilisé dans une commande SQL peut être soit un nom de colonne
       d'une table soit une référence à une variable de la fonction,
       <application>PL/SQL</application> le traite comme un nom de commande
       alors que <application>PL/pgSQL</application> le traite comme un nom de
       variable. Il est préférable d'éviter les ambiguïtés en premier mais, si
       c'est nécessaire, vous pouvez corriger cela en qualifiant correctement
       le nom ambigü. (Voir <xref linkend="plpgsql-var-subst"/>.)
      </para>
     </listitem>

     <listitem>
      <para>
       Dans <productname>PostgreSQL</productname>, le corps de la fonction doit être
       écrit comme une chaîne litérale. Du coup, vous avez besoin d'utiliser
       les guillemets dollar ou l'échappement des simples guillemets dans le
       corps de la fonction. Voir la <xref linkend="plpgsql-quote-tips"/>.
      </para>
     </listitem>

     <listitem>
      <para>
       À la place des paquetages, utilisez des schémas pour organiser vos fonctions en
       groupes.
       </para>
     </listitem>

     <listitem>
      <para>
       Comme il n'y a pas de paquetages, il n'y a pas non plus de variables
       au niveau paquetage. Ceci est un peu ennuyant. Vous pourriez être capable
       de conserver un état par session dans les tables temporaires à la place.
     </para>
     </listitem>

     <listitem>
      <para>
       Les boucles <command>FOR</command> d'entiers en ordre inverse
       (<literal>REVERSE</literal>) fonctionnent différemment&nbsp;;
       <application>PL/SQL</application> compte du second numéro jusqu'au
       premier alors que <application>PL/pgSQL</application> compte du
       premier jusqu'au second, ceci réclamant que les limites de la
       boucle soient échangées lors du portage. Cette incompatibilité
       est malheureuse mais a peu de chance d'être changée. (Voir <xref
       linkend="plpgsql-integer-for"/>.)
      </para>
     </listitem>

     <listitem>
      <para>
       Les boucles <command>FOR</command> sur des requêtes (autres que des
       curseurs) fonctionnent aussi différemment&nbsp;: la variable cible doit
       avoir été déclarée alors que <application>PL/SQL</application> les déclare
       toujours implicitement. Un avantage de ceci est que les valeurs des
       variables sont toujours accessibles à la sortie de la boucle.
      </para>
     </listitem>

     <listitem>
      <para>
       Il existe plusieurs différences de notation pour l'utilisation des
       variables curseurs.
      </para>
     </listitem>

    </itemizedlist>
   </para>

  <sect2>
   <title>Exemples de portages</title>

   <para>
    L'<xref linkend="pgsql-porting-ex1"/> montre comment porter une simple fonction
    de <application>PL/SQL</application> vers <application>PL/pgSQL</application>.
   </para>

   <example id="pgsql-porting-ex1">
    <title>Portage d'une fonction simple de <application>PL/SQL</application> vers <application>PL/pgSQL</application></title>

    <para>
     Voici une fonction en <application>PL/SQL</application>
     <productname>Oracle</productname>&nbsp;:
<programlisting>CREATE OR REPLACE FUNCTION cs_fmt_browser_version(v_name varchar, v_version varchar)
RETURN varchar IS
BEGIN
    IF v_version IS NULL THEN
        RETURN v_name;
    END IF;
    RETURN v_name || '/' || v_version;
END;
/
show errors;
</programlisting>
    </para>

    <para>
     Parcourons cette fonction et voyons les différences avec
     <application>PL/pgSQL</application>&nbsp;:

     <itemizedlist>
      <listitem>
       <para>
        Le mot clé <literal>RETURN</literal> dans le prototype de la fonction (pas dans
	le corps de la fonction) devient <literal>RETURNS</literal> dans PostgreSQL.
	De plus, <literal>IS</literal> devient <literal>AS</literal> et vous avez besoin d'ajouter
	une clause <literal>LANGUAGE</literal> parce que <application>PL/pgSQL</application> n'est pas
	le seul langage de procédures disponible.
       </para>
      </listitem>

      <listitem>
       <para>
        Dans <productname>PostgreSQL</productname>, le corps de la fonction est
        considéré comme une chaîne littérale, donc vous avez besoin d'utiliser
        les guillemets simples ou les guillemets dollar tout autour. Ceci se
        substitue au <literal>/</literal> de fin dans l'approche d'Oracle.
       </para>
      </listitem>

      <listitem>
       <para>
        La commande <literal>show errors</literal> n'existe pas dans
        <productname>PostgreSQL</productname> et n'est pas nécessaire car les erreurs
        sont rapportées automatiquement.
       </para>
      </listitem>
     </itemizedlist>
    </para>

    <para>
     Voici de quoi aurait l'air cette fonction portée sous 
     <productname>PostgreSQL</productname>&nbsp;:

<programlisting>CREATE OR REPLACE FUNCTION cs_fmt_browser_version(v_name varchar, v_version varchar)
RETURNS varchar AS $$
BEGIN
    IF v_version IS NULL THEN
        return v_name;
    END IF;
    RETURN v_name || '/' || v_version;
END;
$$ LANGUAGE plpgsql;
</programlisting>
    </para>
   </example>

   <para>
    L'<xref linkend="plpgsql-porting-ex2"/> montre comment porter une fonction qui crée une
    autre fonction et comment gérer les problèmes de guillemets résultants.
   </para>
 
   <example id="plpgsql-porting-ex2">
    <title>Portage d'une fonction qui crée une autre fonction de <application>PL/SQL</application> vers <application>PL/pgSQL</application></title>

    <para>
     La procédure suivante récupère des lignes d'une instruction <command>SELECT</command>
     et construit une grande fonction dont les résultats sont dans une instruction
     <literal>IF</literal> pour favoriser l'efficacité.
    </para>

    <para>
     Voici la version Oracle&nbsp;:
<programlisting>CREATE OR REPLACE PROCEDURE cs_update_referrer_type_proc IS
    CURSOR referrer_keys IS 
        SELECT * FROM cs_referrer_keys 
	ORDER BY try_order;

    func_cmd VARCHAR(4000); 
BEGIN 
    func_cmd := 'CREATE OR REPLACE FUNCTION cs_find_referrer_type(v_host IN VARCHAR,
        v_domain IN VARCHAR, v_url IN VARCHAR) RETURN VARCHAR IS BEGIN'; 

    FOR referrer_key IN referrer_keys LOOP 
        func_cmd := func_cmd ||
        ' IF v_' || referrer_key.kind
	|| ' LIKE ''' || referrer_key.key_string
	|| ''' THEN RETURN ''' || referrer_key.referrer_type
	|| '''; END IF;'; 
    END LOOP; 

    func_cmd := func_cmd || ' RETURN NULL; END;'; 

    EXECUTE IMMEDIATE func_cmd; 
END; 
/ 
show errors;
</programlisting>
    </para>

    <para>
     Voici comment la fonction serait dans <productname>PostgreSQL</productname>&nbsp;:

<programlisting>CREATE OR REPLACE FUNCTION cs_update_referrer_type_proc() RETURNS void AS $func$
DECLARE
    referrer_keys CURSOR IS
        SELECT * FROM cs_referrer_keys
        ORDER BY try_order;
    func_body text;
    func_cmd text;
BEGIN 
    func_body := 'BEGIN' ;

    FOR referrer_key IN SELECT * FROM cs_referrer_keys ORDER BY try_order LOOP
	func_body := func_body ||
	' IF v_' || referrer_key.kind
	|| ' LIKE ' || quote_literal(referrer_key.key_string)
	|| ' THEN RETURN ' || quote_literal(referrer_key.referrer_type)
	|| '; END IF;' ;
    END LOOP; 

    func_body := func_body || ' RETURN NULL; END;';

    func_cmd :=
	'CREATE OR REPLACE FUNCTION cs_find_referrer_type(v_host varchar,
	v_domain varchar,
	v_url varchar) 
	RETURNS varchar AS '
	|| quote_literal(func_body)
	|| ' LANGUAGE plpgsql;' ;

	EXECUTE func_cmd;
END;
$func$ LANGUAGE plpgsql;
</programlisting>
    Notez comment le corps de la fonction est construit séparément et est passé
    au travers de <literal>quote_literal</literal> pour doubler tout symbole
    guillemet qu'il peut contenir. Cette technique est nécessaire parce que
    nous ne pouvons pas utiliser à coup sûr les guillemets dollar pour
    définir la nouvelle fonction&nbsp;: nous ne sommes pas sûr de savoir
    quelle chaîne sera interpolée à partir du champ
    <structfield>referrer_key.key_string</structfield> (nous supposons ici que ce
    <structfield>referrer_key.kind</structfield> vaut à coup sûr <literal>host</literal>,
    <literal>domain</literal> ou <literal>url</literal> mais
    <structfield>referrer_key.key_string</structfield> pourrait valoir autre chose, il
    pourrait contenir en particulier des signes dollar). Cette fonction est
    en fait une amélioration de l'original Oracle parce qu'il ne
    génèrera pas de code cassé quand <structfield>referrer_key.key_string</structfield>
    ou <structfield>referrer_key.referrer_type</structfield> contient des guillemets.
    </para>
   </example>

   <para>
    L'<xref linkend="plpgsql-porting-ex3"/> montre comment porter une fonction
    ayant des paramètres <literal>OUT</literal> et effectuant des manipulations de
    chaînes.
    <indexterm><primary>instr</primary></indexterm>
    <productname>PostgreSQL</productname> n'a pas de fonction <function>instr</function>
    intégrée mais vous pouvez en créer une en utilisant une combinaison
    d'autres fonctions. Dans la <xref linkend="plpgsql-porting-appendix"/>, il
    y a une implémentation <application>PL/pgSQL</application>
    d'<function>instr</function> que vous pouvez utiliser pour faciliter votre
    portage.
   </para>

   <example id="plpgsql-porting-ex3">
    <title>Portage d'une procédure avec manipulation de chaînes et paramètres
    <literal>OUT</literal> de <application>PL/SQL</application> vers
    <application>PL/pgSQL</application></title>

    <para>
     La procédure <productname>Oracle</productname> suivante est utilisée pour
     analyser une URL et renvoyer plusieurs éléments (hôte, chemin et requête).
     Les fonctions <application>PL/pgSQL</application> ne peuvent renvoyer
     qu'une seule valeur.
    </para>

    <para>
     Voici la version Oracle&nbsp;:
<programlisting>CREATE OR REPLACE PROCEDURE cs_parse_url(
    v_url IN VARCHAR,
    v_host OUT VARCHAR,  -- Celle-ci sera passée en retour
    v_path OUT VARCHAR,  -- Celle-là aussi
    v_query OUT VARCHAR) -- Et celle-là
IS
    a_pos1 INTEGER;
    a_pos2 INTEGER;
BEGIN
    v_host := NULL;
    v_path := NULL;
    v_query := NULL;
    a_pos1 := instr(v_url, '//');

    IF a_pos1 = 0 THEN
        RETURN;
    END IF;
    a_pos2 := instr(v_url, '/', a_pos1 + 2);
    IF a_pos2 = 0 THEN
        v_host := substr(v_url, a_pos1 + 2);
        v_path := '/';
        RETURN;
    END IF;

    v_host := substr(v_url, a_pos1 + 2, a_pos2 - a_pos1 - 2);
    a_pos1 := instr(v_url, '?', a_pos2 + 1);

    IF a_pos1 = 0 THEN
        v_path := substr(v_url, a_pos2);
        RETURN;
    END IF;

    v_path := substr(v_url, a_pos2, a_pos1 - a_pos2);
    v_query := substr(v_url, a_pos1 + 1);
END;
/
show errors;
</programlisting>
    </para>

    <para>
      Voici une traduction possible en <application>PL/pgSQL</application>&nbsp;:
<programlisting>CREATE OR REPLACE FUNCTION cs_parse_url(
    v_url IN VARCHAR,
    v_host OUT VARCHAR,  -- This will be passed back
    v_path OUT VARCHAR,  -- This one too
    v_query OUT VARCHAR) -- And this one
AS $$
DECLARE
    a_pos1 INTEGER;
    a_pos2 INTEGER;
BEGIN
    v_host := NULL;
    v_path := NULL;
    v_query := NULL;
    a_pos1 := instr(v_url, '//');

    IF a_pos1 = 0 THEN
        RETURN;
    END IF;
    a_pos2 := instr(v_url, '/', a_pos1 + 2);
    IF a_pos2 = 0 THEN
        v_host := substr(v_url, a_pos1 + 2);
        v_path := '/';
        RETURN;
    END IF;

    v_host := substr(v_url, a_pos1 + 2, a_pos2 - a_pos1 - 2);
    a_pos1 := instr(v_url, '?', a_pos2 + 1);

    IF a_pos1 = 0 THEN
        v_path := substr(v_url, a_pos2);
        RETURN;
    END IF;

    v_path := substr(v_url, a_pos2, a_pos1 - a_pos2);
    v_query := substr(v_url, a_pos1 + 1);
END;
$$ LANGUAGE plpgsql;
</programlisting>

    Cette fonction pourrait être utilisée ainsi&nbsp;:
    <programlisting>SELECT * FROM cs_parse_url('http://foobar.com/query.cgi?baz');</programlisting>
    </para>
   </example>

   <para>
    L'<xref linkend="plpgsql-porting-ex4"/> montre comment porter une procédure qui utilise
    de nombreuses fonctionnalités spécifiques à Oracle.
   </para>

   <example id="plpgsql-porting-ex4">
    <title>Portage d'une procédure de <application>PL/SQL</application> vers <application>PL/pgSQL</application></title>

    <para>
     La version Oracle&nbsp;:

<programlisting>CREATE OR REPLACE PROCEDURE cs_create_job(v_job_id IN INTEGER) IS
    a_running_job_count INTEGER;
    PRAGMA AUTONOMOUS_TRANSACTION;<co id="co.plpgsql-porting-pragma"/>
BEGIN
    LOCK TABLE cs_jobs IN EXCLUSIVE MODE;<co id="co.plpgsql-porting-locktable"/>

    SELECT count(*) INTO a_running_job_count FROM cs_jobs WHERE end_stamp IS NULL;

    IF a_running_job_count &gt; 0 THEN
        COMMIT; -- free lock<co id="co.plpgsql-porting-commit"/>
        raise_application_error(-20000, 'Unable to create a new job: a job is currently running.');
    END IF;

    DELETE FROM cs_active_job;
    INSERT INTO cs_active_job(job_id) VALUES (v_job_id);

    BEGIN
        INSERT INTO cs_jobs (job_id, start_stamp) VALUES (v_job_id, sysdate);
        EXCEPTION
	  WHEN dup_val_on_index THEN NULL; -- ne vous inquietez pas si cela existe déjà
    END;
    COMMIT;
END;
/
show errors
</programlisting>
   </para>

   <para>
    Les procédures comme celles-ci peuvent être aisément converties en 
    fonctions <productname>PostgreSQL</productname> renvoyant un <type>void</type>. Cette
    procédure en particulier est intéressante parce qu'elle peut nous apprendre diverses
    choses&nbsp;:

    <calloutlist>
     <callout arearefs="co.plpgsql-porting-pragma">
      <para>
       Il n'y a pas d'instruction <literal>PRAGMA</literal> dans <productname>PostgreSQL</productname>.
      </para>
     </callout>

     <callout arearefs="co.plpgsql-porting-locktable">
      <para>
       Si vous faites un <command>LOCK TABLE</command> dans <application>PL/pgSQL</application>, 
       le verrou ne sera pas libéré jusqu'à ce que la transaction appelante soit 
       terminée.
      </para>
     </callout>

     <callout arearefs="co.plpgsql-porting-commit">
      <para>
       Vous ne pouvez pas lancer un <command>COMMIT</command> dans une fonction
       <application>PL/pgSQL</application>. La fonction est lancée à
       l'intérieur d'une transaction externe et, du coup, un
       <command>COMMIT</command> impliquerait simplement la fin de l'exécution de
       la fonction. Néanmoins, dans ce cas particulier, ce n'est de toute
       façon pas nécessaire parce que le verrou obtenu par <command>LOCK
       TABLE</command> sera libéré lors de la levée de l'erreur.
      </para>
     </callout>
    </calloutlist>
   </para>

   <para>
    Voici comment nous pourrions porter cette procédure vers
<application>PL/pgSQL</application>&nbsp;:

<programlisting>CREATE OR REPLACE FUNCTION cs_create_job(v_job_id integer) RETURNS void AS $$
DECLARE
  a_running_job_count integer;
BEGIN
  LOCK TABLE cs_jobs IN EXCLUSIVE MODE;

  SELECT count(*) INTO a_running_job_count FROM cs_jobs WHERE end_stamp IS NULL;

  IF a_running_job_count &gt; 0 THEN
    RAISE EXCEPTION 'Unable to create a new job: a job is currently running';<co id="co.plpgsql-porting-raise"/>
  END IF;

  DELETE FROM cs_active_job;
  INSERT INTO cs_active_job(job_id) VALUES (v_job_id);

  BEGIN
    INSERT INTO cs_jobs (job_id, start_stamp) VALUES (v_job_id, now());
  EXCEPTION
    WHEN unique_violation THEN <co id="co.plpgsql-porting-exception"/>
    -- ne vous inquietez pas si cela existe déjà
  END;
END;
$$ LANGUAGE plpgsql;
</programlisting>

    <calloutlist>
     <callout arearefs="co.plpgsql-porting-raise">
      <para>
       La syntaxe de <literal>RAISE</literal> est considérablement différente de
       l'instruction Oracle similaire, bien que le cas basique du
       <literal>RAISE</literal>
       <replaceable class="parameter">nom_exception</replaceable> fonctionne de
       façon similaire.
      </para>
     </callout>
     
     <callout arearefs="co.plpgsql-porting-exception">
      <para>
       Les noms d'exceptions supportées par <application>PL/pgSQL</application> sont
       différents de ceux d'Oracle. L'ensemble de noms d'exceptions intégré
       est plus important (voir l'<xref linkend="errcodes-appendix"/>).
       Il n'existe actuellement pas de façon de déclarer des noms
       d'exceptions définis par l'utilisateur.
	  </para>
     </callout>
    </calloutlist>

    La principale différence fonctionnelle entre cette procédure et
    l'équivalent Oracle est que le verrou exclusif sur la table
    <literal>cs_jobs</literal> sera détenu jusqu'à la fin de la transaction
    appelante. De plus, si l'appelant annule plus tard (par exemple à cause
    d'une erreur), les effets de cette procédure seront annulés.
   </para>
   </example>
  </sect2>

  <sect2 id="plpgsql-porting-other">
   <title>Autres choses à surveiller</title>

   <para>
    Cette section explique quelques autres choses à surveiller quand on effectue
    un portage de fonctions <application>PL/SQL</application> Oracle vers PostgreSQL.
   </para>

   <sect3 id="plpgsql-porting-exceptions">
	<title>Annulation implicite après une exception</title>
	   
	<para>
     Dans <application>PL/pgSQL</application>, quand une exception est récupérée par une
     clause <literal>EXCEPTION</literal>, toutes les modifications de la base de
     données depuis le bloc <literal>BEGIN</literal> sont automatiquement annulées.
     C'est-à-dire que le comportement est identique à celui obtenu à partir
     d'Oracle avec&nbsp;:

<programlisting>BEGIN
SAVEPOINT s1;
... code ici ...
EXCEPTION
WHEN ... THEN
ROLLBACK TO s1;
... code ici ...
WHEN ... THEN
ROLLBACK TO s1;
... code ici ...
END;</programlisting>

      Si vous traduisez une procédure d'Oracle qui utilise
      <command>SAVEPOINT</command> et <command>ROLLBACK TO</command> dans ce style, votre
      tâche est facile&nbsp;: omettez <command>SAVEPOINT</command> et
      <command>ROLLBACK TO</command>. Si vous avez une procédure qui utilise
      <command>SAVEPOINT</command> et <command>ROLLBACK TO</command> d'une façon différente,
      alors un peu de réflexion supplémentaire sera nécessaire.
     </para>
   </sect3>

   <sect3>
    <title><command>EXECUTE</command></title>

    <para>
     La version <application>PL/pgSQL</application> d'<command>EXECUTE</command> fonctionne de façon
     similaire à la version <application>PL/SQL</application> mais vous devez vous rappeler
     d'utiliser <function>quote_literal</function> et 
     <function>quote_ident</function> comme décrit dans la <xref
     linkend="plpgsql-statements-executing-dyn"/>.  Les constructions de type
     <literal>EXECUTE 'SELECT * FROM $1';</literal> ne fonctionneront pas de
     façon fiable à moins d'utiliser ces fonctions.
    </para>
   </sect3>

   <sect3 id="plpgsql-porting-optimization">
    <title>Optimisation des fonctions <application>PL/pgSQL</application></title>

    <para>
     <productname>PostgreSQL</productname> vous donne deux modificateurs de création de
     fonctions pour optimiser l'exécution&nbsp;: la <quote>volatilité</quote>
     (la fonction renvoie toujours le même
     résultat quand on lui donne les mêmes arguments) et la <quote>rigueur</quote> (une 
     fonction renvoie NULL si tous ses arguments sont NULL).  Consultez la
     page de référence de <xref linkend="sql-createfunction" endterm="sql-createfunction-title"/> pour les détails.
    </para>

    <para>
     Pour faire usage de ces attributs d'optimisation, votre instruction
     <command>CREATE FUNCTION</command> devrait ressembler à ceci&nbsp;:

<programlisting>CREATE FUNCTION foo(...) RETURNS integer AS $$
...
$$ LANGUAGE plpgsql STRICT IMMUTABLE;
</programlisting>
    </para>
   </sect3>
  </sect2>

  <sect2 id="plpgsql-porting-appendix">
   <title>Annexe</title>

   <para>
    Cette section contient le code d'un ensemble de fonctions <function>instr</function> 
    compatible Oracle que vous pouvez utiliser pour simplifier vos efforts de portage.
   </para>

<programlisting>--
-- fonctions instr qui reproduisent la contrepartie Oracle
-- Syntaxe: instr(string1, string2, [n], [m]) où [] signifie paramètre optionnel.
-- 
-- Cherche string1 en commençant par le  n-ième caractère pour la m-ième occurrence
-- de string2.  Si n est négatif, cherche en sens inverse. Si m n'est pas fourni
-- suppose 1 (la recherche commence au premier caractère).
--

CREATE FUNCTION instr(varchar, varchar) RETURNS integer AS $$
DECLARE
    pos integer;
BEGIN
    pos:= instr($1, $2, 1);
    RETURN pos;
END;
$$ LANGUAGE plpgsql STRICT IMMUTABLE;


CREATE FUNCTION instr(string varchar, string_to_search varchar, beg_index integer)
RETURNS integer AS $$
DECLARE
    pos integer NOT NULL DEFAULT 0;
    temp_str varchar;
    beg integer;
    length integer;
    ss_length integer;
BEGIN
    IF beg_index &gt; 0 THEN
        temp_str := substring(string FROM beg_index);
        pos := position(string_to_search IN temp_str);

        IF pos = 0 THEN
            RETURN 0;
        ELSE
            RETURN pos + beg_index - 1;
        END IF;
    ELSE
        ss_length := char_length(string_to_search);
        length := char_length(string);
        beg := length + beg_index - ss_length + 2;

	WHILE beg &gt; 0 LOOP
            temp_str := substring(string FROM beg FOR ss_length);
            pos := position(string_to_search IN temp_str);

	    IF pos &gt; 0 THEN
                RETURN beg;
            END IF;

            beg := beg - 1;
        END LOOP;

        RETURN 0;
    END IF;
END;
$$ LANGUAGE plpgsql STRICT IMMUTABLE;


CREATE FUNCTION instr(string varchar, string_to_search varchar,
                      beg_index integer, occur_index integer)
RETURNS integer AS $$
DECLARE
    pos integer NOT NULL DEFAULT 0;
    occur_nombre integer NOT NULL DEFAULT 0;
    temp_str varchar;
    beg integer;
    i integer;
    length integer;
    ss_length integer;
BEGIN
    IF beg_index &gt; 0 THEN
        beg := beg_index;
        temp_str := substring(string FROM beg_index);

        FOR i IN 1..occur_index LOOP
            pos := position(string_to_search IN temp_str);

            IF i = 1 THEN
                beg := beg + pos - 1;
            ELSE
                beg := beg + pos;
            END IF;

            temp_str := substring(string FROM beg + 1);
        END LOOP;

        IF pos = 0 THEN
            RETURN 0;
        ELSE
            RETURN beg;
        END IF;
    ELSE
        ss_length := char_length(string_to_search);
        length := char_length(string);
        beg := length + beg_index - ss_length + 2;

        WHILE beg &gt; 0 LOOP
            temp_str := substring(string FROM beg FOR ss_length);
            pos := position(string_to_search IN temp_str);

            IF pos &gt; 0 THEN
                occur_nombre := occur_nombre + 1;

                IF occur_nombre = occur_index THEN
                    RETURN beg;
                END IF;
            END IF;

            beg := beg - 1;
        END LOOP;

        RETURN 0;
    END IF;
END;
$$ LANGUAGE plpgsql STRICT IMMUTABLE;
</programlisting>
  </sect2>
  
 </sect1>

</chapter>