From 810cf8cd0afae1710927cab159bba312dc0b816b Mon Sep 17 00:00:00 2001
From: Christopher Jones <sixd@php.net>
Date: Tue, 17 Nov 2009 21:20:52 +0000
Subject: [PATCH] Explain default commit mode when querying. Add
 literal/constant tags & use tables. Standardize examples.  Update oci_close
 doc and add examples

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@290888 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/oci8/examples.xml               | 122 ++++++++------
 reference/oci8/functions/oci-close.xml    | 196 +++++++++++++++++++++-
 reference/oci8/functions/oci-commit.xml   |  21 +--
 reference/oci8/functions/oci-execute.xml  | 149 ++++++++++------
 reference/oci8/functions/oci-parse.xml    |  25 ++-
 reference/oci8/functions/oci-rollback.xml |  25 +--
 6 files changed, 400 insertions(+), 138 deletions(-)

diff --git a/reference/oci8/examples.xml b/reference/oci8/examples.xml
index b9cf618a20..8e83c0616d 100644
--- a/reference/oci8/examples.xml
+++ b/reference/oci8/examples.xml
@@ -2,32 +2,47 @@
 <!-- $Revision$ -->
 <chapter xml:id="oci8.examples" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  &reftitle.examples;
+ <para>
+  These examples connect as the <literal>HR</literal> user, which is
+  the sample &quot;Human Resources&quot; schema supplied with the
+  Oracle database. The account may need to be unlocked and the
+  password reset before you can use it.
+ </para>
+
+ <para>
+  The examples connect to the <literal>XE</literal> database on your
+  machine.  Change the connect string to your database before running
+  the examples.
+ </para>
+
+ <example>
+  <title>Basic query</title>
   <para>
-    Basic queries in oci8 use a prepare-execute-fetch sequence of steps.
-   <example>
-    <title>Basic query</title>
-     <programlisting role="php">
+   This shows querying and displaying results.  Statements in OCI8 use
+   a prepare-execute-fetch sequence of steps.
+  </para>
+  <programlisting role="php">
 <![CDATA[
 <?php
 
 $conn = oci_connect('hr', 'welcome', 'localhost/XE');
 if (!$conn) {
     $e = oci_error();
-    trigger_error(htmlentities($e['message']), E_USER_ERROR);
+    trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
 }
 
 // Prepare the statement
 $stid = oci_parse($conn, 'SELECT * FROM departments');
 if (!$stid) {
     $e = oci_error($conn);
-    trigger_error(htmlentities($e['message']), E_USER_ERROR);
+    trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
 }
 
 // Perform the logic of the query
-$r = oci_execute($stid, OCI_DEFAULT);
+$r = oci_execute($stid);
 if (!$r) {
     $e = oci_error($stid);
-    trigger_error(htmlentities($e['message']), E_USER_ERROR);
+    trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
 }
 
 // Fetch the results of the query
@@ -35,7 +50,7 @@ print "<table border='1'>\n";
 while ($row = oci_fetch_array($stid, OCI_ASSOC+OCI_RETURN_NULLS)) {
     print "<tr>\n";
     foreach ($row as $item) {
-        print "  <td>".($item != null ? htmlentities($item) : "&nbsp;")."</td>\n";
+        print "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;") . "</td>\n";
     }
     print "</tr>\n";
 }
@@ -46,18 +61,17 @@ oci_close($conn);
 
 ?>
 ]]>
-     </programlisting>
-   </example>
-  </para>
-
+  </programlisting>
+ </example>
 
+ <example>
+  <title>Inserting with bind variables</title>
   <para>
