<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.28 $ -->

<!-- 
    If anyone from the translator group has problems with the 
    new version of this file, and finds too difficult the sync his
    translation with this doc, please mail me: gerzson@php.net 
-->

 <reference id="ref.dbx">
  <title>dbx functions</title>
  <titleabbrev>dbx</titleabbrev>
  <partintro>
   <simpara>
    The dbx module is a database abstraction layer (db 'X', where 'X'
    is a supported database). The dbx functions allow you to access
    all supported databases using a single calling convention.  In
    order to have these functions available, you must compile PHP with
    dbx support by using the <link linkend="install.configure.enable-dbx">
    <option role="configure">--enable-dbx</option></link> option and all options for
    the databases that will be used, e.g. for MySQL you must also
    specify <link linkend="install.configure.with-mysql">
    <option role="install.configure.with-mysql">--with-mysql</option></link>. 
    The dbx-functions themselves do not interface directly to the
    databases, but interface to the modules that are used to support
    these databases.  To be able to use a database with the
    dbx-module, the module must be either linked or loaded into PHP,
    and the database module must be supported by the
    dbx-module. Currently, MySQL, PostgreSQL, Microsoft SQL Server,
    FrontBase, Sybase-CT and ODBC are supported, but others will follow 
    (soon, I hope :-).
   </simpara>
   <simpara>
    Documentation for adding additional database support to dbx can be
    found at <ulink url="&url.dbx.docs;">&url.dbx.docs;</ulink>.
   </simpara>
  </partintro>
 
  <refentry id="function.dbx-close">
   <refnamediv>
    <refname>dbx_close</refname>
    <refpurpose>Close an open connection/database</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>dbx_close</methodname>
      <methodparam><type>object</type><parameter>link_identifier</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns &true; on success,
     &false; on error.
    </para>
    <example>
     <title><function>dbx_close</function> example</title>
     <programlisting role="php">
<![CDATA[
<?php
$link = dbx_connect(DBX_MYSQL, "localhost", "db", "username", "password")
    or die ("Could not connect");

print("Connected successfully");
dbx_close($link);
?>
]]>
     </programlisting>
    </example>
    <note>
     <para>
      Always refer to the module-specific documentation as well.
     </para>
    </note>
    <para>
     See also: <function>dbx_connect</function>.
    </para>
   </refsect1>
  </refentry>
 
  <refentry id="function.dbx-connect">
   <refnamediv>
    <refname>dbx_connect</refname>
    <refpurpose>Open a connection/database</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>object</type><methodname>dbx_connect</methodname>
      <methodparam><type>mixed</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>
    <simpara>
     <function>dbx_connect</function> returns an object on success, &false; on
     error. If a connection has been made but the database could not be 
     selected, the connection is closed and &false; is returned. 
     The <parameter>persistent</parameter> parameter can be set to 
     <constant>DBX_PERSISTENT</constant>, if so, a persistent connection will be
     created.
    </simpara>
    <simpara>
     The <parameter>module</parameter> parameter can be either a string or a
     constant, though the latter form is preferred. The possible values are 
     given below, but keep in mind that they only work if the module is 
     actually loaded.
    </simpara>
    <para>
     <itemizedlist>
      <listitem>
       <simpara>
        <constant>DBX_MYSQL</constant> or "mysql"
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <constant>DBX_ODBC</constant> or "odbc"
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <constant>DBX_PGSQL</constant> or "pgsql"
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <constant>DBX_MSSQL</constant> or "mssql"
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <constant>DBX_FBSQL</constant> or "fbsql" (available from PHP 4.1.0)
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <constant>DBX_SYBASECT</constant> or "sybase_ct" (CVS only)
       </simpara>
      </listitem>
     </itemizedlist>
    </para>
    <para>
     The <parameter>host</parameter>, <parameter>database</parameter>, 
     <parameter>username</parameter> and <parameter>password</parameter> 
     parameters are expected, but not always used depending on the connect
     functions for the abstracted module.
    </para>
    <para>
     The returned <varname>object</varname> has three properties:
     <variablelist>
      <varlistentry>
       <term>
        <property>database</property>
       </term>
       <listitem>
        <simpara>
         It is the name of the currently selected database. 
        </simpara>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>
        <property>handle</property>
       </term>
       <listitem>
        <para>
         It is a valid handle for the connected database, and as such it can be
         used in module-specific functions (if required).
         <informalexample>
          <programlisting role="php">
