+++ /dev/null
-<!--
-$PostgreSQL: pgsql/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>
projects / postgresql / commitdiff