Define o número de linhas a serem pré-buscadas pelas consultas

# oci_set_prefetch

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

oci_set_prefetch — Define o número de linhas a serem pré-buscadas pelas consultas

### Descrição

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

Define o número de linhas a serem armazenadas em buffer pelas bibliotecas do Oracle Client após uma chamada de consulta bem-sucedida a oci_execute() e para cada solicitação de busca interna subsequente ao banco de dados. Para consultas que retornam um grande número de linhas, o desempenho pode ser significativamente melhorado aumentando a contagem de pré-busca acima do valor padrão oci8.default_prefetch.

A pré-busca é a maneira eficiente da Oracle de retornar mais de uma linha de dados do banco de dados em cada solicitação de rede. Isso pode resultar em melhor utilização da rede e da CPU. O buffer de linhas é interno ao OCI8 e o comportamento das funções de busca do OCI8 permanece inalterado, independentemente da contagem de pré-busca. Por exemplo, oci_fetch_row() sempre retornará uma linha. O buffer de pré-busca é por instrução e não é usado por instruções reexecutadas ou por outras conexões.

Chame oci_set_prefetch() antes de chamar oci_execute().

Uma meta de ajuste é definir o valor de pré-busca para um tamanho razoável para a rede e o banco de dados manipularem. Para consultas que retornam um número muito grande de linhas, a eficiência geral do sistema pode ser melhor se as linhas forem recuperadas do banco de dados em vários blocos (ou seja, definir o valor de pré-busca menor que o número de linhas). Isso permite que o banco de dados manipule as instruções de outros usuários enquanto o script PHP está processando o conjunto atual de linhas.

A pré-busca de consultas foi introduzida no Oracle 8i. REF CURSOR A pré-busca de CURSOR REF foi introduzida no Oracle 11gR2 e ocorre quando o PHP é vinculado às bibliotecas do cliente Oracle 11gR2 (ou posterior). A pré-busca de cursor aninhado foi introduzida no Oracle 11gR2 e requer que tanto as bibliotecas do cliente Oracle quanto o banco de dados sejam da versão 11gR2 ou superior.

A pré-busca não é suportada quando consultas contêm colunas LONG ou LOB. O valor da pré-busca é ignorado e buscas de linha única serão usadas em todas as situações em que a pré-busca não for suportada.

Ao utilizar o Oracle Database 12c, o valor de pré-busca definido pelo PHP pode ser substituído pelo arquivo de configuração `oraaccess.xml` do cliente da Oracle. Consulte a documentação da Oracle para obter mais detalhes.

### Parâmetros

`statement`
  Um identificador de declaração OCI8 válida criada por oci_parse() e executada por oci_execute() ou um identificador de declaração `REF CURSOR`.
`rows`

  O número de linhas a serem pré-buscadas, >= 0

### Valor Retornado

Retorna `true` em caso de sucesso ou `false` em caso de falha.

### Exemplos

Exemplo #1 Alterando o valor de pré-busca padrão para uma consulta

    <?php

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

    $stid = oci_parse($conn, 'SELECT * FROM myverybigtable');
    oci_set_prefetch($stid, 300);  // Defina antes de chamar 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) : "&nbsp;")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

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

    ?>

Exemplo #2 Alterando a pré-busca padrão para uma busca de CURSOR REF

    <?php
    /*
      Crie o procedimento armazenado PL/SQL como:

      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);

    // Altera a pré-busca antes de executar o cursor.
    // A pré-busca do REF CURSOR funciona quando o PHP está vinculado a bibliotecas de cliente Oracle 11gR2 ou posterior
    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) : "&nbsp;")."</td>\n";
        }
        echo "</tr>\n";
    }
    echo "</table>\n";

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

    ?>

Se o PHP OCI8 buscar um CURSOR REF e, em seguida, passar o CURSOR REF de volta para um segundo procedimento PL/SQL para processamento posterior, defina a contagem de pré-busca do CURSOR REF como `0` para evitar que linhas sejam "perdidas" do conjunto de resultados. O valor da pré-busca é o número de linhas extras buscadas em cada solicitação interna do OCI8 para o banco de dados, portanto, defini-lo como `0` significa apenas buscar uma linha por vez.

Exemplo #3 Definindo o valor de pré-busca ao passar um CURSOR REF de volta para o Oracle

    <?php

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

    // Obtém o CURSOR REF
    $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);

    // Exibe duas linhas, mas não pré-busca nenhuma linha extra, caso contrário
    // essas linhas extras não seriam passadas de volta para 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);

    // Passa o CURSOR REF para myproc_use_rc() para realizar mais processamento de dados
    // com o 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);

    ?>

### Veja Também

- Opção INI oci8.default_prefetch

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open