-    Bind variables improve performance by allowing reuse of execution
-    contexts and caches.  Bind variables improve security by
-    preventing some kinds of SQL Injection problems.
-   <example>
-    <title>Inserting with bind variables</title>
-     <programlisting role="php">
+   Bind variables improve performance by allowing reuse of execution
+   contexts and caches.  Bind variables improve security by preventing
+   some kinds of SQL Injection problems.
+  </para>
+  <programlisting role="php">
 <![CDATA[
 <?php
 
@@ -67,7 +81,7 @@ oci_close($conn);
 $conn = oci_connect('hr', 'welcome', 'localhost/XE');
 if (!$conn) {
     $e = oci_error();
-    trigger_error(htmlentities($e['message']), E_USER_ERROR);
+    trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
 }
 
 $stid = oci_parse($conn, 'INSERT INTO MYTABLE (mid, myd) VALUES(:myid, :mydata)');
@@ -80,24 +94,25 @@ oci_bind_by_name($stid, ':mydata', $data);
 
 $r = oci_execute($stid);  // executes and commits
 
-if ($r)
+if ($r) {
     print "One row inserted";
+}
 
 oci_free_statement($stid);
 oci_close($conn);
 
 ?>
 ]]>
-     </programlisting>
-   </example>
-  </para>
-
+  </programlisting>
+ </example>
 
+ <example>
+  <title>Inserting data into a CLOB column</title>
   <para>
-    For large data use binary long object (BLOB) or character long object (CLOB) types.
-  <example>
-   <title>Inserting data into a CLOB column</title>
-    <programlisting role="php">
+   For large data use binary long object (BLOB) or character long
+   object (CLOB) types.  This example uses CLOB.
+  </para>
+  <programlisting role="php">
 <![CDATA[
 <?php
 
@@ -107,7 +122,7 @@ oci_close($conn);
 $conn = oci_connect('hr', 'welcome', 'localhost/XE');
 if (!$conn) {
     $e = oci_error();
-    trigger_error(htmlentities($e['message']), E_USER_ERROR);
+    trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
 }
 
 $mykey = 12343;  // arbitrary key for this example;
@@ -120,7 +135,7 @@ $stid = oci_parse($conn, $sql);
 $clob = oci_new_descriptor($conn, OCI_D_LOB);
 oci_bind_by_name($stid, ":mykey", $mykey, 5);
 oci_bind_by_name($stid, ":myclob", $clob, -1, OCI_B_CLOB);
-oci_execute($stid, OCI_DEFAULT);
+oci_execute($stid, OCI_NO_AUTO_COMMIT); // use OCI_DEFAULT for PHP <= 5.3.1
 $clob->save("A very long string");
 
 oci_commit($conn);
@@ -131,27 +146,27 @@ $query = 'SELECT myclob FROM mytable WHERE mykey = :mykey';
 
 $stid = oci_parse ($conn, $query);
 oci_bind_by_name($stid, ":mykey", $mykey, 5);
-oci_execute($stid, OCI_DEFAULT);
+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>';
+    $result = $row['MYCLOB']->load();
+    print '<tr><td>'.$result.'</td></tr>';
 }
 print '</table>';
 
 ?>
 ]]>
-   </programlisting>
-  </example>
-  </para>
-
+  </programlisting>
+ </example>
 
+ <example>
+  <title>Using a PL/SQL stored function</title>
   <para>
-   You can easily access stored PL/SQL functions and procedures.
-  <example>
-   <title>Using a stored function </title>
-    <programlisting role="php">
+   You must bind a variable for the return value and optionally for
+   any PL/SQL function arguments.
+  </para>
+  <programlisting role="php">
 <![CDATA[
 <?php
 
@@ -169,7 +184,7 @@ print '</table>';
 $conn = oci_connect('hr', 'welcome', 'localhost/XE');
 if (!$conn) {
     $e = oci_error();
-    trigger_error(htmlentities($e['message']), E_USER_ERROR);
+    trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
 }
 
 $p = 8;
@@ -187,15 +202,15 @@ oci_close($conn);
 
 ?>
 ]]>
-    </programlisting>
-   </example>
-  </para>
-
+  </programlisting>
+ </example>
 
+ <example>
+  <title>Using a PL/SQL stored procedure</title>
   <para>
-  <example>
-   <title>Using a stored procedure</title>
-    <programlisting role="php">
+   With stored procedures, you should bind variables for any arguments.
+  </para>
+  <programlisting role="php">
 <![CDATA[
 <?php
 
@@ -213,7 +228,7 @@ oci_close($conn);
 $conn = oci_connect('hr', 'welcome', 'localhost/XE');
 if (!$conn) {
     $e = oci_error();
-    trigger_error(htmlentities($e['message']), E_USER_ERROR);
+    trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
 }
 
 $p1 = 8;
@@ -231,9 +246,8 @@ oci_close($conn);
 
 ?>
 ]]>
