diff options
Diffstat (limited to 'doc/src/sgml/libpgtcl.sgml')
| -rw-r--r-- | doc/src/sgml/libpgtcl.sgml | 4124 |
1 files changed, 1853 insertions, 2271 deletions
diff --git a/doc/src/sgml/libpgtcl.sgml b/doc/src/sgml/libpgtcl.sgml index 7c216dd6733..220a7d42be2 100644 --- a/doc/src/sgml/libpgtcl.sgml +++ b/doc/src/sgml/libpgtcl.sgml @@ -6,11 +6,12 @@ </indexterm> <indexterm zone="pgtcl"> - <primary>Tcl</primary> + <primary>pgtcl</primary> </indexterm> - <sect1 id="pgtcl-intro"> - <title>Introduction</title> + <indexterm zone="pgtcl"> + <primary>Tcl</primary> + </indexterm> <para> <application>pgtcl</application> is a Tcl package for client @@ -19,9 +20,8 @@ <application>libpq</application> available to Tcl scripts. </para> - <para> - This package was originally written by Jolly Chen. - </para> + <sect1 id="pgtcl-overview"> + <title>Overview</title> <para> <xref linkend="pgtcl-commands-table"> gives an overview over the @@ -30,105 +30,107 @@ </para> -<TABLE TOCENTRY="1" id="pgtcl-commands-table"> -<TITLE><literal>pgtcl</literal> Commands</TITLE> -<TGROUP COLS="2"> -<THEAD> - <ROW> - <ENTRY>Command</ENTRY> - <ENTRY>Description</ENTRY> - </ROW> -</THEAD> -<TBODY> - <ROW> - <ENTRY><function>pg_connect</function></ENTRY> - <ENTRY>opens a connection to the backend server</ENTRY> - </ROW> - <ROW> - <ENTRY><function>pg_disconnect</function></ENTRY> - <ENTRY>closes a connection</ENTRY> - </ROW> - <ROW> - <ENTRY><function>pg_conndefaults</function></ENTRY> - <ENTRY>get connection options and their defaults</ENTRY> - </ROW> - <ROW> - <ENTRY><function>pg_exec</function></ENTRY> - <ENTRY>send a query to the backend</ENTRY> - </ROW> - <ROW> - <ENTRY><function>pg_result</function></ENTRY> - <ENTRY>manipulate the results of a query</ENTRY> - </ROW> - <ROW> - <ENTRY><function>pg_select</function></ENTRY> - <ENTRY>loop over the result of a SELECT statement</ENTRY> - </ROW> - <ROW> - <ENTRY><function>pg_execute</function></ENTRY> - <ENTRY>send a query and optionally loop over the results</ENTRY> - </ROW> - <ROW> - <ENTRY><function>pg_listen</function></ENTRY> - <ENTRY>establish a callback for NOTIFY messages</ENTRY> - </ROW> - <ROW> - <ENTRY><function>pg_on_connection_loss</function></ENTRY> - <ENTRY>establish a callback for unexpected connection loss</ENTRY> - </ROW> - - <ROW> - <ENTRY><function>pg_lo_creat</function></ENTRY> - <ENTRY>create a large object</ENTRY> - </ROW> - <ROW> - <ENTRY><function>pg_lo_open</function></ENTRY> - <ENTRY>open a large object</ENTRY> - </ROW> - <ROW> - <ENTRY><function>pg_lo_close</function></ENTRY> - <ENTRY>close a large object</ENTRY> - </ROW> - <ROW> - <ENTRY><function>pg_lo_read</function></ENTRY> - <ENTRY>read a large object</ENTRY> - </ROW> - <ROW> - <ENTRY><function>pg_lo_write</function></ENTRY> - <ENTRY>write a large object</ENTRY> - </ROW> - <ROW> - <ENTRY><function>pg_lo_lseek</function></ENTRY> - <ENTRY>seek to a position in a large object</ENTRY> - </ROW> - <ROW> - <ENTRY><function>pg_lo_tell</function></ENTRY> - <ENTRY>return the current seek position of a large object</ENTRY> - </ROW> - <ROW> - <ENTRY><function>pg_lo_unlink</function></ENTRY> - <ENTRY>delete a large object</ENTRY> - </ROW> - <ROW> - <ENTRY><function>pg_lo_import</function></ENTRY> - <ENTRY>import a Unix file into a large object</ENTRY> - </ROW> - <ROW> - <ENTRY><function>pg_lo_export</function></ENTRY> - <ENTRY>export a large object into a Unix file</ENTRY> - </ROW> -</TBODY> -</TGROUP> -</TABLE> +<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> routines are interfaces to the - large object features of <ProductName>PostgreSQL</ProductName>. - The functions are designed to mimic the analogous file system - functions in the standard Unix file system interface. The - <function>pg_lo_*</function> routines should be used within a + The <function>pg_lo_*</function> commands are interfaces to the + large object features of + <ProductName>PostgreSQL</ProductName>.<indexterm><primary>Large + Object</></> 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 file descriptor returned by + 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 @@ -136,41 +138,14 @@ block. </para> - <para> - <xref linkend="pgtcl-example"> shows a small example of how to use - the routines. - </para> - - <example id="pgtcl-example"> - <title><application>pgtcl</application> Example Program</title> - -<programlisting> -# getDBs : -# get the names of all the databases at a given host and port number -# with the defaults being the localhost and port 5432 -# return them in alphabetical order -proc getDBs { {host "localhost"} {port "5432"} } { - # datnames is the list to be result - set conn [pg_connect template1 -host $host -port $port] - set res [pg_exec $conn "SELECT datname FROM pg_database ORDER BY datname"] - set ntups [pg_result $res -numTuples] - for {set i 0} {$i < $ntups} {incr i} { - lappend datnames [pg_result $res -getTuple $i] - } - pg_result $res -clear - pg_disconnect $conn - return $datnames -} -</programlisting> - </example> </sect1> -<Sect1 id="libpgtcl-loading"> -<Title>Loading <application>pgtcl</application> into your application</Title> +<sect1 id="libpgtcl-loading"> +<title>Loading <application>pgtcl</application> into an Application</title> <para> Before using <application>pgtcl</application> commands, you must load - <filename>libpgtcl</> into your Tcl application. This is normally + the <filename>libpgtcl</> library into your Tcl application. This is normally done with the Tcl <literal>load</> command. Here is an example: <programlisting> @@ -207,2147 +182,1754 @@ load libpgtcl[info sharedlibextension] linking. See the source code for <application>pgtclsh</> for an example. </para> -</Sect1> - -<Sect1 id="libpgtcl-ref"> -<Title><application>pgtcl</application> Command Reference Information</Title> - -<REFENTRY ID="PGTCL-PGCONNECT"> -<REFMETA> -<REFENTRYTITLE>pg_connect</REFENTRYTITLE> -<REFMISCINFO>PGTCL - Connection Management</REFMISCINFO> -</REFMETA> -<REFNAMEDIV> -<REFNAME>pg_connect -</REFNAME> -<REFPURPOSE>open a connection to the backend server -</REFPURPOSE> -<INDEXTERM ID="IX-PGTCL-PGCONNECT-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>connecting</SECONDARY></INDEXTERM> -<INDEXTERM ID="IX-PGTCL-PGCONNECT-2"><PRIMARY>pg_connect</PRIMARY></INDEXTERM> -</REFNAMEDIV> -<REFSYNOPSISDIV> -<REFSYNOPSISDIVINFO> -<DATE>1997-12-24</DATE> -</REFSYNOPSISDIVINFO> -<SYNOPSIS> -pg_connect -conninfo <REPLACEABLE CLASS="PARAMETER">connectOptions</REPLACEABLE> -pg_connect <REPLACEABLE CLASS="PARAMETER">dbName</REPLACEABLE> <OPTIONAL>-host <REPLACEABLE CLASS="PARAMETER">hostName</REPLACEABLE></OPTIONAL> - <OPTIONAL>-port <REPLACEABLE - CLASS="PARAMETER">portNumber</REPLACEABLE></OPTIONAL> <OPTIONAL>-tty <REPLACEABLE - CLASS="PARAMETER">pqtty</REPLACEABLE></OPTIONAL> - <OPTIONAL>-options <REPLACEABLE - CLASS="PARAMETER">optionalBackendArgs</REPLACEABLE></OPTIONAL> -</SYNOPSIS> - -<REFSECT2 ID="R2-PGTCL-PGCONNECT-1"> -<REFSECT2INFO> -<DATE>1998-10-07</DATE> -</REFSECT2INFO> -<TITLE>Inputs (new style) -</TITLE> -<VARIABLELIST> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">connectOptions</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA>A string of connection options, each written in the form keyword = value. -A list of valid options can be found in <filename>libpq</>'s -<function>PQconnectdb()</> manual entry. -</PARA> -</LISTITEM> -</VARLISTENTRY> -</VARIABLELIST> -</REFSECT2> - -<REFSECT2 ID="R2-PGTCL-PGCONNECT-2"> -<REFSECT2INFO> -<DATE>1997-12-24</DATE> -</REFSECT2INFO> -<TITLE>Inputs (old style) -</TITLE> -<VARIABLELIST> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">dbName</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA>Specifies a valid database name. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> - <OPTIONAL>-host <REPLACEABLE CLASS="PARAMETER">hostName</REPLACEABLE></OPTIONAL> -</TERM> -<LISTITEM> -<PARA>Specifies the domain name of the backend server for <REPLACEABLE CLASS="PARAMETER">dbName</REPLACEABLE>. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> - <OPTIONAL>-port <REPLACEABLE CLASS="PARAMETER">portNumber</REPLACEABLE></OPTIONAL> -</TERM> -<LISTITEM> -<PARA>Specifies the IP port number of the backend server for <REPLACEABLE CLASS="PARAMETER">dbName</REPLACEABLE>. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> - <OPTIONAL>-tty <REPLACEABLE CLASS="PARAMETER">pqtty</REPLACEABLE></OPTIONAL> -</TERM> -<LISTITEM> -<PARA>Specifies file or <acronym>tty</acronym> for optional debug output from backend. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> - <OPTIONAL>-options <REPLACEABLE CLASS="PARAMETER">optionalBackendArgs</REPLACEABLE></OPTIONAL> -</TERM> -<LISTITEM> -<PARA>Specifies options for the backend server for <REPLACEABLE CLASS="PARAMETER">dbName</REPLACEABLE>. -</PARA> -</LISTITEM> -</VARLISTENTRY> -</VARIABLELIST> -</REFSECT2> - -<REFSECT2 ID="R2-PGTCL-PGCONNECT-3"> -<REFSECT2INFO> -<DATE>1997-12-24</DATE> -</REFSECT2INFO> -<TITLE>Outputs -</TITLE> -<VARIABLELIST> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA> -If successful, a handle for a database connection is returned. -Handles start with the prefix <literal>pgsql</literal>. -</PARA> -</LISTITEM> -</VARLISTENTRY> -</VARIABLELIST> -</REFSECT2> -</REFSYNOPSISDIV> - -<!-- ********************************************************** --> - -<REFSECT1 ID="R1-PGTCL-PGCONNECT-1"> -<REFSECT1INFO> -<DATE>1997-12-24</DATE> -</REFSECT1INFO> -<TITLE>Description -</TITLE> -<PARA><FUNCTION>pg_connect</FUNCTION> opens a connection to the -<ProductName>PostgreSQL</ProductName> backend. -</Para> - -<para> -Two syntaxes are available. In the older one, each possible option -has a separate option switch in the pg_connect statement. In the -newer form, a single option string is supplied that can contain -multiple option values. See <FUNCTION>pg_conndefaults</FUNCTION> -for info about the available options in the newer syntax. -</PARA> -</REFSECT1> -<REFSECT1 ID="R1-PGTCL-PGCONNECT-2"> -<TITLE>Usage -</TITLE> -<comment> - XXX thomas 1997-12-24 -</comment> -</REFSECT1> -</REFENTRY> - -<REFENTRY ID="PGTCL-PGDISCONNECT"> -<REFMETA> -<REFENTRYTITLE>pg_disconnect</REFENTRYTITLE> -<REFMISCINFO>PGTCL - Connection Management</REFMISCINFO> -</REFMETA> -<REFNAMEDIV> -<REFNAME>pg_disconnect -</REFNAME> -<REFPURPOSE>close a connection to the backend server -</REFPURPOSE> -<INDEXTERM ID="IX-PGTCL-PGDISCONNECT-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>connecting</SECONDARY></INDEXTERM> -<INDEXTERM ID="IX-PGTCL-PGDISCONNECT-2"><PRIMARY>pg_connect</PRIMARY></INDEXTERM> -</REFNAMEDIV> -<REFSYNOPSISDIV> -<REFSYNOPSISDIVINFO> -<DATE>1997-12-24</DATE> -</REFSYNOPSISDIVINFO> -<SYNOPSIS> -pg_disconnect <REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE> -</SYNOPSIS> - -<REFSECT2 ID="R2-PGTCL-PGDISCONNECT-1"> -<REFSECT2INFO> -<DATE>1997-12-24</DATE> -</REFSECT2INFO> -<TITLE>Inputs -</TITLE> -<VARIABLELIST> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA>Specifies a valid database handle. -</PARA> -</LISTITEM> -</VARLISTENTRY> -</VARIABLELIST> -</REFSECT2> - -<REFSECT2 ID="R2-PGTCL-PGDISCONNECT-2"> -<REFSECT2INFO> -<DATE>1997-12-24</DATE> -</REFSECT2INFO> -<TITLE>Outputs -</TITLE> -<VARIABLELIST> -<VARLISTENTRY> -<TERM> - None -</TERM> -<LISTITEM> -<PARA> -</PARA> -</LISTITEM> -</VARLISTENTRY> -</VARIABLELIST> -</REFSECT2> -</REFSYNOPSISDIV> - -<REFSECT1 ID="R1-PGTCL-PGDISCONNECT-1"> -<REFSECT1INFO> -<DATE>1997-12-24</DATE> -</REFSECT1INFO> -<TITLE>Description -</TITLE> -<PARA><FUNCTION>pg_disconnect</FUNCTION> closes a connection to the <ProductName>PostgreSQL</ProductName> backend. -</PARA> -</REFSECT1> - -</REFENTRY> - - - - -<REFENTRY ID="PGTCL-PGCONNDEFAULTS"> -<REFMETA> -<REFENTRYTITLE>pg_conndefaults</REFENTRYTITLE> -<REFMISCINFO>PGTCL - Connection Management</REFMISCINFO> -</REFMETA> -<REFNAMEDIV> -<REFNAME>pg_conndefaults -</REFNAME> -<REFPURPOSE>obtain information about default connection parameters -</REFPURPOSE> -<INDEXTERM ID="IX-PGTCL-PGCONNDEFAULTS-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>connecting</SECONDARY></INDEXTERM> -<INDEXTERM ID="IX-PGTCL-PGCONNDEFAULTS-2"><PRIMARY>pg_conndefaults</PRIMARY></INDEXTERM> -</REFNAMEDIV> -<REFSYNOPSISDIV> -<REFSYNOPSISDIVINFO> -<DATE>1998-10-07</DATE> -</REFSYNOPSISDIVINFO> -<SYNOPSIS> +</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>-host <parameter>hostName</parameter></optional> <optional>-port <parameter>portNumber</parameter></optional> <optional>-tty <parameter>tty</parameter</optional> <optional>-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> - -<REFSECT2 ID="R2-PGTCL-PGCONNDEFAULTS-1"> -<REFSECT2INFO> -<DATE>1998-10-07</DATE> -</REFSECT2INFO> -<TITLE>Inputs -</TITLE> -<PARA> -None. -</PARA> -</REFSECT2> - -<REFSECT2 ID="R2-PGTCL-PGCONNDEFAULTS-2"> -<REFSECT2INFO> -<DATE>1998-10-07</DATE> -</REFSECT2INFO> -<TITLE>Outputs -</TITLE> -<VARIABLELIST> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">option list</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA> -The result is a list describing the possible connection options and their -current default values. -Each entry in the list is a sublist of the format: -</Para> -<screen> +</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} -</screen> -<Para> -where the <replaceable>optname</> is usable as an option in -<FUNCTION>pg_connect -conninfo</FUNCTION>. -</PARA> -</LISTITEM> -</VARLISTENTRY> -</VARIABLELIST> -</REFSECT2> -</REFSYNOPSISDIV> - -<REFSECT1 ID="R1-PGTCL-PGCONNDEFAULTS-1"> -<REFSECT1INFO> -<DATE>1998-10-07</DATE> -</REFSECT1INFO> -<TITLE>Description -</TITLE> - -<para> -<FUNCTION>pg_conndefaults</FUNCTION> returns info about the connection -options available in <FUNCTION>pg_connect -conninfo</FUNCTION> and the -current default value for each option. -</PARA> -</REFSECT1> -<REFSECT1 ID="R1-PGTCL-PGCONNDEFAULTS-2"> -<TITLE>Usage -</TITLE> -<PARA><literal>pg_conndefaults</> -</PARA> -</REFSECT1> -</REFENTRY> - -<REFENTRY ID="PGTCL-PGEXEC"> -<REFMETA> -<REFENTRYTITLE>pg_exec</REFENTRYTITLE> -<REFMISCINFO>PGTCL - Query Processing</REFMISCINFO> -</REFMETA> -<REFNAMEDIV> -<REFNAME>pg_exec -</REFNAME> -<REFPURPOSE> -send a command string to the server -</REFPURPOSE> -<INDEXTERM ID="IX-PGTCL-PGEXEC-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>connecting</SECONDARY></INDEXTERM> -<INDEXTERM ID="IX-PGTCL-PGEXEC-2"><PRIMARY>pg_connect</PRIMARY></INDEXTERM> -</REFNAMEDIV> -<REFSYNOPSISDIV> -<REFSYNOPSISDIVINFO> -<DATE>1997-12-24</DATE> -</REFSYNOPSISDIVINFO> -<SYNOPSIS> -pg_exec <REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">queryString</REPLACEABLE> -</SYNOPSIS> - -<!-- ********************************************************** --> - -<REFSECT2 ID="R2-PGTCL-PGEXEC-1"> -<REFSECT2INFO> -<DATE>1997-12-24</DATE> -</REFSECT2INFO> -<TITLE>Inputs -</TITLE> -<VARIABLELIST> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA>Specifies a valid database handle. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">queryString</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA>Specifies a valid SQL query. -</PARA> -</LISTITEM> -</VARLISTENTRY> -</VARIABLELIST> -</REFSECT2> - -<REFSECT2 ID="R2-PGTCL-PGEXEC-2"> -<REFSECT2INFO> -<DATE>1997-12-24</DATE> -</REFSECT2INFO> -<TITLE>Outputs -</TITLE> -<VARIABLELIST> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">resultHandle</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA> -A Tcl error will be returned if <application>pgtcl</application> was unable to obtain a backend -response. Otherwise, a query result object is created and a handle for -it is returned. This handle can be passed to <FUNCTION>pg_result</FUNCTION> -to obtain the results of the query. -</PARA> -</LISTITEM> -</VARLISTENTRY> -</VARIABLELIST> -</REFSECT2></REFSYNOPSISDIV> - -<REFSECT1 ID="R1-PGTCL-PGEXEC-1"> -<REFSECT1INFO> -<DATE>1997-12-24</DATE> -</REFSECT1INFO> -<TITLE>Description -</TITLE> -<PARA> -<FUNCTION>pg_exec</FUNCTION> submits a query to the <ProductName>PostgreSQL</ProductName> backend and returns a result. - -Query result handles start with the connection handle and add a period -and a result number. -</Para> - -<PARA> -Note that lack of a Tcl error is not proof that the query succeeded! -An error message returned by the backend will be processed -as a query result with failure status, not by generating a Tcl error -in pg_exec. -</PARA> -</REFSECT1> +</synopsis> + where the <replaceable>optname</> is usable as an option in + <function>pg_connect -conninfo</function>. + </para> + </refsect1> </refentry> -<REFENTRY ID="PGTCL-PGRESULT"> -<REFMETA> -<REFENTRYTITLE>pg_result</REFENTRYTITLE> -<REFMISCINFO>PGTCL - Query Processing</REFMISCINFO> -</REFMETA> -<REFNAMEDIV> -<REFNAME>pg_result -</REFNAME> -<REFPURPOSE> -get information about a query result -</REFPURPOSE> -<INDEXTERM ID="IX-PGTCL-PGRESULT-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>connecting</SECONDARY></INDEXTERM> -<INDEXTERM ID="IX-PGTCL-PGRESULT-2"><PRIMARY>pg_connect</PRIMARY></INDEXTERM> -</REFNAMEDIV> -<REFSYNOPSISDIV> -<REFSYNOPSISDIVINFO> -<DATE>1997-12-24</DATE> -</REFSYNOPSISDIVINFO> -<SYNOPSIS> -pg_result <REPLACEABLE CLASS="PARAMETER">resultHandle</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">resultOption</REPLACEABLE> -</SYNOPSIS> -<REFSECT2 ID="R2-PGTCL-PGRESULT-1"> -<REFSECT2INFO> -<DATE>1997-12-24</DATE> -</REFSECT2INFO> -<TITLE>Inputs -</TITLE> -<VARIABLELIST> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">resultHandle</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA> - The handle for a query result. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">resultOption</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA> -Specifies one of several possible options. -</PARA> -</LISTITEM> -</VARLISTENTRY> -</VARIABLELIST> - -<REFSECT3> -<TITLE>Options</TITLE> - -<VARIABLELIST> -<VARLISTENTRY> -<TERM> -<option>-status</option> -</TERM> -<LISTITEM> -<PARA> -the status of the result. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> -<option>-error</option> -</TERM> -<LISTITEM> -<PARA> -the error message, if the status indicates error; otherwise an empty string. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> -<option>-conn</option> -</TERM> -<LISTITEM> -<PARA> -the connection that produced the result. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> -<option>-oid</option> -</TERM> -<LISTITEM> -<PARA> -if the command was an INSERT, the OID of the -inserted tuple; otherwise 0. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> -<option>-numTuples</option> -</TERM> -<LISTITEM> -<PARA> -the number of tuples returned by the query. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> -<option>-cmdTuples</option> -</TERM> -<LISTITEM> -<PARA> -the number of tuples affected by the query. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> -<option>-numAttrs</option> -</TERM> -<LISTITEM> -<PARA> -the number of attributes in each tuple. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> -<option>-assign arrayName</option> -</TERM> -<LISTITEM> -<PARA> -assign the results to an array, using subscripts of the form -<literal>(tupno,attributeName)</literal>. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> -<option>-assignbyidx arrayName ?appendstr?</option> -</TERM> -<LISTITEM> -<PARA> -assign the results to an array using the first attribute's value and -the remaining attributes' names as keys. If <parameter>appendstr</> is given then -it is appended to each key. In short, all but the first field of each -tuple are stored into the array, using subscripts of the form -<literal>(firstFieldValue,fieldNameAppendStr)</literal>. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> -<option>-getTuple tupleNumber</option> -</TERM> -<LISTITEM> -<PARA> -returns the fields of the indicated tuple in a list. Tuple numbers -start at zero. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> -<option>-tupleArray tupleNumber arrayName</option> -</TERM> -<LISTITEM> -<PARA> -stores the fields of the tuple in array <parameter>arrayName</parameter>, indexed by field names. -Tuple numbers start at zero. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> -<option>-attributes</option> -</TERM> -<LISTITEM> -<PARA> -returns a list of the names of the tuple attributes. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> -<option>-lAttributes</option> -</TERM> -<LISTITEM> -<PARA> -returns a list of sublists, <literal>{name ftype fsize}</literal> for each tuple attribute. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> -<option>-clear</option> -</TERM> -<LISTITEM> -<PARA> -clear the result query object. -</PARA> -</LISTITEM> -</VARLISTENTRY> -</VARIABLELIST> -</REFSECT3> -</REFSECT2> - -<REFSECT2 ID="R2-PGTCL-PGRESULT-2"> -<REFSECT2INFO> -<DATE>1997-12-24</DATE> -</REFSECT2INFO> -<TITLE>Outputs -</TITLE> -<PARA> -The result depends on the selected option, as described above. -</PARA> -</REFSECT2></REFSYNOPSISDIV> - -<REFSECT1 ID="R1-PGTCL-PGRESULT-1"> -<REFSECT1INFO> -<DATE>1997-12-24</DATE> -</REFSECT1INFO> -<TITLE>Description -</TITLE> -<PARA> -<FUNCTION>pg_result</FUNCTION> returns information about a query result -created by a prior <FUNCTION>pg_exec</FUNCTION>. -</Para> - -<para> -You can keep a query result around for as long as you need it, but when -you are done with it, be sure to free it by -executing <FUNCTION>pg_result -clear</FUNCTION>. Otherwise, you have -a memory leak, and <application>Pgtcl</> will eventually start complaining that you've -created too many query result objects. -</PARA> -</REFSECT1> -</REFENTRY> - -<!-- ********************************************************** --> - -<REFENTRY ID="PGTCL-PGSELECT"> -<REFMETA> -<REFENTRYTITLE>pg_select</REFENTRYTITLE> -<REFMISCINFO>PGTCL - Query Processing</REFMISCINFO> -</REFMETA> -<REFNAMEDIV> -<REFNAME>pg_select -</REFNAME> -<REFPURPOSE> -loop over the result of a SELECT statement -</REFPURPOSE> -<INDEXTERM ID="IX-PGTCL-PGSELECT-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>connecting</SECONDARY></INDEXTERM> -<INDEXTERM ID="IX-PGTCL-PGSELECT-2"><PRIMARY>pg_connect</PRIMARY></INDEXTERM> -</REFNAMEDIV> -<REFSYNOPSISDIV> -<REFSYNOPSISDIVINFO> -<DATE>1997-12-24</DATE> -</REFSYNOPSISDIVINFO> -<SYNOPSIS> -pg_select <REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">queryString</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">arrayVar</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">queryProcedure</REPLACEABLE> -</SYNOPSIS> - -<REFSECT2 ID="R2-PGTCL-PGSELECT-1"> -<REFSECT2INFO> -<DATE>1997-12-24</DATE> -</REFSECT2INFO> -<TITLE>Inputs -</TITLE> -<VARIABLELIST> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA>Specifies a valid database handle. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">queryString</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA>Specifies a valid SQL select query. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">arrayVar</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA>Array variable for tuples returned. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">queryProcedure</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA>Procedure run on each tuple found. -</PARA> -</LISTITEM> -</VARLISTENTRY> -</VARIABLELIST> - -</REFSECT2> - -<REFSECT2 ID="R2-PGTCL-PGSELECT-2"> -<REFSECT2INFO> -<DATE>1997-12-24</DATE> -</REFSECT2INFO> -<TITLE>Outputs -</TITLE> -<Para> -None. -</Para> -</REFSECT2></REFSYNOPSISDIV> - -<REFSECT1 ID="R1-PGTCL-PGSELECT-1"> -<REFSECT1INFO> -<DATE>1997-12-24</DATE> -</REFSECT1INFO> -<TITLE>Description -</TITLE> -<PARA> -<FUNCTION>pg_select</FUNCTION> submits a SELECT query to the -<ProductName>PostgreSQL</ProductName> backend, and executes a -given chunk of code for each tuple in the result. - The <REPLACEABLE CLASS="PARAMETER">queryString</REPLACEABLE> - must be a SELECT statement. Anything else returns an error. - The <REPLACEABLE CLASS="PARAMETER">arrayVar</REPLACEABLE> - variable is an array name used in the loop. For each tuple, - <REPLACEABLE CLASS="PARAMETER">arrayVar</REPLACEABLE> is filled in - with the tuple field values, using the field names as the array - indexes. Then the - <REPLACEABLE CLASS="PARAMETER">queryProcedure</REPLACEABLE> - is executed. -</PARA> - -<PARA> - In addition to the field values, the following special entries are -made in the array: - -<VARIABLELIST> -<VARLISTENTRY> -<TERM><literal>.headers</></TERM> -<LISTITEM> -<PARA>A list of the column names returned by the SELECT. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM><literal>.numcols</></TERM> -<LISTITEM> -<PARA>The number of columns returned by the SELECT. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM><literal>.tupno</></TERM> -<LISTITEM> -<PARA>The current tuple number, starting at zero and incrementing -for each iteration of the loop body. -</PARA> -</LISTITEM> -</VARLISTENTRY> -</VARIABLELIST> -</PARA> - -</REFSECT1> - -<REFSECT1 ID="R1-PGTCL-PGSELECT-2"> -<TITLE>Usage -</TITLE> -<PARA> -This would work if table <classname>table</> has fields <structfield>control</> and <structfield>name</> -(and, perhaps, other fields): -<ProgramListing> - pg_select $pgconn "SELECT * FROM table" array { - puts [format "%5d %s" $array(control) $array(name)] - } -</ProgramListing> -</PARA> -</REFSECT1> - -</REFENTRY> - -<!-- ********************************************************** --> - -<REFENTRY ID="PGTCL-PGEXECUTE"> -<REFMETA> -<REFENTRYTITLE>pg_execute</REFENTRYTITLE> -<REFMISCINFO>PGTCL - Query Processing</REFMISCINFO> -</REFMETA> -<REFNAMEDIV> -<REFNAME>pg_execute -</REFNAME> -<REFPURPOSE> -send a query and optionally loop over the results -</REFPURPOSE> -<INDEXTERM ID="IX-PGTCL-PGEXECUTE-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>query</SECONDARY></INDEXTERM> -<INDEXTERM ID="IX-PGTCL-PGEXECUTE-2"><PRIMARY>pg_execute</PRIMARY></INDEXTERM> -</REFNAMEDIV> -<REFSYNOPSISDIV> -<REFSYNOPSISDIVINFO> -<DATE>2002-03-06</DATE> -</REFSYNOPSISDIVINFO> -<SYNOPSIS> -pg_execute <OPTIONAL>-array <REPLACEABLE CLASS="PARAMETER">arrayVar</REPLACEABLE></OPTIONAL> <OPTIONAL>-oid <REPLACEABLE CLASS="PARAMETER">oidVar</REPLACEABLE></OPTIONAL> <REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">queryString</REPLACEABLE> <OPTIONAL><REPLACEABLE CLASS="PARAMETER">queryProcedure</REPLACEABLE></OPTIONAL> -</SYNOPSIS> - -<REFSECT2 ID="R2-PGTCL-PGEXECUTE-1"> -<REFSECT2INFO> -<DATE>2002-03-06</DATE> -</REFSECT2INFO> -<TITLE>Inputs -</TITLE> -<VARIABLELIST> -<VARLISTENTRY> -<TERM> - <OPTIONAL>-array <REPLACEABLE CLASS="PARAMETER">arrayVar</REPLACEABLE></OPTIONAL> -</TERM> -<LISTITEM> -<PARA>Specifies the name of an array variable where result tuples are stored, -indexed by the field names. -This is ignored if <replaceable class=parameter>queryString</> is not a SELECT statement. For SELECT -statements, if this option is not used, result tuples values are stored -in individual variables named according to the field names in the result. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> - <OPTIONAL>-oid <REPLACEABLE CLASS="PARAMETER">oidVar</REPLACEABLE></OPTIONAL> -</TERM> -<LISTITEM> -<PARA>Specifies the name of a variable into which the OID from an INSERT -statement will be stored. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA>Specifies a valid database handle. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">queryString</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA>Specifies a valid SQL query. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> - <OPTIONAL><REPLACEABLE CLASS="PARAMETER">queryProcedure</REPLACEABLE></OPTIONAL> -</TERM> -<LISTITEM> -<PARA>Optional command to execute for each result tuple of a SELECT statement. -</PARA> -</LISTITEM> -</VARLISTENTRY> -</VARIABLELIST> - -</REFSECT2> - -<REFSECT2 ID="R2-PGTCL-PGEXECUTE-2"> -<REFSECT2INFO> -<DATE>2002-03-06</DATE> -</REFSECT2INFO> -<TITLE>Outputs -</TITLE> -<VARIABLELIST> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">ntuples</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA> -The number of tuples affected or returned by the query. -</PARA> -</LISTITEM> -</VARLISTENTRY> -</VARIABLELIST> -</REFSECT2></REFSYNOPSISDIV> - -<REFSECT1 ID="R1-PGTCL-PGEXECUTE-1"> -<REFSECT1INFO> -<DATE>2002-03-06</DATE> -</REFSECT1INFO> -<TITLE>Description -</TITLE> -<PARA> -<FUNCTION>pg_execute</FUNCTION> submits a query to the -<PRODUCTNAME>PostgreSQL</> backend. -</PARA> -<PARA> -If the query is not a SELECT statement, the query is executed and the -number of tuples affected by the query is returned. If the query is an -INSERT and a single tuple is inserted, the OID of the inserted tuple is -stored in the <replaceable>oidVar</> variable if the optional <PARAMETER>-oid</PARAMETER> -argument is supplied. -</PARA> -<PARA> -If the query is a SELECT statement, the query is executed. For each tuple -in the result, the tuple field values are stored in the -<PARAMETER>arrayVar</PARAMETER> variable, -if supplied, using the field names as the array indexes, else in variables -named by the field names, and then the optional -<PARAMETER>queryProcedure</PARAMETER> is executed if supplied. -(Omitting the <PARAMETER>queryProcedure</PARAMETER> probably makes sense -only if the query will return a single tuple.) -The number of tuples selected is returned. -</PARA> -<PARA> -The <PARAMETER>queryProcedure</PARAMETER> can use the Tcl -<LITERAL>break</LITERAL>, <LITERAL>continue</LITERAL>, and -<LITERAL>return</LITERAL> commands, with the expected behavior. -Note that if the <PARAMETER>queryProcedure</PARAMETER> executes -<LITERAL>return</LITERAL>, <FUNCTION>pg_execute</FUNCTION> does -not return <PARAMETER>ntuples</PARAMETER>. -</PARA> -<PARA> -<FUNCTION>pg_execute</FUNCTION> is a newer function which provides a -superset of the features of <FUNCTION>pg_select</FUNCTION>, and can -replace <FUNCTION>pg_exec</FUNCTION> in many cases where access to -the result handle is not needed. -</PARA> -<PARA> -For backend-handled errors, <FUNCTION>pg_execute</FUNCTION> will -throw a Tcl error and return two element list. The first element -is an error code such as <LITERAL>PGRES_FATAL_ERROR</LITERAL>, and -the second element is the backend error text. For more serious -errors, such as failure to communicate with the backend, -<FUNCTION>pg_execute</FUNCTION> will throw a Tcl error and return -just the error message text. -</PARA> - -</REFSECT1> - -<REFSECT1 ID="R1-PGTCL-PGEXECUTE-2"> -<TITLE>Usage -</TITLE> -<PARA> -In the following examples, error checking with <LITERAL>catch</LITERAL> -has been omitted for clarity. -</PARA> -<PARA> -Insert a row and save the OID in <varname>result_oid</>: -<ProgramListing> - pg_execute -oid result_oid $pgconn "insert into mytable values (1)" -</ProgramListing> -</PARA> -<PARA> -Print the item and value fields from each row: -<ProgramListing> - pg_execute -array d $pgconn "select item, value from mytable" { - puts "Item=$d(item) Value=$d(value)" - } -</ProgramListing> -</PARA> -<PARA> -Find the maximum and minimum values and store them in $s(max) and $s(min): -<ProgramListing> - pg_execute -array s $pgconn "select max(value) as max,\ - min(value) as min from mytable" -</ProgramListing> -</PARA> -<PARA> -Find the maximum and minimum values and store them in $max and $min: -<ProgramListing> - pg_execute $pgconn "select max(value) as max, min(value) as min from mytable" -</ProgramListing> -</PARA> -</REFSECT1> - -</REFENTRY> - -<!-- ********************************************************** --> - -<REFENTRY ID="PGTCL-PGLISTEN"> -<REFMETA> -<REFENTRYTITLE>pg_listen</REFENTRYTITLE> -<REFMISCINFO>PGTCL - Asynchronous Notify</REFMISCINFO> -</REFMETA> -<REFNAMEDIV> -<REFNAME>pg_listen -</REFNAME> -<REFPURPOSE>set or change a callback for asynchronous NOTIFY messages -</REFPURPOSE> -<INDEXTERM ID="IX-PGTCL-PGLISTEN-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>notify</SECONDARY></INDEXTERM> -<INDEXTERM ID="IX-PGTCL-PGLISTEN-2"><PRIMARY>notify</PRIMARY></INDEXTERM> -</REFNAMEDIV> -<REFSYNOPSISDIV> -<REFSYNOPSISDIVINFO> -<DATE>1998-5-22</DATE> -</REFSYNOPSISDIVINFO> -<SYNOPSIS> -pg_listen <REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">notifyName</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">callbackCommand</REPLACEABLE> -</SYNOPSIS> - -<REFSECT2 ID="R2-PGTCL-PGLISTEN-1"> -<REFSECT2INFO> -<DATE>1998-5-22</DATE> -</REFSECT2INFO> -<TITLE>Inputs -</TITLE> -<VARIABLELIST> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA>Specifies a valid database handle. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">notifyName</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA>Specifies the notify condition name to start or stop listening to. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">callbackCommand</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA>If present, provides the command string to execute -when a matching notification arrives. -</PARA> -</LISTITEM> -</VARLISTENTRY> -</VARIABLELIST> -</REFSECT2> - -<REFSECT2 ID="R2-PGTCL-PGLISTEN-2"> -<REFSECT2INFO> -<DATE>1998-5-22</DATE> -</REFSECT2INFO> -<TITLE>Outputs -</TITLE> -<VARIABLELIST> -<VARLISTENTRY> -<TERM> - None -</TERM> -<LISTITEM> -<PARA> -</PARA> -</LISTITEM> -</VARLISTENTRY> -</VARIABLELIST> -</REFSECT2> -</REFSYNOPSISDIV> - -<REFSECT1 ID="R1-PGTCL-PGLISTEN-1"> -<REFSECT1INFO> -<DATE>1998-5-22</DATE> -</REFSECT1INFO> -<TITLE>Description -</TITLE> -<PARA><FUNCTION>pg_listen</FUNCTION> creates, changes, or cancels a request -to listen for asynchronous NOTIFY messages from the -<ProductName>PostgreSQL</ProductName> backend. With a <parameter>callbackCommand</> -parameter, the request is established, or the command string of an already -existing request is replaced. With no <parameter>callbackCommand</> parameter, a prior -request is canceled. -</PARA> - -<para> -After a <FUNCTION>pg_listen</FUNCTION> request is established, -the specified command string is executed whenever a NOTIFY message bearing -the given name arrives from the backend. This occurs when any -<ProductName>PostgreSQL</ProductName> client application issues a NOTIFY command -referencing that name. (Note that the name can be, but does not have to be, -that of an existing relation in the database.) -The command string is executed from the Tcl idle loop. That is the normal -idle state of an application written with Tk. In non-Tk Tcl shells, you can -execute <FUNCTION>update</FUNCTION> or <FUNCTION>vwait</FUNCTION> to cause -the idle loop to be entered. -</Para> - -<para> -You should not invoke the SQL statements <command>LISTEN</command> or <command>UNLISTEN</command> directly when -using <FUNCTION>pg_listen</FUNCTION>. <application>Pgtcl</application> takes care of issuing those -statements for you. But if you want to send a NOTIFY message yourself, -invoke the SQL NOTIFY statement using <FUNCTION>pg_exec</FUNCTION>. -</PARA> -</REFSECT1> - -</REFENTRY> - -<!-- ********************************************************** --> - -<REFENTRY ID="PGTCL-PGON-CONNECTION-LOSS"> -<REFMETA> -<REFENTRYTITLE>pg_on_connection_loss</REFENTRYTITLE> -<REFMISCINFO>PGTCL - Asynchronous Notify</REFMISCINFO> -</REFMETA> -<REFNAMEDIV> -<REFNAME>pg_on_connection_loss -</REFNAME> -<REFPURPOSE>set or change a callback for unexpected connection loss -</REFPURPOSE> -<INDEXTERM -ID="IX-PGTCL-PGON-CONNECTION-LOSS-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>connection loss</SECONDARY></INDEXTERM> -<INDEXTERM ID="IX-PGTCL-PGON-CONNECTION-LOSS-2"><PRIMARY>connection loss</PRIMARY></INDEXTERM> -</REFNAMEDIV> -<REFSYNOPSISDIV> -<REFSYNOPSISDIVINFO> -<DATE>2002-09-02</DATE> -</REFSYNOPSISDIVINFO> -<SYNOPSIS> -pg_on_connection_loss <REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">callbackCommand</REPLACEABLE> -</SYNOPSIS> - -<REFSECT2 ID="R2-PGTCL-PGON-CONNECTION-LOSS-1"> -<REFSECT2INFO> -<DATE>2002-09-02</DATE> -</REFSECT2INFO> -<TITLE>Inputs -</TITLE> -<VARIABLELIST> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">dbHandle</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA>Specifies a valid database handle. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">callbackCommand</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA>If present, provides the command string to execute -when connection loss is detected. -</PARA> -</LISTITEM> -</VARLISTENTRY> -</VARIABLELIST> -</REFSECT2> - -<REFSECT2 ID="R2-PGTCL-PGON-CONNECTION-LOSS-2"> -<REFSECT2INFO> -<DATE>2002-09-02</DATE> -</REFSECT2INFO> -<TITLE>Outputs -</TITLE> -<VARIABLELIST> -<VARLISTENTRY> -<TERM> - None -</TERM> -<LISTITEM> -<PARA> -</PARA> -</LISTITEM> -</VARLISTENTRY> -</VARIABLELIST> -</REFSECT2> -</REFSYNOPSISDIV> - -<REFSECT1 ID="R1-PGTCL-PGON-CONNECTION-LOSS-1"> -<REFSECT1INFO> -<DATE>2002-09-02</DATE> -</REFSECT1INFO> -<TITLE>Description -</TITLE> -<PARA><FUNCTION>pg_on_connection_loss</FUNCTION> creates, changes, or cancels -a request to execute a callback command if an unexpected loss of connection -to the database occurs. -With a <parameter>callbackCommand</> -parameter, the request is established, or the command string of an already -existing request is replaced. With no <parameter>callbackCommand</> -parameter, a prior request is canceled. -</PARA> - -<para> -The callback command string is executed from the Tcl idle loop. That is the -normal idle state of an application written with Tk. In non-Tk Tcl shells, -you can -execute <FUNCTION>update</FUNCTION> or <FUNCTION>vwait</FUNCTION> to cause -the idle loop to be entered. -</Para> -</REFSECT1> - -</REFENTRY> - -<!-- ********************************************************** --> - -<REFENTRY ID="PGTCL-PGLOCREAT"> -<REFMETA> -<REFENTRYTITLE>pg_lo_creat</REFENTRYTITLE> -<REFMISCINFO>PGTCL - Large Objects</REFMISCINFO> -</REFMETA> -<REFNAMEDIV> -<REFNAME>pg_lo_creat -</REFNAME> -<REFPURPOSE>create a large object -</REFPURPOSE> -<INDEXTERM ID="IX-PGTCL-PGLOCREAT-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>creating</SECONDARY></INDEXTERM> -<INDEXTERM ID="IX-PGTCL-PGLOCREAT-2"><PRIMARY>pg_lo_creat</PRIMARY></INDEXTERM> -</REFNAMEDIV> -<REFSYNOPSISDIV> -<REFSYNOPSISDIVINFO> -<DATE>1997-12-24</DATE> -</REFSYNOPSISDIVINFO> -<SYNOPSIS> -pg_lo_creat <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">mode</REPLACEABLE> -</SYNOPSIS> - -<REFSECT2 ID="R2-PGTCL-PGLOCREAT-1"> -<REFSECT2INFO> -<DATE>1997-12-24</DATE> -</REFSECT2INFO> -<TITLE>Inputs -</TITLE> -<VARIABLELIST> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA>Specifies a valid database connection. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">mode</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA>Specifies the access mode for the large object</PARA> -</LISTITEM> -</VARLISTENTRY> -</VARIABLELIST> -</REFSECT2> - -<REFSECT2 ID="R2-PGTCL-PGLOCREAT-2"> -<REFSECT2INFO> -<DATE>1997-12-24</DATE> -</REFSECT2INFO> -<TITLE>Outputs -</TITLE> -<VARIABLELIST> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">objOid</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA> -The OID of the large object created. -</PARA> -</LISTITEM> -</VARLISTENTRY> -</VARIABLELIST> -</REFSECT2> -</REFSYNOPSISDIV> - -<REFSECT1 ID="R1-PGTCL-PGLOCREAT-1"> -<REFSECT1INFO> -<DATE>1997-12-24</DATE> -</REFSECT1INFO> -<TITLE>Description -</TITLE> -<PARA><FUNCTION>pg_lo_creat</FUNCTION> creates an Inversion Large Object. -</PARA> -</REFSECT1> -<REFSECT1 ID="R1-PGTCL-PGLOCREAT-2"> -<TITLE>Usage -</TITLE> -<PARA> -mode can be any or'ing together of <literal>INV_READ</> and <literal>INV_WRITE</>. -The <quote>or</quote> operator is <literal>|</literal>. -<ProgramListing> + +<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><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>-array <parameter>arrayVar</parameter></optional> <optional>-oid <parameter>oidVar</parameter></optional> <parameter>conn</parameter> <parameter>commandString</parameter> <optional><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><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>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><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 database connection 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> -</REFSECT1> -</REFENTRY> - -<!-- ********************************************************** --> - -<REFENTRY ID="PGTCL-PGLOOPEN"> -<REFMETA> -<REFENTRYTITLE>pg_lo_open</REFENTRYTITLE> -<REFMISCINFO>PGTCL - Large Objects</REFMISCINFO> -</REFMETA> -<REFNAMEDIV> -<REFNAME>pg_lo_open -</REFNAME> -<REFPURPOSE>open a large object -</REFPURPOSE> -<INDEXTERM ID="IX-PGTCL-PGLOOPEN-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>opening</SECONDARY></INDEXTERM> -<INDEXTERM ID="IX-PGTCL-PGLOOPEN-2"><PRIMARY>pg_lo_open</PRIMARY></INDEXTERM> -</REFNAMEDIV> -<REFSYNOPSISDIV> -<REFSYNOPSISDIVINFO> -<DATE>1997-12-24</DATE> -</REFSYNOPSISDIVINFO> -<SYNOPSIS> -pg_lo_open <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">objOid</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">mode</REPLACEABLE> -</SYNOPSIS> - -<REFSECT2 ID="R2-PGTCL-PGLOOPEN-1"> -<REFSECT2INFO> -<DATE>1997-12-24</DATE> -</REFSECT2INFO> -<TITLE>Inputs -</TITLE> -<VARIABLELIST> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA>Specifies a valid database connection. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">objOid</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA>Specifies a valid large object OID. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">mode</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA>Specifies the access mode for the large object</PARA> -</LISTITEM> -</VARLISTENTRY> -</VARIABLELIST> -</REFSECT2> - -<REFSECT2 ID="R2-PGTCL-PGLOOPEN-2"> -<REFSECT2INFO> -<DATE>1997-12-24</DATE> -</REFSECT2INFO> -<TITLE>Outputs -</TITLE> -<VARIABLELIST> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">fd</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA> -A file descriptor for use in later pg_lo* routines. -</PARA> -</LISTITEM> -</VARLISTENTRY> -</VARIABLELIST> -</REFSECT2> -</REFSYNOPSISDIV> - -<REFSECT1 ID="R1-PGTCL-PGLOOPEN-1"> -<REFSECT1INFO> -<DATE>1997-12-24</DATE> -</REFSECT1INFO> -<TITLE>Description -</TITLE> -<PARA><FUNCTION>pg_lo_open</FUNCTION> open an Inversion Large Object. -</PARA> -</REFSECT1> -<REFSECT1 ID="R1-PGTCL-PGLOOPEN-2"> -<TITLE>Usage -</TITLE> -<PARA> -Mode can be either <literal>r</>, <literal>w</>, or <literal>rw</>. -</PARA> -</REFSECT1> -</REFENTRY> - -<!-- ********************************************************** --> - -<REFENTRY ID="PGTCL-PGLOCLOSE"> -<REFMETA> -<REFENTRYTITLE>pg_lo_close</REFENTRYTITLE> -<REFMISCINFO>PGTCL - Large Objects</REFMISCINFO> -</REFMETA> -<REFNAMEDIV> -<REFNAME>pg_lo_close -</REFNAME> -<REFPURPOSE>close a large object -</REFPURPOSE> -<INDEXTERM ID="IX-PGTCL-PGLOCLOSE-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>closing</SECONDARY></INDEXTERM> -<INDEXTERM ID="IX-PGTCL-PGLOCLOSE-2"><PRIMARY>pg_lo_close</PRIMARY></INDEXTERM> -</REFNAMEDIV> -<REFSYNOPSISDIV> -<REFSYNOPSISDIVINFO> -<DATE>1997-12-24</DATE> -</REFSYNOPSISDIVINFO> -<SYNOPSIS> -pg_lo_close <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">fd</REPLACEABLE> -</SYNOPSIS> - -<REFSECT2 ID="R2-PGTCL-PGLOCLOSE-1"> -<REFSECT2INFO> -<DATE>1997-12-24</DATE> -</REFSECT2INFO> -<TITLE>Inputs -</TITLE> -<VARIABLELIST> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA>Specifies a valid database connection. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">fd</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA> -A file descriptor for use in later pg_lo* routines. -</PARA> -</LISTITEM> -</VARLISTENTRY> -</VARIABLELIST> -</REFSECT2> - -<REFSECT2 ID="R2-PGTCL-PGLOCLOSE-2"> -<REFSECT2INFO> -<DATE>1997-12-24</DATE> -</REFSECT2INFO> -<TITLE>Outputs -</TITLE> -<PARA>None</PARA> -</REFSECT2> -</REFSYNOPSISDIV> - -<REFSECT1 ID="R1-PGTCL-PGLOCLOSE-1"> -<REFSECT1INFO> -<DATE>1997-12-24</DATE> -</REFSECT1INFO> -<TITLE>Description -</TITLE> -<PARA><FUNCTION>pg_lo_close</FUNCTION> closes an Inversion Large Object. -</PARA> -</REFSECT1> -<REFSECT1 ID="R1-PGTCL-PGLOCLOSE-2"> -<TITLE>Usage -</TITLE> -<PARA> -</PARA> -</REFSECT1> -</REFENTRY> - -<!-- ********************************************************** --> - -<REFENTRY ID="PGTCL-PGLOREAD"> -<REFMETA> -<REFENTRYTITLE>pg_lo_read</REFENTRYTITLE> -<REFMISCINFO>PGTCL - Large Objects</REFMISCINFO> -</REFMETA> -<REFNAMEDIV> -<REFNAME>pg_lo_read -</REFNAME> -<REFPURPOSE>read a large object -</REFPURPOSE> -<INDEXTERM ID="IX-PGTCL-PGLOREAD-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>reading</SECONDARY></INDEXTERM> -<INDEXTERM ID="IX-PGTCL-PGLOREAD-2"><PRIMARY>pg_lo_read</PRIMARY></INDEXTERM> -</REFNAMEDIV> -<REFSYNOPSISDIV> -<REFSYNOPSISDIVINFO> -<DATE>1997-12-24</DATE> -</REFSYNOPSISDIVINFO> -<SYNOPSIS> -pg_lo_read <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">fd</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">bufVar</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">len</REPLACEABLE> -</SYNOPSIS> - -<REFSECT2 ID="R2-PGTCL-PGLOREAD-1"> -<REFSECT2INFO> -<DATE>1997-12-24</DATE> -</REFSECT2INFO> -<TITLE>Inputs -</TITLE> -<VARIABLELIST> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA>Specifies a valid database connection. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">fd</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA> -File descriptor for the large object from pg_lo_open. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">bufVar</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA>Specifies a valid buffer variable to contain the large object segment. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">len</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA>Specifies the maximum allowable size of the large object segment.</PARA> -</LISTITEM> -</VARLISTENTRY> -</VARIABLELIST> -</REFSECT2> - -<REFSECT2 ID="R2-PGTCL-PGLOREAD-2"> -<REFSECT2INFO> -<DATE>1997-12-24</DATE> -</REFSECT2INFO> -<TITLE>Outputs -</TITLE> -<PARA>None</PARA> -</REFSECT2> -</REFSYNOPSISDIV> - -<REFSECT1 ID="R1-PGTCL-PGLOREAD-1"> -<REFSECT1INFO> -<DATE>1997-12-24</DATE> -</REFSECT1INFO> -<TITLE>Description -</TITLE> -<PARA><FUNCTION>pg_lo_read</FUNCTION> reads -at most <REPLACEABLE CLASS="PARAMETER">len</REPLACEABLE> bytes from a large object into a variable - named <REPLACEABLE CLASS="PARAMETER">bufVar</REPLACEABLE>. -</PARA> -</REFSECT1> -<REFSECT1 ID="R1-PGTCL-PGLOREAD-2"> -<TITLE>Usage -</TITLE> -<PARA> -<REPLACEABLE CLASS="PARAMETER">bufVar</REPLACEABLE> must be a valid variable name. -</PARA> -</REFSECT1> -</REFENTRY> - -<!-- ********************************************************** --> - -<REFENTRY ID="PGTCL-PGLOWRITE"> -<REFMETA> -<REFENTRYTITLE>pg_lo_write</REFENTRYTITLE> -<REFMISCINFO>PGTCL - Large Objects</REFMISCINFO> -</REFMETA> -<REFNAMEDIV> -<REFNAME>pg_lo_write -</REFNAME> -<REFPURPOSE>write a large object -</REFPURPOSE> -<INDEXTERM ID="IX-PGTCL-PGLOWRITE-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>writing</SECONDARY></INDEXTERM> -<INDEXTERM ID="IX-PGTCL-PGLOWRITE-2"><PRIMARY>pg_lo_write</PRIMARY></INDEXTERM> -</REFNAMEDIV> -<REFSYNOPSISDIV> -<REFSYNOPSISDIVINFO> -<DATE>1997-12-24</DATE> -</REFSYNOPSISDIVINFO> -<SYNOPSIS> -pg_lo_write <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">fd</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">buf</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">len</REPLACEABLE> -</SYNOPSIS> - -<REFSECT2 ID="R2-PGTCL-PGLOWRITE-1"> -<REFSECT2INFO> -<DATE>1997-12-24</DATE> -</REFSECT2INFO> -<TITLE>Inputs -</TITLE> -<VARIABLELIST> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA>Specifies a valid database connection. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">fd</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA> -File descriptor for the large object from pg_lo_open. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">buf</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA>Specifies a valid string variable to write to the large object. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">len</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA>Specifies the maximum size of the string to write.</PARA> -</LISTITEM> -</VARLISTENTRY> -</VARIABLELIST> -</REFSECT2> - -<REFSECT2 ID="R2-PGTCL-PGLOWRITE-2"> -<REFSECT2INFO> -<DATE>1997-12-24</DATE> -</REFSECT2INFO> -<TITLE>Outputs -</TITLE> -<PARA>None</PARA> -</REFSECT2> -</REFSYNOPSISDIV> - -<REFSECT1 ID="R1-PGTCL-PGLOWRITE-1"> -<REFSECT1INFO> -<DATE>1997-12-24</DATE> -</REFSECT1INFO> -<TITLE>Description -</TITLE> -<PARA><FUNCTION>pg_lo_write</FUNCTION> writes -at most <REPLACEABLE CLASS="PARAMETER">len</REPLACEABLE> bytes to a large object from a variable - <REPLACEABLE CLASS="PARAMETER">buf</REPLACEABLE>. -</PARA> -</REFSECT1> -<REFSECT1 ID="R1-PGTCL-PGLOWRITE-2"> -<TITLE>Usage -</TITLE> -<PARA> -<REPLACEABLE CLASS="PARAMETER">buf</REPLACEABLE> must be -the actual string to write, not a variable name. -</PARA> -</REFSECT1> -</REFENTRY> - -<!-- ********************************************************** --> - -<REFENTRY ID="PGTCL-PGLOLSEEK"> -<REFMETA> -<REFENTRYTITLE>pg_lo_lseek</REFENTRYTITLE> -<REFMISCINFO>PGTCL - Large Objects</REFMISCINFO> -</REFMETA> -<REFNAMEDIV> -<REFNAME>pg_lo_lseek -</REFNAME> -<REFPURPOSE>seek to a position in a large object -</REFPURPOSE> -<INDEXTERM ID="IX-PGTCL-PGLOLSEEK-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>positioning</SECONDARY></INDEXTERM> -<INDEXTERM ID="IX-PGTCL-PGLOLSEEK-2"><PRIMARY>pg_lo_lseek</PRIMARY></INDEXTERM> -</REFNAMEDIV> -<REFSYNOPSISDIV> -<REFSYNOPSISDIVINFO> -<DATE>1997-12-24</DATE> -</REFSYNOPSISDIVINFO> -<SYNOPSIS> -pg_lo_lseek <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">fd</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">offset</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">whence</REPLACEABLE> -</SYNOPSIS> - -<REFSECT2 ID="R2-PGTCL-PGLOLSEEK-1"> -<REFSECT2INFO> -<DATE>1997-12-24</DATE> -</REFSECT2INFO> -<TITLE>Inputs -</TITLE> -<VARIABLELIST> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA>Specifies a valid database connection. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">fd</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA> -File descriptor for the large object from pg_lo_open. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">offset</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA>Specifies a zero-based offset in bytes. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">whence</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA> whence can be <literal>SEEK_CUR</>, <literal>SEEK_END</>, or <literal>SEEK_SET</> </PARA> -</LISTITEM> -</VARLISTENTRY> -</VARIABLELIST> -</REFSECT2> - -<REFSECT2 ID="R2-PGTCL-PGLOLSEEK-2"> -<REFSECT2INFO> -<DATE>1997-12-24</DATE> -</REFSECT2INFO> -<TITLE>Outputs -</TITLE> -<PARA>None</PARA> -</REFSECT2> -</REFSYNOPSISDIV> - -<REFSECT1 ID="R1-PGTCL-PGLOLSEEK-1"> -<REFSECT1INFO> -<DATE>1997-12-24</DATE> -</REFSECT1INFO> -<TITLE>Description -</TITLE> -<PARA><FUNCTION>pg_lo_lseek</FUNCTION> positions -to <REPLACEABLE CLASS="PARAMETER">offset</REPLACEABLE> bytes from the beginning of the large object. -</PARA> -</REFSECT1> -<REFSECT1 ID="R1-PGTCL-PGLOLSEEK-2"> -<TITLE>Usage -</TITLE> -<PARA> -<REPLACEABLE CLASS="PARAMETER">whence</REPLACEABLE> -can be <literal>SEEK_CUR</literal>, <literal>SEEK_END</>, or <literal>SEEK_SET</literal>. -</PARA> -</REFSECT1> -</REFENTRY> - -<!-- ********************************************************** --> - -<REFENTRY ID="PGTCL-PGLOTELL"> -<REFMETA> -<REFENTRYTITLE>pg_lo_tell</REFENTRYTITLE> -<REFMISCINFO>PGTCL - Large Objects</REFMISCINFO> -</REFMETA> -<REFNAMEDIV> -<REFNAME>pg_lo_tell -</REFNAME> -<REFPURPOSE>return the current seek position of a large object -</REFPURPOSE> -<INDEXTERM ID="IX-PGTCL-PGLOTELL-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>positioning</SECONDARY></INDEXTERM> -<INDEXTERM ID="IX-PGTCL-PGLOTELL-2"><PRIMARY>pg_lo_tell</PRIMARY></INDEXTERM> -</REFNAMEDIV> -<REFSYNOPSISDIV> -<REFSYNOPSISDIVINFO> -<DATE>1997-12-24</DATE> -</REFSYNOPSISDIVINFO> -<SYNOPSIS> -pg_lo_tell <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">fd</REPLACEABLE> -</SYNOPSIS> - -<REFSECT2 ID="R2-PGTCL-PGLOTELL-1"> -<REFSECT2INFO> -<DATE>1997-12-24</DATE> -</REFSECT2INFO> -<TITLE>Inputs -</TITLE> -<VARIABLELIST> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA>Specifies a valid database connection. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">fd</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA> -File descriptor for the large object from pg_lo_open. -</PARA> -</LISTITEM> -</VARLISTENTRY> -</VARIABLELIST> -</REFSECT2> - -<REFSECT2 ID="R2-PGTCL-PGLOTELL-2"> -<REFSECT2INFO> -<DATE>1997-12-24</DATE> -</REFSECT2INFO> -<TITLE>Outputs -</TITLE> -<VARIABLELIST> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">offset</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA>A zero-based offset in bytes suitable for input to <Function>pg_lo_lseek</Function>. -</PARA> -</LISTITEM> -</VARLISTENTRY> -</VARIABLELIST> -</REFSECT2> -</REFSYNOPSISDIV> - -<REFSECT1 ID="R1-PGTCL-PGLOTELL-1"> -<REFSECT1INFO> -<DATE>1997-12-24</DATE> -</REFSECT1INFO> -<TITLE>Description -</TITLE> -<PARA><FUNCTION>pg_lo_tell</FUNCTION> returns the current -to <REPLACEABLE CLASS="PARAMETER">offset</REPLACEABLE> in bytes from the beginning of the large object. -</PARA> -</REFSECT1> -<REFSECT1 ID="R1-PGTCL-PGLOTELL-2"> -<TITLE>Usage -</TITLE> -<PARA> -</PARA> -</REFSECT1> -</REFENTRY> - -<!-- ********************************************************** --> - -<REFENTRY ID="PGTCL-PGLOUNLINK"> -<REFMETA> -<REFENTRYTITLE>pg_lo_unlink</REFENTRYTITLE> -<REFMISCINFO>PGTCL - Large Objects</REFMISCINFO> -</REFMETA> -<REFNAMEDIV> -<REFNAME>pg_lo_unlink -</REFNAME> -<REFPURPOSE>delete a large object -</REFPURPOSE> -<INDEXTERM ID="IX-PGTCL-PGLOUNLINK-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>delete</SECONDARY></INDEXTERM> -<INDEXTERM ID="IX-PGTCL-PGLOUNLINK-2"><PRIMARY>pg_lo_unlink</PRIMARY></INDEXTERM> -</REFNAMEDIV> -<REFSYNOPSISDIV> -<REFSYNOPSISDIVINFO> -<DATE>1997-12-24</DATE> -</REFSYNOPSISDIVINFO> -<SYNOPSIS> -pg_lo_unlink <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">lobjId</REPLACEABLE> -</SYNOPSIS> - -<REFSECT2 ID="R2-PGTCL-PGLOUNLINK-1"> -<REFSECT2INFO> -<DATE>1997-12-24</DATE> -</REFSECT2INFO> -<TITLE>Inputs -</TITLE> -<VARIABLELIST> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA>Specifies a valid database connection. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">lobjId</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA> -Identifier for a large object. -<comment> - XXX Is this the same as <parameter>objOid</parameter> in other calls?? - thomas 1998-01-11 -</comment> -</PARA> -</LISTITEM> -</VARLISTENTRY> -</VARIABLELIST> -</REFSECT2> - -<REFSECT2 ID="R2-PGTCL-PGLOUNLINK-2"> -<REFSECT2INFO> -<DATE>1997-12-24</DATE> -</REFSECT2INFO> -<TITLE>Outputs -</TITLE> -<PARA> -None -</PARA> -</REFSECT2> -</REFSYNOPSISDIV> - -<REFSECT1 ID="R1-PGTCL-PGLOUNLINK-1"> -<REFSECT1INFO> -<DATE>1997-12-24</DATE> -</REFSECT1INFO> -<TITLE>Description -</TITLE> -<PARA><FUNCTION>pg_lo_unlink</FUNCTION> deletes the specified large object. -</PARA> -</REFSECT1> -<REFSECT1 ID="R1-PGTCL-PGLOUNLINK-2"> -<TITLE>Usage -</TITLE> -<PARA> -</PARA> -</REFSECT1> -</REFENTRY> - -<!-- ********************************************************** --> - -<REFENTRY ID="PGTCL-PGLOIMPORT"> -<REFMETA> -<REFENTRYTITLE>pg_lo_import</REFENTRYTITLE> -<REFMISCINFO>PGTCL - Large Objects</REFMISCINFO> -</REFMETA> -<REFNAMEDIV> -<REFNAME>pg_lo_import -</REFNAME> -<REFPURPOSE>import a large object from a file -</REFPURPOSE> -<INDEXTERM ID="IX-PGTCL-PGLOIMPORT-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>import</SECONDARY></INDEXTERM> -<INDEXTERM ID="IX-PGTCL-PGLOIMPORT-2"><PRIMARY>pg_lo_import</PRIMARY></INDEXTERM> -</REFNAMEDIV> -<REFSYNOPSISDIV> -<REFSYNOPSISDIVINFO> -<DATE>1997-12-24</DATE> -</REFSYNOPSISDIVINFO> -<SYNOPSIS> -pg_lo_import <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">filename</REPLACEABLE> -</SYNOPSIS> - -<REFSECT2 ID="R2-PGTCL-PGLOIMPORT-1"> -<REFSECT2INFO> -<DATE>1997-12-24</DATE> -</REFSECT2INFO> -<TITLE>Inputs -</TITLE> -<VARIABLELIST> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA>Specifies a valid database connection. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">filename</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA> -Unix file name. -</PARA> -</LISTITEM> -</VARLISTENTRY> -</VARIABLELIST> -</REFSECT2> - -<REFSECT2 ID="R2-PGTCL-PGLOIMPORT-2"> -<REFSECT2INFO> -<DATE>1997-12-24</DATE> -</REFSECT2INFO> -<TITLE>Outputs -</TITLE> -<PARA> -None -<comment> - XXX Does this return a lobjId? Is that the same as the objOid in other calls? thomas - 1998-01-11 -</comment> -</PARA> -</REFSECT2> -</REFSYNOPSISDIV> - -<REFSECT1 ID="R1-PGTCL-PGLOIMPORT-1"> -<REFSECT1INFO> -<DATE>1997-12-24</DATE> -</REFSECT1INFO> -<TITLE>Description -</TITLE> -<PARA><FUNCTION>pg_lo_import</FUNCTION> reads the specified file and places the contents into a large object. -</PARA> -</REFSECT1> -<REFSECT1 ID="R1-PGTCL-PGLOIMPORT-2"> -<TITLE>Usage -</TITLE> -<PARA> - <Function>pg_lo_import</Function> must be called within a BEGIN/END transaction block. -</PARA> -</REFSECT1> -</REFENTRY> - -<!-- ********************************************************** --> - -<REFENTRY ID="PGTCL-PGLOEXPORT"> -<REFMETA> -<REFENTRYTITLE>pg_lo_export</REFENTRYTITLE> -<REFMISCINFO>PGTCL - Large Objects</REFMISCINFO> -</REFMETA> -<REFNAMEDIV> -<REFNAME>pg_lo_export -</REFNAME> -<REFPURPOSE>export a large object to a file -</REFPURPOSE> -<INDEXTERM ID="IX-PGTCL-PGLOEXPORT-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>export</SECONDARY></INDEXTERM> -<INDEXTERM ID="IX-PGTCL-PGLOEXPORT-2"><PRIMARY>pg_lo_export</PRIMARY></INDEXTERM> -</REFNAMEDIV> -<REFSYNOPSISDIV> -<REFSYNOPSISDIVINFO> -<DATE>1997-12-24</DATE> -</REFSYNOPSISDIVINFO> -<SYNOPSIS> -pg_lo_export <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">lobjId</REPLACEABLE> <REPLACEABLE CLASS="PARAMETER">filename</REPLACEABLE> -</SYNOPSIS> - -<REFSECT2 ID="R2-PGTCL-PGLOEXPORT-1"> -<REFSECT2INFO> -<DATE>1997-12-24</DATE> -</REFSECT2INFO> -<TITLE>Inputs -</TITLE> -<VARIABLELIST> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">conn</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA>Specifies a valid database connection. -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">lobjId</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA> -Large object identifier. -<comment> - XXX Is this the same as the objOid in other calls?? thomas - 1998-01-11 -</comment> -</PARA> -</LISTITEM> -</VARLISTENTRY> -<VARLISTENTRY> -<TERM> - <REPLACEABLE CLASS="PARAMETER">filename</REPLACEABLE> -</TERM> -<LISTITEM> -<PARA> -Unix file name. -</PARA> -</LISTITEM> -</VARLISTENTRY> -</VARIABLELIST> -</REFSECT2> - -<REFSECT2 ID="R2-PGTCL-PGLOEXPORT-2"> -<REFSECT2INFO> -<DATE>1997-12-24</DATE> -</REFSECT2INFO> -<TITLE>Outputs -</TITLE> -<PARA> -None -<comment> - XXX Does this return a lobjId? Is that the same as the objOid in other calls? thomas - 1998-01-11 -</comment> -</PARA> -</REFSECT2> -</REFSYNOPSISDIV> - -<REFSECT1 ID="R1-PGTCL-PGLOEXPORT-1"> -<REFSECT1INFO> -<DATE>1997-12-24</DATE> -</REFSECT1INFO> -<TITLE>Description -</TITLE> -<PARA><FUNCTION>pg_lo_export</FUNCTION> writes the specified large object into a Unix file. -</PARA> -</REFSECT1> -<REFSECT1 ID="R1-PGTCL-PGLOEXPORT-2"> -<TITLE>Usage -</TITLE> -<PARA> - <Function>pg_lo_export</Function> must be called within a BEGIN/END transaction block. -</PARA> -</REFSECT1> -</REFENTRY> - -</Sect1> -</Chapter> +</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 database connection in which the large object to + be opened 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 database connection 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 database connection 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> + None + </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 database connection 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). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><parameter>len</parameter></term> + <listitem> + <para> + The maximum number of bytes to write. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para> + None + </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 database connection 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 database connection 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 database connection 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 database connection 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 database connection 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> |