root/traduc/branches/bv747/manuel/ecpg.sgml

<!--
$Header: /var/lib/cvs/pgsql-fr/sgml/ecpg.sgml,v 1.7.2.5 2005/09/29 06:51:33 guillaume Exp $
-->

<chapter id="ecpg">
 <title><application>ECPG</application> - <acronym>SQL</acronym> embarqué dans
  du C</title>

 <indexterm zone="ecpg"><primary>SQL embarqué</primary><secondary>dans du
  C</secondary></indexterm>
 <indexterm zone="ecpg"><primary>C</primary></indexterm>
 <indexterm zone="ecpg"><primary>ECPG</primary></indexterm>

 <para>
  Ce chapitre décrit l'interface <acronym>SQL</acronym> embarqué pour
  <productname>PostgreSQL</productname>. Il fonctionne avec le
  <acronym>C</acronym> et le <acronym>C++</acronym>. Il a été écrit par
  Linus Tolke (<email>linus@epact.se</email>) et Michael Meskes
  (<email>meskes@postgresql.org</email>).
 </para>

 <para>
  Il ne fait aucun doute que cette documentation est assez incomplète. Mais du
  fait de la sandardisation de cette interface, des informations complémentaires sont
  disponibles à travers de nombreuses ressources traitant du SQL.
 </para>

 <sect1 id="ecpg-concept">
  <title>Concept</title>

  <para>
   Un programme <acronym>SQL</acronym> embarqué consiste en du code écrit dans un langage de
   programmation ordinaire, dans le cas présent, le <acronym>C</acronym>, mélangé à des commandes SQL incluses dans
   des sections spécialement marquées. Pour construire le programme, le code
   source est d'abord passé au préprocesseur <acronym>SQL</acronym> embarqué qui le convertit en un
   programme <acronym>C</acronym> ordinaire. Il peut alors être traité par un outil de compilation
   <acronym>C</acronym>.
  </para>

  <para>
   Le <acronym>SQL</acronym> embarqué a des avantages par rapport aux autres méthodes
   de gestion de commandes <acronym>SQL</acronym> dans du code C. Premièrement,
   il gère le passage laborieux des informations de et vers les variables du
   programme <acronym>C</acronym>. Deuxièmement, le code SQL du programme est
   vérifié syntaxiquement au moment de la construction. Troisièmement, le
   <acronym>SQL</acronym> embarqué en C est spécifié dans le standard
   <acronym>SQL</acronym> et supporté par de nombreux systèmes de bases de
   données <acronym>SQL</acronym>. L'implémentation <productname>PostgreSQL</>
   est conçue pour correspondre au mieux à ce standard. Il est de ce fait
   assez facile de porter les programmes <acronym>SQL</acronym>
   embarqués écrits pour d'autres bases de données SQL vers
   <productname>PostgreSQL</productname>.
  </para>

  <para>
   Comme indiqué précédemment, les programmes écrits pour l'interface <acronym>SQL</acronym>
   embarqué sont des programmes C normaux contenant un code spécial inséré pour
   réaliser les actions en relation avec la base de données. Ce code spécial a
   toujours la forme
<programlisting>
EXEC SQL ...;
</programlisting>
   Ces instructions prennent syntaxiquement la place d'une instruction C.
   Suivant l'instruction particulière, elles peuvent apparaître dans le
   contexte global ou à l'intérieur d'une fonction. Les instructions
   <acronym>SQL</acronym> embarquées suivent les règles de sensibilité à la
   casse d'un code <acronym>SQL</acronym> normal, et non pas ceux du C.
  </para>

  <para>
   Les sections suivantes expliquent toutes les instructions SQL embarquées.
  </para>
 </sect1>

 <sect1 id="ecpg-connect">
  <title>Se connecter au serveur de bases de données</title>

  <para>
   La connexion à une base de données se fait en utilisant l'instruction
   suivante&nbsp;:
<programlisting>
EXEC SQL CONNECT TO <replaceable>cible</replaceable> <optional>AS <replaceable>nom-connexion</replaceable></optional> <optional>USER <replaceable>nom-utilisateur</replaceable></optional>;
</programlisting>
   La <replaceable>cible</replaceable> peut être spécifiée d'une des façons
   suivantes&nbsp;:

   <itemizedlist>
    <listitem>
     <simpara><literal><replaceable>nombase</><optional>@<replaceable>nomhôte</>
      </optional><optional>:<replaceable>port</></optional></literal>
     </simpara>
    </listitem>

    <listitem>
     <simpara><literal>tcp:postgresql://<replaceable>nomhôte</>
      <optional>:<replaceable>port</> </optional>
      <optional>/<replaceable>nombase</></optional><optional>?<replaceable>
      options</></optional></literal>
     </simpara>
    </listitem>

    <listitem>
     <simpara>
      <literal>unix:postgresql://<replaceable>nomhôte</><optional>:
      <replaceable>port</></optional><optional>/<replaceable>nombase</>
      </optional><optional>?<replaceable> options</></optional></literal>
     </simpara>
    </listitem>

    <listitem>
     <simpara>
      une chaîne SQL littérale contenant une des formes précédentes
     </simpara>
    </listitem>

    <listitem>
     <simpara>
      une référence à une variable contenant une des formes précédentes (voir les
      exemples)
     </simpara>
    </listitem>

    <listitem>
     <simpara>
      <literal>DEFAULT</literal>
     </simpara>
    </listitem>
   </itemizedlist>

   Si la cible de connexion est spécifiée littéralement (c'est-à-dire non pas via une
   variable de référence) et la valeur n'est pas mise entre guillemets,
   les règles d'insensibilité à la casse du SQL standard sont appliquées.
   Dans ce cas, il est possible, si cela s'avérait nécessaire, d'encadrer
   séparément les paramètres individuels de guillemets doubles.
   En pratique, l'utilisation d'une chaîne littérale (entre guillemets
   simples) ou d'une variable de référence engendre moins d'erreurs. La cible de
   connexion <literal>DEFAULT</literal> initie une connexion à la base de
   données standard avec l'utilisateur standard. Aucun nom d'utilisateur ou
   de connexion ne peut être spécifié isolément dans ce cas.
  </para>

  <para>
   Il existe également différentes façons de préciser le nom de l'utilisateur&nbsp;:

   <itemizedlist>
    <listitem>
     <simpara>
      <literal><replaceable>nomutilisateur</replaceable></literal>
     </simpara>
    </listitem>

    <listitem>
     <simpara>
      <literal><replaceable>nomutilisateur</replaceable>/
      <replaceable>motdepasse</replaceable></literal>
     </simpara>
    </listitem>

    <listitem>
     <simpara>
      <literal><replaceable>nomutilisateur</replaceable> IDENTIFIED BY
      <replaceable>motdepasse</replaceable></literal>
     </simpara>
    </listitem>

    <listitem>
     <simpara>
      <literal><replaceable>nomutilisateur</replaceable> USING
      <replaceable>motdepasse</replaceable></literal>
     </simpara>
    </listitem>
   </itemizedlist>

   Comme indiqué ci-dessus, les paramètres
   <replaceable>nomutilisateur</replaceable> et
   <replaceable>motdepasse</replaceable> peuvent être un identificateur SQL, une
   chaîne SQL littérale ou une référence à une variable de type caractère.
  </para>

  <para>
   <replaceable>nom-connexion</replaceable> est utilisé pour gérer plusieurs
   connexions dans un même programme. Il peut être omis si un programme n'utilise
   qu'une seule connexion. La connexion la plus récemment ouverte devient la
   connexion courante, utilisée par défaut lorsqu'une instruction SQL est à
   exécuter (voir plus loin dans ce chapitre).
  </para>

  <para>
   Voici quelques exemples d'instructions <command>CONNECT</command>&nbsp;:
<programlisting>
EXEC SQL CONNECT TO mabase@sql.mondomaine.com;

EXEC SQL CONNECT TO 'unix:postgresql://sql.mondomaine.com/mabase' AS
maconnexion USER john;

EXEC SQL BEGIN DECLARE SECTION;
const char *cible = "mabase@sql.mondomaine.com";
const char *utilisateur = "john";
EXEC SQL END DECLARE SECTION;
 ...
EXEC SQL CONNECT TO :cible USER :utilisateur;
</programlisting>
   La dernière forme utilise la variante dite de la variable de référence,
   à laquelle il est fait allusion ci-dessus. Nous verrons dans les prochaines sections comment
   utiliser des variables C dans des instructions SQL en les
   préfixant par un caractère deux-points.
  </para>

  <para>
   Il est à noter que le format de la cible de connexion n'est pas spécifié dans
   le standard SQL. Ainsi, lorsque l'on souhaite développer des applications portables,
   il est préférable d'utiliser une syntaxe basée sur le dernier exemple ci-dessus
   pour encapsuler la chaîne de la cible de connexion.
  </para>
 </sect1>

 <sect1 id="ecpg-disconnect">
  <title>Fermer une connexion</title>

  <para>
   Pour fermer une connexion, l'instruction suivante est utilisée&nbsp;:
<programlisting>
EXEC SQL DISCONNECT <optional><replaceable>connexion</replaceable></optional>;
</programlisting>
   <replaceable>connexion</replaceable> peut être spécifiée de
   différentes façons&nbsp;:

   <itemizedlist>
    <listitem>
     <simpara>
      <literal><replaceable>nom-connexion</replaceable></literal>
     </simpara>
    </listitem>

    <listitem>
     <simpara>
      <literal>DEFAULT</literal>
     </simpara>
    </listitem>

    <listitem>
     <simpara>
      <literal>CURRENT</literal>
     </simpara>
    </listitem>

    <listitem>
     <simpara>
      <literal>ALL</literal>
     </simpara>
    </listitem>
   </itemizedlist>

   Si aucun nom de connexion n'est spécifié, la connexion en cours est fermée.
  </para>

  <para>
   Il est toujours préférable qu'une application ferme explicitement
   chaque connexion qu'elle a ouverte.
  </para>
 </sect1>

 <sect1 id="ecpg-commands">
  <title>Exécuter des commandes SQL</title>

  <para>
   Toute commande SQL peut être exécutée à l'intérieur d'une application SQL
   embarquée. Ci-dessous se trouvent quelques exemples de façons de procéder.
  </para>

  <para>
   Création d'une table&nbsp;:
<programlisting>
EXEC SQL CREATE TABLE foo (nombre integer, ascii char(16));
EXEC SQL CREATE UNIQUE INDEX num1 ON foo(nombre);
EXEC SQL COMMIT;
</programlisting>
  </para>

  <para>
   Insertion de lignes&nbsp;:
<programlisting>
EXEC SQL INSERT INTO foo (nombre, ascii) VALUES (9999, 'doodad');
EXEC SQL COMMIT;
</programlisting>
  </para>

  <para>
   Suppression de lignes&nbsp;:
<programlisting>
EXEC SQL DELETE FROM foo WHERE nombre = 9999;
EXEC SQL COMMIT;
</programlisting>
  </para>

  <para>
   Sélection d'une ligne&nbsp;:
<programlisting>
EXEC SQL SELECT foo INTO :FooBar FROM table1 WHERE ascii = 'doodad';
</programlisting>
  </para>

  <para>
   Sélection utilisant des curseurs&nbsp;:
<programlisting>
EXEC SQL DECLARE foo_bar CURSOR FOR
    SELECT nombre, ascii FROM foo
    ORDER BY ascii;
EXEC SQL OPEN foo_bar;
EXEC SQL FETCH foo_bar INTO :FooBar, DooDad;
...
EXEC SQL CLOSE foo_bar;
EXEC SQL COMMIT;
</programlisting>
  </para>

  <para>
   Mises à jour&nbsp;:
<programlisting>
EXEC SQL UPDATE foo
    SET ascii = 'foobar'
    WHERE nombre = 9999;
EXEC SQL COMMIT;
</programlisting>
  </para>

  <para>
   Les marques de la forme
   <quote><literal>:<replaceable>quelquechose</replaceable></literal></quote>
   sont des <firstterm>variables hôtes</firstterm>, c'est-à-dire qu'elles font
   référence à des variables dans le programme C. Elles sont expliquées dans
   la <xref linkend="ecpg-variables">.
  </para>

  <para>
   Dans le mode par défaut, les instructions ne sont validées que lorsque
   <command>EXEC SQL COMMIT</command> est exécuté. L'interface SQL embarquée
   supporte aussi la validation automatique des transactions (aussi connue des
   autres interfaces) via l'option <option>-t</option> en ligne de commande pour
   <command>ecpg</command> (voir ci-dessous) ou via l'instruction <literal>EXEC
   SQL SET AUTOCOMMIT TO ON</literal>. En mode de validation automatique, chaque
   commande est automatiquement validée sauf si elle est à l'intérieur d'un bloc
   de transaction explicite. Ce mode peut être explicitement désactivé en
   utilisant <literal>EXEC SQL SET AUTOCOMMIT TO OFF</literal>.
  </para>
 </sect1>

 <sect1 id="ecpg-set-connection">
  <title>Choisir une connexion</title>

  <para>
   Les instructions SQL affichées dans la section précédente sont exécutées à
   partir de la connexion courante, c'est-à-dire la dernière à avoir été ouverte.
   Il y a deux façons de gérer l'utilisation de plusieurs connexions dans une
   application.
  </para>

  <para>
   La première option est de choisir explicitement une connexion pour chaque
   instruction SQL, par exemple
<programlisting>
EXEC SQL AT <replaceable>nom-connexion</replaceable> SELECT ...;
</programlisting>
   Cette option est particulièrement adaptée si l'application a besoin
   d'utiliser plusieurs connexions en ordre divers.
  </para>

  <para>
   La seconde option est d'exécuter une instruction pour basculer la connexion
   courante. L'instruction est&nbsp;:
<programlisting>
EXEC SQL SET CONNECTION <replaceable>connection-name</replaceable>;
</programlisting>
   Cette option est particulièrement intéressante si un grand nombre
   d'instructions doivent être exécutées à partir de la même connexion. Elle ne tient pas
   compte des threads.
  </para>
 </sect1>

 <sect1 id="ecpg-variables">
  <title>Utiliser des variables hôtes</title>

  <para>
   Dans la <xref linkend="ecpg-commands">, nous avons vu comment exécuter des
   instructions SQL à partir d'un programme SQL embarqué. Quelques-unes de ces
   instructions n'utilisent que des valeurs fixes. Elles n'offrent pas la
   possibilité d'insérer des valeurs fournies par l'utilisateur dans les
   instructions. Elles ne permettent pas non plus au programme de traiter
   les valeurs renvoyées par la requête.
   Ces types d'instructions ne sont pas vraiment utiles dans les
   applications réelles. Cette section explique en détail comment
   échanger des données entre votre programme C et les instructions SQL embarquées
   en utilisant un mécanisme simple appelé <firstterm>variables
   hôtes</firstterm>.
  </para>

  <sect2>
   <title>Aperçu</title>

   <para>
    Échanger des données entre le programme C et les instructions SQL est
    particulièrement simple en SQL embarqué. Plutôt que de laisser le programme
    copier les données dans l'instruction, ce qui implique un certain nombre de
    complications, dont la bonne mise entre guillemets de la valeur, il est plus simple
    d'écrire le nom de la variable C dans l'instruction SQL en la préfixant par un
    caractère deux-points. Par exemple&nbsp;:
<programlisting>
EXEC SQL INSERT INTO unetable VALUES (:v1, 'foo', :v2);
</programlisting>
    Cette instruction fait référence à deux variables C nommées
    <varname>v1</varname> et <varname>v2</varname>, et utilise également une
    chaîne littérale SQL pour illustrer l'absence de restriction à l'utilisation
    d'un type de données ou d'un autre.
   </para>

   <para>
    Ce style d'insertions de variables C dans des instructions SQL fonctionne
    dans tous les cas où l'on attend une expression de valeur dans une instruction SQL. Dans
    l'environnement SQL, nous appelons les références à des variables C
    des <firstterm>variables hôtes</firstterm>.
   </para>
  </sect2>

  <sect2>
   <title>Sections de déclaration</title>

   <para>
    Pour passer des données du programme à la base de données,
    comme paramètre d'une requête par exemple, ou pour passer des données de la
    base au programme, les variables C supposées contenir ces données doivent être
    déclarées dans des sections spécialement marquées pour que le préprocesseur
    du SQL embarqué soit averti de leur présence.
   </para>

   <para>
    Cette section commence avec
<programlisting>
EXEC SQL BEGIN DECLARE SECTION;
</programlisting>
    et se termine avec
<programlisting>
EXEC SQL END DECLARE SECTION;
</programlisting>
    Entre ces lignes, on trouvera des déclarations normales de variables C, comme
<programlisting>
int   x;
char  foo[16], bar[16];
</programlisting>
    Il peut y avoir autant de sections de déclarations dans un programme que
    souhaité.
   </para>

   <para>
    Les déclarations sont aussi placées dans le fichier de sortie comme des
    variables C normales. Du coup, il n'est plus besoin de les déclarer à
    nouveau. Les variables qui n'ont pas pour but d'être utilisées dans des
    commandes SQL peuvent être normalement déclarées en dehors des sections
    spéciales.
   </para>

   <para>
    La définition d'une structure ou union doit aussi être saisie dans une
    section <literal>DECLARE</>. Sinon, le préprocesseur, ne connaissant pas leur
    définition, ne pourra pas gérer ces types.
   </para>

   <para>
    Le type spécial <type>VARCHAR</type> est converti dans une <type>struct</>
    nommée pour chaque variable. Une déclaration telle que
<programlisting>
VARCHAR var[180];
</programlisting>
    est convertie en
<programlisting>
struct varchar_var { int len; char arr[180]; } var;
</programlisting>
    Cette structure est utilisable pour créer une interface des données SQL de type
    <type>varchar</type>.
   </para>
  </sect2>

  <sect2>
   <title><command>SELECT INTO</command> et <command>FETCH
    INTO</command></title>

   <para>
    Nous savons maintenant insérer des données engendrées par un
    programme dans une commande SQL. Mais comment récupérer les résultats d'une
    requête&nbsp;? Dans ce but, le SQL embarqué fournit des variantes spéciales
    des commandes habituelles <command>SELECT</command> et
    <command>FETCH</command>. Ces commandes ont une clause
    <literal>INTO</literal> particulière qui spécifie les variables hôtes dans
    lesquelles seront stockées les valeurs récupérées.
   </para>

   <para>
    Voici un exemple&nbsp;:
<programlisting>
/*
 * Soit la table suivante :
 * CREATE TABLE test1 (a int, b varchar(50));
 */

EXEC SQL BEGIN DECLARE SECTION;
int v1;
VARCHAR v2;
EXEC SQL END DECLARE SECTION;

 ...

EXEC SQL SELECT a, b INTO :v1, :v2 FROM test;
</programlisting>
    La clause <literal>INTO</literal> apparaît donc entre les champs du
    <command>select</command> et la clause <literal>FROM</literal>.
    Le nombre d'éléments dans la liste du <command>select</command>
    et celui de la liste après <literal>INTO</literal> (aussi appelée liste
    cible) doivent être identiques.
   </para>

   <para>
    Voici un exemple utilisant la commande <command>FETCH</command>&nbsp;:
<programlisting>
EXEC SQL BEGIN DECLARE SECTION;
int v1;
VARCHAR v2;
EXEC SQL END DECLARE SECTION;

 ...