-    </programlisting>
-   </example>
-  </para>
+  </programlisting>
+ </example>
 </chapter>
 
 <!-- Keep this comment at the end of the file
diff --git a/reference/oci8/functions/oci-close.xml b/reference/oci8/functions/oci-close.xml
index 0f971f20f7..2fbed7e4f0 100644
--- a/reference/oci8/functions/oci-close.xml
+++ b/reference/oci8/functions/oci-close.xml
@@ -3,7 +3,7 @@
 <refentry xml:id="function.oci-close" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>oci_close</refname>
-  <refpurpose>Closes Oracle connection</refpurpose>
+  <refpurpose>Closes an Oracle connection</refpurpose>
  </refnamediv>
  
  <refsect1 role="description">
@@ -13,7 +13,14 @@
    <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
   </methodsynopsis>
   <para>
-   Closes the Oracle <parameter>connection</parameter>.
+   Unsets <parameter>connection</parameter>.  The underlying database
+   connection is closed if no other resources are using it and if it
+   was created with <function>oci_connect</function>
+   or <function>oci_new_connect</function>.
+  </para>
+  <para>
+   It is recommended to close connections that are no longer needed
+   because this makes database resources available for other users.
   </para>
  </refsect1>
 
@@ -25,8 +32,9 @@
      <term><parameter>connection</parameter></term>
      <listitem>
       <para>
-       An Oracle connection identifier, returned by 
-       <function>oci_connect</function>.
+       An Oracle connection identifier returned by 
+       <function>oci_connect</function>, <function>oci_pconnect</function>,
+       or <function>oci_new_connect</function>.
       </para>
      </listitem>
     </varlistentry>
@@ -41,16 +49,188 @@
   </para>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title>Closing a connection</title>
+   <para>
+    Resources associated with a connection should be closed to ensure
+    the underlying database connection is properly terminated and the
+    database resources are released.
+   </para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+$conn = oci_connect('hr', 'welcome', 'localhost/XE');
+if (!$conn) {
+    $e = oci_error();
+    trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
+}
+
+$stid = oci_parse($conn, 'SELECT * FROM departments');
+$r = oci_execute($stid);
+oci_fetch_all($stid, $res);
+var_dump($res);
+
+// Free the statement identifier when closing the connection
+oci_free_statement($stid);
+oci_close($conn);
+
+?>
+]]>
+   </programlisting>
+  </example>
+
+  <example>
+   <title>Database connections are not closed until all references are closed</title>
+   <para>
+    The internal refcount of a connection identifier must be zero
+    before the underlying connection to the database is closed.
+   </para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+$conn = oci_connect('hr', 'welcome', 'localhost/XE');
+if (!$conn) {
+    $e = oci_error();
+    trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
+}
+
+$stid = oci_parse($conn, 'SELECT * FROM departments');  // this increases the refcount on $conn
+oci_execute($stid);
+oci_fetch_all($stid, $res);
+var_dump($res);
+
+oci_close($conn);
+
+// $conn is no long usable in the script but the underlying database
+// connection is still held open until $stid is freed.
+var_dump($conn);  // prints NULL  
+
+// While PHP sleeps, querying the Oracle V$SESSION view in a
+// terminal window will show that the database user is still connected.
+sleep(10);
+
+// When $stid is freed, the database connection is physically closed
+oci_free_statement($stid);  
+
+// While PHP sleeps, querying the Oracle V$SESSION view in a
+// terminal window will show that the database user has disconnected.
+sleep(10);
+
+?>
+]]>
+   </programlisting>
+  </example>
+
+  <example>
+   <title>Closing a connection opened more than once</title>
+   <para>
+     When database credentials are reused, both connections must be closed
+     before the underlying database connection is closed.
+   </para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+$conn1 = oci_connect('hr', 'welcome', 'localhost/XE');
+
+// Using the same credentials reuses the same underlying database connection
+// Any uncommitted changes done on $conn1 will be visible in $conn2
+$conn2 = oci_connect('hr', 'welcome', 'localhost/XE');
+
+// While PHP sleeps, querying the Oracle V$SESSION view in a
+// terminal window will show that only one database user is connected.
+sleep(10);
+
+oci_close($conn1); // doesn't close the underlying database connection
+var_dump($conn1);  // prints NULL because the variable $conn1 is no longer usable
+var_dump($conn2);  // displays that $conn2 is still a valid connection resource
+
+?>
+]]>
+   </programlisting>
+  </example>
+
+  <example>
+   <title>Connections are closed when variables go out of scope</title>
+   <para>
+    When all variables referencing a connection go out of scope and
+    are freed by PHP, a rollback occurs (if necessary) and the
+    underlying connection to the database is closed.
+   </para>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+function myfunc() {
+    $conn = oci_connect('hr', 'hrpwd', 'localhost/XE');
+    if (!$conn) {
+        $e = oci_error();
+        trigger_error(htmlentities($e['message'], ENT_QUOTES), E_USER_ERROR);
+    }
+
+    $stid = oci_parse($conn, 'UPDATE mytab SET id = 100');
+    oci_execute($stid, OCI_NO_AUTO_COMMIT);
+    return "Finished";
+}
+
+$r = myfunc();
+// At this point a rollback occurred and the underlying database connection was released.
+
+print $r;  // displays the function return value "Finished"
+
+?>
+]]>
+   </programlisting>
+  </example>
+ </refsect1>
+
  <refsect1 role="notes">
   &reftitle.notes;
   <note>
    <para>
