<?xml version='1.0' encoding='iso-8859-1'?>
<!-- $Revision: 1.11 $ -->
<!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc. -->
  <refentry id="function.PDOStatement-fetch">
   <refnamediv>
    <refname>PDOStatement::fetch</refname>
    <refpurpose>
     Fetches the next row from a result set
    </refpurpose>
   </refnamediv>
   <refsect1 role="description">
    &reftitle.description;
    <methodsynopsis>
     <type>mixed</type><methodname>PDOStatement::fetch</methodname>
     <methodparam choice="opt"><type>int</type><parameter>fetch_style</parameter></methodparam>
     <methodparam choice="opt"><type>int</type><parameter>cursor_orientation</parameter></methodparam>
     <methodparam choice="opt"><type>int</type><parameter>cursor_offset</parameter></methodparam>
    </methodsynopsis>

    <para>
     Fetches a row from a result set associated with a PDOStatement object. The
     <parameter>fetch_style</parameter> parameter determines how PDO returns
     the row.
    </para>
   </refsect1>

   <refsect1 role="parameters">
    &reftitle.parameters;
    <para>
     <variablelist>
      <varlistentry>
       <term><parameter>fetch_style</parameter></term>
       <listitem>
        <para>
         Controls how the next row will be returned to the caller. This value
         must be one of the <literal>PDO::FETCH_*</literal> constants,
         defaulting to <literal>PDO::FETCH_BOTH</literal>.
         <itemizedlist>
          <listitem><para>
           <literal>PDO::FETCH_ASSOC</literal>: returns an array indexed by column
           name as returned in your result set
          </para></listitem>
          <listitem><para>
           <literal>PDO::FETCH_BOTH</literal> (default): returns an array indexed by
           both column name and 0-indexed column number as returned in your
           result set
          </para></listitem>
          <listitem><para>
           <literal>PDO::FETCH_BOUND</literal>: returns &true; and assigns the
           values of the columns in your result set to the PHP variables to which
           they were bound with the <function>PDOStatement::bindParam</function>
           method
          </para></listitem>
          <listitem><para>
           <literal>PDO::FETCH_CLASS</literal>: returns a new instance of the
           requested class, mapping the columns of the result set to named
           properties in the class. If <parameter>fetch_style</parameter>
           includes PDO::FETCH_CLASSTYPE (e.g. <literal>PDO::FETCH_CLASS |
           PDO::FETCH_CLASSTYPE</literal>) then the name of the class is
           determined from a value of the first column.
          </para></listitem>
          <listitem><para>
           <literal>PDO::FETCH_INTO</literal>: updates an existing instance
           of the requested class, mapping the columns of the result set to
           named properties in the class
          </para></listitem>
          <listitem><para>
           <literal>PDO::FETCH_LAZY</literal>: combines
           <literal>PDO::FETCH_BOTH</literal> and <literal>PDO::FETCH_OBJ</literal>,
           creating the object variable names as they are accessed
          </para></listitem>
          <listitem><para>
           <literal>PDO::FETCH_NUM</literal>: returns an array indexed by column
           number as returned in your result set, starting at column 0
          </para></listitem>
          <listitem><para>
           <literal>PDO::FETCH_OBJ</literal>: returns an anonymous object with
           property names that correspond to the column names returned in your
           result set
          </para></listitem>
         </itemizedlist>
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term><parameter>cursor_orientation</parameter></term>
       <listitem>
        <para>
         For a PDOStatement object representing a scrollable cursor, this
         value determines which row will be returned to the caller. This value
         must be one of the <literal>PDO::FETCH_ORI_*</literal> constants,
         defaulting to <literal>PDO::FETCH_ORI_NEXT</literal>. To request a
         scrollable cursor for your PDOStatement object, you must set the
         <literal>PDO::ATTR_CURSOR</literal> attribute to
         <literal>PDO::CURSOR_SCROLL</literal> when you prepare the SQL
         statement with <function>PDO::prepare</function>.
        </para>
       </listitem>
      </varlistentry>
      <varlistentry>
       <term><parameter>offset</parameter></term>
       <listitem>
        <para> 
         For a PDOStatement object representing a scrollable cursor for which
         the <literal>cursor_orientation</literal> parameter is set to
         <literal>PDO::FETCH_ORI_ABS</literal>, this value specifies the
         absolute number of the row in the result set that shall be fetched.
        </para>
        <para>
         For a PDOStatement object representing a scrollable cursor for which
         the <literal>cursor_orientation</literal> parameter is set to
         <literal>PDO::FETCH_ORI_REL</literal>, this value specifies the
         row to fetch relative to the cursor position before
         <function>PDOStatement::fetch</function> was called.
        </para>
       </listitem>
      </varlistentry>
     </variablelist>
    </para>
   </refsect1>

   <refsect1 role="examples">
    &reftitle.examples;
    <para>
     <example><title>Fetching rows using different fetch styles</title>
      <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");
