<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.7 $ -->
<reference id="ref.dbx">
  <title>dbx</title>
  <titleabbrev>dbx</titleabbrev>
  <partintro>
   &warn.experimental;
   <simpara>
    Le module dbx est un module d'abstraction de base de donn&eacute;es
    (db pour database (base de donn&eacute;es) et 'X' pour toutes les
    bases support&eacute;es). Les fonctions dbx vous permettent d'acc&eacute;der
    &agrave; toutes les bases support&eacute;es, avec la m&ecirc;me convention. Pour cela
    il vous faut avoir ces fonctions compil&eacute;es avec PHP (option
    de configuration <link linkend="install.configure.enable-dbx"><option role="configure">--enable-dbx</option></link>
    et toutes les bases que vous souhaitez utiliser. Par exemple, si
    vous voulez acc&eacute;der &agrave; MySQL depuis dbx, vous devez aussi configurer
    PHP avec
    <link linkend="install.configure.with-mysql"><option role="install.configure.with-mysql">--with-mysql</option></link>.
    Les fonctions dbx n'interface pas directement les bases de
    donn&eacute;es, mais utilise les modules de support de ces bases.
    Pour pouvoir utiliser une base avec le module dbx, il vous
    faut l'avoir configur&eacute; avec PHP, ou bien la charger
    dynamiquement. Actuellement les bases MySQL, PostgreSQL,
    Microsoft SQL server, FrontBase et ODBC sont support&eacute;es, mais
    d'autres suivront bient&ocirc;t (j'esp&egrave;re).
   </simpara>
   <simpara>
    La documentation compl&eacute;mentaire (ajout de nouvelles bases &agrave; dbx) est
    accessible &agrave; <ulink url="&url.dbx.docs;">&url.dbx.docs;</ulink>.
   </simpara>
  </partintro>
  <refentry id="function.dbx-close">
   <refnamediv>
    <refname>dbx_close</refname>
    <refpurpose>Ferme une connexion &agrave; une base</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>boolean</type><methodname>dbx_close</methodname>
      <methodparam><type>resource</type><parameter>link_identifier</parameter></methodparam>
     </methodsynopsis>
   &warn.experimental;
    <para>
     <function>dbx_close</function> retourne &true; en cas
     de succ&egrave;s, et &false; en cas d'erreur.
    </para>
    <example>
     <title>Exemple avec <function>dbx_close</function></title>
     <programlisting role="php">
&lt;?php
  $link = dbx_connect("mysql", "localhost", "base", "utilisateur", "mot de passe")
    or die ("Impossible de se connecter");
  print("Connexion r&eacute;ussie");
  dbx_close($link);
?&gt;
     </programlisting>
    </example>
    <note>
     <para>
      Reportez-vous aussi &agrave; la documentation de la base de donn&eacute;es que vous
      utilisez.
     </para>
    </note>
    <para>
     Voir aussi
     <function>dbx_connect</function>.
    </para>
   </refsect1>
  </refentry>
  <refentry id="function.dbx-connect">
   <refnamediv>
    <refname>dbx_connect</refname>
    <refpurpose>Ouvre une connexion &agrave; une base de donn&eacute;es</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>resource</type><methodname>dbx_connect</methodname>
      <methodparam><type>string</type><parameter>module</parameter></methodparam>
      <methodparam><type>string</type><parameter>host</parameter></methodparam>
      <methodparam><type>string</type><parameter>database</parameter></methodparam>
      <methodparam><type>string</type><parameter>username</parameter></methodparam>
      <methodparam><type>string</type><parameter>password</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>persistent</parameter></methodparam>
     </methodsynopsis>
   &warn.experimental;
    <para>
     <function>dbx_connect</function> retourne une resource dbx_link_object
     en cas de succ&egrave;s, &false; sinon. Si la connexion a
     put &ecirc;tre &eacute;tablie, mais que la base de donn&eacute;es n'a pas
     pu &ecirc;tre s&eacute;lectionn&eacute;e, la fonction retournera quand
     m&ecirc;me une ressource.
     Le param&egrave;tre <parameter>persistent</parameter> peut prendre la
     valeur DBX_PERSISTENT, pour cr&eacute;er une connexion persitante.
    </para>
    <para>
     Le param&egrave;tre <parameter>module</parameter> peut &ecirc;tre soit une
     cha&icirc;ne, soit une constante. Les valeurs possibles de
     <parameter>module</parameter> sont list&eacute;es ci-dessous (n'oubliez pas
     que cela fonctionnera que si le module associ&eacute; est charg&eacute;):
    </para>
    <para>
     <itemizedlist>
      <listitem>
       <simpara>
