From a48bfbee2a121bdf25ceee2946aa27728e611365 Mon Sep 17 00:00:00 2001
From: Christopher Jones <sixd@php.net>
Date: Wed, 19 Mar 2014 19:06:27 +0000
Subject: [PATCH] Add common use case example; mention oci_fetch_all mode
 exclusivity; add notes about LOB peak memory usage.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@333038 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/oci8/examples.xml                   | 48 +++++++++++++++++--
 reference/oci8/functions/oci-bind-by-name.xml | 24 ++++++----
 reference/oci8/functions/oci-fetch-all.xml    |  3 +-
 reference/oci8/functions/oci-fetch-array.xml  |  4 +-
 4 files changed, 64 insertions(+), 15 deletions(-)

diff --git a/reference/oci8/examples.xml b/reference/oci8/examples.xml
index 275fe72098..bdbdaaa2d8 100644
--- a/reference/oci8/examples.xml
+++ b/reference/oci8/examples.xml
@@ -107,7 +107,46 @@ oci_close($conn);
  </example>
 
  <example>
-  <title>Inserting data into a CLOB column</title>
+  <title>Binding in the WHERE clause of a query</title>
+  <para>
+   This shows a single scalar bind.
+  </para>
+  <programlisting role="php">
+<![CDATA[
+<?php
+
+$conn = oci_connect("hr", "hrpwd", "localhost/XE");
+if (!$conn) {
+    $m = oci_error();
+    trigger_error(htmlentities($m['message']), E_USER_ERROR);
+}
+
+$sql = 'SELECT last_name FROM employees WHERE department_id = :didbv ORDER BY last_name';
+$stid = oci_parse($conn, $sql);
+$didbv = 60;
+oci_bind_by_name($stid, ':didbv', $didbv);
+oci_execute($stid);
+while (($row = oci_fetch_array($stid, OCI_ASSOC)) != false) {
+    echo $row['LAST_NAME'] ."<br>\n";
+}
+
+// Output is
+//    Austin
+//    Ernst
+//    Hunold
+//    Lorentz
+//    Pataballa
+
+oci_free_statement($stid);
+oci_close($conn);
+
+?>
+]]>
+  </programlisting>
+ </example>
+
+ <example>
+  <title>Inserting and fetching a CLOB</title>
   <para>
    For large data use binary long object (BLOB) or character long
    object (CLOB) types.  This example uses CLOB.
@@ -149,9 +188,10 @@ oci_bind_by_name($stid, ":mykey", $mykey, 5);
 oci_execute($stid);
 
 print '<table border="1">';
-while ($row = oci_fetch_array($stid, OCI_ASSOC)) {
-    $result = $row['MYCLOB']->load();
-    print '<tr><td>'.$result.'</td></tr>';
+while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_LOBS)) {
+    print '<tr><td>'.$row['MYCLOB'].'</td></tr>';
+    // In a loop, freeing the large variable before the 2nd fetch reduces PHP's peak memory usage
+    unset($row);  
 }
 print '</table>';
 
diff --git a/reference/oci8/functions/oci-bind-by-name.xml b/reference/oci8/functions/oci-bind-by-name.xml
index 303dcb491b..3a8cf584f5 100644
--- a/reference/oci8/functions/oci-bind-by-name.xml
+++ b/reference/oci8/functions/oci-bind-by-name.xml
@@ -366,16 +366,21 @@ if (!$conn) {
     trigger_error(htmlentities($m['message']), E_USER_ERROR);
 }
 
-$sql = 'SELECT last_name FROM employees WHERE employee_id = :eidbv';
+$sql = 'SELECT last_name FROM employees WHERE department_id = :didbv ORDER BY last_name';
 $stid = oci_parse($conn, $sql);
-$myeid = 101;
-oci_bind_by_name($stid, ':eidbv', $myeid);
+$didbv = 60;
+oci_bind_by_name($stid, ':didbv', $didbv);
 oci_execute($stid);
-$row = oci_fetch_array($stid, OCI_ASSOC);
-echo $row['LAST_NAME'] ."<br>\n";
+while (($row = oci_fetch_array($stid, OCI_ASSOC)) != false) {
+    echo $row['LAST_NAME'] ."<br>\n";
+}
 
 // Output is
-//    Kochhar
+//    Austin
+//    Ernst
+//    Hunold
+//    Lorentz
+//    Pataballa
 
 oci_free_statement($stid);
 oci_close($conn);
@@ -746,9 +751,10 @@ oci_bind_by_name($stid, ":mykey", $mykey, 5);
 oci_execute($stid);
 
 print '<table border="1">';
-while ($row = oci_fetch_array($stid, OCI_ASSOC)) {
-  $result = $row['MYCLOB']->load();
-  print '<tr><td>'.$result.'</td></tr>';
+while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_LOBS)) {
+    print '<tr><td>'.$row['MYCLOB'].'</td></tr>';
+    // In a loop, freeing the large variable before the 2nd fetch reduces PHP's peak memory usage
+    unset($row);  
 }
 print '</table>';
 
diff --git a/reference/oci8/functions/oci-fetch-all.xml b/reference/oci8/functions/oci-fetch-all.xml
index a5d3948071..c1b53bdab0 100644
--- a/reference/oci8/functions/oci-fetch-all.xml
+++ b/reference/oci8/functions/oci-fetch-all.xml
@@ -102,7 +102,8 @@
        </table>
       </para>
       <para>
-        Arrays can be indexed by column heading or numerically.
+        Arrays can be indexed either by column heading or numerically.
+        Only one index mode will be returned.
        <table>
         <title><function>oci_fetch_all</function> Array Index Modes</title>
         <tgroup cols="2">
diff --git a/reference/oci8/functions/oci-fetch-array.xml b/reference/oci8/functions/oci-fetch-array.xml
index 59a2cfa7aa..eeadfb8b29 100644
--- a/reference/oci8/functions/oci-fetch-array.xml
+++ b/reference/oci8/functions/oci-fetch-array.xml
@@ -324,6 +324,8 @@ oci_execute($stid);
 while (($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_LOBS)) != false) {
     echo $row['ID'] . "<br>\n";
     echo $row['DESCRIPTION'] . "<br>\n"; // this contains all of DESCRIPTION
+    // In a loop, freeing the large variable before the 2nd fetch reduces PHP's peak memory usage
+    unset($row); 
 }
 
 // Output is:
@@ -594,7 +596,7 @@ if (!$conn) {
 // Requires OCI8 2.0 and Oracle Database 12c
 // Also see oci_get_implicit_resultset()
 $sql = 'DECLARE
-            c1 SYS_REFCURSOR;
+           c1 SYS_REFCURSOR;
         BEGIN
            OPEN c1 FOR SELECT city, postal_code FROM locations WHERE ROWNUM < 4 ORDER BY city;
            DBMS_SQL.RETURN_RESULT(c1);