<?xml version="1.0" encoding="iso-8859-1"?>
<!-- EN-Revision: 1.28 Maintainer: tom Status: ready -->

 <reference id="ref.dbx">
  <title>dbx Funktionen</title>
  <titleabbrev>dbx</titleabbrev>
  <partintro>
   <simpara>
    Das dbx Modul ist eine Datenbank-Abstraktionsschicht (db 'X', wobei 'X'
    eine untersttzte Datenbank ist). Die dbx Funktionen ermglichen Ihnen
    den Zugriff auf alle untersttzten Datenbanken mit einer einzigen
    Aufrufkonvention. Diese Funktionen sind nur verfgbar, wenn PHP mit der
    Option <link linkend="install.configure.enable-dbx">
    <option role="configure">--enable-dbx</option></link>, sowie allen
    Optionen fr die zu benutzenden Datenbanken (z.B. fr MySQL<link
    linkend="install.configure.with-mysql">
    <option role="install.configure.with-mysql">--with-mysql</option></link>)
    konfiguriert und kompiliert wurde. Die dbx Funktionen stellen selbst
    keinen direkten Kontakt zu den Datenbanken her, sondern benutzen dafr
    jene Module, welche die jeweilige Datenbank untersttzen. Um eine
    Datenbank mit dem dbx Modul benutzen zu knnen, muss das Modul in PHP
    gelinkt oder geladen sein, und das Datenbankmodul muss vom dbx-Modul
    untersttzt werden. Derzeit werden MySQL, PostgreSQL, Microsoft SQL
    Server, FrontBase, Sybase-CT und ODBC untersttzt, und weitere werden
    (hoffentlich bald :-) folgen.
   </simpara>
   <simpara>
    Eine Dokumentation, wie dbx weitere Datenbankuntersttzung hinzugefgt
    werden kann, finden Sie unter <ulink
    url="&url.dbx.docs;">&url.dbx.docs;</ulink>.
   </simpara>
  </partintro>
 
  <refentry id="function.dbx-close">
   <refnamediv>
    <refname>dbx_close</refname>
    <refpurpose>Schliet eine offene Verbindung/Datenbank</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>bool</type><methodname>dbx_close</methodname>
      <methodparam><type>object</type><parameter>link_identifier</parameter></methodparam>
     </methodsynopsis>
    <para>
     Gibt bei Erfolg &true;, oder im Fehlerfall &false; zurck.
    </para>
    <example>
     <title><function>dbx_close</function></title>
     <programlisting role="php">
<![CDATA[
<?php
$link = dbx_connect(DBX_MYSQL, "localhost", "db", "username", "password")
    or die ("Fehler beim Verbinden");

print("Verbindung hergestellt");
dbx_close($link);
?>
]]>
     </programlisting>
    </example>
    <note>
     <para>
      Konsultieren Sie bitte auch die modulspezifische Dokumentation.
     </para>
    </note>
    <para>
     Siehe auch <function>dbx_connect</function>.
    </para>
   </refsect1>
  </refentry>
 
  <refentry id="function.dbx-connect">
   <refnamediv>
    <refname>dbx_connect</refname>
    <refpurpose>ffnet eine Verbindung/Datenbank</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</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> gibt bei Erfolg ein Objekt, oder
     im Fehlerfall &false; zurck. Konnte eine Verbindung hergestellt,
     jedoch keine Datenbank ausgewhlt werden, wird die Verbindung wieder
     geschlossen, und &false; zurckgegeben. Wird der Parameter
     <parameter>persistent</parameter> auf
     <constant>DBX_PERSISTENT</constant> gesetzt, wird eine persistente
     Verbindung hergestellt.
    </simpara>
    <simpara>
     Der Parameter <parameter>module</parameter> kann entweder einen String,
     oder eine Konstante enthalten, auch wenn letzteres vorgezogen wird.
     Die mglichen Werte sind nachstehend aufgelistet, aber bedenken Sie
     bitte, dass diese nur funktionieren, wenn das Modul gerade geladen ist.
    </simpara>
    <para>
     <itemizedlist>
      <listitem>
       <simpara>
        <constant>DBX_MYSQL</constant> oder "mysql"
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <constant>DBX_ODBC</constant> oder "odbc"
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <constant>DBX_PGSQL</constant> oder "pgsql"
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <constant>DBX_MSSQL</constant> oder "mssql"
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <constant>DBX_FBSQL</constant> oder "fbsql" (seit PHP 4.1.0 verfgbar)
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <constant>DBX_SYBASECT</constant> oder "sybase_ct" (nur CVS)
       </simpara>
      </listitem>
     </itemizedlist>
    </para>
    <para>
     Die Parameter <parameter>host</parameter>,
     <parameter>database</parameter>, <parameter>username</parameter>
     und <parameter>password</parameter> werden erwartet, werden aber
     abhngig von den Verbindungsfunktionen fr das abstrahierte Modul
     nicht immer verwendet.
    </para>
    <para>
     Das zurckgegebene <varname>Objekt</varname> hat drei Eigenschaften:
     <variablelist>
      <varlistentry>
       <term>
        <property>database</property>
       </term>
       <listitem>
        <simpara>
         Das ist der Name der derzeit ausgewhlten Datenbank.
        </simpara>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>
        <property>handle</property>
       </term>
       <listitem>
        <para>
         Das ist ein gltiges Handle fr die verbundene Datenbank, und
         als solche kann es wenn ntig auch in modulspezifischen Funktionen
         verwendet werden.
         <informalexample>
          <programlisting role="php">
