Home • Explore • Blog • CI
☰



postgresql
8th chunk of `doc/src/sgml/spi.sgml`
3bc0bcc7348f701e9653a592ebcb50c720798aef7a32fe570000000100000fa2
 accumulated in <varname>SPI_tuptable</varname>.  Using
   a caller-supplied <literal>DestReceiver</literal> object 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>const char * <parameter>command</parameter></literal></term>
    <listitem>
     <para>
      command string
     </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>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>bool <parameter>allow_nonatomic</parameter></literal></term>
    <listitem>
     <para>
      <literal>true</literal> allows non-atomic execution of CALL and DO
      statements (but this field is ignored unless
      the <symbol>SPI_OPT_NONATOMIC</symbol> flag was passed
      to <function>SPI_connect_ext</function>)
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>bool <parameter>must_return_tuples</parameter></literal></term>
    <listitem>
     <para>
      if <literal>true</literal>, raise error if the query is not of a kind
      that returns tuples (this does not forbid the case where it happens to
      return zero tuples)
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>uint64 <parameter>tcount</parameter></literal></term>
    <listitem>
     <para>
      maximum number of rows to return,
      or <literal>0</literal> for no limit
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>DestReceiver * <parameter>dest</parameter></literal></term>
    <listitem>
     <para>
      <literal>DestReceiver</literal> object that will receive any tuples
      emitted by the query; if NULL, result tuples are accumulated into
      a <varname>SPI_tuptable</varname> structure, as
      in <function>SPI_execute</function>
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>ResourceOwner <parameter>owner</parameter></literal></term>
    <listitem>
     <para>
      This field is present for consistency
      with <function>SPI_execute_plan_extended</function>, but it is
      ignored, since the plan used
      by <function>SPI_execute_extended</function> is never saved.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Return Value</title>

  <para>
   The return value is the same as for <function>SPI_execute</function>.
  </para>

  <para>
   When <parameter>options-&gt;dest</parameter> is NULL,
   <varname>SPI_processed</varname> and
   <varname>SPI_tuptable</varname> are set as in
   <function>SPI_execute</function>.
   When <parameter>options-&gt;dest</parameter> is not NULL,
   <varname>SPI_processed</varname> is set to zero and
   <varname>SPI_tuptable</varname> is set
Title: SPI_execute_extended Arguments and Return Value Details
Summary
This section provides detailed information about the arguments for the `SPI_execute_extended` function, specifically focusing on the `SPIExecuteOptions` struct. It explains the importance of initializing the struct by zeroing it out for forward compatibility. The section outlines the available fields within the `SPIExecuteOptions` struct, including `params`, `read_only`, `allow_nonatomic`, `must_return_tuples`, `tcount`, `dest`, and `owner`, detailing their purpose and usage. It also specifies that the return value is the same as `SPI_execute` and notes how `SPI_processed` and `SPI_tuptable` are set depending on whether `options->dest` is NULL.