libpgtcl.sgml

PostgreSQL7.4.6 for Linux

   <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