<![CDATA[
$link = dbx_connect (DBX_MYSQL, "localhost", "db", "username", "password");
mysql_close ($link->handle); // dbx_close($link) would be better here
]]>
          </programlisting>
         </informalexample>
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>
        <property>module</property>
       </term>
       <listitem>
        <simpara>
         It is used internally by dbx only, and is actually the module number
         mentioned above.
        </simpara>
       </listitem>
      </varlistentry>
     </variablelist>
    </para>
    <para>
     <example>
      <title><function>dbx_connect</function> example</title>
      <programlisting role="php">
<![CDATA[
<?php
$link = dbx_connect (DBX_ODBC, "", "db", "username", "password", DBX_PERSISTENT)
    or die ("Could not connect");

print ("Connected successfully");
dbx_close ($link);
?>
]]>
      </programlisting>
     </example>
     <note>
      <para>
       Always refer to the module-specific documentation as well.
      </para>
     </note>
    </para>
    <para>
     See also: <function>dbx_close</function>.
    </para>
   </refsect1>
  </refentry>
 
  <refentry id="function.dbx-error">
   <refnamediv>
    <refname>dbx_error</refname>
    <refpurpose>
     Report the error message of the latest function call in the
     module (not just in the connection)
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>dbx_error</methodname>
      <methodparam><type>object</type><parameter>link_identifier</parameter></methodparam>
     </methodsynopsis>
    <simpara>
     <function>dbx_error</function> returns a string containing the error 
     message from the last function call of the abstracted module (e.g. 
     mysql module). If there are multiple connections in the same module,
     just the last error is given. If there are connections on different 
     modules, the latest error is returned for the module specified by the 
     <parameter>link_identifier</parameter> parameter.  
    </simpara>
    <example>
     <title><function>dbx_error</function> example</title>
     <programlisting role="php">
<![CDATA[
<?php
$link   = dbx_connect(DBX_MYSQL, "localhost", "db", "username", "password")
    or die ("Could not connect");

$result = dbx_query($link, "select id from non_existing_table");
if ( $result == 0 ) {
    echo dbx_error ($link);
}
dbx_close ($link);
?>
]]>
     </programlisting>
    </example>
    <note>
     <para>
      Always refer to the module-specific documentation as well.
     </para>
     <para>
      The error message for Microsoft SQL Server is actually the result
      of the <function>mssql_get_last_message</function> function.
     </para>
    </note>
   </refsect1>
  </refentry>
 
  <refentry id="function.dbx-query">
   <refnamediv>
    <refname>dbx_query</refname>
    <refpurpose>Send a query and fetch all results (if any)</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>object</type><methodname>dbx_query</methodname>
      <methodparam><type>object</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>
    <simpara>
     <function>dbx_query</function> returns an object or <literal>1</literal> 
     on success, and <literal>0</literal> on failure. The result object is 
     returned only if the query given in <parameter>sql_statement</parameter>
     produces a result set. 
    </simpara>
    <example>
     <title>How to handle the returned value</title>
     <programlisting role="php">
