repo_zf1/documentation/manual/fr/module_specs/Zend_Db_Select.xml

<!-- EN-Revision: 13846 -->
<sect1 id="zend.db.select">
    <title>Zend_Db_Select</title>

    <sect2 id="zend.db.select.introduction">
        <title>Introduction</title>

        <para>L'objet <classname>Zend_Db_Select</classname> représente une instruction de requête SQL de type <code>SELECT</code>.
        La classe a des méthodes pour ajouter différentes parties à la requête. Vous pouvez indiquer quelques parties de
        la requête en utilisant des structures de données et des méthodes de PHP, et la classe forme la syntaxe correcte
        de SQL pour vous. Après avoir construit une requête, vous pouvez l'exécuter comme si vous l'aviez écrite comme
        une chaîne de caractères.</para>

        <para>Les possibilités offertes par <classname>Zend_Db_Select</classname> inclut :</para>

        <itemizedlist>
            <listitem>
                <para>des méthodes orientées objet pour spécifier des requêtes SQL morceau par morceau ;</para>
            </listitem>

            <listitem>
                <para>l'abstraction de certaines parties de la requête SQL indépendamment de la base de données ;</para>
            </listitem>

            <listitem>
                <para>l'échappement automatique des identificateurs de méta-données dans la plupart des cas, pour
                supporter les identificateurs contenant les mots réservés SQL et les caractères spéciaux ;</para>
            </listitem>

            <listitem>
                <para>l'échappement des identificateurs et des valeurs, afin de réduire les risques d'attaques par
                injection SQL.</para>
            </listitem>
        </itemizedlist>

        <para>L'utilisation de <classname>Zend_Db_Select</classname> n'est pas obligatoire. Pour de très simple requêtes SELECT ,
        il est d'habitude plus simple de spécifier la requête SQL entière comme une chaîne et l'exécuter en utilisant
        des méthodes de l'adaptateur comme <code>query()</code> ou <code>fetchAll()</code>. L'utilisation de
        <classname>Zend_Db_Select</classname> est utile si vous devez assembler une requête SELECT par procédure, ou basé sur une
        logique conditionnelle dans votre application.</para>
    </sect2>

    <sect2 id="zend.db.select.creating">
        <title>Créer un objet Select</title>

        <para>Vous pouvez créer une instance d'un objet <classname>Zend_Db_Select</classname> en utilisant la méthode
        <code>select()</code> de l'objet <classname>Zend_Db_Adapter_Abstract</classname>.</para>

        <example id="zend.db.select.creating.example-db">
            <title>Exemple d'utilisation de la méthode select()</title>

            <programlisting role="php"><![CDATA[
$db = Zend_Db::factory( ...options... );
$select = $db->select();
]]></programlisting>
        </example>

        <para>Une autre manière de créer un objet <classname>Zend_Db_Select</classname> est avec son constructeur, en indiquant
        l'adaptateur de base de données comme argument.</para>

        <example id="zend.db.select.creating.example-new">
            <title>Exemple de création d'un nouvel objet Select</title>

            <programlisting role="php"><![CDATA[
$db = Zend_Db::factory( ...options... );
$select = new Zend_Db_Select($db);
]]></programlisting>
        </example>
    </sect2>

    <sect2 id="zend.db.select.building">
        <title>Construction de requêtes Select</title>

        <para>En construisant la requête, vous pouvez ajouter des clauses à la requête une par une. Il y a une méthode
        séparée pour ajouter chaque clause à l'objet <classname>Zend_Db_Select</classname>.</para>

        <example id="zend.db.select.building.example">
            <title>Exemple d'utilisation des méthodes d'ajout de clauses</title>

            <programlisting role="php"><![CDATA[
// Créer un objet Zend_Db_Select
$select = $db->select();

// Ajouter une clause FROM
$select->from( ...spécifiez une table et des colonnes... )

// Ajouter une clause WHERE
$select->where( ...spécifiez des critères de recherche... )

// Ajouter une clause ORDER BY
$select->order( ...spécifiez des critères de tri... );
]]></programlisting>
        </example>

        <para>Vous pouvez également employer la plupart des méthodes de l'objet Zend_Db_Select avec une interface fluide
        et simple. Une <ulink url="http://en.wikipedia.org/wiki/Fluent_interface">interface fluide</ulink> signifie que
        chaque méthode renvoie une référence à l'objet qui a été appelé, ainsi vous pouvez immédiatement appeler une
        autre méthode.</para>

        <example id="zend.db.select.building.example-fluent">
            <title>Exemple d'utilisation de l'interface fluide</title>

            <programlisting role="php"><![CDATA[
$select = $db->select()
             ->from( ...spécifiez une table et des colonnes... )
             ->where( ...spécifiez des critères de recherche... )
             ->order( ...spécifiez des critères de tri... );
]]></programlisting>
        </example>

        <para>Les exemples de cette section montrent l'utilisation de l'interface fluide, mais vous pouvez employer une
        interface non-fluide dans tous les cas. Il est souvent nécessaire d'employer l'interface non-fluide, par
        exemple, si votre application doit exécuter de la logique avant d'ajouter une clause à une requête.</para>

        <sect3 id="zend.db.select.building.from">
            <title>Ajouter une clause FROM</title>

            <para>Indiquez la table pour la requête en utilisant la méthode <code>from()</code>. Vous pouvez indiquer le
            nom de table comme une chaîne de caractères. <classname>Zend_Db_Select</classname> applique l'échappement des
            identificateurs autour du nom de table, ainsi vous pouvez employer les caractères spéciaux.</para>

            <example id="zend.db.select.building.from.example">
                <title>Exemple d'utilisation de la méthode <code>from()</code></title>

                <programlisting role="php"><![CDATA[
// Construire cette requête :
//   SELECT *
//   FROM "produits"

$select = $db->select()
             ->from( 'produits' );
]]></programlisting>
            </example>

            <para>Vous pouvez également indiquer le nom de corrélation (parfois appelé "l'alias de table") pour une
            table. Au lieu d'une chaîne de caractère simple, employez un tableau associatif faisant correspondre le nom
            de corrélation au nom de table. Dans d'autres clauses de la requête SQL, employez ce nom de corrélation. Si
            votre requête réalise des jointures sur plus d'une table, <classname>Zend_Db_Select</classname> produit des noms
            uniques de corrélation basés sur les noms de table, pour chaque table pour lesquelles vous n'indiquez pas le
            nom de corrélation.</para>

            <example id="zend.db.select.building.from.example-cname">
                <title>Exemple d'utilisation d'un alias de nom de table</title>

                <programlisting role="php"><![CDATA[
// Construire cette requête :
//   SELECT p.*
//   FROM "produits" AS p

$select = $db->select()
             ->from( array('p' => 'produits') );
]]></programlisting>
            </example>

            <para>Certaines marques de SGBDR supportent un spécificateur de schéma principal pour une table. Vous pouvez
            spécifiez un nom de table comme "<code>nomDuSchema.nomDeTable</code>", où <classname>Zend_Db_Select</classname>
            échappera chaque partie individuellement, ou vous pouvez spécifier le nom du schéma séparément. Un nom de
            schéma spécifié dans le nom de table sera prioritaire sur un schéma fourni séparément dans les cas où les
            deux seraient fournis.</para>

            <example id="zend.db.select.building.from.example-schema">
                <title>Exemple d'utilisation d'un nom de schéma</title>

                <programlisting role="php"><![CDATA[
// Construire cette requête :
//   SELECT *
//   FROM "monschema"."produits"

$select = $db->select()
             ->from( 'monschema.produits' );

// ou

$select = $db->select()
             ->from('produits', '*', 'monschema');
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.db.select.building.columns">
            <title>Ajouter des colonnes</title>

            <para>Dans le deuxième argument de la méthode <code>from()</code>, vous pouvez indiquer les colonnes à
            choisir parmi les tables respectives. Si vous n'indiquez aucune colonne, la valeur par défaut est
            "<code>*</code>", la caractère de remplacement SQL pour "toutes les colonnes".</para>

            <para>Vous pouvez énumérer les colonnes dans un tableau simple de chaîne de caractère, ou en tant que
            tableau associatif faisant correspondre l'alias de la colonne au nom de la colonne. Si vous avez seulement
            une colonne à requêter, et vous n'avez pas besoin d'indiquer un alias de colonne, vous pouvez l'énumérer
            comme une chaîne simple au lieu d'un tableau.</para>

            <para>Si vous passez un tableau comme argument pour les colonnes, aucune colonne pour la table
            correspondante ne sera inclus dans le jeu de résultat. Voir un <link
            linkend="zend.db.select.building.join.example-no-columns">exemple de code</link> sous la section concernant
            la méthode <code>join()</code>.</para>

            <para>Vous pouvez indiquer le nom de colonne en tant que "<code>aliasDeTable.nomDeColonne</code>".
            <classname>Zend_Db_Select</classname> échappera chaque partie individuellement. Si vous n'indiquez pas un nom d'alias
            pour une colonne, elle emploie le nom de corrélation de la table nommée dans la méthode courante
            <code>from()</code>.</para>

            <example id="zend.db.select.building.columns.example">
                <title>Exemples de spécification de colonnes</title>

                <programlisting role="php"><![CDATA[
// Construire cette requête :
//   SELECT p."produit_id", p."produit_nom"
//   FROM "produits" AS p

$select = $db->select()
             ->from(array('p' => 'produits'),
                    array('produit_id', 'produit_nom'));

// Construire la même requête, en spécifiant l'alias de table :
//   SELECT p."produit_id", p."produit_nom"
//   FROM "produits" AS p

$select = $db->select()
             ->from(array('p' => 'produits'),
                    array('p.produit_id', 'p.produit_nom'));

// Construire cette requête avec un alias pour une colonne :
//   SELECT p."produit_id" AS prodno, p."produit_nom"
//   FROM "produits" AS p

$select = $db->select()
             ->from(array('p' => 'produits'),
                    array('prodno' => 'produit_id', 'produit_nom'));
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.db.select.building.columns-expr">
            <title>Ajouter une expression de colonne</title>

            <para>Les colonnes dans les requêtes SQL sont parfois des expressions, pas simplement des noms de colonnes
            d'une table. Les expressions peuvent avoir des noms d'alias ou peuvent nécessiter d'être échappées. Si la
            chaîne de caractère désignant votre colonne contient des parenthèses, <classname>Zend_Db_Select</classname> la
            reconnaît comme une expression.</para>

            <para>Vous pouvez aussi créer un objet de type <classname>Zend_Db_Expr</classname> explicitement, pour éviter qu'une
            chaîne soit traitée comme un nom de colonne. <classname>Zend_Db_Expr</classname> est une classe minimale qui contient
            une unique chaîne de caractère. <classname>Zend_Db_Select</classname> reconnaît les objets de type
            <classname>Zend_Db_Expr</classname> et les convertit en chaînes de caractères, mais n'applique aucun changement, tel
            qu'un échappement ou un alias.</para>

            <note>
                <para>Utiliser <classname>Zend_Db_Expr</classname> pour les noms de colonnes n'est pas nécessaire si votre
                expression de colonne contient des parenthèses ; <classname>Zend_Db_Select</classname> reconnaît les parenthèses
                et traite la chaîne comme une expression en omettant l'échappement et les alias.</para>
            </note>

            <example id="zend.db.select.building.columns-expr.example">
                <title>Exemples d'utilisation de colonnes contenant des expressions</title>

                <programlisting role="php"><![CDATA[
// Construire cette requête :
//   SELECT p."produit_id", LOWER(produit_nom)
//   FROM "produits" AS p
// Une expression avec parenthèses devient implicitement
// un objet Zend_Db_Expr.

$select = $db->select()
             ->from(array('p' => 'produits'),
                    array('produit_id', 'LOWER(produit_nom)'));

// Construire cette requête :
//   SELECT p."produit_id", (p.prix * 1.08) AS prix_avec_taxe
//   FROM "produits" AS p

$select = $db->select()
             ->from(array('p' => 'produits'),
                    array('produit_id',
                          'prix_avec_taxe' => '(p.prix * 1.08)'));

// Construire cette requête en utilisant explicitement Zend_Db_Expr :
//   SELECT p."produit_id", p.prix * 1.08 AS prix_avec_taxe
//   FROM "produits" AS p

$select = $db->select()
             ->from(array('p' => 'produits'),
                    array('produit_id',
                          'prix_avec_taxe' =>
                                new Zend_Db_Expr('p.prix * 1.08')));
]]></programlisting>
            </example>

            <para>Dans les cas ci-dessus, <classname>Zend_Db_Select</classname> ne change pas la chaîne pour appliquer des alias
            ou échapper les identificateurs. Si ces changements sont nécessaires pour résoudre l'ambiguïté, vous devez
            faire manuellement les changements dans la chaîne de caractères.</para>

            <para>Si vos noms de colonne sont des mots-clés de SQL ou contiennent les caractères spéciaux, vous devriez
            employer la méthode <code>quoteIdentifier()</code> de l'adaptateur et interpoler le résultat dans la chaîne
            de caractères. La méthode <code>quoteIdentifier()</code> utilise l'échappement SQL pour délimiter les
            identificateurs, qui indique clairement que c'est un identificateur pour une table ou une colonne, et non
            n'importe quelle autre partie de la syntaxe de SQL.</para>

            <para>Votre code est plus indépendant du SGBDR si vous utilisez la méthode <code>quoteIdentifier()</code> au
            lieu d'échapper littéralement dans votre chaîne, car quelques marques de SGBDR utilisent des symboles non
            standards pour échapper les identificateurs. La méthode <code>quoteIdentifier()</code> est conçue pour
            utiliser le symbole d'échappement approprié basé sur le type d'adaptateur. La méthode
            <code>quoteIdentifier()</code> échappe aussi tout caractère d'échappement qui apparaissent dans
            l'identificateur lui-même.</para>

            <example id="zend.db.select.building.columns-quoteid.example">
                <title>Exemples d'échappement de colonnes dans une expression</title>

                <programlisting role="php"><![CDATA[
// Construire cette requête, en échappant une colonne spéciale
// nommée "from" dans une expression :
//   SELECT p."from" + 10 AS origine
//   FROM "produits" AS p

$select = $db->select()
             ->from(array('p' => 'produits'),
                    array('origine' => '(p.'
                                     . $db->quoteIdentifier('from')
                                     . ' + 10)'));
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.db.select.building.columns-atomic">
            <title>Ajouter des colonnes à une table FROM ou JOIN existante</title>

            <para>Il peut y avoir des cas où vous souhaitez ajouter des colonnes à une table FROM ou JOIN existante
            après que ces méthodes aient été appelées. La méthode <code>columns()</code> vous permet d'ajouter des
            colonnes spécifiques à n'importe quel moment avant que la requête ne soit exécutée. Vous pouvez fournir les
            colonnes en tant qu'une chaîne de caractères, une <classname>Zend_Db_Expr</classname> ou un tableau de ces derniers.
            Le second argument de cette méthode peut être omis, impliquant que les colonnes sont ajoutées à la table
            FROM, sinon un alias déjà défini doit être utilisé.</para>

            <example id="zend.db.select.building.columns-atomic.example">
                <title>Exemples d'ajout de colonnes avec la méthode <code>columns()</code></title>

                <programlisting role="php"><![CDATA[
// Construire cette requête :
//   SELECT p."produit_id", p."produit_nom"
//   FROM "produits" AS p

$select = $db->select()
             ->from(array('p' => 'produits'), 'produit_id')
             ->columns('produit_nom');

// Construire la même requête, en spécifiant l'alias :
//   SELECT p."produit_id", p."produit_nom"
//   FROM "produits" AS p

$select = $db->select()
             ->from(array('p' => 'produits'), 'p.produit_id')
             ->columns('produit_nom', 'p');
             // Ou alternativement columns('p.produit_nom')
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.db.select.building.join">
            <title>Ajouter une autre table à la requête avec JOIN</title>

            <para>Beaucoup de requêtes utiles impliquent l'utilisation de <code>JOIN</code> pour combiner les lignes
            issues de tables multiples. Vous pouvez ajouter des tables à une requête en utilisant la méthode
            <code>join()</code>. L'utilisation de cette méthode est similaire à la méthode <code>from()</code>, excepté
            que vous pouvez aussi spécifier une condition join dans la plupart des cas.</para>

            <example id="zend.db.select.building.join.example">
                <title>Exemple d'utilisation de la méthode join()</title>

                <programlisting role="php"><![CDATA[
// Construire cette requête :
//   SELECT p."produit_id", p."produit_nom", l.*
//   FROM "produits" AS p JOIN "ligne_items" AS l
//     ON p.produit_id = l.produit_id

$select = $db->select()
             ->from(array('p' => 'produits'),
                    array('produit_id', 'produit_nom'))
            ->join(array('l' => 'ligne_items'),
                   'p.produit_id = l.produit_id');
]]></programlisting>
            </example>

            <para>Le deuxième argument de <code>join()</code> est une chaîne qui représente la condition join. C'est une
            expression qui déclare les critères par lesquels les lignes d'une table correspondent aux lignes dans une
            autre table. Vous pouvez utiliser un nom d'alias dans cette expression.</para>

            <note>
                <para>Aucun échappement n'est appliqué à une expression que vous spécifiez pour une condition join ; si
                vous avez des noms de colonnes qui nécessitent d'être échappées, vous devez utiliser
                <code>quoteIdentifier()</code> quand vous préparez la chaîne pour une condition join.</para>
            </note>

            <para>Le troisième argument de <code>join()</code> est un tableau des noms de colonnes, comme c'est utilisé
            dans la méthode <code>from()</code>. La valeur par défaut est "<code>*</code>", la méthode supporte les
            alias, les expressions, et les objets <classname>Zend_Db_Expr</classname> de la même manière que le tableau de noms de
            colonnes de la méthode <code>from()</code>.</para>

            <para>Pour ne choisir aucune colonne à partir d'une table, utilisez un tableau vide pour la liste de
            colonnes. Cette utilisation fonctionnerait aussi avec la méthode <code>from()</code>, mais typiquement vous
            pouvez avoir besoin de colonnes issues de la table primaire dans vos requêtes, tandis que vous pourriez ne
            vouloir aucune colonne de la table jointe.</para>

            <example id="zend.db.select.building.join.example-no-columns">
                <title>Exemple avec aucune colonne spécifiée</title>

                <programlisting role="php"><![CDATA[
// Construire cette requête :
//   SELECT p."produit_id", p."produit_nom"
//   FROM "produits" AS p JOIN "ligne_items" AS l
//     ON p.produit_id = l.produit_id

$select = $db->select()
             ->from(array('p' => 'produits'),
                    array('produit_id', 'produit_name'))
             ->join(array('l' => 'ligne_items'),
                    'p.produit_id = l.produit_id',
                    array() ); // liste de colonnes vide
]]></programlisting>

                <para>Notez le tableau vide (<code>array()</code>) dans l'exemple ci-dessus à la place de la liste de
                colonnes de la table jointe.</para>
            </example>

            <para>Le SQL a plusieurs types de jointures. Voyez la liste ci-dessous des méthodes supportant les
            différents types de jointures dans <classname>Zend_Db_Select</classname>.</para>

            <itemizedlist>
                <listitem>
                    <para><command>INNER JOIN</command> avec les méthodes <code>join(table, jointure, [colonnes])</code>
                    ou <code>joinInner(table, jointure, [colonnes])</code>.</para>

                    <para>Ceci est le type de jointure le plus commun. Les lignes de chaque table sont comparées en
                    utilisant la condition join spécifiée. Le résultat inclut seulement les lignes qui vérifient la
                    condition join. Le résultat peut être vide si aucune ligne ne satisfait la condition.</para>

                    <para>Tous les marques de SGBDR supportent ce type de jointure.</para>
                </listitem>

                <listitem>
                    <para><command>LEFT JOIN</command> avec la méthode <code>joinLeft(table, condition,
                    [colonnes])</code>.</para>

                    <para>Toutes les lignes issues de la table opérande de gauche sont inclues, les lignes
                    correspondantes de la table de droite sont inclues, et les colonnes de la table opérande de droite
                    sont remplies de NULL si aucune ligne existante ne correspond à la table de gauche.</para>

                    <para>Tous les marques de SGBDR supportent ce type de jointure.</para>
                </listitem>

                <listitem>
                    <para><command>RIGHT JOIN</command> avec la méthode <code>joinRight(table, condition,
                    [colonnes])</code>.</para>

                    <para>La jointure étrangère droite est le complément de la jointure étrangère gauche. Toutes les
                    lignes issues de la table opérande de droite sont inclues, les lignes correspondantes de la table de
                    gauche sont inclues, et les colonnes de la table opérande de gauche sont remplies de NULL si aucune
                    ligne existante ne correspond à la table de droite.</para>

                    <para>Certaines marques de SGBDR ne supportent pas ce type de jointure, mais en général toute
                    jointure droite peut être représentée comme une jointure gauche en inversant l'ordre des
                    tables.</para>
                </listitem>

                <listitem>
                    <para><command>FULL JOIN</command> avec la méthode <code>joinFull(table, condition,
                    [colonnes])</code>.</para>

                    <para>Une jointure étrangère complète est comme la combinaison d'une jointure étrangère gauche et
                    d'une jointure étrangère droite. Toutes les lignes des deux tables sont inclues, appairées ensemble
                    dans la même ligne de résultat si elles satisfont la condition de jointure, et sinon appairées avec
                    des valeurs NULL à la place des colonnes de l'autre table.</para>

                    <para>Certaines marques de SGBDR ne supportent pas ce type de jointure.</para>
                </listitem>

                <listitem>
                    <para><command>CROSS JOIN</command> avec la méthode <code>joinCross(table,
                    [colonnes])</code>.</para>

                    <para>Une jointure croisée est un produit cartésien. Chaque ligne de la première table est assortie
                    avec chaque ligne de la seconde. Ainsi le nombre de lignes du résultat est équivalent au produit du
                    nombre de lignes de chacune des tables. Vous pouvez filtrer le résultat en utilisant une clause
                    WHERE ; dans ce cas une jointure croisée est semblable à l'ancienne syntaxe de jointure
                    SQL-89.</para>

                    <para>La méthode <code>joinCross()</code> n'a pas de paramètres pour spécifier la condition de
                    jointure. Certaines marques de SGBDR ne supportent pas ce type de jointure.</para>
                </listitem>

                <listitem>
                    <para><command>NATURAL JOIN</command> avec la méthode <code>joinNatural(table,
                    [colonnes])</code>.</para>

                    <para>Une jointure naturelle compare chaque(s) colonne(s) qui apparaissent avec le même nom dans les
                    deux tables. La comparaison est l'égalité pour toute(s) la(es) colonne(s) ; la comparaison des
                    colonnes utilisant l'inégalité n'est pas une jointure naturelle. Seules les jointures internes (NdT
                    : INNER) naturelles sont supportées par cette API, même si la syntaxe SQL permet aussi bien des
                    jointures naturelles étrangères (NdT : OUTER).</para>

                    <para>La méthode <code>joinNatural()</code> n'a pas de paramètres pour spécifier la condition de
                    jointure.</para>
                </listitem>
            </itemizedlist>

            <para>En plus de ces méthodes join, vous pouvez simplifier vos requêtes en utilisant les méthodes de type
            <code>join*Using</code>. Au lieu de fournir une condition complète à votre jointure, vous fournissez
            simplement le nom de la colonne sur laquelle réaliser la jointure et l'objet <classname>Zend_Db_Select</classname>
            complète la condition pour vous.</para>

            <example id="zend.db.select.building.joinusing.example">
                <title>Exemple avec la méthode <code>joinUsing()</code></title>

                <programlisting role="php"><![CDATA[
// Construire cette requête :
//   SELECT *
//   FROM "table1"
//   JOIN "table2"
//   ON "table1".colonne1 = "table2".colonne1
//   WHERE colonne2 = 'foo'

$select = $db->select()
             ->from('table1')
             ->joinUsing('table2', 'colonne1')
             ->where('column2 = ?', 'foo');
]]></programlisting>
            </example>

            <para>Chacune des méthodes join applicables du composant <classname>Zend_Db_Select</classname> possède une méthode
            correspondante "using".</para>

            <itemizedlist>
                <listitem>
                    <para><code>joinUsing(table, join, [columns])</code> et <code>joinInnerUsing(table, join,
                    [columns])</code></para>
                </listitem>

                <listitem>
                    <para><code>joinLeftUsing(table, join, [columns])</code></para>
                </listitem>

                <listitem>
                    <para><code>joinRightUsing(table, join, [columns])</code></para>
                </listitem>

                <listitem>
                    <para><code>joinFullUsing(table, join, [columns])</code></para>
                </listitem>
            </itemizedlist>
        </sect3>

        <sect3 id="zend.db.select.building.where">
            <title>Ajouter une clause WHERE</title>

            <para>Vous pouvez spécifier des critères pour restreindre le nombre de lignes du résultat en utilisant la
            méthode <code>where()</code>. Le premier argument de cette méthode est une expression SQL, et cette
            expression est utilisée dans une clause <code>WHERE</code> dans la requête.</para>

            <example id="zend.db.select.building.where.example">
                <title>Exemple d'utilisation de la méthode <code>where()</code></title>

                <programlisting role="php"><![CDATA[
// Construire cette requête :
//   SELECT produit_id, produit_nom, prix
//   FROM "produits"
//   WHERE prix > 100.00

$select = $db->select()
             ->from('produits',
                    array('produit_id', 'produit_nom', 'prix'))
             ->where('prix > 100.00');
]]></programlisting>
            </example>

            <note>
                <para>Aucun échappement n'est appliqué aux expressions passées aux méthodes <code>where()</code> ou
                <code>orWhere()</code>. Si vous avez des noms de colonnes qui nécessitent d'être échappés, vous devez
                utiliser <code>quoteIdentifier()</code> quand vous générez la chaîne pour la condition.</para>
            </note>

            <para>Le second argument de la méthode <code>where()</code> est optionnel. C'est une valeur à substituer
            dans l'expression. <classname>Zend_Db_Select</classname> échappe cette valeur et la substitue au caractère point
            ("<code>?</code>") d'interrogation dans l'expression.</para>

            <para>Cette méthode accepte un seul paramètre. Si vous avez une expression dans laquelle vous devez
            substituer plusieurs variables, vous devez formater la chaîne manuellement, en interpolant les variables et
            en les échappant vous-même.</para>

            <example id="zend.db.select.building.where.example-param">
                <title>Exemple d'un paramètre dans la méthode <code>where()</code></title>

                <programlisting role="php"><![CDATA[
// Construire cette requête :
//   SELECT produit_id, produit_nom, prix
//   FROM "produits"
//   WHERE (prix > 100.00)

$prixminimum = 100;

$select = $db->select()
             ->from('produits',
                    array('produit_id', 'produit_nom', 'prix'))
             ->where('prix > ?', $prixminimum);
]]></programlisting>
            </example>

            <para>Vous pouvez appeler la méthode <code>where()</code> plusieurs fois sur la même objet
            <classname>Zend_Db_Select</classname>. La requête résultante combine les différents termes ensemble en utilisant
            <code>AND</code> entre eux.</para>

            <example id="zend.db.select.building.where.example-and">
                <title>Exemple avec plusieurs appels de <code>where()</code></title>

                <programlisting role="php"><![CDATA[
// Construire cette requête :
//   SELECT produit_id, produit_nom, prix
//   FROM "produits"
//   WHERE (prix > 100.00)
//     AND (prix < 500.00)

$prixminimum = 100;
$prixmaximum = 500;

$select = $db->select()
             ->from('produits',
                    array('produit_id', 'produit_nom', 'prix'))
             ->where('prix > ?', $prixminimum)
             ->where('prix < ?', $prixmaximum);
]]></programlisting>
            </example>

            <para>Si vous devez combiner ensemble des termes en utilisant <code>OR</code>, utilisez la méthode
            <code>orWhere()</code>. Cette méthode est utilisée de la même manière que la méthode <code>where()</code>,
            excepté que le terme spécifié est précédé par <code>OR</code>, au lieu de <code>AND</code>.</para>

            <example id="zend.db.select.building.where.example-or">
                <title>Exemple d'utilisation de la méthode <code>orWhere()</code></title>

                <programlisting role="php"><![CDATA[
// Construire cette requête :
//   SELECT produit_id, produit_nom, prix
//   FROM "produits"
//   WHERE (prix < 100.00)
//     OR (prix > 500.00)

$prixminimum = 100;
$prixmaximum = 500;

$select = $db->select()
             ->from('produits',
                    array('produit_id', 'produit_nom', 'prix'))
             ->where('prix < ?', $prixminimum)
             ->orWhere('prix > ?', $prixmaximum);
]]></programlisting>
            </example>

            <para><classname>Zend_Db_Select</classname> met automatiquement des parenthèses autour de chaque expression spécifiée
            en utilisant les méthodes <code>where()</code> ou <code>orWhere()</code>. Ceci permet de s'assurer que la
            priorité de l'opérateur booléen n'entraîne pas de résultats inattendus.</para>

            <example id="zend.db.select.building.where.example-parens">
                <title>Exemple de mise en parenthèse d'expressions booléennes</title>

                <programlisting role="php"><![CDATA[
// Construire cette requête :
//   SELECT produit_id, produit_nom, prix
//   FROM "produits"
//   WHERE (prix < 100.00 OR prix > 500.00)
//     AND (produit_nom = 'Pomme')

$prixminimum = 100;
$prixmaximum = 500;
$prod = 'Pomme';

$select = $db->select()
             ->from('produits',
                    array('produit_id', 'produit_nom', 'prix'))
             ->where("prix < $prixminimum OR prix > $prixmaximum")
             ->where('produit_nom = ?', $prod);
]]></programlisting>
            </example>

            <para>Dans l'exemple ci-dessus, le résultat serait tout à fait différent sans parenthèses, car
            <code>AND</code> a une plus grande priorité que <code>OR</code>. <classname>Zend_Db_Select</classname> applique les
            parenthèses avec pour effet de relier de manière plus étroite chaque expression dans les appels successifs
            de <code>where()</code> qu'avec <code>AND</code> qui combine les expressions.</para>
        </sect3>

        <sect3 id="zend.db.select.building.group">
            <title>Ajouter une clause GROUP BY</title>

            <para>Dans la syntaxe SQL, la clause <code>GROUP BY</code> vous permet de réduire le nombre de lignes du
            résultat de la requête à une ligne par valeur unique trouvé dans une(des) colonne(s) nommées) dans la clause
            <code>GROUP BY</code>.</para>

            <para>Dans <classname>Zend_Db_Select</classname>, vous pouvez spécifier la(es) colonne(s) à utiliser pour calculer les
            groupes de lignes en utilisant la méthode <code>group()</code>. L'argument de cette méthode est une colonne
            ou un tableau de colonnes à utiliser dans la clause <code>GROUP BY</code>.</para>

            <example id="zend.db.select.building.group.example">
                <title>Exemple d'utilisation de la méthode <code>group()</code></title>

                <programlisting role="php"><![CDATA[
// Construire cette requête :
//   SELECT p."produit_id", COUNT(*) AS ligne_items_par_produit
//   FROM "produits" AS p JOIN "ligne_items" AS l
//     ON p.produit_id = l.produit_id
//   GROUP BY p.produit_id

$select = $db->select()
             ->from(array('p' => 'produits'),
                    array('produit_id'))
             ->join(array('l' => 'ligne_items'),
                    'p.produit_id = l.produit_id',
                    array('ligne_items_par_produit' => 'COUNT(*)'))
            ->group('p.produit_id');
]]></programlisting>
            </example>

            <para>Comme le tableau de colonnes de la méthode <code>from()</code>, vous pouvez utiliser des noms d'alias
            dans le nom de la colonne, et la colonne est échappée comme un identificateur à moins que la chaîne ne
            contiennent des parenthèses ou que ce soit un objet de type <classname>Zend_Db_Expr</classname>.</para>
        </sect3>

        <sect3 id="zend.db.select.building.having">
            <title>Ajouter une clause HAVING</title>

            <para>Dans la syntaxe SQL, la clause <code>HAVING</code> applique une restriction sur un groupe de lignes.
            Ceci est similaire à la manière dont la clause <code>WHERE</code> applique une restriction sur des lignes.
            Mais les deux clauses sont différentes car les conditions <code>WHERE</code> sont appliquées avant que les
            groupes de lignes ne soient définis, alors que les conditions <code>HAVING</code> sont appliquées après que
            les groupes aient été définis.</para>

            <para>Dans <classname>Zend_Db_Select</classname>, vous pouvez spécifier des conditions pour restreindre des groupes en
            utilisant la méthode <code>having()</code>. Son utilisation est similaire à celle de la méthode
            <code>where()</code>. Le premier argument est une chaîne contenant une expression SQL. Le second argument
            facultatif est une valeur qui est utilisé pour remplacer le caractère de substitution positionné dans
            l'expression SQL. Les expressions passées dans de multiples appels de la méthode <code>having()</code> sont
            combinées en utilisant l'opérateur booléen <code>AND</code>, ou l'opérateur <code>OR</code> si vous utilisez
            la méthode <code>orHaving()</code>.</para>

            <example id="zend.db.select.building.having.example">
                <title>Exemple d'utilisation de la méthode <code>having()</code></title>

                <programlisting role="php"><![CDATA[
// Construire cette requête :
//   SELECT p."produit_id", COUNT(*) AS ligne_items_par_produit
//   FROM "produits" AS p JOIN "ligne_items" AS l
//     ON p.produit_id = l.produit_id
//   GROUP BY p.produit_id
//   HAVING ligne_items_par_produit > 10

$select = $db->select()
             ->from(array('p' => 'produits'),
                    array('produit_id'))
             ->join(array('l' => 'ligne_items'),
                    'p.produit_id = l.produit_id',
                    array('ligne_items_par_produit' => 'COUNT(*)'))
             ->group('p.produit_id')
             ->having('ligne_items_par_produit > 10');
]]></programlisting>
            </example>

            <note>
                <para>Aucun échappement n'est appliqué aux expressions fournies aux méthodes <code>having()</code> ou
                <code>orHaving()</code>. Si vous avez des noms de colonnes qui nécessitent d'être échappées, vous devez
                utiliser <code>quoteIdentifier()</code> quand vous générez la chaîne de cette condition.</para>
            </note>
        </sect3>

        <sect3 id="zend.db.select.building.order">
            <title>Ajouter une clause ORDER BY</title>

            <para>Dans la syntaxe SQL, la clause <code>ORDER BY</code> spécifie une ou plusieurs colonnes ou expressions
            suivant lesquelles le résultat d'une requête doit être trié. Si plusieurs colonnes sont listées, les
            colonnes secondaires sont utilisées pour résoudre les égalités ; l'ordre du tri est déterminé par les
            colonnes secondaires si les colonnes précédentes contiennent des valeurs identiques. Le tri par défaut est
            ascendant (du plus petit vers le plus grand). Vous pouvez aussi appliqué un tri descendant (du plus grand
            vers le plus petit) pour une colonne en spécifiant le mot-clé <code>DESC</code> après la colonne.</para>

            <para>Dans <classname>Zend_Db_Select</classname>, vous pouvez utiliser la méthode <code>order()</code> pour spécifier
            une colonne ou un tableau de colonnes par lesquelles vous voulez trier. Chaque élément du tableau est une
            chaîne nommant une colonne, facultativement suivi les mots-clés <code>ASC</code> ou <code>DESC</code> en
            séparant avec un espace.</para>

            <para>Comme pour les méthodes <code>from()</code> et <code>group()</code>, les noms de colonnes sont
            échappées comme des identificateurs, à moins qu'elles ne contiennent des parenthèses ou ne soient des objets
            de type <classname>Zend_Db_Expr</classname>.</para>

            <example id="zend.db.select.building.order.example">
                <title>Exemple d'utilisation de la méthode <code>order()</code></title>

                <programlisting role="php"><![CDATA[
// Construire cette requête :
//   SELECT p."produit_id", COUNT(*) AS ligne_items_par_produit
//   FROM "produits" AS p JOIN "ligne_items" AS l
//     ON p.produit_id = l.produit_id
//   GROUP BY p.produit_id
//   ORDER BY "ligne_items_par_produit" DESC, "produit_id"

$select = $db->select()
             ->from(array('p' => 'produits'),
                    array('produit_id'))
             ->join(array('l' => 'ligne_items'),
                    'p.produit_id = l.produit_id',
                    array('ligne_items_par_produit' => 'COUNT(*)'))
             ->group('p.produit_id')
             ->order(array('ligne_items_par_produit DESC',
                           'produit_id'));
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.db.select.building.limit">
            <title>Ajouter une clause LIMIT</title>

            <para>Certaines marques de SGBDR étendent la syntaxe SQL avec une clause <code>LIMIT</code>. Cette clause
            réduit le nombre de lignes d'un résultat à un nombre maximum que vous spécifiez. Vous pouvez de plus
            indiquer un nombre de lignes à éviter avant de commencer à produire le résultat. Cette fonctionnalité
            facilite l'extraction d'un sous-ensemble d'un résultat, par exemple quand vous affichez des résultats avec
            un défilement de pages.</para>

            <para>Dans <classname>Zend_Db_Select</classname>, vous pouvez utiliser la méthode <code>limit()</code> pour spécifier
            le nombre de lignes ainsi que le nombre de lignes à omettre. Le premier argument de cette méthode est le
            nombre de lignes désirées. Le second argument est le nombre de lignes à omettre.</para>

            <example id="zend.db.select.building.limit.example">
                <title>Exemple d'utilisation de la méthode <code>limit()</code></title>

                <programlisting role="php"><![CDATA[
// Construire cette requête :
//   SELECT p."produit_id", p."produit_nom"
//   FROM "produits" AS p
//   LIMIT 10, 20

$select = $db->select()
             ->from(array('p' => 'produits'),
                    array('produit_id', 'produit_nom'))
             ->limit(10, 20);
]]></programlisting>
            </example>

            <note>
                <para>La syntaxe <code>LIMIT</code> n'est pas supporté par toutes les marques de SGBDR. Quelques SGBDR
                nécessite une syntaxe différente pour supporter une fonctionnalité similaire. Chaque classe
                <classname>Zend_Db_Adapter_Abstract</classname> inclue une méthode pour produire le code SQL approprié à ce
                SGBDR.</para>
            </note>

            <para>Utilisez de manière alternative la méthode <code>limitPage()</code> pour spécifier le nombre de lignes
            et le décalage. Cette méthode vous permet de limiter le jeu de résultats à une série d'un nombre fixé de
            résultats issus du jeu total de résultats de la requête. En d'autres termes, vous spécifiez la taille de la
            "page" de résultats, et le nombre ordinal de la page unique de résultats que vous souhaitez voir retourner
            par la requête. Le numéro de la page est le premier argument de la méthode <code>limitPage()</code>, et la
            taille de la page est le second argument. Les deux arguments sont obligatoires ; ils n'ont pas de valeurs
            par défaut.</para>

            <example id="zend.db.select.building.limit.example2">
                <title>Exemple d'utilisation de la méthode <code>limitPage()</code></title>

                <programlisting role="php"><![CDATA[
// Construire cette requête :
//   SELECT p."product_id", p."product_name"
//   FROM "products" AS p
//   LIMIT 10, 20

$select = $db->select()
             ->from(array('p' => 'products'),
                    array('product_id', 'product_name'))
             ->limitPage(2, 10);
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.db.select.building.distinct">
            <title>Ajouter le modificateur de requête DISTINCT</title>

            <para>La méthode <code>distinct()</code> vous permet d'ajouter le mot-clé <code>DISTINCT</code> à votre
            requête SQL.</para>

            <example id="zend.db.select.building.distinct.example">
                <title>Exemple d'utilisation de la méthode <code>distinct()</code></title>

                <programlisting role="php"><![CDATA[
// Construire cette requête :
//   SELECT DISTINCT p."produit_nom"
//   FROM "produits" AS p

$select = $db->select()
             ->distinct()
             ->from(array('p' => 'produits'), 'produit_nom');
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.db.select.building.for-update">
            <title>Ajouter le modificateur de requête FOR UPDATE</title>

            <para>La méthode <code>forUpdate()</code> vous permet d'ajouter le modificateur <code>FOR UPDATE</code> à
            votre requête SQL.</para>

            <example id="zend.db.select.building.for-update.example">
                <title>Exemple d'utilisation de la méthode <code>forUpdate()</code></title>

                <programlisting role="php"><![CDATA[
// Construire cette requête :
//   SELECT FOR UPDATE p.*
//   FROM "produits" AS p

$select = $db->select()
             ->forUpdate()
             ->from(array('p' => 'produits'));
]]></programlisting>
            </example>
        </sect3>
    </sect2>

    <sect2 id="zend.db.select.execute">
        <title>Exécuter des requêtes Select</title>

        <para>Cette section décrit comment exécuter une requête représentée par un objet
        <classname>Zend_Db_Select</classname>.</para>

        <sect3 id="zend.db.select.execute.query-adapter">
            <title>Exécuter des requêtes Select à partir de l'adaptateur Db</title>

            <para>Vous pouvez exécuter la requête représentée par l'objet <classname>Zend_Db_Select</classname> en le passant
            comme premier argument de la méthode <code>query()</code> d'un objet <classname>Zend_Db_Adapter_Abstract</classname>.
            Utilisez les objets <classname>Zend_Db_Select</classname> plutôt qu'une simple chaîne de requête.</para>

            <para>La méthode <code>query()</code> retourne un objet de type <classname>Zend_Db_Statement</classname> ou
            <code>PDOStatement</code>, dépendant du type d'adaptateur.</para>

            <example id="zend.db.select.execute.query-adapter.example">
                <title>Exemple d'utilisation de la méthode <code>query()</code> de l'adaptateur Db</title>

                <programlisting role="php"><![CDATA[
$select = $db->select()
             ->from('produits');

$stmt = $db->query($select);
$result = $stmt->fetchAll();
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.db.select.execute.query-select">
            <title>Exécuter des requêtes Select à partir de objet Select</title>

            <para>Comme alternative à l'emploi de la méthode <code>query()</code>de l'objet adaptateur, vous pouvez
            utiliser la méthode <code>query()</code> de l'objet <classname>Zend_Db_Select</classname>. Les deux méthodes retourne
            un objet de type <classname>Zend_Db_Statement</classname> ou <code>PDOStatement</code>, dépendant du type
            d'adaptateur.</para>

            <example id="zend.db.select.execute.query-select.example">
                <title>Exemple d'utilisation de la méthode query() de l'objet Select</title>

                <programlisting role="php"><![CDATA[
$select = $db->select()
    ->from('produits');

$stmt = $select->query();
$result = $stmt->fetchAll();
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.db.select.execute.tostring">
            <title>Convertir un objet Select en une chaîne SQL</title>

            <para>Si vous devez accéder à la chaîne représentant la requête SQL correspondant à un objet
            <classname>Zend_Db_Select</classname>, utilisez la méthode <code>__toString()</code>.</para>

            <example id="zend.db.select.execute.tostring.example">
                <title>Exemple d'utilisation de la méthode <code>__toString()</code></title>

                <programlisting role="php"><![CDATA[
$select = $db->select()
             ->from('produits');

$sql = $select->__toString();
echo "$sql\n";

// L'affichage est la chaîne :
//   SELECT * FROM "produits"
]]></programlisting>
            </example>
        </sect3>
    </sect2>

    <sect2 id="zend.db.select.other">
        <title>Autres méthodes</title>

        <para>Cette section décrit les autres méthodes de la classe <classname>Zend_Db_Select</classname> qui ne sont pas
        couvertes ci-dessus : <code>getPart()</code> et <code>reset()</code>.</para>

        <sect3 id="zend.db.select.other.get-part">
            <title>Récupérer des parties de l'objet Select</title>

            <para>La méthode <code>getPart()</code> retourne une représentation d'une partie de votre requête SQL. Par
            exemple, vous pouvez utiliser cette méthode pour retourner un tableau d'expressions pour la clause
            <code>WHERE</code>, ou un tableau de colonnes (ou d'expressions de colonnes) qui sont dans l'élément
            <code>SELECT</code>, ou les valeurs de nombre et de décalage pour la clause <code>LIMIT</code>.</para>

            <para>La valeur retournée n'est pas une chaîne de caractère contenant un fragment de syntaxe SQL. La valeur
            retournée est une représentation interne, qui est typiquement une structure de type tableau contenant des
            valeurs et des expressions. Chaque partie de la requête a une structure différente.</para>

            <para>L'argument unique de la méthode <code>getPart()</code> est une chaîne qui identifie quelle partie de
            la requête Select doit être retournée. Par exemple, la chaîne "<code>from</code>" identifie la partie de
            l'objet Select qui stocke l'information concernant les tables dans la clause <code>FROM</code>, incluant les
            tables jointes.</para>

            <para>La classe Zend_Db_Select définit des constantes que vous pouvez utiliser pour les parties de la
            requête SQL. Vous pouvez utiliser ces constantes ou des chaînes de caractères littérales.</para>

            <table id="zend.db.select.other.get-part.table">
                <title>Constantes utilisées par <code>getPart()</code> et <code>reset()</code></title>

                <tgroup cols="2">
                    <thead>
                        <row>
                            <entry>Constante</entry>

                            <entry>Chaîne correspondante</entry>
                        </row>
                    </thead>

                    <tbody>
                        <row>
                            <entry><classname>Zend_Db_Select::DISTINCT</classname></entry>

                            <entry><code>'distinct'</code></entry>
                        </row>

                        <row>
                            <entry><classname>Zend_Db_Select::FOR_UPDATE</classname></entry>

                            <entry><code>'forupdate'</code></entry>
                        </row>

                        <row>
                            <entry><classname>Zend_Db_Select::COLUMNS</classname></entry>

                            <entry><code>'columns'</code></entry>
                        </row>

                        <row>
                            <entry><classname>Zend_Db_Select::FROM</classname></entry>

                            <entry><code>'from'</code></entry>
                        </row>

                        <row>
                            <entry><classname>Zend_Db_Select::WHERE</classname></entry>

                            <entry><code>'where'</code></entry>
                        </row>

                        <row>
                            <entry><classname>Zend_Db_Select::GROUP</classname></entry>

                            <entry><code>'group'</code></entry>
                        </row>

                        <row>
                            <entry><classname>Zend_Db_Select::HAVING</classname></entry>

                            <entry><code>'having'</code></entry>
                        </row>

                        <row>
                            <entry><classname>Zend_Db_Select::ORDER</classname></entry>

                            <entry><code>'order'</code></entry>
                        </row>

                        <row>
                            <entry><classname>Zend_Db_Select::LIMIT_COUNT</classname></entry>

                            <entry><code>'limitcount'</code></entry>
                        </row>

                        <row>
                            <entry><classname>Zend_Db_Select::LIMIT_OFFSET</classname></entry>

                            <entry><code>'limitoffset'</code></entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>

            <example id="zend.db.select.other.get-part.example">
                <title>Exemple d'utilisation de la méthode <code>getPart()</code></title>

                <programlisting role="php"><![CDATA[
$select = $db->select()
             ->from('produits')
             ->order('produit_id');

// Vous pouvez spécifier une chaîne littérale
$orderData = $select->getPart( 'order' );

// Vous pouvez utiliser une constante
$orderData = $select->getPart( Zend_Db_Select::ORDER );

// La valeur retournée peut être une structure tableau, pas une chaîne.
// Chaque partie a une structure différente
print_r( $orderData );
]]></programlisting>
            </example>
        </sect3>

        <sect3 id="zend.db.select.other.reset">
            <title>Effacer des parties de l'objet Select</title>

            <para>La méthode <code>reset()</code> vous permet de vider une partie spécifique de la requête SQL, ou
            toutes les parties si vous omettez l'argument.</para>

            <para>L'argument unique est facultatif. Vous pouvez spécifier la partie de la requête à effacer, en
            utilisant les mêmes chaînes que vous utilisez en tant qu'argument de la méthode <code>getPart()</code>. La
            partie de la requête que vous spécifiez est initialisée à l'état par défaut.</para>

            <para>Si vous omettez le paramètre, <code>reset()</code> initialise toutes les parties de la requête à leurs
            valeurs par défaut. Ceci rend l'objet Zend_Db_Select équivalent à un nouvel objet, comme si vous l'aviez
            tout juste instancié.</para>

            <example id="zend.db.select.other.reset.example">
                <title>Exemple d'utilisation de la méthode <code>reset()</code></title>

                <programlisting role="php"><![CDATA[
// Construire cette requête :
//   SELECT p.*
//   FROM "produits" AS p
//   ORDER BY "produit_nom"

$select = $db->select()
             ->from(array('p' => 'produits')
             ->order('produit_nom');

// Changer la condition d'ordre avec une colonne différente :
//   SELECT p.*
//   FROM "produits" AS p
//   ORDER BY "produit_id"

// Vider la partie afin de la redéfinir
$select->reset( Zend_Db_Select::ORDER );

// Et spécifier une colonne différente
$select->order('produit_id');

// Vider toutes les parties de la requête
$select->reset();
]]></programlisting>
            </example>
        </sect3>
    </sect2>
</sect1>