spi.sgml

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

   <function>SPI_execute_plan</function> executes a plan prepared by
   <function>SPI_prepare</function>.  <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>void * <parameter>plan</parameter></literal></term>
    <listitem>
     <para>
      execution plan (returned by <function>SPI_prepare</function>)
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>Datum * <parameter>values</parameter></literal></term>
    <listitem>
     <para>
      An array of actual parameter values.  Must have same length as the
      plan'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 plan's number of arguments.
      <literal>n</literal> indicates a null value (entry in
      <parameter>values</> will be ignored); a space indicates a
      nonnull value (entry in <parameter>values</> is valid).
     </para>

     <para>
      If <parameter>nulls</parameter> is <symbol>NULL</symbol> then
      <function>SPI_execute_plan</function> assumes that no parameters are
      null.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>bool <parameter>read_only</parameter></literal></term>
    <listitem>
     <para>
      <literal>true</> for read-only execution
     </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>
   The return value is the same as for <function>SPI_execute</function>,
   with the following additional possible error (negative) results:

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

    <varlistentry>
     <term><symbol>SPI_ERROR_PARAM</symbol></term>
     <listitem>
      <para>
       if <parameter>values</parameter> is <symbol>NULL</symbol> and
       <parameter>plan</parameter> was prepared with some parameters
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>

  <para>
   <varname>SPI_processed</varname> and
   <varname>SPI_tuptable</varname> are set as in
   <function>SPI_execute</function> if successful.
  </para>
 </refsect1>

 <refsect1>
  <title>Notes</title>

  <para>
   If one of the objects (a table, function, etc.) referenced by the
   prepared plan is dropped during the session then the result of
   <function>SPI_execute_plan</function> for this plan will be unpredictable.
  </para>
 </refsect1>
</refentry>

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

<refentry id="spi-spi-execp">
 <refmeta>
  <refentrytitle>SPI_execp</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>SPI_execp</refname>
  <refpurpose>execute a plan in read/write mode</refpurpose>
 </refnamediv>

 <indexterm><primary>SPI_execp</primary></indexterm>

 <refsynopsisdiv>