EXEC SQL DECLARE foo CURSOR FOR SELECT a, b FROM test;

 ...

do {
    ...
    EXEC SQL FETCH NEXT FROM foo INTO :v1, :v2;
    ...
} while (...);
</programlisting>
    Ici, la clause <literal>INTO</literal> apparaît après toutes les autres
    clauses.
   </para>

   <para>
    Ces deux méthodes ne permettent de récupérer qu'une ligne à la
    fois. Pour traiter des ensembles de résultats
    contenant potentiellement plus d'une ligne, il faut utiliser un
    curseur, comme indiqué dans le second exemple.
   </para>
  </sect2>

  <sect2>
   <title>Indicateurs</title>

   <para>
    Les exemples ci-dessus ne gèrent pas les valeurs nulles (NULL). En fait, ces
    exemples de récupération afficheront une erreur s'ils récupèrent une
    valeur nulle à partir de la base de données. Pour être capable de passer des
    valeurs nulles à la base de données ou de récupérer des valeurs nulles de la
    base de données, il est nécessaire d'ajouter une deuxième spécification de
    variable hôte pour chaque variable hôte contenant des données. Cette seconde
    variable est appelée l'<firstterm>indicateur</firstterm> et contient un
    drapeau indiquant si la valeur est nulle, auquel cas la valeur de la variable
    hôte réelle est ignorée. Voici un exemple qui gère correctement la
    récupération de valeurs nulles&nbsp;:
<programlisting>
EXEC SQL BEGIN DECLARE SECTION;
VARCHAR val;
int val_ind;
EXEC SQL END DECLARE SECTION:

 ...

EXEC SQL SELECT b INTO :val :val_ind FROM test1;
</programlisting>
    La variable indicateur <varname>val_ind</varname> vaudra zéro si la valeur
    est non nulle et elle sera négative si la valeur est nulle.
   </para>

   <para>
    L'indicateur a une autre fonction&nbsp;: si la valeur de l'indicateur est
    positive, cela signifie que la valeur est non nulle mais qu'elle a été
    tronquée lors de son stockage dans la variable hôte.
   </para>
  </sect2>
 </sect1>

 <sect1 id="ecpg-dynamic">
  <title>SQL dynamique</title>

  <para>
   Dans de nombreux cas, les instructions SQL particulières qu'une application
   doit exécuter sont connues au moment de l'écriture de l'application.
   Néanmoins, dans certains cas, les instructions SQL sont composées à
   l'exécution ou fournies par une source externe. Dans ces cas, il n'est pas possible
   d'embarquer directement les instructions SQL dans le code source C. Pour ce faire, il
   existe une fonction permettant d'appeler des instructions SQL arbitraires
   fournies par l'intermédiaire d'une variable de type chaîne.
  </para>

  <para>
   La façon la plus simple d'exécuter une instruction SQL arbitraire est
   d'utiliser la commande <command>EXECUTE IMMEDIATE</command>. Par
   exemple&nbsp;:
<programlisting>
EXEC SQL BEGIN DECLARE SECTION;
const char *stmt = "CREATE TABLE test1 (...);";
EXEC SQL END DECLARE SECTION;

