</example>

</Sect1>

<Sect1 id="libpgtcl-loading">

<Title>Loading <application>pgtcl</application> into your application</Title>

<para>

Before using <application>pgtcl</application> commands, you must load

<filename>libpgtcl</> into your Tcl application. This is normally

done with the Tcl <literal>load</> command. Here is an example:

<programlisting>

load libpgtcl[info sharedlibextension]

</programlisting>

The use of <literal>info sharedlibextension</> is recommended in

preference to hard-wiring <literal>.so</> or <literal>.sl</> into

the program.

</para>

<para>

The <literal>load</> command will fail unless the system's dynamic loader

knows where to look for the <filename>libpgtcl</> shared library file.

You may need to work with <literal>ldconfig</>, or set the environment

variable <envar>LD_LIBRARY_PATH</>, or use some equivalent facility for

your platform to make it work.

</para>

<para>

<filename>libpgtcl</> in turn depends on <filename>libpq</>, so the

dynamic loader must also be able to find the <filename>libpq</> shared

library. In practice this is seldom an issue, since both of these

shared libraries are normally stored in the same directory, but it

can be a stumbling block in some configurations.

</para>

<para>

If you use a custom executable for your application, you might choose

to statically bind <filename>libpgtcl</> into the executable and thereby

avoid the <literal>load</> command and the potential problems of dynamic

linking. See the source code for <application>pgtclsh</> for an example.

</para>

</Sect1>

<Sect1 id="libpgtcl-ref">

<Title><application>pgtcl</application> Command Reference Information</Title>

<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>

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>

<TITLE>Outputs

</TITLE>

<VARIABLELIST>

<VARLISTENTRY>

<TERM>

<REPLACEABLE CLASS="PARAMETER">resultHandle</REPLACEABLE>

</TERM>

<LISTITEM>

<PARA>

the return result is either an error message or a handle for a query result.

</PARA>

</LISTITEM>

</VARLISTENTRY>

</VARIABLELIST>

<Para>

None.

</Para>

</REFSECT2></REFSYNOPSISDIV>

<REFSECT1 ID="R1-PGTCL-PGSELECT-1">

<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">

(and, perhaps, other fields):

<ProgramListing>

pg_select $pgconn "SELECT * FROM table" array {

puts [format "%5d %s" array(control) array(name)]

puts [format "%5d %s"$array(control)$array(name)]

}

</ProgramListing>

</PARA>