<![CDATA[
<?php
$link   = dbx_connect(DBX_ODBC, "", "db", "username", "password")
    or die("Could not connect");

$result = dbx_query($link, 'SELECT id, parentid, description FROM table');

if ( is_object($result) ) {
    // ... do some stuff here, see detailed examples below ...
    // first, print out field names and types 
    // then, draw a table filled with the returned field values
}
else if ( $result == 1 ) {
    echo("Query executed successfully, but no result set returned");
}
else {
    exit("Query failed");
}

dbx_close($link);
?>
]]>
     </programlisting>
    </example>

    <para>
     The <parameter>flags</parameter> parameter is used to control the amount of
     information that is returned. It may be any combination of the following 
     constants with the bitwise OR operator (|):
     <variablelist>
      <varlistentry>
       <term>
        <constant>DBX_RESULT_INDEX</constant>
       </term>
       <listitem>
        <simpara>
         It is <emphasis>always</emphasis> set, that is, the returned object 
         has a <property>data</property> property which is a 2 dimensional
         array indexed numerically. For example, in the expression 
         <literal>data[2][3]</literal> <literal>2</literal> stands for the row
         (or record) number and <literal>3</literal> stands for the column 
         (or field) number. The first row and column are indexed at 0.
        </simpara>
        <simpara>
         If <constant>DBX_RESULT_ASSOC</constant> is also specified, the 
         returning object contains the information related to 
         <constant>DBX_RESULT_INFO</constant> too, even if it was not specified. 
        </simpara>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>
        <constant>DBX_RESULT_INFO</constant>
       </term>
       <listitem>
        <simpara>
         It provides info about columns, such as field names and field types.
        </simpara>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>
        <constant>DBX_RESULT_ASSOC</constant>
       </term>
       <listitem>
        <simpara>
         It effects that the field values can be accessed with the respective 
         column names used as keys to the returned object's 
         <property>data</property> property.
        </simpara>
        <simpara>
         Associated results are actually references to the numerically indexed 
         data, so modifying <literal>data[0][0]</literal> causes that
         <literal>data[0]['field_name_for_first_column']</literal> is modified
         as well.
        </simpara>
       </listitem>
      </varlistentry>
     </variablelist>
     Note that <constant>DBX_RESULT_INDEX</constant> is always used, regardless 
     of the actual value of <parameter>flags</parameter> parameter. This means 
     that the following combinations is effective only:
     <itemizedlist>
      <listitem>
       <simpara>
        <constant>DBX_RESULT_INDEX</constant>
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <constant>DBX_RESULT_INDEX</constant> |
        <constant>DBX_RESULT_INFO</constant>
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <constant>DBX_RESULT_INDEX</constant> |
        <constant>DBX_RESULT_INFO</constant> |
        <constant>DBX_RESULT_ASSOC</constant> - this is the default, if 
        <parameter>flags</parameter> is not specified.
       </simpara>
      </listitem>
     </itemizedlist>
    </para>
    <para>
     The returing <varname>object</varname> has four or five
     properties depending on <parameter>flags</parameter>:
     <variablelist>
      <varlistentry>
       <term>
        <property>handle</property>
       </term>
       <listitem>
        <para>
         It is a valid handle for the connected database, and as such it can be
         used in module specific functions (if required).
         <informalexample role="php">
          <programlisting>
<![CDATA[
$result = dbx_query ($link, "SELECT id FROM table");
mysql_field_len ($result->handle, 0);
]]>
          </programlisting>
         </informalexample>
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>
        <property>cols</property> and <property>rows</property>
       </term>
       <listitem>
        <para>
         These contain the number of columns (or fields) and rows (or records)
         respectively.
         <informalexample>
          <programlisting role="php">
<![CDATA[
$result = dbx_query ($link, 'SELECT id FROM table');
echo $result->rows; // number of records
echo $result->cols; // number of fields 
]]>
          </programlisting>
         </informalexample>
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>
        <property>info</property> (optional)
       </term>
       <listitem>
        <simpara>
         It is returned only if either <constant>DBX_RESULT_INFO</constant> or
         <constant>DBX_RESULT_ASSOC</constant> is specified in the
         <parameter>flags</parameter> parameter. It is a 2 dimensional array,
         that has two named rows (<literal>name</literal> and 
         <literal>type</literal>) to retrieve column information.
        </simpara>
        <example>
         <title>lists each field's name and type</title>
         <programlisting role="php">
<![CDATA[
$result = dbx_query ($link, 'SELECT id FROM table',
                     DBX_RESULT_INDEX | DBX_RESULT_INFO);

for ($i = 0; $i < $result->cols; $i++ ) {
    echo $result->info['name'][$i] . "\n";
    echo $result->info['type'][$i] . "\n";  
}
]]>
         </programlisting>
        </example>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>
        <property>data</property>
       </term>
       <listitem>
        <simpara>
         This property contains the actual resulting data, possibly associated 
         with column names as well depending on <parameter>flags</parameter>.
         If <constant>DBX_RESULT_ASSOC</constant> is set, it is possible to use
         <literal>$result->data[2]["field_name"]</literal>.
        </simpara>
        <example>
         <title>outputs the content of data property into HTML table</title>
         <programlisting role="php">
<![CDATA[
$result = dbx_query ($link, 'SELECT id, parentid, description FROM table');

echo "<table>\n";
foreach ( $result->data as $row ) {
    echo "<tr>\n";
    foreach ( $row as $field ) {
        echo "<td>$field</td>";
    }
    echo "</tr>\n";
}
echo "</table>\n";
]]>
         </programlisting>
        </example>
       </listitem>
      </varlistentry>
     </variablelist>
    </para>
    <note>
     <para>
      Always refer to the module-specific documentation as well.
     </para>
    </note>
    <para>
     See also: <function>dbx_connect</function>.
    </para>
   </refsect1>
  </refentry>
  
  <refentry id="function.dbx-sort">
   <refnamediv>
    <refname>dbx_sort</refname>
    <refpurpose>
     Sort a result from a dbx_query by a custom sort function
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>dbx_sort</methodname>
      <methodparam><type>object</type><parameter>result</parameter></methodparam>
      <methodparam><type>string</type><parameter>user_compare_function</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns &true; on success,
     &false; on error.
    </para>
    <note>
     <simpara>
      It is always better to use <literal>ORDER BY</literal>
      <literal>SQL</literal> clause instead of <function>dbx_sort</function>,
      if possible.
     </simpara>
    </note>
    <example>
     <title><function>dbx_sort</function> example</title>
     <programlisting role="php">
