<!--
$Header: /cvsroot/pgsql-server/doc/src/sgml/libpgtcl.sgml,v 1.39 2003/10/31 00:18:55 tgl Exp $
-->

<chapter id="pgtcl">
 <title><application>pgtcl</application> - Tcl Binding Library</title>

 <indexterm zone="pgtcl">
  <primary>libpgtcl</primary>
 </indexterm>

 <indexterm zone="pgtcl">
  <primary>pgtcl</primary>
 </indexterm>

 <indexterm zone="pgtcl">
  <primary>Tcl</primary>
 </indexterm>

  <para>
   <application>pgtcl</application> is a Tcl package for client
   programs to interface with <ProductName>PostgreSQL</ProductName>
   servers.  It makes most of the functionality of
   <application>libpq</application> available to Tcl scripts.
  </para>

 <sect1 id="pgtcl-overview">
  <title>Overview</title>

  <para>
   <xref linkend="pgtcl-commands-table"> gives an overview over the
   commands available in <application>pgtcl</application>. These
   commands are described further on subsequent pages.
  </para>


<table id="pgtcl-commands-table">
<title><application>pgtcl</application> Commands</title>
<tgroup cols="2">
<thead>
  <row>
    <entry>Command</entry>
    <entry>Description</entry>
  </row>
</thead>

<tbody>
  <row>
    <entry><function>pg_connect</function></entry>
    <entry>open a connection to the server</entry>
  </row>
  <row>
    <entry><function>pg_disconnect</function></entry>
    <entry>close a connection to the server</entry>
  </row>
  <row>
    <entry><function>pg_conndefaults</function></entry>
    <entry>get connection options and their defaults</entry>
  </row>
  <row>
    <entry><function>pg_exec</function></entry>
    <entry>send a command to the server</entry>
  </row>
  <row>
    <entry><function>pg_result</function></entry>
    <entry>get information about a command result</entry>
  </row>
  <row>
    <entry><function>pg_select</function></entry>
    <entry>loop over the result of a query</entry>
  </row>
  <row>
    <entry><function>pg_execute</function></entry>
    <entry>send a query and optionally loop over the results</entry>
  </row>
  <row>
    <entry><function>pg_listen</function></entry>
    <entry>set or change a callback for asynchronous notification messages</entry>
  </row>
  <row>
    <entry><function>pg_on_connection_loss</function></entry>
    <entry>set or change a callback for unexpected connection loss</entry>
  </row>

  <row>
    <entry><function>pg_lo_creat</function></entry>
    <entry>create a large object</entry>
  </row>
  <row>
    <entry><function>pg_lo_open</function></entry>
    <entry>open a large object</entry>
  </row>
  <row>
    <entry><function>pg_lo_close</function></entry>
    <entry>close a large object</entry>
  </row>
  <row>
    <entry><function>pg_lo_read</function></entry>
    <entry>read from a large object</entry>
  </row>
  <row>
    <entry><function>pg_lo_write</function></entry>
    <entry>write to a large object</entry>
  </row>
  <row>
    <entry><function>pg_lo_lseek</function></entry>
    <entry>seek to a position in a large object</entry>
  </row>
  <row>
    <entry><function>pg_lo_tell</function></entry>
    <entry>return the current seek position of a large object</entry>
  </row>
  <row>
    <entry><function>pg_lo_unlink</function></entry>
    <entry>delete a large object</entry>
  </row>
  <row>
    <entry><function>pg_lo_import</function></entry>
    <entry>import a large object from a file</entry>
  </row>
  <row>
    <entry><function>pg_lo_export</function></entry>
    <entry>export a large object to a file</entry>
  </row>
</tbody>
</tgroup>
</table>

  <para>
   The <function>pg_lo_*</function> commands are interfaces to the
   large object features of
   <ProductName>PostgreSQL</ProductName>.<indexterm><primary>large
   object</><secondary>in pgctl</></> The functions are designed to mimic the analogous file
   system functions in the standard Unix file system interface.  The
   <function>pg_lo_*</function> commands should be used within a
   <command>BEGIN</command>/<command>COMMIT</command> transaction
   block because the descriptor returned by
   <function>pg_lo_open</function> is only valid for the current
   transaction.  <function>pg_lo_import</function> and
   <function>pg_lo_export</function> <emphasis>must</emphasis> be used
   in a <command>BEGIN</command>/<command>COMMIT</command> transaction
   block.
  </para>

 </sect1>

<sect1 id="libpgtcl-loading">
<title>Loading <application>pgtcl</application> into an Application</title>

   <para>
    Before using <application>pgtcl</application> commands, you must load
    the <filename>libpgtcl</> library into your Tcl application.  This is normally
    done with the Tcl <literal>load</> command.  Here is an example:

