head	1.42;
access;
symbols
	REL7_4_29:1.39
	REL7_4_28:1.39
	REL7_4_27:1.39
	REL7_4_26:1.39
	REL7_4_25:1.39
	REL7_4_24:1.39
	REL7_4_23:1.39
	REL7_4_22:1.39
	REL7_4_21:1.39
	REL7_4_20:1.39
	REL7_3_21:1.31.2.1
	REL7_4_19:1.39
	REL7_3_20:1.31.2.1
	REL7_4_18:1.39
	REL7_3_19:1.31.2.1
	REL7_4_17:1.39
	REL7_3_18:1.31.2.1
	REL7_4_16:1.39
	REL7_4_15:1.39
	REL7_3_17:1.31.2.1
	REL7_4_14:1.39
	REL7_3_16:1.31.2.1
	REL7_3_15:1.31.2.1
	REL7_4_13:1.39
	REL7_3_14:1.31.2.1
	REL7_4_12:1.39
	REL7_3_13:1.31.2.1
	REL7_4_11:1.39
	REL7_3_12:1.31.2.1
	REL7_4_10:1.39
	REL7_3_11:1.31.2.1
	REL7_4_9:1.39
	REL7_2_8:1.25
	REL7_3_10:1.31.2.1
	REL7_4_8:1.39
	REL7_2_7:1.25
	REL7_3_9:1.31.2.1
	REL7_4_7:1.39
	REL7_4_6:1.39
	REL7_3_8:1.31.2.1
	REL7_2_6:1.25
	REL7_2_5:1.25
	REL7_4_5:1.39
	REL7_3_7:1.31.2.1
	REL7_4_4:1.39
	REL7_4_3:1.39
	REL7_4_2:1.39
	REL7_3_6:1.31.2.1
	REL7_4_1:1.39
	REL7_3_5:1.31.2.1
	REL7_4:1.39
	REL7_4_RC2:1.39
	REL7_4_STABLE:1.39.0.2
	REL7_4_RC1:1.39
	REL7_4_BETA5:1.38
	REL7_4_BETA4:1.38
	REL7_4_BETA3:1.37
	REL7_4_BETA2:1.35
	WIN32_DEV:1.35.0.2
	REL7_4_BETA1:1.35
	REL7_3_4:1.31.2.1
	REL7_3_2:1.31.2.1
	REL7_2_4:1.25
	REL7_3_STABLE:1.31.0.2
	REL7_2_3:1.25
	REL7_2_STABLE:1.25.0.2
	REL7_2:1.25
	REL7_2_RC2:1.25
	REL7_2_RC1:1.25
	REL7_2_BETA5:1.24
	REL7_2_BETA4:1.23
	REL7_2_BETA3:1.21
	REL7_2_BETA2:1.21
	REL7_2_BETA1:1.21
	REL7_1_2:1.14
	REL7_1_STABLE:1.14.0.2
	REL7_1_BETA:1.13
	REL7_1_BETA3:1.13
	REL7_1_BETA2:1.13
	REL7_1:1.13
	REL7_0_PATCHES:1.12.0.2
	REL7_0:1.12
	REL6_5_PATCHES:1.10.0.2
	REL6_5:1.10
	REL6_4:1.9.0.2
	release-6-3:1.1;
locks; strict;
comment	@# @;


1.42
date	2004.04.20.01.11.49;	author momjian;	state dead;
branches;
next	1.41;

1.41
date	2004.02.29.15.36.46;	author neilc;	state Exp;
branches;
next	1.40;

1.40
date	2003.11.29.19.51.37;	author pgsql;	state Exp;
branches;
next	1.39;

1.39
date	2003.10.31.00.18.55;	author tgl;	state Exp;
branches;
next	1.38;

1.38
date	2003.09.29.18.18.35;	author momjian;	state Exp;
branches;
next	1.37;

1.37
date	2003.09.08.23.02.28;	author petere;	state Exp;
branches;
next	1.36;

1.36
date	2003.08.31.17.32.19;	author petere;	state Exp;
branches;
next	1.35;

1.35
date	2003.03.13.01.30.28;	author petere;	state Exp;
branches
	1.35.2.1;
next	1.34;

1.34
date	2002.11.26.21.38.46;	author momjian;	state Exp;
branches;
next	1.33;

1.33
date	2002.11.15.03.11.16;	author momjian;	state Exp;
branches;
next	1.32;

1.32
date	2002.11.08.04.56.40;	author momjian;	state Exp;
branches;
next	1.31;

1.31
date	2002.09.21.18.32.53;	author petere;	state Exp;
branches
	1.31.2.1;
next	1.30;

1.30
date	2002.09.03.16.21.23;	author momjian;	state Exp;
branches;
next	1.29;

1.29
date	2002.09.02.21.51.46;	author tgl;	state Exp;
branches;
next	1.28;

1.28
date	2002.04.14.01.31.37;	author ishii;	state Exp;
branches;
next	1.27;

1.27
date	2002.04.13.01.42.44;	author momjian;	state Exp;
branches;
next	1.26;

1.26
date	2002.03.22.19.20.11;	author petere;	state Exp;
branches;
next	1.25;

1.25
date	2002.01.20.22.19.56;	author petere;	state Exp;
branches;
next	1.24;

1.24
date	2002.01.07.02.29.12;	author petere;	state Exp;
branches;
next	1.23;

1.23
date	2001.11.27.20.33.29;	author tgl;	state Exp;
branches;
next	1.22;

1.22
date	2001.11.21.05.53.41;	author thomas;	state Exp;
branches;
next	1.21;

1.21
date	2001.10.12.23.32.33;	author momjian;	state Exp;
branches;
next	1.20;

1.20
date	2001.10.11.16.30.41;	author momjian;	state Exp;
branches;
next	1.19;

1.19
date	2001.09.15.16.08.59;	author petere;	state Exp;
branches;
next	1.18;

1.18
date	2001.09.13.15.55.23;	author petere;	state Exp;
branches;
next	1.17;

1.17
date	2001.09.10.21.58.46;	author petere;	state Exp;
branches;
next	1.16;

1.16
date	2001.09.10.04.15.41;	author momjian;	state Exp;
branches;
next	1.15;

1.15
date	2001.05.12.22.51.35;	author petere;	state Exp;
branches;
next	1.14;

1.14
date	2001.04.30.04.26.01;	author momjian;	state Exp;
branches;
next	1.13;

1.13
date	2000.09.29.20.21.34;	author petere;	state Exp;
branches;
next	1.12;

1.12
date	2000.03.31.03.27.40;	author thomas;	state Exp;
branches;
next	1.11;

1.11
date	2000.03.30.22.22.40;	author thomas;	state Exp;
branches;
next	1.10;

1.10
date	98.12.29.02.24.17;	author thomas;	state Exp;
branches;
next	1.9;

1.9
date	98.10.30.19.37.03;	author thomas;	state Exp;
branches;
next	1.8;

1.8
date	98.10.17.22.01.13;	author tgl;	state Exp;
branches;
next	1.7;

1.7
date	98.10.10.17.12.13;	author thomas;	state Exp;
branches;
next	1.6;

1.6
date	98.10.08.03.23.03;	author tgl;	state Exp;
branches;
next	1.5;

1.5
date	98.08.17.16.19.25;	author thomas;	state Exp;
branches;
next	1.4;

1.4
date	98.07.29.06.35.17;	author thomas;	state Exp;
branches;
next	1.3;

1.3
date	98.06.16.04.10.14;	author momjian;	state Exp;
branches;
next	1.2;

1.2
date	98.05.13.03.29.12;	author momjian;	state Exp;
branches;
next	1.1;

1.1
date	98.03.01.08.15.57;	author thomas;	state Exp;
branches;
next	;

1.31.2.1
date	2002.11.08.04.57.07;	author momjian;	state Exp;
branches;
next	;

1.35.2.1
date	2003.09.07.04.36.42;	author momjian;	state Exp;
branches;
next	;


desc
@@


1.42
log
@Remove TCL docs.
@
text
@<!--
$PostgreSQL: pgsql-server/doc/src/sgml/libpgtcl.sgml,v 1.41 2004/02/29 15:36:46 neilc 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>
@


1.41
log
@Fix a bunch (~88) typos that the OpenJade tools don't warn about by
default: some SGML tags weren't properly terminated.
@
text
@d2 1
a2 1
$PostgreSQL: pgsql-server/doc/src/sgml/libpgtcl.sgml,v 1.40 2003/11/29 19:51:37 pgsql Exp $
@


1.40
log
@
$Header: -> $PostgreSQL Changes ...
@
text
@d2 1
a2 1
$PostgreSQL: /cvsroot/pgsql-server/doc/src/sgml/libpgtcl.sgml,v 1.39 2003/10/31 00:18:55 tgl Exp $
d208 1
a208 1
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>
d484 1
a484 1
 </refsect1
@


1.39
log
@Use Tcl ByteArray objects to avoid unwanted character set translation
in libpgtcl's lo_read/lo_write commands.  Also, deal correctly with
failure return from lo_read().  ljb and Tom Lane.
@
text
@d2 1
a2 1
$Header: /cvsroot/pgsql-server/doc/src/sgml/libpgtcl.sgml,v 1.38 2003/09/29 18:18:35 momjian Exp $
@


1.38
log
@This patch makes a few incremental improvements to geqo.sgml and
arch-dev.sgml

Neil Conway
@
text
@d2 1
a2 1
$Header$
d1220 1
a1220 1
      The handle of a database connection in which to create the large
d1287 2
a1288 2
      The handle of a database connection in which the large object to
      be opened exists.
d1357 1
a1357 1
      The handle of a database connection in which the large object
d1420 1
a1420 1
      The handle of a database connection in which the large object
d1461 3
a1463 1
   None
d1504 1
a1504 1
      The handle of a database connection in which the large object
d1524 2
a1525 1
      The string to write to the large object (not a variable name).
d1534 2
a1535 1
      The maximum number of bytes to write.
d1546 3
a1548 1
   None
d1589 1
a1589 1
      The handle of a database connection in which the large object
d1673 1
a1673 1
      The handle of a database connection in which the large object
d1736 1
a1736 1
      The handle of a database connection in which the large object
d1797 1
a1797 1
      The handle of a database connection in which to create the large
d1867 1
a1867 1
      The handle of a database connection in which the large object
@


1.37
log
@Update preface.

Use question marks rather than brackets to delimit optional elements in
Tcl synopses.

Fix stylesheet misfeature leading to excessively long cross-reference text
when linking to a different "part".

Remove <body> attributes -- CSS stylesheets should handle that.

Improve bibliography formatting.

Add fast-forward links for more convenient navigation.
@
text
@d1 4
@


1.36
log
@Add/edit index entries.
@
text
@d204 1
a204 1
pg_connect <parameter>dbName</parameter> <optional>-host <parameter>hostName</parameter></optional> <optional>-port <parameter>portNumber</parameter></optional> <optional>-tty <parameter>tty</parameter</optional> <optional>-options <parameter>serverOptions</parameter></optional>
d615 1
a615 1
        <term><option>-assignbyidx <parameter>arrayName</> <optional><parameter>appendstr</></optional></option></term>
