oci_set_prefetch
(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)
oci_set_prefetch — Indique le nombre de lignes qui doivent être lues à l'avance par Oracle
Description
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 oci_fetch_row() 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.
Il convient d'appeler la fonction oci_set_prefetch() avant
la fonction oci_execute().
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.
Le préchargement a été introduit en Oracle 8i.
Le préchargement REF CURSOR a été introduit en
Oracle 11gR2 et est disponible lorsque PHP est lié
avec les bibliothèques clientes Oracle 11gR2 (ou supérieur).
Les curseurs imbriqués de préchargement ont été introduits en Oracle
11gR2 et nécessitent à la fois les bibliothèques clientes
Oracle, et une base de données en version 11gR2 (ou supérieur).
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é.
Lors de l'utilisation de la base de données Oracle 12c,
le jeu de valeurs préchargées par PHP peut être écrasé par le fichier
de configuration client d'Oracle oraaccess.xml.
Référez-vous à la documentation d'Oracle pour plus de détails.
Liste de paramètres
statement-
Un identifiant de requête OCI8
créé par la fonction oci_parse() et exécuté par la fonction
oci_execute(), ou un identifiant de requête REF
CURSOR.
rows-
Le nombre de lignes à précharger, >=0
Valeurs de retour
Cette fonction retourne true en cas de succès ou false si une erreur survient.
Exemples
Exemple #1 Modification de la valeur de préchargement pour une requête
<?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);
?>
Exemple #2 Modification de la valeur de préchargement pour une récupération REF CURSOR
<?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);
?>
Si PHP OCI8 récupère des données depuis un curseur REF CURSOR
puis, retourne le curseur REF CURSOR à une seconde
procédure stockée pour traitement, alors il convient de définir le
préchargement de REF CURSOR à 0
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 à 0 signifie uniquement que nous souhaitons
récupérer une seule ligne à la fois.
Exemple #3 Définition de la valeur de préchargement lorsque l'on retourne
un curseur REF CURSOR à Oracle
<?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);
?>