<programlisting>
load libpgtcl[info sharedlibextension]
</programlisting>

    The use of <literal>info sharedlibextension</> is recommended in
    preference to hard-wiring <literal>.so</> or  <literal>.sl</> into
    the program.
   </para>

   <para>
    The <literal>load</> command will fail unless the system's dynamic
    loader knows where to look for the <filename>libpgtcl</> shared
    library file.  You may need to work with <command>ldconfig</>, or
    set the environment variable <envar>LD_LIBRARY_PATH</>, or use
    some equivalent facility for your platform to make it work.  Refer
    to the <productname>PostgreSQL</> installation instructions for
    more information.
   </para>

   <para>
    <filename>libpgtcl</> in turn depends on <filename>libpq</>, so the
    dynamic loader must also be able to find the <filename>libpq</> shared
    library.  In practice this is seldom an issue, since both of these
    shared libraries are normally stored in the same directory, but it
    can be a stumbling block in some configurations.
   </para>

   <para>
    If you use a custom executable for your application, you might choose
    to statically bind <filename>libpgtcl</> into the executable and thereby
    avoid the <literal>load</> command and the potential problems of dynamic
    linking.  See the source code for <application>pgtclsh</> for an example.
   </para>

</sect1>

<sect1 id="libpgtcl-ref">
<title><application>pgtcl</application> Command Reference</title>

<refentry ID="PGTCL-PGCONNECT">
 <refmeta>
  <refentrytitle>pg_connect</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>pg_connect</refname>
  <refpurpose>open a connection to the server</refpurpose>
  <indexterm ID="IX-PGTCL-PGCONNECT-2"><primary>pg_connect</primary></indexterm>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
pg_connect -conninfo <parameter>connectOptions</parameter>
pg_connect <parameter>dbName</parameter> <optional role="tcl">-host <parameter>hostName</parameter></optional> <optional role="tcl">-port <parameter>portNumber</parameter></optional> <optional role="tcl">-tty <parameter>tty</parameter</optional> <optional role="tcl">-options <parameter>serverOptions</parameter></optional>
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>pg_connect</function> opens a connection to the
   <ProductName>PostgreSQL</ProductName> server.
  </para>

  <para>
   Two syntaxes are available.  In the older one, each possible option
   has a separate option switch in the <command>pg_connect</command>
   command.  In the newer form, a single option string is supplied
   that can contain multiple option values.
   <function>pg_conndefaults</function> can be used to retrieve
   information about the available options in the newer syntax.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <title>New style</title>

   <varlistentry>
    <term><parameter>connectOptions</parameter></term>
    <listitem>
     <para>
      A string of connection options, each written in the form
      <literal>keyword = value</>.  A list of valid options can be
      found in the description of the <application>libpq</> function
      <function>PQconnectdb</>.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>

  <variablelist>
   <title>Old style</title>

   <varlistentry>
    <term><parameter>dbName</parameter></term>
    <listitem>
     <para>
      The name of the database to connect to.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><option>-host <parameter>hostName</parameter></option></term>
    <listitem>
     <para>
      The host name of the database server to connect to.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><option>-port <parameter>portNumber</parameter></option></term>
    <listitem>
     <para>
      The TCP port number of the database server to connect to.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><option>-tty <parameter>tty</parameter></option></term>
    <listitem>
     <para>
      A file or <acronym>TTY</acronym> for optional debug output from
      the server.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><option>-options <parameter>serverOptions</parameter></option></term>
    <listitem>
     <para>
      Additional configuration options to pass to the server.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

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

  <para>
   If successful, a handle for a database connection is returned.
   Handles start with the prefix <literal>pgsql</literal>.
  </para>
 </refsect1>
</refentry>


<refentry ID="PGTCL-PGDISCONNECT">
 <refmeta>
  <refentrytitle>pg_disconnect</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>pg_disconnect</refname>
  <refpurpose>close a connection to the server</refpurpose>
  <indexterm ID="IX-PGTCL-PGDISCONNECT-2"><primary>pg_disconnect</primary></indexterm>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
pg_disconnect <parameter>conn</parameter>
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>pg_disconnect</function> closes a connection to the
   <productname>PostgreSQL</productname> server.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><parameter>conn</parameter></term>
    <listitem>
     <para>
      The handle of the connection to be closed.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

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

  <para>
   None
  </para>
 </refsect1>
</refentry>


<refentry ID="PGTCL-PGCONNDEFAULTS">
 <refmeta>
  <refentrytitle>pg_conndefaults</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>pg_conndefaults</refname>
  <refpurpose>get connection options and their defaults</refpurpose>
  <indexterm ID="IX-PGTCL-PGCONNDEFAULTS-2"><primary>pg_conndefaults</primary></indexterm>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
