<term><symbol>SPI_ERROR_ARGUMENT</symbol></term>
     <listitem>
      <para>
       if <parameter>plan</parameter> is <symbol>NULL</symbol> or invalid,
       or <parameter>count</parameter> is less than 0
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><symbol>SPI_ERROR_PARAM</symbol></term>
     <listitem>
      <para>
       if <parameter>values</parameter> is <symbol>NULL</symbol> and
       <parameter>plan</parameter> was prepared with some parameters
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>

  <para>
   <varname>SPI_processed</varname> and
   <varname>SPI_tuptable</varname> are set as in
   <function>SPI_execute</function> if successful.
  </para>
 </refsect1>
</refentry>

<!-- *********************************************** -->

<refentry id="spi-spi-execute-plan-extended">
 <indexterm><primary>SPI_execute_plan_extended</primary></indexterm>

 <refmeta>
  <refentrytitle>SPI_execute_plan_extended</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_execute_plan_extended</refname>
  <refpurpose>execute a statement prepared by <function>SPI_prepare</function></refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
int SPI_execute_plan_extended(SPIPlanPtr <parameter>plan</parameter>,
                              const SPIExecuteOptions * <parameter>options</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_execute_plan_extended</function> executes a statement
   prepared by <function>SPI_prepare</function> or one of its siblings.
   This function is equivalent to <function>SPI_execute_plan</function>,
   except that information about the parameter values to be passed to the
   query is presented differently, and additional execution-controlling
   options can be passed.
  </para>

  <para>
   Query parameter values are represented by
   a <literal>ParamListInfo</literal> struct, which is convenient for passing
   down values that are already available in that format.  Dynamic parameter
   sets can also be used, via hook functions specified
   in <literal>ParamListInfo</literal>.
  </para>

  <para>
   Also, instead of always accumulating the result tuples into a
   <varname>SPI_tuptable</varname> structure, tuples can be passed to a
   caller-supplied <literal>DestReceiver</literal> object as they are
   generated by the executor.  This is particularly helpful for queries
   that might generate many tuples, since the data can be processed
   on-the-fly instead of being accumulated in memory.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>SPIPlanPtr <parameter>plan</parameter></literal></term>
    <listitem>
     <para>
      prepared statement (returned by <function>SPI_prepare</function>)
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>const SPIExecuteOptions * <parameter>options</parameter></literal></term>
    <listitem>
     <para>
      struct containing optional arguments
     </para>
    </listitem>
   </varlistentry>
  </variablelist>

  <para>
   Callers should always zero out the entire <parameter>options</parameter>
   struct, then fill whichever fields they want to set.  This ensures forward
   compatibility of code, since any fields that are added to the struct in
   future will be defined to behave backwards-compatibly if they are zero.
   The currently available <parameter>options</parameter> fields are:
  </para>

  <variablelist>
   <varlistentry>
    <term><literal>ParamListInfo <parameter>params</parameter></literal></term>
    <listitem>
     <para>
      data structure containing query parameter types and values; NULL if none
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>bool <parameter>read_only</parameter></literal></term>
    <listitem>
     <para><literal>true</literal> for read-only execution</para>