<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.18 $ -->
 <reference id="ref.dba">
  <title>Database (dbm-style) abstraction layer functions</title>
  <titleabbrev>dba</titleabbrev>

  <partintro>
   <para>
    These functions build the foundation for accessing Berkeley DB
    style databases.
   </para>
   <para>
    This is a general abstraction layer for several file-based databases.
    As such, functionality is limited to a common subset of features
    supported by modern databases such as
    <ulink url="&url.sleepycat;">Sleepycat Software's DB2</ulink>.
    (This is not to be confused with IBM's DB2 software, which is
    supported through the <link linkend="ref.odbc">ODBC functions</link>.)
   </para>
   <para>
    The behaviour of various aspects depends on the implementation of the
    underlying database. Functions such as <function>dba_optimize</function>
    and <function>dba_sync</function> will do what they promise for one
    database and will do nothing for others.
   </para>
   <para>
    When invoking the <function>dba_open</function> or
    <function>dba_popen</function> functions, one of the following
    handler names must be supplied as an argument.  The actually
    available list of handlers is displayed by invoking
    <function>phpinfo</function>.  (To add support for any of the
    following handlers during the production of PHP, add the
    specified <literal>--with-XXXX</literal> configure switch to
    your PHP configure line.)
    <table>
     <title>List of DBA handlers</title>
     <tgroup cols="2">
      <thead>
       <row>
        <entry>Handler</entry>
        <entry>Notes</entry>
       </row>
      </thead>
      <tbody>
       <row>
         <entry><literal>dbm</literal></entry>
        <entry>
         Dbm is the oldest (original) type of Berkeley DB style
         databases. You should avoid it, if possible. We do not support
         the compatibility functions built into DB2 and gdbm, because
         they are only compatible on the source code level, but cannot
         handle the original dbm format.  (<literal>--with-dbm</literal>)
        </entry>
       </row>

       <row>
         <entry><literal>ndbm</literal></entry>
        <entry>
         Ndbm is a newer type and more flexible than dbm. It still has
         most of the arbitrary limits of dbm (therefore it is
         deprecated).  (<literal>--with-ndbm</literal>)
        </entry>
       </row>

       <row>
         <entry><literal>gdbm</literal></entry>
        <entry>
         Gdbm is the <ulink url="&url.gdbm;">GNU database
         manager</ulink>.  (<literal>--with-gdbm</literal>)
        </entry>
       </row>

       <row>
         <entry><literal>db2</literal></entry>
        <entry>
         DB2 is <ulink url="&url.sleepycat;">Sleepycat Software's
         DB2</ulink>. It is described as "a programmatic toolkit that
         provides high-performance built-in database support for both
         standalone and client/server applications."  (<literal>--with-db2</literal>)
        </entry>
       </row>

       <row>
         <entry><literal>db3</literal></entry>
        <entry>
         DB3 is <ulink url="&url.sleepycat;">Sleepycat Software's
         DB3</ulink>.  (<literal>--with-db3</literal>)
        </entry>
       </row>

       <row>
         <entry><literal>cdb</literal></entry>
        <entry>
         Cdb is "a fast, reliable, lightweight package for creating and
         reading constant databases." It is from the author of qmail and
         can be found <ulink url="&url.cdb;">here</ulink>. Since it is
         constant, we support only reading operations.  (<literal>--with-cdb</literal>)
        </entry>
       </row>

      </tbody>
     </tgroup>
    </table>
   </para>
   <para>
    <example>
     <title>DBA example</title>
     <programlisting role="php">
<![CDATA[
<?php

$id = dba_open ("/tmp/test.db", "n", "db2");

if (!$id) {
    echo "dba_open failed\n";
    exit;
}

dba_replace ("key", "This is an example!", $id);

if (dba_exists ("key", $id)) {
    echo dba_fetch ("key", $id);
    dba_delete ("key", $id);
}

dba_close ($id);
?>
]]>
     </programlisting>
    </example>
   </para>
   <para>
    DBA is binary safe and does not have any arbitrary limits.
    However, it inherits all limits set by the underlying
    database implementation.
   </para>
   <para>
    All file-based databases must provide a way of setting the file
    mode of a new created database, if that is possible at all. The
    file mode is commonly passed as the fourth argument to
    <function>dba_open</function> or <function>dba_popen</function>.
   </para>
   <para>
    You can access all entries of a database in a linear way by using the
    <function>dba_firstkey</function> and <function>dba_nextkey</function>
    functions. You may not change the database while traversing it.
   </para> 
   <para>
    <example>
     <title>Traversing a database</title>
     <programlisting role="php">
