oci-fetch-all.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: d33a6756e7a94bc06164d2a97bb0a3ffa19e3471 Maintainer: sammywg Status: ready -->
<!-- Reviewed: yes -->
<!-- Rev-Revision: 1.0 Reviewer: samesch -->
<refentry xml:id="function.oci-fetch-all" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>oci_fetch_all</refname>
  <refpurpose>
   Ruft mehrere Datensätze einer Abfrage in ein zweidimensionales Array ab
  </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>offset</parameter><initializer>0</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>limit</parameter><initializer>-1</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer>OCI_FETCHSTATEMENT_BY_COLUMN | OCI_ASSOC</initializer></methodparam>
  </methodsynopsis>
  <para>
   Ruft mehrere Datensätze einer Abfrage in ein zweidimensionales Array ab.
   Standardmäßig werden alle Datensätze zurückgegeben.
  </para>
  <para>
   Diese Funktion kann nur einmal für jede Abfrage, die mit
   <function>oci_execute</function> ausgeführt wurde, aufgerufen werden.
  </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>
       Die Variable, die die zurückgegebenen Datensätze enthalten wird.
      </para>
      <para>
       LOB-Spalten werden als Zeichenketten zurückgegeben, sofern Oracle die
       Umwandlung unterstützt.
      </para>
      <para>
       Informationen, wie Daten und Typen abgerufen werden, sind der
       Dokumentation von <function>oci_fetch_array</function> zu entnehmen.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>offset</parameter></term>
     <listitem>
      <para>
       Die Anzahl der zu verwerfenden Anfangsdatensätze beim Abrufen des
       Ergebnisses. Standardwert ist 0, sodass vom ersten Datensatz an
       zurückgegeben wird.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>limit</parameter></term>
     <listitem>
      <para>
       Die Anzahl der zurückzugebenden Datensätze. Der Standardwert ist -1,
       was bedeutet, dass alle Datensätze von <parameter>offset</parameter> + 1
       an zurückgegeben werden.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>flags</parameter></term>
     <listitem>
      <para>
       Der Parameter <parameter>flags</parameter> legt die Array-Struktur
       fest und ob assoziative Arrays verwendet werden sollen.
       <table>
        <title>Struktur-Modi für das <function>oci_fetch_all</function>-Array</title>
        <tgroup cols="2">
         <thead>
          <row>
           <entry>Konstante</entry>
           <entry>Beschreibung</entry>
          </row>
         </thead>
         <tbody>
          <row>
           <entry><constant>OCI_FETCHSTATEMENT_BY_ROW</constant></entry>
           <entry>
            Das äußere Array wird ein Unterarray pro Abfragedatensatz
            enthalten.
           </entry>
          </row>
          <row>
           <entry><constant>OCI_FETCHSTATEMENT_BY_COLUMN</constant></entry>
           <entry>
            Das äußere Array wird ein Unterarray pro Abfragespalte enthalten.
            Das ist der Standardwert.
           </entry>
          </row>
         </tbody>
        </tgroup>
       </table>
      </para>
      <para>
       Arrays können entweder nach Spaltennamen oder numerisch indexiert
       werden. Nur ein Index-Modus wird zurückgegeben.
       <table>
        <title>Index-Modi für das <function>oci_fetch_all</function>-Array</title>
        <tgroup cols="2">
         <thead>
          <row>
           <entry>Konstante</entry>
           <entry>Beschreibung</entry>
          </row>
         </thead>
         <tbody>
          <row>
           <entry><constant>OCI_NUM</constant></entry>
           <entry>
            Numerische Indizes werden für das Array jeder Spalte verwendet.
           </entry>
          </row>
          <row>
           <entry><constant>OCI_ASSOC</constant></entry>
           <entry>
            Assoziative Indizes werden für das Array jeder Spalte verwendet.
            Das ist der Standardwert.
           </entry>
          </row>
         </tbody>
        </tgroup>
       </table>
      </para>
      <para>
       Der Additionsoperator &quot;+&quot; ist zu verwenden, um eine
       Kombination von Array-Struktur- und Index-Modi zu wählen.
      </para>
      <para>
       Für Spaltennamen, die Groß- und Kleinschreibung nicht unterscheiden,
       was bei Oracle der Standard ist, werden Arrayschlüssel in
       Großschreibung verwendet. Spalten, die Groß- und Kleinschreibung
       unterscheiden, verwenden die genaue Schreibweise.
       <function>var_dump</function> kann auf <parameter>output</parameter>
       angewendet werden, um die richtige Schreibweise für jede Abfrage zu
       prüfen.
      </para>
      <para>
       Abfragen, die mehr als eine Spalte mit demselben Namen haben, sollten
       Spaltenaliase verwenden. Andernfalls wird nur eine der Spalten in
       einem assoziativen Array auftauchen.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Gibt die Anzahl der Datensätze in <parameter>output</parameter> zurück,
   die 0 oder mehr sein kann.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>oci_fetch_all</function>-Beispiel</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 Datensätze abgerufen<br>\n";
