the <structname>pg_proc</structname> system catalog.
       </para>
       <para>
        If the optional <replaceable>loop-body</replaceable> argument is given, it is
        a piece of Tcl script that is executed once for each row in the
        query result.  (<replaceable>loop-body</replaceable> is ignored if the given
        command is not a <command>SELECT</command>.)
        The values of the current row's columns
        are stored into Tcl variables or array elements before each iteration.
        For example:
<programlisting>
spi_exec -array C "SELECT * FROM pg_class" {
    elog DEBUG "have table $C(relname)"
}
</programlisting>
        will print a log message for every row of <literal>pg_class</literal>.  This
        feature works similarly to other Tcl looping constructs; in
        particular <literal>continue</literal> and <literal>break</literal> work in the
        usual way inside the loop body.
       </para>
       <para>
        If a column of a query result is null, the target
        variable for it is <quote>unset</quote> rather than being set.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><function>spi_prepare</function> <replaceable>query</replaceable> <replaceable>typelist</replaceable></term>
      <listitem>
       <para>
        Prepares and saves a query plan for later execution.  The
        saved plan will be retained for the life of the current
        session.<indexterm><primary>preparing a query</primary>
        <secondary>in PL/Tcl</secondary></indexterm>
       </para>
       <para>
        The query can use parameters, that is, placeholders for
        values to be supplied whenever the plan is actually executed.
        In the query string, refer to parameters
        by the symbols <literal>$1</literal> ... <literal>$<replaceable>n</replaceable></literal>.
        If the query uses parameters, the names of the parameter types
        must be given as a Tcl list.  (Write an empty list for
        <replaceable>typelist</replaceable> if no parameters are used.)
       </para>
       <para>
        The return value from <function>spi_prepare</function> is a query ID
        to be used in subsequent calls to <function>spi_execp</function>. See
        <function>spi_execp</function> for an example.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><literal><function>spi_execp</function> <optional role="tcl">-count <replaceable>n</replaceable></optional> <optional role="tcl">-array <replaceable>name</replaceable></optional> <optional role="tcl">-nulls <replaceable>string</replaceable></optional> <replaceable>queryid</replaceable> <optional role="tcl"><replaceable>value-list</replaceable></optional> <optional role="tcl"><replaceable>loop-body</replaceable></optional></literal></term>
      <listitem>
       <para>
        Executes a query previously prepared with <function>spi_prepare</function>.
        <replaceable>queryid</replaceable> is the ID returned by
        <function>spi_prepare</function>.  If the query references parameters,
        a <replaceable>value-list</replaceable> must be supplied.  This
        is a Tcl list of actual values for the parameters.  The list must be
        the same length as the parameter type list previously given to
        <function>spi_prepare</function>.  Omit <replaceable>value-list</replaceable>
        if the query has no parameters.
       </para>
       <para>
        The optional value for <literal>-nulls</literal> is a string of spaces and
        <literal>'n'</literal> characters telling <function>spi_execp</function>
        which of the parameters are null values. If given, it must have exactly the
        same length as the <replaceable>value-list</replaceable>.  If it
        is not given, all the parameter values are nonnull.
       </para>
       <para>
        Except for the way in which the query and its parameters are specified,
        <function>spi_execp</function>