From ade64d05a0c9c77def776f64ea399697c3cd7f61 Mon Sep 17 00:00:00 2001 From: Tom Lane 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 e9cce82408..d3272e1209 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 CURRENT DIAGNOSTICS variable { = | := } item , ... ; - This command allows retrieval of system status indicators. Each - item 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 ROW_COUNT, the number of rows - processed by the last SQL command sent to - the SQL engine, and RESULT_OID, - the OID of the last row inserted by the most recent - SQL command. Note that RESULT_OID - is only useful after an INSERT command into a - table containing OIDs. - Colon-equal (:=) can be used instead of SQL-standard - = for GET DIAGNOSTICS. - - - - An example: + This command allows retrieval of system status indicators. + CURRENT is a noise word (but see also GET STACKED + DIAGNOSTICS in ). + Each item 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 . Colon-equal + (:=) can be used instead of the SQL-standard = + token. An example: GET DIAGNOSTICS integer_var = ROW_COUNT; + + Available Diagnostics Items + + + + Name + Type + Description + + + + + ROW_COUNT + bigint + the number of rows processed by the most + recent SQL command + + + RESULT_OID + oid + the OID of the last row inserted by the most + recent SQL command (only useful after + an INSERT command into a table having + OIDs) + + + PG_CONTEXT + text + line(s) of text describing the current call stack + (see ) + + + +
+ The second method to determine the effects of a command is to check the special variable named FOUND, which is of @@ -1828,13 +1856,13 @@ SELECT * FROM get_available_flightid(CURRENT_DATE); PL/pgSQL has three forms of IF: - IF ... THEN + IF ... THEN ... END IF - IF ... THEN ... ELSE + IF ... THEN ... ELSE ... END IF - IF ... THEN ... ELSIF ... THEN ... ELSE + IF ... THEN ... ELSIF ... THEN ... ELSE ... END IF @@ -2699,13 +2727,14 @@ GET STACKED DIAGNOSTICS variable { = | := } Each item 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 . + 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 . - Error Diagnostics Values + Error Diagnostics Items @@ -2717,53 +2746,54 @@ GET STACKED DIAGNOSTICS variable { = | := } RETURNED_SQLSTATE - text + text the SQLSTATE error code of the exception COLUMN_NAME - text + text the name of the column related to exception CONSTRAINT_NAME - text + text the name of the constraint related to exception PG_DATATYPE_NAME - text + text the name of the data type related to exception MESSAGE_TEXT - text + text the text of the exception's primary message TABLE_NAME - text + text the name of the table related to exception SCHEMA_NAME - text + text the name of the schema related to exception PG_EXCEPTION_DETAIL - text + text the text of the exception's detail message, if any PG_EXCEPTION_HINT - text + text the text of the exception's hint message, if any PG_EXCEPTION_CONTEXT - text - line(s) of text describing the call stack + text + line(s) of text describing the call stack at the time of the + exception (see ) @@ -2794,26 +2824,19 @@ END; - - Obtaining Current Execution Information + + Obtaining Execution Location Information - The GET CURRENT DIAGNOSTICS - command retrieves information about current execution state (whereas - the GET STACKED DIAGNOSTICS command discussed above - reports information about the execution state as of a previous error). - This command has the form: - - - -GET CURRENT DIAGNOSTICS variable { = | := } item , ... ; - - - - Currently only one information item is supported. Status - item 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 GET DIAGNOSTICS + The GET DIAGNOSTICS command, previously described + in , retrieves information + about current execution state (whereas the GET STACKED + DIAGNOSTICS command discussed above reports information about + the execution state as of a previous error). Its PG_CONTEXT + status item is useful for identifying the current execution + location. 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 GET DIAGNOSTICS 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 + + + GET STACKED DIAGNOSTICS ... PG_EXCEPTION_CONTEXT + returns the same sort of stack trace, but describing the location + at which an error was detected, rather than the current location. + @@ -4235,7 +4264,7 @@ SELECT * FROM sales_summary_bytime; - When a PL/pgSQL function is called as a + When a PL/pgSQL 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; - shows an example of a + shows an example of an event trigger procedure in PL/pgSQL. diff --git a/doc/src/sgml/release-9.4.sgml b/doc/src/sgml/release-9.4.sgml index 3c0f4ab736..555a26c950 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 Add ability to retrieve the current PL/PgSQL call stack - using GET + using GET DIAGNOSTICS (Pavel Stehule, Stephen Frost)