rdelaage
/
postgresql
mirror of https://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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>
This commit is contained in:
Tom Lane 2016-07-18 16:52:06 -04:00
parent 82bbfc75c1
commit ade64d05a0
2 changed files with 85 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

139
doc/src/sgml/plpgsql.sgml
View File

@ -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>; GET <optional> CURRENT </optional> DIAGNOSTICS <replaceable>variable</replaceable> { = | := } <replaceable>item</replaceable> <optional> , ... </optional>;
</synopsis> </synopsis>
This command allows retrieval of system status indicators. Each This command allows retrieval of system status indicators.
<replaceable>item</replaceable> is a key word identifying a status <literal>CURRENT</> is a noise word (but see also <command>GET STACKED
value to be assigned to the specified variable (which should be DIAGNOSTICS</command> in <xref linkend="plpgsql-exception-diagnostics">).
of the right data type to receive it). The currently available Each <replaceable>item</replaceable> is a key word identifying a status
status items are <varname>ROW_COUNT</>, the number of rows value to be assigned to the specified <replaceable>variable</replaceable>
processed by the last <acronym>SQL</acronym> command sent to (which should be of the right data type to receive it). The currently
the <acronym>SQL</acronym> engine, and <varname>RESULT_OID</>, available status items are shown
the OID of the last row inserted by the most recent in <xref linkend="plpgsql-current-diagnostics-values">. Colon-equal
<acronym>SQL</acronym> command. Note that <varname>RESULT_OID</> (<literal>:=</>) can be used instead of the SQL-standard <literal>=</>
is only useful after an <command>INSERT</command> command into a token. An example:
table containing OIDs.
Colon-equal (<literal>:=</>) can be used instead of SQL-standard
<literal>=</> for <command>GET DIAGNOSTICS</>.
</para>
<para>
An example:
<programlisting> <programlisting>
GET DIAGNOSTICS integer_var = ROW_COUNT; GET DIAGNOSTICS integer_var = ROW_COUNT;
</programlisting> </programlisting>
</para> </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> <para>
The second method to determine the effects of a command is to check the The second method to determine the effects of a command is to check the
special variable named <literal>FOUND</literal>, which is of 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</>: <application>PL/pgSQL</> has three forms of <command>IF</>:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para><literal>IF ... THEN</></> <para><literal>IF ... THEN ... END IF</></>
</listitem> </listitem>
<listitem> <listitem>
<para><literal>IF ... THEN ... ELSE</></> <para><literal>IF ... THEN ... ELSE ... END IF</></>
</listitem> </listitem>
<listitem> <listitem>
<para><literal>IF ... THEN ... ELSIF ... THEN ... ELSE</></> <para><literal>IF ... THEN ... ELSIF ... THEN ... ELSE ... END IF</></>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@ -2699,13 +2727,14 @@ GET STACKED DIAGNOSTICS <replaceable>variable</replaceable> { = | := } <replacea
</synopsis> </synopsis>
Each <replaceable>item</replaceable> is a key word identifying a status Each <replaceable>item</replaceable> is a key word identifying a status
value to be assigned to the specified variable (which should be value to be assigned to the specified <replaceable>variable</replaceable>
of the right data type to receive it). The currently available (which should be of the right data type to receive it). The currently
status items are shown in <xref linkend="plpgsql-exception-diagnostics-values">. available status items are shown
in <xref linkend="plpgsql-exception-diagnostics-values">.
</para> </para>
<table id="plpgsql-exception-diagnostics-values"> <table id="plpgsql-exception-diagnostics-values">
<title>Error Diagnostics Values</title> <title>Error Diagnostics Items</title>
<tgroup cols="3"> <tgroup cols="3">
<thead> <thead>
<row> <row>
@ -2717,53 +2746,54 @@ GET STACKED DIAGNOSTICS <replaceable>variable</replaceable> { = | := } <replacea
<tbody> <tbody>
<row> <row>
<entry><literal>RETURNED_SQLSTATE</literal></entry> <entry><literal>RETURNED_SQLSTATE</literal></entry>
<entry>text</entry> <entry><type>text</></entry>
<entry>the SQLSTATE error code of the exception</entry> <entry>the SQLSTATE error code of the exception</entry>
</row> </row>
<row> <row>
<entry><literal>COLUMN_NAME</literal></entry> <entry><literal>COLUMN_NAME</literal></entry>
<entry>text</entry> <entry><type>text</></entry>
<entry>the name of the column related to exception</entry> <entry>the name of the column related to exception</entry>
</row> </row>
<row> <row>
<entry><literal>CONSTRAINT_NAME</literal></entry> <entry><literal>CONSTRAINT_NAME</literal></entry>
<entry>text</entry> <entry><type>text</></entry>
<entry>the name of the constraint related to exception</entry> <entry>the name of the constraint related to exception</entry>
</row> </row>
<row> <row>
<entry><literal>PG_DATATYPE_NAME</literal></entry> <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> <entry>the name of the data type related to exception</entry>
</row> </row>
<row> <row>
<entry><literal>MESSAGE_TEXT</literal></entry> <entry><literal>MESSAGE_TEXT</literal></entry>
<entry>text</entry> <entry><type>text</></entry>
<entry>the text of the exception's primary message</entry> <entry>the text of the exception's primary message</entry>
</row> </row>
<row> <row>
<entry><literal>TABLE_NAME</literal></entry> <entry><literal>TABLE_NAME</literal></entry>
<entry>text</entry> <entry><type>text</></entry>
<entry>the name of the table related to exception</entry> <entry>the name of the table related to exception</entry>
</row> </row>
<row> <row>
<entry><literal>SCHEMA_NAME</literal></entry> <entry><literal>SCHEMA_NAME</literal></entry>
<entry>text</entry> <entry><type>text</></entry>
<entry>the name of the schema related to exception</entry> <entry>the name of the schema related to exception</entry>
</row> </row>
<row> <row>
<entry><literal>PG_EXCEPTION_DETAIL</literal></entry> <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> <entry>the text of the exception's detail message, if any</entry>
</row> </row>
<row> <row>
<entry><literal>PG_EXCEPTION_HINT</literal></entry> <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> <entry>the text of the exception's hint message, if any</entry>
</row> </row>
<row> <row>
<entry><literal>PG_EXCEPTION_CONTEXT</literal></entry> <entry><literal>PG_EXCEPTION_CONTEXT</literal></entry>
<entry>text</entry> <entry><type>text</></entry>
<entry>line(s) of text describing the call stack</entry> <entry>line(s) of text describing the call stack at the time of the
exception (see <xref linkend="plpgsql-call-stack">)</entry>
</row> </row>
</tbody> </tbody>
</tgroup> </tgroup>
@ -2794,26 +2824,19 @@ END;
</sect3> </sect3>
</sect2> </sect2>
<sect2 id="plpgsql-get-diagnostics-context"> <sect2 id="plpgsql-call-stack">
<title>Obtaining Current Execution Information</title> <title>Obtaining Execution Location Information</title>
<para> <para>
The <command>GET <optional> CURRENT </optional> DIAGNOSTICS</command> The <command>GET DIAGNOSTICS</command> command, previously described
command retrieves information about current execution state (whereas in <xref linkend="plpgsql-statements-diagnostics">, retrieves information
the <command>GET STACKED DIAGNOSTICS</command> command discussed above about current execution state (whereas the <command>GET STACKED
reports information about the execution state as of a previous error). DIAGNOSTICS</command> command discussed above reports information about
This command has the form: the execution state as of a previous error). Its <literal>PG_CONTEXT</>
</para> status item is useful for identifying the current execution
location. <literal>PG_CONTEXT</> returns a text string with line(s)
<synopsis> of text describing the call stack. The first line refers to the current
GET <optional> CURRENT </optional> DIAGNOSTICS <replaceable>variable</replaceable> { = | := } <replaceable>item</replaceable> <optional> , ... </optional>; function and currently executing <command>GET DIAGNOSTICS</command>
</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>
command. The second and any subsequent lines refer to calling functions command. The second and any subsequent lines refer to calling functions
further up the call stack. For example: further up the call stack. For example:
@ -2847,6 +2870,12 @@ CONTEXT: PL/pgSQL function outer_func() line 3 at RETURN
</programlisting> </programlisting>
</para> </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> </sect2>
</sect1> </sect1>
@ -4235,7 +4264,7 @@ SELECT * FROM sales_summary_bytime;
</para> </para>
<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 event trigger, several special variables are created automatically
in the top-level block. They are: in the top-level block. They are:
@ -4263,7 +4292,7 @@ SELECT * FROM sales_summary_bytime;
</para> </para>
<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>. event trigger procedure in <application>PL/pgSQL</application>.
</para> </para>

2
doc/src/sgml/release-9.4.sgml
View File

@ -7308,7 +7308,7 @@ Branch: REL9_4_STABLE [c2b06ab17] 2015-01-30 22:45:58 -0500
<listitem> <listitem>
<para> <para>
Add ability to retrieve the current PL/PgSQL call stack 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> DIAGNOSTICS</></link>
(Pavel Stehule, Stephen Frost) (Pavel Stehule, Stephen Frost)
</para> </para>