mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-19 10:28:54 +00:00
9904027e99
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@32297 c90b9560-bf6c-de11-be94-00142212c4b1
619 lines
19 KiB
XML
619 lines
19 KiB
XML
<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 subset of features modern databases
|
|
such as <ulink url="&url.sleepycat;">Sleepycat Software's DB2</ulink>
|
|
support. (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 depend 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>
|
|
To add support for any of the following handlers, add the
|
|
specified --with configure switch to your PHP configure line:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<simpara>
|
|
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. (--with-dbm)
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
Ndbm is a newer type and more flexible than dbm. It still has
|
|
most of the arbitrary limits of dbm (therefore it is
|
|
deprecated). (--with-ndbm)
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
Gdbm is the <ulink url="&url.gdbm;">GNU database
|
|
manager</ulink>. (--with-gdbm)
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
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." (--with-db2)
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
DB3 is <ulink url="&url.sleepycat;">Sleepycat Software's
|
|
DB3</ulink>. (--with-db3)
|
|
</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>
|
|
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. (--with-cdb)
|
|
</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
<example>
|
|
<title>DBA example</title>
|
|
<programlisting role="php">
|
|
<?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. 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">
|
|
<?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>string <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>
|
|
</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 increments 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>
|
|
</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 name of the handler 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 handler id 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 name of the handler 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 handler id 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
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"../../manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
-->
|