module DBX_MYSQL : "mysql"
       </simpara>
      </listitem>
      <listitem>
       <simpara>
module DBX_ODBC : "odbc"
       </simpara>
      </listitem>
      <listitem>
       <simpara>
module DBX_PGSQL : "pgsql"
       </simpara>
      </listitem>
      <listitem>
       <simpara>
module DBX_MSSQL : "mssql"
       </simpara>
      </listitem>
      <listitem>
       <simpara>
module DBX_FBSQL : "fbsql" (CVS uniquement)
       </simpara>
      </listitem>
     </itemizedlist>
    </para>
    <para>
     Le support de pgsql &eacute;tait au stade exp&eacute;rimental jusqu'en avril 2001, et vous devez
     compiler vous-m&ecirc;me le module pgsql apr&egrave;s avoir modifi&eacute; un
     des fichiers sources. Sinon, vous aurez une alerte affich&eacute;e
     &agrave; chaque requ&ecirc;te.
    </para>
    <para>
     La ressource dbx_link_object a trois membres : 'handle', 'module' et
     'database'.  Le membre 'database' contient le nom de la base de donn&eacute;es
     actuellement s&eacute;lectionn&eacute;e. Le membre 'module' est &agrave; usage
     interne &agrave; dbx, et contient le num&eacute;ro de module sus-cit&eacute;. Le membre
     'handle' est une ressource valide de connexion &agrave; la base de donn&eacute;es,
     et peut &ecirc;tre utilis&eacute; en tant que tel dans les autres fonctions
     sp&eacute;cifiques &agrave; cette base de donn&eacute;es.
    </para>
    <para>
     Le message d'erreur pour Microsoft SQL server est actuellement
     le r&eacute;sultat direct de la fonction <function>mssql_get_last_message</function>.
      </para>
    <para>
     <informalexample>
      <programlisting role="php">
&lt;?php
$link = dbx_connect("mysql", "localhost", "base de donn&eacute;es", "utilisateur", "mot de passe");
mysql_close($link->handle);
// dbx_close($link) est beaucoup plus adapt&eacute; ici
?&gt;
      </programlisting>
     </informalexample>
    </para>
    <para>
     Les param&egrave;tres <parameter>host</parameter>, <parameter>database</parameter>,
     <parameter>username</parameter> et <parameter>password</parameter> sont
     attendus, mais ne sont pas toujours utiles, suivant la fonction de connexion
     de la base de donn&eacute;es utilis&eacute;e.
    </para>
    <para>
     <example>
      <title>Exemple avec <function>dbx_connect</function></title>
      <programlisting role="php">
&lt;?php
$link = dbx_connect("odbc", "", "base de donn&eacute;es", "utilisateur", "mot de passe", DBX_PERSISTENT)
    or die ("Impossible de se connecter");