d842 1
a842 1
pg_execute <optional>-array <parameter>arrayVar</parameter></optional> <optional>-oid <parameter>oidVar</parameter></optional> <parameter>conn</parameter> <parameter>commandString</parameter> <optional><parameter>procedure</parameter></optional>
d1023 1
a1023 1
pg_listen <parameter>conn</parameter> <parameter>notifyName</parameter> <optional><parameter>callbackCommand</parameter></optional>
d1123 1
a1123 1
pg_on_connection_loss <parameter>conn</parameter> <optional><parameter>callbackCommand</parameter></optional>
@


1.35
log
@Big editing for consistent content and presentation.
@
text
@d128 2
a129 2
   <ProductName>PostgreSQL</ProductName>.<indexterm><primary>Large
   Object</></> The functions are designed to mimic the analogous file
d1046 6
a1051 6
   <command>NOTIFY</command><indexterm><primary>NOTIFY</><secondary>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.
@


1.35.2.1
log
@Update this branch to match CVS head, includes WIN32 improvements.
@
text
@d128 2
a129 2
   <ProductName>PostgreSQL</ProductName>.<indexterm><primary>large
   object</><secondary>in pgctl</></> The functions are designed to mimic the analogous file
d1046 6
a1051 6
   <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.
@


1.34
log
@Add -cmdTuples to tcl interface.
@
text
@d9 4
a15 3
 <sect1 id="pgtcl-intro">
  <title>Introduction</title>

d23 2
a24 3
  <para>
   This package was originally written by Jolly Chen.
  </para>
d33 99
a131 97
<TABLE TOCENTRY="1" id="pgtcl-commands-table">
<TITLE><literal>pgtcl</literal> Commands</TITLE>
<TGROUP COLS="2">
<THEAD>
  <ROW>
    <ENTRY>Command</ENTRY>
    <ENTRY>Description</ENTRY>
  </ROW>
</THEAD>
<TBODY>
  <ROW>
    <ENTRY><function>pg_connect</function></ENTRY>
    <ENTRY>opens a connection to the backend server</ENTRY>
  </ROW>
  <ROW>
    <ENTRY><function>pg_disconnect</function></ENTRY>
    <ENTRY>closes a connection</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 query to the backend</ENTRY>
  </ROW>
  <ROW>
    <ENTRY><function>pg_result</function></ENTRY>
    <ENTRY>manipulate the results of a query</ENTRY>
  </ROW>
  <ROW>
    <ENTRY><function>pg_select</function></ENTRY>
    <ENTRY>loop over the result of a SELECT statement</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>establish a callback for NOTIFY messages</ENTRY>
  </ROW>
  <ROW>
    <ENTRY><function>pg_on_connection_loss</function></ENTRY>
    <ENTRY>establish 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 a large object</ENTRY>
  </ROW>
  <ROW>
    <ENTRY><function>pg_lo_write</function></ENTRY>
    <ENTRY>write 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 Unix file into a large object</ENTRY>
  </ROW>
  <ROW>
    <ENTRY><function>pg_lo_export</function></ENTRY>
    <ENTRY>export a large object into a Unix file</ENTRY>
  </ROW>
</TBODY>
</TGROUP>
</TABLE>

  <para>
   The <function>pg_lo_*</function> routines are interfaces to the
   large object features of <ProductName>PostgreSQL</ProductName>.
   The functions are designed to mimic the analogous file system
   functions in the standard Unix file system interface.  The
   <function>pg_lo_*</function> routines should be used within a
d133 1
a133 1
   block because the file descriptor returned by
a140 27
  <para>
   <xref linkend="pgtcl-example"> shows a small example of how to use
   the routines.
  </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>
d143 2
a144 2
<Sect1 id="libpgtcl-loading">
<Title>Loading <application>pgtcl</application> into your application</Title>
d148 1
a148 1
    <filename>libpgtcl</> into your Tcl application.  This is normally
d185 138
a322 1
</Sect1>
d324 2
a325 2
<Sect1 id="libpgtcl-ref">
<Title><application>pgtcl</application> Command Reference Information</Title>
d327 44
a370 247
<REFENTRY ID="PGTCL-PGCONNECT">
<REFMETA>
<REFENTRYTITLE>pg_connect</REFENTRYTITLE>
<REFMISCINFO>PGTCL - Connection Management</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>pg_connect
</REFNAME>
<REFPURPOSE>open a connection to the backend server
</REFPURPOSE>
<INDEXTERM ID="IX-PGTCL-PGCONNECT-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>connecting</SECONDARY></INDEXTERM>
<INDEXTERM ID="IX-PGTCL-PGCONNECT-2"><PRIMARY>pg_connect</PRIMARY></INDEXTERM>
</REFNAMEDIV>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1997-12-24</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
pg_connect -conninfo <REPLACEABLE CLASS="PARAMETER">connectOptions</REPLACEABLE>
pg_connect <REPLACEABLE CLASS="PARAMETER">dbName</REPLACEABLE> <OPTIONAL>-host <REPLACEABLE CLASS="PARAMETER">hostName</REPLACEABLE></OPTIONAL>
  <OPTIONAL>-port <REPLACEABLE
  CLASS="PARAMETER">portNumber</REPLACEABLE></OPTIONAL> <OPTIONAL>-tty <REPLACEABLE
  CLASS="PARAMETER">pqtty</REPLACEABLE></OPTIONAL>
  <OPTIONAL>-options <REPLACEABLE
  CLASS="PARAMETER">optionalBackendArgs</REPLACEABLE></OPTIONAL>
</SYNOPSIS>

<REFSECT2 ID="R2-PGTCL-PGCONNECT-1">
<REFSECT2INFO>
<DATE>1998-10-07</DATE>
</REFSECT2INFO>
<TITLE>Inputs (new style)
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">connectOptions</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>A string of connection options, each written in the form keyword = value.
A list of valid options can be found in <filename>libpq</>'s
<function>PQconnectdb()</> manual entry.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>

<REFSECT2 ID="R2-PGTCL-PGCONNECT-2">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Inputs (old style)
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">dbName</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies a valid database name.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <OPTIONAL>-host <REPLACEABLE CLASS="PARAMETER">hostName</REPLACEABLE></OPTIONAL>
</TERM>
<LISTITEM>
<PARA>Specifies the domain name of the backend server for <REPLACEABLE CLASS="PARAMETER">dbName</REPLACEABLE>.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <OPTIONAL>-port <REPLACEABLE CLASS="PARAMETER">portNumber</REPLACEABLE></OPTIONAL>
</TERM>
<LISTITEM>
<PARA>Specifies the IP port number of the backend server for <REPLACEABLE CLASS="PARAMETER">dbName</REPLACEABLE>.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <OPTIONAL>-tty <REPLACEABLE CLASS="PARAMETER">pqtty</REPLACEABLE></OPTIONAL>
</TERM>
<LISTITEM>
<PARA>Specifies file or <acronym>tty</acronym> for optional debug output from backend.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <OPTIONAL>-options <REPLACEABLE CLASS="PARAMETER">optionalBackendArgs</REPLACEABLE></OPTIONAL>
</TERM>
<LISTITEM>
<PARA>Specifies options for the backend server for <REPLACEABLE CLASS="PARAMETER">dbName</REPLACEABLE>.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>

<REFSECT2 ID="R2-PGTCL-PGCONNECT-3">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Outputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
If successful, a handle for a database connection is returned.
Handles start with the prefix <literal>pgsql</literal>.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>

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

<REFSECT1 ID="R1-PGTCL-PGCONNECT-1">
<REFSECT1INFO>
<DATE>1997-12-24</DATE>
</REFSECT1INFO>
<TITLE>Description
</TITLE>
<PARA><FUNCTION>pg_connect</FUNCTION> opens a connection to the
<ProductName>PostgreSQL</ProductName> backend.
</Para>

<para>
Two syntaxes are available.  In the older one, each possible option
has a separate option switch in the pg_connect statement.  In the
newer form, a single option string is supplied that can contain
multiple option values.  See <FUNCTION>pg_conndefaults</FUNCTION>
for info about the available options in the newer syntax.
</PARA>
</REFSECT1>
<REFSECT1 ID="R1-PGTCL-PGCONNECT-2">
<TITLE>Usage
</TITLE>
<comment>
 XXX thomas 1997-12-24
</comment>
</REFSECT1>
</REFENTRY>

<REFENTRY ID="PGTCL-PGDISCONNECT">
<REFMETA>
<REFENTRYTITLE>pg_disconnect</REFENTRYTITLE>
<REFMISCINFO>PGTCL - Connection Management</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>pg_disconnect
</REFNAME>
<REFPURPOSE>close a connection to the backend server
</REFPURPOSE>
<INDEXTERM ID="IX-PGTCL-PGDISCONNECT-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>connecting</SECONDARY></INDEXTERM>
<INDEXTERM ID="IX-PGTCL-PGDISCONNECT-2"><PRIMARY>pg_connect</PRIMARY></INDEXTERM>
</REFNAMEDIV>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1997-12-24</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
pg_disconnect <REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE>
</SYNOPSIS>

<REFSECT2 ID="R2-PGTCL-PGDISCONNECT-1">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Inputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies a valid database handle.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>

<REFSECT2 ID="R2-PGTCL-PGDISCONNECT-2">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Outputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  None
</TERM>
<LISTITEM>
<PARA>
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>

<REFSECT1 ID="R1-PGTCL-PGDISCONNECT-1">
<REFSECT1INFO>
<DATE>1997-12-24</DATE>
</REFSECT1INFO>
<TITLE>Description
</TITLE>
<PARA><FUNCTION>pg_disconnect</FUNCTION> closes a connection to the <ProductName>PostgreSQL</ProductName> backend.
</PARA>
</REFSECT1>

</REFENTRY>




<REFENTRY ID="PGTCL-PGCONNDEFAULTS">
<REFMETA>
<REFENTRYTITLE>pg_conndefaults</REFENTRYTITLE>
<REFMISCINFO>PGTCL - Connection Management</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>pg_conndefaults
</REFNAME>
<REFPURPOSE>obtain information about default connection parameters
</REFPURPOSE>
<INDEXTERM ID="IX-PGTCL-PGCONNDEFAULTS-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>connecting</SECONDARY></INDEXTERM>
<INDEXTERM ID="IX-PGTCL-PGCONNDEFAULTS-2"><PRIMARY>pg_conndefaults</PRIMARY></INDEXTERM>
</REFNAMEDIV>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-10-07</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
d372 2
a373 1
</SYNOPSIS>
d375 26
a400 29
<REFSECT2 ID="R2-PGTCL-PGCONNDEFAULTS-1">
<REFSECT2INFO>
<DATE>1998-10-07</DATE>
</REFSECT2INFO>
<TITLE>Inputs
</TITLE>
<PARA>
None.
</PARA>
</REFSECT2>

<REFSECT2 ID="R2-PGTCL-PGCONNDEFAULTS-2">
<REFSECT2INFO>
<DATE>1998-10-07</DATE>
</REFSECT2INFO>
<TITLE>Outputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">option list</REPLACEABLE>
</TERM>
<LISTITEM>
<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:
</Para>
<screen>
d402 844
a1245 127
</screen>
<Para>
where the <replaceable>optname</> is usable as an option in
<FUNCTION>pg_connect -conninfo</FUNCTION>.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>