pg_conndefaults
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>pg_conndefaults</function> returns information about the
   connection options available in <function>pg_connect
   -conninfo</function> and the current default value for each option.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <para>
   None
  </para>
 </refsect1>

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

  <para>
   The result is a list describing the possible connection options and
   their current default values.  Each entry in the list is a sublist
   of the format:
<synopsis>
{optname label dispchar dispsize value}
</synopsis>
   where the <replaceable>optname</> is usable as an option in
   <function>pg_connect -conninfo</function>.
  </para>
 </refsect1>
</refentry>


<refentry ID="PGTCL-PGEXEC">
 <refmeta>
  <refentrytitle>pg_exec</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>pg_exec</refname>
  <refpurpose>send a command to the server</refpurpose>
  <indexterm ID="IX-PGTCL-PGEXEC-2"><primary>pg_exec</primary></indexterm>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
pg_exec <parameter>conn</parameter> <parameter>commandString</parameter>
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>pg_exec</function> submits a command to the
   <productname>PostgreSQL</productname> server and returns a result.
   Command result handles start with the connection handle and add a
   period and a result number.
  </para>

  <para>
   Note that lack of a Tcl error is not proof that the command
   succeeded!  An error message returned by the server will be
   processed as a command result with failure status, not by
   generating a Tcl error in <function>pg_exec</function>.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><parameter>conn</parameter></term>
    <listitem>
     <para>
      The handle of the connection on which to execute the command.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>commandString</parameter></term>
    <listitem>
     <para>
      The SQL command to execute.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

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

  <para>
   A result handle. A Tcl error will be returned if
   <application>pgtcl</application> was unable to obtain a server
   response.  Otherwise, a command result object is created and a
   handle for it is returned.  This handle can be passed to
   <function>pg_result</function> to obtain the results of the
   command.
  </para>
 </refsect1
</refentry>


<refentry ID="PGTCL-PGRESULT">
 <refmeta>
  <refentrytitle>pg_result</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>pg_result</refname>
  <refpurpose>get information about a command result</refpurpose>
  <indexterm ID="IX-PGTCL-PGRESULT-2"><primary>pg_result</primary></indexterm>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
pg_result <parameter>resultHandle</parameter> <parameter>resultOption</parameter>
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>pg_result</function> returns information about a command
   result created by a prior <function>pg_exec</function>.
  </para>

  <para>
   You can keep a command result around for as long as you need it,
   but when you are done with it, be sure to free it by executing
   <function>pg_result -clear</function>.  Otherwise, you have a
   memory leak, and <application>pgtcl</> will eventually start
   complaining that you have created too many command result objects.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><parameter>resultHandle</parameter></term>
    <listitem>
     <para>
      The handle of the command result.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>resultOption</parameter></term>
    <listitem>
     <para>
      One of the following options, specifying which piece of result
      information to return:

      <variablelist>
       <varlistentry>
        <term><option>-status</option></term>
        <listitem>
         <para>
          The status of the result.
         </para>
        </listitem>
       </varlistentry>

       <varlistentry>
        <term><option>-error</option></term>
        <listitem>
         <para>
          The error message, if the status indicates an error,
          otherwise an empty string.
         </para>
        </listitem>
       </varlistentry>

       <varlistentry>
        <term><option>-conn</option></term>
        <listitem>
         <para>
          The connection that produced the result.
         </para>
        </listitem>
       </varlistentry>

       <varlistentry>
        <term><option>-oid</option></term>
        <listitem>
         <para>
          If the command was an <command>INSERT</command>, the OID of
          the inserted row, otherwise 0.
         </para>
        </listitem>
       </varlistentry>

       <varlistentry>
        <term><option>-numTuples</option></term>
        <listitem>
         <para>
          The number of rows (tuples) returned by the query.
         </para>
        </listitem>
       </varlistentry>

       <varlistentry>
        <term><option>-cmdTuples</option></term>
        <listitem>
         <para>
          The number of rows (tuples) affected by the command.
         </para>
        </listitem>
       </varlistentry>

       <varlistentry>
        <term><option>-numAttrs</option></term>
        <listitem>
         <para>
          The number of columns (attributes) in each row.
         </para>
        </listitem>
       </varlistentry>

       <varlistentry>
        <term><option>-assign <parameter>arrayName</parameter></option></term>
        <listitem>
         <para>
          Assign the results to an array, using subscripts of the form
          <literal>(rowNumber, columnName)</literal>.
         </para>
        </listitem>
       </varlistentry>

       <varlistentry>
        <term><option>-assignbyidx <parameter>arrayName</> <optional role="tcl"><parameter>appendstr</></optional></option></term>
        <listitem>
         <para>
          Assign the results to an array using the values of the
          first column and the names of the remaining column as keys.
          If <parameter>appendstr</> is given then it is appended to
          each key.  In short, all but the first column of each row
          are stored into the array, using subscripts of the form
          <literal>(firstColumnValue, columnNameAppendStr)</literal>.
         </para>
        </listitem>
       </varlistentry>

       <varlistentry>
        <term><option>-getTuple <parameter>rowNumber</parameter></option></term>
        <listitem>
         <para>
          Returns the columns of the indicated row in a list.  Row
          numbers start at zero.
         </para>
        </listitem>
       </varlistentry>

       <varlistentry>
        <term><option>-tupleArray <parameter>rowNumber</> <parameter>arrayName</></option></term>
        <listitem>
         <para>
          Stores the columns of the row in array
          <parameter>arrayName</parameter>, indexed by column names.
          Row numbers start at zero.
         </para>
        </listitem>
       </varlistentry>

       <varlistentry>
        <term><option>-attributes</option></term>
        <listitem>
         <para>
          Returns a list of the names of the columns in the result.
         </para>
        </listitem>
       </varlistentry>

       <varlistentry>
        <term><option>-lAttributes</option></term>
        <listitem>
         <para>
          Returns a list of sublists, <literal>{name typeOid
          typeSize}</literal> for each column.
         </para>
        </listitem>
       </varlistentry>

       <varlistentry>
        <term><option>-clear</option></term>
        <listitem>
         <para>
          Clear the command result object.
         </para>
        </listitem>
       </varlistentry>
      </variablelist>
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

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

  <para>
   The result depends on the selected option, as described above.
  </para>
 </refsect1>
