Home • Explore • Blog • CI
☰



postgresql
13th chunk of `doc/src/sgml/spi.sgml`
ff12fb1b998cb3efa4574c57f1f16bf33381bb559e3a32e40000000100000fa0
 <productname>PostgreSQL</productname>.
  </para>

  <para>
   The name <type>SPIPlanPtr</type> is somewhat historical, since the data
   structure no longer necessarily contains an execution plan.
  </para>
 </refsect1>
</refentry>

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

<refentry id="spi-spi-prepare-cursor">
 <indexterm><primary>SPI_prepare_cursor</primary></indexterm>

 <refmeta>
  <refentrytitle>SPI_prepare_cursor</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

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

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

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_prepare_cursor</function> is identical to
   <function>SPI_prepare</function>, except that it also allows specification
   of the planner's <quote>cursor options</quote> parameter.  This is a bit mask
   having the values shown in <filename>nodes/parsenodes.h</filename>
   for the <structfield>options</structfield> field of <structname>DeclareCursorStmt</structname>.
   <function>SPI_prepare</function> always takes the cursor options as zero.
  </para>

  <para>
   This function is now deprecated in favor
   of <function>SPI_prepare_extended</function>.
  </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>
      pointer to an array containing the <acronym>OID</acronym>s of
      the data types of the parameters
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>int <parameter>cursorOptions</parameter></literal></term>
    <listitem>
     <para>
      integer bit mask of cursor options; zero produces default behavior
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

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

  <para>
   <function>SPI_prepare_cursor</function> has the same return conventions as
   <function>SPI_prepare</function>.
  </para>
 </refsect1>

 <refsect1>
  <title>Notes</title>

  <para>
   Useful bits to set in <parameter>cursorOptions</parameter> include
   <symbol>CURSOR_OPT_SCROLL</symbol>,
   <symbol>CURSOR_OPT_NO_SCROLL</symbol>,
   <symbol>CURSOR_OPT_FAST_PLAN</symbol>,
   <symbol>CURSOR_OPT_GENERIC_PLAN</symbol>, and
   <symbol>CURSOR_OPT_CUSTOM_PLAN</symbol>.  Note in particular that
   <symbol>CURSOR_OPT_HOLD</symbol> is ignored.
  </para>
 </refsect1>
</refentry>

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

<refentry id="spi-spi-prepare-extended">
 <indexterm><primary>SPI_prepare_extended</primary></indexterm>

 <refmeta>
  <refentrytitle>SPI_prepare_extended</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

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

 <refsynopsisdiv>
<synopsis>
SPIPlanPtr SPI_prepare_extended(const char * <parameter>command</parameter>,
                                const SPIPrepareOptions * <parameter>options</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_prepare_extended</function> creates
Title: SPI_prepare_cursor and SPI_prepare_extended: Preparing Statements with Options
Summary
This section introduces `SPI_prepare_cursor`, which is similar to `SPI_prepare` but allows specifying planner's cursor options. It then mentions that `SPI_prepare_cursor` is deprecated in favor of `SPI_prepare_extended`. The section provides details on the arguments for `SPI_prepare_cursor`, its return value, and useful bits for the cursor options. Finally, it introduces `SPI_prepare_extended` as an extended way to create a prepared statement.