# oci_set_prefetch

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_set_prefetch — Establece el número de filas a precargar mediante consultas

### Descripción

oci_set_prefetch(resource `$statement`, int `$rows`): bool

Establece el número de filas que las bibliotecas de Oracle Client almacenará en búfer después de una llamada exitosa a oci_execute() y por cada petición de obtención interna subsigiente a la base de datos. Para consultas que devuelven un gran número de filas, se puede mejorar significativamente el rendimiento aumentando el número de precarga sobre el valor predeterminado de oci8.default_prefetch.

La precarga es la forma eficiente de Oracle de devolver más de una fila de datos desde la base de datos en cada petición de red. Esto puede resultar en un uso mejor de la red y la CPU. El almacenamiento en búder de filas es interno a OCI8 y el comportamiento de las funciones de obtención de OCI8 no se modifica a pesar del número de precargas. Por ejemplo, oci_fetch_row() siempre devolverá una fila. El almancenamiento en búfer de las precargas se realiza en función de cada sentencia y no es utilizado por sentencias reejecutadas o por otras conexiones.

Se ha de llamar a oci_set_prefetch() antes de invocar a oci_execute().

Un objetivo para el ajuste es establecer el valor de precarga a un tamaño razonable que pueda manejar la red y la base de datos. Para consultas que devuelven un número de filas muy grande, se podría mejorar la eficiencia total del sistema si las filas son obtenidas de la base de datos en varios trozos (esto es, establecer el valor de precarga menor que el número de filas). Esto permite que la base de datos maneje otras sentencias de usuarios mientras que el script de PHP está procesando el conjunto de filas actual.

La precarga de consultas se introdujo en Oracle 8i. La precarga de REF CURSOR se introdujo en Oracle 11gR2 y sucede cuando PHP está vinculado con las bibliotecas cliente de Oracle 11gR2 (o posterior). La precarga de cursores anidados fue introducida en Oracle 11gR2 y requiere que las bibliotecas de Oracle Client y las bases de datos sean la versión 11gR2 o posterior.

La precarga no está soportada cuando las consultas contienen columnas LONG o LOB. El valor de la precarga será ignorado y se usará la obtención de una única fila en todas las situaciones donde no esté soportada la precarga.

Al usar Oracle Database 12c, el valor precargado establecido por PHP puede ser sobrescrito por el fichero de configuración de del cliente `oraaccess.xml` de Oracle. Consulte la documentación de Oracle para más detalles.

### Parámetros

`statement`

  Un identificador de sentencia de OCI8 válido creado por oci_parse() y ejecutado por oci_execute(), o un identificador de sentencia de `REF CURSOR`.

`rows`

  El número de filas que van a se precargadas, >= 0

### Valores devueltos

Devuelve `true` en caso de éxito o `false` en caso de error.

### Historial de cambios

Versión | Descripción
--- | ---
5.3.2 (PECL OCI8 1.4) | Antes de esta versión, `rows` debe ser >= 1.
5.3.0 (PECL OCI8 1.3.4) | Antes de esta versión, la precarga estaba limitada al menor valor de `rows` filas y 1024 * `rows` bytes. La restricción del tamaño de bytes ahora ha sido eliminada.

### Ejemplos

Ejemplo #1 Cambiar el valor de precarga predeterminado para una consulta

`<?php
$conn = oci_connect('hr', 'welcome', 'localhost/XE');
$stid = oci_parse($conn, 'SELECT * FROM myverybigtable');
oci_set_prefetch($stid, 300); // Establecer antes de llamar a 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);
?>`

Ejemplo #2 Cambiar la precarga predeterminada para la obtención de un REF CURSOR

`<?php
/*
Crear el procedimiento almacenado PL/SQL:
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);
// Cambiar la precarga antes de ejecutar el cursor.
// La precarga de REF CURSOR funciona cuando PHP está vinculado con las bibliotecas cliente de Oracle 11gR2 o posteriores
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 OCI8 de PHP realiza la obtención desde un REF CURSOR y luego pasa el REF CURSOR a un segundo procedimiento de PL/SQL para su procesamiento posterior, establezca el número de precargas de REF CURSOR a `0` para evitar que las filas se "pierdan" en el conjunto de resultados. El valor de la precarga es el número de filas extra obtenidas en cada petición interna de OCI8 para la base de datos, por lo que establecerlo a `0` significa que únicamente se obtiene una fila cada vez.

Ejemplo #3 Establecer el valor de precarga cuando se vuelve a pasar un REF CURSOR a Oracle

`<?php
$conn = oci_connect('hr', 'welcome', 'localhost/orcl');
// obtener el 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);
// Mostrar dos filas, pero no precargar ninguna fila extra, si no,
// esas filas extra no se pasarán de nuevo a myproc_use_rc().
// Un valor de precarga de 0 está permitido en PHP 5.3.2 y PECL OCI8 1.4
oci_set_prefetch($refcur, 0);
oci_execute($refcur);
$row = oci_fetch_array($refcur);
var_dump($row);
$row = oci_fetch_array($refcur);
var_dump($row);
// pasar el REF CURSOR a myproc_use_rc() para porcesar más datos
// con el conjunto de resultados
$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);
?>`

### Ver también

- La opción ini oci8.default_prefetch