Home • Explore • Blog • CI
☰



postgresql
17th chunk of `doc/src/sgml/spi.sgml`
05a9543974d936a41ad751f0ac583896d5d5dd4a56c16f460000000100000fad
 given index.
    If the <parameter>plan</parameter> is <symbol>NULL</symbol> or invalid,
    or <parameter>argIndex</parameter> is less than 0 or
    not less than the number of arguments declared for the
    <parameter>plan</parameter>,
    <varname>SPI_result</varname> is set to <symbol>SPI_ERROR_ARGUMENT</symbol>
    and <symbol>InvalidOid</symbol> is returned.
  </para>
 </refsect1>
</refentry>

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

<refentry id="spi-spi-is-cursor-plan">
 <indexterm><primary>SPI_is_cursor_plan</primary></indexterm>

 <refmeta>
  <refentrytitle>SPI_is_cursor_plan</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_is_cursor_plan</refname>
  <refpurpose>return <symbol>true</symbol> if a statement
  prepared by <function>SPI_prepare</function> can be used with
  <function>SPI_cursor_open</function></refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
bool SPI_is_cursor_plan(SPIPlanPtr <parameter>plan</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_is_cursor_plan</function> returns <symbol>true</symbol>
   if a statement prepared by <function>SPI_prepare</function> can be passed
   as an argument to <function>SPI_cursor_open</function>, or
   <symbol>false</symbol> if that is not the case. The criteria are that the
   <parameter>plan</parameter> represents one single command and that this
   command returns tuples to the caller; for example, <command>SELECT</command>
   is allowed unless it contains an <literal>INTO</literal> clause, and
   <command>UPDATE</command> is allowed only if it contains a <literal>RETURNING</literal>
   clause.
  </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>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Return Value</title>
  <para>
    <symbol>true</symbol> or <symbol>false</symbol> to indicate if the
    <parameter>plan</parameter> can produce a cursor or not, with
    <varname>SPI_result</varname> set to zero.
    If it is not possible to determine the answer (for example,
    if the <parameter>plan</parameter> is <symbol>NULL</symbol> or invalid,
    or if called when not connected to SPI), then
    <varname>SPI_result</varname> is set to a suitable error code
    and <symbol>false</symbol> is returned.
  </para>
 </refsect1>
</refentry>

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

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

 <refmeta>
  <refentrytitle>SPI_execute_plan</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

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

 <refsynopsisdiv>
<synopsis>
int SPI_execute_plan(SPIPlanPtr <parameter>plan</parameter>, Datum * <parameter>values</parameter>, const char * <parameter>nulls</parameter>,
                     bool <parameter>read_only</parameter>, long <parameter>count</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_execute_plan</function> executes a statement prepared by
   <function>SPI_prepare</function> or one of its siblings.
   <parameter>read_only</parameter> and
   <parameter>count</parameter> have the same interpretation as in
   <function>SPI_execute</function>.
  </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>
Title: SPI_is_cursor_plan and SPI_execute_plan: Functions for Using Prepared Statements
Summary
This section details two functions used with prepared statements: `SPI_is_cursor_plan`, which checks if a prepared statement (created by `SPI_prepare`) can be used with `SPI_cursor_open` (returning true if it can, false otherwise, based on whether it's a single command returning tuples), and `SPI_execute_plan`, which executes a prepared statement. `SPI_execute_plan` takes the prepared statement, an array of `Datum` values, a nulls array, a read-only flag, and a count, similar to `SPI_execute`.