<synopsis>
int SPI_execp(void * <parameter>plan</parameter>, Datum * <parameter>values</parameter>, const char * <parameter>nulls</parameter>, long <parameter>count</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_execp</function> is the same as
   <function>SPI_execute_plan</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>void * <parameter>plan</parameter></literal></term>
    <listitem>
     <para>
      execution plan (returned by <function>SPI_prepare</function>)
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>Datum * <parameter>values</parameter></literal></term>
    <listitem>
     <para>
      An array of actual parameter values.  Must have same length as the
      plan'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 plan's number of arguments.
      <literal>n</literal> indicates a null value (entry in
      <parameter>values</> will be ignored); a space indicates a
      nonnull value (entry in <parameter>values</> is valid).
     </para>

     <para>
      If <parameter>nulls</parameter> is <symbol>NULL</symbol> then
      <function>SPI_execp</function> assumes that no parameters are
      null.
     </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_plan</function>.
  </para>

  <para>
   <varname>SPI_processed</varname> and
   <varname>SPI_tuptable</varname> are set as in
   <function>SPI_execute</function> if successful.
  </para>
 </refsect1>
</refentry>

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

<refentry id="spi-spi-cursor-open">
 <refmeta>
  <refentrytitle>SPI_cursor_open</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>SPI_cursor_open</refname>
  <refpurpose>set up a cursor using a plan created with <function>SPI_prepare</function></refpurpose>
 </refnamediv>

 <indexterm><primary>SPI_cursor_open</primary></indexterm>

 <refsynopsisdiv>
<synopsis>
Portal SPI_cursor_open(const char * <parameter>name</parameter>, void * <parameter>plan</parameter>,
                       Datum * <parameter>values</parameter>, const char * <parameter>nulls</parameter>,
                       bool <parameter>read_only</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_cursor_open</function> sets up a cursor (internally,
   a portal) that will execute a plan prepared by
   <function>SPI_prepare</function>.  The parameters have the same
   meanings as the corresponding parameters to
   <function>SPI_execute_plan</function>.
  </para>

  <para>
   Using a cursor instead of executing the plan directly has two
   benefits.  First, the result rows can be retrieved a few at a time,
   avoiding memory overrun for queries that return many rows.  Second,
   a portal can outlive the current procedure (it can, in fact, live
   to the end of the current transaction).  Returning the portal name
   to the procedure's caller provides a way of returning a row set as
   result.
  </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>void * <parameter>plan</parameter></literal></term>
    <listitem>
     <para>
      execution plan (returned by <function>SPI_prepare</function>)
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>Datum * <parameter>values</parameter></literal></term>
    <listitem>
     <para>
      An array of actual parameter values.  Must have same length as the
      plan'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 plan's number of arguments.
      <literal>n</literal> indicates a null value (entry in
      <parameter>values</> will be ignored); a space indicates a
      nonnull value (entry in <parameter>values</> is valid).
     </para>

     <para>
      If <parameter>nulls</parameter> is <symbol>NULL</symbol> then
      <function>SPI_cursor_open</function> assumes that no parameters are
      null.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>bool <parameter>read_only</parameter></literal></term>
    <listitem>
     <para>
      <literal>true</> for read-only execution
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

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

  <para>
   pointer to portal containing the cursor, or <symbol>NULL</symbol>
   on error
  </para>
 </refsect1>
</refentry>

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

<refentry id="spi-spi-cursor-find">
 <refmeta>
  <refentrytitle>SPI_cursor_find</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>SPI_cursor_find</refname>
  <refpurpose>find an existing cursor by name</refpurpose>
 </refnamediv>

 <indexterm><primary>SPI_cursor_find</primary></indexterm>

 <refsynopsisdiv>
<synopsis>
Portal SPI_cursor_find(const char * <parameter>name</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_cursor_find</function> finds an existing portal by
   name.  This is primarily useful to resolve a cursor name returned
   as text by some other function.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>const char * <parameter>name</parameter></literal></term>
    <listitem>
     <para>
      name of the portal
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

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

  <para>
   pointer to the portal with the specified name, or
   <symbol>NULL</symbol> if none was found
  </para>
 </refsect1>
</refentry>

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

<refentry id="spi-spi-cursor-fetch">
 <refmeta>
  <refentrytitle>SPI_cursor_fetch</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>SPI_cursor_fetch</refname>
  <refpurpose>fetch some rows from a cursor</refpurpose>
 </refnamediv>

 <indexterm><primary>SPI_cursor_fetch</primary></indexterm>

 <refsynopsisdiv>
<synopsis>
void SPI_cursor_fetch(Portal <parameter>portal</parameter>, bool <parameter>forward</parameter>, long <parameter>count</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_cursor_fetch</function> fetches some rows from a
   cursor.  This is equivalent to the SQL command <command>FETCH</>.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><literal>Portal <parameter>portal</parameter></literal></term>
    <listitem>
     <para>
      portal containing the cursor
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><literal>bool <parameter>forward</parameter></literal></term>
    <listitem>
     <para>
      true for fetch forward, false for fetch backward
     </para>
    </listitem>
   </varlistentry>

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

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

  <para>
   <varname>SPI_processed</varname> and
   <varname>SPI_tuptable</varname> are set as in
   <function>SPI_execute</function> if successful.
  </para>
 </refsect1>
</refentry>

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

<refentry id="spi-spi-cursor-move">
 <refmeta>
  <refentrytitle>SPI_cursor_move</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>SPI_cursor_move</refname>
  <refpurpose>move a cursor</refpurpose>
 </refnamediv>

 <indexterm><primary>SPI_cursor_move</primary></indexterm>

 <refsynopsisdiv>
<synopsis>
void SPI_cursor_move(Portal <parameter>portal</parameter>, bool <parameter>forward</parameter>, long <parameter>count</parameter>)
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>SPI_cursor_move</function> skips over some number of rows
   in a cursor.  This is equivalent to the SQL command
   <command>MOVE</>.
  </para>
 </refsect1>