martin Thu May 17 05:43:47 2001 EDT
Modified files:
/phpdoc/en/functions dba.xml
Log:
Clarify the "Handler" (supply a handler table) vs. "handle".
Fix erroneous return type for dba_delete()
"Literal"ize TRUE and FALSE
Index: phpdoc/en/functions/dba.xml
diff -u phpdoc/en/functions/dba.xml:1.7 phpdoc/en/functions/dba.xml:1.8
--- phpdoc/en/functions/dba.xml:1.7 Fri Sep 8 18:06:51 2000
+++ phpdoc/en/functions/dba.xml Thu May 17 05:43:46 2001
@@ -8,67 +8,97 @@
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
+ 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 depend on the implementation of the
+ 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>
- 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>
+ 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>
@@ -96,8 +126,9 @@
</example>
</para>
<para>
- DBA is binary safe and does not have any arbitrary limits. It inherits all
- limits set by the underlying database implementation.
+ 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
@@ -177,7 +208,7 @@
<title>Description</title>
<funcsynopsis>
<funcprototype>
- <funcdef>string <function>dba_delete</function></funcdef>
+ <funcdef>bool <function>dba_delete</function></funcdef>
<paramdef>string <parameter>key</parameter></paramdef>
<paramdef>int <parameter>handle</parameter></paramdef>
</funcprototype>
@@ -196,7 +227,7 @@
<function>dba_open</function>.
</para>
<para>
- <function>dba_delete</function> returns true or false, if the entry is
+ <function>dba_delete</function> returns <literal>true</literal> or
+<literal>false</literal>, if the entry is
deleted or not deleted, respectively.
</para>
<para>
@@ -234,7 +265,7 @@
<function>dba_open</function>.
</para>
<para>
- <function>Dba_exists</function> returns true or false, if the key is found
+ <function>Dba_exists</function> returns <literal>true</literal> or
+<literal>false</literal>, if the key is found
or not found, respectively.
</para>
<para>
@@ -273,7 +304,7 @@
</para>
<para>
- <function>Dba_fetch</function> returns the associated string or false, if
+ <function>Dba_fetch</function> returns the associated string or
+<literal>false</literal>, if
the key/data pair is found or not found, respectively.
</para>
<para>
@@ -308,12 +339,13 @@
<function>dba_open</function>.
</para>
<para>
- <function>Dba_firstkey</function> returns the key or false
+ <function>Dba_firstkey</function> returns the key or <literal>false</literal>
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>
@@ -350,7 +382,7 @@
<function>dba_open</function>.
</para>
<para>
- <function>dba_insert</function> returns true or false, depending on
+ <function>dba_insert</function> returns <literal>true</literal> or
+<literal>false</literal>, depending on
whether it succeeds of fails, respectively.
</para>
<para>
@@ -378,7 +410,7 @@
</funcsynopsis>
<para>
<function>dba_nextkey</function> returns the next key of the database
- specified by <parameter>handle</parameter> and increments the internal
+ specified by <parameter>handle</parameter> and advances the internal
key pointer.
</para>
<para>
@@ -386,12 +418,13 @@
<function>dba_open</function>.
</para>
<para>
- <function>dba_nextkey</function> returns the key or false depending on
+ <function>dba_nextkey</function> returns the key or <literal>false</literal>
+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>
@@ -428,13 +461,14 @@
create, truncate and read/write access.
</para>
<para>
- <parameter>handler</parameter> is the name of the handler which shall be
+ <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 handler id or false, in
+ <function>dba_popen</function> returns a positive handle or
+<literal>false</literal>, in
the case the open is successful or fails, respectively.
</para>
<para>
@@ -476,13 +510,14 @@
create, truncate and read/write access.
</para>
<para>
- <parameter>handler</parameter> is the name of the handler which shall be
+ <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 handler id or false, in
+ <function>dba_open</function> returns a positive handle or
+<literal>false</literal>, in
the case the open is successful or fails, respectively.
</para>
<para>
@@ -515,7 +550,7 @@
<function>dba_open</function>.
</para>
<para>
- <function>dba_optimize</function> returns true or false, if the
+ <function>dba_optimize</function> returns <literal>true</literal> or
+<literal>false</literal>, if the
optimization succeeds or fails, respectively.
</para>
<para>
@@ -556,7 +591,7 @@
<function>dba_open</function>.
</para>
<para>
- <function>dba_replace</function> returns true or false, depending on
+ <function>dba_replace</function> returns <literal>true</literal> or
+<literal>false</literal>, depending on
whether it succeeds of fails, respectively.
</para>
<para>
@@ -590,7 +625,7 @@
<function>dba_open</function>.
</para>
<para>
- <function>dba_sync</function> returns true or false, if the
+ <function>dba_sync</function> returns <literal>true</literal> or
+<literal>false</literal>, if the
synchronization succeeds or fails, respectively.
</para>
<para>
