Home • Explore • Blog • CI
☰



postgresql
10th chunk of `doc/src/sgml/spi.sgml`
aa1b7ffcf2840fe31c228ae15d3c0f2b966095f728771f780000000100000fa6
 provided.
   For one-time query execution, this function should be preferred.
   If the same command is to be executed with many different parameters,
   either method might be faster, depending on the cost of re-planning
   versus the benefit of custom plans.
  </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>int <parameter>nargs</parameter></literal></term>
    <listitem>
     <para>
      number of input parameters (<literal>$1</literal>, <literal>$2</literal>, etc.)
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>Oid * <parameter>argtypes</parameter></literal></term>
    <listitem>
     <para>
      an array of length <parameter>nargs</parameter>, containing the
      <acronym>OID</acronym>s of the data types of the parameters
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>Datum * <parameter>values</parameter></literal></term>
    <listitem>
     <para>
      an array of length <parameter>nargs</parameter>, containing the actual
      parameter values
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>const char * <parameter>nulls</parameter></literal></term>
    <listitem>
     <para>
      an array of length <parameter>nargs</parameter>, describing which
      parameters are null
     </para>

     <para>
      If <parameter>nulls</parameter> is <symbol>NULL</symbol> then
      <function>SPI_execute_with_args</function> assumes that no parameters
      are null.  Otherwise, each entry of the <parameter>nulls</parameter>
      array should be <literal>'&nbsp;'</literal> if the corresponding parameter
      value is non-null, or <literal>'n'</literal> if the corresponding parameter
      value is null.  (In the latter case, the actual value in the
      corresponding <parameter>values</parameter> entry doesn't matter.)  Note
      that <parameter>nulls</parameter> is not a text string, just an array:
      it does not need a <literal>'\0'</literal> terminator.
     </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>long <parameter>count</parameter></literal></term>
    <listitem>
     <para>
      maximum number of rows to return,
      or <literal>0</literal> for no limit
     </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>
   <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-prepare">
 <indexterm><primary>SPI_prepare</primary></indexterm>

 <refmeta>
  <refentrytitle>SPI_prepare</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_prepare</refname>
  <refpurpose>prepare a statement, without executing it yet</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
SPIPlanPtr SPI_prepare(const char * <parameter>command</parameter>, int <parameter>nargs</parameter>, Oid * <parameter>argtypes</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_prepare</function> creates and returns a prepared
   statement for the specified command, but doesn't execute the command.
   The prepared statement can later be executed repeatedly using
   <function>SPI_execute_plan</function>.
Title: SPI_execute_with_args Arguments and Return Value, Introduction to SPI_prepare
Summary
This section provides a detailed explanation of the arguments used in the `SPI_execute_with_args` function, including the command string, number of input parameters, their data types and values, handling of null parameters, read-only execution flag, and the maximum number of rows to return. It also specifies that the return value and how `SPI_processed` and `SPI_tuptable` are set are the same as for `SPI_execute`. The section concludes by introducing the `SPI_prepare` function, which prepares a statement for later execution using `SPI_execute_plan`.