cvs: phpdoc /en/functions dba.xml

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>