execute.sgml 3.43 KB
Newer Older
1
<!--
2
$PostgreSQL: pgsql/doc/src/sgml/ref/execute.sgml,v 1.14 2006/09/16 00:30:18 momjian Exp $
3 4 5 6 7 8 9 10
PostgreSQL documentation
-->

<refentry id="SQL-EXECUTE">
 <refmeta>
  <refentrytitle id="sql-execute-title">EXECUTE</refentrytitle>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>
11

12
 <refnamediv>
13 14
  <refname>EXECUTE</refname>
  <refpurpose>execute a prepared statement</refpurpose>
15
 </refnamediv>
16

Peter Eisentraut's avatar
Peter Eisentraut committed
17 18 19 20
 <indexterm zone="sql-execute">
  <primary>EXECUTE</primary>
 </indexterm>

21 22 23 24 25
 <indexterm zone="sql-execute">
  <primary>prepared statements</primary>
  <secondary>executing</secondary>
 </indexterm>

26 27
 <refsynopsisdiv>
<synopsis>
28
EXECUTE <replaceable class="PARAMETER">name</replaceable> [ (<replaceable class="PARAMETER">parameter</replaceable> [, ...] ) ]
29
</synopsis>
30 31
 </refsynopsisdiv>

32 33
 <refsect1>
  <title>Description</title>
34 35 36

  <para>
   <command>EXECUTE</command> is used to execute a previously prepared
37 38
   statement. Since prepared statements only exist for the duration of a
   session, the prepared statement must have been created by a
39 40 41 42 43
   <command>PREPARE</command> statement executed earlier in the
   current session.
  </para>

  <para>
44
   If the <command>PREPARE</command> statement that created the statement
45 46
   specified some parameters, a compatible set of parameters must be
   passed to the <command>EXECUTE</command> statement, or else an
47 48 49
   error is raised. Note that (unlike functions) prepared statements are
   not overloaded based on the type or number of their parameters; the
   name of a prepared statement must be unique within a database session.
50 51 52
  </para>

  <para>
53
   For more information on the creation and usage of prepared statements,
54 55 56 57
   see <xref linkend="sql-prepare" endterm="sql-prepare-title">.
  </para>
 </refsect1>

58 59 60 61 62
 <refsect1>
  <title>Parameters</title>

  <variablelist>
   <varlistentry>
63
    <term><replaceable class="PARAMETER">name</replaceable></term>
64 65 66 67 68 69
    <listitem>
     <para>
      The name of the prepared statement to execute.
     </para>
    </listitem>
   </varlistentry>
70

71 72 73 74 75
   <varlistentry>
    <term><replaceable class="PARAMETER">parameter</replaceable></term>
    <listitem>
     <para>
      The actual value of a parameter to the prepared statement.  This
76 77 78
      must be an expression yielding a value that is compatible with
      the data type of this parameter, as was determined when the
      prepared statement was created.
79 80 81 82 83 84
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

85
 <refsect1>
86
  <title>Outputs</title>
87
   <para>
88 89 90 91 92 93 94 95
   The command tag returned by <command>EXECUTE</command>
   is that of the prepared statement, and not <literal>EXECUTE</>.
  </para>
 </refsect1>

 <refsect1>
  <title>Examples</>
  <para>
96 97 98 99 100 101
    Examples are given in the <xref linkend="sql-prepare-examples"
    endterm="sql-prepare-examples-title"> section of the <xref
    linkend="sql-prepare" endterm="sql-prepare-title"> documentation.
   </para>
 </refsect1>

102 103 104 105 106 107 108 109 110
 <refsect1>
  <title>Compatibility</title>

  <para>
   The SQL standard includes an <command>EXECUTE</command> statement,
   but it is only for use in embedded SQL.  This version of the
   <command>EXECUTE</command> statement also uses a somewhat different
   syntax.
  </para>
111
 </refsect1>
112 113 114 115 116 117 118 119 120

 <refsect1>
  <title>See Also</title>

  <simplelist type="inline">
   <member><xref linkend="sql-deallocate" endterm="sql-deallocate-title"></member>
   <member><xref linkend="sql-prepare" endterm="sql-prepare-title"></member>
  </simplelist>
 </refsect1>
121
</refentry>