print ("Connexion r&eacute;ussie");
dbx_close($link);
?&gt;
      </programlisting>
     </example>
     <note>
      <para>
       Reportez-vous aussi &agrave; la documentation de la base de donn&eacute;es que vous
       utilisez.
      </para>
     </note>
    </para>
    <para>
     Voir aussi
     <function>dbx_close</function>.
    </para>
   </refsect1>
  </refentry>
  <refentry id="function.dbx-error">
   <refnamediv>
    <refname>dbx_error</refname>
    <refpurpose>
     Rapporte le message d'erreur du dernier appel de fonction
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>dbx_error</methodname>
      <methodparam><type>resource</type><parameter>link_identifier</parameter></methodparam>
     </methodsynopsis>
   &warn.experimental;
    <para>
     <function>dbx_error</function> retourne une cha&icirc;ne contenant le
     message d'erreur du module s&eacute;lectionn&eacute;. S'il y a des connexions
     multiples sur le m&ecirc;me module, seule la derni&egrave;re erreur est fournie.
     S'il a des des connexions sur diff&eacute;rents modules, la derni&egrave;re
     erreur du module est retourn&eacute; (le module est alors repr&eacute;sent&eacute; par
     <parameter>link_identifier</parameter>). Notez que le module
     ODBC ne supporte pas encore cette fonction.
    </para>
    <example>
     <title>Exemple avec <function>dbx_error</function></title>
     <programlisting role="php">
&lt;?php
$link = dbx_connect("mysql", "localhost", "base de donn&eacute;es", "utilisateur", "mot de passe")
    or die ("Impossible de se connecter");
$result = dbx_query($link, "select id from nonexistingtbl");
if ($result==0) {
    echo dbx_error($link);
}
dbx_close($link);
?&gt;
     </programlisting>
    </example>
    <note>
     <para>
      Reportez-vous aussi &agrave; la documentation de la base de donn&eacute;es que vous
      utilisez.
     </para>
    </note>
   </refsect1>
  </refentry>
  <refentry id="function.dbx-query">
   <refnamediv>
    <refname>dbx_query</refname>
    <refpurpose>Envoie une requ&ecirc;te et lit tous les r&eacute;sultats</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>resource</type><methodname>dbx_query</methodname>
      <methodparam><type>resource</type><parameter>link_identifier</parameter></methodparam>
      <methodparam><type>string</type><parameter>sql_statement</parameter></methodparam>
      <methodparam choice="opt"><type>long</type><parameter>flags</parameter></methodparam>
     </methodsynopsis>
   &warn.experimental;
    <para>
     <function>dbx_query</function> retourne une ressource
     dbx_result_object ou 1 en cas de succ&egrave;s (un objet de r&eacute;sultat
     ne sera retourn&eacute; que pour les requ&ecirc;tes SQL qui retournent un
     r&eacute;sultat), ou 0 en cas d'erreur. Le param&egrave;tre
     <parameter>flags</parameter> sert &agrave; contr&ocirc;ler la quantit&eacute;
     d'informations retourn&eacute;e. Il peut &ecirc;tre n'importe quelle
     combinaisons par OR des constantes : DBX_RESULT_INFO,
     DBX_RESULT_INDEX, DBX_RESULT_ASSOC. DBX_RESULT_INFO fournit
     des informations sur les colonnes, comme les noms des champs
     et leur type. DBX_RESULT_INDEX retourne le r&eacute;sultat dans un
     tableau index&eacute; (par exemple, data[2][3], o&ugrave; 2 est le num&eacute;ro
     de ligne et 3 est le num&eacute;ro de colonne), dont la premi&egrave;re
     colonne est index&eacute;e &agrave; 0. DBX_RESULT_ASSOC associe les noms
     de colonnes avec leurs indices. Notez que DBX_RESULT_INDEX est
     toujours retourn&eacute;, ind&eacute;pendamment de la valeur de
     <parameter>flags</parameter>. Si DBX_RESULT_ASSOC est sp&eacute;cifi&eacute;,
     DBX_RESULT_INFO est aussi retourn&eacute;, m&ecirc;me s'il n'a pas &eacute;t&eacute;
     sp&eacute;cifi&eacute;. Ce qui signifie que les seules combinaisons envisageables
     sont
     DBX_RESULT_INDEX,
     DBX_RESULT_INDEX | DBX_RESULT_INFO et
     DBX_RESULT_INDEX | DBX_RESULT_INFO | DBX_RESULT_ASSOC. La derni&egrave;re
     combinaison est la valeur par d&eacute;faut de <parameter>flags</parameter>.
     Les r&eacute;sultats associ&eacute;s sont en fait des r&eacute;f&eacute;rences, ce qui fait que
     modifier <literal>data[0][0]</literal>, revient &agrave; modifier
     <literal>data[0]['fieldnameforfirstcolumn']</literal>.
    </para>
    <para>
     Un objet dbx_result_object a 5 membres (&eacute;ventuellement 4, suivants
     les valeurs de <parameter>flags</parameter>) : 'handle', 'cols', 'rows',
     'info' (optionnel) et 'data'. Handle est un identifiant de r&eacute;sultat,
     qui peut &ecirc;tre utilis&eacute; avec les fonctions sp&eacute;cifiques &agrave; son module.
     Par exemple :
    </para>
    <para>
     <informalexample role="php">
      <programlisting>
