php-doc-en/reference/dba/reference.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.2 $ -->
 <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>

&reference.dba.functions;

 </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
-->