-    Starting from the version 1.1 <function>oci_close</function> correctly 
-    closes the Oracle connection. Use <link
-    linkend="ini.oci8.old-oci-close-semantics">oci8.old_oci_close_semantics</link>
-    option to restore old behaviour of this function.
+    Variables that have a dependency on the connection identifier,
+    such as statement identifiers returned
+    by <function>oci_parse</function>, must also be freed before the
+    underlying database connection is closed.
    </para>
   </note>
+  <note>
+   <para>
+    Prior to version PHP 5.1.2 (PECL OCI8
+    1.1) <function>oci_close</function> was a no-op. In more recent
+    versions it correctly closes the Oracle
+    connection. Use <link linkend="ini.oci8.old-oci-close-semantics">oci8.old_oci_close_semantics</link>
+    option to restore old behavior of this function.
+   </para>
+  </note>
+  <note>
+   <para>
+    The <function>oci_close</function> function does not close the
+    underlying database connections created
+    with <function>oci_pconnect</function>.
+   </para>
+  </note>
+  <note>
+   <para>
+    In PHP versions before 5.0.0 you must
+    use <function>ocilogoff</function> instead. &oci.name.compat.note;
+   </para>
+  </note>
+
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>oci_connect</function></member>
+    <member><function>oci_free_statement</function></member>
+   </simplelist>
+  </para>
  </refsect1>
 
 </refentry>
diff --git a/reference/oci8/functions/oci-commit.xml b/reference/oci8/functions/oci-commit.xml
index 069f1c6672..8601a9336e 100644
--- a/reference/oci8/functions/oci-commit.xml
+++ b/reference/oci8/functions/oci-commit.xml
@@ -28,8 +28,8 @@
    the database will not see the changes until they are committed.
   </para>
   <para>
-   Using transactions is recommended for relational data consistency
-   and for performance reasons.
+   When inserting or updating data, using transactions is recommended
+   for relational data consistency and for performance reasons.
   </para>
  </refsect1>
 
@@ -68,7 +68,7 @@
 
 // Insert into several tables, rolling back the changes if an error occurs
 
-$conn = oci_connect("hr", "welcome", "localhost/XE");
+$conn = oci_connect('hr', 'welcome', 'localhost/XE');
 
 $stid = oci_parse($conn, "INSERT INTO mysalary (id, name) VALUES (1, 'Chris')");
 