EXEC SQL EXECUTE IMMEDIATE :stmt;
</programlisting>
   Les instructions de ce type ne peuvent pas être utilisées pour récupérer des
   données (c'est-à-dire un <command>SELECT</command>).
  </para>

  <para>
   Une façon plus puissante d'exécuter des instructions SQL arbitraires est de
   les préparer une seule fois et de les exécuter ensuite aussi souvent que nécessaire.
   Il est
   également possible de préparer une version généralisée d'une instruction, puis
   d'exécuter les versions spécifiques en substituant les paramètres. Lors de la
   préparation de l'instruction, il suffit d'écrire des points d'interrogation
   aux endroits où des paramètres seront substitués par la suite. Par exemple&nbsp;:
<programlisting>
EXEC SQL BEGIN DECLARE SECTION;
const char *stmt = "INSERT INTO test1 VALUES(?, ?);";
EXEC SQL END DECLARE SECTION;

EXEC SQL PREPARE mystmt FROM :stmt;
 ...
EXEC SQL EXECUTE mystmt USING 42, 'foobar';
</programlisting>
   Si l'instruction exécutée retourne des valeurs, il est nécessaire d'ajouter une
   clause <literal>INTO</literal>&nbsp;:
<programlisting>
EXEC SQL BEGIN DECLARE SECTION;
const char *stmt = "SELECT a, b, c FROM test1 WHERE a > ?";
int v1, v2;
VARCHAR v3;
EXEC SQL END DECLARE SECTION;

EXEC SQL PREPARE mystmt FROM :stmt;
 ...
EXEC SQL EXECUTE mystmt INTO v1, v2, v3 USING 37;
</programlisting>
   Une commande <command>EXECUTE</command> peut avoir une clause
   <literal>INTO</literal>, une clause <literal>USING</literal>, les deux ou
   aucune.
  </para>

  <para>
   Lorsqu'une instruction préparée n'est plus utile, il est préférable de la
   désallouer&nbsp;:
<programlisting>
EXEC SQL DEALLOCATE PREPARE <replaceable>name</replaceable>;
</programlisting>
  </para>
 </sect1>

 <sect1 id="ecpg-descriptors">
  <title>Utiliser les zones des descripteurs SQL</title>

  <para>
   Une zone de descripteur SQL est une méthode plus sophistiquée pour traiter
   le résultat d'un <command>SELECT</command> ou d'un <command>FETCH</command>.
   La zone du descripteur SQL groupe les données d'une ligne avec les éléments
   de métadonnées en une seule structure de données. Les métadonnées sont
   particulièrement utiles lors de l'exécution d'instructions SQL dynamiques
   pour lesquelles la nature des colonnes de résultats n'est pas forcément
   connue à l'avance.
  </para>

  <para>
   Une zone de descripteur SQL consiste en un en-tête, contenant des
   informations sur le descripteur complet, et un ou plusieurs éléments
   des zones du descripteur, décrivant basiquement une colonne de la ligne de
   résultat.
  </para>

  <para>
   Avant d'utiliser une zone de descripteur SQL, il est nécessaire d'en
   allouer une&nbsp;:
<programlisting>
EXEC SQL ALLOCATE DESCRIPTOR <replaceable>identifiant</replaceable>;
</programlisting>
   L'identifiant sert de <quote>nom de variable</quote> à la zone du
   descripteur. <comment>La portée du descripteur alloué est QUOI&nbsp;?</comment>
   Lorsque le descripteur n'est plus utilisé, il est recommandé de le désallouer&nbsp;:
<programlisting>
EXEC SQL DEALLOCATE DESCRIPTOR <replaceable>identifiant</replaceable>;
</programlisting>
  </para>

  <para>
   Pour utiliser la zone d'un descripteur, il faut le spécifier comme cible de
   stockage dans une clause <literal>INTO</literal> à la place de la liste des
   variables hôtes&nbsp;:
<programlisting>
EXEC SQL FETCH NEXT FROM moncurseur INTO DESCRIPTOR mondesc;
</programlisting>
  </para>

  <para>
   Comment récupérer les données de la zone du descripteur&nbsp;?
   Celle-ci peut être envisagée comme une structure contenant des champs nommés. Pour
   récupérer la valeur d'un champ à partir de l'en-tête et la stocker dans une
   variable hôte, on utilise la commande suivante&nbsp;:
<programlisting>
EXEC SQL GET DESCRIPTOR <replaceable>nom</replaceable> :<replaceable>varhote</replaceable> = <replaceable>champ</replaceable>;
</programlisting>
   Actuellement, il n'existe qu'un seul champ d'en-tête défini&nbsp;:
   <replaceable>COUNT</replaceable>, qui indique le nombre d'éléments dans
   la zone de descripteur (c'est-à-dire le nombre de colonnes contenues dans le
   résultat). La variable hôte nécessite d'être du type entier. Pour récupérer
   un champ à partir de l'élément de la zone du descripteur, on utilise la commande
   suivante&nbsp;:
<programlisting>
EXEC SQL GET DESCRIPTOR <replaceable>nom</replaceable> VALUE
<replaceable>numero</replaceable> :<replaceable>varhote</replaceable> =
<replaceable>champ</replaceable>;
</programlisting>
   <replaceable>numero</replaceable> peut être un entier littéral ou une
   variable hôte contenant un entier. Les champs possibles sont&nbsp;:

   <variablelist>
    <varlistentry>
     <term><literal>CARDINALITY</literal> (integer)</term>
     <listitem>
      <para>
       nombre de lignes dans l'ensemble du résultat
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>DATA</literal></term>
     <listitem>
      <para>
       élément de données en cours (de fait, le type de données de ce champ
       dépend de la requête)
      </para>
     </listitem>
    </varlistentry>


    <varlistentry>
     <term><literal>DATETIME_INTERVAL_CODE</literal> (integer)</term>
     <listitem>
      <para>
       ?
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>DATETIME_INTERVAL_PRECISION</literal> (integer)</term>
     <listitem>
      <para>
       non implémenté
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>INDICATOR</literal> (integer)</term>
     <listitem>
      <para>
       l'indicateur (indiquant une valeur nulle ou une troncature de la
       valeur)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>KEY_MEMBER</literal> (integer)</term>
     <listitem>
      <para>
       non implémenté
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>LENGTH</literal> (integer)</term>
     <listitem>
      <para>
       longueur de la donnée en caractères
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>NAME</literal> (string)</term>
     <listitem>
      <para>
       nom de la colonne
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>NULLABLE</literal> (integer)</term>
     <listitem>
      <para>
       non implémenté
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>OCTET_LENGTH</literal> (integer)</term>
     <listitem>
      <para>
       longueur en octets de la représentation en caractères de la donnée
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>PRECISION</literal> (integer)</term>
     <listitem>
      <para>
       précision (pour le type <type>numeric</type>)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>RETURNED_LENGTH</literal> (integer)</term>
     <listitem>
      <para>
       longueur de la donnée en caractère
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>RETURNED_OCTET_LENGTH</literal> (integer)</term>
     <listitem>
      <para>
       longueur en octets de la représentation en caractères de la donnée
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>SCALE</literal> (integer)</term>
     <listitem>
      <para>
       échelle (pour le type <type>numeric</type>)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>TYPE</literal> (integer)</term>
     <listitem>
      <para>
       code numérique du type de données de la colonne
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </sect1>

 <sect1 id="ecpg-errors">
  <title>Gestion des erreurs</title>

  <para>
   Cette section décrit la gestion des conditions exceptionnelles
   et des avertissements dans un programme SQL embarqué. Il existe
   plusieurs fonctions non exclusives pour cela.
  </para>

  <sect2>
   <title>Configurer des rappels</title>

   <para>
    Une méthode simple de récupération des erreurs et des avertissements consiste à
    configurer une action spécifique à exécuter à chaque fois qu'une condition
    particulière survient. En général&nbsp;:
<programlisting>
EXEC SQL WHENEVER <replaceable>condition</replaceable> <replaceable>action</replaceable>;
</programlisting>
   </para>

   <para>
    <replaceable>condition</replaceable> peut prendre une des valeurs
    suivantes&nbsp;:

    <variablelist>
     <varlistentry>
      <term><literal>SQLERROR</literal></term>
      <listitem>
       <para>
        L'action spécifiée est appelée lorsqu'une erreur survient
        pendant l'exécution d'une instruction SQL.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>SQLWARNING</literal></term>
      <listitem>
       <para>
        L'action spécifiée est appelée lorsqu'un avertissement
        survient pendant l'exécution d'une instruction SQL.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>NOT FOUND</literal></term>
      <listitem>
       <para>
        L'action spécifiée est appelée lorsqu'une instruction ne
        récupère ou n'affecte aucune ligne (cette condition n'est pas une
        erreur mais il peut être intéressant de la gérer de façon particulière).
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>

   <para>
    <replaceable>action</replaceable> peut avoir une des valeurs
    suivantes&nbsp;:

    <variablelist>
     <varlistentry>
      <term><literal>CONTINUE</literal></term>
      <listitem>
       <para>
        Signifie effectivement que la condition est ignorée. Ceci est la
        valeur par défaut.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>GOTO <replaceable>label</replaceable></literal></term>
      <term><literal>GO TO <replaceable>label</replaceable></literal></term>
      <listitem>
       <para>
        Saute au label spécifié (en utilisant une instruction C
        <literal>goto</literal>).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>SQLPRINT</literal></term>
      <listitem>
       <para>
        Affiche un message sur la sortie standard. Ceci est utile pour des
        programmes simples ou lors d'un prototypage. Les détails du message ne
        peuvent pas être configurés.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>STOP</literal></term>
      <listitem>
       <para>
        Appel de <literal>exit(1)</literal>, ce qui terminera le programme.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>BREAK</literal></term>
      <listitem>
       <para>
        Exécute l'instruction C <literal>break</literal>. Ceci devrait être
        utilisé uniquement dans des boucles ou dans des instructions
        <literal>switch</literal>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>CALL <replaceable>nom</replaceable>
        (<replaceable>args</replaceable>)</literal></term>
      <term><literal>DO <replaceable>nom</replaceable>
        (<replaceable>args</replaceable>)</literal></term>
      <listitem>
       <para>
        Appelle les fonctions C spécifiées avec les arguments spécifiés.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>

    Le standard SQL ne définit que les actions
    <literal>CONTINUE</literal> et <literal>GOTO</literal> (et
    <literal>GO TO</literal>).
   </para>

   <para>
    Voici un exemple utilisable dans un programme simple. Il affiche un message
    lorsqu'un avertissement survient et termine le programme quand une erreur se
    produit.
<programlisting>
EXEC SQL WHENEVER SQLWARNING SQLPRINT;
EXEC SQL WHENEVER SQLERROR STOP;
</programlisting>
   </para>

   <para>
    L'instruction <literal>EXEC SQL WHENEVER</literal> est une directive du
    préprocesseur SQL, pas une instruction C. Les actions sur les erreurs
    et avertissements qu'elle définit s'appliquent à toutes les instructions
    SQL embarquées qui apparaissent avant l'endroit où le gestionnaire est défini,
    à moins qu'une action différente n'ait été définie pour la même condition
    entre le premier <literal>EXEC SQL WHENEVER</literal> et l'instruction SQL
    qui a engendré la condition, quelque soit le flux de contrôle du programme C.
    De ce fait, aucun des deux extraits de programme C qui suivent n'aura le
    comportement désiré.
<programlisting>
/*
 * MAUVAIS
 */