&lt;?php
$result = dbx_query($link, "SELECT id FROM tbl");
mysql_field_len($result->handle, 0);
?&gt;
      </programlisting>
     </informalexample>
    </para>
    <para>
     Les membres cols et rows contiennent les num&eacute;ros de colonne et de
     champs.
    </para>
    <para>
     <informalexample>
      <programlisting role="php">
&lt;?php
$result = dbx_query($link, "SELECT id FROM tbl");
echo "Taille du r&eacute;sultat: " . $result->rows . " x " . $result->cols . "&lt;br&gt;\n";
?&gt;
      </programlisting>
     </informalexample>
    </para>
    <para>
     Le membre info n'est retourn&eacute; que si DBX_RESULT_INFO et/ou
     DBX_RESULT_ASSOC sont sp&eacute;cifi&eacute; dans le param&egrave;tre <parameter>flags</parameter>.
     C'est un deuxi&egrave;me tableau, qui poss&egrave;de deux lignes ("name" and "type"),
     pour conna&icirc;tre les informations sur les colonnes.
    </para>
    <para>
     <informalexample>
      <programlisting role="php">
&lt;?php
$result = dbx_query($link, "SELECT id FROM tbl");
echo "Nom de la colonne : " . $result->info["name"][0] . "&lt;br&gt;\n";
echo "Type de la colonne: " . $result->info["type"][0] . "&lt;br&gt;\n";
?&gt;
      </programlisting>
     </informalexample>
    </para>
    <para>
     Le membre data contient les donn&eacute;es effectivement lues,
     &eacute;ventuellement associ&eacute;es &agrave; des noms de colonnes. Si
     DBX_RESULT_ASSOC est utilis&eacute;, il est possible d'utiliser
     <literal>$result->data[2]["fieldname"]</literal>.
    </para>
    <example>
     <title>Exemple avec <function>dbx_query</function></title>
     <programlisting role="php">
&lt;?php
$link = dbx_connect("odbc", "", "base de donn&eacute;es", "utilisateur", "mot de passe")
    or die ("Impossible de se connecter");
