spi.sgml

PostgreSQL 8.1.4的源码 适用于Linux下的开源数据库系统

     <term><symbol>SPI_OK_UTILITY</symbol></term>
     <listitem>
      <para>
       if a utility command (e.g., <command>CREATE TABLE</command>)
       was executed
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>

  <para>
   On error, one of the following negative values is returned:

   <variablelist>
    <varlistentry>
     <term><symbol>SPI_ERROR_ARGUMENT</symbol></term>
     <listitem>
      <para>
       if <parameter>command</parameter> is <symbol>NULL</symbol> or
       <parameter>count</parameter> is less than 0
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><symbol>SPI_ERROR_COPY</symbol></term>
     <listitem>
      <para>
       if <command>COPY TO stdout</> or <command>COPY FROM stdin</>
       was attempted
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><symbol>SPI_ERROR_CURSOR</symbol></term>
     <listitem>
      <para>
       if <command>DECLARE</>, <command>CLOSE</>, or <command>FETCH</>
       was attempted
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><symbol>SPI_ERROR_TRANSACTION</symbol></term>
     <listitem>
      <para>
	   if any command involving transaction manipulation was attempted
	   (<command>BEGIN</>,
	   <command>COMMIT</>,
	   <command>ROLLBACK</>,
	   <command>SAVEPOINT</>,
	   <command>PREPARE TRANSACTION</>,
	   <command>COMMIT PREPARED</>,
	   <command>ROLLBACK PREPARED</>,
	   or any variant thereof)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><symbol>SPI_ERROR_OPUNKNOWN</symbol></term>
     <listitem>
      <para>
       if the command type is unknown (shouldn't happen)
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><symbol>SPI_ERROR_UNCONNECTED</symbol></term>
     <listitem>
      <para>
       if called from an unconnected procedure
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1>
  <title>Notes</title>

  <para>
   The functions <function>SPI_execute</function>,
   <function>SPI_exec</function>,
   <function>SPI_execute_plan</function>, and
   <function>SPI_execp</function> change both
   <varname>SPI_processed</varname> and
   <varname>SPI_tuptable</varname> (just the pointer, not the contents
   of the structure).  Save these two global variables into local
   procedure variables if you need to access the result table of
   <function>SPI_execute</function> or a related function
   across later calls.
  </para>
 </refsect1>
</refentry>

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

<refentry id="spi-spi-exec">
 <refmeta>
  <refentrytitle>SPI_exec</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>SPI_exec</refname>
  <refpurpose>execute a read/write command</refpurpose>
 </refnamediv>

 <indexterm><primary>SPI_exec</primary></indexterm>

 <refsynopsisdiv>
<synopsis>
int SPI_exec(const char * <parameter>command</parameter>, long <parameter>count</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_exec</function> is the same as
   <function>SPI_execute</function>, with the latter's
   <parameter>read_only</parameter> parameter always taken as
   <literal>false</>.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>const char * <parameter>command</parameter></literal></term>
    <listitem>
     <para>
      string containing command to execute
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>long <parameter>count</parameter></literal></term>
    <listitem>
     <para>
      maximum number of rows to process or return
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

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

  <para>
   See <function>SPI_execute</function>.
  </para>
 </refsect1>
</refentry>

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

<refentry id="spi-spi-prepare">
 <refmeta>
  <refentrytitle>SPI_prepare</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>SPI_prepare</refname>
  <refpurpose>prepare a plan for a command, without executing it yet</refpurpose>
 </refnamediv>

 <indexterm><primary>SPI_prepare</primary></indexterm>

 <refsynopsisdiv>
<synopsis>
void * SPI_prepare(const char * <parameter>command</parameter>, int <parameter>nargs</parameter>, Oid * <parameter>argtypes</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_prepare</function> creates and returns an execution
   plan for the specified command but doesn't execute the command.
   This function should only be called from a connected procedure.
  </para>

  <para>
   When the same or a similar command is to be executed repeatedly, it
   may be advantageous to perform the planning only once.
   <function>SPI_prepare</function> converts a command string into an
   execution plan that can be executed repeatedly using
   <function>SPI_execute_plan</function>.
  </para>

  <para>
   A prepared command can be generalized by writing parameters
   (<literal>$1</>, <literal>$2</>, etc.) in place of what would be
   constants in a normal command.  The actual values of the parameters
   are then specified when <function>SPI_execute_plan</function> is called.
   This allows the prepared command to be used over a wider range of
   situations than would be possible without parameters.
  </para>

  <para>
   The plan returned by <function>SPI_prepare</function> can be used
   only in the current invocation of the procedure, since
   <function>SPI_finish</function> frees memory allocated for a plan.
   But a plan can be saved for longer using the function
   <function>SPI_saveplan</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>$2</>, 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>
  </variablelist>
 </refsect1>

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

  <para>
   <function>SPI_prepare</function> returns a non-null pointer to an
   execution plan.  On error, <symbol>NULL</symbol> will be returned,
   and <varname>SPI_result</varname> will be set to one of the same
   error codes used by <function>SPI_execute</function>, except that
   it is set to <symbol>SPI_ERROR_ARGUMENT</symbol> if
   <parameter>command</parameter> is <symbol>NULL</symbol>, or if
   <parameter>nargs</> is less than 0, or if <parameter>nargs</> is
   greater than 0 and <parameter>argtypes</> is <symbol>NULL</symbol>.
  </para>
 </refsect1>

 <refsect1>
  <title>Notes</title>

  <para>
   There is a disadvantage to using parameters: since the planner does
   not know the values that will be supplied for the parameters, it
   may make worse planning choices than it would make for a normal
   command with all constants visible.
  </para>
 </refsect1>
</refentry>

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

<refentry id="spi-spi-getargcount">
 <refmeta>
  <refentrytitle>SPI_getargcount</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>SPI_getargcount</refname>
  <refpurpose>return the number of arguments needed by a plan
  prepared by <function>SPI_prepare</function></refpurpose>
 </refnamediv>

 <indexterm><primary>SPI_getargcount</primary></indexterm>

 <refsynopsisdiv>
<synopsis>
int SPI_getargcount(void * <parameter>plan</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_getargcount</function> returns the number of arguments needed
   to execute a plan prepared by <function>SPI_prepare</function>.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>void * <parameter>plan</parameter></literal></term>
    <listitem>
     <para>
      execution plan (returned by <function>SPI_prepare</function>)
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Return Value</title>
  <para>
    The expected argument count for the <parameter>plan</parameter>, or
    <symbol>SPI_ERROR_ARGUMENT</symbol> if the <parameter>plan
    </parameter> is <symbol>NULL</symbol>
  </para>
 </refsect1>
</refentry>

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

<refentry id="spi-spi-getargtypeid">
 <refmeta>
  <refentrytitle>SPI_getargtypeid</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>SPI_getargtypeid</refname>
  <refpurpose>return the data type OID for an argument of
  a plan prepared by <function>SPI_prepare</function></refpurpose>
 </refnamediv>

 <indexterm><primary>SPI_getargtypeid</primary></indexterm>

 <refsynopsisdiv>
<synopsis>
Oid SPI_getargtypeid(void * <parameter>plan</parameter>, int <parameter>argIndex</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_getargtypeid</function> returns the OID representing the type
   id for the <parameter>argIndex</parameter>'th argument of a plan prepared by
   <function>SPI_prepare</function>. First argument is at index zero.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>void * <parameter>plan</parameter></literal></term>
    <listitem>
     <para>
      execution plan (returned by <function>SPI_prepare</function>)
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>int <parameter>argIndex</parameter></literal></term>
    <listitem>
     <para>
      zero based index of the argument
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Return Value</title>
  <para>
    The type id of the argument at the given index, or
    <symbol>SPI_ERROR_ARGUMENT</symbol> if the <parameter>plan</parameter> is
    <symbol>NULL</symbol> or <parameter>argIndex</parameter> is less than 0 or
    not less than the number of arguments declared for the
    <parameter>plan</parameter>
  </para>
 </refsect1>
</refentry>

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

<refentry id="spi-spi-is-cursor-plan">
 <refmeta>
  <refentrytitle>SPI_is_cursor_plan</refentrytitle>
 </refmeta>

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

 <indexterm><primary>SPI_is_cursor_plan</primary></indexterm>

 <refsynopsisdiv>
<synopsis>
bool SPI_is_cursor_plan(void * <parameter>plan</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_is_cursor_plan</function> returns <symbol>true</symbol>
   if a plan prepared by <function>SPI_prepare</function> can be passed
   as an argument to <function>SPI_cursor_open</function> and <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 is a <command>SELECT</command> without an <command>INTO</command>
   clause.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>void * <parameter>plan</parameter></literal></term>
    <listitem>
     <para>
      execution plan (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, or
    <symbol>SPI_ERROR_ARGUMENT</symbol> if the <parameter>plan</parameter>
    is <symbol>NULL</symbol>
  </para>
 </refsect1>
</refentry>

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

<refentry id="spi-spi-execute-plan">
 <refmeta>
  <refentrytitle>SPI_execute_plan</refentrytitle>
 </refmeta>

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

 <indexterm><primary>SPI_execute_plan</primary></indexterm>

 <refsynopsisdiv>
<synopsis>
int SPI_execute_plan(void * <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>