<REFSECT1 ID="R1-PGTCL-PGCONNDEFAULTS-1">
<REFSECT1INFO>
<DATE>1998-10-07</DATE>
</REFSECT1INFO>
<TITLE>Description
</TITLE>

<para>
<FUNCTION>pg_conndefaults</FUNCTION> returns info about the connection
options available in <FUNCTION>pg_connect -conninfo</FUNCTION> and the
current default value for each option.
</PARA>
</REFSECT1>
<REFSECT1 ID="R1-PGTCL-PGCONNDEFAULTS-2">
<TITLE>Usage
</TITLE>
<PARA><literal>pg_conndefaults</>
</PARA>
</REFSECT1>
</REFENTRY>

<REFENTRY ID="PGTCL-PGEXEC">
<REFMETA>
<REFENTRYTITLE>pg_exec</REFENTRYTITLE>
<REFMISCINFO>PGTCL - Query Processing</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>pg_exec
</REFNAME>
<REFPURPOSE>
send a command string to the server
</REFPURPOSE>
<INDEXTERM ID="IX-PGTCL-PGEXEC-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>connecting</SECONDARY></INDEXTERM>
<INDEXTERM ID="IX-PGTCL-PGEXEC-2"><PRIMARY>pg_connect</PRIMARY></INDEXTERM>
</REFNAMEDIV>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1997-12-24</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
pg_exec <REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">queryString</REPLACEABLE>
</SYNOPSIS>

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

<REFSECT2 ID="R2-PGTCL-PGEXEC-1">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Inputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies a valid database handle.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">queryString</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies a valid SQL query.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>

<REFSECT2 ID="R2-PGTCL-PGEXEC-2">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Outputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">resultHandle</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
A Tcl error will be returned if <application>pgtcl</application> was unable to obtain a backend
response.  Otherwise, a query 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 query.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2></REFSYNOPSISDIV>

<REFSECT1 ID="R1-PGTCL-PGEXEC-1">
<REFSECT1INFO>
<DATE>1997-12-24</DATE>
</REFSECT1INFO>
<TITLE>Description
</TITLE>
<PARA>
<FUNCTION>pg_exec</FUNCTION> submits a query to the <ProductName>PostgreSQL</ProductName> backend and returns a result.

Query 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 query succeeded!
An error message returned by the backend will be processed
as a query result with failure status, not by generating a Tcl error
in pg_exec.
</PARA>
</REFSECT1>
d1248 678
a1925 566
<REFENTRY ID="PGTCL-PGRESULT">
<REFMETA>
<REFENTRYTITLE>pg_result</REFENTRYTITLE>
<REFMISCINFO>PGTCL - Query Processing</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>pg_result
</REFNAME>
<REFPURPOSE>
get information about a query result
</REFPURPOSE>
<INDEXTERM ID="IX-PGTCL-PGRESULT-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>connecting</SECONDARY></INDEXTERM>
<INDEXTERM ID="IX-PGTCL-PGRESULT-2"><PRIMARY>pg_connect</PRIMARY></INDEXTERM>
</REFNAMEDIV>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1997-12-24</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
pg_result <REPLACEABLE CLASS="PARAMETER">resultHandle</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">resultOption</REPLACEABLE>
</SYNOPSIS>
<REFSECT2 ID="R2-PGTCL-PGRESULT-1">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Inputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">resultHandle</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
  The handle for a query result.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">resultOption</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
Specifies one of several possible options.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>

<REFSECT3>
<TITLE>Options</TITLE>

<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 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 INSERT, the OID of the 
inserted tuple; otherwise 0.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<option>-numTuples</option>
</TERM>
<LISTITEM>
<PARA>
the number of tuples returned by the query.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<option>-cmdTuples</option>
</TERM>
<LISTITEM>
<PARA>
the number of tuples affected by the query.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<option>-numAttrs</option>
</TERM>
<LISTITEM>
<PARA>
the number of attributes in each tuple.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<option>-assign arrayName</option>
</TERM>
<LISTITEM>
<PARA>
assign the results to an array, using subscripts of the form
<literal>(tupno,attributeName)</literal>.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<option>-assignbyidx arrayName ?appendstr?</option>
</TERM>
<LISTITEM>
<PARA>
assign the results to an array using the first attribute's value and
the remaining attributes' names as keys.  If <parameter>appendstr</> is given then
it is appended to each key.  In short, all but the first field of each
tuple are stored into the array, using subscripts of the form
<literal>(firstFieldValue,fieldNameAppendStr)</literal>.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<option>-getTuple tupleNumber</option>
</TERM>
<LISTITEM>
<PARA>
returns the fields of the indicated tuple in a list.  Tuple numbers
start at zero.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<option>-tupleArray tupleNumber arrayName</option>
</TERM>
<LISTITEM>
<PARA>
stores the fields of the tuple in array <parameter>arrayName</parameter>, indexed by field names.
Tuple numbers start at zero.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<option>-attributes</option>
</TERM>
<LISTITEM>
<PARA>
returns a list of the names of the tuple attributes.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<option>-lAttributes</option>
</TERM>
<LISTITEM>
<PARA>
returns a list of sublists, <literal>{name ftype fsize}</literal> for each tuple attribute.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
<option>-clear</option>
</TERM>
<LISTITEM>
<PARA>
clear the result query object.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT3>
</REFSECT2>

<REFSECT2 ID="R2-PGTCL-PGRESULT-2">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Outputs
</TITLE>
<PARA>
The result depends on the selected option, as described above.
</PARA>
</REFSECT2></REFSYNOPSISDIV>

<REFSECT1 ID="R1-PGTCL-PGRESULT-1">
<REFSECT1INFO>
<DATE>1997-12-24</DATE>
</REFSECT1INFO>
<TITLE>Description
</TITLE>
<PARA>
<FUNCTION>pg_result</FUNCTION> returns information about a query result
created by a prior <FUNCTION>pg_exec</FUNCTION>.
</Para>

<para>
You can keep a query 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've
created too many query result objects.
</PARA>
</REFSECT1>
</REFENTRY>

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

<REFENTRY ID="PGTCL-PGSELECT">
<REFMETA>
<REFENTRYTITLE>pg_select</REFENTRYTITLE>
<REFMISCINFO>PGTCL - Query Processing</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>pg_select
</REFNAME>
<REFPURPOSE>
loop over the result of a SELECT statement
</REFPURPOSE>
<INDEXTERM ID="IX-PGTCL-PGSELECT-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>connecting</SECONDARY></INDEXTERM>
<INDEXTERM ID="IX-PGTCL-PGSELECT-2"><PRIMARY>pg_connect</PRIMARY></INDEXTERM>
</REFNAMEDIV>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1997-12-24</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
pg_select <REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">queryString</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">arrayVar</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">queryProcedure</REPLACEABLE>
</SYNOPSIS>

<REFSECT2 ID="R2-PGTCL-PGSELECT-1">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Inputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies a valid database handle.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">queryString</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies a valid SQL select query.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">arrayVar</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Array variable for tuples returned.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">queryProcedure</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Procedure run on each tuple found.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>

</REFSECT2>

<REFSECT2 ID="R2-PGTCL-PGSELECT-2">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Outputs
</TITLE>
<Para>
None.
</Para>
</REFSECT2></REFSYNOPSISDIV>

<REFSECT1 ID="R1-PGTCL-PGSELECT-1">
<REFSECT1INFO>
<DATE>1997-12-24</DATE>
</REFSECT1INFO>
<TITLE>Description
</TITLE>
<PARA>
<FUNCTION>pg_select</FUNCTION> submits a SELECT query to the
<ProductName>PostgreSQL</ProductName> backend, and executes a
given chunk of code for each tuple in the result.
  The <REPLACEABLE CLASS="PARAMETER">queryString</REPLACEABLE>
  must be a SELECT statement.  Anything else returns an error.
  The <REPLACEABLE CLASS="PARAMETER">arrayVar</REPLACEABLE>
  variable is an array name used in the loop.  For each tuple,
  <REPLACEABLE CLASS="PARAMETER">arrayVar</REPLACEABLE> is filled in
  with the tuple field values, using the field names as the array
  indexes.  Then the
  <REPLACEABLE CLASS="PARAMETER">queryProcedure</REPLACEABLE>
  is executed.
</PARA>

<PARA>
 In addition to the field 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 SELECT.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><literal>.numcols</></TERM>
<LISTITEM>
<PARA>The number of columns returned by the SELECT.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM><literal>.tupno</></TERM>
<LISTITEM>
<PARA>The current tuple number, starting at zero and incrementing
for each iteration of the loop body.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</PARA>

</REFSECT1>

<REFSECT1 ID="R1-PGTCL-PGSELECT-2">
<TITLE>Usage
</TITLE>
<PARA>
This would work if table <classname>table</> has fields <structfield>control</> and <structfield>name</>
(and, perhaps, other fields):
<ProgramListing>
	pg_select $pgconn "SELECT * FROM table" array {
		puts [format "%5d %s" $array(control) $array(name)]
	}
</ProgramListing>
</PARA>
</REFSECT1>

</REFENTRY>

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

<REFENTRY ID="PGTCL-PGEXECUTE">
<REFMETA>
<REFENTRYTITLE>pg_execute</REFENTRYTITLE>
<REFMISCINFO>PGTCL - Query Processing</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>pg_execute
</REFNAME>
<REFPURPOSE>
send a query and optionally loop over the results
</REFPURPOSE>
<INDEXTERM ID="IX-PGTCL-PGEXECUTE-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>query</SECONDARY></INDEXTERM>
<INDEXTERM ID="IX-PGTCL-PGEXECUTE-2"><PRIMARY>pg_execute</PRIMARY></INDEXTERM>
</REFNAMEDIV>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>2002-03-06</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
pg_execute <OPTIONAL>-array <REPLACEABLE CLASS="PARAMETER">arrayVar</REPLACEABLE></OPTIONAL> <OPTIONAL>-oid <REPLACEABLE CLASS="PARAMETER">oidVar</REPLACEABLE></OPTIONAL> <REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">queryString</REPLACEABLE> <OPTIONAL><REPLACEABLE CLASS="PARAMETER">queryProcedure</REPLACEABLE></OPTIONAL>
</SYNOPSIS>

<REFSECT2 ID="R2-PGTCL-PGEXECUTE-1">
<REFSECT2INFO>
<DATE>2002-03-06</DATE>
</REFSECT2INFO>
<TITLE>Inputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  <OPTIONAL>-array <REPLACEABLE CLASS="PARAMETER">arrayVar</REPLACEABLE></OPTIONAL>
</TERM>
<LISTITEM>
<PARA>Specifies the name of an array variable where result tuples are stored,
indexed by the field names.
This is ignored if <replaceable class=parameter>queryString</> is not a SELECT statement. For SELECT
statements, if this option is not used, result tuples values are stored
in individual variables named according to the field names in the result.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <OPTIONAL>-oid <REPLACEABLE CLASS="PARAMETER">oidVar</REPLACEABLE></OPTIONAL>
</TERM>
<LISTITEM>
<PARA>Specifies the name of a variable into which the OID from an INSERT
statement will be stored.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies a valid database handle.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">queryString</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies a valid SQL query.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <OPTIONAL><REPLACEABLE CLASS="PARAMETER">queryProcedure</REPLACEABLE></OPTIONAL>
</TERM>
<LISTITEM>
<PARA>Optional command to execute for each result tuple of a SELECT statement.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>