$result = dbx_query($link, "SELECT id, parentid, description FROM tbl");
if ($result==0) echo "La requ&ecirc;te a &eacute;chou&eacute;\n&lt;br&gt;";
elseif ($result==1) {
    echo "La requ&ecirc;te a r&eacute;ussie\n&lt;br&gt;";
} else {
    $rows=$result->rows;
    $cols=$result->cols;
    echo "&lt;p>table dimension: {$result->rows} x {$result->cols}&lt;br&gt;&lt;table border=1>\n";
    echo "&lt;tr>";
    for ($col=0; $col&lt;$cols; ++$col) {
        echo "&lt;td>-{$result->info["name"][$col]}-&lt;br&gt;-{$result->info["type"][$col]}-&lt;/td>";
    }
    echo "&lt;/tr>\n";
    for ($row=0; $row&lt;$rows; ++$row){
        echo "&lt;tr>";
        for ($col=0; $col&lt;$cols; ++$col) {
            echo "&lt;td>-{$result->data[$row][$col]}-&lt;/td>";
        }
        echo "&lt;/tr>\n";
    }
    echo "&lt;/table>&lt;p>\n";
    echo "table dimension: {$result->rows} x id, parentid, description&lt;br&gt;&lt;table border=1>\n";
    for ($row=0; $row&lt;$rows; ++$row) {
        echo "&lt;tr>";
        echo "&lt;td>-{$result->data[$row]["id"]}-&lt;/td>";
        echo "&lt;td>-{$result->data[$row]["parentid"]}-&lt;/td>";
        echo "&lt;td>-{$result->data[$row]["description"]}-&lt;/td>";
        echo "&lt;/tr>\n";
    }
    echo "&lt;/table>&lt;p>\n";
}
dbx_close($link);
?&gt;
     </programlisting>
    </example>
    <note>
     <para>
      Reportez-vous aussi &agrave; la documentation de la base de donn&eacute;es que vous
      utilisez.
     </para>
    </note>
    <para>
     Voir aussi
     <function>dbx_connect</function>.
    </para>
   </refsect1>
  </refentry>
  <refentry id="function.dbx-sort">
   <refnamediv>
    <refname>dbx_sort</refname>
    <refpurpose>
     Tri un r&eacute;sultat avec une fonction utilisateur
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>boolean</type><methodname>dbx_sort</methodname>
      <methodparam><type>dbx_result_object</type><parameter>result</parameter></methodparam>
      <methodparam><type>string</type><parameter>user_compare_function</parameter></methodparam>
     </methodsynopsis>
   &warn.experimental;
    <para>
     <function>dbx_sort</function> retourne &true;
     en cas de succ&egrave;s, et &false; sinon.
    </para>
    <example>
     <title>Exemple avec <function>dbx_sort</function></title>
     <programlisting role="php">
&lt;?php
function user_re_order ($a, $b) {
    $rv = dbx_cmp_desc($a, $b, "parentid");
    if (!$rv) $rv = dbx_cmp_asc($a, $b, "id");
    return $rv;
}
$link = dbx_connect("odbc", "", "base de donn&eacute;es", "utilisateur", "mot de passe")
    or die ("Impossible de se connecter");
$result = dbx_query($link, "SELECT id, parentid, description FROM tbl ORDER BY id");
echo "Les donn&eacute;es sont maintenant tri&eacute;es par id&lt;br&gt;";
dbx_sort($result, "user_re_order");
echo "Les donn&eacute;es sont maintenant tri&eacute;es par parentid d&eacute;croissant, puis par id&lt;br&gt;";
dbx_close($link);
?&gt;
     </programlisting>
    </example>
    <para>
     Voir aussi
     <function>dbx_cmp_asc</function> et
     <function>dbx_cmp_desc</function>.
    </para>
   </refsect1>
  </refentry>
  <refentry id="function.dbx-cmp-asc">
   <refnamediv>
    <refname>dbx_cmp_asc</refname>
    <refpurpose>Compare deux lignes pour tri croissant</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>dbx_cmp_asc</methodname>
      <methodparam><type>array</type><parameter>row_a</parameter></methodparam>
      <methodparam><type>array</type><parameter>row_b</parameter></methodparam>
      <methodparam><type>string</type><parameter>columnname_or_index</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>comparison_type</parameter></methodparam>
     </methodsynopsis>
   &warn.experimental;
    <para>
     <function>dbx_cmp_asc</function> retourne 0 si row_a[$columnname_or_index]
     est &eacute;gal &agrave; row_b[$columnname_or_index], 1 si elle est plus grande et
     -1 si elle est plus petite.
    </para>
    <para>
     Le param&egrave;tre <parameter>comparison_type</parameter> sert utiliser le mode
     num&eacute;rique pour les comparaisons (il faut alors lui passer <literal>DBX_CMP_NUMBER</literal>).
     Par d&eacute;faut, la comparaison est textuelle (c'est-&agrave;-dire que
     "<literal>20</literal>" est plus grand que "<literal>100</literal>").
    </para>
    <example>
     <title>Exemple avec <function>dbx_cmp_asc</function></title>
     <programlisting role="php">
