<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision: 297028 $ -->
<refentry xml:id="function.oci-fetch-all" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>oci_fetch_all</refname>
  <refpurpose>Fetches multiple rows from a query into a two-dimensional array</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>int</type><methodname>oci_fetch_all</methodname>
   <methodparam><type>resource</type><parameter>statement</parameter></methodparam>
   <methodparam><type>array</type><parameter role="reference">output</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>skip</parameter><initializer>0</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>maxrows</parameter><initializer>-1</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer><constant>OCI_FETCHSTATEMENT_BY_COLUMN</constant> + <constant>OCI_ASSOC</constant></initializer></methodparam>
  </methodsynopsis>
  <para>
   Fetches multiple rows from a query into a two-dimensional array.
   By default, all rows are returned.
  </para>
  <para>
   This function can be called only once for each query executed
   with <function>oci_execute</function>.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>statement</parameter></term>
     <listitem>
       &oci.arg.statement.id;
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>output</parameter></term>
     <listitem>
      <para>
       The variable to contain the returned rows.
      </para>
      <para>
        LOB columns are returned as strings, where Oracle supports
        conversion.
      </para>
      <para>
        See <function>oci_fetch_array</function> for more information
        on how data and types are fetched.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>skip</parameter></term>
     <listitem>
      <para>
       The number of initial rows to discard when fetching the
       result. The default value is 0, so the first row onwards is
       returned.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>maxrows</parameter></term>
     <listitem>
      <para>
       The number of rows to return.  The default is -1 meaning return
       all the rows from <parameter>skip</parameter> + 1 onwards.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>flags</parameter></term>
     <listitem>
      <para>
       Parameter <parameter>flags</parameter> indicates the array
       structure and whether associative arrays should be used.
       <table>
        <title><function>oci_fetch_all</function> Array Structure Modes</title>
        <tgroup cols="2">
         <thead>
          <row>
           <entry>Constant</entry>
           <entry>Description</entry>
          </row>
         </thead>
         <tbody>
          <row>
           <entry><constant>OCI_FETCHSTATEMENT_BY_ROW</constant></entry>
           <entry>The outer array will contain one sub-array per query
           row.</entry>
          </row>
          <row>
           <entry><constant>OCI_FETCHSTATEMENT_BY_COLUMN</constant></entry>
           <entry>The outer array will contain one sub-array per query
           column. This is the default.</entry>
          </row>
         </tbody>
        </tgroup>
       </table>
      </para>
      <para>
        Arrays can be indexed by column heading or numerically.
       <table>
        <title><function>oci_fetch_all</function> Array Index Modes</title>
        <tgroup cols="2">
         <thead>
          <row>
           <entry>Constant</entry>
           <entry>Description</entry>
          </row>
         </thead>
         <tbody>
          <row>
           <entry><constant>OCI_NUM</constant></entry>
           <entry>Numeric indexes are used for each column's array.</entry>
          </row>
          <row>
           <entry><constant>OCI_ASSOC</constant></entry>
           <entry>Associative indexes are used for each column's
           array. This is the default.</entry>
          </row>
         </tbody>
        </tgroup>
       </table>
      </para>
      <para>
       Use the addition operator &quot;+&quot; to choose a combination
       of array structure and index modes.
      </para>
      <para>
       Oracle's default, non-case sensitive column names will have
       uppercase array keys.  Case-sensitive column names will have
       array keys using the exact column case.
       Use <function>var_dump</function>
       on <parameter>output</parameter>to verify the appropriate case
       to use for each query.
      </para>
      <para>
        Queries that have more than one column with the same name
        should use column aliases.  Otherwise only one of the columns
        will appear in an associative array.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Returns the number of rows in <parameter>output</parameter>, which
   may be 0 or more, &return.falseforfailure;.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>oci_fetch_all</function> example</title>
    <programlisting role="php">