<![CDATA[
$link = dbx_connect (DBX_MYSQL, "localhost", "db", "username", "password");
mysql_close ($link->handle); // dbx_close($link) wre hier besser
]]>
          </programlisting>
         </informalexample>
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>
        <property>module</property>
       </term>
       <listitem>
        <simpara>
         Dies ist die oben erwhnte Modulnummer, und wird nur dbx-intern
         verwendet.
        </simpara>
       </listitem>
      </varlistentry>
     </variablelist>
    </para>
    <para>
     <example>
      <title><function>dbx_connect</function></title>
      <programlisting role="php">
<![CDATA[
<?php
$link = dbx_connect (DBX_ODBC, "", "db", "username", "password", DBX_PERSISTENT)
    or die ("Fehler beim Verbinden");

print ("Verbindung hergestellt");
dbx_close ($link);
?>
]]>
      </programlisting>
     </example>
     <note>
      <para>
      Konsultieren Sie bitte auch die modulspezifische Dokumentation.
      </para>
     </note>
    </para>
    <para>
     Siehe auch <function>dbx_close</function>.
    </para>
   </refsect1>
  </refentry>
 
  <refentry id="function.dbx-error">
   <refnamediv>
    <refname>dbx_error</refname>
    <refpurpose>
     Liefert die Fehlermeldung des letzten Funktionsaufrufes in dem Modul
     (nicht nur in der Verbindung).
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</title>
     <methodsynopsis>
      <type>string</type><methodname>dbx_error</methodname>
      <methodparam><type>object</type><parameter>link_identifier</parameter></methodparam>
     </methodsynopsis>
    <simpara>
     <function>dbx_error</function> gibt eine Zeichenkette mit der
     Fehlermeldung des letzten Funktionsaufrufes von dem abstrahierten
     Modul (z.B. MySQL-Modul) zurck. Bestehen mehrere Verbindungen zu
     dem gleichen Modul, wird nur der letzte Fehler zurckgegeben.
     Bestehen Verbindungen zu verschiedenen Modulen, wird der letzte
     Fehler von dem im Parameter <parameter>link_identifier</parameter>
     angegebenen Modul zurckgegeben.
    </simpara>
    <example>
     <title><function>dbx_error</function></title>
     <programlisting role="php">
<![CDATA[
<?php
$link   = dbx_connect(DBX_MYSQL, "localhost", "db", "username", "password")
    or die ("Fehler beim Verbinden");

$result = dbx_query($link, "select id from non_existing_table");
if ( $result == 0 ) {
    echo dbx_error ($link);
}
dbx_close ($link);
?>
]]>
     </programlisting>
    </example>
    <note>
     <para>
      Konsultieren Sie bitte auch die modulspezifische Dokumentation.
     </para>
     <para>
      Die Fehlermeldung des Microsoft SQL Server ist brigens das Ergebnis
      der Funktion <function>mssql_get_last_message</function>.
     </para>
    </note>
   </refsect1>
  </refentry>
 
  <refentry id="function.dbx-query">
   <refnamediv>
    <refname>dbx_query</refname>
    <refpurpose>
     Sendet eine Abfrage und holt alle Ergebnisse (falls vorhanden)
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</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> gibt bei Erfolg ein Objekt oder
     <literal>1</literal> zurck, oder <literal>0</literal> im
     Fehlerfall. Das Objekt wird nur zurckgegeben, wenn die in
     <parameter>sql_statement</parameter> angegebene Abfrage eine
     Ergebnisliste liefert.
    </simpara>
    <example>
     <title>Wie mit dem gelieferten Wert umgegangen wird</title>
     <programlisting role="php">
