Update examples, include warning for fetchAll about resource requirements.

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

reference/pdo/functions/PDOStatement-fetch.xml

@@ -1,5 +1,5 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc. -->
   <refentry id="function.PDOStatement-fetch">
    <refnamediv>
@@ -56,6 +56,9 @@
      <programlisting role="php">
 <![CDATA[
 <?php
+$sth = $dbh->prepare("SELECT name, colour FROM fruit");
+$sth->execute();
+
 /* Exercise PDOStatement::fetch styles */
 print("PDO_FETCH_ASSOC: ");
 print("Return next row as an array indexed by column name\n");

reference/pdo/functions/PDOStatement-fetchAll.xml

@@ -1,5 +1,5 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.3 $ -->
+<!-- $Revision: 1.4 $ -->
 <!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc. -->
   <refentry id="function.PDOStatement-fetchAll">
    <refnamediv>
@@ -25,11 +25,22 @@
      <function>PDOStatement::fetch</function>. <parameter>fetch_style</parameter>
      defaults to <literal>PDO_FETCH_BOTH</literal>.
     </para>
+    <para>
+     Using this method to fetch large result sets will result in a heavy
+     demand on system and possibly network resources. Rather than retrieving
+     all of the data and manipulating it in PHP, consider using the database
+     server to manipulate the result sets. For example, use the WHERE and
+     SORT BY clauses in SQL to restrict results before retrieving and
+     processing them with PHP.
+    </para>
 
     <example><title>Fetch all remaining rows in a result set</title>
      <programlisting role="php">
 <![CDATA[
 <?php
+$sth = $dbh->prepare("SELECT name, colour FROM fruit");
+$sth->execute();
+
 /* Fetch all of the remaining rows in the result set */
 print("Fetch all of the remaining rows in the result set:\n");
 $result = $sth->fetchAll();

reference/pdo/functions/PDOStatement-fetchSingle.xml

@@ -1,11 +1,11 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.2 $ -->
+<!-- $Revision: 1.3 $ -->
 <!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc. -->
   <refentry id="function.PDOStatement-fetchSingle">
    <refnamediv>
     <refname>PDOStatement::fetchSingle</refname>
     <refpurpose>
-     Returns a data of the first column in the result set
+     Returns the first column in the next row of a result set
     </refpurpose>
    </refnamediv>
    <refsect1>
@@ -15,7 +15,44 @@
      <void/>
     </methodsynopsis>
 
-     &warn.undocumented.func;
+     &warn.experimental.func;
+     <para>
+      <function>PDOStatement::fetchSingle</function> returns the first column
+      in the next row of a result set as a <literal>string</literal> value.
+     </para>
+     <warning>
+      <para>
+       There is no way to return the second or subsequent columns from a row
+       if you use this method to retrieve data.
+      </para>
+     </warning>
+
+     <example><title>Return first column of the next row</title>
+      <programlisting role="php">
+<![CDATA[
+<?php
+$sth = $dbh->prepare("SELECT name, colour FROM fruit");
+$sth->execute();
+
+/* Fetch the first column from the next row in the result set */
+print("Fetch the first column from the next row in the result set:\n");
+$result = $sth->fetchSingle();
+print("$result\n");
+
+$result = $sth->fetchSingle();
+print("$result\n");
+?>
+]]>
+      </programlisting>
+     </example>
+     &example.outputs;
+     <screen>
+<![CDATA[
+Fetch the first column from the next row in the result set:
+lemon
+orange
+]]>
+     </screen>
 
    </refsect1>
   </refentry>