Re: Need help with clarification on stored procedure support in PostGreSQL database

[Tom Lane <tgl@xxxxxxxxxxxxx>]

"David G. Johnston" <david.g.johnston@xxxxxxxxx> writes:
> On Mon, Mar 8, 2021 at 9:41 PM Tom Lane <tgl@xxxxxxxxxxxxx> wrote:
>> Guyren Howe <guyren@xxxxxxxxx> writes:
>>> This seems like an important consideration. I've spent 10 minutes
>>> searching the documentation for PG 11 and can't find where it is
>>> documented. Perhaps it should be made more prominent?

>> https://www.postgresql.org/docs/current/xproc.html

> CREATE FUNCTION links into 37.3 but CREATE PROCEDURE doesn't link into 37.4
> Even if this may not be sufficient it seems reasonable to at least remain
> consistent.  I suspect most people start at CREATE, not "Server
> Programming".

Yeah, fair point, and it also seems like we ought to give those links
more prominence.  In the attached proposed patch, I put them into the
introductory section of the reference pages.  I also failed to resist
the temptation to do some wordsmithing in 38.4 ...

			regards, tom lane

diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 9d41967ad3..9242c54329 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -1959,7 +1959,8 @@ SELECT * FROM get_available_flightid(CURRENT_DATE);
      or <command>DO</command> block can call a procedure
      using <command>CALL</command>.  Output parameters are handled
      differently from the way that <command>CALL</command> works in plain
-     SQL.  Each <literal>INOUT</literal> parameter of the procedure must
+     SQL.  Each <literal>OUT</literal> or <literal>INOUT</literal>
+     parameter of the procedure must
      correspond to a variable in the <command>CALL</command> statement, and
      whatever the procedure returns is assigned back to that variable after
      it returns.  For example:
diff --git a/doc/src/sgml/ref/create_function.sgml b/doc/src/sgml/ref/create_function.sgml
index 3c1eaea651..d18a5ab5d2 100644
--- a/doc/src/sgml/ref/create_function.sgml
+++ b/doc/src/sgml/ref/create_function.sgml
@@ -100,6 +100,11 @@ CREATE [ OR REPLACE ] FUNCTION
    To be able to create a function, you must have <literal>USAGE</literal>
    privilege on the argument types and the return type.
   </para>
+
+  <para>
+   Refer to <xref linkend="xfunc"/> for further information on writing
+   functions.
+  </para>
  </refsect1>
 
  <refsect1>
@@ -578,12 +583,6 @@ CREATE [ OR REPLACE ] FUNCTION
     </varlistentry>
 
    </variablelist>
-
-   <para>
-    Refer to <xref linkend="xfunc"/> for further information on writing
-    functions.
-   </para>
-
  </refsect1>
 
  <refsect1 id="sql-createfunction-overloading">
diff --git a/doc/src/sgml/ref/create_procedure.sgml b/doc/src/sgml/ref/create_procedure.sgml
index e258eca5ce..b4d2e5920c 100644
--- a/doc/src/sgml/ref/create_procedure.sgml
+++ b/doc/src/sgml/ref/create_procedure.sgml
@@ -76,6 +76,11 @@ CREATE [ OR REPLACE ] PROCEDURE
    To be able to create a procedure, you must have <literal>USAGE</literal>
    privilege on the argument types.
   </para>
+
+  <para>
+   Refer to <xref linkend="xproc"/> for further information on writing
+   procedures.
+  </para>
  </refsect1>
 
  <refsect1>
@@ -328,6 +333,10 @@ $$;
 
 CALL insert_data(1, 2);
 </programlisting>
+
+  <para>
+   For more information and examples, see <xref linkend="xproc"/>.
+  </para>
  </refsect1>
 
  <refsect1 id="sql-createprocedure-compat">
diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index 2863f7c206..c492348261 100644
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -81,19 +81,19 @@
   </indexterm>
 
    <para>
-    A procedure is a database object similar to a function.  The difference is
+    A procedure is a database object similar to a function.  One difference is
     that a procedure does not return a value, so there is no return type
     declaration.  While a function is called as part of a query or DML
     command, a procedure is called in isolation using
     the <link linkend="sql-call"><command>CALL</command></link> command.  If the <command>CALL</command> command is not
-    part of an explicit transaction, a procedure in many server-side
-    languages can commit, rollback, and begin new transactions during
-    its execution, which is not possible in functions.
+    part of an explicit transaction block, a procedure can commit or roll back
+    transactions (then automatically beginning a new transaction) during
+    its execution, which a function cannot do.
    </para>
 
    <para>
-    The explanations on how to define user-defined functions in the rest of
-    this chapter apply to procedures as well, except that
+    The explanations in the following sections about how to define
+    user-defined functions apply to procedures as well, except that
     the <link linkend="sql-createprocedure"><command>CREATE PROCEDURE</command></link> command is used instead, there is
     no return type, and some other features such as strictness don't apply.
    </para>