From 82fde1aaa818d50c758f596b170c38b592a9e53b Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Sun, 8 Aug 2004 22:40:46 +0000
Subject: [PATCH] Add note pointing out the difference in semantics between
 Oracle and plpgsql EXCEPTION blocks.

---
 doc/src/sgml/plpgsql.sgml | 39 ++++++++++++++++++++++++++++++++++++---
 1 file changed, 36 insertions(+), 3 deletions(-)

diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 0615440725..5e21d1abb6 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/plpgsql.sgml,v 1.44 2004/08/08 00:50:58 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/plpgsql.sgml,v 1.45 2004/08/08 22:40:46 tgl Exp $
 -->
 
 <chapter id="plpgsql"> 
@@ -2647,7 +2647,7 @@ show errors;
        <para>
         The <literal>show errors</literal> command does not exist in
         <productname>PostgreSQL</>, and is not needed since errors are
-	reported automatically.
+        reported automatically.
        </para>
       </listitem>
      </itemizedlist>
@@ -3009,7 +3009,8 @@ $$ LANGUAGE plpgsql;
       <para>
        The exception names supported by <application>PL/pgSQL</> are
        different from Oracle's.  The set of built-in exception names
-       is much larger (see <xref linkend="errcodes-appendix">).
+       is much larger (see <xref linkend="errcodes-appendix">).  There
+       is not currently a way to declare user-defined exception names.
       </para>
      </callout>
     </calloutlist>
@@ -3032,6 +3033,38 @@ $$ LANGUAGE plpgsql;
     <productname>PostgreSQL</productname>.
    </para>
 
+   <sect3 id="plpgsql-porting-exceptions">
+    <title>Implicit Rollback after Exceptions</title>
+
+    <para>
+     In <application>PL/pgSQL</>, when an exception is caught by an
+     <literal>EXCEPTION</> clause, all database changes since the block's
+     <literal>BEGIN</> are automatically rolled back.  That is, the behavior
+     is equivalent to what you'd get in Oracle with
+
+<programlisting>
+    BEGIN
+        SAVEPOINT s1;
+        ... code here ...
+    EXCEPTION
+        WHEN ... THEN
+            ROLLBACK TO s1;
+            ... code here ...
+        WHEN ... THEN
+            ROLLBACK TO s1;
+            ... code here ...
+    END;
+</programlisting>
+
+     If you are translating an Oracle procedure that uses
+     <command>SAVEPOINT</> and <command>ROLLBACK TO</> in this style,
+     your task is easy: just omit the <command>SAVEPOINT</> and
+     <command>ROLLBACK TO</>.  If you have a procedure that uses
+     <command>SAVEPOINT</> and <command>ROLLBACK TO</> in a different way
+     then some actual thought will be required.
+    </para>
+   </sect3>
+
    <sect3>
     <title><command>EXECUTE</command></title>
 
-- 
2.40.0