1<!--
2doc/src/sgml/ref/call.sgml
3PostgreSQL documentation
4-->
5
6<refentry id="sql-call">
7 <indexterm zone="sql-call">
8  <primary>CALL</primary>
9 </indexterm>
10
11 <refmeta>
12  <refentrytitle>CALL</refentrytitle>
13  <manvolnum>7</manvolnum>
14  <refmiscinfo>SQL - Language Statements</refmiscinfo>
15 </refmeta>
16
17 <refnamediv>
18  <refname>CALL</refname>
19  <refpurpose>invoke a procedure</refpurpose>
20 </refnamediv>
21
22 <refsynopsisdiv>
23<synopsis>
24CALL <replaceable class="parameter">name</replaceable> ( [ <replaceable class="parameter">argument</replaceable> ] [, ...] )
25</synopsis>
26 </refsynopsisdiv>
27
28 <refsect1>
29  <title>Description</title>
30
31  <para>
32   <command>CALL</command> executes a procedure.
33  </para>
34
35  <para>
36   If the procedure has any output parameters, then a result row will be
37   returned, containing the values of those parameters.
38  </para>
39 </refsect1>
40
41 <refsect1>
42  <title>Parameters</title>
43
44  <variablelist>
45   <varlistentry>
46    <term><replaceable class="parameter">name</replaceable></term>
47    <listitem>
48     <para>
49      The name (optionally schema-qualified) of the procedure.
50     </para>
51    </listitem>
52   </varlistentry>
53
54  <varlistentry>
55    <term><replaceable class="parameter">argument</replaceable></term>
56    <listitem>
57     <para>
58      An argument expression for the procedure call.
59     </para>
60
61     <para>
62      Arguments can include parameter names, using the syntax
63      <literal><replaceable class="parameter">name</replaceable> =&gt; <replaceable class="parameter">value</replaceable></literal>.
64      This works the same as in ordinary function calls; see
65      <xref linkend="sql-syntax-calling-funcs"/> for details.
66     </para>
67
68     <para>
69      Arguments must be supplied for all procedure parameters that lack
70      defaults, including <literal>OUT</literal> parameters.  However,
71      arguments matching <literal>OUT</literal> parameters are not evaluated,
72      so it's customary to just write <literal>NULL</literal> for them.
73      (Writing something else for an <literal>OUT</literal> parameter
74      might cause compatibility problems with
75      future <productname>PostgreSQL</productname> versions.)
76     </para>
77    </listitem>
78   </varlistentry>
79  </variablelist>
80 </refsect1>
81
82 <refsect1>
83  <title>Notes</title>
84
85  <para>
86   The user must have <literal>EXECUTE</literal> privilege on the procedure in
87   order to be allowed to invoke it.
88  </para>
89
90  <para>
91   To call a function (not a procedure), use <command>SELECT</command> instead.
92  </para>
93
94  <para>
95   If <command>CALL</command> is executed in a transaction block, then the
96   called procedure cannot execute transaction control statements.
97   Transaction control statements are only allowed if <command>CALL</command>
98   is executed in its own transaction.
99  </para>
100
101  <para>
102   <application>PL/pgSQL</application> handles output parameters
103   in <command>CALL</command> commands differently;
104   see <xref linkend="plpgsql-statements-calling-procedure"/>.
105  </para>
106 </refsect1>
107
108 <refsect1>
109  <title>Examples</title>
110<programlisting>
111CALL do_db_maintenance();
112</programlisting>
113 </refsect1>
114
115 <refsect1>
116  <title>Compatibility</title>
117
118  <para>
119   <command>CALL</command> conforms to the SQL standard,
120   except for the handling of output parameters.  The standard
121   says that users should write variables to receive the values
122   of output parameters.
123  </para>
124 </refsect1>
125
126 <refsect1>
127  <title>See Also</title>
128
129  <simplelist type="inline">
130   <member><xref linkend="sql-createprocedure"/></member>
131  </simplelist>
132 </refsect1>
133</refentry>
134