From f938c2b91bebb7f436a3615cf86347d7261f71e8 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Sun, 21 Mar 2004 22:29:11 +0000
Subject: Revise syntax-error reporting behavior to give pleasant results for
 errors in internally-generated queries, such as those submitted by plpgsql
 functions.  Per recent discussions with Fabien Coelho.

---
 doc/src/sgml/libpq.sgml    | 32 ++++++++++++++++++++++++++++----
 doc/src/sgml/protocol.sgml | 34 ++++++++++++++++++++++++++++++----
 2 files changed, 58 insertions(+), 8 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 82b8099a4a0..ee30b0d7e57 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.147 2004/03/11 02:39:10 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.148 2004/03/21 22:29:10 tgl Exp $
 -->
 
  <chapter id="libpq">
@@ -1390,13 +1390,37 @@ bytes.
 </listitem>
 </varlistentry>
 
+<varlistentry>
+<term><symbol>PG_DIAG_INTERNAL_POSITION</></term>
+<listitem>
+<para>
+This is defined the same as the <symbol>PG_DIAG_STATEMENT_POSITION</>
+field, but it is used when the cursor position refers to an internally
+generated command rather than the one submitted by the client.
+The <symbol>PG_DIAG_INTERNAL_QUERY</> field will always appear when this field
+appears.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><symbol>PG_DIAG_INTERNAL_QUERY</></term>
+<listitem>
+<para>
+The text of a failed internally-generated command.
+This could be, for example, a SQL query issued by a PL/pgSQL function.
+</para>
+</listitem>
+</varlistentry>
+
 <varlistentry>
 <term><symbol>PG_DIAG_CONTEXT</></term>
 <listitem>
 <para>
-An indication of the context in which the error occurred.  Presently
-this includes a call stack traceback of active PL functions.  The
-trace is one entry per line, most recent first.
+An indication of the context in which the error occurred.
+Presently this includes a call stack traceback of active
+procedural language functions and internally-generated queries.
+The trace is one entry per line, most recent first.
 </para>
 </listitem>
 </varlistentry>
diff --git a/doc/src/sgml/protocol.sgml b/doc/src/sgml/protocol.sgml
index a4baff82a4b..de3b72738d7 100644
--- a/doc/src/sgml/protocol.sgml
+++ b/doc/src/sgml/protocol.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/protocol.sgml,v 1.50 2004/03/09 16:57:46 neilc Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/protocol.sgml,v 1.51 2004/03/21 22:29:10 tgl Exp $ -->
 
 <chapter id="protocol">
  <title>Frontend/Backend Protocol</title>
@@ -3902,6 +3902,32 @@ message.
 </ListItem>
 </VarListEntry>
 
+<VarListEntry>
+<Term>
+<literal>p</>
+</Term>
+<ListItem>
+<Para>
+        Internal position: this is defined the same as the <literal>P</>
+        field, but it is used when the cursor position refers to an internally
+        generated command rather than the one submitted by the client.
+        The <literal>q</> field will always appear when this field appears.
+</Para>
+</ListItem>
+</VarListEntry>
+
+<VarListEntry>
+<Term>
+<literal>q</>
+</Term>
+<ListItem>
+<Para>
+        Internal query: the text of a failed internally-generated command.
+        This could be, for example, a SQL query issued by a PL/pgSQL function.
+</Para>
+</ListItem>
+</VarListEntry>
+
 <VarListEntry>
 <Term>
 <literal>W</>
@@ -3909,9 +3935,9 @@ message.
 <ListItem>
 <Para>
         Where: an indication of the context in which the error occurred.
-	Presently this includes a call stack traceback of active
-	procedural language functions.  The trace is one entry per line,
-	most recent first.
+        Presently this includes a call stack traceback of active
+        procedural language functions and internally-generated queries.
+        The trace is one entry per line, most recent first.
 </Para>
 </ListItem>
 </VarListEntry>
-- 
cgit v1.2.3