Modified: phpdoc/en/trunk/reference/oci8/functions/oci-commit.xml
===================================================================
--- phpdoc/en/trunk/reference/oci8/functions/oci-commit.xml	2009-11-16 23:32:45 UTC (rev 290850)
+++ phpdoc/en/trunk/reference/oci8/functions/oci-commit.xml	2009-11-17 00:19:18 UTC (rev 290851)
@@ -3,7 +3,7 @@
 <refentry xml:id="function.oci-commit" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>oci_commit</refname>
-  <refpurpose>Commits outstanding statements</refpurpose>
+  <refpurpose>Commits the outstanding database transaction</refpurpose>
  </refnamediv>

  <refsect1 role="description">
@@ -13,9 +13,24 @@
    <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
   </methodsynopsis>
   <para>
-   Commits all outstanding statements for the active transaction on the
-   Oracle <parameter>connection</parameter>.
+   Commits the outstanding transaction for the
+   Oracle <parameter>connection</parameter>.  A commit ends the
+   current transaction and makes permanent all changes.  It releases
+   all locks held.
   </para>
+  <para>
+   A transaction begins when the first SQL statement that changes data
+   is executed with <function>oci_execute</function> using
+   the <constant>OCI_NO_AUTO_COMMIT</constant> flag.  Further data
+   changes made by other statements become part of the same
+   transaction.  Data changes made in a transaction are temporary
+   until the transaction is committed or rolled back.  Other users of
+   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.
+  </para>
  </refsect1>

  <refsect1 role="parameters">
@@ -26,8 +41,8 @@
      <term><parameter>connection</parameter></term>
      <listitem>
       <para>
-       An Oracle connection identifier, returned by
-       <function>oci_connect</function> or <function>oci_pconnect</function>.
+       An Oracle connection identifier, returned by
+       <function>oci_connect</function>, <function>oci_pconnect</function>, or <function>oci_new_connect</function>.
       </para>
      </listitem>
     </varlistentry>