</refentry>


<refentry ID="PGTCL-PGSELECT">
 <refmeta>
  <refentrytitle>pg_select</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>pg_select</refname>
  <refpurpose>loop over the result of a query</refpurpose>
  <indexterm ID="IX-PGTCL-PGSELECT-2"><primary>pg_select</primary></indexterm>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
pg_select <parameter>conn</parameter> <parameter>commandString</parameter> <parameter>arrayVar</parameter> <parameter>procedure</parameter>
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>pg_select</function> submits a query
   (<command>SELECT</command> statement) to the
   <productname>PostgreSQL</productname> server and executes a given
   chunk of code for each row in the result.  The
   <parameter>commandString</parameter> must be a
   <command>SELECT</command> statement; anything else returns an
   error.  The <parameter>arrayVar</parameter> variable is an array
   name used in the loop.  For each row,
   <parameter>arrayVar</parameter> is filled in with the row values,
   using the column names as the array indices.  Then the
   <parameter>procedure</parameter> is executed.
  </para>

  <para>
   In addition to the column values, the following special entries are
   made in the array:

   <variablelist>
    <varlistentry>
     <term><literal>.headers</></term>
     <listitem>
      <para>
       A list of the column names returned by the query.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>.numcols</></term>
     <listitem>
      <para>
       The number of columns returned by the query.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry>
     <term><literal>.tupno</></term>
     <listitem>
      <para>
       The current row number, starting at zero and incrementing for
       each iteration of the loop body.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><parameter>conn</parameter></term>
    <listitem>
     <para>
      The handle of the connection on which to execute the query.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>commandString</parameter></term>
    <listitem>
     <para>
      The SQL query to execute.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>arrayVar</parameter></term>
    <listitem>
     <para>
      An array variable for returned rows.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>procedure</parameter></term>
    <listitem>
     <para>
      The procedure to run for each returned row.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Return Value</title>
  <para>
   None
  </para>
 </refsect1>

 <refsect1>
  <title>Examples</title>

  <para>
   This examples assumes that the table <classname>table1</> has
   columns <structfield>control</> and <structfield>name</> (and
   perhaps others):
<programlisting>
pg_select $pgconn "SELECT * FROM table1;" array {
    puts [format "%5d %s" $array(control) $array(name)]
}
</programlisting>
  </para>
 </refsect1>
</refentry>


<refentry ID="PGTCL-PGEXECUTE">
 <refmeta>
  <refentrytitle>pg_execute</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>pg_execute</refname>
  <refpurpose>send a query and optionally loop over the results</refpurpose>
  <indexterm ID="IX-PGTCL-PGEXECUTE-2"><primary>pg_execute</primary></indexterm>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