<![CDATA[
<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
    $e = oci_error();
    trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$stid = oci_parse($conn, 'SELECT POSTAL_CODE, CITY FROM locations WHERE ROWNUM < 3');
oci_execute($stid);

$nrows = oci_fetch_all($stid, $res);

echo "$nrows rows fetched<br>\n";
var_dump($res);

// var_dump output is:
//    2 rows fetched
//    array(2) {
//      ["POSTAL_CODE"]=>
//      array(2) {
//        [0]=>
//        string(6) "00989x"
//        [1]=>
//        string(6) "10934x"
//      }
//      ["CITY"]=>
//      array(2) {
//        [0]=>
//        string(4) "Roma"
//        [1]=>
//        string(6) "Venice"
//      }
//    }

// Pretty-print the results
echo "<table border='1'>\n";
foreach ($res as $col) {
    echo "<tr>\n";
    foreach ($col as $item) {
        echo "    <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;")."</td>\n";
    }
    echo "</tr>\n";
}
echo "</table>\n";

oci_free_statement($stid);
oci_close($conn);

?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title><function>oci_fetch_all</function> example with <constant>OCI_FETCHSTATEMENT_BY_ROW</constant></title>
    <programlisting role="php">
<![CDATA[
<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
    $e = oci_error();
    trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$stid = oci_parse($conn, 'SELECT POSTAL_CODE, CITY FROM locations WHERE ROWNUM < 3');
oci_execute($stid);

$nrows = oci_fetch_all($stid, $res, null, null, OCI_FETCHSTATEMENT_BY_ROW);

echo "$nrows rows fetched<br>\n";
var_dump($res);

// Output is:
//    2 rows fetched
//    array(2) {
//      [0]=>
//      array(2) {
//        ["POSTAL_CODE"]=>
//        string(6) "00989x"
//        ["CITY"]=>
//        string(4) "Roma"
//      }
//      [1]=>
//      array(2) {
//        ["POSTAL_CODE"]=>
//        string(6) "10934x"
//        ["CITY"]=>
//        string(6) "Venice"
//      }
//    }

oci_free_statement($stid);
oci_close($conn);

?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title><function>oci_fetch_all</function> with <constant>OCI_NUM</constant></title>
    <programlisting role="php">
<![CDATA[
<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE');
if (!$conn) {
    $e = oci_error();
    trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
}

$stid = oci_parse($conn, 'SELECT POSTAL_CODE, CITY FROM locations WHERE ROWNUM < 3');
oci_execute($stid);

$nrows = oci_fetch_all($stid, $res, null, null, OCI_FETCHSTATEMENT_BY_ROW + OCI_NUM);

echo "$nrows rows fetched<br>\n";
var_dump($res);

// Output is:
//    2 rows fetched
//    array(2) {
//      [0]=>
//      array(2) {
//        [0]=>
//        string(6) "00989x"
//        [1]=>
//        string(4) "Roma"
//      }
//      [1]=>
//      array(2) {
//        [0]=>
//        string(6) "10934x"
//        [1]=>
//        string(6) "Venice"
//      }
//    }

oci_free_statement($stid);
oci_close($conn);

?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
     Using <parameter>skip</parameter> is very inefficient.  All the
     rows to be skipped are included in the result set that is
     returned from the database to PHP.  They are then discarded.  It
     is more efficient to use SQL to restrict the offset and range of
     rows in the query.  See <function>oci_fetch_array</function> for
     an example.
   </para>
  </note>
  <note>
   <para>
    Queries that return a large number of rows can be more memory
    efficient if a single-row fetching function
    like <function>oci_fetch_array</function> is used.
   </para>
  </note>
  <note>
   &oci.use.setprefetch;
  </note>
  <note>
   <para>
    In PHP versions before 5.0.0 you must
    use <function>ocifetchstatement</function>
    instead. &oci.name.compat.note;
   </para>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>oci_fetch</function></member>
    <member><function>oci_fetch_array</function></member>
    <member><function>oci_fetch_assoc</function></member>
    <member><function>oci_fetch_object</function></member>
    <member><function>oci_fetch_row</function></member>
    <member><function>oci_set_prefetch</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:"~/.phpdoc/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
-->