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[email protected]>

diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index e9cce8240855fc4bf0fa33179cbd8e6683aaab5e..d3272e12096e6c0c7825e255ceda8b0e4c45b0a7 100644 (file)
--- 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 <span class="marked">Value</span>s
+      Error Diagnostics <span class="marked">Item</span>s
       
        
         
@@ -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;
    
   
 
-  get-diagnostics-context">
-   Obtaining <span class="marked">Current Execu</span>tion Information
+  call-stack">
+   Obtaining <span class="marked">Execution Loca</span>tion 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 3c0f4ab73627a8d738051b2e0bf0d1d75a96d07c..555a26c950e29cc8781b006d083de62ea0c2e32b 100644 (file)
--- 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-diagnostics-context">GET
+        using call-stack">GET
         DIAGNOSTICS
         (Pavel Stehule, Stephen Frost)