ecpg.xml

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

<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 le paquetage <acronym>SQL</acronym> embarqué pour
  <productname>PostgreSQL</productname>. Il a été écrit par
  Linus Tolke (<email>linus@epact.se</email>) et Michael Meskes
  (<email>meskes@postgresql.org</email>). Originellement, il a été écrit pour
  fonctionner avec le langage <acronym>C</acronym>. Il fonctionne aussi avec le
  <acronym>C++</acronym>, mais il ne reconnaît pas encore toutes les
  constructions <acronym>C++</acronym>.
 </para>

 <para>
  Cette documentation est assez incomplète. Mais du fait de la standardisation
  de cette interface, des informations complémentaires sont
  disponibles au 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, le <acronym>C</acronym> dans le cas
   présent, 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 compilateur <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'implantation <productname>PostgreSQL</productname>
   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&nbsp;:
<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 à l'aide de 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 indiquée d'une des façons
   suivantes&nbsp;:

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

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

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

    <listitem>
     <simpara>
      une chaîne SQL 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 indiquée littéralement (c'est-à-dire non pas via une
   variable de référence) et que 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ère 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 indiqué 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 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 le 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>
   Quelques exemples d'instructions <command>CONNECT</command>&nbsp;:
<programlisting>EXEC SQL CONNECT TO ma_base@sql.mondomaine.com;

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

EXEC SQL BEGIN DECLARE SECTION;
const char *cible = "ma_base@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 de référence de variable
   caractère, citée plus haut. L'utilisation de variables C dans les
   instructions SQL, en les préfixant d'un caractère deux-points, est expliqué 
   dans les prochaines sections.
  </para>

  <para>
   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 fondé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 indiqué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 indiqué, 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 procédures.
  </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 à l'aide de 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>
   Actualisations&nbsp;:
<programlisting>EXEC SQL UPDATE foo
    SET ascii = 'foobar'
    WHERE nombre = 9999;
EXEC SQL COMMIT;
</programlisting>
  </para>

  <para>
   Les lexèmes 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 du 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é
   supporte aussi la validation automatique des transactions (similaire au
   comportement de <application>libpq</application>) 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&nbsp;:
<programlisting>EXEC SQL AT <replaceable>nom-connexion</replaceable> SELECT ...;
</programlisting>
   Cette option est particulièrement adaptée si l'application a besoin
   d'utiliser alternativement plusieurs connexions.
  </para>

  <para>
   Si l'application utilise plusieurs threads (fil) d'exécution, ils ne peuvent
   pas concurrement partager une connexion. Il faut, soit contrôler explicitement l'accès
   à la connexion (en utilisant des mutex), soit utiliser une connexion pour
   chaque thread. Si chaque thread utilise sa propre connexion, il est
   nécessaire d'utiliser la clause AT pour préciser la connexion utilisée par le
   thread.
  </para>

  <para>
   La seconde option consiste à exécuter une instruction pour basculer la connexion
   courante. L'instruction est&nbsp;:
<programlisting>EXEC SQL SET CONNECTION <replaceable>nom-connexion</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
   gère pas les threads.
  </para>
 </sect1>

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

  <para>
   La <xref linkend="ecpg-commands"/> présente l'exécution d'instructions
   SQL à partir d'un programme SQL embarqué. Certaines 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étails
   l'échange de données entre le programme C et les instructions SQL embarquées
   à l'aide d'un mécanisme simple appelé <firstterm>variables
   hôtes</firstterm>. Dans un programme SQL embarqué, les
   instructions SQL sont considérées comme <firstterm>invitées</firstterm> dans le code du
   programme C qui est le <firstterm>langage hôte</firstterm>. Du coup, les
   variables du programme C sont appelées <firstterm>variables hôtes</firstterm>.
  </para>

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

   <para>
    L'échange de 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 SQL pour illustrer l'absence de restriction à l'utilisation
    d'un type de données ou d'un autre.
   </para>

   <para>
    Ce style d'insertion de variables C dans des instructions SQL fonctionne
    dans tous les cas où l'on attend une expression de valeur dans une instruction SQL.
   </para>
  </sect2>

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

   <para>
    Pour passer des données du programme à la base de données,
    comme paramètres 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&nbsp;:
<programlisting>EXEC SQL BEGIN DECLARE SECTION;
</programlisting>
    et se termine avec&nbsp;:
<programlisting>EXEC SQL END DECLARE SECTION;
</programlisting>
    Entre ces lignes, on trouve des déclarations normales de variables C,
    comme&nbsp;:
<programlisting>int   x = 4;
char  foo[16], bar[16];
</programlisting>
    Une valeur initiale optionnelle peut être affectée à la variable.
    La portée de la variable est déterminée par son emplacement
    dans la section de déclaration du programme.
    Les variables peuvent aussi être déclarées avec la syntaxe suivante qui crée
    implicitement une section de déclaration&nbsp;:
<programlisting>EXEC SQL int i = 4;
</programlisting>
    Le nombre de sections de déclarations dans un programme n'est pas limité.
   </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 nécessaire 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</literal>. Sinon, le préprocesseur, ne connaissant pas leur
    définition, ne peut pas gérer ces types.
   </para>
  </sect2>

<!-- variables hôtes ou variables hôte ? -->
  <sect2>
   <title>Les différents types de variables hôtes</title>
   <para>
    Des tableaux (<foreignphrase>array</foreignphrase>), définitions de type
    (<foreignphrase>typedef</foreignphrase>), structures
    (<foreignphrase>struct</foreignphrase>) et pointeurs
    (<foreignphrase>pointer</foreignphrase>) peuvent aussi être utilisés comme
    variables hôtes. Il existe également des types spéciaux de
    variables hôtes qui n'existent qu'en ECPG.
   </para>

   <para>
    Quelques exemples sur les variables hôtes&nbsp;:
    <variablelist>
     <varlistentry>
      <term>Tableaux</term>
      <listitem>
      <para>
       Une des utilisations les plus communes d'une déclaration de tableaux
       est certainement l'allocation d'un tableau de caractères&nbsp;:
<programlisting>EXEC SQL BEGIN DECLARE SECTION;
    char chaine[50];
EXEC SQL END DECLARE SECTION;
</programlisting>
       C'est à l'utilisateur de gérer la longueur du tableau. Si une telle
       variable hôte est utilisée comme variable cible d'une requête qui
       renvoie une chaîne de plus de 49 caractères, un dépassement de tampon
       survient.
      </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>Typedefs</term>
      <listitem>
      <para>
       Le mot clé <literal>typedef</literal> est utilisé pour faire correspondre
       de nouveaux types à des types déjà existants.
<programlisting>EXEC SQL BEGIN DECLARE SECTION;
    typedef char montypecaractere[40];
    typedef long serial_t;
EXEC SQL END DECLARE SECTION;
</programlisting>
       On peut aussi utiliser&nbsp;:
<programlisting>EXEC SQL TYPE serial_t IS long;
</programlisting>
       Cette déclaration n'a pas besoin de faire partie d'une section de
       déclaration.
      </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>Pointeurs</term>
      <listitem>
      <para>
       Des pointeurs peuvent être déclarés vers les types les plus communs.
       Néanmoins, Les pointeurs en
       tant que variables cibles de requêtes ne peuvent être utilisés sans
       allocation automatique.
       Voir <xref linkend="ecpg-descriptors"/> pour plus d'informations sur
       l'allocation automatique.
      </para>
<programlisting>EXEC SQL BEGIN DECLARE SECTION;
    int   *intp;
    char **charp;
EXEC SQL END DECLARE SECTION;
</programlisting>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>Types spéciaux de variables</term>
      <listitem>
       <para>
        ECPG contient certains types spéciaux qui facilitent l'interaction
	avec les données du serveur SQL. Par exemple, le support
        des types <type>varchar</type>, <type>numeric</type>, <type>date</type>,
	<type>timestamp</type> et <type>interval</type> a été
        implanté.
        <xref linkend="ecpg-pgtypes"/> contient des fonctions basiques de
        gestion de ces types. Il n'est ainsi pas nécessaire d'envoyer
        une requête au serveur SQL simplement pour ajouter un interval
        à une variable de type timestamp, par exemple.
       </para>

       <para>
        Le type spécial <type>VARCHAR</type> est converti en une
        <type>struct</type> nommée pour chaque variable. La déclaration&nbsp;:
<programlisting>VARCHAR var[180];
</programlisting>
        est convertie en&nbsp;:
<programlisting>struct varchar_var { int len; char arr[180]; } var;
</programlisting>
        Cette structure convient pour interfacer des données SQL
        de type <type>varchar</type>.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </sect2>

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

   <para>
    Les sections précédentes expliquent le passage de données entre
    l'application et une commande SQL. Pour récupérer le résultat d'une
    requête, 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 indique les variables hôtes de
    stockage des valeurs récupérées.
   </para>

   <para>
    Par exemple&nbsp;:
