Home Explore Blog CI



postgresql

24th chunk of `doc/src/sgml/spi.sgml`
e5b582e6863c2d75e49a88676cbd0317bdee2f49a9ec79cd0000000100000fc3
 statement's number of arguments.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>const char * <parameter>nulls</parameter></literal></term>
    <listitem>
     <para>
      An array describing which parameters are null.  Must have same length as
      the statement's number of arguments.
     </para>

     <para>
      If <parameter>nulls</parameter> is <symbol>NULL</symbol> then
      <function>SPI_cursor_open</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>
  </variablelist>
 </refsect1>

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

  <para>
   Pointer to portal containing the cursor.  Note there is no error
   return convention; any error will be reported via <function>elog</function>.
  </para>
 </refsect1>
</refentry>

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

<refentry id="spi-spi-cursor-open-with-args">
 <indexterm><primary>SPI_cursor_open_with_args</primary></indexterm>

 <refmeta>
  <refentrytitle>SPI_cursor_open_with_args</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

 <refnamediv>
  <refname>SPI_cursor_open_with_args</refname>
  <refpurpose>set up a cursor using a query and parameters</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
Portal SPI_cursor_open_with_args(const char *<parameter>name</parameter>,
                                 const char *<parameter>command</parameter>,
                                 int <parameter>nargs</parameter>, Oid *<parameter>argtypes</parameter>,
                                 Datum *<parameter>values</parameter>, const char *<parameter>nulls</parameter>,
                                 bool <parameter>read_only</parameter>, int <parameter>cursorOptions</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_cursor_open_with_args</function> sets up a cursor
   (internally, a portal) that will execute the specified query.
   Most of the parameters have the same meanings as the corresponding
   parameters to <function>SPI_prepare_cursor</function>
   and <function>SPI_cursor_open</function>.
  </para>

  <para>
   For one-time query execution, this function should be preferred
   over <function>SPI_prepare_cursor</function> followed by
   <function>SPI_cursor_open</function>.
   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>

  <para>
   The passed-in parameter data will be copied into the cursor's portal, so it
   can be freed while the cursor still exists.
  </para>

  <para>
   This function is now deprecated in favor
   of <function>SPI_cursor_parse_open</function>, which provides equivalent
   functionality using a more modern API for handling query parameters.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>const char * <parameter>name</parameter></literal></term>
    <listitem>
     <para>
      name for portal, or <symbol>NULL</symbol> to let the system
      select a name
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>const char * <parameter>command</parameter></literal></term>

Title: SPI_cursor_open and SPI_cursor_open_with_args: Cursor Management in SPI
Summary
This section describes the `SPI_cursor_open` function, detailing the `read_only` argument. It then moves on to `SPI_cursor_open_with_args`, a function that sets up a cursor to execute a query, with parameters similar to `SPI_prepare_cursor` and `SPI_cursor_open`. This function is recommended for one-time query execution over preparing and then opening a cursor. Parameter data is copied into the portal. It is deprecated in favor of `SPI_cursor_parse_open`. Arguments for `SPI_cursor_open_with_args` are then specified including the portal name and the command to execute.