var_dump($res);

// die var_dump Ausgabe ist:
//    2 Datensätze abgerufen
//    array(2) {
//      ["POSTAL_CODE"]=>
//      array(2) {
//        [0]=>
//        string(6) "00989x"
//        [1]=>
//        string(6) "10934x"
//      }
//      ["CITY"]=>
//      array(2) {
//        [0]=>
//        string(4) "Rom"
//        [1]=>
//        string(6) "Venedig"
//      }
//    }

// ordentliche Ausgabe der Ergebnisse
echo "<table border='1'>\n";
foreach ($res as $col) {
    echo "<tr>\n";
    foreach ($col as $item) {
        echo "    <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : "")."</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>-Beispiel mit <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 Datensätze abgerufen<br>\n";
var_dump($res);

// die Ausgabe ist:
//    2 Datensätze abgerufen
//    array(2) {
//      [0]=>
//      array(2) {
//        ["POSTAL_CODE"]=>
//        string(6) "00989x"
//        ["CITY"]=>
//        string(4) "Rom"
//      }
//      [1]=>
//      array(2) {
//        ["POSTAL_CODE"]=>
//        string(6) "10934x"
//        ["CITY"]=>
//        string(6) "Venedig"
//      }
//    }

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

?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title><function>oci_fetch_all</function> mit <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 Datensätze abgerufen<br>\n";
var_dump($res);

// die Ausgabe ist:
//    2 Datensätze abgerufen
//    array(2) {
//      [0]=>
//      array(2) {
//        [0]=>
//        string(6) "00989x"
//        [1]=>
//        string(4) "Rom"
//      }
//      [1]=>
//      array(2) {
//        [0]=>
//        string(6) "10934x"
//        [1]=>
//        string(6) "Venedig"
//      }
//    }

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

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

 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    Die Verwendung von <parameter>offset</parameter> ist sehr ineffizient. All
    die zu überspringenden Datensätze sind in der Ergebnismenge, die von der
    Datenbank an PHP zurückgegeben wird. Dann werden sie verworfen. Es ist
    effizienter SQL zu nutzen, um den Offset und den Bereich der Datensätze
    in der Abfrage zu beschränken. Ein Beispiel kann der Dokumentation von
    <function>oci_fetch_array</function> entnommen werden.
   </para>
  </note>
  <note>
   <para>
    Abfragen, die eine große Anzahl von Datensätze liefern, sind
    speichereffizienter, wenn eine Funktion wie
    <function>oci_fetch_array</function> verwendet wird, die nur einzelne
    Datensätze abruft.
   </para>
  </note>
  <note>
   &oci.use.setprefetch;
  </note>
  <note>
   <para>
    Diese Funktion gibt keine Datensätze aus einer impliziten Ergebnismenge
    einer Oracle 12<emphasis>c</emphasis>-Datenbank zurück. Verwenden Sie
    stattdessen die Funktion <function>oci_fetch_array</function>.
   </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
-->