   #PHP Manual Function Reference ctype_xdigit dba_close

   PHP Manual
   Prev  Next
   ______________________________________________________________________

XVI. Database (dbm-style) abstraction layer functions

Introduction

   These functions build the foundation for accessing Berkeley DB style
   databases.

   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 Sleepycat Software's DB2. (This
   is not to be confused with IBM's DB2 software, which is supported
   through the ODBC functions.)

Requirements

   The behaviour of various aspects depends on the implementation of the
   underlying database. Functions such as dba_optimize() and dba_sync()
   will do what they promise for one database and will do nothing for
   others. You have to download and install supported dba-Handlers.

   Table 1. List of DBA handlers
   Handler Notes
   dbm 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.
   ndbm Ndbm is a newer type and more flexible than dbm. It still has
   most of the arbitrary limits of dbm (therefore it is deprecated).
   gdbm Gdbm is the GNU database manager.
   db2 DB2 is Sleepycat Software's DB2. It is described as "a
   programmatic toolkit that provides high-performance built-in database
   support for both standalone and client/server applications.
   db3 DB3 is Sleepycat Software's DB3.
   db4 DB4 is Sleepycat Software's DB4. This is available since PHP
   5.0.0.
   cdb Cdb is "a fast, reliable, lightweight package for creating and
   reading constant databases." It is from the author of qmail and can be
   found here. Since it is constant, we support only reading operations.
   And since PHP 4.3.0 we support writing (not updating) through the
   internal cdb library.
   cdb_make Since PHP 4.3.0 we support creation (not updating) of cdb
   files when the bundled cdb library is used.
   flatfile This is available since PHP 4.3.0 for compatibility with the
   deprecated dbm extension only and should be avoided. However you may
   use this where files were created in this format. That happens when
   configure could not find any external library.
   inifile This is available since PHP 4.3.3 to be able to modify php.ini
   files from within PHP scripts. When working with ini files you can
   pass arrays of the form array(0=>group,1=>value_name) or strings of
   the form "[group]value_name" where group is optional. As the functions
   dba_firstkey() and dba_nextkey() return string representations of the
   key there is a new function dba_key_split() available since PHP 5
   which allows to convert the string keys into array keys without
   loosing FALSE.

   When invoking the dba_open() or dba_popen() functions, one of the
   handler names must be supplied as an argument. The actually available
   list of handlers is displayed by invoking phpinfo() or dba_handlers().

Installation

   By using the --enable-dba=shared configuration option you can build a
   dynamic loadable module to enable PHP for basic support of dbm-style
   databases. You also have to add support for at least one of the
   following handlers by specifying the --with-XXXX configure switch to
   your PHP configure line.

   Table 2. Supported DBA handlers
   Handler  Configure Switch
   dbm      To enable support for dbm add --with-dbm[=DIR].
   ndbm     To enable support for ndbm add --with-ndbm[=DIR].
   gdbm     To enable support for gdbm add --with-gdbm[=DIR].
   db2 To enable support for db2 add --with-db2[=DIR].

     Note: db2 conflicts with db3 and db4.

   db3 To enable support for db3 add --with-db3[=DIR].

     Note: db3 conflicts with db2 and db4.

   db4 To enable support for db4 add --with-db4[=DIR].

     Note: db4 conflicts with db2 and db3.

     Note: This was added in PHP 4.3.2. In earlier versions of PHP you
     need to use --with-db3=DIR with DIR being the path to db4 library.
     It is not possible to use db versions starting from 4.1 with PHP
     prior to version 4.3.0. Also, the db libraries with versions 4.1
     through 4.1.24 cannot be used in any PHP version.

   cdb To enable support for cdb add --with-cdb[=DIR].

     Note: Since PHP 4.3.0 you can omit DIR to use the bundled cdb
     library that adds the cdb_make handler which allows creation of cdb
     files and allows to access cdb files on the network using PHP's
     streams.

   flatfile To enable support for flatfile add --with-flatfile.

     Note: This was added in PHP 4.3.0 to add compatibility with
     deprecated dbm extension. Use this handler only when you cannot
     install one of the libraries required by the other handlers and
     when you cannot use bundled cdb handler.

   inifile To enable support for inifile add --with-inifile.

     Note: This was added in PHP 5.0.0 and allows to read and set
     microsoft style ini files (like the php.ini file).

     Note: Up to PHP 4.3.0 you are able to add both db2 and db3 handler
     but only one of them can be used internally. That means that you
     cannot have both file formats. Starting with PHP 5.0.0 there is a
     configuration check avoid such missconfigurations.

Runtime Configuration

   This extension has no configuration directives defined in php.ini.

Resource Types

   The functions dba_open() and dba_popen() return a handle to the
   specified database file to access which is used by all other
   dba-function calls.

Predefined Constants

   This extension has no constants defined.

Examples

   Example 1. DBA example
   <?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);
   ?>

   DBA is binary safe and does not have any arbitrary limits. However, it
   inherits all limits set by the underlying database implementation.

   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 dba_open() or
   dba_popen().

   You can access all entries of a database in a linear way by using the
   dba_firstkey() and dba_nextkey() functions. You may not change the
   database while traversing it.

   Example 2. Traversing a database
   <?php
   // ...open database...
   $key = dba_firstkey($id);
   while ($key != false) {
       if (true) {          // 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);
   ?>

   Table of Contents
   dba_close -- Close database
   dba_delete -- Delete entry specified by key
   dba_exists -- Check whether key exists
   dba_fetch -- Fetch data specified by key
   dba_firstkey -- Fetch first key
   dba_handlers -- List handlers available
   dba_insert -- Insert entry
   dba_key_split -- Splits a key in string representation into array
          representation

   dba_list -- List all open database files
   dba_nextkey -- Fetch next key
   dba_open -- Open database
   dba_optimize -- Optimize database
   dba_popen -- Open database persistently
   dba_replace -- Replace or insert entry
   dba_sync -- Synchronize database
   ______________________________________________________________________

   Prev         Home      Next
   ctype_xdigit  Up  dba_close