<programlisting>/*
 * Soit la table :
 * 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 la liste de
    sélection et la clause <literal>FROM</literal>.
    Le nombre d'éléments dans la liste du <command>select</command>
    et dans la liste qui suit <literal>INTO</literal> (aussi appelée liste
    cible) doivent être identiques.
   </para>

   <para>
    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 NULL. En fait, ces
    exemples de récupération affichent une erreur s'ils récupèrent une
    valeur NULL à partir de la base de données. Pour être capable de passer des
    valeurs NULL à la base de données ou de récupérer des valeurs NULL 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 NULL, auquel cas la valeur de la variable
    hôte réelle est ignorée. Exemple qui gère correctement la
    récupération de valeurs NULL&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> vaut zéro si la valeur
    n'est pas nulle, elle est négative dans le cas contraire.
   </para>

   <para>
    L'indicateur a une autre fonction&nbsp;: si la valeur de l'indicateur est
    positive, cela signifie que la valeur n'est pas 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 ce cas, il n'est pas possible
   d'embarquer directement les instructions SQL dans le code source C, mais il
   existe une fonctionnalité 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><![CDATA[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-pgtypes">
  <title>Bibliothèque pgtypes</title>

  <para>
   La bibliothèque pgtypes établit une correspondance entre les types
   <productname>PostgreSQL</productname> et les équivalents en C. Elle fournit
   aussi des fonctions permettant des calculs simples sur ces types en C,
   c'est-à-dire sans l'aide du serveur <productname>PostgreSQL</productname>.
   Par exemple&nbsp;:
<programlisting><![CDATA[EXEC SQL BEGIN DECLARE SECTION;
   date date1;
   timestamp ts1, tsout;
   interval iv1;
   char *out;
EXEC SQL END DECLARE SECTION;

PGTYPESdate_today(&date1);
EXEC SQL SELECT started, duration INTO :ts1, :iv1 FROM datetbl WHERE d=:date1;
PGTYPEStimestamp_add_interval(&ts1, &iv1, &tsout);
out = PGTYPEStimestamp_to_asc(&tsout);
printf("Started + duration: %s\n", out);
free(out);
]]></programlisting>
  </para>

  <sect2>
   <title>Le type numeric</title>
   <para>
    Le type numeric permet des calculs de précision arbitraire. Voir
    <xref linkend="datatype-numeric"/> pour le type équivalent dans le serveur
    <productname>PostgreSQL</productname>. Du fait de la précision arbitraire, 
    une variable de ce type doit pouvoir étendre et diminuer sa taille dynamiquement.
    C'est pourquoi il est obligatoire d'utiliser les fonctions 
    <function>PGTYPESnumeric_new</function> et
    <function>PGTYPESnumeric_free</function> pour créer de telles variables,
    et uniquement en mémoire <foreignphrase>heap</foreignphrase>.
    Le type decimal, similaire mais limité en précision, peut être créé sur la
    pile comme sur le <quote>heap</quote>.
   </para>
   <para>
    Les fonctions suivantes peuvent être utilisées avec le type numeric&nbsp;:
   <variablelist>
    <varlistentry>
     <term><function>PGTYPESnumeric_new</function></term>
     <listitem>
      <para>
      réclame un pointeur vers une variable de type numeric nouvellement allouée.
<synopsis>numeric *PGTYPESnumeric_new(void);
</synopsis>
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>PGTYPESnumeric_free</function></term>
     <listitem>
      <para>
      libère un type numeric en vidant toute sa mémoire.
<synopsis>void PGTYPESnumeric_free(numeric *var);
</synopsis>
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>PGTYPESnumeric_from_asc</function></term>
     <listitem>
      <para>
       analyse un type numeric à partir de sa notation en chaîne.
<synopsis>numeric *PGTYPESnumeric_from_asc(char *str, char **endptr);
</synopsis>
       Les formats valides sont, par exemple&nbsp;:
        <literal>-2</literal>,
        <literal>.794</literal>,
        <literal>+3.44</literal>,
        <literal>592.49E07</literal> ou
        <literal>-32.84e-4</literal>.
       Si la valeur a pu être analysée correctement, un pointeur valide est
       renvoyé. Dans le cas contraire, il s'agit d'un pointeur NULL.
       Actuellement, ecpg analyse toujours la chaîne complète et, du coup,
       ne supporte pas le stockage de l'adresse du premier caractère
       invalide dans <literal>*endptr</literal>. 
       <literal>endptr</literal> peut être initialisé à NULL en toute sécurité.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>PGTYPESnumeric_to_asc</function></term>
     <listitem>
      <para>
       renvoie un pointeur vers une chaîne allouée via <function>malloc</function>
       qui contient la représentation en chaîne du type numeric <literal>num</literal>.
<synopsis>char *PGTYPESnumeric_to_asc(numeric *num, int dscale);
</synopsis>
       La valeur numerique est affichée avec <literal>dscale</literal> chiffres
       décimaux, arrondie si nécessaire.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>PGTYPESnumeric_add</function></term>
     <listitem>
      <para>
       additionne deux variables de type numeric dans une troisième.
<synopsis>int PGTYPESnumeric_add(numeric *var1, numeric *var2, numeric *result);
</synopsis>
       La fonction additionne les variables <literal>var1</literal> et
       <literal>var2</literal> dans la variable résultat
       <literal>result</literal>.
       Elle renvoie 0 en cas de succès et -1 en cas d'erreur.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>PGTYPESnumeric_sub</function></term>
     <listitem>
      <para>
       soustrait deux variables de type numeric et renvoie le résultat dans une
       troisième.
<synopsis>int PGTYPESnumeric_sub(numeric *var1, numeric *var2, numeric *result);
</synopsis>
       La fonction soustrait la variable <literal>var2</literal> à la variable
       <literal>var1</literal>. Le résultat de cette opération est stocké dans la
       variable <literal>result</literal>.
       La fonction renvoie 0 en cas de succès et -1 en cas d'erreur.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>PGTYPESnumeric_mul</function></term>
     <listitem>
      <para>
       multiplie deux variables de type numeric et renvoie le résultat dans une
       troisième.
<synopsis>
int PGTYPESnumeric_mul(numeric *var1, numeric *var2, numeric *result);
</synopsis>
       La fonction multiplie les variables <literal>var1</literal> et
       <literal>var2</literal>. Le résultat de cette opération est stocké dans la
       variable <literal>result</literal>.
       La fonction renvoie 0 en cas de succès et -1 en cas d'erreur.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>PGTYPESnumeric_div</function></term>
     <listitem>
      <para>
       divise deux variables de type numeric et renvoie le résultat dans une
       troisième.
<synopsis>
int PGTYPESnumeric_div(numeric *var1, numeric *var2, numeric *result);
</synopsis>
       La fonction divise la variable <literal>var1</literal> par
       <literal>var2</literal>. Le résultat de cette opération est stocké dans la
       variable <literal>result</literal>.
       La fonction renvoie 0 en cas de succès et -1 en cas d'erreur.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>PGTYPESnumeric_cmp</function></term>
     <listitem>
      <para>
       compare deux variables de type numeric.
<synopsis>
int PGTYPESnumeric_cmp(numeric *var1, numeric *var2)
</synopsis>
       La fonction compare deux variables de type numeric. En cas
       d'erreur, <literal>INT_MAX</literal> est renvoyé. En cas de succès, la
       fonction renvoie un des trois résultats possibles&nbsp;:
       <itemizedlist>
        <listitem>
         <para>
          1, si <literal>var1</literal> est plus grand que <literal>var2</literal>
         </para>
        </listitem>
        <listitem>
         <para>
          -1, si <literal>var1</literal> est plus petit que <literal>var2</literal>
         </para>
        </listitem>
        <listitem>
         <para>
          0, si <literal>var1</literal> est égal à <literal>var2</literal>
         </para>
        </listitem>
       </itemizedlist>
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>PGTYPESnumeric_from_int</function></term>
     <listitem>
      <para>
       convertit une variable de type int en une variable de type numeric.
<synopsis>
int PGTYPESnumeric_from_int(signed int int_val, numeric *var);
</synopsis>
       La fonction accepte une variable de type signed int (entier signé) et la stocke
       dans la variable <literal>var</literal> de type numeric.
       La fonction renvoie 0 en cas de succès et -1 en cas d'erreur.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>PGTYPESnumeric_from_long</function></term>
     <listitem>
      <para>
       convertit une variable de type long int en une variable de type numeric.
<synopsis>
int PGTYPESnumeric_from_long(signed long int long_val, numeric *var);
</synopsis>
       La fonction accepte une variable de type signed long int (entier long
       signé) et la stocke
       dans la variable <literal>var</literal> de type numeric.
       La fonction renvoie 0 en cas de succès et -1 en cas d'erreur.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>PGTYPESnumeric_copy</function></term>
     <listitem>
      <para>
       copie une variable de type numeric dans une autre.
<synopsis>
int PGTYPESnumeric_copy(numeric *src, numeric *dst);
</synopsis>
       la fonction copie la valeur de la variable sur laquelle pointe
       <literal>src</literal> dans la variable sur laquelle pointe
       <literal>dst</literal>.
       La fonction renvoie 0 en cas de succès et -1 en cas d'erreur.
      </para>
     </listitem>
    </varlistentry>

<!-- SAS : 20070522 
    Il y a le type numeric, type SQL, et le numérique qui est une
    représentation sous la forme de chiffres d'un nombre -->
    <varlistentry>
     <term><function>PGTYPESnumeric_from_double</function></term>
     <listitem>
      <para>
       convertit une variable de type double en numeric.
<synopsis>
int  PGTYPESnumeric_from_double(double d, numeric *dst);
</synopsis>
       La fonction accepte une variable de type double et la stocke dans la
       variable sur laquelle pointe <literal>dst</literal>.
       La fonction renvoie 0 en cas de succès et -1 en cas d'erreur.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>PGTYPESnumeric_to_double</function></term>
     <listitem>
      <para>
       convertit une variable de type numeric en double.
<synopsis>
int PGTYPESnumeric_to_double(numeric *nv, double *dp)
</synopsis>
       La fonction convertit la valeur numérique de la variable pointée par
       <literal>nv</literal> dans la variable de type double pointée
       par <literal>dp</literal>.
       La fonction renvoie 0 en cas de succès et -1 en cas d'erreur,
       dépassement inclus. En cas de dépassement, la variable globale
       <literal>errno</literal> est positionnée à
       <literal>PGTYPES_NUM_OVERFLOW</literal>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>PGTYPESnumeric_to_int</function></term>
     <listitem>
      <para>
       convertit une variable de type numeric en int.
<synopsis>
int PGTYPESnumeric_to_int(numeric *nv, int *ip);
</synopsis>
       La fonction convertit la valeur numérique de la variable pointée par
       <literal>nv</literal> en une variable de type integer pointée par
       <literal>ip</literal>.
       La fonction renvoie 0 en cas de succès et -1 en cas d'erreur,
       dépassement inclus. En cas de dépassement, la variable globale
       <literal>errno</literal> est initialisée à
       <literal>PGTYPES_NUM_OVERFLOW</literal>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>PGTYPESnumeric_to_long</function></term>
     <listitem>
      <para>
       convertit une variable de type numeric en long int.
<synopsis>
int PGTYPESnumeric_to_long(numeric *nv, long *lp);
</synopsis>
       La fonction convertit la valeur numérique de la variable pointée par 
       <literal>nv</literal> en une variable de type long integer pointée par
       <literal>lp</literal>.
       La fonction renvoie 0 en cas de succès et -1 en cas d'erreur,
       dépassement inclus. En cas de dépassement, la variable globale
       <literal>errno</literal> est initialisée à
       <literal>PGTYPES_NUM_OVERFLOW</literal>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>PGTYPESnumeric_to_decimal</function></term>
     <listitem>
      <para>
       convertit une variable de type numeric en decimal.
<synopsis>
int PGTYPESnumeric_to_decimal(numeric *src, decimal *dst);
</synopsis>
       La fonction convertit la valeur numérique de la variable pointée par
       <literal>nv</literal> en une variable de type decimal pointée par
       <literal>dst</literal>.
       La fonction renvoie 0 en cas de succès et -1 en cas d'erreur,
       dépassement inclus. En cas de débordement, la variable globale
       <literal>errno</literal> est initialisée à
       <literal>PGTYPES_NUM_OVERFLOW</literal>.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><function>PGTYPESnumeric_from_decimal</function></term>
     <listitem>
      <para>
       convertit une variable de type decimal en numeric.
<synopsis>
int PGTYPESnumeric_from_decimal(decimal *src, numeric *dst);
</synopsis>
       La fonction convertit la valeur décimale de la variable pointée par
       <literal>nv</literal> en une variable de type numeric pointée par
       <literal>dst</literal>.
       La fonction renvoie 0 en cas de succès et -1 en cas d'erreur. Comme
       le type decimal est une version limitée du type numeric, aucun
       dépassement ne peut survenir avec cette conversion.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
   </para>
  </sect2>

  <sect2>
   <title>Le type date</title>
   <para>
    Le type date en C permet aux programmes de gérer les données de type date
    SQL.
    Voir <xref linkend="datatype-datetime"/> pour le type équivalent dans le
    serveur <productname>PostgreSQL</productname>.
   </para>
   <para>
    Les fonctions qui suivent peuvent être utilisées pour travailler avec le type
    date&nbsp;:
    <variablelist>
     <varlistentry id="PGTYPESdatefromtimestamp">
      <term><function>PGTYPESdate_from_timestamp</function></term>
      <listitem>
       <para>
        extrait la date d'une variable de type timestamp.
<synopsis>
date PGTYPESdate_from_timestamp(timestamp dt);
</synopsis>
	    La fonction reçoit une variable de type timestamp comme seul argument
	    et en retourne la partie date.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPESdatefromasc">
      <term><function>PGTYPESdate_from_asc</function></term>
      <listitem>
       <para>
        analyse une date à partir de sa représentation textuelle.
<synopsis>
date PGTYPESdate_from_asc(char *str, char **endptr);
</synopsis>
	    La fonction reçoit une chaîne C (char*) <literal>str</literal> et un
	    pointeur vers une autre chaîne C, <literal>endptr</literal>. À ce
	    jour, ecpg analyse toujours la chaîne complète et ne peut donc pas
	    stocker l'adresse du premier caractère invalide dans <literal>*endptr</literal>.
	    <literal>endptr</literal> peut être initialisé à NULL en toute
	    sécurité.
       </para>
       <para>
	    La fonction estime systématiquement recevoir des dates au format
	    MDY. Il n'y a actuellement aucune variable qui permette de
	    modifier cela dans ecpg.
       </para>
       <para>
        <xref linkend="ecpg-pgtypesdate-from-asc-table"/> affiche les format de
	saisie autorisés.
       </para>
        <table id="ecpg-pgtypesdate-from-asc-table">
	 <title>Formats de saisie valides pour <function>PGTYPESdate_from_asc</function></title>
	 <tgroup cols="2">
	  <thead>
	   <row>
	   <!-- J'ai un doute sur la localisation de ces chaînes -->
	    <entry>Saisie</entry>
	    <entry>Résultat</entry>
	   </row>
	  </thead>
	  <tbody>
	   <row>
	    <entry><literal>January 8, 1999</literal></entry>
	    <entry><literal>January 8, 1999</literal></entry>
	   </row>
	   <row>
	    <entry><literal>1999-01-08</literal></entry>
	    <entry><literal>January 8, 1999</literal></entry>
	   </row>
	   <row>
	    <entry><literal>1/8/1999</literal></entry>
	    <entry><literal>January 8, 1999</literal></entry>
	   </row>
	   <row>
	    <entry><literal>1/18/1999</literal></entry>
	    <entry><literal>January 18, 1999</literal></entry>
	   </row>
	   <row>
	    <entry><literal>01/02/03</literal></entry>
	    <entry><literal>February 1, 2003</literal></entry>
	   </row>
	   <row>
	    <entry><literal>1999-Jan-08</literal></entry>
	    <entry><literal>January 8, 1999</literal></entry>
	   </row>
	   <row>
	    <entry><literal>Jan-08-1999</literal></entry>
	    <entry><literal>January 8, 1999</literal></entry>
	   </row>
	   <row>
	    <entry><literal>08-Jan-1999</literal></entry>
	    <entry><literal>January 8, 1999</literal></entry>
	   </row>
	   <row>
	    <entry><literal>99-Jan-08</literal></entry>
	    <entry><literal>January 8, 1999</literal></entry>
	   </row>
	   <row>
	    <entry><literal>08-Jan-99</literal></entry>
	    <entry><literal>January 8, 1999</literal></entry>
	   </row>
	   <row>
	    <entry><literal>08-Jan-06</literal></entry>
	    <entry><literal>January 8, 2006</literal></entry>
	   </row>
	   <row>
	    <entry><literal>Jan-08-99</literal></entry>
	    <entry><literal>January 8, 1999</literal></entry>
	   </row>
	   <row>
	    <entry><literal>19990108</literal></entry>
	    <entry><literal>ISO 8601; January 8, 1999</literal></entry>
	   </row>
	   <row>
	    <entry><literal>990108</literal></entry>
	    <entry><literal>ISO 8601; January 8, 1999</literal></entry>
	   </row>
	   <row>
	    <entry><literal>1999.008</literal></entry>
	    <entry><literal>year and day of year</literal></entry>
	   </row>
	   <row>
	    <entry><literal>J2451187</literal></entry>
	    <entry><literal>Julian day</literal></entry>
	   </row>
	   <row>
	    <entry><literal>January 8, 99 BC</literal></entry>
	    <entry><literal>year 99 before the Common Era</literal></entry>
	   </row>
          </tbody>
         </tgroup>
        </table>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPESdatetoasc">
      <term><function>PGTYPESdate_to_asc</function></term>
      <listitem>
       <para>
        renvoie la représentation textuelle d'une variable date.
<synopsis>
char *PGTYPESdate_to_asc(date dDate);
</synopsis>
	    La fonction reçoit la date <literal>dDate</literal> comme seul
	    paramètre. Elle affiche la date sous la forme
	    <literal>1999-01-18</literal>, c'est-à-dire dans le format
	    <literal>YYYY-MM-DD</literal>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPESdatejulmdy">
      <term><function>PGTYPESdate_julmdy</function></term>
      <listitem>
       <para>
	    extrait les valeurs du jour, du mois et de l'année à partir d'une
	    variable de type date.
<synopsis>
void PGTYPESdate_julmdy(date d, int *mdy);
</synopsis>
        <!-- almost same description as for rjulmdy() -->
	    La fonction reçoit la date <literal>d</literal> et un pointeur sur
	    un tableau de trois valeurs entières <literal>mdy</literal>. Le nom de
	    la variable indique l'ordre de séquence&nbsp;: <literal>mdy[0]</literal>
	    contient le numéro du mois, <literal>mdy[1]</literal> le jour et
	    <literal>mdy[2]</literal> l'année.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPESdatemdyjul">
      <term><function>PGTYPESdate_mdyjul</function></term>
      <listitem>
       <para>
	    crée une valeur date à partir d'un tableau de trois entiers qui précisent
	    le jour, le mois et l'année de la date.
<synopsis>
void PGTYPESdate_mdyjul(int *mdy, date *jdate);
</synopsis>
	    La fonction prend le tableau de trois entiers (<literal>mdy</literal>)
	    comme premier argument et un pointeur sur une variable de type date
	    comme second argument. Ce dernier reçoit le résultat de l'opération.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPESdatedayofweek">
      <term><function>PGTYPESdate_dayofweek</function></term>
      <listitem>
       <para>
        renvoie un nombre représentant le jour de la semaine pour une valeur de
        type date.
<synopsis>
int PGTYPESdate_dayofweek(date d);
</synopsis>
	    La fonction reçoit la variable <literal>d</literal> de type date
	    comme seul argument et renvoie un entier indiquant le jour de la semaine
	    associé à cette date.
        <itemizedlist>
         <listitem>
          <para>
	   0 - Dimanche
          </para>
         </listitem>
         <listitem>
          <para>
	   1 - Lundi
          </para>
         </listitem>
         <listitem>
          <para>
	   2 - Mardi
          </para>
         </listitem>
         <listitem>
          <para>
	   3 - Mercredi
          </para>
         </listitem>
         <listitem>
          <para>
	   4 - Jeudi
          </para>
         </listitem>
         <listitem>
          <para>
	   5 - Vendredi
          </para>
         </listitem>
         <listitem>
          <para>
	   6 - Samedi
          </para>
         </listitem>
        </itemizedlist>
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPESdatetoday">
      <term><function>PGTYPESdate_today</function></term>
      <listitem>
       <para>
        récupère la date courante.
<synopsis>
void PGTYPESdate_today(date *d);
</synopsis>
	    La fonction reçoit un pointeur vers une variable date
	    (<literal>d</literal>) et l'initialise à la date couratne.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPESdatefmtasc">
      <term><function>PGTYPESdate_fmt_asc</function></term>
      <listitem>
       <para>
	convertit une variable de type date en sa représentation textuelle à
	l'aide d'un masque de format.
<synopsis>
int PGTYPESdate_fmt_asc(date dDate, char *fmtstring, char *outbuf);
</synopsis>
	La fonction reçoit la date à convertir (<literal>dDate</literal>),
	    le masque de format (<literal>fmtstring</literal>) et la chaîne
	    de récupération de la représentation textuelle de la date
	    (<literal>outbuf</literal>).
       </para>
       <para>
        La fonction renvoie 0 en cas de succès et une valeur négative en cas
        d'erreur.
       </para>
       <para>
        Les chaînes suivantes indiquent les champs à utiliser&nbsp;:
        <itemizedlist>
         <listitem>
          <para>
           <literal>dd</literal> - le numéro du jour dans le mois&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>mm</literal> - le numéro du mois dans l'année&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>yy</literal> - le numéro de l'année sur deux
	   chiffres&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>yyyy</literal> - le numéro de l'année sur quatre
	   chiffres&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>ddd</literal> - l'abréviation du nom du jour&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
           <literal>mmm</literal> - l'abréviation du nom du mois.
          </para>
         </listitem>
        </itemizedlist>
	    Tous les autres caractères sont copiés un à un dans la chaîne de
	    sortie.
       </para>
       <para>
	<!-- SAS : Là encore se pose la question de la localisation -->
        <xref linkend="ecpg-pgtypesdate-fmt-asc-example-table"/> indique
	quelques formats possibles. Ceci vous donnera une idée de la façon
	d'utiliser cette fonction. Toutes les lignes en sortie sont basées sur
	la même date&nbsp;: 23 novembre 1959.
       </para>
        <table id="ecpg-pgtypesdate-fmt-asc-example-table">
	 <title>Formats valides en entrée de <function>PGTYPESdate_fmt_asc</function></title>
	 <tgroup cols="2">
	  <thead>
	   <row>
	    <entry>Format</entry>
	    <entry>Résultat</entry>
	   </row>
	  </thead>
	  <tbody>
	   <row>
	    <entry><literal>mmddyy</literal></entry>
	    <entry><literal>112359</literal></entry>
	   </row>
	   <row>
	    <entry><literal>ddmmyy</literal></entry>
	    <entry><literal>231159</literal></entry>
	   </row>
	   <row>
	    <entry><literal>yymmdd</literal></entry>
	    <entry><literal>591123</literal></entry>
	   </row>
	   <row>
	    <entry><literal>yy/mm/dd</literal></entry>
	    <entry><literal>59/11/23</literal></entry>
	   </row>
	   <row>
	    <entry><literal>yy mm dd</literal></entry>
	    <entry><literal>59 11 23</literal></entry>
	   </row>
	   <row>
	    <entry><literal>yy.mm.dd</literal></entry>
	    <entry><literal>59.11.23</literal></entry>
	   </row>
	   <row>
	    <entry><literal>.mm.yyyy.dd.</literal></entry>
	    <entry><literal>.11.1959.23.</literal></entry>
	   </row>
	   <row>
	    <entry><literal>mmm. dd, yyyy</literal></entry>
	    <entry><literal>Nov. 23, 1959</literal></entry>
	   </row>
	   <row>
	    <entry><literal>mmm dd yyyy</literal></entry>
	    <entry><literal>Nov 23 1959</literal></entry>
	   </row>
	   <row>
	    <entry><literal>yyyy dd mm</literal></entry>
	    <entry><literal>1959 23 11</literal></entry>
	   </row>
	   <row>
	    <entry><literal>ddd, mmm. dd, yyyy</literal></entry>
	    <entry><literal>Mon, Nov. 23, 1959</literal></entry>
	   </row>
	   <row>
	    <entry><literal>(ddd) mmm. dd, yyyy</literal></entry>
	    <entry><literal>(Mon) Nov. 23, 1959</literal></entry>
	   </row>
          </tbody>
         </tgroup>
        </table>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPESdatedefmtasc">
      <term><function>PGTYPESdate_defmt_asc</function></term>
      <listitem>
       <para>
	    utilise un masque de format pour convertir une chaîne C (char*) en une
	    valeur de type date.
<synopsis>
int PGTYPESdate_defmt_asc(date *d, char *fmt, char *str);
</synopsis>
	    <!-- same description as rdefmtdate -->
	    Cette fonction prend en argumant un pointeur sur la valeur de type
	    date de stockage du résultat de l'opération (<literal>d</literal>), le masque
	    du format à utiliser pour analyser la date (<literal>fmt</literal>) et
	    la chaîne C qui contient la représentation textuelle de la date
	    (<literal>str</literal>). La représentation textuelle doit correspondre
	    au masque de format. Il n'est toutefois pas nécessaire d'avoir une
	    correspondance exacte. La fonction analyse simplement l'ordre
	    séquentiel et cherche les libellés <literal>yy</literal> ou
	    <literal>yyyy</literal> qui indiquent la position de l'année,
	    <literal>mm</literal> pour celle du mois et <literal>dd</literal>
	    pour celle du jour.
       </para>
       <para>
	    <!-- SAS : Localisation ? -->
        <xref linkend="ecpg-rdefmtdate-example-table"/> indique les quelques
	formats possibles. Ceci vous donnera une idée de la façon d'utiliser
	ces fonctions.
       </para>
        <table id="ecpg-rdefmtdate-example-table">
	 <title>Formats valides en entrée de  <function>rdefmtdate</function></title>
	 <tgroup cols="2">
	  <thead>
	   <row>
	    <entry>Format</entry>
	    <entry>Chaîne</entry>
	    <entry>Résultat</entry>
	   </row>
	  </thead>
	  <tbody>
	   <row>
	    <entry><literal>ddmmyy</literal></entry>
	    <entry><literal>21-2-54</literal></entry>
	    <entry><literal>1954-02-21</literal></entry>
	   </row>
	   <row>
	    <entry><literal>ddmmyy</literal></entry>
	    <entry><literal>2-12-54</literal></entry>
	    <entry><literal>1954-12-02</literal></entry>
	   </row>
	   <row>
	    <entry><literal>ddmmyy</literal></entry>
	    <entry><literal>20111954</literal></entry>
	    <entry><literal>1954-11-20</literal></entry>
	   </row>
	   <row>
	    <entry><literal>ddmmyy</literal></entry>
	    <entry><literal>130464</literal></entry>
	    <entry><literal>1964-04-13</literal></entry>
	   </row>
	   <row>
	    <entry><literal>mmm.dd.yyyy</literal></entry>
	    <entry><literal>MAR-12-1967</literal></entry>
	    <entry><literal>1967-03-12</literal></entry>
	   </row>
	   <row>
	    <entry><literal>yy/mm/dd</literal></entry>
	    <entry><literal>1954, February 3rd</literal></entry>
	    <entry><literal>1954-02-03</literal></entry>
	   </row>
	   <row>
	    <entry><literal>mmm.dd.yyyy</literal></entry>
	    <entry><literal>041269</literal></entry>
	    <entry><literal>1969-04-12</literal></entry>
	   </row>
	   <row>
	    <entry><literal>yy/mm/dd</literal></entry>
	    <entry><literal>En l'an 2525, au mois de juillet, on trouvera bien
	    quelqu'un de vivant le 28ème jour (In the year
	    2525, in the month of July, mankind will be alive on the 28th
	    day)</literal></entry>
	    <entry><literal>2525-07-28</literal></entry>
	   </row>
	   <row>
	    <entry><literal>dd-mm-yy</literal></entry>
	    <entry><literal>J'ai dit le 28 juillet de l'an 2525
	    (I said on the 28th of July in the year
	    2525)</literal></entry>
	    <entry><literal>2525-07-28</literal></entry>
	   </row>
	   <row>
	    <entry><literal>mmm.dd.yyyy</literal></entry>
	    <entry><literal>9/14/58</literal></entry>
	    <entry><literal>1958-09-14</literal></entry>
	   </row>
	   <row>
	    <entry><literal>yy/mm/dd</literal></entry>
	    <entry><literal>47/03/29</literal></entry>
	    <entry><literal>1947-03-29</literal></entry>
	   </row>
	   <row>
	    <entry><literal>mmm.dd.yyyy</literal></entry>
	    <entry><literal>oct 28 1975</literal></entry>
	    <entry><literal>1975-10-28</literal></entry>
	   </row>
	   <row>
	    <entry><literal>mmddyy</literal></entry>
	    <entry><literal>Nov 14th, 1985</literal></entry>
	    <entry><literal>1985-11-14</literal></entry>
	   </row>
          </tbody>
         </tgroup>
        </table>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </sect2>
 
  <sect2>
   <title>Le type timestamp</title>
   <para>
    Le type timestamp en C permet aux programmes de gérer les données de type
    timestamp SQL. Voir <xref linkend="datatype-datetime"/> pour le type
    équivalent dans le serveur <productname>PostgreSQL</productname>.
   </para>
   <para>
    Le fonctions qui suivent sont utilisées pour travailler avec le type
    timestamp&nbsp;:
    <variablelist>
     <varlistentry id="PGTYPEStimestampfromasc">
      <term><function>PGTYPEStimestamp_from_asc</function></term>
      <listitem>
       <para>
	    analyse une variable de type timestamp à partir de sa représentation
	    textuelle et la stocke dans une variable de type timestamp.
<synopsis>
timestamp PGTYPEStimestamp_from_asc(char *str, char **endptr);
</synopsis>
	    La fonction prend en arguments la chaîne à analyser (<literal>str</literal>) et
	    un pointeur sur une chaîne C de type char* (<literal>endptr</literal>).
	    Actuellement, ecpg analyse toujours la chaîne complète et ne
	    permet pas de stocker l'adresse du premier caractère invalide
	    dans <literal>*endptr</literal>. <literal>endptr</literal> peut
	    être initialisé à NULL en toute sécurité.
       </para>
       <para>
        La fonction renvoie la variable de type timestamp analysée en cas de
        succès. En cas d'erreur, <literal>PGTYPESInvalidTimestamp</literal> est
        renvoyée et errno vaut <literal>PGTYPES_TS_BAD_TIMESTAMP</literal>. Voir
        <xref linkend="PGTYPESInvalidTimestamp"/> pour d'importantes informations
        sur cette valeur.
       </para>
       <para>
	En général, la chaîne saisie peut contenir toute combinaison de
	spécification autorisée de date, d'espace et de spécification
	autorisée d'heure. Les fuseaux horaires ne sont pas supportés par ecpg.
	    Il peut les analyser mais n'applique aucun calcul au contraire du serveur
	    <productname>PostgreSQL</productname> par exemple. Les fuseaux horaires
	    sont ignorés silencieusement.
       </para>
       <para>
	<!-- SAS : localisation ? -->
        <xref linkend="ecpg-pgtypestimestamp-from-asc-example-table"/> contient
	quelques exemples pour les chaînes en entrée.
       </para>
        <table id="ecpg-pgtypestimestamp-from-asc-example-table">
	 <title>Formats de saisie valides pour <function>PGTYPEStimestamp_from_asc</function></title>
	 <tgroup cols="2">
	  <thead>
	   <row>
	    <entry>Saisie</entry>
	    <entry>Résultat</entry>
	   </row>
	  </thead>
	  <tbody>
	   <row>
	    <entry><literal>1999-01-08 04:05:06</literal></entry>
	    <entry><literal>1999-01-08 04:05:06</literal></entry>
	   </row>
	   <row>
	    <entry><literal>January 8 04:05:06 1999 PST</literal></entry>
	    <entry><literal>1999-01-08 04:05:06</literal></entry>
	   </row>
	   <row>
	    <entry><literal>1999-Jan-08 04:05:06.789-8</literal></entry>
	    <entry><literal>1999-01-08 04:05:06.789 (fuseau horaire ignoré)</literal></entry>
	   </row>
	   <row>
	    <entry><literal>J2451187 04:05-08:00</literal></entry>
	    <entry><literal>1999-01-08 04:05:00 (fuseau horaire ignoré)</literal></entry>
	   </row>
          </tbody>
         </tgroup>
        </table>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPEStimestamptoasc">
      <term><function>PGTYPEStimestamp_to_asc</function></term>
      <listitem>
       <para>
        convertit une date en chaîne C char*.
<synopsis>
char *PGTYPEStimestamp_to_asc(timestamp tstamp);
</synopsis>
	 La fonction prend comme seul argument la variable <literal>tstamp</literal> de type
	    timestamp et renvoie une chaîne allouée qui contient
	    la représentation textuelle du timestamp.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPEStimestampcurrent">
      <term><function>PGTYPEStimestamp_current</function></term>
      <listitem>
       <para>
        récupère le timestamp courant.
<synopsis>
void PGTYPEStimestamp_current(timestamp *ts);
</synopsis>
	    La fonction récupère le timestamp courant et le sauvegarde dans la
	    variable de type timestamp pointée par <literal>ts</literal>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPEStimestampfmtasc">
      <term><function>PGTYPEStimestamp_fmt_asc</function></term>
      <listitem>
       <para>
        convertit une variable de type timestamp en une chaîne C de type char*
        à l'aide d'un masque de formatage.
<synopsis>
int PGTYPEStimestamp_fmt_asc(timestamp *ts, char *output, int str_len, char *fmtstr);
</synopsis>
	   La fonction prend en arguments un pointeur vers la variable de type timestamp
	 (<literal>ts</literal>), un pointeur vers le tampon
	 de sortie (<literal>output</literal>), la longueur maximale
	   allouée pour le tampon de sortie (<literal>str_len</literal>) et le masque
	   de formatage à utiliser pour la conversion (<literal>fmtstr</literal>).
       </para>
       <para>
	    La fonction renvoie 0 en cas de succès et une valeur négative en cas
        d'erreur.
       </para>
       <para>
	    Les caractères de formatage qui suivent peuvent être utilisés
	    comme masque de formatage. Ces caractères sont identiques à ceux utilisés dans la
	    fonction <function>strftime</function> de <productname>libc</productname>.
	    Tout caractère n'en faisant pas partie est copié tel quel dans le
	    tampon de sortie.
	<!-- This is from the FreeBSD man page:
	     http://www.freebsd.org/cgi/man.cgi?query=strftime&apropos=0&sektion=3&manpath=FreeBSD+7.0-current&format=html
	-->
        <itemizedlist>
         <listitem>
          <para>
	   <literal>%A</literal> - remplacé par la représentation nationale du nom
	   complet du jour de la semaine&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%a</literal> - remplacé par la représentation nationale de
	   l'abréviation du nom de la semaine&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%B</literal> - remplacé par la représentation nationale du nom
	   complet du mois&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%b</literal> - remplacé par la représentation nationale de
	   l'abréviation du nom du mois&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%C</literal> - remplacé par (année / 100) en nombre
	   décimal, les chiffres seuls sont précédés d'un zéro&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%c</literal> - remplacé par la représentation nationale de
	   l'heure et de la date&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%D</literal> - est équivalent à
	   <literal>%m/%d/%y</literal>.
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%d</literal> - est remplacé par le jour du mois en
	   nombre décimal (01-31)&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%E*</literal> <literal>%O*</literal> -  extensions POSIX de la
	   locale. Les séquences
	   <literal>%Ec</literal>
	   <literal>%EC</literal> 
	   <literal>%Ex</literal> 
	   <literal>%EX</literal> 
	   <literal>%Ey</literal> 
	   <literal>%EY</literal> 
	   <literal>%Od</literal> 
	   <literal>%Oe</literal>
	   <literal>%OH</literal> 
	   <literal>%OI</literal> 
	   <literal>%Om</literal> 
	   <literal>%OM</literal> 
	   <literal>%OS</literal> 
	   <literal>%Ou</literal> 
	   <literal>%OU</literal> 
	   <literal>%OV</literal> 
	   <literal>%Ow</literal> 
	   <literal>%OW</literal> 
	   <literal>%Oy</literal> 
	   sont supposées fournir d'autres représentations.
          </para>
          <para>
	   De plus, <literal>%OB</literal> permet de représenter les autres
	   noms des mois (utilisés en autonome, sans mention du jour)&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%e</literal> - est remplacé par le jour du mois en nombre
	   décimal (1-31)&nbsp;; les chiffres seuls sont précédés d'un
	   zéro&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%F</literal> - est équivalent à
	   <literal>%Y-%m-%d</literal>&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%G</literal> - est remplacé par une année comme nombre
	   décimal avec le siècle. Il s'agit de l'année qui contient la plus
	   grande partie de la semaine (lundi étant le premier jour de la
	   semaine)&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%g</literal> - est remplacé par la même année que
	   <literal>%G</literal> mais en décimal sans le siècle
	   (00-99)&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%H</literal> - est remplacé par l'heure (sur 24 heures) en
	   nombre décimal (00-23)&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%h</literal> - idem à <literal>%b</literal>&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%I</literal> - est remplacé par l'heure (sur 12 heures) en
	   nombre décimal (01-12)&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%j</literal> - est remplacé par le jour de l'année en nombre
	   décimal (001-366)&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%k</literal> - est remplacé par l'heure (sur 24 heures) en
	   nombre décimal (0-23), les chiffres seuls sont précédés d'un
	   zéro&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%l</literal> - est remplacé par l'heure (sur 12 heures) en
	   nombre décimal (1-12), les chiffres seuls sont précédés d'un zéro&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%M</literal> - est remplacé par la minute en nombre décimal
	   (00-59)&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%m</literal> - est remplacé par le mois en nombre décimal
	   (01-12)&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	  <literal>%n</literal> - est remplacé par un retour chariot&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%O*</literal> - identique à <literal>%E*</literal>&nbsp;;
          </para>
         </listitem>
         <listitem>
	 <!-- SAS : ante meridiem est un terme latin -->
          <para>
	   <literal>%p</literal> - remplacé par la représentation nationale de 
	   « ante meridiem » ou « post meridiem » suivant le cas&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%R</literal> - est équivalent à
	   <literal>%H:%M</literal>&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%r</literal> - est équivalent à <literal>%I:%M:%S
	   %p</literal>&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%S</literal> - est remplacé par la seconde en nombre décimal
	   (00-60)&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%s</literal> - est remplacé par le nombre de secondes depuis
	   Epoch, UTC&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%T</literal> - est équivalent à
	   <literal>%H:%M:%S</literal>&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%t</literal> - est remplacé par une tabulation&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%U</literal> - est remplacé par le numéro de la semaine dans
	   l'année (dimanche étant le premier jour de l'année) en nombre décimal
	   (00-53)&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%u</literal> - est remplacé par le jour de la semaine (lundi
	   étant le premier jour de la semaine) en nombre décimal (1-7)&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%V</literal> - est remplacé par le numéro de la semaine dans
	   l'année (lundi étant le premier jour de la semaine) en nombre décimal
	   (01-53). Si la semaine contenant le 1er janvier a quatre jours ou
	   plus dans la nouvelle année, alors c'est la semaine 1&nbsp;; sinon
	   c'est la dernière semaine de l'année précédente et la semaine
	   suivante est la semaine 1&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%v</literal> - est équivalent à
	   <literal>%e-%b-%Y</literal>&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%W</literal> - est remplacé par le numéro de semaine de
	   l'année (lundi étant le premier jour de la semaine) en nombre
	   décimal (00-53)&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%w</literal> - est remplacé par le jour de la semaine
	   (dimanche étant le premier jour de la semaine) en nombre décimal
	   (0-6)&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%X</literal> - est remplacé par la représentation nationale
	   de l'heure&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%x</literal> - est remplacé par la représentation nationale de
	   la date&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%Y</literal> - est remplacé par l'année avec le siècle en
	   nombre décimal&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%y</literal> - est remplacé par l'année sans le siècle en
	   nombre décimal (00-99)&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%Z</literal> - est remplacé par le nom du fuseau
	   horaire&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%z</literal> - est remplacé par le décalage du fuseau horaire
	   à partir d'UTC&nbsp;; un signe plus au début signifie à l'est d'UTC,
	   un signe moins signifie à l'ouest d'UTC&nbsp;; les heures et les
	   minutes suivent avec deux chiffres chacun et aucun délimiteur entre
	   eux (format habituel pour les en-têtes de date au standard
	   RFC 822)&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%+</literal> - est remplacé par la représentation nationale
	   de la date et l'heure&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%-*</literal> - extension GNU libc. N'ajoute aucune espace
	   de remplissage lors du traitement des sorties numériques&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   $_* - extension GNU libc. Indique explicitement l'espace comme
	   caractère de remplissage&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%0*</literal> - extension GNU libc. Indique explicitement
	   zéro comme caractère de remplissage&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>%%</literal> - est remplacé par <literal>%</literal>.
          </para>
         </listitem>
        </itemizedlist>
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPEStimestampsub">
      <term><function>PGTYPEStimestamp_sub</function></term>
      <listitem>
       <para>
	soustrait une valeur de type timestamp à une autre valeur et sauvegarde
	le résultat dans une variable de type interval.
<synopsis>
int PGTYPEStimestamp_sub(timestamp *ts1, timestamp *ts2, interval *iv);
</synopsis>
	La fonction soustrait la variable timestamp pointée par
	<literal>ts2</literal> de la variable timestamp pointée par
	<literal>ts1</literal> et stocke le résultat dans la variable de type interval
	pointée par <literal>iv</literal>.
       </para>
       <para>
	La fonction renvoie 0 en cas de succès et une valeur négative en cas
        d'erreur.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPEStimestampdefmtasc">
      <term><function>PGTYPEStimestamp_defmt_asc</function></term>
      <listitem>
       <para>
	analyse une valeur de type timestamp à partir de sa représentation
	textuelle à l'aide d'un masque de formatage.
<synopsis>
int PGTYPEStimestamp_defmt_asc(char *str, char *fmt, timestamp *d);
</synopsis>
	La fonction reçoit la représentation textuelle d'une valeur de type
	timestamp dans la variable <literal>str</literal> ainsi que le masque
	de formatage à utiliser dans la variable <literal>fmt</literal>. Le
	résultat est stocké dans la variable pointée par <literal>d</literal>.
       </para>
       <para>
	Si le masque de formatage <literal>fmt</literal> est NULL, la fonction
	utilise la masque de formatage par défaut qui est <literal>%Y-%m-%d
	%H:%M:%S</literal>.
       </para>
       <para>
	C'est la fonction inverse de <xref linkend="PGTYPEStimestampfmtasc"/>.
	Voir la documentation pour découvrir les saisies possibles pour le masque
	de formatage.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPEStimestampaddinterval">
      <term><function>PGTYPEStimestamp_add_interval</function></term>
      <listitem>
       <para>
        ajoute une variable de type interval à une variable de type timestamp.
<synopsis>
int PGTYPEStimestamp_add_interval(timestamp *tin, interval *span, timestamp *tout);
</synopsis>
	La fonction recçoit un pointeur vers une variable de type timestamp,
	<literal>tin</literal>, et un pointeur vers une variable de type interval
	<literal>span</literal>. Elle ajoute l'interval au timestamp et sauvegarde
	le résultat, de type timestamp, dans la variable pointée par
	<literal>tout</literal>.
       </para>
       <para>
	La fonction renvoie 0 en cas de succès et une valeur négative en cas
        d'erreur.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPEStimestampsubinterval">
      <term><function>PGTYPEStimestamp_sub_interval</function></term>
      <listitem>
       <para>
        soustrait une variable de type interval à une variable de type
	timestamp.
<synopsis>
int PGTYPEStimestamp_sub_interval(timestamp *tin, interval *span, timestamp *tout);
</synopsis>
	La fonction soustrait la variable de type interval pointée par
	<literal>span</literal> à la variable timestamp pointée par
	<literal>tin</literal> et sauvegarde le résultat dans une variable
	pointée par <literal>tout</literal>.
       </para>
       <para>
	La fonction renvoie 0 en cas de succès et une valeur négative en cas
        d'erreur.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </sect2>

  <sect2>
   <title>Type interval</title>
   <para>
    Le type interval en C permet aux programmes de gérer des données du type
    SQL interval.
    Voir <xref linkend="datatype-datetime"/> pour le type équivalent dans le
    serveur <productname>PostgreSQL</productname>.
   </para>
   <para>
    Les fonctions qui suivent peuvent être utilisées pour travailler avec le type interval&nbsp;:
    <variablelist>

     <varlistentry id="PGTYPESintervalnew">
      <term><function>PGTYPESinterval_new</function></term>
      <listitem>
       <para>
        renvoie un pointeur vers une variable interval nouvellement allouée.
<synopsis>
interval *PGTYPESinterval_new(void);
</synopsis>
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPESintervalfree">
      <term><function>PGTYPESinterval_free</function></term>
      <listitem>
       <para>
        libère la mémoire d'une variable interval précédemment allouée.
<synopsis>
void PGTYPESinterval_new(interval *intvl);
</synopsis>
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPESintervalfromasc">
      <term><function>PGTYPESinterval_from_asc</function></term>
      <listitem>
       <para>
        analyse une variable de type interval à partir de sa représentation textuelle.
<synopsis>
interval *PGTYPESinterval_from_asc(char *str, char **endptr);
</synopsis>
	La fonction analyse la chaîne <literal>str</literal> en entrée et renvoie
	un pointeur vers une variable allouée de type interval. Actuellement,
	ecpg analyse toujours la chaîne complète et ne supporte donc pas le
	stockage de l'adresse du premier caractère invalide dans
	<literal>*endptr</literal>. 
	<literal>endptr</literal> peut ainsi être initialisé à NULL en toute sécurité.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPESintervaltoasc">
      <term><function>PGTYPESinterval_to_asc</function></term>
      <listitem>
       <para>
        convertit une variable de type interval en sa représentation textuelle.
<synopsis>
char *PGTYPESinterval_to_asc(interval *span);
</synopsis>
	La fonction convertit la variable de type interval pointée par
	<literal>span</literal> en une chaîne C de type char*. Son
	contenu ressemble à&nbsp;:
	<literal>@ 1 day 12 hours 59 mins 10 secs</literal>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="PGTYPESintervalcopy">
      <term><function>PGTYPESinterval_copy</function></term>
      <listitem>
       <para>
        copie une variable de type interval.
<synopsis>
int PGTYPESinterval_copy(interval *intvlsrc, interval *intvldest);
</synopsis>
	La fonction copie la variable de type interval pointée par
	<literal>intvlsrc</literal> dans la variable pointée par
	<literal>intvldest</literal>. La
	mémoire de la variable de destination doit être allouée avant
	d'appeler la fonction.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </sect2>

  <sect2>
   <title>Type decimal</title>
   <para>
     Le type decimal est similaire au type numeric. Néanmoins, il est limité
     à une précision maximale de 30 chiffres significatifs. Contrairement au
     type numeric qui ne peut être créé que sur la partie
     <foreignphrase>heap</foreignphrase> de la mémoire, le type decimal peut
     être créé soit sur la pile soit sur le <foreignphrase>heap</foreignphrase>
     (au moyen des fonctions PGTYPESdecimal_new() et PGTYPESdecimal_free()).
     Il existe d'autres fonctions qui gèrent le type decimal dans le mode
     de compatibilité <productname>Informix</productname> décrit dans
     <xref linkend="ecpg-informix-compat"/>.
   </para>
   <para>
    Les fonctions qui suivent sont utilisées pour travailler avec le type decimal
    et ne sont pas uniquement contenues dans la bibliothèque
    <literal>libcompat</literal>.
    <variablelist>
     <varlistentry>
      <term><function>PGTYPESdecimal_new</function></term>
      <listitem>
       <para>
        réclame un pointeur vers une variable de type decimal nouvellement allouée.
<synopsis>
decimal *PGTYPESdecimal_new(void);
</synopsis>
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>PGTYPESdecimal_free</function></term>
      <listitem>
       <para>
       libère toute la mémoire d'un type decimal.
<synopsis>
void PGTYPESdecimal_free(decimal *var);
</synopsis>
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </sect2>
 
   <sect2>
    <title>Valeurs errno de pgtypeslib</title>
   <para>
    <variablelist>
     <varlistentry>
      <term><literal>PGTYPES_NUM_BAD_NUMERIC</literal></term>
      <listitem>
       <para>
	Un argument doit contenir une variable de type numeric (ou pointer
	sur une variable numeric) mais, en fait, sa représentation en mémoire
	est invalide.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>PGTYPES_NUM_OVERFLOW</literal></term>
      <listitem>
       <para>
	Un dépassement (<foreignphrase>overflow</foreignphrase>) est survenu.
	Comme le type numeric peut gérer une
	précision quasiment arbitraire, transtyper une variable de type numeric
	peut causer un dépassement.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>PGTYPES_NUM_OVERFLOW</literal></term>
      <listitem>
       <para>
	Un soupassement (<foreignphrase>underflow</foreignphrase>, erreur de traitement
	survenant quand la valeur absolue d'une quantité calculée est plus petite
	que les limites de précision) est survenu. Comme le type numeric peut gérer une
	précision quasiment arbitraire, transtyper une variable de type numeric
	peut causer un soupassement.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>PGTYPES_NUM_DIVIDE_ZERO</literal></term>
      <listitem>
       <para>
        Tentative de division par zéro.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>PGTYPES_DATE_BAD_DATE</literal></term>
      <listitem>
       <para>
        
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>PGTYPES_DATE_ERR_EARGS</literal></term>
      <listitem>
       <para>
        
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>PGTYPES_DATE_ERR_ENOSHORTDATE</literal></term>
      <listitem>
       <para>
        
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>PGTYPES_INTVL_BAD_INTERVAL</literal></term>
      <listitem>
       <para>
        
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>PGTYPES_DATE_ERR_ENOTDMY</literal></term>
      <listitem>
       <para>
        
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>PGTYPES_DATE_BAD_DAY</literal></term>
      <listitem>
       <para>
        
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>PGTYPES_DATE_BAD_MONTH</literal></term>
      <listitem>
       <para>
        
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>PGTYPES_TS_BAD_TIMESTAMP</literal></term>
      <listitem>
       <para>
        
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </sect2>

   <sect2>
    <title>Constantes spéciales de pgtypeslib</title>
   <para>
    <variablelist>
     <varlistentry id="PGTYPESInvalidTimestamp">
      <term><literal>PGTYPESInvalidTimestamp</literal></term>
      <listitem>
       <para>
	Une valeur de type timestamp qui représente un timestamp invalide. Ce
	code est renvoyé par la fonction <function>PGTYPEStimestamp_from_asc</function>
	en cas d'erreur lors de l'analyse. Du fait de la représentation
	interne du type de données timestamp,
	<literal>PGTYPESInvalidTimestamp</literal> est aussi en même temps un
	timestamp valide. Il est configuré à <literal>1899-12-31 23:59:59</literal>.
	Pour détecter les erreurs, il est impératif de s'assurer que l'application ne teste
	pas seulement <literal>PGTYPESInvalidTimestamp</literal> mais aussi
	<literal>errno != 0</literal> après chaque appel à
	<function>PGTYPEStimestamp_from_asc</function>.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </sect2>
 </sect1>

 <sect1 id="ecpg-informix-compat">
  <title>Mode de compatibilité <productname>Informix</productname></title>
  <para>
   ecpg peut fonctionner en <firstterm>mode compatible avec Informix</firstterm>.
   Dans ce mode, ecpg tente de se comporter comme le précompilateur
   <productname>Informix</productname> pour <productname>Informix</productname>
   E/SQL. Dans les grandes lignes, cela permet d'utiliser le signe dollar à la
   place de la primitive <literal>EXEC SQL</literal> pour introduire des
   commandes SQL embarquées&nbsp;:
<programlisting>   $int j = 3;
   $CONNECT TO :dbname;
   $CREATE TABLE test(i INT PRIMARY KEY, j INT);
   $INSERT INTO test(i, j) VALUES (7, :j);
   $COMMIT;
</programlisting>
  </para>
  <para>
   Il existe deux modes de compatibilité&nbsp;: INFORMIX et INFORMIX_SE.
  </para>
  <para>
   Lors de l'édition de liens pour des programmes qui utilisent ce mode de compatibilité,
   il est nécessaire de lier les programmes avec <literal>libcompat</literal>,
   fournie avec ecpg.
  </para>
  <para>
   En dehors de la syntaxe expliquée précédemment, le mode de compatibilité
   <productname>Informix</productname> ajoute à ecpg quelques fonctions pour la
   saisie, la sortie et la transformation de données ainsi que des instructions
   SQL embarquées connues d'E/SQL.
  </para>
  <para>
   Le mode de compatibilité <productname>Informix</productname> est très
   fortement connecté à la bibliothèque pgtypeslib d'ecpg. pgtypeslib fait
   correspondre les types de données SQL aux types de données internes du
   programme C hôte&nbsp;; la plupart des
   fonctions supplémentaires du mode de compatibilité
   <productname>Informix</productname> permettent d'opérer sur ces types.
   L'étendue de la compatibilité est toutefois limitée. L'idée n'est pas de
   mimer le comportement d'<productname>Informix</productname>&nbsp;;
   cela permet de réaliser plus ou moins les mêmes opérations et fournit
   des fonctions de même nom et de même comportement de base, mais il n'est
   pas question de replacer au pied levé une utilisation
   d'<productname>Informix</productname>. De plus, certains types
   de données sont différents. Ainsi, les types datetime et interval de
   <productname>PostgreSQL</productname> ne gèrent pas les échelles telles que 
   <literal>YEAR TO MINUTE</literal>, par exemple&nbsp;; ecpg ne les supportent donc
   pas non plus.
  </para>

  <sect2>
   <title>Instructions supplémentaires du SQL embarqué</title>
   <para>
    <variablelist>
     <varlistentry>
      <term><literal>CLOSE DATABASE</literal></term>
      <listitem>
       <para>
	ferme la connexion en cours. En fait, il s'agit d'un
	synonyme de la commande ecpg <literal>DISCONNECT CURRENT</literal>&nbsp;:
<programlisting>
    $CLOSE DATABASE;                /* ferme la connexion actuelle */
    EXEC SQL CLOSE DATABASE;
