From 6926843be0f2232db8df2b81f675b2fec1131ab9 Mon Sep 17 00:00:00 2001
From: Dan Scott <dbs@php.net>
Date: Thu, 14 Apr 2005 00:42:43 +0000
Subject: [PATCH] Document db2_fetch_row and db2_result.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@184308 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/ibm_db2/functions/db2-fetch-row.xml | 121 ++++++++----------
 reference/ibm_db2/functions/db2-result.xml    |  85 +++++-------
 2 files changed, 84 insertions(+), 122 deletions(-)

diff --git a/reference/ibm_db2/functions/db2-fetch-row.xml b/reference/ibm_db2/functions/db2-fetch-row.xml
index 3432bdaf06..37676aa3ad 100644
--- a/reference/ibm_db2/functions/db2-fetch-row.xml
+++ b/reference/ibm_db2/functions/db2-fetch-row.xml
@@ -1,11 +1,11 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 <!-- Generated by xml_proto.php v2.2. Found in /scripts directory of phpdoc. -->
 <refentry id="function.db2-fetch-row">
  <refnamediv>
   <refname>db2_fetch_row</refname>
   <refpurpose>
-   Sets the fetch pointer to the next or requested row in a result set
+   Sets the result set pointer to the next row or requested row
   </refpurpose>
  </refnamediv>
  <refsect1 role="description">
@@ -16,7 +16,24 @@
    <methodparam choice="opt"><type>int</type><parameter>row_number</parameter></methodparam>
   </methodsynopsis>
 
-  &warn.undocumented.func;
+  &warn.experimental.func;
+
+  <para>
+   Use <function>db2_fetch_row</function> to iterate through a result set, or
+   to point to a specific row in a result set if you requested a scrollable
+   cursor.
+  </para>
+  <para>
+   To retrieve individual fields from the result set, call the
+   <function>db2_result</function> function.
+  </para>
+  <para>
+   Rather than calling <function>db2_fetch_row</function> and
+   <function>db2_result</function>, most applications will call one of
+   <function>db2_fetch_assoc</function>, <function>db2_fetch_both</function>,
+   or <function>db2_fetch_into</function> to advance the result set pointer
+   and return a complete row as an array.
+  </para>
 
  </refsect1>
  <refsect1 role="parameters">
@@ -25,82 +42,52 @@
    <variablelist>
     <varlistentry>
      <term><parameter>stmt</parameter></term>
-      <listitem>
-       <para>
-        Its description
-       </para>
-      </listitem>
-     </varlistentry>
+     <listitem>
+      <para>
+       A valid <literal>stmt</literal> resource.
+      </para>
+     </listitem>
+    </varlistentry>
     <varlistentry>
      <term><parameter>row_number</parameter></term>
-      <listitem>
-       <para>
-        Its description
-       </para>
-      </listitem>
-     </varlistentry>
+     <listitem>
+      <para>
+       With scrollable cursors, you can request a specific row number in the
+       result set. Row numbering is 1-indexed.
+      </para>
+     </listitem>
+    </varlistentry>
    </variablelist>
   </para>
  </refsect1>
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   What the function returns, first on success, then on failure. See
-   also the &return.success; entity
+   Returns &true; if the requested row exists in the result set. Returns
+   &false; if the requested row does not exist in the result set.
   </para>
  </refsect1>
 
- <!-- Use when EXCEPTIONS exist
- <refsect1 role="exceptions">
-  &reftitle.exceptions;
-  <para>
-   When does this function throw exceptions?
-  </para>
- </refsect1>
- -->
-
-
- <!-- Use when a CHANGELOG exists
- <refsect1 role="changelog">
-  &reftitle.changelog;
-  <para>
-   <informaltable>
-    <tgroup cols="2">
-     <thead>
-      <row>
-       <entry>&Version;</entry>
-       <entry>&Description</entry>
-      </row>
-     </thead>
-     <tbody>
-      <row>
-       <entry>Enter the PHP version of change here
-       <entry>Description of change
-      </row>
-     </tbody>
-    </tgroup>
-   </informaltable>
-  </para>
- </refsect1>
- -->
-
-
- <!-- Use when examples exist
  <refsect1 role="examples">
   &reftitle.examples;
   <para>
    <example>
-    <title>A <function>db2_fetch_row</function> example</title>
+    <title>Iterating through a result set</title>
     <para>