&lt;?php
function user_re_order($a, $b) {
    $rv = dbx_cmp_desc($a, $b, "parentid");
    if (!$rv) {
        $rv = dbx_cmp_asc($a, $b, "id");
        return $rv;
    }
}
$link = dbx_connect("odbc", "", "base de donn&eacute;es", "utilisateur", "mot de passe")
    or die ("Impossible de se connecter");
$result = dbx_query($link, "SELECT id, parentid, description FROM tbl ORDER BY id");
echo "Les donn&eacute;es sont maintenant tri&eacute;es par id&lt;br&gt;";
dbx_sort($result, "user_re_order");
echo "Les donn&eacute;es sont maintenant tri&eacute;es par parentid d&eacute;croissant, puis par id&lt;br&gt;";
dbx_close($link);
?&gt;
     </programlisting>
    </example>
    <para>
     Voir aussi
     <function>dbx_sort</function> et
     <function>dbx_cmp_desc</function>.
    </para>
   </refsect1>
  </refentry>
  <refentry id="function.dbx-cmp-desc">
   <refnamediv>
    <refname>dbx_cmp_desc</refname>
    <refpurpose>Compare deux lignes pour tri d&eacute;croissant</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>dbx_cmp_desc</methodname>
      <methodparam><type>array</type><parameter>row_a</parameter></methodparam>
      <methodparam><type>array</type><parameter>row_b</parameter></methodparam>
      <methodparam><type>string</type><parameter>columnname_or_index</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>comparison_type</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>dbx_cmp_desc</function> retourne 0 si row_a[$columnname_or_index]
     est &eacute;gal &agrave; row_b[$columnname_or_index], 1 si elle est plus grande et
     -1 si elle est plus petite.
    </para>
    <para>
     Le param&egrave;tre <parameter>comparison_type</parameter> sert utiliser le mode
     num&eacute;rique pour les comparaisons (il faut alors lui passer <literal>DBX_CMP_NUMBER</literal>).
     Par d&eacute;faut, la comparaison est textuelle (c'est-&agrave;-dire que
     "<literal>20</literal>" est plus grand que "<literal>100</literal>").
    </para>
    <example>
     <title>Exemple avec <function>dbx_cmp_desc</function></title>
     <programlisting role="php">
&lt;?php
function user_re_order ($a, $b) {
    $rv = dbx_cmp_desc($a, $b, "parentid");
    if (!$rv) {
        $rv = dbx_cmp_asc($a, $b, "id");
        return $rv;
    }
}
$link = dbx_connect("odbc", "", "base de donn&eacute;es", "utilisateur", "mot de passe")
    or die ("Impossible de se connecter");
$result = dbx_query($link, "SELECT id, parentid, description FROM tbl ORDER BY id");
echo "Les donn&eacute;es sont maintenant tri&eacute;es par id&lt;br&gt;";
dbx_sort($result, "user_re_order");
echo "Les donn&eacute;es sont maintenant tri&eacute;es par parentid d&eacute;croissant, puis par id&lt;br&gt;";
dbx_close($link);
?&gt;
     </programlisting>
    </example>
    <para>
     Voir aussi
     <function>dbx_sort</function> et
     <function>dbx_cmp_asc</function>.
    </para>
   </refsect1>
  </refentry>
 </reference>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->