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>
  </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-parse-open">
 <indexterm><primary>SPI_cursor_parse_open</primary></indexterm>

 <refmeta>
  <refentrytitle>SPI_cursor_parse_open</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

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

 <refsynopsisdiv>
<synopsis>
Portal SPI_cursor_parse_open(const char *<parameter>name</parameter>,
                             const char *<parameter>command</parameter>,
                             const SPIParseOpenOptions * <parameter>options</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_cursor_parse_open</function> sets up a cursor
   (internally, a portal) that will execute the specified query string.
   This is comparable to <function>SPI_prepare_cursor</function> followed
   by <function>SPI_cursor_open_with_paramlist</function>, except that
   parameter references within the query string are handled entirely by
   supplying a <literal>ParamListInfo</literal> object.
  </para>

  <para>
   For one-time query execution, this function should be preferred
   over <function>SPI_prepare_cursor</function> followed by
   <function>SPI_cursor_open_with_paramlist</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 <parameter>options-&gt;params</parameter> object should normally
   mark each parameter with the <literal>PARAM_FLAG_CONST</literal> flag,
   since a one-shot plan is always used for the query.
  </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>
 </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>
    <listitem>
     <para>
      command string
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>const SPIParseOpenOptions * <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>int <parameter>cursorOptions</parameter></literal></term>