oci-set-prefetch.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 5e41012cfdf8f2eff5fa56de446c7656afac536c Maintainer: yannick Status: ready -->
<!-- Reviewed: yes -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.oci-set-prefetch">
 <refnamediv>
  <refname>oci_set_prefetch</refname>
  <refpurpose>Indique le nombre de lignes qui doivent être lues à l'avance par Oracle</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>bool</type><methodname>oci_set_prefetch</methodname>
   <methodparam><type>resource</type><parameter>statement</parameter></methodparam>
   <methodparam><type>int</type><parameter>rows</parameter></methodparam>
  </methodsynopsis>
  <para>
   Définit le nombre de lignes à précharger par les bibliothèques clientes Oracle
   après un appel réussi à la fonction <function>oci_execute</function> mais aussi
   pour chaque appel aux fonctions internes de récupération de lignes à la base
   de données. Pour les requêtes retournant un grand nombre de lignes, les performances
   peuvent être significativement améliorées en augmentant le nombre de lignes
   à précharger par rapport à la valeur par défaut définie par l'option
   de configuration <link linkend="ini.oci8.default-prefetch">oci8.default_prefetch</link>.
  </para>
  <para>
   Le préchargement est une façon efficace de retourner plus d'une ligne de données
   depuis la base de données pour chaque envoi réseau. Il en retourne une meilleure
   utilisation du réseau mais aussi une meilleure utilisation du CPU.
   Le préchargement de lignes est interne à OCI8 et le comportement des fonctions
   de récupération de données reste inchangé suivant la valeur du compteur de
   préchargement. Par exemple, la fonction <function>oci_fetch_row</function> retournera
   toujours une ligne. Le buffer de préchargement est propre à chaque requête
   et ne sera pas utilisé pour ré-exécuter des requêtes ou par les autres connexions.
  </para>
  <para>
   Il convient d'appeler la fonction <function>oci_set_prefetch</function> avant
   la fonction <function>oci_execute</function>.
  </para>
  <para>
   Un des moyens de gagner en efficacité est de définir la valeur de préchargement
   à une valeur raisonnable en fonction du réseau et de la base de données à gérer.
   Pour les requêtes retournant un très grand nombre de lignes, il convient
   de récupérer l'ensemble des lignes par morceaux (i.e. définit la valeur de
   préchargement à une valeur en dessous du nombre total de lignes). Ceci permet
   à la base de données de gérer les requêtes des autres utilisateurs pendant que le
   script PHP gère le jeu de lignes courant.
  </para>
  <para>
   Le préchargement a été introduit en Oracle 8<emphasis>i</emphasis>.
   Le préchargement <literal>REF CURSOR</literal> a été introduit en
   Oracle 11<emphasis>g</emphasis>R2 et est disponible lorsque PHP est lié
   avec les bibliothèques clientes Oracle 11<emphasis>g</emphasis>R2 (ou supérieur).
   Les curseurs imbriqués de préchargement ont été introduits en Oracle
   11<emphasis>g</emphasis>R2 et nécessitent à la fois les bibliothèques clientes
   Oracle, et une base de données en version 11<emphasis>g</emphasis>R2 (ou supérieur).
  </para>
  <para>
   Le préchargement n'est pas supporté lorsque les requêtes contiennent des colonnes
   de type LONG ou LOB. La valeur de préchargement sera utilisé dans toutes les situations
   où le préchargement est supporté.
  </para>
  <para>
   Lors de l'utilisation de la base de données Oracle 12<emphasis>c</emphasis>,
   le jeu de valeurs préchargées par PHP peut être écrasé par le fichier
   de configuration client d'Oracle <literal>oraaccess.xml</literal>.
   Référez-vous à la documentation d'Oracle pour plus de détails.
  </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>rows</parameter></term>
     <listitem>
      <para>
       Le nombre de lignes à précharger, &gt;=0
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   &return.success;
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Modification de la valeur de préchargement pour une requête</title>
    <programlisting role="php">