</REFSECT2>

<REFSECT2 ID="R2-PGTCL-PGEXECUTE-2">
<REFSECT2INFO>
<DATE>2002-03-06</DATE>
</REFSECT2INFO>
<TITLE>Outputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">ntuples</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
The number of tuples affected or returned by the query.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2></REFSYNOPSISDIV>

<REFSECT1 ID="R1-PGTCL-PGEXECUTE-1">
<REFSECT1INFO>
<DATE>2002-03-06</DATE>
</REFSECT1INFO>
<TITLE>Description
</TITLE>
<PARA>
<FUNCTION>pg_execute</FUNCTION> submits a query to the
<PRODUCTNAME>PostgreSQL</> backend.
</PARA>
<PARA>
If the query is not a SELECT statement, the query is executed and the
number of tuples affected by the query is returned.  If the query is an
INSERT and a single tuple is inserted, the OID of the inserted tuple is
stored in the <replaceable>oidVar</> variable if the optional <PARAMETER>-oid</PARAMETER>
argument is supplied.
</PARA>
<PARA>
If the query is a SELECT statement, the query is executed. For each tuple
in the result, the tuple field values are stored in the
<PARAMETER>arrayVar</PARAMETER> variable,
if supplied, using the field names as the array indexes, else in variables
named by the field names, and then the optional
<PARAMETER>queryProcedure</PARAMETER> is executed if supplied.
(Omitting the <PARAMETER>queryProcedure</PARAMETER> probably makes sense
only if the query will return a single tuple.)
The number of tuples selected is returned.
</PARA>
<PARA>
The <PARAMETER>queryProcedure</PARAMETER> can use the Tcl
<LITERAL>break</LITERAL>, <LITERAL>continue</LITERAL>, and
<LITERAL>return</LITERAL> commands, with the expected behavior.
Note that if the <PARAMETER>queryProcedure</PARAMETER> executes
<LITERAL>return</LITERAL>, <FUNCTION>pg_execute</FUNCTION> does
not return <PARAMETER>ntuples</PARAMETER>.
</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 backend-handled errors, <FUNCTION>pg_execute</FUNCTION> will
throw a Tcl error and return two element list. The first element
is an error code such as <LITERAL>PGRES_FATAL_ERROR</LITERAL>, and
the second element is the backend error text. For more serious
errors, such as failure to communicate with the backend,
<FUNCTION>pg_execute</FUNCTION> will throw a Tcl error and return
just the error message text.
</PARA>

</REFSECT1>

