2017-11-30 14:46:13 +01:00
|
|
|
<!--
|
|
|
|
doc/src/sgml/ref/call.sgml
|
|
|
|
PostgreSQL documentation
|
|
|
|
-->
|
|
|
|
|
|
|
|
<refentry id="sql-call">
|
|
|
|
<indexterm zone="sql-call">
|
|
|
|
<primary>CALL</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
|
|
|
<refmeta>
|
|
|
|
<refentrytitle>CALL</refentrytitle>
|
|
|
|
<manvolnum>7</manvolnum>
|
|
|
|
<refmiscinfo>SQL - Language Statements</refmiscinfo>
|
|
|
|
</refmeta>
|
|
|
|
|
|
|
|
<refnamediv>
|
|
|
|
<refname>CALL</refname>
|
|
|
|
<refpurpose>invoke a procedure</refpurpose>
|
|
|
|
</refnamediv>
|
|
|
|
|
|
|
|
<refsynopsisdiv>
|
|
|
|
<synopsis>
|
2018-03-05 17:27:08 +01:00
|
|
|
CALL <replaceable class="parameter">name</replaceable> ( [ <replaceable class="parameter">argument</replaceable> ] [, ...] )
|
2017-11-30 14:46:13 +01:00
|
|
|
</synopsis>
|
|
|
|
</refsynopsisdiv>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Description</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
<command>CALL</command> executes a procedure.
|
|
|
|
</para>
|
2018-03-14 16:47:21 +01:00
|
|
|
|
|
|
|
<para>
|
2018-11-04 19:25:39 +01:00
|
|
|
If the procedure has any output parameters, then a result row will be
|
|
|
|
returned, containing the values of those parameters.
|
2018-03-14 16:47:21 +01:00
|
|
|
</para>
|
2017-11-30 14:46:13 +01:00
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Parameters</title>
|
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">name</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The name (optionally schema-qualified) of the procedure.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><replaceable class="parameter">argument</replaceable></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
Reconsider the handling of procedure OUT parameters.
Commit 2453ea142 redefined pg_proc.proargtypes to include the types of
OUT parameters, for procedures only. While that had some advantages
for implementing the SQL-spec behavior of DROP PROCEDURE, it was pretty
disastrous from a number of other perspectives. Notably, since the
primary key of pg_proc is name + proargtypes, this made it possible to
have multiple procedures with identical names + input arguments and
differing output argument types. That would make it impossible to call
any one of the procedures by writing just NULL (or "?", or any other
data-type-free notation) for the output argument(s). The change also
seems likely to cause grave confusion for client applications that
examine pg_proc and expect the traditional definition of proargtypes.
Hence, revert the definition of proargtypes to what it was, and
undo a number of complications that had been added to support that.
To support the SQL-spec behavior of DROP PROCEDURE, when there are
no argmode markers in the command's parameter list, we perform the
lookup both ways (that is, matching against both proargtypes and
proallargtypes), succeeding if we get just one unique match.
In principle this could result in ambiguous-function failures
that would not happen when using only one of the two rules.
However, overloading of procedure names is thought to be a pretty
rare usage, so this shouldn't cause many problems in practice.
Postgres-specific code such as pg_dump can defend against any
possibility of such failures by being careful to specify argmodes
for all procedure arguments.
This also fixes a few other bugs in the area of CALL statements
with named parameters, and improves the documentation a little.
catversion bump forced because the representation of procedures
with OUT arguments changes.
Discussion: https://postgr.es/m/3742981.1621533210@sss.pgh.pa.us
2021-06-10 23:11:36 +02:00
|
|
|
An argument expression for the procedure call.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Arguments can include parameter names, using the syntax
|
|
|
|
<literal><replaceable class="parameter">name</replaceable> => <replaceable class="parameter">value</replaceable></literal>.
|
|
|
|
This works the same as in ordinary function calls; see
|
|
|
|
<xref linkend="sql-syntax-calling-funcs"/> for details.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Arguments must be supplied for all procedure parameters that lack
|
|
|
|
defaults, including <literal>OUT</literal> parameters. However,
|
|
|
|
arguments matching <literal>OUT</literal> parameters are not evaluated,
|
|
|
|
so it's customary to just write <literal>NULL</literal> for them.
|
|
|
|
(Writing something else for an <literal>OUT</literal> parameter
|
|
|
|
might cause compatibility problems with
|
|
|
|
future <productname>PostgreSQL</productname> versions.)
|
2017-11-30 14:46:13 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Notes</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The user must have <literal>EXECUTE</literal> privilege on the procedure in
|
|
|
|
order to be allowed to invoke it.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
To call a function (not a procedure), use <command>SELECT</command> instead.
|
|
|
|
</para>
|
Transaction control in PL procedures
In each of the supplied procedural languages (PL/pgSQL, PL/Perl,
PL/Python, PL/Tcl), add language-specific commit and rollback
functions/commands to control transactions in procedures in that
language. Add similar underlying functions to SPI. Some additional
cleanup so that transaction commit or abort doesn't blow away data
structures still used by the procedure call. Add execution context
tracking to CALL and DO statements so that transaction control commands
can only be issued in top-level procedure and block calls, not function
calls or other procedure or block calls.
- SPI
Add a new function SPI_connect_ext() that is like SPI_connect() but
allows passing option flags. The only option flag right now is
SPI_OPT_NONATOMIC. A nonatomic SPI connection can execute transaction
control commands, otherwise it's not allowed. This is meant to be
passed down from CALL and DO statements which themselves know in which
context they are called. A nonatomic SPI connection uses different
memory management. A normal SPI connection allocates its memory in
TopTransactionContext. For nonatomic connections we use PortalContext
instead. As the comment in SPI_connect_ext() (previously SPI_connect())
indicates, one could potentially use PortalContext in all cases, but it
seems safest to leave the existing uses alone, because this stuff is
complicated enough already.
SPI also gets new functions SPI_start_transaction(), SPI_commit(), and
SPI_rollback(), which can be used by PLs to implement their transaction
control logic.
- portalmem.c
Some adjustments were made in the code that cleans up portals at
transaction abort. The portal code could already handle a command
*committing* a transaction and continuing (e.g., VACUUM), but it was not
quite prepared for a command *aborting* a transaction and continuing.
In AtAbort_Portals(), remove the code that marks an active portal as
failed. As the comment there already predicted, this doesn't work if
the running command wants to keep running after transaction abort. And
it's actually not necessary, because pquery.c is careful to run all
portal code in a PG_TRY block and explicitly runs MarkPortalFailed() if
there is an exception. So the code in AtAbort_Portals() is never used
anyway.
In AtAbort_Portals() and AtCleanup_Portals(), we need to be careful not
to clean up active portals too much. This mirrors similar code in
PreCommit_Portals().
- PL/Perl
Gets new functions spi_commit() and spi_rollback()
- PL/pgSQL
Gets new commands COMMIT and ROLLBACK.
Update the PL/SQL porting example in the documentation to reflect that
transactions are now possible in procedures.
- PL/Python
Gets new functions plpy.commit and plpy.rollback.
- PL/Tcl
Gets new commands commit and rollback.
Reviewed-by: Andrew Dunstan <andrew.dunstan@2ndquadrant.com>
2018-01-22 14:30:16 +01:00
|
|
|
|
|
|
|
<para>
|
|
|
|
If <command>CALL</command> is executed in a transaction block, then the
|
|
|
|
called procedure cannot execute transaction control statements.
|
|
|
|
Transaction control statements are only allowed if <command>CALL</command>
|
|
|
|
is executed in its own transaction.
|
|
|
|
</para>
|
2018-11-04 19:25:39 +01:00
|
|
|
|
|
|
|
<para>
|
|
|
|
<application>PL/pgSQL</application> handles output parameters
|
|
|
|
in <command>CALL</command> commands differently;
|
|
|
|
see <xref linkend="plpgsql-statements-calling-procedure"/>.
|
|
|
|
</para>
|
2017-11-30 14:46:13 +01:00
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Examples</title>
|
|
|
|
<programlisting>
|
|
|
|
CALL do_db_maintenance();
|
|
|
|
</programlisting>
|
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Compatibility</title>
|
|
|
|
|
|
|
|
<para>
|
Reconsider the handling of procedure OUT parameters.
Commit 2453ea142 redefined pg_proc.proargtypes to include the types of
OUT parameters, for procedures only. While that had some advantages
for implementing the SQL-spec behavior of DROP PROCEDURE, it was pretty
disastrous from a number of other perspectives. Notably, since the
primary key of pg_proc is name + proargtypes, this made it possible to
have multiple procedures with identical names + input arguments and
differing output argument types. That would make it impossible to call
any one of the procedures by writing just NULL (or "?", or any other
data-type-free notation) for the output argument(s). The change also
seems likely to cause grave confusion for client applications that
examine pg_proc and expect the traditional definition of proargtypes.
Hence, revert the definition of proargtypes to what it was, and
undo a number of complications that had been added to support that.
To support the SQL-spec behavior of DROP PROCEDURE, when there are
no argmode markers in the command's parameter list, we perform the
lookup both ways (that is, matching against both proargtypes and
proallargtypes), succeeding if we get just one unique match.
In principle this could result in ambiguous-function failures
that would not happen when using only one of the two rules.
However, overloading of procedure names is thought to be a pretty
rare usage, so this shouldn't cause many problems in practice.
Postgres-specific code such as pg_dump can defend against any
possibility of such failures by being careful to specify argmodes
for all procedure arguments.
This also fixes a few other bugs in the area of CALL statements
with named parameters, and improves the documentation a little.
catversion bump forced because the representation of procedures
with OUT arguments changes.
Discussion: https://postgr.es/m/3742981.1621533210@sss.pgh.pa.us
2021-06-10 23:11:36 +02:00
|
|
|
<command>CALL</command> conforms to the SQL standard,
|
|
|
|
except for the handling of output parameters. The standard
|
|
|
|
says that users should write variables to receive the values
|
|
|
|
of output parameters.
|
2017-11-30 14:46:13 +01:00
|
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>See Also</title>
|
|
|
|
|
|
|
|
<simplelist type="inline">
|
|
|
|
<member><xref linkend="sql-createprocedure"/></member>
|
|
|
|
</simplelist>
|
|
|
|
</refsect1>
|
|
|
|
</refentry>
|