<![CDATA[
<?php

$conn = oci_connect('hr', 'welcome', 'localhost/XE');

$stid = oci_parse($conn, 'SELECT * FROM myverybigtable');
oci_set_prefetch($stid, 300);  // A définir avant l'appel à la fonction oci_execute()
oci_execute($stid);

echo "<table border='1'>\n";
while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
    echo "<tr>\n";
    foreach ($row 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>Modification de la valeur de préchargement pour une récupération REF CURSOR</title>
    <programlisting role="php">
<![CDATA[
<?php
/*
  Création de la procédure stockée PL/SQL suivante :

  CREATE OR REPLACE PROCEDURE myproc(p1 OUT SYS_REFCURSOR) AS
  BEGIN
    OPEN p1 FOR SELECT * FROM all_objects WHERE ROWNUM < 5000;
  END;
*/

$conn = oci_connect('hr', 'welcome', 'localhost/XE');

$stid = oci_parse($conn, 'BEGIN myproc(:rc); END;');
$refcur = oci_new_cursor($conn);
oci_bind_by_name($stid, ':rc', $refcur, -1, OCI_B_CURSOR);
oci_execute($stid);

// Modification de la valeur de préchargement avant l'exécution du curseur.
// Le préchargement REF CURSOR fonctionne lorsque PHP est lié avec les bibliothèques clientes
// Oracle 11gR2 (ou supérieur)
oci_set_prefetch($refcur, 200);
oci_execute($refcur);

echo "<table border='1'>\n";
while ($row = oci_fetch_array($refcur, OCI_ASSOC+OCI_RETURN_NULLS)) {
    echo "<tr>\n";
    foreach ($row as $item) {
        echo "    <td>".($item !== null ? htmlentities($item, ENT_QUOTES) : "")."</td>\n";
    }
    echo "</tr>\n";
}
echo "</table>\n";

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

?> 
]]>
    </programlisting>
   </example>
  </para>
  <para>
   Si PHP OCI8 récupère des données depuis un curseur <literal>REF CURSOR</literal>
   puis, retourne le curseur <literal>REF CURSOR</literal> à une seconde
   procédure stockée pour traitement, alors il convient de définir le
   préchargement de <literal>REF CURSOR</literal> à <constant>0</constant>
   afin d'éviter de perdre des lignes du jeu de résultats. La valeur de
   préchargement est le nombre de lignes supplémentaire à récupérer
   pour chaque requête interne OCI8 à la base de données, aussi, le fait de la
   définir à <constant>0</constant> signifie uniquement que nous souhaitons
   récupérer une seule ligne à la fois.
   <example>
    <title>Définition de la valeur de préchargement lorsque l'on retourne
     un curseur <literal>REF CURSOR</literal> à Oracle</title>
    <programlisting role="php">
<![CDATA[
<?php

$conn = oci_connect('hr', 'welcome', 'localhost/orcl');

// Récupération du curseur REF CURSOR
$stid = oci_parse($conn, 'BEGIN myproc(:rc_out); END;');
$refcur = oci_new_cursor($conn);
oci_bind_by_name($stid, ':rc_out', $refcur, -1, OCI_B_CURSOR);
oci_execute($stid);

// Affiche 2 lignes, mais ne précharge pas de lignes supplémentaires
// sinon, ces lignes supplémentaires ne seront pas passées à myproc_use_rc().
oci_set_prefetch($refcur, 0);
oci_execute($refcur);
$row = oci_fetch_array($refcur);
var_dump($row);
$row = oci_fetch_array($refcur);
var_dump($row);

// passe le curseur REF CURSOR à myproc_use_rc() afin d'effectuer d'autres
// traitement sur le jeu de résultats
$stid = oci_parse($conn, 'begin myproc_use_rc(:rc_in); end;'); 
oci_bind_by_name($stid, ':rc_in', $refcur, -1, OCI_B_CURSOR);
oci_execute($stid);

?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>
 
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member>
     l'option de configuration
     <link linkend="ini.oci8.default-prefetch">oci8.default_prefetch</link>
    </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
-->