oci-set-prefetch.xml

<?xml version="1.0" encoding="utf-8" ?>
<!-- $Revision$ -->
<!-- EN-Revision: 5e41012cfdf8f2eff5fa56de446c7656afac536c Maintainer: shimooka Status: ready -->
<!-- Credits: mumumu -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.oci-set-prefetch">
 <refnamediv>
  <refname>oci_set_prefetch</refname>
  <refpurpose>クエリがプリフェッチする行数を設定する</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>
   <function>oci_execute</function>
   のコール、およびそれに伴う内部的なデータベースへのリクエストがすべて成功した後に
   Oracle Client ライブラリがバッファに取り込む行数を設定します。
   クエリが返す結果の行数が多くなる場合は、プリフェッチ行数をデフォルトの
   <link linkend="ini.oci8.default-prefetch">oci8.default_prefetch</link>
   より大きくしておくとパフォーマンスが劇的に向上します。
  </para>
  <para>
   プリフェッチは、Oracle がデータベースからデータを取得する際の効率的な方法で、
   一回のネットワークリクエストで複数の行を取得します。こうすれば、
   ネットワークや CPU の利用効率がよくなります。
   行のバッファリングは OCI8 の内部的なものであり、
   プリフェッチ行数が変わっても OCI8 のフェッチ関数群の挙動は変わりません。
   たとえば、<function>oci_fetch_row</function> は、常に一行だけを返します。
   プリフェッチバッファはステートメント単位で設定されるものであり、
   ステートメントを再実行したときや他の接続から実行したときには使われません。
  </para>
  <para>
   <function>oci_set_prefetch</function> は
   <function>oci_execute</function> の前にコールします。
  </para>
  <para>
   ネットワークやデータベースの状況を考慮して、
   プリフェッチの値を適切な大きさに設定することがチューニングの目標です。
   大量の行を返すクエリの場合は、データベースからの行の取得を
   いくつかの塊に分けて行うとシステム全体の効率が良くなるかもしれません
   (つまり、プリフェッチの値を行数より小さめに設定するということです)。
   こうすれば、PHP スクリプトが現在の行を処理している間にも
   データベースが別のユーザーからのステートメントを処理できるようになります。
  </para>
  <para>
   クエリのプリフェッチが導入されたのは、Oracle 8<emphasis>i</emphasis> からです。
   REF CURSOR のプリフェッチが導入されたのは Oracle 11<emphasis>g</emphasis>R2 からで、
   PHP を Oracle 11<emphasis>g</emphasis>R2 以降のクライアントライブラリとリンクすれば使えます。
   ネストしたカーソルのプリフェッチが導入されたのは Oracle 11<emphasis>g</emphasis>R2 からで、
   これを使うには Oracle クライアントライブラリと接続先のデータベースがどちらも
   11<emphasis>g</emphasis>R2 以降でなければなりません。
  </para>
  <para>
   プリフェッチは、LONG あるいは LOB 列を含むクエリには対応していません。
   プリフェッチに対応していないクエリの場合はプリフェッチの値は無視され、
   どんな場合でも一行単位でフェッチします。
  </para>
  <para>
   Oracle Database 12<emphasis>c</emphasis> では、PHP で設定したプリフェッチの値を
   Oracle のクライアント設定ファイル <literal>oraaccess.xml</literal> で上書きできます。
   詳細は、Oracle のドキュメントを参照ください。
  </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>
       プリフェッチする行数。&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>クエリのデフォルトプリフェッチ値の変更</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);  // 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);

?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>REF CURSOR のデフォルトプリフェッチの変更</title>
    <programlisting role="php">
<![CDATA[
<?php
/*
  下記のようにして 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);

// プリフェッチはカーソルの実行前に変更します。
// REF CURSOR のプリフェッチが使えるのは、PHP を Oracle 11R2 以降のクライアントライブラリとリンクしたときです。
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);

?> 
]]>
    </programlisting>
   </example>
  </para>
  <para>
   PHP OCI8 で REF CURSOR からフェッチした内容を別の
   PL/SQL プロシージャに渡すときには、REF CURSOR
   のプリフェッチ行数を <constant>0</constant>
   に設定して行が結果セットから "失われる" ことを防ぎます。
   プリフェッチの値は OCI8 内部でのデータベースへのリクエスト時に余計に取得する行数です。
   つまり、<constant>0</constant> に設定すると一度に一行だけ取得するということになります。
   <example>
    <title>REF CURSOR を Oracle に戻すときのプリフェッチの設定</title>
    <programlisting role="php">
<![CDATA[
<?php

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

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

// ふたつの行を表示しますが、それ以上の余計な行はプリフェッチしません。
// 余計な行は 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);

// REF CURSOR を myproc_use_rc() に渡して、
// 結果セットに対してさらにデータ処理を行います
$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>
     <link linkend="ini.oci8.default-prefetch">oci8.default_prefetch</link>
     ini オプション
    </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
-->