@@ -50,37 +65,36 @@
     <programlisting role="php">
 <![CDATA[
 <?php
-// Login to Oracle server
-$conn = oci_connect('scott', 'tiger');

-// Parse SQL
-$stmt = oci_parse($conn, "
-                          INSERT INTO
-                                     employees (name, surname)
-                               VALUES
-                                     ('Maxim', 'Maletsky')
-                         ");
+// Insert into several tables, rolling back the changes if an error occurs

-/* Execute statement
-   OCI_DEFAULT tells oci_execute()
-   not to commit statement immediately */
-oci_execute($stmt, OCI_DEFAULT);
+$conn = oci_connect("hr", "welcome", "localhost/XE");

-/*
-....
-Parsing and executing other statements here ...
-....
-*/
+$stid = oci_parse($conn, "INSERT INTO mysalary (id, name) VALUES (1, 'Chris')");

-// Commit transaction
-$committed = oci_commit($conn);
+// The OCI_NO_AUTO_COMMIT flag tells Oracle not to commit the INSERT immediately
+// Use OCI_DEFAULT as the flag for PHP <= 5.3.1.  The two flags are equivalent
+$r = oci_execute($stid, OCI_NO_AUTO_COMMIT);
+if (!$r) {
+    $e = oci_error($stid);
+    trigger_error(htmlentities($e['message']), E_USER_ERROR);
+}

-// Test whether commit was successful. If error occurred, return error message
-if (!$committed) {
-    $error = oci_error($conn);
-    echo 'Commit failed. Oracle reports: ' . $error['message'];
+$stid = oci_parse($conn, "INSERT INTO myschedule (startday) VALUES (12)");
+$r = oci_execute($stid, OCI_NO_AUTO_COMMIT);
+if (!$r) {
+    $e = oci_error($stid);
+    oci_rollback($conn);  // rollback changes to both tables
+    trigger_error(htmlentities($e['message']), E_USER_ERROR);
 }

+// Commit the changes to both tables
+$r = oci_commit($conn);
+if (!r) {
+    $e = oci_error($conn);
+    trigger_error(htmlentities($e['message']), E_USER_ERROR);
+}
+
 ?>
 ]]>
     </programlisting>
@@ -95,17 +109,33 @@
     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, or <function>oci_rollback</function> to abort it.
+    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.
+   </para>
+   <para>
+    Any Oracle DDL statement such as CREATE or DROP will automatically
+    commit any uncommitted transaction.
+   </para>
   </note>
+  <note>
+   <para>
+    In PHP versions before 5.0.0 you must
+    use <function>ocicommit</function>
+    instead. &oci.name.compat.note;
+   </para>
+  </note>
  </refsect1>

  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>
    <simplelist>
+    <member><function>oci_execute</function></member>
     <member><function>oci_rollback</function></member>
-    <member><function>oci_execute</function></member>
    </simplelist>
   </para>
  </refsect1>

Modified: phpdoc/en/trunk/reference/oci8/functions/oci-rollback.xml
===================================================================
--- phpdoc/en/trunk/reference/oci8/functions/oci-rollback.xml	2009-11-16 23:32:45 UTC (rev 290850)
+++ phpdoc/en/trunk/reference/oci8/functions/oci-rollback.xml	2009-11-17 00:19:18 UTC (rev 290851)
@@ -3,7 +3,7 @@
 <refentry xml:id="function.oci-rollback" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>oci_rollback</refname>
-  <refpurpose>Rolls back outstanding transaction</refpurpose>
+  <refpurpose>Rolls back the outstanding database transaction</refpurpose>
  </refnamediv>

  <refsect1 role="description">
@@ -13,9 +13,24 @@
    <methodparam><type>resource</type><parameter>connection</parameter></methodparam>
   </methodsynopsis>
   <para>
-   Rolls back all outstanding statements for the Oracle
-   <parameter>connection</parameter>.
+   Reverts all uncommitted changes for the Oracle
+   <parameter>connection</parameter> and ends the transaction.  It
+   releases all locks held.  All Oracle <literal>SAVEPOINTS</literal>
+   are erased.
   </para>
+  <para>
+   A transaction begins when the first SQL statement that changes data
+   is executed with <function>oci_execute</function> using
+   the <constant>OCI_NO_AUTO_COMMIT</constant> flag.  Further data
+   changes made by other statements become part of the same
+   transaction.  Data changes made in a transaction are temporary
+   until the transaction is committed or rolled back.  Other users of
+   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.
+  </para>
  </refsect1>

  <refsect1 role="parameters">
@@ -26,8 +41,9 @@
      <term><parameter>connection</parameter></term>
      <listitem>
       <para>
-       An Oracle connection identifier, returned by
-       <function>oci_connect</function> or <function>oci_pconnect</function>.
+       An Oracle connection identifier, returned by
+       <function>oci_connect</function>, <function>oci_pconnect</function>
+       or <function>oci_new_connect</function>.
       </para>
      </listitem>
     </varlistentry>
@@ -42,22 +58,99 @@
   </para>
  </refsect1>

+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title><function>oci_rollback</function> example</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+
+// Insert into several tables, rolling back the changes if an error occurs
+
+$conn = oci_connect("hr", "welcome", "localhost/XE");
+
+$stid = oci_parse($conn, "INSERT INTO mysalary (id, name) VALUES (1, 'Chris')");
+
+// The OCI_NO_AUTO_COMMIT flag tells Oracle not to commit the INSERT immediately
+// Use OCI_DEFAULT as the flag for PHP <= 5.3.1.  The two flags are equivalent
+$r = oci_execute($stid, OCI_NO_AUTO_COMMIT);
+if (!$r) {
+    $e = oci_error($stid);
+    trigger_error(htmlentities($e['message']), E_USER_ERROR);
+}
+
+$stid = oci_parse($conn, "INSERT INTO myschedule (startday) VALUES (12)");
+$r = oci_execute($stid, OCI_NO_AUTO_COMMIT);
+if (!$r) {
+    $e = oci_error($stid);
+    oci_rollback($conn);  // rollback changes to both tables
+    trigger_error(htmlentities($e['message']), E_USER_ERROR);
+}
+
+// Commit the changes to both tables
+$r = oci_commit($conn);
+if (!r) {
+    $e = oci_error($conn);
+    trigger_error(htmlentities($e['message']), E_USER_ERROR);
+}
+
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+  <para>
+   <example>
+    <title>Rolling back to a <literal>SAVEPOINT</literal> example</title>
+    <programlisting role="php">
+<![CDATA[
+$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");
+oci_execute($stid, OCI_NO_AUTO_COMMIT);
+
+$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");
+oci_execute($stid, OCI_NO_AUTO_COMMIT);
+
+oci_commit($conn);  // mytab now has id of 1111
+]]>
+    </programlisting>
+   </example>
+  </para>
+ </refsect1>
+
  <refsect1 role="notes">
   &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, or <function>oci_rollback</function> to abort it.
+    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.
+   </para>
+   <para>
+    Any Oracle DDL statement such as CREATE or DROP will automatically
+    commit any uncommitted transaction.
+   </para>
   </note>
   <note>
    <para>
-    In PHP versions before 5.0.0 you must use <function>ocirollback</function> instead.
-    This name still can be used, it was left as alias of
-    <function>oci_rollback</function> for downwards compatability.
-    This, however, is deprecated and not recommended.
+    In PHP versions before 5.0.0 you must
+    use <function>ocirollback</function>
+    instead. &oci.name.compat.note;
    </para>
   </note>
  </refsect1>
@@ -67,6 +160,7 @@
   <para>
    <simplelist>
     <member><function>oci_commit</function></member>
+    <member><function>oci_execute</function></member>
    </simplelist>
   </para>
  </refsect1>