Home • Explore • Blog • CI
☰



postgresql
14th chunk of `doc/src/sgml/spi.sgml`
208b3f1e1f031abea32bdc4657e9c8d6e0f15235cf22842e0000000100000fbd
 <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 and returns a prepared
   statement for the specified command, but doesn't execute the command.
   This function is equivalent to <function>SPI_prepare</function>,
   with the addition that the caller can specify options to control
   the parsing of external parameter references, as well as other facets
   of query parsing and planning.
  </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>const SPIPrepareOptions * <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>ParserSetupHook <parameter>parserSetup</parameter></literal></term>
    <listitem>
     <para>
      Parser hook setup function
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>void * <parameter>parserSetupArg</parameter></literal></term>
    <listitem>
     <para>
      pass-through argument for <parameter>parserSetup</parameter>
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>RawParseMode <parameter>parseMode</parameter></literal></term>
    <listitem>
     <para>
      mode for raw parsing; <literal>RAW_PARSE_DEFAULT</literal> (zero)
      produces default behavior
     </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_extended</function> has the same return conventions as
   <function>SPI_prepare</function>.
  </para>
 </refsect1>
</refentry>

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

<refentry id="spi-spi-prepare-params">
 <indexterm><primary>SPI_prepare_params</primary></indexterm>

 <refmeta>
  <refentrytitle>SPI_prepare_params</refentrytitle>
  <manvolnum>3</manvolnum>
 </refmeta>

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

 <refsynopsisdiv>
<synopsis>
SPIPlanPtr SPI_prepare_params(const char * <parameter>command</parameter>,
Title: SPI_prepare_extended: Preparing Statements with Advanced Options
Summary
This section details the `SPI_prepare_extended` function, which prepares a statement for execution without actually running it. It's similar to `SPI_prepare` but offers more control over parsing and planning through options. The function takes the command string and an `SPIPrepareOptions` struct as arguments. The `SPIPrepareOptions` struct includes fields for parser setup, parser setup arguments, raw parse mode, and cursor options. The section also advises to zero-initialize the `options` struct to ensure forward compatibility.