Support "OR condition ..." in plpgsql EXCEPTION clauses to make the syntax

more nearly Oracle-equivalent.  Allow matching by category as well as
specific error code.  Document the set of available condition names
(or more accurately, synchronize it with the existing documentation).  In
passing, update errcodes.sgml to include codes added during 7.5 development.

2 files changed, 80 insertions, 23 deletions

diff --git a/doc/src/sgml/errcodes.sgml b/doc/src/sgml/errcodes.sgml
index 5d1a770bf87..ca3bc9ca4f1 100644
--- a/doc/src/sgml/errcodes.sgml
+++ b/doc/src/sgml/errcodes.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/errcodes.sgml,v 1.6 2004/05/16 23:18:52 neilc Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/errcodes.sgml,v 1.7 2004/07/31 23:04:54 tgl Exp $ -->
 
 <appendix id="errcodes-appendix">
  <title><productname>PostgreSQL</productname> Error Codes</title>
@@ -41,10 +41,18 @@
   within the class but do not have any more-specific code assigned.
  </para>
 
+ <para>
+  The <application>PL/pgSQL</> condition name for each error code is the
+  same as the phrase shown in the table, with underscores substituted
+  for spaces.  For example, code <literal>22012</>, DIVISION BY ZERO,
+  has condition name <literal>DIVISION_BY_ZERO</>.  Condition names can
+  be written in either upper or lower case.
+ </para>
+
 
 <!--
  The following table should correspond to the contents of
- src/include/utils/errcodes.h.
+ src/include/utils/errcodes.h and src/pl/plpgsql/src/plerrcodes.h.
 -->
 
 <table id="errcodes-table">
@@ -82,27 +90,37 @@
 
 <row>
 <entry><literal>0100C</literal></entry>
-<entry>WARNING DYNAMIC RESULT SETS RETURNED</entry>
+<entry>DYNAMIC RESULT SETS RETURNED</entry>
 </row>
 
 <row>
 <entry><literal>01008</literal></entry>
-<entry>WARNING IMPLICIT ZERO BIT PADDING</entry>
+<entry>IMPLICIT ZERO BIT PADDING</entry>
 </row>
 
 <row>
 <entry><literal>01003</literal></entry>
-<entry>WARNING NULL VALUE ELIMINATED IN SET FUNCTION</entry>
+<entry>NULL VALUE ELIMINATED IN SET FUNCTION</entry>
+</row>
+
+<row>
+<entry><literal>01007</literal></entry>
+<entry>PRIVILEGE NOT GRANTED</entry>
+</row>
+
+<row>
+<entry><literal>01006</literal></entry>
+<entry>PRIVILEGE NOT REVOKED</entry>
 </row>
 
 <row>
 <entry><literal>01004</literal></entry>
-<entry>WARNING STRING DATA RIGHT TRUNCATION</entry>
+<entry>STRING DATA RIGHT TRUNCATION</entry>
 </row>
 
 <row>
 <entry><literal>01P01</literal></entry>
-<entry>WARNING DEPRECATED FEATURE</entry>
+<entry>DEPRECATED FEATURE</entry>
 </row>
 
 <row>
@@ -218,7 +236,7 @@
 
 <row>
 <entry><literal>0F001</literal></entry>
-<entry>INVALID SPECIFICATION</entry>
+<entry>INVALID LOCATOR SPECIFICATION</entry>
 </row>
 
 
@@ -272,7 +290,7 @@
 
 <row>
 <entry><literal>2202E</literal></entry>
-<entry>ARRAY ELEMENT ERROR</entry>
+<entry>ARRAY SUBSCRIPT ERROR</entry>
 </row>
 
 <row>
@@ -729,6 +747,22 @@
 
 
 <row>
+<entry>Class 3B</entry>
+<entry>Savepoint Exception</entry>
+</row>
+
+<row>
+<entry><literal>3B000</literal></entry>
+<entry>SAVEPOINT EXCEPTION</entry>
+</row>
+
+<row>
+<entry><literal>3B001</literal></entry>
+<entry>INVALID SAVEPOINT SPECIFICATION</entry>
+</row>
+
+
+<row>
 <entry>Class 3D</entry>
 <entry>Invalid Catalog Name</entry>
 </row>