@@ -80,7 +80,7 @@ if (!$r) {
     trigger_error(htmlentities($e['message']), E_USER_ERROR);
 }
 
-$stid = oci_parse($conn, "INSERT INTO myschedule (startday) VALUES (12)");
+$stid = oci_parse($conn, 'INSERT INTO myschedule (startday) VALUES (12)');
 $r = oci_execute($stid, OCI_NO_AUTO_COMMIT);
 if (!$r) {    
     $e = oci_error($stid);
@@ -106,19 +106,20 @@ if (!r) {
   &reftitle.notes;
   <note>
    <para>
-    Transactions are automatically rolled back when you close
-    the connection, or when the script ends, whichever is soonest. You
+    Transactions are automatically rolled back when you close the
+    connection, or when the script ends, whichever is soonest. You
     need to explicitly call <function>oci_commit</function> to commit
     the transaction.
    </para>
    <para>
     Any call to <function>oci_execute</function> that uses
-    OCI_COMMIT_ON_SUCCESS mode explicitly or by default will commit
-    any previous uncommitted transaction.
+    <constant>OCI_COMMIT_ON_SUCCESS</constant> mode explicitly or by
+    default will commit any previous uncommitted transaction.
    </para>
    <para>
-    Any Oracle DDL statement such as CREATE or DROP will automatically
-    commit any uncommitted transaction.
+    Any Oracle DDL statement such as <literal>CREATE</literal>
+    or <literal>DROP</literal> will automatically commit any
+    uncommitted transaction.
    </para>
   </note>
   <note>
diff --git a/reference/oci8/functions/oci-execute.xml b/reference/oci8/functions/oci-execute.xml
index cd69938724..541eea3312 100644
--- a/reference/oci8/functions/oci-execute.xml
+++ b/reference/oci8/functions/oci-execute.xml
@@ -49,26 +49,47 @@
      <listitem>
       <para>
         An optional second parameter can be one of the following constants:
-        <simplelist>
-         <member>
-          <constant>OCI_COMMIT_ON_SUCCESS</constant> - Automatically
-          commit changes when the statement has succeeded. This is the
-          default.
-         </member>
-         <member>
-           <constant>OCI_NO_AUTO_COMMIT</constant> - Do not
-           automatically commit changes.  Prior to PHP 5.3.2 and for
-           PECL oci8 &lt; 1.4 use <constant>OCI_DEFAULT</constant>
-           which is an alias for <constant>OCI_NO_AUTO_COMMIT</constant>.
-         </member>
-         <member>
-           <constant>OCI_DESCRIBE_ONLY</constant> - Make query meta
-           data available to functions
-           like <function>oci_field_name</function> but do not create
-           a result set. Any subsequent fetch call such
-           as <function>oci_fetch_array</function> will fail.
-         </member>
-        </simplelist>
+       <table>
+        <title>Execution Modes</title>
+        <tgroup cols="2">
+         <thead>
+          <row>
+           <entry>Constant</entry>
+           <entry>Description</entry>
+          </row>
+         </thead>
+         <tbody>
+          <row>
+           <entry><constant>OCI_COMMIT_ON_SUCCESS</constant></entry>
+           <entry>Automatically commit all outstanding changes for
+             this connection when the statement has succeeded. This
+             is the default.</entry>
+          </row>
+          <row>
+           <entry><constant>OCI_DEFAULT</constant></entry>
+           <entry>Obsolete as of PHP 5.3.2 (PECL OCI8 1.4) but still
+             available for backward compatibility.  Use the
+             equivalent <constant>OCI_NO_AUTO_COMMIT</constant> in new
+             code.</entry>
+          </row>
+          <row>
+           <entry><constant>OCI_DESCRIBE_ONLY</constant></entry>
+           <entry>Make query meta data available to functions
+             like <function>oci_field_name</function> but do not
+             create a result set. Any subsequent fetch call such
+             as <function>oci_fetch_array</function> will
+             fail.</entry>
+          </row>
+          <row>
+           <entry><constant>OCI_NO_AUTO_COMMIT</constant></entry>
+           <entry>Do not automatically commit changes.  Prior to PHP
+             5.3.2 (PECL OCI8 1.4)
+             use <constant>OCI_DEFAULT</constant> which is an alias
+             for <constant>OCI_NO_AUTO_COMMIT</constant>.</entry>
+          </row>
+         </tbody>
+        </tgroup>
+       </table>
       </para>
       <para>
        When using <constant>OCI_NO_AUTO_COMMIT</constant> mode, you're
@@ -78,8 +99,22 @@
        transaction, or <function>oci_rollback</function> to abort it.
       </para>
       <para>
-       Using transactions is recommended for relational data
-       consistency and for performance reasons.
+       When inserting or updating data, using transactions is
+       recommended for relational data consistency and for performance
+       reasons.
+      </para>
+      <para>
+       If you use <constant>OCI_NO_AUTO_COMMIT</constant> mode for any
+       statement including queries, and you do not subsequently
+       call <function>oci_commit</function>
+       or <function>oci_rollback</function>, then OCI8 will perform a
+       rollback at the end of the script even if no data was changed.
+       To avoid an unnecessary rollback, many scripts do not
+       use <constant>OCI_NO_AUTO_COMMIT</constant> mode for queries or
+       PL/SQL.  Be careful to ensure the appropriate transactional
+       consistency for your application when
+       using <function>oci_execute</function> with different modes in
+       the same script.
       </para>
      </listitem>
     </varlistentry>
@@ -103,16 +138,16 @@
 <![CDATA[
 <?php
 
-$connection = oci_connect("hr", "welcome", "localhost/XE");
+$conn = oci_connect('hr', 'welcome', 'localhost/XE');
 
-$statement = oci_parse($connection, "SELECT * FROM employees");
-oci_execute($statement);
+$stid = oci_parse($conn, 'SELECT * FROM employees');
+oci_execute($stid);
 
 echo "<table border='1'>\n";
-while ($row = oci_fetch_array($statement, OCI_ASSOC+OCI_RETURN_NULLS)) {
+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 "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;") . "</td>\n";
     }
     echo "</tr>\n";
 }
@@ -130,11 +165,14 @@ echo "</table>\n";
 <![CDATA[
 <?php
 
-$connection = oci_connect("hr", "welcome", "localhost/XE");
+// Before running, create the table:
+//   CREATE TABLE MYTABLE (col1 NUMBER);
 
-$statement = oci_parse($connection, "INSERT INTO mytab (col1) VALUES (123)");
+$conn = oci_connect('hr', 'welcome', 'localhost/XE');
 
-oci_execute($statement); // The row is committed and immediately visible to other users
+$stid = oci_parse($conn, 'INSERT INTO mytab (col1) VALUES (123)');
+
+oci_execute($stid); // The row is committed and immediately visible to other users
 
 ?>
 ]]>
@@ -148,14 +186,17 @@ oci_execute($statement); // The row is committed and immediately visible to othe
 <![CDATA[
 <?php
 
-$connection = oci_connect("hr", "welcome", "localhost/XE");
+// Before running, create the table:
+//   CREATE TABLE MYTABLE (col1 NUMBER);
 
-$statement = oci_parse($connection, "INSERT INTO mytab (col1) VALUES (:bv)");
-oci_bind_by_name($statement, ":bv", $i, 10);
+$conn = oci_connect('hr', 'welcome', 'localhost/XE');
+
+$stid = oci_parse($conn, 'INSERT INTO mytab (col1) VALUES (:bv)');
+oci_bind_by_name($stid, ':bv', $i, 10);
 for ($i = 1; $i <= 5; ++$i) {
-    oci_execute($statement, OCI_NO_AUTO_COMMIT);  // use OCI_DEFAULT for PHP <= 5.3.1
+    oci_execute($stid, OCI_NO_AUTO_COMMIT);  // use OCI_DEFAULT for PHP <= 5.3.1
 }
-oci_commit($connection);  // commits all new values: 1, 2, 3, 4, 5
+oci_commit($conn);  // commits all new values: 1, 2, 3, 4, 5
 
 ?>
 ]]>
@@ -169,13 +210,16 @@ oci_commit($connection);  // commits all new values: 1, 2, 3, 4, 5
 <![CDATA[
 <?php
 
-$connection = oci_connect("hr", "welcome", "localhost/XE");
+// Before running, create the table:
+//   CREATE TABLE MYTABLE (col1 NUMBER);
 
-$statement = oci_parse($connection, "INSERT INTO mytab (col1) VALUES (123)");
-oci_execute($statement, OCI_NO_AUTO_COMMIT);  // data not committed
+$conn = oci_connect('hr', 'welcome', 'localhost/XE');
 
-$statement = oci_parse($connection, "INSERT INTO mytab (col1) VALUES (456)");
-oci_execute($statement);  // commits both 123 and 456 values
+$stid = oci_parse($conn, 'INSERT INTO mytab (col1) VALUES (123)');
+oci_execute($stid, OCI_NO_AUTO_COMMIT);  // data not committed
+
+$stid = oci_parse($conn, 'INSERT INTO mytab (col1) VALUES (456)');
+oci_execute($stid);  // commits both 123 and 456 values
 
 ?>
 ]]>
@@ -190,12 +234,12 @@ oci_execute($statement);  // commits both 123 and 456 values
 <![CDATA[
 <?php
 
-$connection = oci_connect("hr", "welcome", "localhost/XE");
+$conn = oci_connect('hr', 'welcome', 'localhost/XE');
 
-$statement = oci_parse($connection, "SELECT * FROM mytab");
+$stid = oci_parse($conn, 'SELECT * FROM locations');
 oci_execute($s, OCI_DESCRIBE_ONLY);
-for ($i = 1; $i <= oci_num_fields($statement); ++$i) {
-    echo oci_field_name($statement, $i) . "<br>\n";
+for ($i = 1; $i <= oci_num_fields($stid); ++$i) {
+    echo oci_field_name($stid, $i) . "<br>\n";
 }
 
 ?>
@@ -209,13 +253,20 @@ for ($i = 1; $i <= oci_num_fields($statement); ++$i) {
   &reftitle.notes;
   <note>
    <para>
-    Any call to <function>oci_execute</function> that uses
-    OCI_COMMIT_ON_SUCCESS mode explicitly or by default will commit
-    any previous uncommitted transaction.
+    Transactions are automatically rolled back when you close the
+    connection, or when the script ends, whichever is soonest. You
+    need to explicitly call <function>oci_commit</function> to commit
+    the transaction.
    </para>
    <para>
-    Any Oracle DDL statement such as CREATE or DROP will automatically
-    commit any uncommitted transaction.
+    Any call to <function>oci_execute</function> that uses
+    <constant>OCI_COMMIT_ON_SUCCESS</constant> mode explicitly or by
+    default will commit any previous uncommitted transaction.
+   </para>
+   <para>
+    Any Oracle DDL statement such as <literal>CREATE</literal>
+    or <literal>DROP</literal> will automatically commit any
+    uncommitted transaction.
    </para>
   </note>
   <note>
diff --git a/reference/oci8/functions/oci-parse.xml b/reference/oci8/functions/oci-parse.xml
index 8e6d542836..5c4e6394e4 100644
--- a/reference/oci8/functions/oci-parse.xml
+++ b/reference/oci8/functions/oci-parse.xml
@@ -19,6 +19,11 @@
    which can be used with <function>oci_bind_by_name</function>, 
    <function>oci_execute</function> and other functions.
   </para>
+  <para>
+   Statement identifiers can be freed
+   with <function>oci_free_statement</function> or by setting the
+   variable to <constant>null</constant>.
+  </para>
  </refsect1>
 
  <refsect1 role="parameters">
@@ -62,16 +67,16 @@
 <![CDATA[
 <?php
 
-$connection = oci_connect("hr", "welcome", "localhost/XE");
+$conn = oci_connect('hr', 'welcome', 'localhost/XE');
 
-$statement = oci_parse($connection, "SELECT * FROM employees");
-oci_execute($statement);
+$stid = oci_parse($conn, 'SELECT * FROM employees');
+oci_execute($stid);
 
 echo "<table border='1'>\n";
-while ($row = oci_fetch_array($statement, OCI_ASSOC+OCI_RETURN_NULLS)) {
+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 "    <td>" . ($item !== null ? htmlentities($item, ENT_QUOTES) : "&nbsp;") . "</td>\n";
     }
     echo "</tr>\n";
 }
@@ -102,6 +107,16 @@ echo "</table>\n";
   </note>
  </refsect1>
 
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>oci_execute</function></member>
+    <member><function>oci_free_statement</function></member>
+   </simplelist>
+  </para>
+ </refsect1>
+
 </refentry>
 
 <!-- Keep this comment at the end of the file
diff --git a/reference/oci8/functions/oci-rollback.xml b/reference/oci8/functions/oci-rollback.xml
index e4ca030b82..4ab8896a43 100644
--- a/reference/oci8/functions/oci-rollback.xml
+++ b/reference/oci8/functions/oci-rollback.xml
@@ -28,8 +28,8 @@
    the database will not see the changes until they are committed.
   </para>
   <para>
-   Using transactions is recommended for relational data consistency
-   and for performance reasons.
+   When inserting or updating data, using transactions is recommended
+   for relational data consistency and for performance reasons.
   </para>
  </refsect1>
 
@@ -69,7 +69,7 @@
 
 // Insert into several tables, rolling back the changes if an error occurs
 
-$conn = oci_connect("hr", "welcome", "localhost/XE");
+$conn = oci_connect('hr', 'welcome', 'localhost/XE');
 
 $stid = oci_parse($conn, "INSERT INTO mysalary (id, name) VALUES (1, 'Chris')");
 
@@ -81,7 +81,7 @@ if (!$r) {
     trigger_error(htmlentities($e['message']), E_USER_ERROR);
 }
 
-$stid = oci_parse($conn, "INSERT INTO myschedule (startday) VALUES (12)");
+$stid = oci_parse($conn, 'INSERT INTO myschedule (startday) VALUES (12)');
 $r = oci_execute($stid, OCI_NO_AUTO_COMMIT);
 if (!$r) {    
     $e = oci_error($stid);
@@ -106,18 +106,18 @@ if (!r) {
     <title>Rolling back to a <literal>SAVEPOINT</literal> example</title>
     <programlisting role="php">
 <![CDATA[
-$stid = oci_parse($conn, "UPDATE mytab SET id = 1111");
+$stid = oci_parse($conn, 'UPDATE mytab SET id = 1111');
 oci_execute($stid, OCI_NO_AUTO_COMMIT);
 
 // Create the savepoint
-$stid = oci_parse($conn, "SAVEPOINT mysavepoint");
+$stid = oci_parse($conn, 'SAVEPOINT mysavepoint');
 oci_execute($stid, OCI_NO_AUTO_COMMIT);
 
-$stid = oci_parse($conn, "UPDATE mytab SET id = 2222");
+$stid = oci_parse($conn, 'UPDATE mytab SET id = 2222');
 oci_execute($stid, OCI_NO_AUTO_COMMIT);
 
 // Use an explicit SQL statement to rollback to the savepoint
-$stid = oci_parse($conn, "ROLLBACK TO SAVEPOINT mysavepoint");
+$stid = oci_parse($conn, 'ROLLBACK TO SAVEPOINT mysavepoint');
 oci_execute($stid, OCI_NO_AUTO_COMMIT);
 
 oci_commit($conn);  // mytab now has id of 1111
@@ -138,12 +138,13 @@ oci_commit($conn);  // mytab now has id of 1111
    </para>
    <para>
     Any call to <function>oci_execute</function> that uses
-    OCI_COMMIT_ON_SUCCESS mode explicitly or by default will commit
-    any previous uncommitted transaction.
+    <constant>OCI_COMMIT_ON_SUCCESS</constant> mode explicitly or by
+    default will commit any previous uncommitted transaction.
    </para>
    <para>
-    Any Oracle DDL statement such as CREATE or DROP will automatically
-    commit any uncommitted transaction.
+    Any Oracle DDL statement such as <literal>CREATE</literal>
+    or <literal>DROP</literal> will automatically commit any
+    uncommitted transaction.
    </para>
   </note>
   <note>