<![CDATA[
<?php

# ...open database...

$key = dba_firstkey ($id);

while ($key != false) {
    if (...) { # remember the key to perform some action later
        $handle_later[] = $key;
    }
    $key = dba_nextkey ($id);
}

for ($i = 0; $i < count($handle_later); $i++)
    dba_delete ($handle_later[$i], $id);

?>
]]>
     </programlisting>
    </example>
   </para>
  </partintro>

  <refentry id="function.dba-close">
   <refnamediv>
    <refname>dba_close</refname>
    <refpurpose>Close database</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>void <function>dba_close</function></funcdef>
      <paramdef>int <parameter>handle</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     <function>dba_close</function> closes the established database
     and frees all resources specified by
     <parameter>handle</parameter>.
    </para>
    <para>
     <parameter>handle</parameter> is a database handle returned by
     <function>dba_open</function>.
    </para>
    <para>
     <function>dba_close</function> does not return any value.
    </para>
    <para>
     See also: <function>dba_open</function> and
     <function>dba_popen</function>
    </para>     
   </refsect1>
  </refentry>

  <refentry id="function.dba-delete">
   <refnamediv>
    <refname>dba_delete</refname>
    <refpurpose>Delete entry specified by key</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>bool <function>dba_delete</function></funcdef>
      <paramdef>string <parameter>key</parameter></paramdef>
      <paramdef>int <parameter>handle</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     <function>dba_delete</function> deletes the entry specified by
     <parameter>key</parameter> from the database specified with
     <parameter>handle</parameter>.
    </para>
    <para>
     <parameter>key</parameter> is the key of the entry which is
     deleted.
    </para>
    <para>
     <parameter>handle</parameter> is a database handle returned by
     <function>dba_open</function>.
    </para>
    <para>
     <function>dba_delete</function> returns &true; or &false;, if the entry is
     deleted or not deleted, respectively.
    </para>
    <para>
     See also: <function>dba_exists</function>,
     <function>dba_fetch</function>, <function>dba_insert</function>,
     and <function>dba_replace</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.dba-exists">
   <refnamediv>
    <refname>dba_exists</refname>
    <refpurpose>Check whether key exists</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>bool <function>dba_exists</function></funcdef>
      <paramdef>string <parameter>key</parameter></paramdef>
      <paramdef>int <parameter>handle</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     <function>dba_exists</function> checks whether the specified
     <parameter>key</parameter> exists in the database specified by
     <parameter>handle</parameter>.
    </para>
    <para>
     <parameter>Key</parameter> is the key the check is performed for.
    </para>
    <para>
     <parameter>Handle</parameter> is a database handle returned by
     <function>dba_open</function>.
    </para>
    <para>
     <function>dba_exists</function> returns &true; or &false;, if the key is found
     or not found, respectively.
    </para>
    <para>
     See also: <function>dba_fetch</function>,
     <function>dba_delete</function>, <function>dba_insert</function>,
     and <function>dba_replace</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.dba-fetch">
   <refnamediv>
    <refname>dba_fetch</refname>
    <refpurpose>Fetch data specified by key</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>string <function>dba_fetch</function></funcdef>
      <paramdef>string <parameter>key</parameter></paramdef>
      <paramdef>int <parameter>handle</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     <function>dba_fetch</function> fetches the data specified by
     <parameter>key</parameter> from the database specified with
     <parameter>handle</parameter>.
    </para>
    <para>
     <parameter>Key</parameter> is the key the data is specified by.
    </para>
    <para>
     <parameter>Handle</parameter> is a database handle returned by
     <function>dba_open</function>.
    </para>

    <para>
     <function>dba_fetch</function> returns the associated string or &false;, if
     the key/data pair is found or not found, respectively.
    </para>
    <para>
     See also: <function>dba_exists</function>,
     <function>dba_delete</function>, <function>dba_insert</function>,
     and <function>dba_replace</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.dba-firstkey">
   <refnamediv>
    <refname>dba_firstkey</refname>
    <refpurpose>Fetch first key</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>string <function>dba_firstkey</function></funcdef>
      <paramdef>int <parameter>handle</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     <function>dba_firstkey</function> returns the first key of the
     database specified by <parameter>handle</parameter> and resets
     the internal key pointer. This permits a linear search through
     the whole database.
    </para>
    <para>
     <parameter>Handle</parameter> is a database handle returned by
     <function>dba_open</function>.
    </para>
    <para>
     <function>dba_firstkey</function> returns the key or &false;
     depending on whether it succeeds or fails, respectively.
    </para>
    <para>
     See also:
     <function>dba_nextkey</function>
     and example 2 in the <link linkend="ref.dba">DBA overview</link>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.dba-insert">
   <refnamediv>
    <refname>dba_insert</refname>
    <refpurpose>Insert entry</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>bool <function>dba_insert</function></funcdef>
      <paramdef>string <parameter>key</parameter></paramdef>
      <paramdef>string <parameter>value</parameter></paramdef>
      <paramdef>int <parameter>handle</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     <function>dba_insert</function> inserts the entry described with
     <parameter>key</parameter> and <parameter>value</parameter> into the
     database specified by <parameter>handle</parameter>. It fails, if an entry
     with the same <parameter>key</parameter> already exists.
    </para>
    <para>
     <parameter>key</parameter> is the key of the entry to be inserted.
    </para>
    <para>
     <parameter>value</parameter> is the value to be inserted.
    </para>
    <para>
     <parameter>handle</parameter> is a database handle returned by
     <function>dba_open</function>.
    </para>
    <para>
     <function>dba_insert</function> returns &true; or &false;, depending on
     whether it succeeds of fails, respectively.
    </para>
    <para>
     See also:
     <function>dba_exists</function>
     <function>dba_delete</function>
     <function>dba_fetch</function>
     <function>dba_replace</function>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.dba-nextkey">
   <refnamediv>
    <refname>dba_nextkey</refname>
    <refpurpose>Fetch next key</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>string <function>dba_nextkey</function></funcdef>
      <paramdef>int <parameter>handle</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     <function>dba_nextkey</function> returns the next key of the database
     specified by <parameter>handle</parameter> and advances the internal
     key pointer.
    </para> 
    <para>
     <parameter>handle</parameter> is a database handle returned by
     <function>dba_open</function>.
    </para>
    <para>
     <function>dba_nextkey</function> returns the key or &false; depending on
     whether it succeeds or fails, respectively.
    </para>
    <para>
     See also:
     <function>dba_firstkey</function>
     and example 2 in the <link linkend="ref.dba">DBA overview</link>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.dba-popen">
   <refnamediv>
    <refname>dba_popen</refname>
    <refpurpose>Open database persistently</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>int <function>dba_popen</function></funcdef>
      <paramdef>string <parameter>path</parameter></paramdef>
      <paramdef>string <parameter>mode</parameter></paramdef>
      <paramdef>string <parameter>handler</parameter></paramdef>
      <paramdef><parameter><optional>...</optional></parameter></paramdef>
     </funcprototype>
    </funcsynopsis>

    <para>
     <function>dba_popen</function> establishes a persistent database instance
     for <parameter>path</parameter> with <parameter>mode</parameter> using
     <parameter>handler</parameter>.
    </para>
    <para>
     <parameter>path</parameter> is commonly a regular path in your filesystem.
    </para>
    <para>
     <parameter>mode</parameter> is "r" for read access, "w" for read/write
     access to an already existing database, "c" for read/write access
     and database creation if it doesn't currently exist, and "n" for
     create, truncate and read/write access.
    </para>
    <para>
     <parameter>handler</parameter> is the <link linkend="ref.dba">name
     of the handler</link> which shall be
     used for accessing <parameter>path</parameter>. It is passed all optional
     parameters given to <function>dba_popen</function> and can act on behalf
     of them.
    </para>
    <para>
     <function>dba_popen</function> returns a positive handle or &false;, in
     the case the open is successful or fails, respectively.
    </para>
    <para>
     See also:
     <function>dba_open</function>
     <function>dba_close</function>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.dba-open">
   <refnamediv>
    <refname>dba_open</refname>
    <refpurpose>Open database</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>int <function>dba_open</function></funcdef>
      <paramdef>string <parameter>path</parameter></paramdef>
      <paramdef>string <parameter>mode</parameter></paramdef>
      <paramdef>string <parameter>handler</parameter></paramdef>
      <paramdef><parameter><optional>...</optional></parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     <function>dba_open</function> establishes a database instance for
     <parameter>path</parameter> with <parameter>mode</parameter> using
     <parameter>handler</parameter>.
    </para>
    <para>
     <parameter>path</parameter> is commonly a regular path in your filesystem.
    </para>
    <para>
     <parameter>mode</parameter> is "r" for read access, "w" for read/write
     access to an already existing database, "c" for read/write access
     and database creation if it doesn't currently exist, and "n" for
     create, truncate and read/write access.
    </para>
    <para>
     <parameter>handler</parameter> is the <link linkend="ref.dba">name
     of the handler</link> which shall be
     used for accessing <parameter>path</parameter>. It is passed all optional
     parameters given to <function>dba_open</function> and can act on behalf of
     them.
    </para>
    <para>
     <function>dba_open</function> returns a positive handle or &false;, in
     the case the open is successful or fails, respectively.
    </para>
    <para>
     See also:
     <function>dba_popen</function>
     <function>dba_close</function>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.dba-optimize">
   <refnamediv>
    <refname>dba_optimize</refname>
    <refpurpose>Optimize database</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>bool <function>dba_optimize</function></funcdef>
      <paramdef>int <parameter>handle</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     <function>dba_optimize</function> optimizes the underlying database
     specified by <parameter>handle</parameter>.
    </para>
    <para>
     <parameter>handle</parameter> is a database handle returned by
     <function>dba_open</function>.
    </para>
    <para>
     <function>dba_optimize</function> returns &true; or &false;, if the
     optimization succeeds or fails, respectively.
    </para>
    <para>
     See also:
     <function>dba_sync</function>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.dba-replace">
   <refnamediv>
    <refname>dba_replace</refname>
    <refpurpose>Replace or insert entry</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>bool <function>dba_replace</function></funcdef>
      <paramdef>string <parameter>key</parameter></paramdef>
      <paramdef>string <parameter>value</parameter></paramdef>
      <paramdef>int <parameter>handle</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     <function>dba_replace</function> replaces or inserts the entry described
     with <parameter>key</parameter> and <parameter>value</parameter> into the
     database specified by <parameter>handle</parameter>.
    </para> 
    <para>
     <parameter>key</parameter> is the key of the entry to be inserted.
    </para>
    <para>
     <parameter>value</parameter> is the value to be inserted.
    </para>
    <para>
     <parameter>handle</parameter> is a database handle returned by
     <function>dba_open</function>.
    </para>
    <para>
     <function>dba_replace</function> returns &true; or &false;, depending on
     whether it succeeds of fails, respectively.
    </para>
    <para>
     See also: <function>dba_exists</function>,
     <function>dba_delete</function>, <function>dba_fetch</function>,
     and <function>dba_insert</function>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.dba-sync">
   <refnamediv>
    <refname>dba_sync</refname>
    <refpurpose>Synchronize database</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>bool <function>dba_sync</function></funcdef>
      <paramdef>int <parameter>handle</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     <function>dba_sync</function> synchronizes the database specified by
     <parameter>handle</parameter>. This will probably trigger a physical write
     to disk, if supported.
    </para>
    <para>
     <parameter>handle</parameter> is a database handle returned by
     <function>dba_open</function>.
    </para>
    <para>
     <function>dba_sync</function> returns &true; or &false;, if the
     synchronization succeeds or fails, respectively.
    </para>
    <para>
     See also: <function>dba_optimize</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
-->