From ade64d05a0c9c77def776f64ea399697c3cd7f61 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Mon, 18 Jul 2016 16:52:06 -0400
Subject: [PATCH] Doc: improve discussion of plpgsql's GET DIAGNOSTICS, other
minor fixes.
9.4 added a second description of GET DIAGNOSTICS that was totally
independent of the existing one, resulting in each description lying to the
extent that it claimed the set of status items it described was complete.
Fix that, and do some minor markup improvement.
Also some other small fixes per bug #14258 from Dilian Palauzov.
Discussion: <20160718181437.1414.40802@wrigleys.postgresql.org>
---
doc/src/sgml/plpgsql.sgml | 139 ++++++++++++++++++++--------------
doc/src/sgml/release-9.4.sgml | 2 +-
2 files changed, 85 insertions(+), 56 deletions(-)
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index e9cce824085..d3272e12096 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -1441,28 +1441,56 @@ EXECUTE format('UPDATE tbl SET %I = $1 WHERE key = $2', colname)
GET <optional> CURRENT </optional> DIAGNOSTICS <replaceable>variable</replaceable> { = | := } <replaceable>item</replaceable> <optional> , ... </optional>;
</synopsis>
- This command allows retrieval of system status indicators. Each
- <replaceable>item</replaceable> is a key word identifying a status
- value to be assigned to the specified variable (which should be
- of the right data type to receive it). The currently available
- status items are <varname>ROW_COUNT</>, the number of rows
- processed by the last <acronym>SQL</acronym> command sent to
- the <acronym>SQL</acronym> engine, and <varname>RESULT_OID</>,
- the OID of the last row inserted by the most recent
- <acronym>SQL</acronym> command. Note that <varname>RESULT_OID</>
- is only useful after an <command>INSERT</command> command into a
- table containing OIDs.
- Colon-equal (<literal>:=</>) can be used instead of SQL-standard
- <literal>=</> for <command>GET DIAGNOSTICS</>.
- </para>
-
- <para>
- An example:
+ This command allows retrieval of system status indicators.
+ <literal>CURRENT</> is a noise word (but see also <command>GET STACKED
+ DIAGNOSTICS</command> in <xref linkend="plpgsql-exception-diagnostics">).
+ Each <replaceable>item</replaceable> is a key word identifying a status
+ value to be assigned to the specified <replaceable>variable</replaceable>
+ (which should be of the right data type to receive it). The currently
+ available status items are shown
+ in <xref linkend="plpgsql-current-diagnostics-values">. Colon-equal
+ (<literal>:=</>) can be used instead of the SQL-standard <literal>=</>
+ token. An example:
<programlisting>
GET DIAGNOSTICS integer_var = ROW_COUNT;
</programlisting>
</para>
+ <table id="plpgsql-current-diagnostics-values">
+ <title>Available Diagnostics Items</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><varname>ROW_COUNT</varname></entry>
+ <entry><type>bigint</></entry>
+ <entry>the number of rows processed by the most
+ recent <acronym>SQL</acronym> command</entry>
+ </row>
+ <row>
+ <entry><varname>RESULT_OID</varname></entry>
+ <entry><type>oid</></entry>
+ <entry>the OID of the last row inserted by the most
+ recent <acronym>SQL</acronym> command (only useful after
+ an <command>INSERT</command> command into a table having
+ OIDs)</entry>
+ </row>
+ <row>
+ <entry><literal>PG_CONTEXT</literal></entry>
+ <entry><type>text</></entry>
+ <entry>line(s) of text describing the current call stack
+ (see <xref linkend="plpgsql-call-stack">)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
<para>
The second method to determine the effects of a command is to check the
special variable named <literal>FOUND</literal>, which is of
@@ -1828,13 +1856,13 @@ SELECT * FROM get_available_flightid(CURRENT_DATE);
<application>PL/pgSQL</> has three forms of <command>IF</>:
<itemizedlist>
<listitem>
- <para><literal>IF ... THEN</></>
+ <para><literal>IF ... THEN ... END IF</></>
</listitem>
<listitem>
- <para><literal>IF ... THEN ... ELSE</></>
+ <para><literal>IF ... THEN ... ELSE ... END IF</></>
</listitem>
<listitem>
- <para><literal>IF ... THEN ... ELSIF ... THEN ... ELSE</></>
+ <para><literal>IF ... THEN ... ELSIF ... THEN ... ELSE ... END IF</></>
</listitem>
</itemizedlist>
@@ -2699,13 +2727,14 @@ GET STACKED DIAGNOSTICS <replaceable>variable</replaceable> { = | := } <replacea
</synopsis>
Each <replaceable>item</replaceable> is a key word identifying a status
- value to be assigned to the specified variable (which should be
- of the right data type to receive it). The currently available
- status items are shown in <xref linkend="plpgsql-exception-diagnostics-values">.
+ value to be assigned to the specified <replaceable>variable</replaceable>
+ (which should be of the right data type to receive it). The currently
+ available status items are shown
+ in <xref linkend="plpgsql-exception-diagnostics-values">.
</para>
<table id="plpgsql-exception-diagnostics-values">
- <title>Error Diagnostics Values</title>
+ <title>Error Diagnostics Items</title>
<tgroup cols="3">
<thead>
<row>
@@ -2717,53 +2746,54 @@ GET STACKED DIAGNOSTICS <replaceable>variable</replaceable> { = | := } <replacea
<tbody>
<row>
<entry><literal>RETURNED_SQLSTATE</literal></entry>
- <entry>text</entry>
+ <entry><type>text</></entry>
<entry>the SQLSTATE error code of the exception</entry>
</row>
<row>
<entry><literal>COLUMN_NAME</literal></entry>
- <entry>text</entry>
+ <entry><type>text</></entry>
<entry>the name of the column related to exception</entry>
</row>
<row>
<entry><literal>CONSTRAINT_NAME</literal></entry>
- <entry>text</entry>
+ <entry><type>text</></entry>
<entry>the name of the constraint related to exception</entry>
</row>
<row>
<entry><literal>PG_DATATYPE_NAME</literal></entry>
- <entry>text</entry>
+ <entry><type>text</></entry>
<entry>the name of the data type related to exception</entry>
</row>
<row>
<entry><literal>MESSAGE_TEXT</literal></entry>
- <entry>text</entry>
+ <entry><type>text</></entry>
<entry>the text of the exception's primary message</entry>
</row>
<row>
<entry><literal>TABLE_NAME</literal></entry>
- <entry>text</entry>
+ <entry><type>text</></entry>
<entry>the name of the table related to exception</entry>
</row>
<row>
<entry><literal>SCHEMA_NAME</literal></entry>
- <entry>text</entry>
+ <entry><type>text</></entry>
<entry>the name of the schema related to exception</entry>
</row>
<row>
<entry><literal>PG_EXCEPTION_DETAIL</literal></entry>
- <entry>text</entry>
+ <entry><type>text</></entry>
<entry>the text of the exception's detail message, if any</entry>
</row>
<row>
<entry><literal>PG_EXCEPTION_HINT</literal></entry>
- <entry>text</entry>
+ <entry><type>text</></entry>
<entry>the text of the exception's hint message, if any</entry>
</row>
<row>
<entry><literal>PG_EXCEPTION_CONTEXT</literal></entry>
- <entry>text</entry>
- <entry>line(s) of text describing the call stack</entry>
+ <entry><type>text</></entry>
+ <entry>line(s) of text describing the call stack at the time of the
+ exception (see <xref linkend="plpgsql-call-stack">)</entry>
</row>
</tbody>
</tgroup>
@@ -2794,26 +2824,19 @@ END;
</sect3>
</sect2>
- <sect2 id="plpgsql-get-diagnostics-context">
- <title>Obtaining Current Execution Information</title>
+ <sect2 id="plpgsql-call-stack">
+ <title>Obtaining Execution Location Information</title>
<para>
- The <command>GET <optional> CURRENT </optional> DIAGNOSTICS</command>
- command retrieves information about current execution state (whereas
- the <command>GET STACKED DIAGNOSTICS</command> command discussed above
- reports information about the execution state as of a previous error).
- This command has the form:
- </para>
-
-<synopsis>
-GET <optional> CURRENT </optional> DIAGNOSTICS <replaceable>variable</replaceable> { = | := } <replaceable>item</replaceable> <optional> , ... </optional>;
-</synopsis>
-
- <para>
- Currently only one information item is supported. Status
- item <literal>PG_CONTEXT</> will return a text string with line(s) of
- text describing the call stack. The first line refers to the
- current function and currently executing <command>GET DIAGNOSTICS</command>
+ The <command>GET DIAGNOSTICS</command> command, previously described
+ in <xref linkend="plpgsql-statements-diagnostics">, retrieves information
+ about current execution state (whereas the <command>GET STACKED
+ DIAGNOSTICS</command> command discussed above reports information about
+ the execution state as of a previous error). Its <literal>PG_CONTEXT</>
+ status item is useful for identifying the current execution
+ location. <literal>PG_CONTEXT</> returns a text string with line(s)
+ of text describing the call stack. The first line refers to the current
+ function and currently executing <command>GET DIAGNOSTICS</command>
command. The second and any subsequent lines refer to calling functions
further up the call stack. For example:
@@ -2847,6 +2870,12 @@ CONTEXT: PL/pgSQL function outer_func() line 3 at RETURN
</programlisting>
</para>
+
+ <para>
+ <literal>GET STACKED DIAGNOSTICS ... PG_EXCEPTION_CONTEXT</literal>
+ returns the same sort of stack trace, but describing the location
+ at which an error was detected, rather than the current location.
+ </para>
</sect2>
</sect1>
@@ -4235,7 +4264,7 @@ SELECT * FROM sales_summary_bytime;
</para>
<para>
- When a <application>PL/pgSQL</application> function is called as a
+ When a <application>PL/pgSQL</application> function is called as an
event trigger, several special variables are created automatically
in the top-level block. They are:
@@ -4263,7 +4292,7 @@ SELECT * FROM sales_summary_bytime;
</para>
<para>
- <xref linkend="plpgsql-event-trigger-example"> shows an example of a
+ <xref linkend="plpgsql-event-trigger-example"> shows an example of an
event trigger procedure in <application>PL/pgSQL</application>.
</para>
diff --git a/doc/src/sgml/release-9.4.sgml b/doc/src/sgml/release-9.4.sgml
index 3c0f4ab7362..555a26c950e 100644
--- a/doc/src/sgml/release-9.4.sgml
+++ b/doc/src/sgml/release-9.4.sgml
@@ -7308,7 +7308,7 @@ Branch: REL9_4_STABLE [c2b06ab17] 2015-01-30 22:45:58 -0500
<listitem>
<para>
Add ability to retrieve the current PL/PgSQL call stack
- using <link linkend="plpgsql-get-diagnostics-context"><command>GET
+ using <link linkend="plpgsql-call-stack"><command>GET
DIAGNOSTICS</></link>
(Pavel Stehule, Stephen Frost)
</para>
--
GitLab