</programlisting>
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </sect2>

  <sect2>
   <title>Fonctions supplémentaires</title>
   <para>
    <variablelist>
     <varlistentry>
      <term><function>decadd</function></term>
      <listitem>
       <para>
        additionne deux valeurs de type decimal.
<synopsis>
int decadd(decimal *arg1, decimal *arg2, decimal *sum);
</synopsis>
<!-- SAS : un opérande -->
	La fonction reçoit un pointeur vers le premier opérande de type decimal
	(<literal>arg1</literal>), un pointeur vers le second opérande de type
	decimal (<literal>arg2</literal>) et un pointeur vers une valeur de type
	decimal destinée à contenir la somme (<literal>sum</literal>). En cas de
	succès, la fonction renvoie 0. ECPG_INFORMIX_NUM_OVERFLOW est renvoyé
	dans le cas d'un dépassement de tampon, et ECPG_INFORMIX_NUM_UNDERFLOW
	dans le cas d'un soupassement. -1 est renvoyé
	s'il s'agit d'une autre erreur et errno est configuré avec le numéro
	errno respectif dans pgtypeslib.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>deccmp</function></term>
      <listitem>
       <para>
        compare deux variables de type decimal.
<synopsis>
int deccmp(decimal *arg1, decimal *arg2);
</synopsis>
	La fonction reçoit un pointeur vers la première valeur de type decimal
	(<literal>arg1</literal>), un pointeur vers la seconde
	(<literal>arg2</literal>) et renvoie un entier qui indique la
	plus grande valeur.
        <itemizedlist>
         <listitem>
          <para>
	   1, si la valeur pointée par <literal>arg1</literal> est plus
	   grande que la valeur pointée par <literal>var2</literal>&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   -1, si la valeur pointée par <literal>arg1</literal> est plus
	   petite que la valeur pointée par
	   <literal>arg2</literal></para>
         </listitem>
         <listitem>
          <para>
	   0, si les valeurs pointées par <literal>arg1</literal>
	   et <literal>arg2</literal> sont identiques.
          </para>
         </listitem>
        </itemizedlist>
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>deccopy</function></term>
      <listitem>
       <para>
        copie une valeur de type decimal.
