<function>spi_execp</function> example below.
    </para>
   </sect1>

   <sect1 id="pltcl-dbaccess">
    <title>Database Access from PL/Tcl</title>

    <para>
     In this section, we follow the usual Tcl convention of using question
     marks, rather than brackets, to indicate an optional element in a
     syntax synopsis.  The following commands are available to access
     the database from the body of a PL/Tcl function:

    <variablelist>

     <varlistentry>
      <term><literal><function>spi_exec</function> <optional role="tcl">-count <replaceable>n</replaceable></optional> <optional role="tcl">-array <replaceable>name</replaceable></optional> <replaceable>command</replaceable> <optional role="tcl"><replaceable>loop-body</replaceable></optional></literal></term>
      <listitem>
       <para>
        Executes an SQL command given as a string.  An error in the command
        causes an error to be raised.  Otherwise, the return value of <function>spi_exec</function>
        is the number of rows processed (selected, inserted, updated, or
        deleted) by the command, or zero if the command is a utility
        statement.  In addition, if the command is a <command>SELECT</command> statement, the
        values of the selected columns are placed in Tcl variables as
        described below.
       </para>
       <para>
        The optional <literal>-count</literal> value tells
        <function>spi_exec</function> to stop
        once <replaceable>n</replaceable> rows have been retrieved,
        much as if the query included a <literal>LIMIT</literal> clause.
        If <replaceable>n</replaceable> is zero, the query is run to
        completion, the same as when <literal>-count</literal> is omitted.
       </para>
       <para>
        If the command is a <command>SELECT</command> statement, the values of the
        result columns are placed into Tcl variables named after the columns.
        If the <literal>-array</literal> option is given, the column values are
        instead stored into elements of the named associative array, with the
        column names used as array indexes.  In addition, the current row
        number within the result (counting from zero) is stored into the array
        element named <quote><literal>.tupno</literal></quote>, unless that name is
        in use as a column name in the result.
       </para>
       <para>
        If the command is a <command>SELECT</command> statement and no <replaceable>loop-body</replaceable>
        script is given, then only the first row of results are stored into
        Tcl variables or array elements; remaining rows, if any, are ignored.
        No storing occurs if the query returns no rows.  (This case can be
        detected by checking the result of <function>spi_exec</function>.)
        For example:
<programlisting>
spi_exec "SELECT count(*) AS cnt FROM pg_proc"
</programlisting>
        will set the Tcl variable <literal>$cnt</literal> to the number of rows in
        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