int main(int argc, char *argv[])
{
    ...
    if (verbose) {
        EXEC SQL WHENEVER SQLWARNING SQLPRINT;
    }
    ...
    EXEC SQL SELECT ...;
    ...
}
</programlisting>

<programlisting>
/*
 * MAUVAIS
 */
int main(int argc, char *argv[])
{
    ...
    set_error_handler();
    ...
    EXEC SQL SELECT ...;
    ...
}

static void set_error_handler(void)
{
    EXEC SQL WHENEVER SQLERROR STOP;
}
</programlisting>
   </para>
  </sect2>

  <sect2>
   <title>sqlca</title>

   <para>
    Pour une gestion plus puissante des erreurs, l'interface du SQL embarqué
    fournit une variable globale de nom <varname>sqlca</varname> qui a la
    structure suivante&nbsp;:
<programlisting>
struct
{
    char sqlcaid[8];
    long sqlabc;
    long sqlcode;
    struct
    {
        int sqlerrml;
        char sqlerrmc[70];
    } sqlerrm;
    char sqlerrp[8];
    long sqlerrd[6];
    char sqlwarn[8];
    char sqlstate[5];
} sqlca;
</programlisting>
    (Dans un programme multithreadé, chaque thread obtient automatiquement sa
    propre copie de <varname>sqlca</varname>. Ceci fonctionne de façon similaire
    à la gestion de la variable globale C standard <varname>errno</varname>.)
   </para>

   <para>
    <varname>sqlca</varname> couvre à la fois les avertissements et les
    erreurs. Si plusieurs avertissements ou erreurs surviennent lors de
    l'exécution d'une instruction, alors <varname>sqlca</varname> ne contiendra
    que les informations relatives à la dernière.
   </para>

   <para>
    Si aucune erreur ne survient dans la dernière instruction <acronym>SQL</acronym>,
    <literal>sqlca.sqlcode</literal> vaudra 0 et
    <literal>sqlca.sqlstate</literal> vaudra <literal>"00000"</literal>. Si un
    avertissement ou une erreur a eu lieu, alors
    <literal>sqlca.sqlcode</literal> sera négatif et
    <literal>sqlca.sqlstate</literal> sera différent de
    <literal>"00000"</literal>. Un <literal>sqlca.sqlcode</literal> positif
    indique une condition sans dommage, telle que <quote>aucune ligne renvoyée
    par la dernière requête</quote>. <literal>sqlcode</literal> et
    <literal>sqlstate</literal> sont deux schémas de code d'erreur
    différents&nbsp;; les détails apparaissent ci-dessous.
   </para>

   <para>
    Si la dernière instruction SQL a réussi, alors
    <literal>sqlca.sqlerrd[1]</literal> contient l'OID de la ligne traitée, si
    applicable, et <literal>sqlca.sqlerrd[2]</literal> contient le nombre de
    lignes traitées ou renvoyées, si applicable à la commande.
   </para>

   <para>
    Dans le cas d'une erreur ou d'un avertissement,
    <literal>sqlca.sqlerrm.sqlerrmc</literal> contiendra une chaîne décrivant
    l'erreur. Le champ <literal>sqlca.sqlerrm.sqlerrml</literal> contient la
    longueur du message d'erreur stocké dans
    <literal>sqlca.sqlerrm.sqlerrmc</literal> (le résultat de
    <function>strlen()</function>, sans réel intérêt pour un
    programmeur C).
   </para>

   <para>
    Dans le cas d'un avertissement,
    <literal>sqlca.sqlwarn[2]</literal> est positionné à <literal>W</literal>.
    (Dans tous les autres cas, il est positionné à quelque chose de différent de
    <literal>W</literal>.) Si <literal>sqlca.sqlwarn[1]</literal> est positionné
    à <literal>W</literal>, alors une valeur a été tronquée lors de son stockage
    dans une variable hôte. <literal>sqlca.sqlwarn[0]</literal> est
    positionné à <literal>W</literal> si un autre élément est positionné pour
    indiquer un avertissement.
   </para>

   <para>
    Les champs <structfield>sqlcaid</structfield>,
    <structfield>sqlcabc</structfield>,
    <structfield>sqlerrp</structfield>, et les éléments restant de
    <structfield>sqlerrd</structfield> et
    <structfield>sqlwarn</structfield> ne contiennent actuellement
    aucune information utile.
   </para>

   <para>
    La structure <varname>sqlca</varname> n'est pas définie dans le standard
    SQL mais elle est implémentée dans plusieurs autres systèmes de bases de données SQL.
    Leurs définitions sont similaires dans leur esprit, mais l'écriture d'applications
    portables nécessite une étude attentive des autres implémentations.
   </para>
  </sect2>

  <sect2>
   <title><literal>SQLSTATE</literal> contre <literal>SQLCODE</literal></title>

   <para>
    Les champs <literal>sqlca.sqlstate</literal> et
    <literal>sqlca.sqlcode</literal> sont deux schémas différents fournissant
    des codes d'erreur. Les deux sont spécifiés dans le standard SQL mais