<synopsis>
void deccopy(decimal *src, decimal *target);
</synopsis>
	La fonction prend en premier argument un pointeur vers la valeur de type
	decimal à copier (<literal>src</literal>) et un pointeur vers la
	structure cible de type decimal (<literal>target</literal>) comme second
	argument.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>deccvasc</function></term>
      <listitem>
       <para>
        convertit une valeur de sa représentation ASCII en valeur de type
	decimal.
<synopsis>
int deccvasc(char *cp, int len, decimal *np);
</synopsis>
	La fonction reçoit un pointeur vers la chaîne contenant le
	représentation textuelle du nombre à convertir (<literal>cp</literal>)
	ainsi que sa longueur <literal>len</literal>. <literal>np</literal> est
	un pointeur vers la valeur de type decimal qui sauvegarde le résultat
	de l'opération.
       </para>
       <para>
	Quelques formats valides&nbsp;:
         <literal>-2</literal>,
         <literal>.794</literal>,
         <literal>+3.44</literal>,
         <literal>592.49E07</literal> ou
         <literal>-32.84e-4</literal>.
       </para>
       <para>
	La fonction renvoie 0 en cas de succès. Si un
	dépassement ou un soupassement survient,
	<literal>ECPG_INFORMIX_NUM_OVERFLOW</literal> ou
	<literal>ECPG_INFORMIX_NUM_UNDERFLOW</literal>, respectivement, est renvoyé. Si la
	représentation ASCII ne peut être analysée,
	<literal>ECPG_INFORMIX_BAD_NUMERIC</literal> est renvoyé (ou
	<literal>ECPG_INFORMIX_BAD_EXPONENT</literal> si le problème survient
	lors de l'analyse de l'exposant).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>deccvdbl</function></term>
      <listitem>
       <para>
        convertit une valeur de type double en une valeur de type decimal.
