libpgtcl.sgml

PostgreSQL7.4.6 for Linux

<!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/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>