@@ -762,7 +796,7 @@
 
 <row>
 <entry><literal>40002</literal></entry>
-<entry>INTEGRITY CONSTRAINT VIOLATION</entry>
+<entry>TRANSACTION INTEGRITY CONSTRAINT VIOLATION</entry>
 </row>
 
 <row>
@@ -893,7 +927,7 @@
 
 <row>
 <entry><literal>42P05</literal></entry>
-<entry>DUPLICATE PSTATEMENT</entry>
+<entry>DUPLICATE PREPARED STATEMENT</entry>
 </row>
 
 <row>
@@ -963,7 +997,7 @@
 
 <row>
 <entry><literal>42P14</literal></entry>
-<entry>INVALID PSTATEMENT DEFINITION</entry>
+<entry>INVALID PREPARED STATEMENT DEFINITION</entry>
 </row>
 
 <row>
@@ -1135,6 +1169,22 @@
 
 
 <row>
+<entry>Class P0</entry>
+<entry><application>PL/pgSQL</> Error</entry>
+</row>
+
+<row>
+<entry><literal>P0000</literal></entry>
+<entry>PLPGSQL ERROR</entry>
+</row>
+
+<row>
+<entry><literal>P0001</literal></entry>
+<entry>RAISE EXCEPTION</entry>
+</row>
+
+
+<row>
 <entry>Class XX</entry>
 <entry>Internal Error</entry>
 </row>
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 7f3f84448d7..e44b886214b 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.42 2004/07/31 07:39:17 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/plpgsql.sgml,v 1.43 2004/07/31 23:04:54 tgl Exp $
 -->
 
 <chapter id="plpgsql"> 
@@ -1816,12 +1816,11 @@ END LOOP;
 BEGIN
     <replaceable>statements</replaceable>
 EXCEPTION
-    WHEN <replaceable>condition</replaceable> THEN
+    WHEN <replaceable>condition</replaceable> <optional> OR <replaceable>condition</replaceable> ... </optional> THEN
         <replaceable>handler_statements</replaceable>
-    <optional> WHEN <replaceable>condition</replaceable> THEN
-                   <replaceable>handler_statements</replaceable>
-    ...
-    </optional>
+    <optional> WHEN <replaceable>condition</replaceable> <optional> OR <replaceable>condition</replaceable> ... </optional> THEN
+          <replaceable>handler_statements</replaceable>
+    ... </optional>
 END;
 </synopsis>
     </para>
@@ -1841,10 +1840,18 @@ END;
      as though the <literal>EXCEPTION</> clause were not there at all:
      the error can be caught by an enclosing block with
      <literal>EXCEPTION</>, or if there is none it aborts processing
-     of the function.  The special condition name <literal>OTHERS</>
+     of the function.
+    </para>
+
+    <para>
+     The <replaceable>condition</replaceable> names can be any of those
+     shown in <xref linkend="errcodes-appendix">.  A category name matches
+     any error within its category.
+     The special condition name <literal>OTHERS</>
      matches every error type except <literal>QUERY_CANCELED</>.
-     (It is possible, but usually not a good idea, to trap
+     (It is possible, but often unwise, to trap
      <literal>QUERY_CANCELED</> by name.)
+     Condition names are not case-sensitive.
     </para>
 
     <para>
@@ -1879,9 +1886,9 @@ END;
      the <literal>EXCEPTION</> clause.  The value returned in the
      <command>RETURN</> statement will be the incremented value of
      <literal>x</>, but the effects of the <command>UPDATE</> command will
-     have been rolled back.  The <command>INSERT</> command is not rolled
-     back, however, so the end result is that the database contains
-     <literal>Tom Jones</> not <literal>Joe Jones</>.
+     have been rolled back.  The <command>INSERT</> command preceding the
+     block is not rolled back, however, so the end result is that the database
+     contains <literal>Tom Jones</> not <literal>Joe Jones</>.
     </para>
 
     <tip>