<synopsis>
int deccvdbl(double dbl, decimal *np);
</synopsis>
	La fonction prend la variable de type double à convertir
	en premier argument (<literal>dbl</literal>) et comme second argument
	(<literal>np</literal>) un pointeur vers la
	variable décimale amenée à contenir le résultat de l'opération.
       </para>
       <para>
	La fonction renvoie 0 en cas de succès et une valeur négative en cas
        d'erreur.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>deccvint</function></term>
      <listitem>
       <para>
        convertit une valeur de type int en une valeur de type decimal.
<synopsis>
int deccvint(int in, decimal *np);
</synopsis>
	La fonction prend la variable de type int à convertir comme premier argument
	(<literal>in</literal>) et comme second argument
	(<literal>np</literal>) un pointeur vers la variable
	de type decimal aménée à contenir le résultat de l'opération.
       </para>
       <para>
	La fonction renvoie 0 en cas de succès et une valeur négative en cas
        d'erreur.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
	     <term><function>deccvlong</function></term>
      <listitem>
       <para>
        convertit une valeur de type long en une valeur de type decimal.
<synopsis>
int deccvlong(long lng, decimal *np);
</synopsis>
	La fonction prend la variable de type long à convertir comme premier
	argument (<literal>lng</literal>) et comme second argument
	(<literal>np</literal>) un pointeur vers la variable
	de type decimal amenée à contenir le résultat de l'opération.
       </para>
       <para>
	La fonction renvoie 0 en cas de succès et une valeur négative en cas
        d'erreur.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>decdiv</function></term>
      <listitem>
       <para>
        effectue la division entre deux variables de type decimal.
<synopsis>
int decdiv(decimal *n1, decimal *n2, decimal *result);
</synopsis>
	La fonction reçoit des pointeurs vers les variables représentant le
	premier opérande (<literal>n1</literal>) et le second
	(<literal>n2</literal>) et calcule
	<literal>n1</literal>/<literal>n2</literal>. Le résultat
	(<literal>result</literal>) est un pointeur vers la variable amenée à
	contenir le résultat de l'opération.
       </para>
       <para>
	La fonction renvoie 0 en cas de succès et une valeur négative en cas
        d'erreur. Si un dépassement ou un soupassement survient,
	<literal>ECPG_INFORMIX_NUM_OVERFLOW</literal> ou
	<literal>ECPG_INFORMIX_NUM_UNDERFLOW</literal>, respectivement, est
	renvoyé. En cas de tentative de division par zéro, la fonction renvoie
	<literal>ECPG_INFORMIX_DIVIDE_ZERO</literal>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>decmul</function></term>
      <listitem>
       <para>
        effectue la multiplication de deux valeurs décimales.
<synopsis>
int decmul(decimal *n1, decimal *n2, decimal *result);
</synopsis>
	La fonction reçoit des pointeurs vers les variables représentant le
	premier opérande (<literal>n1</literal>) et le second
	(<literal>n2</literal>) et calcule
	<literal>n1</literal>/<literal>n2</literal>. Le résultat
	(<literal>result</literal>) est un pointeur vers la variable amenée à
	contenir le résultat de l'opération.
       </para>
       <para>
	La fonction renvoie 0 en cas de succès et une valeur négative en cas
        d'erreur. Si un dépassement ou un soupassement survient,
	<literal>ECPG_INFORMIX_NUM_OVERFLOW</literal> ou
	<literal>ECPG_INFORMIX_NUM_UNDERFLOW</literal>, respectivement, est renvoyé.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>decsub</function></term>
      <listitem>
       <para>
        soustrait une valeur de type decimal à une autre.
<synopsis>
int decsub(decimal *n1, decimal *n2, decimal *result);
</synopsis>
	La fonction reçoit des pointeurs vers les variables représentant le
	premier opérande (<literal>n1</literal>) et le second
	(<literal>n2</literal>) et calcule
	<literal>n1</literal>-<literal>n2</literal>. Le résultat
	(<literal>result</literal>) est un pointeur vers la variable amenée à 
	contenir le résultat de l'opération.
       </para>
       <para>
	La fonction renvoie 0 en cas de succès et une valeur négative en cas
        d'erreur. Si un dépassement ou soupassement survient,
	<literal>ECPG_INFORMIX_NUM_OVERFLOW</literal> ou
	<literal>ECPG_INFORMIX_NUM_UNDERFLOW</literal>, respectivment, est renvoyé.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>dectoasc</function></term>
      <listitem>
       <para>
	convertit une variable de type decimal en sa représentation ASCII dans
	une chaîne C char*.
<synopsis>
int dectoasc(decimal *np, char *cp, int len, int right)
</synopsis>
	La fonction reçoit un pointeur vers une variable de type decimal
	(<literal>np</literal>) qu'elle convertit dans sa représentation textuelle.
	<literal>cp</literal> est le tampon de stockage du résultat de
	l'opération. Le paramètre <literal>right</literal> indique le nombre
	de chiffres à inclure à droite du point décimal dans le résultat.
	Le résultat est arrondi à ce nombre de chiffres décimaux. Configurer
	<literal>right</literal> à -1 indique que tous les chiffres décimaux
	disponibles doivent être inclus dans la sortie. Si la longueur du tampon
	de sortie, indiquée par <literal>len</literal>, n'est pas suffisante pour
	contenir la représentation textuelle, seul le caractère
	<literal>*</literal> est stocké dans le résultat et -1 est renvoyé.
       </para>
       <para>
	Cette fonction renvoie -1 si le tampon <literal>cp</literal> est trop
	petit ou <literal>ECPG_INFORMIX_OUT_OF_MEMORY</literal> si la mémoire
	disponible est épuisée.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>dectodbl</function></term>
      <listitem>
       <para>
        convertit une variable de type decimal en double.
<synopsis>
int dectodbl(decimal *np, double *dblp);
</synopsis>
	La fonction reçoit un pointeur vers la valeur du type decimal à
	convertir (<literal>np</literal>) et un pointeur vers la variable de
	type double de stockage du résultat de l'opération
	(<literal>dblp</literal>).
       </para>
       <para>
	La fonction renvoie 0 en cas de succès et une valeur négative en cas
        d'erreur.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>dectoint</function></term>
      <listitem>
       <para>
        convertit une variable de type decimal en integer.
<synopsis>
int dectoint(decimal *np, int *ip);
</synopsis>
	La fonction reçoit un pointeur vers la valeur du type decimal à
	convertir (<literal>np</literal>) et un pointeur vers la variable de
	type integer de stockage du résultat de l'opération
	(<literal>ip</literal>).
       </para>
       <para>
	La fonction renvoie 0 en cas de succès et une valeur négative en cas
        d'erreur. Si un dépassement survient, <literal>ECPG_INFORMIX_NUM_OVERFLOW</literal>
	est renvoyé.
       </para>
       <para>
	L'implantation d'ecpg diffère de celle
	d'<productname>Informix</productname>. <productname>Informix</productname>
	limite un entier à la plage -32767&nbsp;..&nbsp;32767 alors que les limites
	de l'implantation d'ecpg dépendent de l'architecture
	(<literal>-INT_MAX .. INT_MAX</literal>).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>dectolong</function></term>
      <listitem>
       <para>
        convertit une variable de type decimal en long integer.
<synopsis>
int dectolong(decimal *np, long *lngp);
</synopsis>
	Cette fonction reçoit un pointeur vers la valeur du type decimal à
	convertir (<literal>np</literal>) et un pointeur vers la variable de
	type long de stockage du résultat de l'opération
	(<literal>lngp</literal>).
       </para>
       <para>
	La fonction renvoie 0 en cas de succès et une valeur négative en cas
        d'erreur. Si un dépassement survient, <literal>ECPG_INFORMIX_NUM_OVERFLOW</literal>
	est renvoyé.
       </para>
       <para>
	L'implantation d'ecpg diffère de celle
	d'<productname>Informix</productname>. <productname>Informix</productname>
	limite un entier long à la plage -2.147.483.647&nbsp;..&nbsp;2.147.483.647
	alors que les limites de l'implantation d'ecpg dépendent de
	l'architecture (<literal>-LONG_MAX .. LONG_MAX</literal>).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>rdatestr</function></term>
      <listitem>
       <para>
        convertit une date en une chaîne C de type char*.
<synopsis>
int rdatestr(date d, char *str);
</synopsis>
	La fonction prend deux arguments. Le premier est la date à convertir
	(<literal>d</literal>) et le second est un pointeur vers la chaîne cible.
	Le format de sortie est toujours <literal>yyyy-mm-dd</literal>. Il est donc
	nécessaire d'allouer au minimum 11 octets (ce qui inclut le
	terminateur NUL) pour la chaîne.
       </para>
       <para>
	La fonction renvoie 0 en cas de succès et une valeur négative en cas
        d'erreur.
       </para>
       <para>
	L'implantation d'ecpg diffère de celle
	d'<productname>Informix</productname>. Dans <productname>Informix</productname>,
	le format peut être modifié en configurant les variables
	d'environnement. EN revanche, avec ecpg, le format de sortie ne peut pas
	être modifié.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>rstrdate</function></term>
      <listitem>
       <para>
        analyse la représentation textuelle d'une date.
<synopsis>
int rstrdate(char *str, date *d);
</synopsis>
	La fonction reçoit la représentation textuelle de la date à convertir
	(<literal>str</literal>) et un pointeur vers une variable de type date
	(<literal>d</literal>). Cette fonction ne permet pas de préciser
	un masque de formatage. Elle utilise le masque de formatage
	d'<productname>Informix</productname>, <literal>mm/dd/yyyy</literal>.
	En interne, cette fonction est implantée via <function>rdefmtdate</function>.
	Du coup, <function>rstrdate</function> n'est pas plus rapide et si
	c'est possible, il est préférable d'opter pour
	<function>rdefmtdate</function> qui permet d'expliciter le masque de formatage.
       </para>
       <para>
        Cette fonction renvoie les mêmes valeurs que <function>rdefmtdate</function>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>rtoday</function></term>
      <listitem>
       <para>
        récupère la date courante.
<synopsis>
void rtoday(date *d);
</synopsis>
	La fonction reçoit un pointeur vers une variable de type date
	(<literal>d</literal>) qu'elle positionne à la date courante.
       </para>
       <para>
	En interne, cette fonction utilise la fonction
	<xref linkend="PGTYPESdatetoday"/>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>rjulmdy</function></term>
      <listitem>
       <para>
	extrait les valeurs du jour, du mois et de l'année à partir d'une
	variable de type date.
<synopsis>
int rjulmdy(date d, short mdy[3]);
</synopsis>
	La fonction reçoit la date <literal>d</literal> et un pointeur vers
	un tableau de trois valeurs de type short integer, <literal>mdy</literal>.
	Le nom de la variable indique l'ordre séquentiel&nbsp;:
	<literal>mdy[0]</literal> contient le numéro du mois,
	<literal>mdy[1]</literal> contient le numéro du jour et
	<literal>mdy[2]</literal> contient l'année.
       </para>
       <para>
        Cette fonction renvoie toujours 0 actuellement.
       </para>
       <para>
	En interne, cette fonction utilise la fonction <xref
	linkend="PGTYPESdatejulmdy"/>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>rdefmtdate</function></term>
      <listitem>
       <para>
	utilise un masque de formatage pour convertir une chaîne de caractères
	en une valeur de type date.
<synopsis>
int rdefmtdate(date *d, char *fmt, char *str);
</synopsis>
	La fonction reçoit un pointeur vers la valeur de type date de stockage
	du résultat de l'opération (<literal>d</literal>), le masque de
	formatage à utiliser pour analyser la date (<literal>fmt</literal>) et
	la chaîne C char* contenant la représentation textuelle de la date
	(<literal>str</literal>). La représentation textuelle doit correspondre
	au masque de formatage. Il n'est toutefois pas nécessaire d'avoir
	une correspondance caractère par caractère entre la chaîne et le masque
	de formatage. La fonction n'analyse que l'ordre séquentiel et
	recherche les constantes <literal>yy</literal> ou
	<literal>yyyy</literal> pour la position de l'année,
	<literal>mm</literal> pour la position du mois et
	<literal>dd</literal> pour la position du jour.
       </para>
       <para>
        La fonction renvoie les valeurs suivantes&nbsp;:
        <itemizedlist>
         <listitem>
          <para>
           0 - la fonction a terminé avec succès&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>ECPG_INFORMIX_ENOSHORTDATE</literal> - la date ne contient
	   pas de délimiteur entre le jour, le mois et l'année. Dans ce cas,
	   la taille de la chaîne en entrée doit être de six ou huit
	   octets exactement mais elle ne l'est pas&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>ECPG_INFORMIX_ENOTDMY</literal> - la chaîne de formatage
	   n'indique pas correctement l'ordre séquentiel de l'année, du mois et
	   du jour&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>ECPG_INFORMIX_BAD_DAY</literal> - la chaîne en entrée ne
	   contient pas de jour valide&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>ECPG_INFORMIX_BAD_MONTH</literal> - la chaîne en entrée ne
	   contient pas de mois valide&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>ECPG_INFORMIX_BAD_YEAR</literal> - la chaîne en entrée ne
	   contient pas d'année valide.
          </para>
         </listitem>
	</itemizedlist>
       </para>
       <para>
	En interne, cette fonction est codée pour utiliser la fonction
	<xref linkend="PGTYPESdatedefmtasc"/>. La référence présente un
	tableau d'exemples de saisie.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>rfmtdate</function></term>
      <listitem>
       <para>
	convertit une variable de type date en sa représentation textuelle en
	utilisant un masque de formatage.
<synopsis>
int rfmtdate(date d, char *fmt, char *str);
</synopsis>
	La fonction reçoit la date à convertir (<literal>d</literal>), le
	masque de formatage (<literal>fmt</literal>) et la chaîne de stockage
	de la représentation textuelle de la date (<literal>str</literal>).
       </para>
       <para>
        La fonction renvoie 0 en cas de succès et une valeur négative en cas
        d'erreur.
       </para>
       <para>
	En interne, cette fonction utilise la fonction <xref
	linkend="PGTYPESdatefmtasc"/>. La référence présente divers exemples.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>rmdyjul</function></term>
      <listitem>
       <para>
	crée une valeur de type date à partir d'un tableau de trois entiers
	indiquant le jour, le mois et l'année de la date.
<synopsis>
int rmdyjul(short mdy[3], date *d);
</synopsis>
	La fonction reçoit le tableau de trois entiers courts
	(<literal>mdy</literal>) et un pointeur vers une variable de type date
	pour stocker le résultat de l'opération.
       </para>
       <para>
        Actuellement, la fonction renvoie toujours 0.
       </para>
       <para>
	En interne, cette fonction utilise la fonction <xref
	linkend="PGTYPESdatemdyjul"/>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>rdayofweek</function></term>
      <listitem>
       <para>
        renvoie un numéro représentant le jour de la semaine pour une valeur de
	type date.
<synopsis>
int rdayofweek(date d);
</synopsis>
	La fonction prend comme seul argument la variable de type date
	<literal>d</literal> et renvoie un entier qui indique le jour de la semaine
	pour cette date.
        <itemizedlist>
         <listitem>
          <para>
	   0 - Dimanche
          </para>
         </listitem>
         <listitem>
          <para>
	   1 - Lundi
          </para>
         </listitem>
         <listitem>
          <para>
	   2 - Mardi
          </para>
         </listitem>
         <listitem>
          <para>
	   3 - Mercredi
          </para>
         </listitem>
         <listitem>
          <para>
	   4 - Jeudi
          </para>
         </listitem>
         <listitem>
          <para>
	   5 - Vendredi
          </para>
         </listitem>
         <listitem>
          <para>
	   6 - Samedi
          </para>
         </listitem>
        </itemizedlist>
       </para>
       <para>
	En interne, cette fonction utilise la fonction <xref
	linkend="PGTYPESdatedayofweek"/>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>dtcurrent</function></term>
      <listitem>
       <para>
        récupère le timestamp courant.
