mirror of
https://github.com/postgres/postgres.git
synced 2025-08-30 06:01:21 +03:00
1946 lines
48 KiB
Plaintext
1946 lines
48 KiB
Plaintext
<!--
|
|
$PostgreSQL: pgsql/doc/src/sgml/libpgtcl.sgml,v 1.40 2003/11/29 19:51:37 pgsql 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>
|