<REFSECT1 ID="R1-PGTCL-PGEXECUTE-2">
<TITLE>Usage
</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 item and value fields from each row:
<ProgramListing>
    pg_execute -array d $pgconn "select item, value from mytable" {
       puts "Item=$d(item) Value=$d(value)"
d1927 7
a1933 1160
</ProgramListing>
</PARA>
<PARA>
Find the maximum and minimum values and store them in $s(max) and $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 $max and $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>
<REFMISCINFO>PGTCL - Asynchronous Notify</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>pg_listen
</REFNAME>
<REFPURPOSE>set or change a callback for asynchronous NOTIFY messages
</REFPURPOSE>
<INDEXTERM ID="IX-PGTCL-PGLISTEN-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>notify</SECONDARY></INDEXTERM>
<INDEXTERM ID="IX-PGTCL-PGLISTEN-2"><PRIMARY>notify</PRIMARY></INDEXTERM>
</REFNAMEDIV>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1998-5-22</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
pg_listen <REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">notifyName</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">callbackCommand</REPLACEABLE>
</SYNOPSIS>

<REFSECT2 ID="R2-PGTCL-PGLISTEN-1">
<REFSECT2INFO>
<DATE>1998-5-22</DATE>
</REFSECT2INFO>
<TITLE>Inputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies a valid database handle.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">notifyName</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies the notify condition name to start or stop listening to.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">callbackCommand</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>If present, provides the command string to execute
when a matching notification arrives.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>

<REFSECT2 ID="R2-PGTCL-PGLISTEN-2">
<REFSECT2INFO>
<DATE>1998-5-22</DATE>
</REFSECT2INFO>
<TITLE>Outputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  None
</TERM>
<LISTITEM>
<PARA>
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>

<REFSECT1 ID="R1-PGTCL-PGLISTEN-1">
<REFSECT1INFO>
<DATE>1998-5-22</DATE>
</REFSECT1INFO>
<TITLE>Description
</TITLE>
<PARA><FUNCTION>pg_listen</FUNCTION> creates, changes, or cancels a request
to listen for asynchronous NOTIFY messages from the
<ProductName>PostgreSQL</ProductName> backend.  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 NOTIFY message bearing
the given name arrives from the backend.  This occurs when any
<ProductName>PostgreSQL</ProductName> client application issues a NOTIFY command
referencing that name.  (Note that the name can be, but does not have to be,
that of an existing relation in the database.)
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 NOTIFY message yourself,
invoke the SQL NOTIFY statement using <FUNCTION>pg_exec</FUNCTION>.
</PARA>
</REFSECT1>

</REFENTRY>

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

<REFENTRY ID="PGTCL-PGON-CONNECTION-LOSS">
<REFMETA>
<REFENTRYTITLE>pg_on_connection_loss</REFENTRYTITLE>
<REFMISCINFO>PGTCL - Asynchronous Notify</REFMISCINFO>
</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-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>connection loss</SECONDARY></INDEXTERM>
<INDEXTERM ID="IX-PGTCL-PGON-CONNECTION-LOSS-2"><PRIMARY>connection loss</PRIMARY></INDEXTERM>
</REFNAMEDIV>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>2002-09-02</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
pg_on_connection_loss <REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">callbackCommand</REPLACEABLE>
</SYNOPSIS>

<REFSECT2 ID="R2-PGTCL-PGON-CONNECTION-LOSS-1">
<REFSECT2INFO>
<DATE>2002-09-02</DATE>
</REFSECT2INFO>
<TITLE>Inputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies a valid database handle.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">callbackCommand</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>If present, provides the command string to execute
when connection loss is detected.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>

<REFSECT2 ID="R2-PGTCL-PGON-CONNECTION-LOSS-2">
<REFSECT2INFO>
<DATE>2002-09-02</DATE>
</REFSECT2INFO>
<TITLE>Outputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  None
</TERM>
<LISTITEM>
<PARA>
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>

<REFSECT1 ID="R1-PGTCL-PGON-CONNECTION-LOSS-1">
<REFSECT1INFO>
<DATE>2002-09-02</DATE>
</REFSECT1INFO>
<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>

</REFENTRY>

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

<REFENTRY ID="PGTCL-PGLOCREAT">
<REFMETA>
<REFENTRYTITLE>pg_lo_creat</REFENTRYTITLE>
<REFMISCINFO>PGTCL - Large Objects</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>pg_lo_creat
</REFNAME>
<REFPURPOSE>create a large object
</REFPURPOSE>
<INDEXTERM ID="IX-PGTCL-PGLOCREAT-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>creating</SECONDARY></INDEXTERM>
<INDEXTERM ID="IX-PGTCL-PGLOCREAT-2"><PRIMARY>pg_lo_creat</PRIMARY></INDEXTERM>
</REFNAMEDIV>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1997-12-24</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
pg_lo_creat <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">mode</REPLACEABLE>
</SYNOPSIS>

<REFSECT2 ID="R2-PGTCL-PGLOCREAT-1">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Inputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies a valid database connection.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">mode</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies the access mode for the large object</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>

<REFSECT2 ID="R2-PGTCL-PGLOCREAT-2">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Outputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">objOid</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
The OID of the large object created.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>

<REFSECT1 ID="R1-PGTCL-PGLOCREAT-1">
<REFSECT1INFO>
<DATE>1997-12-24</DATE>
</REFSECT1INFO>
<TITLE>Description
</TITLE>
<PARA><FUNCTION>pg_lo_creat</FUNCTION> creates an Inversion Large Object.
</PARA>
</REFSECT1>
<REFSECT1 ID="R1-PGTCL-PGLOCREAT-2">
<TITLE>Usage
</TITLE>
<PARA>
mode can be any or'ing together of <literal>INV_READ</> and <literal>INV_WRITE</>.
The <quote>or</quote> operator is <literal>|</literal>.
<ProgramListing>
[pg_lo_creat $conn "INV_READ|INV_WRITE"]
</ProgramListing>
</PARA>
</REFSECT1>
</REFENTRY>

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

<REFENTRY ID="PGTCL-PGLOOPEN">
<REFMETA>
<REFENTRYTITLE>pg_lo_open</REFENTRYTITLE>
<REFMISCINFO>PGTCL - Large Objects</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>pg_lo_open
</REFNAME>
<REFPURPOSE>open a large object
</REFPURPOSE>
<INDEXTERM ID="IX-PGTCL-PGLOOPEN-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>opening</SECONDARY></INDEXTERM>
<INDEXTERM ID="IX-PGTCL-PGLOOPEN-2"><PRIMARY>pg_lo_open</PRIMARY></INDEXTERM>
</REFNAMEDIV>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1997-12-24</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
pg_lo_open <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">objOid</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">mode</REPLACEABLE>
</SYNOPSIS>

<REFSECT2 ID="R2-PGTCL-PGLOOPEN-1">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Inputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies a valid database connection.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">objOid</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies a valid large object OID.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">mode</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies the access mode for the large object</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>

<REFSECT2 ID="R2-PGTCL-PGLOOPEN-2">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Outputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">fd</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
A file descriptor for use in later pg_lo* routines.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>

<REFSECT1 ID="R1-PGTCL-PGLOOPEN-1">
<REFSECT1INFO>
<DATE>1997-12-24</DATE>
</REFSECT1INFO>
<TITLE>Description
</TITLE>
<PARA><FUNCTION>pg_lo_open</FUNCTION> open an Inversion Large Object.
</PARA>
</REFSECT1>
<REFSECT1 ID="R1-PGTCL-PGLOOPEN-2">
<TITLE>Usage
</TITLE>
<PARA>
Mode can be either <literal>r</>, <literal>w</>, or <literal>rw</>.
</PARA>
</REFSECT1>
</REFENTRY>

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

<REFENTRY ID="PGTCL-PGLOCLOSE">
<REFMETA>
<REFENTRYTITLE>pg_lo_close</REFENTRYTITLE>
<REFMISCINFO>PGTCL - Large Objects</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>pg_lo_close
</REFNAME>
<REFPURPOSE>close a large object
</REFPURPOSE>
<INDEXTERM ID="IX-PGTCL-PGLOCLOSE-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>closing</SECONDARY></INDEXTERM>
<INDEXTERM ID="IX-PGTCL-PGLOCLOSE-2"><PRIMARY>pg_lo_close</PRIMARY></INDEXTERM>
</REFNAMEDIV>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1997-12-24</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
pg_lo_close <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">fd</REPLACEABLE>
</SYNOPSIS>

<REFSECT2 ID="R2-PGTCL-PGLOCLOSE-1">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Inputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies a valid database connection.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">fd</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
A file descriptor for use in later pg_lo* routines.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>

<REFSECT2 ID="R2-PGTCL-PGLOCLOSE-2">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Outputs
</TITLE>
<PARA>None</PARA>
</REFSECT2>
</REFSYNOPSISDIV>

<REFSECT1 ID="R1-PGTCL-PGLOCLOSE-1">
<REFSECT1INFO>
<DATE>1997-12-24</DATE>
</REFSECT1INFO>
<TITLE>Description
</TITLE>
<PARA><FUNCTION>pg_lo_close</FUNCTION> closes an Inversion Large Object.
</PARA>
</REFSECT1>
<REFSECT1 ID="R1-PGTCL-PGLOCLOSE-2">
<TITLE>Usage
</TITLE>
<PARA>
</PARA>
</REFSECT1>
</REFENTRY>

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

<REFENTRY ID="PGTCL-PGLOREAD">
<REFMETA>
<REFENTRYTITLE>pg_lo_read</REFENTRYTITLE>
<REFMISCINFO>PGTCL - Large Objects</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>pg_lo_read
</REFNAME>
<REFPURPOSE>read a large object
</REFPURPOSE>
<INDEXTERM ID="IX-PGTCL-PGLOREAD-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>reading</SECONDARY></INDEXTERM>
<INDEXTERM ID="IX-PGTCL-PGLOREAD-2"><PRIMARY>pg_lo_read</PRIMARY></INDEXTERM>
</REFNAMEDIV>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1997-12-24</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
pg_lo_read <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">fd</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">bufVar</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">len</REPLACEABLE>
</SYNOPSIS>

<REFSECT2 ID="R2-PGTCL-PGLOREAD-1">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Inputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies a valid database connection.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">fd</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
File descriptor for the large object from pg_lo_open.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">bufVar</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies a valid buffer variable to contain the large object segment.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">len</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies the maximum allowable size of the large object segment.</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>

<REFSECT2 ID="R2-PGTCL-PGLOREAD-2">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Outputs
</TITLE>
<PARA>None</PARA>
</REFSECT2>
</REFSYNOPSISDIV>

<REFSECT1 ID="R1-PGTCL-PGLOREAD-1">
<REFSECT1INFO>
<DATE>1997-12-24</DATE>
</REFSECT1INFO>
<TITLE>Description
</TITLE>
<PARA><FUNCTION>pg_lo_read</FUNCTION> reads 
at most <REPLACEABLE CLASS="PARAMETER">len</REPLACEABLE> bytes from a large object into a variable
 named <REPLACEABLE CLASS="PARAMETER">bufVar</REPLACEABLE>.
</PARA>
</REFSECT1>
<REFSECT1 ID="R1-PGTCL-PGLOREAD-2">
<TITLE>Usage
</TITLE>
<PARA>
<REPLACEABLE CLASS="PARAMETER">bufVar</REPLACEABLE> must be a valid variable name.
</PARA>
</REFSECT1>
</REFENTRY>

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

<REFENTRY ID="PGTCL-PGLOWRITE">
<REFMETA>
<REFENTRYTITLE>pg_lo_write</REFENTRYTITLE>
<REFMISCINFO>PGTCL - Large Objects</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>pg_lo_write
</REFNAME>
<REFPURPOSE>write a large object
</REFPURPOSE>
<INDEXTERM ID="IX-PGTCL-PGLOWRITE-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>writing</SECONDARY></INDEXTERM>
<INDEXTERM ID="IX-PGTCL-PGLOWRITE-2"><PRIMARY>pg_lo_write</PRIMARY></INDEXTERM>
</REFNAMEDIV>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1997-12-24</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
pg_lo_write <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">fd</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">buf</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">len</REPLACEABLE>
</SYNOPSIS>

<REFSECT2 ID="R2-PGTCL-PGLOWRITE-1">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Inputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies a valid database connection.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">fd</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
File descriptor for the large object from pg_lo_open.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">buf</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies a valid string variable to write to the large object.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">len</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies the maximum size of the string to write.</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>

<REFSECT2 ID="R2-PGTCL-PGLOWRITE-2">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Outputs
</TITLE>
<PARA>None</PARA>
</REFSECT2>
</REFSYNOPSISDIV>

<REFSECT1 ID="R1-PGTCL-PGLOWRITE-1">
<REFSECT1INFO>
<DATE>1997-12-24</DATE>
</REFSECT1INFO>
<TITLE>Description
</TITLE>
<PARA><FUNCTION>pg_lo_write</FUNCTION> writes 
at most <REPLACEABLE CLASS="PARAMETER">len</REPLACEABLE> bytes to a large object from a variable
 <REPLACEABLE CLASS="PARAMETER">buf</REPLACEABLE>.
</PARA>
</REFSECT1>
<REFSECT1 ID="R1-PGTCL-PGLOWRITE-2">
<TITLE>Usage
</TITLE>
<PARA>
<REPLACEABLE CLASS="PARAMETER">buf</REPLACEABLE> must be 
the actual string to write, not a variable name.
</PARA>
</REFSECT1>
</REFENTRY>

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

<REFENTRY ID="PGTCL-PGLOLSEEK">
<REFMETA>
<REFENTRYTITLE>pg_lo_lseek</REFENTRYTITLE>
<REFMISCINFO>PGTCL - Large Objects</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>pg_lo_lseek
</REFNAME>
<REFPURPOSE>seek to a position in a large object
</REFPURPOSE>
<INDEXTERM ID="IX-PGTCL-PGLOLSEEK-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>positioning</SECONDARY></INDEXTERM>
<INDEXTERM ID="IX-PGTCL-PGLOLSEEK-2"><PRIMARY>pg_lo_lseek</PRIMARY></INDEXTERM>
</REFNAMEDIV>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1997-12-24</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
pg_lo_lseek <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">fd</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">offset</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">whence</REPLACEABLE>
</SYNOPSIS>

<REFSECT2 ID="R2-PGTCL-PGLOLSEEK-1">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Inputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies a valid database connection.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">fd</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
File descriptor for the large object from pg_lo_open.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">offset</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies a zero-based offset in bytes.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">whence</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA> whence can be <literal>SEEK_CUR</>, <literal>SEEK_END</>, or <literal>SEEK_SET</> </PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>

<REFSECT2 ID="R2-PGTCL-PGLOLSEEK-2">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Outputs
</TITLE>
<PARA>None</PARA>
</REFSECT2>
</REFSYNOPSISDIV>

<REFSECT1 ID="R1-PGTCL-PGLOLSEEK-1">
<REFSECT1INFO>
<DATE>1997-12-24</DATE>
</REFSECT1INFO>
<TITLE>Description
</TITLE>
<PARA><FUNCTION>pg_lo_lseek</FUNCTION> positions 
to <REPLACEABLE CLASS="PARAMETER">offset</REPLACEABLE> bytes from the beginning of the large object.
</PARA>
</REFSECT1>
<REFSECT1 ID="R1-PGTCL-PGLOLSEEK-2">
<TITLE>Usage
</TITLE>
<PARA>
<REPLACEABLE CLASS="PARAMETER">whence</REPLACEABLE> 
can be <literal>SEEK_CUR</literal>, <literal>SEEK_END</>, or <literal>SEEK_SET</literal>.
</PARA>
</REFSECT1>
</REFENTRY>

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

<REFENTRY ID="PGTCL-PGLOTELL">
<REFMETA>
<REFENTRYTITLE>pg_lo_tell</REFENTRYTITLE>
<REFMISCINFO>PGTCL - Large Objects</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>pg_lo_tell
</REFNAME>
<REFPURPOSE>return the current seek position of a large object
</REFPURPOSE>
<INDEXTERM ID="IX-PGTCL-PGLOTELL-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>positioning</SECONDARY></INDEXTERM>
<INDEXTERM ID="IX-PGTCL-PGLOTELL-2"><PRIMARY>pg_lo_tell</PRIMARY></INDEXTERM>
</REFNAMEDIV>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1997-12-24</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
pg_lo_tell <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">fd</REPLACEABLE>
</SYNOPSIS>

<REFSECT2 ID="R2-PGTCL-PGLOTELL-1">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Inputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies a valid database connection.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">fd</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
File descriptor for the large object from pg_lo_open.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>

<REFSECT2 ID="R2-PGTCL-PGLOTELL-2">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Outputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">offset</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>A zero-based offset in bytes suitable for input to <Function>pg_lo_lseek</Function>.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>
</REFSYNOPSISDIV>

<REFSECT1 ID="R1-PGTCL-PGLOTELL-1">
<REFSECT1INFO>
<DATE>1997-12-24</DATE>
</REFSECT1INFO>
<TITLE>Description
</TITLE>
<PARA><FUNCTION>pg_lo_tell</FUNCTION> returns the current
to <REPLACEABLE CLASS="PARAMETER">offset</REPLACEABLE> in bytes from the beginning of the large object.
</PARA>
</REFSECT1>
<REFSECT1 ID="R1-PGTCL-PGLOTELL-2">
<TITLE>Usage
</TITLE>
<PARA>
</PARA>
</REFSECT1>
</REFENTRY>

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

<REFENTRY ID="PGTCL-PGLOUNLINK">
<REFMETA>
<REFENTRYTITLE>pg_lo_unlink</REFENTRYTITLE>
<REFMISCINFO>PGTCL - Large Objects</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>pg_lo_unlink
</REFNAME>
<REFPURPOSE>delete a large object
</REFPURPOSE>
<INDEXTERM ID="IX-PGTCL-PGLOUNLINK-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>delete</SECONDARY></INDEXTERM>
<INDEXTERM ID="IX-PGTCL-PGLOUNLINK-2"><PRIMARY>pg_lo_unlink</PRIMARY></INDEXTERM>
</REFNAMEDIV>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1997-12-24</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
pg_lo_unlink <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">lobjId</REPLACEABLE>
</SYNOPSIS>

<REFSECT2 ID="R2-PGTCL-PGLOUNLINK-1">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Inputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies a valid database connection.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">lobjId</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
Identifier for a large object.
<comment>
 XXX Is this the same as <parameter>objOid</parameter> in other calls?? - thomas 1998-01-11
</comment>
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>

<REFSECT2 ID="R2-PGTCL-PGLOUNLINK-2">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Outputs
</TITLE>
<PARA>
None
</PARA>
</REFSECT2>
</REFSYNOPSISDIV>

<REFSECT1 ID="R1-PGTCL-PGLOUNLINK-1">
<REFSECT1INFO>
<DATE>1997-12-24</DATE>
</REFSECT1INFO>
<TITLE>Description
</TITLE>
<PARA><FUNCTION>pg_lo_unlink</FUNCTION> deletes the specified large object.
</PARA>
</REFSECT1>
<REFSECT1 ID="R1-PGTCL-PGLOUNLINK-2">
<TITLE>Usage
</TITLE>
<PARA>
</PARA>
</REFSECT1>
</REFENTRY>

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

<REFENTRY ID="PGTCL-PGLOIMPORT">
<REFMETA>
<REFENTRYTITLE>pg_lo_import</REFENTRYTITLE>
<REFMISCINFO>PGTCL - Large Objects</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>pg_lo_import
</REFNAME>
<REFPURPOSE>import a large object from a file
</REFPURPOSE>
<INDEXTERM ID="IX-PGTCL-PGLOIMPORT-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>import</SECONDARY></INDEXTERM>
<INDEXTERM ID="IX-PGTCL-PGLOIMPORT-2"><PRIMARY>pg_lo_import</PRIMARY></INDEXTERM>
</REFNAMEDIV>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1997-12-24</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
pg_lo_import <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">filename</REPLACEABLE>
</SYNOPSIS>

<REFSECT2 ID="R2-PGTCL-PGLOIMPORT-1">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Inputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies a valid database connection.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">filename</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
Unix file name.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>

<REFSECT2 ID="R2-PGTCL-PGLOIMPORT-2">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Outputs
</TITLE>
<PARA>
None
<comment>
 XXX Does this return a lobjId? Is that the same as the objOid in other calls? thomas - 1998-01-11
</comment>
</PARA>
</REFSECT2>
</REFSYNOPSISDIV>

<REFSECT1 ID="R1-PGTCL-PGLOIMPORT-1">
<REFSECT1INFO>
<DATE>1997-12-24</DATE>
</REFSECT1INFO>
<TITLE>Description
</TITLE>
<PARA><FUNCTION>pg_lo_import</FUNCTION> reads the specified file and places the contents into a large object.
</PARA>
</REFSECT1>
<REFSECT1 ID="R1-PGTCL-PGLOIMPORT-2">
<TITLE>Usage
</TITLE>
<PARA>
  <Function>pg_lo_import</Function> must be called within a BEGIN/END transaction block.
</PARA>
</REFSECT1>
</REFENTRY>

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

<REFENTRY ID="PGTCL-PGLOEXPORT">
<REFMETA>
<REFENTRYTITLE>pg_lo_export</REFENTRYTITLE>
<REFMISCINFO>PGTCL - Large Objects</REFMISCINFO>
</REFMETA>
<REFNAMEDIV>
<REFNAME>pg_lo_export
</REFNAME>
<REFPURPOSE>export a large object to a file
</REFPURPOSE>
<INDEXTERM ID="IX-PGTCL-PGLOEXPORT-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>export</SECONDARY></INDEXTERM>
<INDEXTERM ID="IX-PGTCL-PGLOEXPORT-2"><PRIMARY>pg_lo_export</PRIMARY></INDEXTERM>
</REFNAMEDIV>
<REFSYNOPSISDIV>
<REFSYNOPSISDIVINFO>
<DATE>1997-12-24</DATE>
</REFSYNOPSISDIVINFO>
<SYNOPSIS>
pg_lo_export <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">lobjId</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">filename</REPLACEABLE>
</SYNOPSIS>

<REFSECT2 ID="R2-PGTCL-PGLOEXPORT-1">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Inputs
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>Specifies a valid database connection.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">lobjId</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
Large object identifier.
<comment>
 XXX Is this the same as the objOid in other calls?? thomas - 1998-01-11
</comment>
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">filename</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
Unix file name.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>

<REFSECT2 ID="R2-PGTCL-PGLOEXPORT-2">
<REFSECT2INFO>
<DATE>1997-12-24</DATE>
</REFSECT2INFO>
<TITLE>Outputs
</TITLE>
<PARA>
None
<comment>
 XXX Does this return a lobjId? Is that the same as the objOid in other calls? thomas - 1998-01-11
</comment>
</PARA>
</REFSECT2>
</REFSYNOPSISDIV>

<REFSECT1 ID="R1-PGTCL-PGLOEXPORT-1">
<REFSECT1INFO>
<DATE>1997-12-24</DATE>
</REFSECT1INFO>
<TITLE>Description
</TITLE>
<PARA><FUNCTION>pg_lo_export</FUNCTION> writes the specified large object into a Unix file.
</PARA>
</REFSECT1>
<REFSECT1 ID="R1-PGTCL-PGLOEXPORT-2">
<TITLE>Usage
</TITLE>
<PARA>
  <Function>pg_lo_export</Function> must be called within a BEGIN/END transaction block.
</PARA>
</REFSECT1>
</REFENTRY>
d1935 1
a1935 2
</Sect1>
</Chapter>
@


1.33
log
@SGML improvements.

Neil Conway
@
text
@d731 10
@


1.32
log
@I'm using libpgtcl with PostgreSQL-7.2.3. There is a discrepancy between
the documentation and behavior of "pg_result $res -oid" when $res is not
from an INSERT.  The documentation says it should return an empty
string, but in fact it returns 0. I think it used to return an empty
string around PostgreSQL-7.1.3 when PQoidStatus() was used, but now it
uses PQoidValue() which returns InvalidOid, 0 in this case.

Assuming the current behavior is desired, here is a patch to the
documentation doc/src/sgml/libpgtcl.sgml to match what really happens:


ljb
@
text
@d1115 2
a1116 1
<FUNCTION>pg_execute</FUNCTION> submits a query to the PostgreSQL backend.
@


1.31
log
@Add more appropriate markup.
@
text
@d715 1
a715 1
inserted tuple; otherwise an empty string.
@


1.31.2.1
log
@I'm using libpgtcl with PostgreSQL-7.2.3. There is a discrepancy between
the documentation and behavior of "pg_result $res -oid" when $res is not
from an INSERT.  The documentation says it should return an empty
string, but in fact it returns 0. I think it used to return an empty
string around PostgreSQL-7.1.3 when PQoidStatus() was used, but now it
uses PQoidValue() which returns InvalidOid, 0 in this case.

Assuming the current behavior is desired, here is a patch to the
documentation doc/src/sgml/libpgtcl.sgml to match what really happens:


ljb
@
text
@d715 1
a715 1
inserted tuple; otherwise 0.
@


1.30
log
@Fix SGML build failure.
@
text
@d1041 1
a1041 1
This is ignored if queryString is not a SELECT statement. For SELECT
d1121 1
a1121 1
stored in the oidVar variable if the optional <PARAMETER>-oid</PARAMETER>
d1169 1
a1169 1
Insert a row and save the OID in result_oid:
@


1.29
log
@pg_on_connection_loss command for libpgtcl.  Patch from
Gerhard Hintermayer, revised and documented by Tom Lane.

This patch also fixes a 'must fix' bug: libpgtcl's LISTEN/NOTIFY
support was broken by the recent changes to the PGnotify structure.
Guess that change wasn't quite so safe as we thought.
@
text
@d1319 1
a1319 1
<REFENTRY ID="PGTCL-PGON_CONNECTION_LOSS">
d1330 2
a1331 2
ID="IX-PGTCL-PGON_CONNECTION_LOSS-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>connection loss</SECONDARY></INDEXTERM>
<INDEXTERM ID="IX-PGTCL-PGON_CONNECTION_LOSS-2"><PRIMARY>connection loss</PRIMARY></INDEXTERM>
d1341 1
a1341 1
<REFSECT2 ID="R2-PGTCL-PGON_CONNECTION_LOSS-1">
d1370 1
a1370 1
<REFSECT2 ID="R2-PGTCL-PGON_CONNECTION_LOSS-2">
d1390 1
a1390 1
<REFSECT1 ID="R1-PGTCL-PGON_CONNECTION_LOSS-1">
@


1.28
log
@Fix broken SGML tag.
@
text
@d75 4
d1252 1
a1252 1
<PARA>If present and not empty, provides the command string to execute
d1313 99
@


1.27
log
@This is a proposed patch to doc/src/sgml/libpgtcl.sgml which documents
the libpgtcl "pg_execute" command. This was mentioned on
pgsql-interfaces on Mar 3. I am posting it here in the hope that someone
will check to see if it makes sense and is correct SGML-wise.  I did run
it through jade, but this is my first try at this sort of thing.

ljb
@
text
@d70 1
@


1.26
log
@Spell checking and markup additions
@
text
@d68 3
d992 196
@


1.25
log
@Spell-check and markup police
@
text
@d1176 1
a1176 1
The oid of the large object created.
d1250 1
a1250 1
<PARA>Specifies a valid large object oid.
@


1.24
log
@Editorial review
@
text
@d1197 2
a1198 2
mode can be any OR'ing together of INV_READ and INV_WRITE. 
The OR delimiter character is <literal>|</literal>.
@


1.23
log
@Add a section about loading libpgtcl; fix errors and omissions in
documentation of pg_select command.
@
text
@d12 2
a13 6
<Para>
<literal>pgtcl</literal> is a Tcl package for front-end programs 
to interface with <ProductName>PostgreSQL</ProductName>
backends.  It makes most of the functionality of <literal>libpq</literal> available to
Tcl scripts.
</Para>
d15 16
a30 3
<Para>
This package was originally written by Jolly Chen.
</Para>
a31 2
<Sect1 id="libpgtcl-commands">
<Title>Commands</Title>
d33 1
a33 2
<Para>
<TABLE TOCENTRY="1">
a114 16
</Para>

<Para>
These commands are described further on subsequent pages.
</Para>

<Para>
The pg_lo* routines are interfaces to the Large Object features of
<ProductName>PostgreSQL</ProductName>.
The functions are designed to mimic the analogous file system functions in
the standard Unix file system interface.
The pg_lo* routines should be used within a BEGIN/END transaction
block because the file descriptor returned by pg_lo_open is only valid for
the current transaction.  pg_lo_import and pg_lo_export MUST be used
in a BEGIN/END transaction block.
</Para>
d116 19
a134 1
</Sect1>
d136 1
a136 4
<Sect1 id="libpgtcl-examples">
<Title>Examples</Title>

  <example>
a138 3
   <para>
    Here's a small example of how to use the routines:

d156 1
a156 2
</ProgramListing>
   </para>
d158 1
a158 1
</Sect1>
d169 1
a169 1
	load libpgtcl[info sharedlibextension]
d178 7
a184 5
    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 <literal>ldconfig</>, or set the environment
    variable <envar>LD_LIBRARY_PATH</>, or use some equivalent facility for
    your platform to make it work.
d215 1
a215 1
<REFPURPOSE>opens a connection to the backend server
d369 1
a369 1
<REFPURPOSE>closes a connection to the backend server
d528 1
a528 1
send a query string to the backend 
d1005 1
a1005 1
<REFPURPOSE>sets or changes a callback for asynchronous NOTIFY messages
d1865 1
a1865 1
<REFPURPOSE>import a large object from a Unix file
d1950 1
a1950 1
<REFPURPOSE>export a large object to a Unix file
@


1.22
log
@Deprecate 'current' for date/time input.
Fix up references to "PostgreSQL" rather than "Postgres". Was roughly
 evenly split between the two before. ref/ files not yet done.
@
text
@d159 42
d862 1
a862 2
pg_select <REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">queryString</REPLACEABLE>
  <REPLACEABLE CLASS="PARAMETER">arrayVar</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">queryProcedure</REPLACEABLE>
d918 3
a920 12
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">resultHandle</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>
   the return result is either an error message or a handle for a query result.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
d943 31
d984 1
a984 1
		puts [format "%5d %s" array(control) array(name)]
@


1.21
log
@Uppercase keywords where appropriate.
@
text
@d14 1
a14 1
to interface with <ProductName>Postgres</ProductName>
d117 1
a117 1
<ProductName>Postgres</ProductName>.
d296 1
a296 1
<ProductName>Postgres</ProductName> backend.
d382 1
a382 1
<PARA><FUNCTION>pg_disconnect</FUNCTION> closes a connection to the <ProductName>Postgres</ProductName> backend.
d556 1
a556 1
<FUNCTION>pg_exec</FUNCTION> submits a query to the <ProductName>Postgres</ProductName> backend and returns a result.
d899 1
a899 1
<ProductName>Postgres</ProductName> backend, and executes a
d1018 1
a1018 1
<ProductName>Postgres</ProductName> backend.  With a <parameter>callbackCommand</>
d1028 1
a1028 1
<ProductName>Postgres</ProductName> client application issues a NOTIFY command
@


1.20
log
@Remove mention of "pg_result -list" becuase it is not implemented, per
Tatsuo.
@
text
@d920 1
a920 1
	pg_select $pgconn "SELECT * from table" array {
@


1.19
log
@Markup examples as examples.
@
text
@a687 10
<option>-list VarName</option>
</TERM>
<LISTITEM>
<PARA>
assign the results to a list of lists.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
@


1.18
log
@Replace ASCII-quotes with proper markup.
@
text
@d131 2
a132 2
<Para>
Here's a small example of how to use the routines:
d134 4
a137 1
<ProgramListing>
d155 2
a156 2

</Para>
@


1.17
log
@Markup and spell-check run over Programmer's Guide (rather incomplete still).
@
text
@d924 1
a924 1
This would work if table "table" has fields "control" and "name"
d1139 1
a1139 1
The OR delimiter character is "|".
d1240 1
a1240 1
Mode can be either "r", "w", or "rw".
d1586 1
a1586 1
<PARA> whence can be "SEEK_CUR", "SEEK_END", or "SEEK_SET" </PARA>
d1617 1
a1617 1
can be "SEEK_CUR", "SEEK_END", or "SEEK_SET".
@


1.16
log
@Remove mention of INV_ARCHIVE.
@
text
@d2 1
a2 1
 <title>pgtcl - Tcl Binding Library</title>
d13 1
a13 1
<literal>pgtcl</literal> is a tcl package for front-end programs 
d16 1
a16 1
tcl scripts.
d38 1
a38 1
    <ENTRY>pg_connect</ENTRY>
d42 1
a42 1
    <ENTRY>pg_disconnect</ENTRY>
d46 1
a46 1
    <ENTRY>pg_conndefaults</ENTRY>
d50 1
a50 1
    <ENTRY>pg_exec</ENTRY>
d54 1
a54 1
    <ENTRY>pg_result</ENTRY>
d58 1
a58 1
    <ENTRY>pg_select</ENTRY>
d62 1
a62 1
    <ENTRY>pg_listen</ENTRY>
d67 1
a67 1
    <ENTRY>pg_lo_creat</ENTRY>
d71 1
a71 1
    <ENTRY>pg_lo_open</ENTRY>
d75 1
a75 1
    <ENTRY>pg_lo_close</ENTRY>
d79 1
a79 1
    <ENTRY>pg_lo_read</ENTRY>
d83 1
a83 1
    <ENTRY>pg_lo_write</ENTRY>
d87 1
a87 1
    <ENTRY>pg_lo_lseek</ENTRY>
d91 1
a91 1
    <ENTRY>pg_lo_tell</ENTRY>
d95 1
a95 1
    <ENTRY>pg_lo_unlink</ENTRY>
d99 1
a99 1
    <ENTRY>pg_lo_import</ENTRY>
d103 1
a103 1
    <ENTRY>pg_lo_export</ENTRY>
d157 1
a157 1
<Title>pgtcl Command Reference Information</Title>
d246 1
a246 1
<PARA>Specifies file or tty for optional debug output from backend.
d276 1
a276 1
Handles start with the prefix "pgsql".
d307 3
a309 2
<PARA>XXX thomas 1997-12-24
</PARA>
d437 3
a439 3
<para>
	 {optname label dispchar dispsize value}
</Para>
d441 1
a441 1
where the optname is usable as an option in
d466 1
a466 1
<PARA>pg_conndefaults
d536 1
a536 1
A Tcl error will be returned if Pgtcl was unable to obtain a backend
d624 1
a624 1
-status  
d634 1
a634 1
-error
d644 1
a644 1
-conn
d654 1
a654 1
-oid
d665 1
a665 1
-numTuples
d675 1
a675 1
-numAttrs
d685 1
a685 1
-list VarName
d695 1
a695 1
-assign arrayName
d700 1
a700 1
(tupno,attributeName).
d706 1
a706 1
-assignbyidx arrayName ?appendstr?
d711 1
a711 1
the remaining attributes' names as keys.  If appendstr is given then
d714 1
a714 1
(firstFieldValue,fieldNameAppendStr).
d720 1
a720 1
-getTuple tupleNumber
d731 1
a731 1
-tupleArray tupleNumber arrayName
d735 1
a735 1
stores the fields of the tuple in array arrayName, indexed by field names.
d742 1
a742 1
-attributes
d752 1
a752 1
-lAttributes
d756 1
a756 1
returns a list of sublists, {name ftype fsize} for each tuple attribute.
d762 1
a762 1
-clear 
d800 1
a800 1
a memory leak, and Pgtcl will eventually start complaining that you've
d1025 1
a1025 1
<ProductName>Postgres</ProductName> backend.  With a callbackCommand
d1027 1
a1027 1
existing request is replaced.  With no callbackCommand parameter, a prior
d1045 2
a1046 2
You should not invoke the SQL statements LISTEN or UNLISTEN directly when
using <FUNCTION>pg_listen</FUNCTION>.  Pgtcl takes care of issuing those
d1758 3
a1760 1
XXX Is this the same as objOid in other calls?? - thomas 1998-01-11
d1856 3
a1858 1
XXX Does this return a lobjId? Is that the same as the objOid in other calls? thomas - 1998-01-11
d1927 3
a1929 1
XXX Is this the same as the objOid in other calls?? thomas - 1998-01-11
d1954 3
a1956 1
XXX Does this return a lobjId? Is that the same as the objOid in other calls? thomas - 1998-01-11
@


1.15
log
@Add index.  Only some parts of the manual set have index entries so far...
@
text
@d1137 1
a1137 1
mode can be any OR'ing together of INV_READ, INV_WRITE, and INV_ARCHIVE. 
@


1.14
log
@Add mention of libpgtcl's options to manual, libpq++ markup fixes.
@
text
@d1 10
a10 2
<Chapter Id="pgtcl">
<Title>pgtcl - TCL Binding Library</Title>
@


1.13
log
@Add `id' attributes to all `chapter' and `sect1' tags, to generate useful
names for the HTML files (e.g., not x4856.htm).
@
text
@d191 2
@


1.12
log
@Minor markup changes. Refer to (".../catalog") in the emacs hints.
@
text
@d15 1
a15 1
<Sect1>
d120 1
a120 1
<Sect1>
d148 1
a148 1
<Sect1>
@


1.11
log
@Accumulated fixups.
Add some chapters on new topics.
Change to referencing OASIS/Docbook v3.1 rather than Davenport/Docbook v3.0
Grepped for and fixed apparent tag mangling from emacs
 "Normalize" operation. Should be the last of those.
@
text
@d2 1
a2 1
<Title>pgtcl</Title>
@


1.10
log
@Clean up to ensure tag completion as required by the newest versions
 of Norm's Modular Style Sheets and jade/docbook.
From Vince Vielhaber <vev@@michvhf.com>.
@
text
@d674 10
@


1.9
log
@Minor editing and markup changes as a result of preparing the Postscript
 documentation for v6.4.
Bigger updates to the installation instructions (install and config).
@
text
@d284 1
d425 1
d428 1
d546 1
d555 1
d773 1
d1021 1
@


1.8
log
@Minor documentation improvements and markup fixes.
@
text
@d5 3
a7 2
pgtcl is a tcl package for front-end programs to interface with <ProductName>Postgres</ProductName>
backends.  It makes most of the functionality of libpq available to
d20 1
a20 1
<TITLE>PGTCL Commands</TITLE>
@


1.7
log
@Clean up markup.
Add new bibliographic references from Paul Aoki.
Include libpq++ docs from the old man page in the Programmer's Guide.
Update Unix installation info for ODBC.
@
text
@d50 1
a50 1
    <ENTRY>loop over the result of a select statement</ENTRY>
d79 1
a79 1
    <ENTRY>seek to a position on a large object</ENTRY>
d171 2
a172 2
  CLASS="PARAMETER">portNumber</REPLACEABLE></OPTIONAL> <OPTIONAL>-tty
  <REPLACEABLE CLASS="PARAMETER">pqtty</REPLACEABLE></OPTIONAL>
d179 19
d235 1
a235 1
<PARA>(need information thomas 1997-12-24)
a250 19
<REFSECT2 ID="R2-PGTCL-PGCONNECT-2">
<REFSECT2INFO>
<DATE>1998-10-07</DATE>
</REFSECT2INFO>
<TITLE>Inputs (new style)
</TITLE>
<VARIABLELIST>
<VARLISTENTRY>
<TERM>
  <REPLACEABLE CLASS="PARAMETER">connectOptions</REPLACEABLE>
</TERM>
<LISTITEM>
<PARA>A string of connection options, each written in the form keyword = value.
</PARA>
</LISTITEM>
</VARLISTENTRY>
</VARIABLELIST>
</REFSECT2>

d426 2
a427 1
where the optname is usable as an option in pg_connect -conninfo.
d789 1
a789 1
loop over the result of a select statement
d1504 1
a1504 1
<REFPURPOSE>seek to a position on a large object
@


1.6
log
@libpgtcl.sgml still needs work, but at least there are
fewer errors than there were.
@
text
@d168 1
a174 2
<para>
pg_connect -conninfo <REPLACEABLE CLASS="PARAMETER">connectOptions</REPLACEABLE>
d440 2
@


1.5
log
@Rename Id tags to eliminate the trailing "-1" field. This propagates
 into cleaner html output file names.
@
text
@a17 6
The pg_lo* routines are interfaces to the Inversion Large Objects in <ProductName>Postgres</ProductName>.
The functions are designed to mimic the analogous file system functions in
the standard Unix file system interface.
</Para>

<Para>
d107 5
a111 1
The pg_lo* routines should typically be used within a BEGIN/END transaction
d138 1
d169 7
a175 1
  <OPTIONAL>-port <REPLACEABLE CLASS="PARAMETER">portNumber</REPLACEABLE></OPTIONAL> <OPTIONAL>-tty <REPLACEABLE CLASS="PARAMETER">pqtty</REPLACEABLE></OPTIONAL> <OPTIONAL>-options <REPLACEABLE CLASS="PARAMETER">optionalBackendArgs</REPLACEABLE></OPTIONAL>
d182 1
a182 1
<TITLE>Inputs
d235 19
d265 2
a266 2
The return result is either an error message or a handle for a database
   connection.  Handles start with the prefix "pgsql"
d282 9
a290 1
<PARA><FUNCTION>pg_connect</FUNCTION> opens a connection to the <ProductName>Postgres</ProductName> backend.
d373 81
d457 1
a457 1
<REFMISCINFO>PGTCL - Connection Management</REFMISCINFO>
d515 1
a515 1
  <REPLACEABLE CLASS="PARAMETER">queryHandle</REPLACEABLE>
d519 4
a522 1
   the return result is either an error message or a handle for a query result.
d540 6
d549 1
a549 1
<REFENTRY ID="PGTCL-PGLISTEN">
d551 2
a552 2
<REFENTRYTITLE>pg_listen</REFENTRYTITLE>
<REFMISCINFO>PGTCL - Asynchronous Notify</REFMISCINFO>
d555 1
a555 1
<REFNAME>pg_listen
d557 2
a558 1
<REFPURPOSE>sets or changes a callback for asynchronous NOTIFY messages
d560 2
a561 2
<INDEXTERM ID="IX-PGTCL-PGLISTEN-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>notify</SECONDARY></INDEXTERM>
<INDEXTERM ID="IX-PGTCL-PGLISTEN-2"><PRIMARY>notify</PRIMARY></INDEXTERM>
d565 1
a565 1
<DATE>1998-5-22</DATE>
d568 1
a568 1
pg_listen <REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">notifyName</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">callbackCommand</REPLACEABLE>
d570 1
a570 2

<REFSECT2 ID="R2-PGTCL-PGLISTEN-1">
d572 1
a572 1
<DATE>1998-5-22</DATE>
d579 124
a702 1
  <REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE>
d705 3
a707 1
<PARA>Specifies a valid database handle.
d713 1
a713 1
  <REPLACEABLE CLASS="PARAMETER">notifyName</REPLACEABLE>
d716 2
a717 1
<PARA>Specifies the notification name to start or stop listening to.
d723 1
a723 1
  <REPLACEABLE CLASS="PARAMETER">callbackCommand</REPLACEABLE>
d726 2
a727 2
<PARA>If present and not empty, provides the command string to execute
when a matching notification arrives.
a730 10
</VARIABLELIST>
</REFSECT2>

<REFSECT2 ID="R2-PGTCL-PGLISTEN-2">
<REFSECT2INFO>
<DATE>1998-5-22</DATE>
</REFSECT2INFO>
<TITLE>Outputs
</TITLE>
<VARIABLELIST>
d733 1
a733 1
  None
d737 1
d742 1
a743 1
</REFSYNOPSISDIV>
d745 12
a756 1
<REFSECT1 ID="R1-PGTCL-PGLISTEN-1">
d758 1
a758 1
<DATE>1998-5-22</DATE>
d762 3
a764 7
<PARA><FUNCTION>pg_listen</FUNCTION> creates, changes, or cancels a request
to listen for asynchronous NOTIFY messages from the
<ProductName>Postgres</ProductName> backend.  With a callbackCommand
parameter, the request is established, or the command string of an already
existing request is replaced.  With no callbackCommand parameter, a prior
request is canceled.
</PARA>
d767 5
a771 10
After a <PARA><FUNCTION>pg_listen</FUNCTION> request is established,
the specified command string is executed whenever a NOTIFY message bearing
the given name arrives from the backend.  This occurs when any
<ProductName>Postgres</ProductName> client application issues a NOTIFY command
referencing that name.  (Note that the name can be, but does not have to be,
that of an existing relation in the database.)
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.
a773 1

d781 1
a781 1
<REFMISCINFO>PGTCL - Connection Management</REFMISCINFO>
d857 1
a857 1
  <REPLACEABLE CLASS="PARAMETER">queryHandle</REPLACEABLE>
d875 3
a877 2
<FUNCTION>pg_select</FUNCTION> submits a query to the <ProductName>Postgres</ProductName> backend.
 and returns the results.
d879 1
a879 1
   must be a select statement.  Anything else returns an error.
d881 6
a886 3
   variable is an array name used in the loop.  It is filled
   out with the result of the query for each tuple using the field
   names as the associative indices.
d894 2
d897 1
a897 3
	set DB "mydb"
	set conn [pg_connect $DB]
	pg_select $conn "SELECT * from table" array {
a899 1
	pg_disconnect $conn
d908 1
a908 1
<REFENTRY ID="PGTCL-PGRESULT">
d910 2
a911 2
<REFENTRYTITLE>pg_result</REFENTRYTITLE>
<REFMISCINFO>PGTCL - Connection Management</REFMISCINFO>
d914 1
a914 1
<REFNAME>pg_result
d916 1
a916 2
<REFPURPOSE>
get information about a query result
d918 2
a919 2
<INDEXTERM ID="IX-PGTCL-PGRESULT-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>connecting</SECONDARY></INDEXTERM>
<INDEXTERM ID="IX-PGTCL-PGRESULT-2"><PRIMARY>pg_connect</PRIMARY></INDEXTERM>
d923 1
a923 1
<DATE>1997-12-24</DATE>
d926 1
a926 1
pg_result <REPLACEABLE CLASS="PARAMETER">queryHandle</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">resultOption</REPLACEABLE>
d928 2
a929 1
<REFSECT2 ID="R2-PGTCL-PGRESULT-1">
d931 1
a931 1
<DATE>1997-12-24</DATE>
d938 1
a938 1
  <REPLACEABLE CLASS="PARAMETER">queryHandle</REPLACEABLE>
d941 1
a941 2
<PARA>
  The handle for a query result.
d947 1
a947 1
  <REPLACEABLE CLASS="PARAMETER">resultOption</REPLACEABLE>
d950 1
a950 2
<PARA>
Specifies one of several possible options.
a953 6
</VARIABLELIST>

<REFSECT3>
<TITLE>Options</TITLE>

<VARIABLELIST>
d956 1
a956 1
-status  
d959 2
a960 85
<PARA>
the status of the result.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
-oid
</TERM>
<LISTITEM>
<PARA>
if the last query was an insert, returns the oid of the 
inserted tuple
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
-conn
</TERM>
<LISTITEM>
<PARA>
the connection that produced the result
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
-assign arrayName
</TERM>
<LISTITEM>
<PARA>
assign the results to an array
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
-assignbyidx arrayName ?appendstr?
</TERM>
<LISTITEM>
<PARA>
assign the results to an array using the first field as a key
and optionally append appendstr to the key name. Useful for
creating pseudo-multi dimensional arrays in tcl.
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
-numTuples
</TERM>
<LISTITEM>
<PARA>
the number of tuples in the query
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
-attributes
</TERM>
<LISTITEM>
<PARA>
returns a list of the name/type pairs of the tuple attributes
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
-getTuple tupleNumber
</TERM>
<LISTITEM>
<PARA>
returns the values of the tuple in a list
</PARA>
</LISTITEM>
</VARLISTENTRY>
<VARLISTENTRY>
<TERM>
-clear 
</TERM>
<LISTITEM>
<PARA>
clear the result buffer. Do not reuse after this
a964 1
</REFSECT3>
d967 1
a967 1
<REFSECT2 ID="R2-PGTCL-PGRESULT-2">
d969 1
a969 1
<DATE>1997-12-24</DATE>
d976 1
a976 1
  <REPLACEABLE CLASS="PARAMETER">queryHandle</REPLACEABLE>
a979 1
   the return result is either an error message or a handle for a query result.
d984 2
a985 1
</REFSECT2></REFSYNOPSISDIV>
d987 1
a987 1
<REFSECT1 ID="R1-PGTCL-PGRESULT-1">
d989 1
a989 1
<DATE>1997-12-24</DATE>
d993 25
a1017 2
<PARA>
<FUNCTION>pg_result</FUNCTION> returns information about a query.
d1020 1
@


1.4
log
@Add port information for NS32532.
Fix Id tag in chapter headings to allow meaningful file names in html.
@
text
@d151 1
a151 1
<REFENTRY ID="PGTCL-PGCONNECT-1">
d269 1
a269 1
<REFENTRY ID="PGTCL-PGDISCONNECT-1">
d341 1
a341 1
<REFENTRY ID="PGTCL-PGEXEC-1">
d427 1
a427 1
<REFENTRY ID="PGTCL-PGLISTEN-1">
d538 1
a538 1
<REFENTRY ID="PGTCL-PGSELECT-1">
d665 1
a665 1
<REFENTRY ID="PGTCL-PGRESULT-1">
d850 1
a850 1
<REFENTRY ID="PGTCL-PGLOCREAT-1">
d943 1
a943 1
<REFENTRY ID="PGTCL-PGLOOPEN-1">
d1041 1
a1041 1
<REFENTRY ID="PGTCL-PGLOCLOSE-1">
d1120 1
a1120 1
<REFENTRY ID="PGTCL-PGLOREAD-1">
d1219 1
a1219 1
<REFENTRY ID="PGTCL-PGLOWRITE-1">
d1319 1
a1319 1
<REFENTRY ID="PGTCL-PGLOLSEEK-1">
d1418 1
a1418 1
<REFENTRY ID="PGTCL-PGLOTELL-1">
d1508 1
a1508 1
<REFENTRY ID="PGTCL-PGLOUNLINK-1">
d1590 1
a1590 1
<REFENTRY ID="PGTCL-PGLOIMPORT-1">
d1673 1
a1673 1
<REFENTRY ID="PGTCL-PGLOEXPORT-1">
@


1.3
log
@The attached patch modifies libpgtcl per previous discussion:  the
pg_notifies statement is eliminated, and callbacks defined by
pg_listen are instead invoked automatically from the Tcl idle loop
whenever a NOTIFY message is received.

I have done only cursory testing, so there may be problems still
lurking (particularly on non-Unix machines?).  But it seems to
work.

Patch is against today's cvs sources.  Note that this will not work
with the 6.3.2 release since it depends on the new libpq.

The diffs are a bit large so I've gzipped them.  A patch to update
libpgtcl.sgml is included too.

			regards, tom lane
@
text
@d1 1
a1 1
<Chapter>
d519 2
@


1.2
log
@|I noticed that the -assignbyidx function of -result in libpgtcl
is not |documented, here is the relevant patch for it

Anton
@
text
@d6 2
a7 5
backends.    pgtcl does not use the libpq library but communicates to
the backend directly via the frontend-backend protocol.  Thus, it is
more efficient than previous postgres->tcl bindings which are layered
on top of libpq.  In addition, pgtcl can handle multiple backend
connections from a single frontend application.
d43 4
d51 4
d59 2
a60 2
    <ENTRY>pg_result</ENTRY>
    <ENTRY>manipulate the results of a query</ENTRY>
d109 1
a109 2
Some commands equivalent to libpq commands are provided for connection
and query operations.
d149 1
a149 1
<Title>Reference Information</Title>
d242 1
a242 1
   connection.  Handles start with the prefix "pgp"
d421 108
a528 1
  Handles start with the prefix "pgp".
@


1.1
log
@SGML source for new documentation.
@
text
@d649 12
@