-     Any text that describes the purpose of the example, or
-     what goes on in the example should go here (inside the
-     <example> tag, not out
+     The following example demonstrates how to iterate through a result set
+     with <function>db2_fetch_row</function> and retrieve columns from the
+     result set with <function>db2_result</function>.
     </para>
     <programlisting role="php">
 <![CDATA[
 <?php
-if ($anexample === true) {
-    echo 'Use the PEAR Coding Standards';
+$sql = 'SELECT name, breed FROM animals WHERE weight < ?';
+$stmt = db2_prepare($conn, $sql);
+db2_execute($stmt, array(10));
+while (db2_fetch_row($stmt)) {
+    $name = db2_result($stmt, 0);
+    $breed = db2_result($stmt, 1);
+    print "$name $breed";
 }
 ?>
 ]]>
@@ -108,27 +95,27 @@ if ($anexample === true) {
     &example.outputs;
     <screen>
 <![CDATA[
-Use the PEAR Coding Standards
+cat Pook
+gold fish Bubbles
+budgerigar Gizmo
+goat Rickety Ride
 ]]>
     </screen>
    </example>
   </para>
  </refsect1>
- -->
 
-
- <!-- Use when adding See Also links
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>
    <simplelist>
-    <member><function></function></member>
-    <member>Or <link linkend="somethingelse">something else</link></member>
+    <member><function>db2_fetch_assoc</function></member>
+    <member><function>db2_fetch_both</function></member>
+    <member><function>db2_fetch_into</function></member>
+    <member><function>db2_result</function></member>
    </simplelist>
   </para>
  </refsect1>
- -->
-
 
 </refentry>
 
diff --git a/reference/ibm_db2/functions/db2-result.xml b/reference/ibm_db2/functions/db2-result.xml
index 642e531f4c..7d051c50f3 100644
--- a/reference/ibm_db2/functions/db2-result.xml
+++ b/reference/ibm_db2/functions/db2-result.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.1 $ -->
+<!-- $Revision: 1.2 $ -->
 <!-- Generated by xml_proto.php v2.2. Found in /scripts directory of phpdoc. -->
 <refentry id="function.db2-result">
  <refnamediv>
@@ -16,7 +16,15 @@
    <methodparam><type>mixed</type><parameter>column</parameter></methodparam>
   </methodsynopsis>
 
-  &warn.undocumented.func;
+  &warn.experimental.func;
+
+  <para>
+   Use <function>db2_result</function> to return the value of a specified
+   column in the current row of a result set. You must call
+   <function>db2_fetch_row</function> before calling
+   <function>db2_result</function> to set the location of the result set
+   pointer.
+  </para>
 
  </refsect1>
  <refsect1 role="parameters">
@@ -27,7 +35,7 @@
      <term><parameter>stmt</parameter></term>
       <listitem>
        <para>
-        Its description
+        A valid <literal>stmt</literal> resource.
        </para>
       </listitem>
      </varlistentry>
@@ -35,7 +43,8 @@
      <term><parameter>column</parameter></term>
       <listitem>
        <para>
-        Its description
+        Either an integer mapping to the 0-indexed field in the result set, or
+        a string matching the name of the column.
        </para>
       </listitem>
      </varlistentry>
@@ -45,62 +54,31 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   What the function returns, first on success, then on failure. See
-   also the &return.success; entity
+   Returns the value of the requested field if the field exists in the result
+   set. Returns NULL if the field does not exist, and issues a warning.
   </para>
  </refsect1>
 
- <!-- Use when EXCEPTIONS exist
- <refsect1 role="exceptions">
-  &reftitle.exceptions;
-  <para>
-   When does this function throw exceptions?
-  </para>
- </refsect1>
- -->
-
-
- <!-- Use when a CHANGELOG exists
- <refsect1 role="changelog">
-  &reftitle.changelog;
-  <para>
-   <informaltable>
-    <tgroup cols="2">
-     <thead>
-      <row>
-       <entry>&Version;</entry>
-       <entry>&Description</entry>
-      </row>
-     </thead>
-     <tbody>
-      <row>
-       <entry>Enter the PHP version of change here
-       <entry>Description of change
-      </row>
-     </tbody>
-    </tgroup>
-   </informaltable>
-  </para>
- </refsect1>
- -->
-
-
- <!-- Use when examples exist
  <refsect1 role="examples">
   &reftitle.examples;
   <para>
    <example>
     <title>A <function>db2_result</function> example</title>
     <para>
-     Any text that describes the purpose of the example, or
-     what goes on in the example should go here (inside the
-     <example> tag, not out
+     The following example demonstrates how to iterate through a result set
+     with <function>db2_fetch_row</function> and retrieve columns from the
+     result set with <function>db2_result</function>.
     </para>
     <programlisting role="php">
 <![CDATA[
 <?php
-if ($anexample === true) {
-    echo 'Use the PEAR Coding Standards';
+$sql = 'SELECT name, breed FROM animals WHERE weight < ?';
+$stmt = db2_prepare($conn, $sql);
+db2_execute($stmt, array(10));
+while (db2_fetch_row($stmt)) {
+    $name = db2_result($stmt, 0);
+    $breed = db2_result($stmt, 'BREED');
+    print "$name $breed";
 }
 ?>
 ]]>
@@ -108,27 +86,24 @@ if ($anexample === true) {
     &example.outputs;
     <screen>
 <![CDATA[
-Use the PEAR Coding Standards
+cat Pook
+gold fish Bubbles
+budgerigar Gizmo
+goat Rickety Ride
 ]]>
     </screen>
    </example>
   </para>
  </refsect1>
- -->
 
-
- <!-- Use when adding See Also links
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>
    <simplelist>
-    <member><function></function></member>
-    <member>Or <link linkend="somethingelse">something else</link></member>
+    <member><function>db2_fetch_row</function></member>
    </simplelist>
   </para>
  </refsect1>
- -->
-
 
 </refentry>