<![CDATA[
<?php
function user_re_order ($a, $b) {
    $rv = dbx_compare ($a, $b, "parentid", DBX_CMP_DESC);
    if ( !$rv ) {
        $rv = dbx_compare ($a, $b, "id", DBX_CMP_NUMBER);
    }
    return $rv;
}

$link   = dbx_connect (DBX_ODBC, "", "db", "username", "password")
    or die ("Could not connect");

$result = dbx_query ($link, "SELECT id, parentid, description FROM tbl ORDER BY id");
    // data in $result is now ordered by id

dbx_sort ($result, "user_re_order");
    // data in $result is now ordered by parentid (descending), then by id

dbx_close ($link);
?>
]]>
     </programlisting>
    </example>
    <para>
     See also <function>dbx_compare</function>.
    </para>
   </refsect1>
  </refentry>
 
  <refentry id="function.dbx-compare">
   <refnamediv>
    <refname>dbx_compare</refname>
    <refpurpose>Compare two rows for sorting purposes</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>dbx_compare</methodname>
      <methodparam><type>array</type><parameter>row_a</parameter></methodparam>
      <methodparam><type>array</type><parameter>row_b</parameter></methodparam>
      <methodparam><type>string</type><parameter>column_key</parameter></methodparam>
      <methodparam choice="opt"><type>int</type><parameter>flags</parameter></methodparam>
     </methodsynopsis>
    <para>
     <function>dbx_compare</function> returns <literal>0</literal> if the 
     <literal>row_a[$column_key]</literal> is equal to 
     <literal>row_b[$column_key]</literal>, and <literal>1</literal> or 
     <literal>-1</literal> if the former is greater or is smaller than 
     the latter one, respectively, or vice versa if the 
     <parameter>flag</parameter> is set to <constant>DBX_CMP_DESC</constant>.
     <function>dbx_compare</function> is a helper function for 
     <function>dbx_sort</function> to ease the make and use of the custom 
     sorting function.
    </para>
    <para>
     The <parameter>flags</parameter> can be set to specify comparison
     direction: 
     <itemizedlist>
      <listitem>
       <simpara>
        <constant>DBX_CMP_ASC</constant> - ascending order
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <constant>DBX_CMP_DESC</constant> - descending order
       </simpara>
      </listitem>
     </itemizedlist>
     and the preferred comparison type:
     <itemizedlist>
      <listitem>
       <simpara>
        <constant>DBX_CMP_NATIVE</constant> - no type conversion
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <constant>DBX_CMP_TEXT</constant> - compare items as strings
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <constant>DBX_CMP_NUMBER</constant> - compare items numerically
       </simpara>
      </listitem>
     </itemizedlist>
     One of the direction and one of the type constant can be combined with 
     bitwise OR operator (|). The default value for the 
     <parameter>flags</parameter> parameter is <constant>DBX_CMP_ASC</constant>
     | <constant>DBX_CMP_NATIVE</constant>.
    </para>
    <example>
     <title><function>dbx_compare</function> example</title>
     <programlisting role="php">
<![CDATA[
<?php
function user_re_order ($a, $b) {
    $rv = dbx_compare ($a, $b, "parentid", DBX_CMP_DESC);
    if ( !$rv ) {
        $rv = dbx_compare ($a, $b, "id", DBX_CMP_NUMBER);
    }
    return $rv;
}

$link   = dbx_connect (DBX_ODBC, "", "db", "username", "password")
    or die ("Could not connect");

$result = dbx_query ($link, "SELECT id, parentid, description FROM table ORDER BY id");
    // data in $result is now ordered by id

dbx_sort ($result, "user_re_order");
    // date in $result is now ordered by parentid (descending), then by id

dbx_close ($link);
?>
]]>
     </programlisting>
    </example>
    <para>
     See also <function>dbx_sort</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:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->