<![CDATA[
<?php
$link   = dbx_connect(DBX_ODBC, "", "db", "username", "password")
    or die("Fehler beim Verbinden");

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

if ( is_object($result) ) {
    // ... tue hier irgendetwas, detaillierte Beispiele siehe unten ...
    // erst die Ausgabe der Feldnamen und Typen
    // dann die Ausgabe einer Tabelle mit den gelieferten Werten
}
else if ( $result == 1 ) {
    echo("Abfrage wurde erfolgreich ausgefhrt, jedoch keine Ergebnisse");
}
else {
    exit("Fehler bei Abfrage");
}

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

    <para>
     Der Parameter <parameter>flags</parameter> wird verwendet, um die Menge
     der zu liefernden Informationen zu steuern. Die folgenden Konstanten
     knnen mit dem Bit-Operator (|) beliebig kombiniert werden:
     <variablelist>
      <varlistentry>
       <term>
        <constant>DBX_RESULT_INDEX</constant>
       </term>
       <listitem>
        <simpara>
         Dieser Flag ist <emphasis>immer</emphasis> gesetzt, d.h. dass
         zurckgegebene Objekt hat eine Eigenschaft <property>data</property>,
         welche aus einem zweidimensionalen, numerisch indizierten Array
         besteht. Zum Beispiel steht in <literal>data[2][3]</literal> die
         <literal>2</literal> fr die Reihen- (bzw. Datensatz-) Nummer, und
         <literal>3</literal> steht fr die Spalten- (bzw. Feld- Nummer).
         Die erste Reihe und Spalte haben den Index 0.
        </simpara>
        <simpara>
         Ist <constant>DBX_RESULT_ASSOC</constant> ebenfalls angegeben,
         so enthlt das zurckgegebene Objekt auch Informationen im
         Zusammenhang mit <constant>DBX_RESULT_INFO</constant>, selbst
         wenn es nicht angegeben wurde.
        </simpara>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>
        <constant>DBX_RESULT_INFO</constant>
       </term>
       <listitem>
        <simpara>
         Liefert Informationen ber Spalten, wie Feldnamen und Feldtypen.
        </simpara>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>
        <constant>DBX_RESULT_ASSOC</constant>
       </term>
       <listitem>
        <simpara>
         Dies bewirkt, dass in der <property>data</property> Eigenschaft
         des zurckgegebenen Objektes auf die Werte eines Feldes mit den
         entsprechenden Spaltennamen als Schlssel zugegriffen werden kann.
        </simpara>
        <simpara>
         Assoziierte Ergebnisse sind eigentlich Referenzen zu den numerisch
         indizierten Daten, weshalb eine nderung von
         <literal>data[0][0]</literal> auch den Inhalt von
         <literal>data[0]['feldname_fr_erste_spalte']</literal> betrifft.
        </simpara>
       </listitem>
      </varlistentry>
     </variablelist>
     Beachten Sie, dass <constant>DBX_RESULT_INDEX</constant> unabhngig von
     dem aktuell verwendeten Wert des Parameters <parameter>flags</parameter>
     immer verwendet wird. Das heit, dass es effektiv nur die folgenden
     Kombinationen gibt:
     <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> - dies ist Standard, wenn 
        <parameter>flags</parameter> nicht angegeben ist.
       </simpara>
      </listitem>
     </itemizedlist>
    </para>
    <para>
     Das zurckgegebene Objekt hat abhngig von <parameter>flags</parameter>
     vier oder fnf Eigenschaften:
     <variablelist>
      <varlistentry>
       <term>
        <property>handle</property>
       </term>
       <listitem>
        <para>
         Das ein gltiges Handle fr die verbundene Datenbank, und als solche
         kann es (wenn ntig) auch in modulspezifischen Funktionen verwendet
         werden.
         <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> und <property>rows</property>
       </term>
       <listitem>
        <para>
         Diese enthalten die Anzahl der Spalten (oder Felder) bzw. Reihen
         (oder Datenstze).
         <informalexample>
          <programlisting role="php">
<![CDATA[
$result = dbx_query ($link, 'SELECT id FROM table');
echo $result->rows; // Anzahl der Datenstze
echo $result->cols; // Anzahl der Felder 
]]>
          </programlisting>
         </informalexample>
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term>
        <property>info</property> (optional)
       </term>
       <listitem>
        <simpara>
         Dies wird nur zurckgegeben, wenn im Parameter
         <parameter>flags</parameter> entweder
         <constant>DBX_RESULT_INFO</constant> oder
         <constant>DBX_RESULT_ASSOC</constant> spezifiziert sind.
         Es ist ein zweidimensionales Array mit zwei Reihen
         (<literal>name</literal> und <literal>type</literal>),
         welches die Spalteninformationen enthlt.
        </simpara>
        <example>
         <title>Auflistung von Name und Typ jedes Feldes</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>
         Diese Eigenschaft enthlt die aktuellen Ergebnisdaten, mglicherweise
         auch mit den Spaltennamen assoziiert, was jedoch vom Parameter
         <parameter>flags</parameter> abhngig ist. Wenn 
         <constant>DBX_RESULT_ASSOC</constant> gesetzt ist, knnen Sie
         <literal>$result->data[2]["feldname"]</literal> verwenden.
        </simpara>
        <example>
         <title>Ausgabe des Inhaltes der data Eigenschaft in eine HTML Tabelle</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>
      Konsultieren Sie bitte auch die modulspezifische Dokumentation.
     </para>
    </note>
    <para>
     Siehe auch <function>dbx_connect</function>.
    </para>
   </refsect1>
  </refentry>
  
  <refentry id="function.dbx-sort">
   <refnamediv>
    <refname>dbx_sort</refname>
    <refpurpose>
     Sortiert das Ergebnis einer dbx-Abfrage mittels einer Benutzerfunktion
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</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>
     Gibt bei Erfolg &true;, oder im Fehlerfall &false; zurck.
    </para>
    <note>
     <simpara>
      Wenn mglich ist es besser, die <literal>ORDER BY</literal>
      <literal>SQL</literal> Klausel anstatt von
      <function>dbx_sort</function> zu verwenden.
     </simpara>
    </note>
    <example>
     <title><function>dbx_sort</function></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 ("Fehler beim Verbinden");

$result = dbx_query ($link, "SELECT id, parentid, description FROM tbl ORDER BY id");
    // Die Daten in $result sind nun nach id geordnet

dbx_sort ($result, "user_re_order");
    // Die Daten in $result sind nun nach parentid (absteigend) geordnet,
    // dann nach id

dbx_close ($link);
?>
]]>
     </programlisting>
    </example>
    <para>
     Siehe auch <function>dbx_compare</function>.
    </para>
   </refsect1>
  </refentry>
 
  <refentry id="function.dbx-compare">
   <refnamediv>
    <refname>dbx_compare</refname>
    <refpurpose>Vergleicht zwei Reihen fr Sortierzwecke</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Beschreibung</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> gibt 0 zurck, wenn
     <literal>row_a[$column_key]</literal> gleich
     <literal>row_b[$column_key]</literal> ist. Ist der erste Wert
     grer oder kleiner als der zweite, wird <literal>1</literal>
     bzw. <literal>-1</literal> zurckgegeben (oder umgekehrt, wenn
     der Parameter <parameter>flag</parameter> auf
     <constant>DBX_CMP_DESC</constant> gesetzt ist). 
     <function>dbx_compare</function> ist eine Hilfsfunktion fr 
     <function>dbx_sort</function>, um das Erstellen bzw. Verwenden
     der Benutzerfunktion zu vereinfachen.
    </para>
    <para>
     Der Parameter <parameter>flags</parameter> spezifiziert die
     Vergleichsrichtung:
     <itemizedlist>
      <listitem>
       <simpara>
        <constant>DBX_CMP_ASC</constant> - aufsteigende Reihenfolge
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <constant>DBX_CMP_DESC</constant> - absteigende Reihenfolge
       </simpara>
      </listitem>
     </itemizedlist>
     und den bevorzugten Vergleichstyp:
     <itemizedlist>
      <listitem>
       <simpara>
        <constant>DBX_CMP_NATIVE</constant> - keine Typenkonvertierung
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <constant>DBX_CMP_TEXT</constant> - vergleicht die Werte als Strings
       </simpara>
      </listitem>
      <listitem>
       <simpara>
        <constant>DBX_CMP_NUMBER</constant> - vergleicht die Werte numerisch
       </simpara>
      </listitem>
     </itemizedlist>
     Eine der Vergleichs-, und eine der Typkonstanten knnen mit dem
     Bit-Operator OR (|) kombiniert werden. Die Standardwerte fr
     <parameter>flags</parameter> sind <constant>DBX_CMP_ASC</constant>
     | <constant>DBX_CMP_NATIVE</constant>.
    </para>
    <example>
     <title><function>dbx_compare</function></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 ("Fehler beim Verbinden");

$result = dbx_query ($link, "SELECT id, parentid, description FROM table ORDER BY id");
    // die Daten in $result sind nun nach id gereiht

dbx_sort ($result, "user_re_order");
    // die Daten in $result sind nun nach parentid (absteigend) gereiht,
    // und dann nach id

dbx_close ($link);
?>
]]>
     </programlisting>
    </example>
    <para>
     Siehe auch <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
-->