pg_execute <optional role="tcl">-array <parameter>arrayVar</parameter></optional> <optional role="tcl">-oid <parameter>oidVar</parameter></optional> <parameter>conn</parameter> <parameter>commandString</parameter> <optional role="tcl"><parameter>procedure</parameter></optional>
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>pg_execute</function> submits a command to the
   <productname>PostgreSQL</> server.
  </para>

  <para>
   If the command is not a <command>SELECT</command> statement, the
   number of rows affected by the command is returned.  If the command
   is an <command>INSERT</command> statement and a single row is
   inserted, the OID of the inserted row is stored in the variable
   <parameter>oidVar</> if the optional <parameter>-oid</parameter>
   argument is supplied.
  </para>

  <para>
   If the command is a <command>SELECT</command> statement, then, for
   each row in the result, the row values are stored in the
   <parameter>arrayVar</parameter> variable, if supplied, using the
   column names as the array indices, else in variables named by the
   column names, and then the optional
   <parameter>procedure</parameter> is executed if supplied.
   (Omitting the <parameter>procedure</parameter> probably makes sense
   only if the query will return a single row.)  The number of rows
   selected is returned.
  </para>

  <para>
   The <parameter>procedure</parameter> can use the Tcl commands
   <literal>break</literal>, <literal>continue</literal>, and
   <literal>return</literal> with the expected behavior.  Note that if
   the <parameter>procedure</parameter> executes
   <literal>return</literal>, then <function>pg_execute</function>
   does not return the number of affected rows.
  </para>

  <para>
   <function>pg_execute</function> is a newer function which provides
   a superset of the features of <function>pg_select</function> and
   can replace <function>pg_exec</function> in many cases where access
   to the result handle is not needed.
  </para>

  <para>
   For server-handled errors, <function>pg_execute</function> will
   throw a Tcl error and return a two-element list.  The first element
   is an error code, such as <literal>PGRES_FATAL_ERROR</literal>, and
   the second element is the server error text.  For more serious
   errors, such as failure to communicate with the server,
   <function>pg_execute</function> will throw a Tcl error and return
   just the error message text.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><option>-array <parameter>arrayVar</parameter></option></term>
    <listitem>
     <para>
      Specifies the name of an array variable where result rows are
      stored, indexed by the column names.  This is ignored if
      <parameter>commandString</> is not a <command>SELECT</>
      statement.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><option>-oid <parameter>oidVar</parameter></option></term>
    <listitem>
     <para>
      Specifies the name of a variable into which the OID from an
      <command>INSERT</command> statement will be stored.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>conn</parameter></term>
    <listitem>
     <para>
      The handle of the connection on which to execute the command.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>commandString</parameter></term>
    <listitem>
     <para>
      The SQL command to execute.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>procedure</parameter></term>
    <listitem>
     <para>
      Optional procedure to execute for each result row of a
      <command>SELECT</command> statement.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

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

  <para>
   The number of rows affected or returned by the command.
  </para>
 </refsect1>

 <refsect1>
  <title>Examples</title>

  <para>
   In the following examples, error checking with
   <literal>catch</literal> has been omitted for clarity.
  </para>

  <para>
   Insert a row and save the OID in <varname>result_oid</>:
<programlisting>
pg_execute -oid result_oid $pgconn "INSERT INTO mytable VALUES (1);"
</programlisting>
  </para>

  <para>
   Print the columns <literal>item</> and <literal>value</> from each
   row:
<programlisting>
pg_execute -array d $pgconn "SELECT item, value FROM mytable;" {
    puts "Item=$d(item) Value=$d(value)"
}
</programlisting>
  </para>

  <para>
   Find the maximum and minimum values and store them in
   <literal>$s(max)</> and <literal>$s(min)</>:
<programlisting>
pg_execute -array s $pgconn "SELECT max(value) AS max, min(value) AS min FROM mytable;"
</programlisting>
  </para>

  <para>
   Find the maximum and minimum values and store them in
   <literal>$max</> and <literal>$min</>:
<programlisting>
pg_execute $pgconn "SELECT max(value) AS max, min(value) AS min FROM mytable;"
</programlisting>
  </para>
 </refsect1>
</refentry>


<refentry ID="PGTCL-PGLISTEN">
 <refmeta>
  <refentrytitle>pg_listen</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>pg_listen</refname>
  <refpurpose>set or change a callback for asynchronous notification messages</refpurpose>
  <indexterm ID="IX-PGTCL-PGLISTEN-2"><primary>pg_listen</primary></indexterm>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
pg_listen <parameter>conn</parameter> <parameter>notifyName</parameter> <optional role="tcl"><parameter>callbackCommand</parameter></optional>
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>pg_listen</function> creates, changes, or cancels a
   request to listen for asynchronous notification messages from the
   <productname>PostgreSQL</productname> server.  With a
   <parameter>callbackCommand</> parameter, the request is
   established, or the command string of an already existing request
   is replaced.  With no <parameter>callbackCommand</> parameter, a
   prior request is canceled.
  </para>

  <para>
   After a <function>pg_listen</function> request is established, the
   specified command string is executed whenever a notification
   message bearing the given name arrives from the server.  This
   occurs when any <productname>PostgreSQL</productname> client
   application issues a
   <command>NOTIFY</command><indexterm><primary>NOTIFY</><secondary
   sortas="pgtcl">in pgtcl</></> command referencing that name.  The
   command string is executed from the Tcl idle loop.  That is the
   normal idle state of an application written with Tk.  In non-Tk Tcl
   shells, you can execute <function>update</function> or
   <function>vwait</function> to cause the idle loop to be entered.
  </para>

  <para>
   You should not invoke the SQL statements <command>LISTEN</command>
   or <command>UNLISTEN</command> directly when using
   <function>pg_listen</function>.  <application>pgtcl</application>
   takes care of issuing those statements for you.  But if you want to
   send a notification message yourself, invoke the SQL
   <command>NOTIFY</command> statement using
   <function>pg_exec</function>.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><parameter>conn</parameter></term>
    <listitem>
     <para>
      The handle of the connection on which to listen for notifications.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>notifyName</parameter></term>
    <listitem>
     <para>
      The name of the notification condition to start or stop
      listening to.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>callbackCommand</parameter></term>
    <listitem>
     <para>
      If present, provides the command string to execute when a
      matching notification arrives.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

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

  <para>
   None
  </para>
 </refsect1>
