Added documentation for the new DBX_RESULT_UNBUFFERED flag and the new

dbx_fetch_row function.
# untested xml-files, if someone with a working setup could test them
# please? Thanks!


git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@139654 c90b9560-bf6c-de11-be94-00142212c4b1

reference/dbx/constants.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.7 $ -->
+<!-- $Revision: 1.8 $ -->
  <section id="constants.dbx">
  &reftitle.constants;
  &extension.constants;
@@ -136,6 +136,17 @@
       </simpara>
      </listitem>
     </varlistentry>
+    <varlistentry>
+     <term>
+      <constant>DBX_RESULT_UNBUFFERED</constant> 
+      (<type>integer</type>) (CVS only)
+     </term>
+     <listitem>
+      <simpara>
+       
+      </simpara>
+     </listitem>
+    </varlistentry>
     <varlistentry>
      <term>
       <constant>DBX_COLNAMES_UNCHANGED</constant> 

reference/dbx/functions/dbx-fetch-row.xml

@@ -0,0 +1,80 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!-- $Revision: 1.1 $ -->
+  <refentry id="function.dbx-fetch-row">
+   <refnamediv>
+    <refname>dbx_fetch_row</refname>
+    <refpurpose>Fetches rows from a query-result that had the 
+    <constant>DBX_RESULT_UNBUFFERED</constant> flag set</refpurpose>
+   </refnamediv>
+   <refsect1>
+    <title>Description</title>
+     <methodsynopsis>
+      <type>object</type><methodname>dbx_fetch_row</methodname>
+      <methodparam><type>object</type><parameter>result_identifier</parameter></methodparam>
+     </methodsynopsis>
+    <simpara>
+     <function>dbx_fetch_row</function> returns a row on success, and 
+     <literal>0</literal> on failure (e.g. when no more rows are available). 
+     When the <constant>DBX_RESULT_UNBUFFERED</constant> is not set in the 
+     query, <function>dbx_fetch_row</function> will fail as all rows have 
+     already been fetched into the results <property>data</property> property.
+    </simpara>
+    <simpara>
+     As a side effect, the <property>rows</property> property of the query-result
+     object is incremented for each successful call to 
+     <function>dbx_fetch_row</function>.
+    </simpara>
+    <example>
+     <title>How to handle the returned value</title>
+      <programlisting role="php">
+<![CDATA[
+$result = dbx_query ($link, 'SELECT id, parentid, description FROM table', DBX_RESULT_UNBUFFERED);
+
+echo "<table>\n";
+while ( $row = dbx_fetch_row($result) ) {
+    echo "<tr>\n";
+    foreach ( $row as $field ) {
+        echo "<td>$field</td>";
+    }
+    echo "</tr>\n";
+}
+echo "</table>\n";
+]]>
+      </programlisting>
+    </example>
+    <para>
+     The <parameter>result_identifier</parameter> parameter is the result
+     object returned by a call to <function>dbx_query</function>.
+    </para>
+    <para>
+     The returned array contains the same information as any row would have
+     in the dbx_query result <property>data</property> property, including
+     columns accessable by index or fieldname when the flags for dbx_guery
+     were set that way.
+    </para>
+    <para>
+     See also <function>dbx_query</function>.
+    </para>
+   </refsect1>
+  </refentry>
+
+<!-- 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:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->

reference/dbx/functions/dbx-query.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.10 $ -->
+<!-- $Revision: 1.11 $ -->
 <!-- splitted from ./en/functions/dbx.xml, last change in rev 1.3 -->
   <refentry id="function.dbx-query">
    <refnamediv>
@@ -47,7 +47,6 @@ dbx_close($link);
 ]]>
      </programlisting>
     </example>
-
     <para>
      The <parameter>flags</parameter> parameter is used to control the amount of
      information that is returned. It may be any combination of the following 
@@ -102,6 +101,24 @@ dbx_close($link);
         </simpara>
        </listitem>
       </varlistentry>
+      <varlistentry>
+       <term>
+        <constant>DBX_RESULT_UNBUFFERED</constant> (CVS only)
+       </term>
+       <listitem>
+        <simpara>
+         This flag will not create the <property>data</property> property, and 
+         the <property>rows</property> property will initially be 0. Use this 
+         flag for large datasets, and use <function>dbx_fetch_row</function> to
+         retrieve the results row by row.
+        </simpara>
+        <simpara>
+         The <function>dbx_fetch_row</function> function will return rows that
+         are conformant to the flags set with this query. Incidentally, it will
+         also update the <property>rows</property> each time it is called.
+        </simpara>
+       </listitem>
+      </varlistentry>
       <varlistentry>
        <term>
         <constant>DBX_COLNAMES_UNCHANGED</constant> (available from PHP 4.3.0)
@@ -137,7 +154,7 @@ dbx_close($link);
      </variablelist>
      Note that <constant>DBX_RESULT_INDEX</constant> is always used, regardless 
      of the actual value of <parameter>flags</parameter> parameter. This means 
-     that the following combinations is effective only:
+     that only the following combinations are effective:
      <itemizedlist>
       <listitem>
        <simpara>
@@ -161,7 +178,7 @@ dbx_close($link);
      </itemizedlist>
     </para>
     <para>
-     The returing <varname>object</varname> has four or five
+     The returned <varname>object</varname> has four or five
      properties depending on <parameter>flags</parameter>:
      <variablelist>
       <varlistentry>
@@ -268,7 +285,25 @@ echo "</table>\n";
 ]]>
          </programlisting>
         </example>
-       </listitem>
+        <example>
+         <title>How to handle UNBUFFERED queries</title>
+         <programlisting role="php">
+<![CDATA[
+$result = dbx_query ($link, 'SELECT id, parentid, description FROM table', DBX_RESULT_UNBUFFERED);
+
+echo "<table>\n";
+while ( $row = dbx_fetch_row($result) ) {
+    echo "<tr>\n";
+    foreach ( $row as $field ) {
+        echo "<td>$field</td>";
+    }
+    echo "</tr>\n";
+}
+echo "</table>\n";
+]]>
+         </programlisting>
+        </example>
+      </listitem>
       </varlistentry>
      </variablelist>
     </para>
@@ -282,7 +317,8 @@ echo "</table>\n";
      </para>
     </note>
     <para>
-     See also <function>dbx_escape_string</function> and 
+     See also <function>dbx_escape_string</function>, 
+     <function>dbx_fetch_row</function> and 
      <function>dbx_connect</function>.
     </para>
    </refsect1>

reference/dbx/reference.xml

@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.12 $ -->
+<!-- $Revision: 1.13 $ -->
 
 <!-- 
     If anyone from the translator group has problems with the 
@@ -29,7 +29,7 @@
     <para>
      To be able to use a database with the dbx-module, the module must be either
      linked or loaded into PHP, and the database module must be supported by the
-     dbx-module. Currently, following databases are supported, but others
+     dbx-module. Currently, the following databases are supported, but others
      will follow:
      <itemizedlist>
       <listitem>
@@ -89,7 +89,7 @@
     <para>
      There are two resource types used in the dbx module. The first one is the
      link-<type>object</type> for a database connection, the second a
-     result-<type>object</type> which helds the result of a query.
+     result-<type>object</type> which holds the result of a query.
     </para>
    </section>