$result = $sth->fetch(PDO::FETCH_ASSOC);
print_r($result);
print("\n");

print("PDO::FETCH_BOTH: ");
print("Return next row as an array indexed by both column name and number\n");
$result = $sth->fetch(PDO::FETCH_BOTH);
print_r($result);
print("\n");

print("PDO::FETCH_LAZY: ");
print("Return next row as an anonymous object with column names as properties\n");
$result = $sth->fetch(PDO::FETCH_LAZY);
print_r($result);
print("\n");

print("PDO::FETCH_OBJ: ");
print("Return next row as an anonymous object with column names as properties\n");
$result = $sth->fetch(PDO::FETCH_OBJ);
print $result->NAME;
print("\n");
?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
PDO::FETCH_ASSOC: Return next row as an array indexed by column name
Array
(
    [NAME] => apple
    [COLOUR] => red
)

PDO::FETCH_BOTH: Return next row as an array indexed by both column name and number
Array
(
    [NAME] => banana
    [0] => banana
    [COLOUR] => yellow
    [1] => yellow
)

PDO::FETCH_LAZY: Return next row as an anonymous object with column names as properties
PDORow Object
(
    [NAME] => orange
    [COLOUR] => orange
)

PDO::FETCH_OBJ: Return next row as an anonymous object with column names as properties
kiwi
]]>
      </screen>
     </example>
     <example><title>Fetching rows with a scrollable cursor</title>
      <programlisting role="php">
<![CDATA[
<?php
function readDataForwards($dbh) {
  $sql = 'SELECT hand, won, bet FROM mynumbers ORDER BY BET';
  try {
    $stmt = $dbh->prepare($sql, array(PDO::ATTR_CURSOR, PDO::CURSOR_SCROLL));
    $stmt->execute();
    while ($row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_NEXT)) {
      $data = $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
      print $data;
    }
    $stmt = null;
  }
  catch (PDOException $e) {
    print $e->getMessage();
  }
}
function readDataBackwards($dbh) {
  $sql = 'SELECT hand, won, bet FROM mynumbers ORDER BY bet';
  try {
    $stmt = $dbh->prepare($sql, array(PDO::ATTR_CURSOR, PDO::CURSOR_SCROLL));
    $stmt->execute();
    $row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_LAST);
    do {
      $data = $row[0] . "\t" . $row[1] . "\t" . $row[2] . "\n";
      print $data;
    } while ($row = $stmt->fetch(PDO::FETCH_NUM, PDO::FETCH_ORI_PRIOR));
    $stmt = null;
  }
  catch (PDOException $e) {
    print $e->getMessage();
  }
}

print "Reading forwards:\n";
readDataForwards($conn);

print "Reading backwards:\n";
readDataBackwards($conn);
?>
]]>
      </programlisting>
      &example.outputs;
      <screen>
<![CDATA[
Reading forwards:
21    10    5
16    0     5
19    20    10

Reading backwards:
19    20    10
16    0     5
21    10    5
]]>
      </screen>
     </example>

    </para>
   </refsect1>

   <refsect1 role="seealso">
    &reftitle.seealso;
    <para>
     <simplelist>
      <member><function>PDO::query</function></member>
      <member><function>PDOStatement::fetchAll</function></member>
      <member><function>PDOStatement::fetchColumn</function></member>
      <member><function>PDOStatement::prepare</function></member>
      <member><function>PDOStatement::setFetchMode</function></member>
     </simplelist>
    </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
-->