</refentry>


<refentry ID="PGTCL-PGON-CONNECTION-LOSS">
 <refmeta>
  <refentrytitle>pg_on_connection_loss</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>pg_on_connection_loss</refname>
  <refpurpose>set or change a callback for unexpected connection loss</refpurpose>
  <indexterm ID="IX-PGTCL-PGON-CONNECTION-LOSS-2"><primary>pg_on_connection_loss</primary></indexterm>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
pg_on_connection_loss <parameter>conn</parameter> <optional role="tcl"><parameter>callbackCommand</parameter></optional>
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>pg_on_connection_loss</function> creates, changes, or
   cancels a request to execute a callback command if an unexpected
   loss of connection to the database occurs.  With a
   <parameter>callbackCommand</> parameter, the request is
   established, or the command string of an already existing request
   is replaced.  With no <parameter>callbackCommand</> parameter, a
   prior request is canceled.
  </para>

  <para>
   The callback command string is executed from the Tcl idle loop.
   That is the normal idle state of an application written with Tk.
   In non-Tk Tcl shells, you can execute <function>update</function>
   or <function>vwait</function> to cause the idle loop to be entered.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><parameter>conn</parameter></term>
    <listitem>
     <para>
      The handle to watch for connection losses.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>callbackCommand</parameter></term>
    <listitem>
     <para>
      If present, provides the command string to execute when
      connection loss is detected.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

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

  <para>
   None
  </para>
 </refsect1>
</refentry>


<refentry ID="PGTCL-PGLOCREAT">
 <refmeta>
  <refentrytitle>pg_lo_creat</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>pg_lo_creat</refname>
  <refpurpose>create a large object</refpurpose>
  <indexterm ID="IX-PGTCL-PGLOCREAT-2"><primary>pg_lo_creat</primary></indexterm>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
pg_lo_creat <parameter>conn</parameter> <parameter>mode</parameter>
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>pg_lo_creat</function> creates a large object.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><parameter>conn</parameter></term>
    <listitem>
     <para>
      The handle of a connection to the database in which to create the large
      object.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>mode</parameter></term>
    <listitem>
     <para>
      The access mode for the large object.  It can be any or'ing
      together of <literal>INV_READ</> and <literal>INV_WRITE</>.  The
      <quote>or</quote> operator is <literal>|</literal>.  For
      example:
<programlisting>
[pg_lo_creat $conn "INV_READ|INV_WRITE"]
</programlisting>
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

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

  <para>
   The OID of the large object created.
  </para>
 </refsect1>
</refentry>


<refentry ID="PGTCL-PGLOOPEN">
 <refmeta>
  <refentrytitle>pg_lo_open</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>pg_lo_open</refname>
  <refpurpose>open a large object</refpurpose>
  <indexterm ID="IX-PGTCL-PGLOOPEN-2"><primary>pg_lo_open</primary></indexterm>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
pg_lo_open <parameter>conn</parameter> <parameter>loid</parameter> <parameter>mode</parameter>
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>pg_lo_open</function> opens a large object.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><parameter>conn</parameter></term>

    <listitem>
     <para>
      The handle of a connection to the database in which the large object
      exists.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>loid</parameter></term>
    <listitem>
     <para>
      The OID of the large object.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>mode</parameter></term>
    <listitem>
     <para>
      Specifies the access mode for the large object.  Mode can be
      either <literal>r</>, <literal>w</>, or <literal>rw</>.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

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

  <para>
   A descriptor for use in later large-object commands.
  </para>
 </refsect1>
</refentry>


<refentry ID="PGTCL-PGLOCLOSE">
 <refmeta>
  <refentrytitle>pg_lo_close</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>pg_lo_close</refname>
  <refpurpose>close a large object</refpurpose>
  <indexterm ID="IX-PGTCL-PGLOCLOSE-2"><primary>pg_lo_close</primary></indexterm>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