<synopsis>
void dtcurrent(timestamp *ts);
</synopsis>
	La fonction récupère la valeur du timestamp courant et la sauvegarde
	dans la variable de type timestamp pointée par <literal>ts</literal>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>dtcvasc</function></term>
      <listitem>
       <para>
	analyse une variable de type timestamp à partir d'une représentation
	textuelle en un standard ANSI pour en faire une variable de type timestamp.
<synopsis>
int dtcvasc(char *str, timestamp *ts);
</synopsis>
	La fonction reçoit la chaîne à analyser (<literal>str</literal>) et
	un pointeur vers la variable de type timestamp pour stocker le
	résultat de l'opération (<literal>ts</literal>).
       </para>
       <para>
	La fonction renvoie 0 en cas de succès et une valeur négative en cas
        d'erreur.
       </para>
       <para>
	En interne, cette fonction utilise la fonction <xref
	linkend="PGTYPEStimestampfromasc"/>. Cette référence présente un
	tableau d'exemples de saisie.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>dtcvfmtasc</function></term>
      <listitem>
       <para>
	analyse une variable de type timestamp à partir de sa représentation
	textuelle dans le standard ANSI en utilisant un masque de formatage
	pour en faire une variable de type timestamp.
<synopsis>
dtcvfmtasc(char *inbuf, char *fmtstr, timestamp *dtvalue)
</synopsis>
	La fonction reçoit la chaîne à analyser (<literal>inbuf</literal>),
	le masque de formatage à utiliser (<literal>fmtstr</literal>) et un
	pointeur vers une variable de type timestamp pour stocker
	le résultat de l'opération (<literal>ts</literal>).
       </para>
       <para>
	Cette fonction utilise la fonction <xref
	linkend="PGTYPEStimestampdefmtasc"/>. Voir la documentation
	pour une liste des spécificateurs de format utilisables.
       </para>
       <para>
	La fonction renvoie 0 en cas de succès et une valeur négative en cas
        d'erreur.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>dtsub</function></term>
      <listitem>
       <para>
	soustrait une variable de type timestamp à une autre et renvoie
	une variable de type interval.
<synopsis>
int dtsub(timestamp *ts1, timestamp *ts2, interval *iv);
</synopsis>
	La fonction soustrait la variable timestamp pointée par
	<literal>ts2</literal> à la variable timestamp pointée par
	<literal>ts1</literal> et stocke le résultat dans la variable
	interval pointée par <literal>iv</literal>.
       </para>
       <para>
	La fonction renvoie 0 en cas de succès et une valeur négative en cas
        d'erreur.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>dttoasc</function></term>
      <listitem>
       <para>
        convertit une variable de type timestamp en une chaîne C de type char*.
<synopsis>
int dttoasc(timestamp *ts, char *output);
</synopsis>
	La fonction reçoit un pointeur vers la variable de type timestamp
	à convertir (<literal>ts</literal>) et la chaîne de stockage du
	résultat de l'opération, <literal>output</literal>. Elle convertit
	<literal>ts</literal> en sa représentation textuelle dans le standard
	SQL ANSI, définie comme <literal>YYYY-MM-DD HH:MM:SS</literal>.
       </para>
       <para>
	La fonction renvoie 0 en cas de succès et une valeur négative en cas
        d'erreur.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>dttofmtasc</function></term>
      <listitem>
       <para>
        convertit une variable de type timestamp en une chaîne C de type char*
	en utilisant un masque de formatage.
<synopsis>
int dttofmtasc(timestamp *ts, char *output, int str_len, char *fmtstr);
</synopsis>
	La fonction reçoit un pointeur vers la variable de type timestamp
	à convertir (<literal>ts</literal>) et la chaîne de stockage du
	résultat de l'opération, <literal>output</literal>, la longueur
	maximale allouée au tampon de sortie
	(<literal>str_len</literal>) et le masque de formatage à utiliser pour
	la conversion (<literal>fmtstr</literal>).
       </para>
       <para>
	La fonction renvoie 0 en cas de succès et une valeur négative en cas
        d'erreur.
       </para>
       <para>
	En interne, cette fonction utilise la fonction <xref
	linkend="PGTYPEStimestampfmtasc"/>. Cette référence fournit les
	informations concernant les spécificateurs de format de masque
	utilisables.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>intoasc</function></term>
      <listitem>
       <para>
        convertit une variable de type timestamp en une chaîne C de type char*.
<synopsis>
int intoasc(interval *i, char *str);
</synopsis>
	La fonction reçoit un pointeur vers la variable de type timestamp
	à convertir (<literal>i</literal>) et la chaîne de stockage du
	résultat de l'opération, <literal>str</literal>. Elle convertit
	<literal>i</literal> en sa représentation textuelle dans le standard
	SQL ANSI, définie comme <literal>YYYY-MM-DD HH:MM:SS</literal>.
       </para>
       <para>
	La fonction renvoie 0 en cas de succès et une valeur négative en cas
        d'erreur.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>rfmtlong</function></term>
      <listitem>
       <para>
	convertit un entier long en sa représentation textuelle en utilisant un
	masque de formatage.
<synopsis>
int rfmtlong(long lng_val, char *fmt, char *outbuf);
</synopsis>
	La fonction reçoit la valeur <literal>lng_val</literal> de type long,
	le masque de formatage <literal>fmt</literal> et un pointeur vers un
	tampon de sortie <literal>outbuf</literal>. Elle convertit la valeur de
	type long en sa représentation textuelle selon le masque de formatage.
       </para>
       <para>
	Le masque de formatage est composé de caractères de spécification de
	formats à prendre parmi&nbsp;:
        <itemizedlist>
         <listitem>
          <para>
	   <literal>*</literal> (astérisque) - remplace une position autrement
	   vide par une astérisque&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>&amp;</literal> (esperluette, perluette ou « et commercial
	   ») - remplace une position autrement vide par un zéro&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>#</literal> - remplace les zéros de début de chaîne
	   par des espaces&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>&lt;</literal> - justifie le nombre à gauche dans la
	   chaîne&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>,</literal> (virgule) - groupe les nombres de plus de quatre
	   chiffres en groupes de trois chiffres séparés par des
	   virgules&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>.</literal> (point) - sépare la partie décimale
	   de la partie entière&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>-</literal> (moins) - apparaît si le nombre est négatif&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>+</literal> (plus) - apparaît si le nombre est positif&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>(</literal> - remplace le signe moins devant le nombre
	   négatif. Le signe moins n'apparaît pas&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>)</literal> - remplace le signe moins et est affiché
	   derrière la valeur négative&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>$</literal> - représente le symbole monétaire.
          </para>
         </listitem>
	</itemizedlist>
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>rupshift</function></term>
      <listitem>
       <para>
        convertit une chaîne en majuscules.
<synopsis>
void rupshift(char *str);
</synopsis>
	La fonction reçoit un pointeur vers la chaîne et transforme chaque
	caractère minuscule en majuscule.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>byleng</function></term>
      <listitem>
       <para>
	renvoie le nombre de caractères dans une chaîne sans compter les espaces
	en fin de chaîne.
<synopsis>
int byleng(char *str, int len);
</synopsis>
	La fonction attend une chaîne de longueur fixe comme premier argument
	(<literal>str</literal>) et sa longueur comme deuxième argument
	(<literal>len</literal>). Elle renvoie le nombre de caractères
	significatifs, c'est-à-dire la longueur de la chaîne sans les espaces
	de fin de chaîne.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>ldchar</function></term>
      <listitem>
       <para>
        copie une chaîne de longueur fixe dans une chaîne terminée par NUL.
<synopsis>
void ldchar(char *src, int len, char *dest);
</synopsis>
	La fonction reçoit une chaîne de longueur fixe à copier
	(<literal>src</literal>), sa longueur (<literal>len</literal>) et un
	pointeur vers la chaîne de destination (<literal>dest</literal>).
	Il est nécessaire de réserver au moins <literal>len+1</literal>
	octets pour la chaîne vers laquelle <literal>dest</literal> pointe.
	La fonction copie au maximum <literal>len</literal> octets vers le nouvel
	emplacement (moins si la chaîne source contient des espaces en fin de
	chaîne) et ajoute le terminateur de chaîne NUL.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>rgetmsg</function></term>
      <listitem>
       <para>
<synopsis>
int rgetmsg(int msgnum, char *s, int maxsize);
</synopsis>
        Cette fonction existe mais elle n'est pas codée actuellement&nbsp;!
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>rtypalign</function></term>
      <listitem>
       <para>
<synopsis>
int rtypalign(int offset, int type);
</synopsis>
        Cette fonction existe mais elle n'est pas codée actuellement&nbsp;!
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>rtypmsize</function></term>
      <listitem>
       <para>
<synopsis>
int rtypmsize(int type, int len);
</synopsis>
        Cette fonction existe mais elle n'est pas codée actuellement&nbsp;!
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>rtypwidth</function></term>
      <listitem>
       <para>
<synopsis>
int rtypwidth(int sqltype, int sqllen);
</synopsis>
        Cette fonction existe mais elle n'est pas codée actuellement&nbsp;!
       </para>
      </listitem>
     </varlistentry>

     <varlistentry id="rsetnull">
      <term><function>rsetnull</function></term>
      <listitem>
       <para>
        initialise une variable à NULL.
<synopsis>
int rsetnull(int t, char *ptr);
</synopsis>
	La fonction reçoit un entier qui indique le type de la variable et
	un pointeur vers la variable elle-même qui est convertie en un pointeur
	de chaîne C, type char*.
       </para>
       <para>
        Les types suivants existent&nbsp;:
        <itemizedlist>
         <listitem>
          <para>
	   <literal>CCHARTYPE</literal> - pour une variable de type
	   <type>char</type> ou <type>char*</type>&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>CSHORTTYPE</literal> - pour une variable de type
	   <type>short int</type>&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>CINTTYPE</literal> - pour une variable de type
	   <type>int</type>&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>CBOOLTYPE</literal> - pour une variable de type
	   <type>boolean</type>&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>CFLOATTYPE</literal> - pour une variable de type
	   <type>float</type>&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>CLONGTYPE</literal> - pour une variable de type
	   <type>long</type>&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>CDOUBLETYPE</literal> - pour une variable de type
	   <type>double</type>&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>CDECIMALTYPE</literal> - pour une variable de type
	   <type>decimal</type>&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>CDATETYPE</literal> - pour une variable de type
	   <type>date</type>&nbsp;;
          </para>
         </listitem>
         <listitem>
          <para>
	   <literal>CDTIMETYPE</literal> - pour une variable de type
	   <type>timestamp</type>.
          </para>
         </listitem>
        </itemizedlist>
       </para>

       <para>
        Exemple d'appel de la fonction&nbsp;:
<programlisting><![CDATA[$char c[] = "abc       ";
$short s = 17;
$int i = -74874;

rsetnull(CCHARTYPE, (char *) c);
rsetnull(CSHORTTYPE, (char *) &s);
rsetnull(CINTTYPE, (char *) &i);
]]></programlisting>
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>risnull</function></term>
      <listitem>
       <para>
        teste si une variable est NULL.
<synopsis>
int risnull(int t, char *ptr);
</synopsis>
	La fonction reçoit le type de la variable à tester (<literal>t</literal>)
	ainsi qu'un pointeur vers cette variable (<literal>ptr</literal>).
	Ce dernier a besoin d'être converti en char*. Voir la fonction
	<xref linkend="rsetnull"/> pour une liste des types de variable possibles.
       </para>
       <para>
        Exemple d'utilisation de la fonction&nbsp;:
<programlisting><![CDATA[$char c[] = "abc       ";
$short s = 17;
$int i = -74874;

risnull(CCHARTYPE, (char *) c);
risnull(CSHORTTYPE, (char *) &s);
risnull(CINTTYPE, (char *) &i);
]]></programlisting>
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </sect2>

  <sect2>
   <title>Constantes supplémentaires</title>
   <para>
    Toutes les constantes qui suivent décrivent des erreurs et toutes sont
    négatives. Dans les descriptions des différentes
    constantes se trouve la valeur de la constante dans l'implantation
    actuelle. Il est toutefois préférable de ne pas compter sur ce nombre.
    Cela dit on peut se reposer sur le fait que toutes les valeurs sont négatives.
    <variablelist>
     <varlistentry>
      <term><literal>ECPG_INFORMIX_NUM_OVERFLOW</literal></term>
      <listitem>
       <para>
	Les fonctions renvoient cette valeur si un dépassement survient lors
	d'un calcul. En interne, elle vaut -1200 (définition
	<productname>Informix</productname>).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>ECPG_INFORMIX_NUM_UNDERFLOW</literal></term>
      <listitem>
       <para>
	Les fonctions renvoient cette valeur si un soupassement survient
	lors d'un calcul. En interne, elle vaut -1201 (définition
	<productname>Informix</productname>).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>ECPG_INFORMIX_DIVIDE_ZERO</literal></term>
      <listitem>
       <para>
	Les fonctions renvoient cette valeur si une tentative de division par
	zéro est observée. En interne, elle vaut -1202 (définition
	<productname>Informix</productname>).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>ECPG_INFORMIX_BAD_YEAR</literal></term>
      <listitem>
       <para>
	Les fonctions renvoient cette valeur si une mauvaise valeur pour l'année
	est trouvée lors de l'analyse d'une date. En interne, elle vaut -1204
	(définition <productname>Informix</productname>).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>ECPG_INFORMIX_BAD_MONTH</literal></term>
      <listitem>
       <para>
	Les fonctions renvoient cette valeur si une mauvaise valeur pour le mois
	est trouvée lors de l'analyse d'une date. En interne, elle vaut -1205
	(définition <productname>Informix</productname>).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>ECPG_INFORMIX_BAD_DAY</literal></term>
      <listitem>
       <para>
	Les fonctions renvoient cette valeur si une mauvaise valeur pour le jour
	est trouvée lors de l'analyse d'une date. En interne, elle vaut -1206
	(définition <productname>Informix</productname>).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>ECPG_INFORMIX_ENOSHORTDATE</literal></term>
      <listitem>
       <para>
	Les fonctions renvoient cette valeur si une routine d'analyse
	nécessite une représentation courte de date mais qu'elle n'obtient pas
	une chaîne de la bonne longueur.
	En interne, elle vaut -1209 (définition <productname>Informix</productname>).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>ECPG_INFORMIX_DATE_CONVERT</literal></term>
      <listitem>
       <para>
	Les fonctions renvoient cette valeur en cas de problème lors de la
	conversion de la date. En interne, elle vaut -1210 (définition
	<productname>Informix</productname>).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>ECPG_INFORMIX_OUT_OF_MEMORY</literal></term>
      <listitem>
       <para>
	Les fonctions renvoient cette valeur en cas de manque de mémoire. En
	interne, elle vaut -1211 (définition <productname>Informix</productname>).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>ECPG_INFORMIX_ENOTDMY</literal></term>
      <listitem>
       <para>
	Les fonctions renvoient cette valeur si une routine d'analyse attend un
	masque de formatage (comme <literal>mmddyy</literal>) mais que
	certains champs n'ont pas été indiqués correctement.
	En interne, elle vaut -1212 (définition <productname>Informix</productname>).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>ECPG_INFORMIX_BAD_NUMERIC</literal></term>
      <listitem>
       <para>
	Les fonctions renvoient cette valeur si une routine d'analyse ne peut
	pas créer la représentation textuelle d'une valeur numérique, parce
	qu'elle contient des erreurs,
	ou si une routine ne peut terminer un calcul impliquant des variables
	numériques parce que l'une d'elle, au moins, est invalide.
	En interne, elle vaut -1213 (définition <productname>Informix</productname>).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>ECPG_INFORMIX_BAD_EXPONENT</literal></term>
      <listitem>
       <para>
	Les fonctions renvoient cette valeur en cas de mauvais exposant. En
	interne, elle vaut -1216 (définition <productname>Informix</productname>).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>ECPG_INFORMIX_BAD_DATE</literal></term>
      <listitem>
       <para>
	Les fonctions renvoient cette valeur en cas de mauvaise valeur. En
	interne, elle vaut -1218 (définition <productname>Informix</productname>).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>ECPG_INFORMIX_EXTRA_CHARS</literal></term>
      <listitem>
       <para>
	Les fonctions renvoient cette valeur en cas de caractères superflus.
	En interne, elle vaut -1264 (définition <productname>Informix</productname>).
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </sect2>
 </sect1>

 <sect1 id="ecpg-descriptors">
  <title>Utiliser les zones de descripteur SQL</title>

  <para>
   Une zone de descripteur SQL est une méthode de traitement du résultat 
   d'un <command>SELECT</command> ou d'un <command>FETCH</command> plus
   sophistiquée.
   La zone de 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 est constituée d'un en-tête, qui contient des
   informations sur le descripteur complet, et un ou plusieurs éléments
   de zones de descripteur, qui basiquement décrivent chacun une colonne de la ligne de
   résultat.
  </para>

  <para>
   Avant d'utiliser une zone de descripteur SQL, il est nécessaire de
   l'allouer&nbsp;:
<programlisting>EXEC SQL ALLOCATE DESCRIPTOR <replaceable>identifiant</replaceable>;
</programlisting>
   L'identifiant sert de <quote>nom de variable</quote> à la zone du
   descripteur.
  </para> <remark>La portée du descripteur alloué est QUOI&nbsp;?</remark>
  <para>
   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 une zone de descripteur, il suffit de le préciser 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>
   Il reste à répondre à la question de la récupération des données de la zone
   descripteur.
   Celle-ci peut être considéré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 doit être de 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 une constante entière ou une
   variable hôte contenant un entier. Les champs possibles sont&nbsp;:

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

    <varlistentry>
     <term><literal>DATA</literal></term>
     <listitem>
      <para>
       l'élément de données en cours (de fait, le type de données de ce champ
       dépend de la requête)&nbsp;;
      </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 implanté&nbsp;;
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>INDICATOR</literal> (integer)</term>
     <listitem>
      <para>
       l'indicateur (de valeur NULL ou de troncature de la valeur)&nbsp;;
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>KEY_MEMBER</literal> (integer)</term>
     <listitem>
      <para>
       non implanté&nbsp;;
      </para>
     </listitem>
    </varlistentry>

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

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

    <varlistentry>
     <term><literal>NULLABLE</literal> (integer)</term>
     <listitem>
      <para>
       non implanté&nbsp;;
      </para>
     </listitem>
    </varlistentry>

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

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

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

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

    <varlistentry>
     <term><literal>SCALE</literal> (integer)</term>
     <listitem>
      <para>
       l'échelle (pour le type <type>numeric</type>)&nbsp;;
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>TYPE</literal> (integer)</term>
     <listitem>
      <para>
       le code numérique du type de données de la colonne&nbsp;;
      </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 indiquée est appelée lorsqu'une erreur survient
        pendant l'exécution d'une instruction SQL&nbsp;;
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>SQLWARNING</literal></term>
      <listitem>
       <para>
        l'action indiquée est appelée lorsqu'un avertissement
        survient pendant l'exécution d'une instruction SQL&nbsp;;
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>NOT FOUND</literal></term>
      <listitem>
       <para>
        l'action indiqué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 prendre une des valeurs
    suivantes&nbsp;:

    <variablelist>
     <varlistentry>
      <term><literal>CONTINUE</literal></term>
      <listitem>
       <para>
        la condition est ignorée. C'est le comportement
        par défaut&nbsp;;
       </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 indiqué (à l'iade d'une instruction C
        <literal>goto</literal>)&nbsp;;
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>SQLPRINT</literal></term>
      <listitem>
       <para>
        affiche un message sur la sortie standard. Cela est utile pour les
        programmes simples ou lors du prototypage. Les détails du message ne
        peuvent pas être configurés&nbsp;;
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>STOP</literal></term>
      <listitem>
       <para>
        appelle <literal>exit(1)</literal>, ce qui termine le programme&nbsp;;
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal>DO BREAK</literal></term>
      <listitem>
       <para>
        exécute l'instruction C <literal>break</literal>. Cela ne doit être
        utilisé que dans les boucles et les instructions
        <literal>switch</literal>&nbsp;;
       </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 indiquées avec les arguments indiqué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>
    L'exemple suivant est utilisable dans un programme simple. Il affiche un message
    lorsqu'un avertissement survient et termine le programme quand une erreur se
    produit&nbsp;:
<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 erreur
    ou avertissement 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 engendre 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'a le
    comportement désiré&nbsp;:
<programlisting>/*
 * FAUX
 */
int main(int argc, char *argv[])
{
    ...
    if (verbose) {
        EXEC SQL WHENEVER SQLWARNING SQLPRINT;
    }
    ...
    EXEC SQL SELECT ...;
    ...
}
</programlisting>

<programlisting>/*
 * FAUX
 */
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 sqlerrmcSQLERRMC_LEN;
    } 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 contient
    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> vaut 0 et
    <literal>sqlca.sqlstate</literal> vaut <literal>"00000"</literal>. Si un
    avertissement ou une erreur survient, alors
    <literal>sqlca.sqlcode</literal> est négatif et
    <literal>sqlca.sqlstate</literal> est différent de
    <literal>"00000"</literal>. Une valeur positive de
    <literal>sqlca.sqlcode</literal> indique une condition sans dommage,
    telle que <quote>la dernière requête n'a retourné aucune ligne</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>
    En cas d'erreur ou d'avertissement,
    <literal>sqlca.sqlerrm.sqlerrmc</literal> contient 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). Certains messages sont trop longs pour entrer
    dans le tableau <literal>sqlerrmc</literal> de taille fixe&nbsp;; ils sont
    alors tronqués.
   </para>

   <para>
    En cas d'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 tout 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 implantée dans plusieurs autres systèmes de bases de données SQL.
    Leurs définitions sont similaires dans l'esprit, mais l'écriture d'applications
    portables nécessite une étude attentive des autres implantations.
   </para>
  </sect2>

  <sect2>
   <title><literal>SQLSTATE</literal> vs <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 dérivés du standard SQL mais
    <literal>SQLCODE</literal> est indiqué comme obsolète dans l'édition
    SQL-92 du standard et a été supprimé dans les éditions ultérieures. C'est
    pourquoi il est fortement recommandé que les nouvelles applications
    utilisent <literal>SQLSTATE</literal> dans les nouvelles applications.
   </para>

   <para>
    <literal>SQLSTATE</literal> est un tableau de cinq caractères. Ces cinq
    caractères contiennent des chiffres ou des lettres en majuscules
    représentant les codes de différentes conditions d'erreur ou
    d'avertissement. <literal>SQLSTATE</literal> dispose d'un schéma
    hiérarchique&nbsp;: les deux premiers caractères indiquent la classe
    générale de la condition, les trois derniers caractères indiquent une
    sous-classe de la condition générale. Un succès est indiqué par le
    code <literal>00000</literal>. Les codes <literal>SQLSTATE</literal> sont
    pour la plupart définis dans le standard SQL. Le serveur
    <productname>PostgreSQL</productname> supporte nativement les codes
    d'erreurs <literal>SQLSTATE</literal>&nbsp;; de ce fait, un haut degré de
    cohérence peut être atteint en utilisant ce schéma de code d'erreur dans
    toutes les applications. Pour plus d'informations, voir l'<xref
    linkend="errcodes-appendix"/>.
   </para>

   <para>
    <literal>SQLCODE</literal>, schéma obsolète de codes d'erreur, est un
    simple entier. Une valeur 0 indique un succès, une valeur positive
    indique un succès avec des informations supplémentaires, une valeur négative
    indique une erreur. Le standard SQL ne définit que la valeur positive
    +100, qui indique que la dernière commande n'a renvoyé ou modifié aucune ligne,
    et aucune valeur négative spécifique. De ce fait, ce schéma n'est que faiblement portable
    et ne propose pas d'affectation de code hiérarchique.
    Historiquement, le processeur de SQL embarqué pour
    <productname>PostgreSQL</productname> a affecté quelques valeurs à
    <literal>SQLCODE</literal> spécifiques pour sa propre utilisation. ces
    valeurs sont listées ci-dessous avec leurs valeurs numériques et leurs noms symboliques.
    Elles ne sont pas portables vers d'autres implantations SQL. Pour
    simplifier le portage d'applications vers la schéma <literal>SQLSTATE</literal>,
    le code <literal>SQLSTATE</literal> correspondant est également affiché.
    Il n'y a toutefois pas de correspondance une-à-une ou une-à-plusieurs
    entre les deux schémas (en fait, c'est plutôt plusieurs-à-plusieurs).
    Il est préférable de consulter le schéma <literal>SQLSTATE</literal> global
    dans l'<xref linkend="errcodes-appendix"/> pour chaque cas.
   </para>

   <para>
    Valeurs affectées à <literal>SQLCODE</literal>&nbsp;:

    <variablelist>
     <varlistentry>
      <term>-12 (<symbol>ECPG_OUT_OF_MEMORY</symbol>)</term>
      <listitem>
       <para>
        la mémoire virtuelle est épuisée, (SQLSTATE
        YE001)&nbsp;;
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-200 (<symbol>ECPG_UNSUPPORTED</symbol>)</term>
     <listitem>
      <para>
       le préprocesseur a engendré quelque chose que la bibliothèque
       ne connaît pas. Il peut s'agir de l'exécution de versions incompatibles
       du préprocesseur et de la bibliothèque, (SQLSTATE YE002).&nbsp;;
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-201 (<symbol>ECPG_TOO_MANY_ARGUMENTS</symbol>)</term>
     <listitem>
      <para>
       la commande indique plus de variables hôtes que n'en
       attend la commande (SQLSTATE 07001 ou 07002)&nbsp;;
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-202 (<symbol>ECPG_TOO_FEW_ARGUMENTS</symbol>)</term>
     <listitem>
      <para>
       la commande indique moins de variables hôtes
       que n'en attend la commande (SQLSTATE 07001 ou 07002)&nbsp;;
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-203 (<symbol>ECPG_TOO_MANY_MATCHES</symbol>)</term>
     <listitem>
      <para>
       une requête retourne plusieurs lignes alors que
       l'instruction est préparée à ne stocker qu'une seule ligne de résultat (par
       exemple, parce que les variables indiquées ne sont pas des tableaux)
       (SQLSTATE 21000)&nbsp;;
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-204 (<symbol>ECPG_INT_FORMAT</symbol>)</term>
     <listitem>
      <para>
       la variable hôte est de type <type>int</type> alors que la donnée dans la base
       est d'un type différent et contient une valeur qui ne peut pas
       être interprétée comme un <type>int</type>. La bibliothèque utilise
       <function>strtol()</function> pour cette conversion (SQLSTATE
       42804)&nbsp;;
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-205 (<symbol>ECPG_UINT_FORMAT</symbol>)</term>
     <listitem>
      <para>
       la variable hôte est de type <type>unsigned int</type> alors que la donnée de la
       base est d'un type différent et contient une valeur qui ne
       peut pas être interprétée comme un <type>unsigned int</type>. La
       bibliothèque utilise <function>strtoul()</function> pour cette
       conversion (SQLSTATE 42804)&nbsp;;
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-206 (<symbol>ECPG_FLOAT_FORMAT</symbol>)</term>
     <listitem>
      <para>
       la variable hôte est de type <type>float</type> alors que la donnée de la
       base est d'un type différent et contient une valeur qui ne
       peut pas être interprétée comme un <type>float</type>. La
       bibliothèque utilise <function>strtod()</function> pour cette conversion
       (SQLSTATE 42804)&nbsp;;
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-211 (<symbol>ECPG_CONVERT_BOOL</symbol>)</term>
     <listitem>
      <para>
       la variable hôte est de type <type>bool</type> alors que
       la donnée de la base n'est ni <literal>'t'</literal> ni
       <literal>'f'</literal> (SQLSTATE 42804)&nbsp;;
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-212 (<symbol>ECPG_EMPTY</symbol>)</term>
     <listitem>
      <para>
       l'instruction envoyée au serveur <productname>PostgreSQL</productname>
       est vide (ceci ne peut normalement pas survenir dans un programme SQL
       embarqué et peut donc indiquer une erreur interne) (SQLSTATE
       YE002)&nbsp;;
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-213 (<symbol>ECPG_MISSING_INDICATOR</symbol>)</term>
     <listitem>
      <para>
       une valeur NULL est retournée alors qu'aucune variable indicateur de
       nullité n'est fournie (SQLSTATE 22002)&nbsp;;
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-214 (<symbol>ECPG_NO_ARRAY</symbol>)</term>
     <listitem>
      <para>
       une variable ordinaire est utilisée à un endroit qui requiert un tableau
       (SQLSTATE 42804)&nbsp;;
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-215 (<symbol>ECPG_DATA_NOT_ARRAY</symbol>)</term>
     <listitem>
      <para>
       la base de données a retourné une variable ordinaire à un endroit qui
       requiert une valeur de tableau (SQLSTATE 42804)&nbsp;;
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-220 (<symbol>ECPG_NO_CONN</symbol>)</term>
     <listitem>
      <para>
       le programme tente d'accéder à une connexion qui n'existe pas
       (SQLSTATE 08003)&nbsp;;
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-221 (<symbol>ECPG_NOT_CONN</symbol>)</term>
     <listitem>
      <para>
       le programme tente d'accéder à une connexion qui existe mais n'est pas
       ouverte (ceci est une erreur interne) (SQLSTATE YE002)&nbsp;;
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-230 (<symbol>ECPG_INVALID_STMT</symbol>)</term>
     <listitem>
      <para>
       l'instruction utilisée n'a pas été préparée (SQLSTATE 26000)&nbsp;;
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-240 (<symbol>ECPG_UNKNOWN_DESCRIPTOR</symbol>)</term>
     <listitem>
      <para>
       le descripteur indiqué n'a pas été trouvé. L'instruction utilisée n'a
       pas été préparée (SQLSTATE 33000)&nbsp;;
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-241 (<symbol>ECPG_INVALID_DESCRIPTOR_INDEX</symbol>)</term>
     <listitem>
      <para>
       l'index du descripteur indiqué est hors échelle (SQLSTATE
       07009)&nbsp;;
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-242 (<symbol>ECPG_UNKNOWN_DESCRIPTOR_ITEM</symbol>)</term>
     <listitem>
      <para>
       un élément invalide du descripteur est demandé (erreur
       interne) (SQLSTATE YE002)&nbsp;;
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-243 (<symbol>ECPG_VAR_NOT_NUMERIC</symbol>)</term>
     <listitem>
      <para>
       lors de l'exécution d'une instruction dynamique, la base de données a
       retourné une valeur numérique alors que la variable hôte n'est pas numérique
       (SQLSTATE 07006)&nbsp;;
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-244 (<symbol>ECPG_VAR_NOT_CHAR</symbol>)</term>
     <listitem>
      <para>
       lors de l'exécution d'une instruction dynamique, la base de données a
       retourné une valeur non numérique alors que la variable hôte est numérique
       (SQLSTATE 07006)&nbsp;;
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-400 (<symbol>ECPG_PGSQL</symbol>)</term>
     <listitem>
      <para>
       le serveur <productname>PostgreSQL</productname> a engendré une erreur. Le message contient le message
       d'erreur du serveur <productname>PostgreSQL</productname>&nbsp;;
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-401 (<symbol>ECPG_TRANS</symbol>)</term>
     <listitem>
      <para>
       le serveur <productname>PostgreSQL</productname> signale que la transaction
       ne peut être commencée, validée ou annulée (SQLSTATE 08007)&nbsp;;
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>-402 (<symbol>ECPG_CONNECT</symbol>)</term>
     <listitem>
      <para>
       la tentative de connexion à la base de données a échoué
       (SQLSTATE 08001)&nbsp;;
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term>100 (<symbol>ECPG_NOT_FOUND</symbol>)</term>
     <listitem>
      <para>
       il s'agit d'une condition sans gravité qui indique que la dernière commande
       n'a récupéré ni traité aucune ligne, ou que la fin du curseur est atteinte
       (SQLSTATE 02000).
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
  </sect2>
 </sect1>

 <sect1 id="ecpg-preproc">
  <title>Directives du préprocesseur</title>

  <sect2>
   <title>Inclusion de fichiers</title>

  <para>
   Pour inclure un fichier externe dans un programme SQL embarqué,
   il suffit d'utiliser&nbsp;:
<programlisting>EXEC SQL INCLUDE <replaceable>nomfichier</replaceable>;
</programlisting>
   Le préprocesseur du SQL embarqué cherche un fichier nommé
   <literal><replaceable>nomfichier</replaceable>.h</literal>, le prétraite et
   l'inclut dans la sortie C résultante. De ce fait, les instructions C
   embarquées du fichier inclus sont correctement gérées.
  </para>

  <para>
   Ce <emphasis>n'</emphasis>est <emphasis>pas</emphasis> la même chose que&nbsp;:
<programlisting>#include &lt;<replaceable>nomfichier</replaceable>.h&gt;
</programlisting>
   parce que ce fichier n'est alors pas sujet au prétraitement des commandes SQL.
   Naturellement, la directive C <literal>#include</literal> peut toujours être
   utilisée pour inclure d'autres fichiers d'en-tête.
  </para>

  <note>
   <para>
    Le nom du fichier inclus est sensible à la casse, même si le reste de la
    commande <literal>EXEC SQL INCLUDE</literal> suit les règles habituelles de
    sensibilité à la casse du SQL.
   </para>
  </note>
  </sect2>

  <sect2>
   <title>Directives #define et #undef</title>
   <para>
    Le SQL embarqué utilise un concept similaire à la directive <literal>#define</literal>
    utilisée en C&nbsp;:
<programlisting>EXEC SQL DEFINE <replaceable>nom</replaceable>;
EXEC SQL DEFINE <replaceable>nom</replaceable> <replaceable>valeur</replaceable>;
</programlisting>
    Un nom peut être défini&nbsp;:
<programlisting>EXEC SQL DEFINE HAVE_FEATURE;
</programlisting>
    Des constantes peuvent aussi être définies&nbsp;:
<programlisting>EXEC SQL DEFINE MON_NOMBRE 12;
EXEC SQL DEFINE MA_CHAINE 'abc';
</programlisting>
    <literal>undef</literal> est utilisé pour supprimer une définition&nbsp;:
<programlisting>
EXEC SQL UNDEF MON_NOMBRE;
</programlisting>
   </para>

   <para>
    Les versions C de <literal>#define</literal> et <literal>#undef</literal>
    peuvent, évidemment, continuer à être utilisées dans le programme
    qui embarque le SQL. La différence se situe à l'endroit où les valeurs
    définies sont évaluées. Si <literal>EXEC SQL DEFINE</literal> est utilisé, 
    alors le préprocesseur ecpg évalue les définitions et effectue les
    substitutions. Par exemple, si on écrit&nbsp;:
<programlisting>EXEC SQL DEFINE MON_NOMBRE 12;
...
EXEC SQL UPDATE Tbl SET col = MON_NOMBRE;
</programlisting>
    alors ecpg effectue la substitution et le compilateur C ne voit aucun
    nom ou identifiant <literal>MON_NOMBRE</literal>. 
    <literal>#define</literal> ne peut pas être utilisé pour une constante
    utilisée dans une requête SQL embarquée car, dans ce cas, le précompilateur
    ecpg n'est pas capable de voir cette déclaration.
   </para>
  </sect2>

  <sect2>
   <title>Directives ifdef, ifndef, else, elif et endif</title>
   <para>
   Les directives suivantes peuvent être utilisées pour compiler des sections de
   code de façon conditionnelle&nbsp;:

   <variablelist>
    <varlistentry>
     <term><literal>EXEC SQL ifdef <replaceable>nom</replaceable>;</literal></term>
     <listitem>
     <para>
      vérifie un <replaceable>nom</replaceable> et traite les lignes qui
      suivent si <replaceable>nom</replaceable> a été créé avec
      <literal>EXEC SQL define <replaceable>nom</replaceable></literal>&nbsp;;
     </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>EXEC SQL ifndef <replaceable>nom</replaceable>;</literal></term>
     <listitem>
     <para>
      vérifie un <replaceable>nom</replaceable> et traite les lignes qui
      suivent si <replaceable>nom</replaceable> <emphasis>n'</emphasis>a <emphasis>pas</emphasis> été créé
      avec <literal>EXEC SQL define
      <replaceable>nom</replaceable></literal>&nbsp;;
     </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>EXEC SQL else;</literal></term>
     <listitem>
     <para>
      commence le traitement d'une section alternative à une section introduite
      avec <literal>EXEC SQL ifdef <replaceable>nom</replaceable></literal>
      ou <literal>EXEC SQL ifndef <replaceable>nom</replaceable></literal>&nbsp;;
     </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>EXEC SQL elif <replaceable>nom</replaceable>;</literal></term>
     <listitem>
     <para>
      vérifie <replaceable>nom</replaceable> et commence le traitement d'une
      section alternative si <replaceable>nom</replaceable> a été créé avec
      <literal>EXEC SQL define <replaceable>nom</replaceable></literal>&nbsp;;
     </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>EXEC SQL endif;</literal></term>
     <listitem>
     <para>
      termine une section alternative.
     </para>
     </listitem>
    </varlistentry>
   </variablelist>
   </para>

   <para>
    Exemple&nbsp;:
<programlisting>exec sql ifndef TZVAR;
exec sql SET TIMEZONE TO 'GMT';
exec sql elif TZNAME;
exec sql SET TIMEZONE TO TZNAME;
exec sql else;
exec sql SET TIMEZONE TO TZVAR;
exec sql endif;
</programlisting>
   </para>

  </sect2>
 </sect1>

 <sect1 id="ecpg-process">
  <title>Traiter les programmes en SQL embarqué</title>

  <para>
   Après avoir vu comment former des programmes C incluant du SQL embarqué, il
   est tout aussi intéressant de savoir comment les compiler.
  </para>
  <para>
   Avant d'être compilé,
   le fichier est passé au travers du préprocesseur <acronym>C</acronym> pour le
   <acronym>SQL</acronym> embarqué. Ce préprocesseur, appelé aussi
   précompilateur, convertit les instructions
   <acronym>SQL</acronym> utilisées en appels de fonctions spéciales.
   Après compilation, le programme doit être lié avec une bibliothèque spéciale
   contenant les fonctions nécessaires. Ces fonctions traitent l'information
   issues des arguments, exécutent la commande <acronym>SQL</acronym> via
   l'interface <application>libpq</application> et placent le résultat
   dans les arguments indiqués pour la sortie.
  </para>

  <para>
   Le préprocesseur, appelé <filename>ecpg</filename>, est inclus dans toute
   installation standard de <productname>PostgreSQL</productname>. Les
   programmes en SQL embarqué
   sont nommés typiquement avec une extension <filename>.pgc</filename>. Un
   fichier programme nommé <filename>prog1.pgc</filename> peut être passé au
   préprocesseur par la simple commande&nbsp;:
<programlisting>ecpg prog1.pgc
</programlisting>
   Ceci crée un fichier nommé <filename>prog1.c</filename>. Si les fichiers
   en entrée ne suivent pas le modèle de nommage suggéré, il est possible de
   nommer explicitement le fichier de sortie en utilisant l'option <option>-o</option>.
  </para>

  <para>
   Le fichier traité par le préprocesseur peut être compilé normalement.
   Par exemple&nbsp;:
<programlisting>cc -c prog1.c
</programlisting>
   Les fichiers sources en C engendrés incluent les fichiers d'en-tête provenant
   de l'installation de <productname>PostgreSQL</productname>. De ce fait, si
   <productname>PostgreSQL</productname> a été installé à un emplacement qui n'est
   pas parcouru par défaut, il faut ajouter une option comme
   <literal>-I/usr/local/pgsql/include</literal> sur la ligne de commande de la
   compilation.
  </para>

  <para>
   Pour lier un programme SQL embarqué, il faut inclure la
   bibliothèque <filename>libecpg</filename> de cette façon&nbsp;:
<programlisting>cc -o monprog prog1.o prog2.o ... -lecpg
</programlisting>
   Là encore, il peut être nécessaire d'ajouter une option comme
   <literal>-L/usr/local/pgsql/lib</literal> sur la ligne de commande.
  </para>

  <para>
   Si le processus de construction d'un grand projet est géré avec
   <application>make</application>, il peut être plus pratique d'inclure la
   règle implicite suivante dans les fichiers makefile&nbsp;:
<programlisting>ECPG = ecpg

%.c: %.pgc
        $(ECPG) $&lt;
</programlisting>
  </para>

  <para>
   La syntaxe complète de la commande <command>ecpg</command> est détaillée dans
   <xref linkend="app-ecpg"/>.
  </para>

  <para>
   La bibliothèque <application>ecpg</application> est compatible avec les
   threads si elle a été compilée en utilisant l'option en ligne de commande
   <option>--enable-thread-safety</option> de <filename>configure</filename>.
   (Il peut s'avérer nécessaire de préciser d'autres options de threading sur la
   ligne de commande pour compiler le code client.)
  </para>
 </sect1>

 <sect1 id="ecpg-library">
  <title>Fonctions de bibliothèque</title>

  <para>
   La bibliothèque <filename>libecpg</filename> contient principalement des
   fonctions <quote>cachées</quote> utilisées pour coder les
   fonctionnalités exprimées par les commandes SQL embarquées. Mais il existe
   quelques fonctions qu'il peut être utile d'appeler directement. Cela a
   toutefois des conséquences sur la portabilité du code.
  </para>

  <itemizedlist>
   <listitem>
    <para>
     <function>ECPGdebug(int <replaceable>on</replaceable>, FILE
     *<replaceable>flux</replaceable>)</function> active le débogage si elle est
     appelée avec une valeur différente de zéro pour le premier argument. Les traces
     de débogage sont envoyées sur le <replaceable>flux</replaceable>. Les
     traces contiennent toutes les instructions <acronym>SQL</acronym> avec
     toutes les variables en entrée et les résultats du serveur
     <productname>PostgreSQL</productname>. Cela peut être très utile pour
     rechercher des erreurs dans les instructions <acronym>SQL</acronym>.
    </para>
    <note>
    <para>
    Sur Windows, si les bibliothèques <application>ecpg</application> et une application
    sont compilées avec des options différentes, cet appel de fonction arrête
    brutalement l'application car la représentation interne des pointeurs
    <literal>FILE</literal> diffère. En particulier, les options
    multi-threaded/single-threaded, release/debug et static/dynamic doivent
    être identiques pour la bibliothèque et pour toutes les
    applications qui utilisent cette bibliothèque.
    </para>
    </note>
   </listitem>

   <listitem>
    <para>
     <function>ECPGstatus(int <replaceable>no_ligne</replaceable>,
     const char* <replaceable>nom_connexion</replaceable>)</function> retourne
     vrai si une connexion à une base de données est active, faux sinon.
     <replaceable>nom_connexion</replaceable> peut être <literal>NULL</literal> si une
     seule connexion est utilisée.
    </para>
   </listitem>
  </itemizedlist>
 </sect1>

 <sect1 id="ecpg-develop">
  <title>Fonctionnement interne</title>

  <para>
   Cette section explique le fonctionnement interne d'<application>ECPG</application>.
   Cette information est parfois utile pour aider les
   utilisateurs à comprendre comment utiliser <application>ECPG</application>.
  </para>

   <para>
    Les quatre premières lignes écrites par <command>ecpg</command> sur la
    sortie sont des lignes figées. Deux sont des commentaires et deux sont des
    lignes d'inclusion de fichiers d'en-tête nécessaires pour l'interfaçage
    avec la bibliothèque. Ensuite, le préprocesseur lit le fichier et écrit
    la sortie. Normalement, il ne fait que tout répéter sur la sortie.
   </para>

   <para>
    Lorsqu'<command>ecpg</command> lit une instruction <command>EXEC SQL</command>, il
    intervient et la modifie. La commande commence avec <command>EXEC
    SQL</command> et se termine avec <command>;</command>. Tout ce qui se trouve
    entre est traité comme une instruction <acronym>SQL</acronym> et analysé
    pour substitution de variable.
   </para>

   <para>
    La substitution de variable intervient quand un symbole débute par un
    caractère deux-points (<literal>:</literal>). La variable possédant ce nom
    est recherchée parmi toutes les variables précédemment déclarées dans une
    section <literal>EXEC SQL DECLARE</literal>.
   </para>

   <para>
    La fonction la plus importante de la bibliothèque est
    <function>ECPGdo</function>, qui prend en charge l'exécution de la plupart
    des commandes. Elle prend un nombre variable d'arguments. Ceci permet d'aller
    jusqu'à environ 50 arguments, ce qui, il faut l'espérer, ne pose
    de problème sur aucune plateforme.
   </para>

   <para>
    Les arguments sont&nbsp;:

    <variablelist>
     <varlistentry>
      <term>Un numéro de ligne</term>
      <listitem>
       <para>
        C'est le numéro de ligne de la ligne originale&nbsp;; utilisé
        seulement dans les messages d'erreur.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>Une chaîne</term>
      <listitem>
       <para>
        C'est la commande <acronym>SQL</acronym> à exécuter. Elle est modifiée
        par les variables en entrée, c'est-à-dire les variables qui n'étaient
        pas connues au moment de la compilation mais qui doivent être précisées
        dans la commande. À l'emplacement des variables, la chaîne contient
        le signe <literal>?</literal>.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>Variables en entrée</term>
      <listitem>
       <para>
        Chaque variable en entrée entraîne la création de dix arguments
        (voir ci-dessous).
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><parameter>ECPGt_EOIT</parameter></term>
      <listitem>
       <para>
        Un <type>enum</type> indiquant qu'il n'y a plus de variables en entrée.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term>Variables en sortie</term>
      <listitem>
       <para>
        Chaque variable en sortie entraîne la création de dix arguments
        (voir ci-dessous). La valeur des variables est fournie par la fonction.
       </para>
      </listitem>
     </varlistentry>

      <varlistentry>
       <term><parameter>ECPGt_EORT</parameter></term>
       <listitem>
       <para>
        Un <type>enum</type> indiquant qu'il n'y a plus de variables.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>

   <para>
    Pour chaque variable de la commande <acronym>SQL</acronym>, la
    fonction récupère dix arguments&nbsp;:

    <orderedlist>
     <listitem>
      <para>
       le type comme symbole spécial&nbsp;;
      </para>
     </listitem>

     <listitem>
      <para>
       un pointeur sur la valeur ou un pointeur sur le pointeur&nbsp;;
      </para>
     </listitem>

     <listitem>
      <para>
       la taille de la variable dans le cas d'un type <type>char</type> ou
       <type>varchar</type>&nbsp;;
      </para>
     </listitem>

     <listitem>
      <para>
       le nombre d'éléments du tableau (pour les parcours de tableaux)&nbsp;;
      </para>
     </listitem>

     <listitem>
      <para>
       le décalage pour obtenir le prochain élément dans le tableau (pour les
       parcours de tableaux)&nbsp;;
      </para>
     </listitem>

     <listitem>
      <para>
       le type de variable indicateur comme un symbole spécial&nbsp;;
      </para>
     </listitem>

     <listitem>
      <para>
       un pointeur vers la variable indicateur&nbsp;;
      </para>
     </listitem>

     <listitem>
      <para>
       0&nbsp;;
      </para>
     </listitem>

     <listitem>
      <para>
       le nombre d'éléments dans le tableau indicateur (pour les parcours
       de tableaux)&nbsp;;
      </para>
     </listitem>

     <listitem>
      <para>
       le décalage pour obtenir le prochain élément dans le tableau indicateur
       (pour les parcours de tableaux).
      </para>
     </listitem>
    </orderedlist>
   </para>

   <para>
    Toutes les commandes SQL ne sont pas traitées ainsi.
    Par exemple, une instruction d'ouverture de curseur comme&nbsp;:
<programlisting>EXEC SQL OPEN <replaceable>curseur</replaceable>;
</programlisting>
    n'est pas copiée sur la sortie. À la place, la commande <command>DECLARE</command>
    de déclaration du curseur est utilisée à la position de la commande <command>OPEN</command>
    car, en fait, elle ouvre le curseur.
   </para>

   <para>
    Exemple complet de sortie du préprocesseur d'un
    fichier <filename>foo.pgc</filename> (les détails peuvent varier pour
    chaque version particulière du préprocesseur)&nbsp;:
<programlisting>EXEC SQL BEGIN DECLARE SECTION;
int index;
int resultat;
EXEC SQL END DECLARE SECTION;
...
EXEC SQL SELECT res INTO :resultat FROM matable WHERE index = :index;
</programlisting>
    est traduit en&nbsp;:
<programlisting><![CDATA[/* Processed by ecpg (2.6.0) */
/* These two include files are added by the preprocessor */
#include <ecpgtype.h>;
#include <ecpglib.h>;

/* exec sql begin declare section */

#line 1 "foo.pgc"

 int index;
 int resultat;
/* exec sql end declare section */
...
ECPGdo(__LINE__, NULL, "SELECT res FROM matable WHERE index = ?     ",
        ECPGt_int,&(index),1L,1L,sizeof(int),
        ECPGt_NO_INDICATOR, NULL , 0L, 0L, 0L, ECPGt_EOIT,
        ECPGt_int,&(resultat),1L,1L,sizeof(int),
        ECPGt_NO_INDICATOR, NULL , 0L, 0L, 0L, ECPGt_EORT);
#line 147 "foo.pgc"
]]></programlisting>
    (L'indentation a été ajoutée ici pour des raisons de lisibilité et n'est pas
    réalisée par le préprocesseur)
   </para>
 </sect1>
</chapter>