<?xml version="1.0" encoding="utf-8"?>
 <reference id="ref.dbm">
  <title>DBM Functions</title>
  <titleabbrev>DBM</titleabbrev>

  <partintro>
   <simpara>
    These functions allow you to store records stored in a dbm-style
    database. This type of database (supported by the Berkeley DB,
    GDBM, and some system libraries, as well as a built-in flatfile
    library) stores key/value pairs (as opposed to the full-blown
    records supported by relational databases).
   </simpara>
   <para>
    <example>
     <title>DBM example</title>
     <programlisting role="php">
$dbm = dbmopen ("lastseen", "w");
if (dbmexists ($dbm, $userid)) {
    $last_seen = dbmfetch ($dbm, $userid);
} else {
    dbminsert ($dbm, $userid, time());
}
do_stuff();
dbmreplace ($dbm, $userid, time());
dbmclose ($dbm);
     </programlisting>
    </example>
   </para>
  </partintro>

  <refentry id="function.dbmopen">
   <refnamediv>
    <refname>dbmopen</refname>
    <refpurpose>Opens a DBM database</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>dbmopen</methodname>
      <methodparam><type>string</type><parameter>filename</parameter></methodparam>
      <methodparam><type>string</type><parameter>flags</parameter></methodparam>
     </methodsynopsis>
    <para>
     The first argument is the full-path filename of the DBM file to
     be opened and the second is the file open mode which is one of
     "r", "n", "c" or "w" for read-only, new (implies read-write, and
     most likely will truncate an already-existing database of the
     same name), create (implies read-write, and will not truncate an
     already-existing database of the same name) and read-write
     respectively.
    </para>
    <para>
     Returns an identifer to be passed to the other DBM functions on
     success, or &false; on failure.
    </para>
    <para>
     If NDBM support is used, NDBM will actually create filename.dir
     and filename.pag files. GDBM only uses one file, as does the
     internal flat-file support, and Berkeley DB creates a
     <filename>filename.db</filename> file. Note that PHP does its own
     file locking in addition to any file locking that may be done by
     the DBM library itself. PHP does not delete the
     <filename>.lck</filename> files it creates. It uses these files
     simply as fixed inodes on which to do the file locking. For more
     information on DBM files, see your Unix man pages, or obtain
     <ulink url="&url.gdbm;">GNU's GDBM</ulink>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.dbmclose">
   <refnamediv>
    <refname>dbmclose</refname>
    <refpurpose>Closes a dbm database</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>dbmclose</methodname>
      <methodparam><type>int</type><parameter>dbm_identifier</parameter></methodparam>
     </methodsynopsis>
    <para>
     Unlocks and closes the specified database.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.dbmexists">
   <refnamediv>
    <refname>dbmexists</refname>
    <refpurpose>
     Tells if a value exists for a key in a DBM database
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>dbmexists</methodname>
      <methodparam><type>int</type><parameter>dbm_identifier</parameter></methodparam>
      <methodparam><type>string</type><parameter>key</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns &true; if there is a value associated with the
     <parameter>key</parameter>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.dbmfetch">
   <refnamediv>
    <refname>dbmfetch</refname>
    <refpurpose>
     Fetches a value for a key from a DBM database
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>dbmfetch</methodname>
      <methodparam><type>int</type><parameter>dbm_identifier</parameter></methodparam>
      <methodparam><type>string</type><parameter>key</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns the value associated with <parameter>key</parameter>.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.dbminsert">
   <refnamediv>
    <refname>dbminsert</refname>
    <refpurpose>
     Inserts a value for a key in a DBM database
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>int</type><methodname>dbminsert</methodname>
      <methodparam><type>int</type><parameter>dbm_identifier</parameter></methodparam>
      <methodparam><type>string</type><parameter>key</parameter></methodparam>
      <methodparam><type>string</type><parameter>value</parameter></methodparam>
     </methodsynopsis>
    <para>
     Adds the value to the database with the specified key.
    </para>
    <para>
     Returns -1 if the database was opened read-only, 0 if the insert
     was successful, and 1 if the specified key already exists. (To
     replace the value, use <function>dbmreplace</function>.)
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.dbmreplace">
   <refnamediv>
    <refname>dbmreplace</refname>
    <refpurpose>
     Replaces the value for a key in a DBM database
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>dbmreplace</methodname>
      <methodparam><type>int</type><parameter>dbm_identifier</parameter></methodparam>
      <methodparam><type>string</type><parameter>key</parameter></methodparam>
      <methodparam><type>string</type><parameter>value</parameter></methodparam>
     </methodsynopsis>
    <para>
     Replaces the value for the specified key in the database.
    </para>
    <para>
     This will also add the key to the database if it didn't already
     exist.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.dbmdelete">
   <refnamediv>
    <refname>dbmdelete</refname>
    <refpurpose>
     Deletes the value for a key from a DBM database
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>bool</type><methodname>dbmdelete</methodname>
      <methodparam><type>int</type><parameter>dbm_identifier</parameter></methodparam>
      <methodparam><type>string</type><parameter>key</parameter></methodparam>
     </methodsynopsis>
    <para>
     Deletes the value for <parameter>key</parameter> in the database.
    </para>
    <para>
     Returns &false; if the key didn't exist in the database.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.dbmfirstkey">
   <refnamediv>
    <refname>dbmfirstkey</refname>
    <refpurpose>
     Retrieves the first key from a DBM database
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>dbmfirstkey</methodname>
      <methodparam><type>int</type><parameter>dbm_identifier</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns the first key in the database. Note that no particular order
     is guaranteed since the database may be built using a hash-table,
     which doesn't guarantee any ordering.
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.dbmnextkey">
   <refnamediv>
    <refname>dbmnextkey</refname>
    <refpurpose>
     Retrieves the next key from a DBM database</refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>dbmnextkey</methodname>
      <methodparam><type>int</type><parameter>dbm_identifier</parameter></methodparam>
      <methodparam><type>string</type><parameter>key</parameter></methodparam>
     </methodsynopsis>
    <para>
     Returns the next key after <parameter>key</parameter>. By calling
     <function>dbmfirstkey</function> followed by successive
     calls to <function>dbmnextkey</function> it is possible to
     visit every key/value pair in the dbm database. For example:
     <example>
      <title>Visiting every key/value pair in a DBM database</title>
      <programlisting role="php">
$key = dbmfirstkey ($dbm_id);
while ($key) {
    echo "$key = " . dbmfetch ($dbm_id, $key) . "\n";
    $key = dbmnextkey ($dbm_id, $key);
}
     </programlisting>
    </example>
    </para>
   </refsect1>
  </refentry>

  <refentry id="function.dblist">
   <refnamediv>
    <refname>dblist</refname>
    <refpurpose>
     Describes the DBM-compatible library being used
    </refpurpose>
   </refnamediv>
   <refsect1>
    <title>Description</title>
     <methodsynopsis>
      <type>string</type><methodname>dblist</methodname>
      <void/>
     </methodsynopsis>
   </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:
-->