pg_lo_close <parameter>conn</parameter> <parameter>descriptor</parameter>
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>pg_lo_close</function> closes a large object.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><parameter>conn</parameter></term>
    <listitem>
     <para>
      The handle of a connection to the database in which the large object
      exists.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>descriptor</parameter></term>
    <listitem>
     <para>
      A descriptor for the large object from
      <function>pg_lo_open</function>.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

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

  <para>
   None
  </para>
 </refsect1>
</refentry>


<refentry ID="PGTCL-PGLOREAD">
 <refmeta>
  <refentrytitle>pg_lo_read</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>pg_lo_read</refname>
  <refpurpose>read from a large object</refpurpose>
  <indexterm ID="IX-PGTCL-PGLOREAD-2"><primary>pg_lo_read</primary></indexterm>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
pg_lo_read <parameter>conn</parameter> <parameter>descriptor</parameter> <parameter>bufVar</parameter> <parameter>len</parameter>
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>pg_lo_read</function> reads at most
   <parameter>len</parameter> bytes from a large object into a
   variable named <parameter>bufVar</parameter>.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><parameter>conn</parameter></term>
    <listitem>
     <para>
      The handle of a connection to the database in which the large object
      exists.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>descriptor</parameter></term>
    <listitem>
     <para>
      A descriptor for the large object from
      <function>pg_lo_open</function>.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>bufVar</parameter></term>
    <listitem>
     <para>
      The name of a buffer variable to contain the large object
      segment.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>len</parameter></term>
    <listitem>
     <para>
      The maximum number of bytes to read.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

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

  <para>
   The number of bytes actually read is returned; this could be less than
   the number requested if the end of the large object is reached first.
   In event of an error, the return value is negative.
  </para>
 </refsect1>
</refentry>


<refentry ID="PGTCL-PGLOWRITE">
 <refmeta>
  <refentrytitle>pg_lo_write</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>pg_lo_write</refname>
  <refpurpose>write to a large object</refpurpose>
  <indexterm ID="IX-PGTCL-PGLOWRITE-2"><primary>pg_lo_write</primary></indexterm>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
pg_lo_write <parameter>conn</parameter> <parameter>descriptor</parameter> <parameter>buf</parameter> <parameter>len</parameter>
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>pg_lo_write</function> writes at most
   <parameter>len</parameter> bytes from a variable
   <parameter>buf</parameter> to a large object.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><parameter>conn</parameter></term>
    <listitem>
     <para>
      The handle of a connection to the database in which the large object
      exists.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>descriptor</parameter></term>
    <listitem>
     <para>
      A descriptor for the large object from
      <function>pg_lo_open</function>.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>buf</parameter></term>
    <listitem>
     <para>
      The string to write to the large object (not a variable name,
      but the value itself).
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>len</parameter></term>
    <listitem>
     <para>
      The maximum number of bytes to write.  The number written will
      be the smaller of this value and the length of the string.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

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

  <para>
   The number of bytes actually written is returned; this will ordinarily
   be the same as the number requested.
   In event of an error, the return value is negative.
  </para>
 </refsect1>
</refentry>


<refentry ID="PGTCL-PGLOLSEEK">
 <refmeta>
  <refentrytitle>pg_lo_lseek</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>pg_lo_lseek</refname>
  <refpurpose>seek to a position of a large object</refpurpose>
  <indexterm ID="IX-PGTCL-PGLOLSEEK-2"><primary>pg_lo_lseek</primary></indexterm>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
pg_lo_lseek <parameter>conn</parameter> <parameter>descriptor</parameter> <parameter>offset</parameter> <parameter>whence</parameter>
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>pg_lo_lseek</function> moves the current read/write
   position to <parameter>offset</parameter> bytes from the position
   specified by <parameter>whence</parameter>.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><parameter>conn</parameter></term>
    <listitem>
     <para>
      The handle of a connection to the database in which the large object
      exists.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>descriptor</parameter></term>
    <listitem>
     <para>
      A descriptor for the large object from
      <function>pg_lo_open</function>.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>offset</parameter></term>
    <listitem>
     <para>
      The new seek position in bytes.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>whence</parameter></term>
    <listitem>
     <para>
      Specified from where to calculate the new seek position:
      <literal>SEEK_CUR</> (from current position),
      <literal>SEEK_END</> (from end), or <literal>SEEK_SET</> (from
      start).
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

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

  <para>
   None
  </para>
 </refsect1>
</refentry>


<refentry ID="PGTCL-PGLOTELL">
 <refmeta>
  <refentrytitle>pg_lo_tell</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>pg_lo_tell</refname>
  <refpurpose>return the current seek position of a large object</refpurpose>
  <indexterm ID="IX-PGTCL-PGLOTELL-2"><primary>pg_lo_tell</primary></indexterm>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
pg_lo_tell <parameter>conn</parameter> <parameter>descriptor</parameter>
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>pg_lo_tell</function> returns the current read/write
   position in bytes from the beginning of the large object.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><parameter>conn</parameter></term>

    <listitem>
     <para>
      The handle of a connection to the database in which the large object
      exists.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>descriptor</parameter></term>
    <listitem>
     <para>
      A descriptor for the large object from
      <function>pg_lo_open</function>.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

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

  <para>
   A zero-based offset in bytes suitable for input to
   <function>pg_lo_lseek</function>.
  </para>
 </refsect1>
</refentry>


<refentry ID="PGTCL-PGLOUNLINK">
 <refmeta>
  <refentrytitle>pg_lo_unlink</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>pg_lo_unlink</refname>
  <refpurpose>delete a large object</refpurpose>
  <indexterm ID="IX-PGTCL-PGLOUNLINK-2"><primary>pg_lo_unlink</primary></indexterm>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
pg_lo_unlink <parameter>conn</parameter> <parameter>loid</parameter>
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>pg_lo_unlink</function> deletes the specified large
   object.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><parameter>conn</parameter></term>
    <listitem>
     <para>
      The handle of a connection to the database in which the large object
      exists.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>loid</parameter></term>
    <listitem>
     <para>
      The OID of the large object.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

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

  <para>
   None
  </para>
 </refsect1>
</refentry>


<refentry ID="PGTCL-PGLOIMPORT">
 <refmeta>
  <refentrytitle>pg_lo_import</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>pg_lo_import</refname>
  <refpurpose>import a large object from a file</refpurpose>
  <indexterm ID="IX-PGTCL-PGLOIMPORT-2"><primary>pg_lo_import</primary></indexterm>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
pg_lo_import <parameter>conn</parameter> <parameter>filename</parameter>
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>pg_lo_import</function> reads the specified file and
   places the contents into a new large object.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><parameter>conn</parameter></term>
    <listitem>
     <para>
      The handle of a connection to the database in which to create the large
      object.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>filename</parameter></term>
    <listitem>
     <para>
      Specified the file from which to import the data.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

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

  <para>
   The OID of the large object created.
  </para>
 </refsect1>

 <refsect1>
  <title>Notes</title>

  <para>
   <function>pg_lo_import</function> must be called within a
   <command>BEGIN</>/<command>COMMIT</> transaction block.
  </para>
 </refsect1>
</refentry>


<refentry ID="PGTCL-PGLOEXPORT">
 <refmeta>
  <refentrytitle>pg_lo_export</refentrytitle>
 </refmeta>

 <refnamediv>
  <refname>pg_lo_export</refname>
  <refpurpose>export a large object to a file</refpurpose>
  <indexterm ID="IX-PGTCL-PGLOEXPORT-2"><primary>pg_lo_export</primary></indexterm>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
pg_lo_export <parameter>conn</parameter> <parameter>loid</parameter> <parameter>filename</parameter>
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <function>pg_lo_export</function> writes the specified large object
   into a file.
  </para>
 </refsect1>

 <refsect1>
  <title>Arguments</title>

  <variablelist>
   <varlistentry>
    <term><parameter>conn</parameter></term>
    <listitem>
     <para>
      The handle of a connection to the database in which the large object
      exists.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>loid</parameter></term>
    <listitem>
     <para>
      The OID of the large object.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><parameter>filename</parameter></term>
    <listitem>
     <para>
      Specifies the file into which the data is to be exported.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1>
  <title>Return Value</title>
  <para>
   None
  </para>
 </refsect1>

 <refsect1>
  <title>Notes</title>

  <para>
   <function>pg_lo_export</function> must be called within a
   <command>BEGIN</>/<command>COMMIT</> transaction block.
  </para>
 </refsect1>
</refentry>

</sect1>


<sect1 id="pgtcl-examplesect">
 <title>Example Program</title>

 <para>
  <xref linkend="pgtcl-example"> shows a small example of how to use
  the <application>pgtcl</application> commands.
 </para>

 <example id="pgtcl-example">
  <title><application>pgtcl</application> Example Program</title>

<programlisting>
# getDBs :
#   get the names of all the databases at a given host and port number
#   with the defaults being the localhost and port 5432
#   return them in alphabetical order
proc getDBs { {host "localhost"} {port "5432"} } {
    # datnames is the list to be result
    set conn [pg_connect template1 -host $host -port $port]
    set res [pg_exec $conn "SELECT datname FROM pg_database ORDER BY datname;"]
    set ntups [pg_result $res -numTuples]
    for {set i 0} {$i < $ntups} {incr i} {
	lappend datnames [pg_result $res -getTuple $i]
    }
    pg_result $res -clear
    pg_disconnect $conn
    return $datnames
}
</programlisting>
  </example>
 </sect1>

</chapter>
