mirrors
/
postgres
mirror of https://github.com/postgres/postgres
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

More minor updates and copy-editing.

This commit is contained in:
Tom Lane 2004-12-28 22:47:15 +00:00
parent 7737d01ece
commit 797c2b2501
5 changed files with 160 additions and 127 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
doc/src/sgml/ecpg.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.59 2003/12/26 20:00:00 meskes Exp $ $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.60 2004/12/28 22:47:15 tgl Exp $
--> -->
<chapter id="ecpg"> <chapter id="ecpg">
@ -19,7 +19,7 @@ $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.59 2003/12/26 20:00:00 meskes Exp
</para> </para>
<para> <para>
Admittedly, this documentation is quite incomplete. But since this This documentation is quite incomplete. But since this
interface is standardized, additional information can be found in interface is standardized, additional information can be found in
many resources about SQL. many resources about SQL.
</para> </para>
@ -31,9 +31,9 @@ $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.59 2003/12/26 20:00:00 meskes Exp
An embedded SQL program consists of code written in an ordinary An embedded SQL program consists of code written in an ordinary
programming language, in this case C, mixed with SQL commands in programming language, in this case C, mixed with SQL commands in
specially marked sections. To build the program, the source code specially marked sections. To build the program, the source code
is first passed to the embedded SQL preprocessor, which converts it is first passed through the embedded SQL preprocessor, which converts it
to an ordinary C program, and afterwards it can be processed by a C to an ordinary C program, and afterwards it can be processed by a C
compilation tool chain. compiler.
</para> </para>
<para> <para>
@ -53,7 +53,7 @@ $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.59 2003/12/26 20:00:00 meskes Exp
</para> </para>
<para> <para>
As indicated, programs written for the embedded As already stated, programs written for the embedded
<acronym>SQL</acronym> interface are normal C programs with special <acronym>SQL</acronym> interface are normal C programs with special
code inserted to perform database-related actions. This special code inserted to perform database-related actions. This special
code always has the form code always has the form
@ -61,8 +61,8 @@ $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.59 2003/12/26 20:00:00 meskes Exp
EXEC SQL ...; EXEC SQL ...;
</programlisting> </programlisting>
These statements syntactically take the place of a C statement. These statements syntactically take the place of a C statement.
Depending on the particular statement, they may appear in the Depending on the particular statement, they may appear at the
global context or within a function. Embedded global level or within a function. Embedded
<acronym>SQL</acronym> statements follow the case-sensitivity rules <acronym>SQL</acronym> statements follow the case-sensitivity rules
of normal <acronym>SQL</acronym> code, and not those of C. of normal <acronym>SQL</acronym> code, and not those of C.
</para> </para>
@ -326,9 +326,9 @@ EXEC SQL COMMIT;
<para> <para>
In the default mode, statements are committed only when In the default mode, statements are committed only when
<command>EXEC SQL COMMIT</command> is issued. The embedded SQL <command>EXEC SQL COMMIT</command> is issued. The embedded SQL
interface also supports autocommit of transactions (as known from interface also supports autocommit of transactions (similar to
other interfaces) via the <option>-t</option> command-line option <application>libpq</> behavior) via the <option>-t</option> command-line
to <command>ecpg</command> (see below) or via the <literal>EXEC SQL option to <command>ecpg</command> (see below) or via the <literal>EXEC SQL
SET AUTOCOMMIT TO ON</literal> statement. In autocommit mode, each SET AUTOCOMMIT TO ON</literal> statement. In autocommit mode, each
command is automatically committed unless it is inside an explicit command is automatically committed unless it is inside an explicit
transaction block. This mode can be explicitly turned off using transaction block. This mode can be explicitly turned off using
@ -448,7 +448,7 @@ char foo[16], bar[16];
<para> <para>
The declarations are also echoed to the output file as a normal C The declarations are also echoed to the output file as a normal C
variables, so there's no need to declare them again. Variables variables, so there's no need to declare them again. Variables
that are not intended to be used with SQL commands can be declared that are not intended to be used in SQL commands can be declared
normally outside these special sections. normally outside these special sections.
</para> </para>
@ -553,7 +553,7 @@ do {
second host variable specification to each host variable that second host variable specification to each host variable that
contains data. This second host variable is called the contains data. This second host variable is called the
<firstterm>indicator</firstterm> and contains a flag that tells <firstterm>indicator</firstterm> and contains a flag that tells
whether the datums is null, in which case the value of the real whether the datum is null, in which case the value of the real
host variable is ignored. Here is an example that handles the host variable is ignored. Here is an example that handles the
retrieval of null values correctly: retrieval of null values correctly:
<programlisting> <programlisting>
@ -1043,7 +1043,7 @@ static void set_error_handler(void)
<title>sqlca</title> <title>sqlca</title>
<para> <para>
For a more powerful error handling, the embedded SQL interface For more powerful error handling, the embedded SQL interface
provides a global variable with the name <varname>sqlca</varname> provides a global variable with the name <varname>sqlca</varname>
that has the following structure: that has the following structure:
<programlisting> <programlisting>
@ -1064,7 +1064,7 @@ struct
} sqlca; } sqlca;
</programlisting> </programlisting>
(In a multithreaded program, every thread automatically gets its (In a multithreaded program, every thread automatically gets its
own copy of <varname>sqlca</varname>. This works similar to the own copy of <varname>sqlca</varname>. This works similarly to the
handling of the standard C global variable handling of the standard C global variable
<varname>errno</varname>.) <varname>errno</varname>.)
</para> </para>
@ -1132,7 +1132,7 @@ struct
<para> <para>
The structure <varname>sqlca</varname> is not defined in the SQL The structure <varname>sqlca</varname> is not defined in the SQL
standard, but is implemented in several other SQL database standard, but is implemented in several other SQL database
systems. The definitions are similar in the core, but if you want systems. The definitions are similar at the core, but if you want
to write portable applications, then you should investigate the to write portable applications, then you should investigate the
different implementations carefully. different implementations carefully.
</para> </para>
@ -1539,7 +1539,7 @@ ecpg prog1.pgc
<programlisting> <programlisting>
cc -c prog1.c cc -c prog1.c
</programlisting> </programlisting>
The generated C source files include headers files from the The generated C source files include header files from the
<productname>PostgreSQL</> installation, so if you installed <productname>PostgreSQL</> installation, so if you installed
<productname>PostgreSQL</> in a location that is not searched by <productname>PostgreSQL</> in a location that is not searched by
default, you have to add an option such as default, you have to add an option such as
@ -1575,9 +1575,9 @@ ECPG = ecpg
</para> </para>
<para> <para>
<application>ecpg</application> is thread-safe if it is compiled using The <application>ecpg</application> library is thread-safe if it is built
the <option>--enable-thread-safety</> <filename>configure</filename> using the <option>--enable-thread-safety</> command-line option to
command-line option. (You might need to use other threading <filename>configure</filename>. (You might need to use other threading
command-line options to compile your client code.) command-line options to compile your client code.)
</para> </para>
</sect1> </sect1>
@ -1621,7 +1621,7 @@ ECPG = ecpg
<title>Internals</title> <title>Internals</title>
<para> <para>
This section explain how <application>ECPG</application> works This section explains how <application>ECPG</application> works
internally. This information can occasionally be useful to help internally. This information can occasionally be useful to help
users understand how to use <application>ECPG</application>. users understand how to use <application>ECPG</application>.
</para> </para>

87
doc/src/sgml/external-projects.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$PostgreSQL: pgsql/doc/src/sgml/external-projects.sgml,v 1.5 2004/12/13 18:05:08 petere Exp $ $PostgreSQL: pgsql/doc/src/sgml/external-projects.sgml,v 1.6 2004/12/28 22:47:15 tgl Exp $
--> -->
<chapter id="external-projects"> <chapter id="external-projects">
@ -9,15 +9,28 @@ $PostgreSQL: pgsql/doc/src/sgml/external-projects.sgml,v 1.5 2004/12/13 18:05:08
<productname>PostgreSQL</productname> is a complex software project, <productname>PostgreSQL</productname> is a complex software project,
and managing it is difficult. We have found that many and managing it is difficult. We have found that many
enhancements to <productname>PostgreSQL</productname> can be more enhancements to <productname>PostgreSQL</productname> can be more
efficiently developed independently of the main project. They can efficiently developed separately from the core project. Separate
have their own developer teams, email lists, their own bug tracking, projects can
and their own release schedule. While their independence makes have their own developer teams, email lists, bug tracking,
development easier, it makes user's jobs harder. They have to hunt and release schedules. While their independence makes
development easier, it makes users' jobs harder. They have to hunt
around looking for database enhancements to meet their needs. around looking for database enhancements to meet their needs.
This section outlines some of the more popular externally This section describes some of the more popular externally
developed enhancements and guides you on how to find them. developed enhancements and guides you on how to find them.
</para> </para>
<para>
Many <productname>PostgreSQL</productname>-related projects are
hosted at either
<productname>GBorg</> at <ulink url="http://gborg.postgresql.org">
http://gborg.postgresql.org</ulink> or
<productname>pgFoundry</> at <ulink
url="http://pgfoundry.org">http://pgfoundry.org</ulink>.
There are other
<productname>PostgreSQL</productname>-related projects that are hosted
elsewhere, but you will have to do an Internet search to find them.
</para>
<sect1 id="interfaces"> <sect1 id="interfaces">
<title>Externally Developed Interfaces</title> <title>Externally Developed Interfaces</title>
@ -36,11 +49,7 @@ $PostgreSQL: pgsql/doc/src/sgml/external-projects.sgml,v 1.5 2004/12/13 18:05:08
</para> </para>
<para> <para>
To use other interfaces, you have to do some searching. For example, Some of the more popular interfaces are:
<productname>GBorg</> at <ulink url="http://gborg.postgresql.org">
http://gborg.postgresql.org</ulink> has over thirty interfaces listed
in its <literal>Drivers/Interfaces</> section. Some of the more
popular interfaces are:
<variablelist> <variablelist>
<varlistentry> <varlistentry>
@ -53,6 +62,15 @@ $PostgreSQL: pgsql/doc/src/sgml/external-projects.sgml,v 1.5 2004/12/13 18:05:08
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry>
<term>pgjdbc</term>
<listitem>
<para>
A <application>JDBC</> interface.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term>Npgsql</term> <term>Npgsql</term>
<listitem> <listitem>
@ -64,19 +82,19 @@ $PostgreSQL: pgsql/doc/src/sgml/external-projects.sgml,v 1.5 2004/12/13 18:05:08
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>libpq++</term> <term>libpqxx</term>
<listitem> <listitem>
<para> <para>
An older <application>C++</> interface. A newer <application>C++</> interface.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>libpqxx</term> <term>libpq++</term>
<listitem> <listitem>
<para> <para>
A newer <application>C++</> interface. An older <application>C++</> interface.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -101,11 +119,20 @@ $PostgreSQL: pgsql/doc/src/sgml/external-projects.sgml,v 1.5 2004/12/13 18:05:08
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry>
<term>pgtclng</term>
<listitem>
<para>
A newer version of the <application>Tcl</> interface.
</para>
</listitem>
</varlistentry>
<varlistentry> <varlistentry>
<term>pgtcl</term> <term>pgtcl</term>
<listitem> <listitem>
<para> <para>
The original version of the <application>TCL</> interface. The original version of the <application>Tcl</> interface.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -119,35 +146,9 @@ $PostgreSQL: pgsql/doc/src/sgml/external-projects.sgml,v 1.5 2004/12/13 18:05:08
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry>
<term>pgjdbc</term>
<listitem>
<para>
A <application>JDBC</> interface.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>pgtclng</term>
<listitem>
<para>
A newer version of the <application>TCL</> interface.
</para>
</listitem>
</varlistentry>
</variablelist> </variablelist>
</para> </para>
<para>
That section also contains several server-side languages that are
separate projects. <application>pgFoundry</> at <ulink
url="http://pgfoundry.org">http://pgfoundry.org</ulink> contains
even more projects. Other projects are not even hosted on these
servers and you will have to do an Internet search to find them.
</para>
</sect1> </sect1>
<sect1 id="extensions"> <sect1 id="extensions">
@ -169,7 +170,7 @@ $PostgreSQL: pgsql/doc/src/sgml/external-projects.sgml,v 1.5 2004/12/13 18:05:08
like <application>PostGIS</>. Even <application>PostgreSQL</> like <application>PostGIS</>. Even <application>PostgreSQL</>
replication solutions are developed externally. For example, replication solutions are developed externally. For example,
<application>Slony-I</> is a popular master/slave replication solution <application>Slony-I</> is a popular master/slave replication solution
that is developed independently from the main projects. that is developed independently from the core project.
</para> </para>
<para> <para>

12
doc/src/sgml/information_schema.sgml
View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/information_schema.sgml,v 1.19 2004/11/27 21:27:06 petere Exp $ --> <!-- $PostgreSQL: pgsql/doc/src/sgml/information_schema.sgml,v 1.20 2004/12/28 22:47:15 tgl Exp $ -->
<chapter id="information-schema"> <chapter id="information-schema">
<title>The Information Schema</title> <title>The Information Schema</title>
@ -30,7 +30,7 @@
exists in all databases. The owner of this schema is the initial exists in all databases. The owner of this schema is the initial
database user in the cluster, and that user naturally has all the database user in the cluster, and that user naturally has all the
privileges on this schema, including the ability to drop it (but privileges on this schema, including the ability to drop it (but
the space savings achieved by this are minuscule). the space savings achieved by that are minuscule).
</para> </para>
<para> <para>
@ -1003,7 +1003,7 @@
function (as parameter or return type) and stores some information function (as parameter or return type) and stores some information
about how the data type is used in that instance (for example, the about how the data type is used in that instance (for example, the
declared maximum length, if applicable). Each data type declared maximum length, if applicable). Each data type
descriptors is assigned an arbitrary identifier that is unique descriptor is assigned an arbitrary identifier that is unique
among the data type descriptor identifiers assigned for one object among the data type descriptor identifiers assigned for one object
(table, domain, function). This view is probably not useful for (table, domain, function). This view is probably not useful for
applications, but it is used to define some other views in the applications, but it is used to define some other views in the
@ -1735,7 +1735,7 @@ ORDER BY c.ordinal_position;
in the current database that are restricted by some unique, primary in the current database that are restricted by some unique, primary
key, or foreign key constraint. Check constraints are not included key, or foreign key constraint. Check constraints are not included
in this view. Only those columns are shown that are contained in a in this view. Only those columns are shown that are contained in a
table owned the current user. table owned by the current user.
</para> </para>
<table> <table>
@ -3320,7 +3320,7 @@ ORDER BY c.ordinal_position;
<para> <para>
The table <literal>sql_packages</literal> contains information The table <literal>sql_packages</literal> contains information
about which features packages defined in the SQL standard are about which feature packages defined in the SQL standard are
supported by <productname>PostgreSQL</productname>. Refer to <xref supported by <productname>PostgreSQL</productname>. Refer to <xref
linkend="features"> for background information on feature packages. linkend="features"> for background information on feature packages.
</para> </para>
@ -3888,7 +3888,7 @@ ORDER BY c.ordinal_position;
incompatibilities with the SQL standard that affect the incompatibilities with the SQL standard that affect the
representation in the information schema. First, trigger names are representation in the information schema. First, trigger names are
local to the table in <productname>PostgreSQL</productname>, rather local to the table in <productname>PostgreSQL</productname>, rather
than independent schema objects. Therefore there may be duplicate than being independent schema objects. Therefore there may be duplicate
trigger names defined in one schema, as long as they belong to trigger names defined in one schema, as long as they belong to
different tables. (<literal>trigger_catalog</literal> and different tables. (<literal>trigger_catalog</literal> and
<literal>trigger_schema</literal> are really the values pertaining <literal>trigger_schema</literal> are really the values pertaining

96
doc/src/sgml/libpq.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.172 2004/12/20 18:15:05 tgl Exp $ $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.173 2004/12/28 22:47:15 tgl Exp $
--> -->
<chapter id="libpq"> <chapter id="libpq">
@ -19,11 +19,19 @@ $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.172 2004/12/20 18:15:05 tgl Exp $
<application>libpq</> is a set of library functions that allow <application>libpq</> is a set of library functions that allow
client programs to pass queries to the <productname>PostgreSQL</> client programs to pass queries to the <productname>PostgreSQL</>
backend server and to receive the results of these queries. backend server and to receive the results of these queries.
</para>
<para>
<application>libpq</> is also the underlying engine for several <application>libpq</> is also the underlying engine for several
other <productname>PostgreSQL</> application interfaces, including other <productname>PostgreSQL</> application interfaces, including
those written for C++, TCL, Perl, Python and <application>ECPG</>. those written for C++, Perl, Python, Tcl and <application>ECPG</>.
So some aspects of <application>libpq</>'s behavior will be So some aspects of <application>libpq</>'s behavior will be
important to you if you use one of those packages. important to you if you use one of those packages. In particular,
<xref linkend="libpq-envars">,
<xref linkend="libpq-pgpass"> and
<xref linkend="libpq-ssl">
describe behavior that is visible to the user of any application
that uses <application>libpq</>.
</para> </para>
<para> <para>
@ -49,7 +57,7 @@ $PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.172 2004/12/20 18:15:05 tgl Exp $
application program can have several backend connections open at application program can have several backend connections open at
one time. (One reason to do that is to access more than one one time. (One reason to do that is to access more than one
database.) Each connection is represented by a database.) Each connection is represented by a
<structname>PGconn</><indexterm><primary>PGconn</></> object which <structname>PGconn</><indexterm><primary>PGconn</></> object, which
is obtained from the function <function>PQconnectdb</> or is obtained from the function <function>PQconnectdb</> or
<function>PQsetdbLogin</>. Note that these functions will always <function>PQsetdbLogin</>. Note that these functions will always
return a non-null object pointer, unless perhaps there is too return a non-null object pointer, unless perhaps there is too
@ -82,12 +90,12 @@ PGconn *PQconnectdb(const char *conninfo);
can be empty to use all default parameters, or it can contain one or more can be empty to use all default parameters, or it can contain one or more
parameter settings separated by whitespace. parameter settings separated by whitespace.
Each parameter setting is in the form <literal>keyword = value</literal>. Each parameter setting is in the form <literal>keyword = value</literal>.
(To write an empty value or a value containing Spaces around the equal sign are optional.
To write an empty value or a value containing
spaces, surround it with single quotes, e.g., spaces, surround it with single quotes, e.g.,
<literal>keyword = 'a value'</literal>. <literal>keyword = 'a value'</literal>.
Single quotes and backslashes within the value must be escaped with a Single quotes and backslashes within the value must be escaped with a
backslash, i.e., <literal>\'</literal> and <literal>\\</literal>.) backslash, i.e., <literal>\'</literal> and <literal>\\</literal>.
Spaces around the equal sign are optional.
</para> </para>
<para> <para>
@ -172,6 +180,8 @@ PGconn *PQconnectdb(const char *conninfo);
<listitem> <listitem>
<para> <para>
<productname>PostgreSQL</productname> user name to connect as. <productname>PostgreSQL</productname> user name to connect as.
Defaults to be the same as the operating system name of the user
running the application.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -235,7 +245,7 @@ PGconn *PQconnectdb(const char *conninfo);
If <productname>PostgreSQL</> is compiled without SSL support, If <productname>PostgreSQL</> is compiled without SSL support,
using option <literal>require</> will cause an error, while using option <literal>require</> will cause an error, while
options <literal>allow</> and <literal>prefer</> will be options <literal>allow</> and <literal>prefer</> will be
tolerated but <application>libpq</> will be unable to negotiate accepted but <application>libpq</> will not in fact attempt
an <acronym>SSL</> an <acronym>SSL</>
connection.<indexterm><primary>SSL</><secondary connection.<indexterm><primary>SSL</><secondary
sortas="libpq">with libpq</></indexterm> sortas="libpq">with libpq</></indexterm>
@ -273,8 +283,8 @@ PGconn *PQconnectdb(const char *conninfo);
name in <filename>pg_service.conf</filename> that holds additional connection parameters. name in <filename>pg_service.conf</filename> that holds additional connection parameters.
This allows applications to specify only a service name so connection parameters This allows applications to specify only a service name so connection parameters
can be centrally maintained. See can be centrally maintained. See
<filename><replaceable>PREFIX</>/share/pg_service.conf.sample</> for <filename>share/pg_service.conf.sample</> in the installation
information on how to set up the file. directory for information on how to set up the file.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -283,7 +293,7 @@ PGconn *PQconnectdb(const char *conninfo);
If any parameter is unspecified, then the corresponding If any parameter is unspecified, then the corresponding
environment variable (see <xref linkend="libpq-envars">) environment variable (see <xref linkend="libpq-envars">)
is checked. If the environment variable is not set either, is checked. If the environment variable is not set either,
then built-in defaults are used. then the indicated built-in defaults are used.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -489,7 +499,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn);
</variablelist> </variablelist>
Note that, although these constants will remain (in order to maintain Note that, although these constants will remain (in order to maintain
compatibility), an application should never rely upon these appearing in a compatibility), an application should never rely upon these occurring in a
particular order, or at all, or on the status always being one of these particular order, or at all, or on the status always being one of these
documented values. An application might do something like this: documented values. An application might do something like this:
<programlisting> <programlisting>
@ -877,7 +887,8 @@ Pre-3.0-protocol servers do not report parameter settings, but
<application>libpq</> includes logic to obtain values for <application>libpq</> includes logic to obtain values for
<literal>server_version</> and <literal>client_encoding</> anyway. <literal>server_version</> and <literal>client_encoding</> anyway.
Applications are encouraged to use <function>PQparameterStatus</> Applications are encouraged to use <function>PQparameterStatus</>
rather than ad-hoc code to determine these values. (Beware however rather than <foreignphrase>ad hoc</> code to determine these values.
(Beware however
that on a pre-3.0 connection, changing <literal>client_encoding</> via that on a pre-3.0 connection, changing <literal>client_encoding</> via
<command>SET</> after connection startup will not be reflected by <command>SET</> after connection startup will not be reflected by
<function>PQparameterStatus</>.) For <literal>server_version</>, <function>PQparameterStatus</>.) For <literal>server_version</>,
@ -905,8 +916,8 @@ Applications may wish to use this to determine whether certain features
are supported. are supported.
Currently, the possible values are 2 (2.0 protocol), 3 (3.0 protocol), Currently, the possible values are 2 (2.0 protocol), 3 (3.0 protocol),
or zero (connection bad). This will not change after connection or zero (connection bad). This will not change after connection
startup is complete, but it could theoretically change during a reset. startup is complete, but it could theoretically change during a connection
The 3.0 protocol will normally be used when communicating with reset. The 3.0 protocol will normally be used when communicating with
<productname>PostgreSQL</> 7.4 or later servers; pre-7.4 servers support <productname>PostgreSQL</> 7.4 or later servers; pre-7.4 servers support
only protocol 2.0. (Protocol 1.0 is obsolete and not supported by <application>libpq</application>.) only protocol 2.0. (Protocol 1.0 is obsolete and not supported by <application>libpq</application>.)
</para> </para>
@ -950,7 +961,9 @@ char *PQerrorMessage(const PGconn *conn);
<function>PQerrorMessage</function> result will <function>PQerrorMessage</function> result will
include a trailing newline. The caller should not free the result include a trailing newline. The caller should not free the result
directly. It will be freed when the associated <structname>PGconn</> directly. It will be freed when the associated <structname>PGconn</>
handle is passed to <function>PQfinish</function>. handle is passed to <function>PQfinish</function>. The result string
should not be expected to remain the same across operations on the
<literal>PGconn</> structure.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -1014,7 +1027,7 @@ SSL *PQgetssl(const PGconn *conn);
</para> </para>
<para> <para>
You must define <symbol>USE_SSL</symbol> in order to get the You must define <symbol>USE_SSL</symbol> in order to get the
prototype for this function. Doing this will also correct prototype for this function. Doing this will also
automatically include <filename>ssl.h</filename> from <productname>OpenSSL</productname>. automatically include <filename>ssl.h</filename> from <productname>OpenSSL</productname>.
</para> </para>
</listitem> </listitem>
@ -1768,7 +1781,8 @@ exactly which table is referenced.
<para> <para>
Returns the column number (within its table) of the column making up Returns the column number (within its table) of the column making up
the specified query result column. the specified query result column.
Result column numbers start at 0. Query-result column numbers start at 0, but table columns have nonzero
numbers.
<synopsis> <synopsis>
int PQftablecol(const PGresult *res, int PQftablecol(const PGresult *res,
int column_number); int column_number);
@ -2678,7 +2692,7 @@ server, using the functions described in this section.
<listitem> <listitem>
<para> <para>
Creates a data structure containing the information needed to cancel Creates a data structure containing the information needed to cancel
a command issued through a particular database connection. a command issued through a particular database connection.
<synopsis> <synopsis>
PGcancel *PQgetCancel(PGconn *conn); PGcancel *PQgetCancel(PGconn *conn);
</synopsis> </synopsis>
@ -3614,8 +3628,9 @@ information into simple client applications, for example.
</indexterm> </indexterm>
<envar>PGHOST</envar> sets the database server name. <envar>PGHOST</envar> sets the database server name.
If this begins with a slash, it specifies Unix-domain communication If this begins with a slash, it specifies Unix-domain communication
rather than TCP/IP communication; the value is the name of the rather than TCP/IP communication; the value is then the name of the
directory in which the socket file is stored (default <filename>/tmp</filename>). directory in which the socket file is stored (in a default installation
setup this would be <filename>/tmp</filename>).
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
@ -3624,8 +3639,8 @@ directory in which the socket file is stored (default <filename>/tmp</filename>)
<primary><envar>PGHOSTADDR</envar></primary> <primary><envar>PGHOSTADDR</envar></primary>
</indexterm> </indexterm>
<envar>PGHOSTADDR</envar> specifies the numeric IP address of the database <envar>PGHOSTADDR</envar> specifies the numeric IP address of the database
server. This can be set instead of <envar>PGHOST</envar> to avoid DNS server. This can be set instead of or in addition to <envar>PGHOST</envar>
lookup overhead. See the documentation of to avoid DNS lookup overhead. See the documentation of
these parameters, under <function>PQconnectdb</function> above, for details these parameters, under <function>PQconnectdb</function> above, for details
on their interaction. on their interaction.
</para> </para>
@ -3666,7 +3681,7 @@ sets the user name used to connect to the database.
<envar>PGPASSWORD</envar> <envar>PGPASSWORD</envar>
sets the password used if the server demands password sets the password used if the server demands password
authentication. This environment variable is deprecated for security authentication. This environment variable is deprecated for security
reasons; consider migrating to use the <filename>$HOME/.pgpass</> reasons; instead consider using the <filename>$HOME/.pgpass</>
file (see <xref linkend="libpq-pgpass">). file (see <xref linkend="libpq-pgpass">).
</para> </para>
</listitem> </listitem>
@ -3718,9 +3733,9 @@ trying an <acronym>SSL</> connection; <literal>prefer</>
connection, then if that fails, trying a regular non-<acronym>SSL</> connection, then if that fails, trying a regular non-<acronym>SSL</>
connection; <literal>require</> will try only an <acronym>SSL</> connection; <literal>require</> will try only an <acronym>SSL</>
connection. If <productname>PostgreSQL</> is compiled without SSL support, connection. If <productname>PostgreSQL</> is compiled without SSL support,
using option <literal>require</> will cause an error, and options using option <literal>require</> will cause an error, while options
<literal>allow</> and <literal>prefer</> will be tolerated but <literal>allow</> and <literal>prefer</> will be accepted but
<application>libpq</> will be unable to negotiate an <acronym>SSL</> <application>libpq</> will not in fact attempt an <acronym>SSL</>
connection. connection.
</para> </para>
</listitem> </listitem>
@ -3758,7 +3773,9 @@ It is not recommended to set the timeout to less than 2 seconds.
<para> <para>
The following environment variables can be used to specify default The following environment variables can be used to specify default
behavior for each <productname>PostgreSQL</productname> session. behavior for each <productname>PostgreSQL</productname> session.
(See also the <command>ALTER USER</> and <command>ALTER DATABASE</> (See also the
<xref linkend="sql-alteruser" endterm="sql-alteruser-title"> and
<xref linkend="sql-alterdatabase" endterm="sql-alterdatabase-title">
commands for ways to set default behavior on a per-user or per-database commands for ways to set default behavior on a per-user or per-database
basis.) basis.)
@ -3803,6 +3820,18 @@ sets the default mode for the genetic query optimizer.
(Equivalent to <literal>SET geqo TO ...</literal>.) (Equivalent to <literal>SET geqo TO ...</literal>.)
</para> </para>
</listitem> </listitem>
</itemizedlist>
Refer to the <acronym>SQL</acronym> command
<xref linkend="sql-set" endterm="sql-set-title">
for information on correct values for these environment variables.
</para>
<para>
The following environment variables determine internal behavior of
<application>libpq</application>; they override compiled-in defaults.
<itemizedlist>
<listitem> <listitem>
<para> <para>
<indexterm> <indexterm>
@ -3818,13 +3847,11 @@ sets the directory containing the <filename>pg_service.conf</> file.
<primary><envar>PGLOCALEDIR</envar></primary> <primary><envar>PGLOCALEDIR</envar></primary>
</indexterm> </indexterm>
<envar>PGLOCALEDIR</envar> <envar>PGLOCALEDIR</envar>
sets the directory containing the <literal>locale</> files. sets the directory containing the <literal>locale</> files for message
internationalization.
</para> </para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
Refer to the <acronym>SQL</acronym> command <command>SET</command>
for information on correct values for these environment variables.
</para> </para>
</sect1> </sect1>
@ -3910,7 +3937,7 @@ If the permissions are less strict than this, the file will be ignored.
<para> <para>
<application>libpq</application> is reentrant and thread-safe if the <application>libpq</application> is reentrant and thread-safe if the
<filename>configure</filename> command-line option <filename>configure</filename> command-line option
<literal>--enable-thread-safety</> has been used when the <literal>--enable-thread-safety</> was used when the
<productname>PostgreSQL</productname> distribution was built. In <productname>PostgreSQL</productname> distribution was built. In
addition, you might need to use additional compiler command-line addition, you might need to use additional compiler command-line
options when you compile your application code. Refer to your options when you compile your application code. Refer to your
@ -3974,7 +4001,8 @@ your library might not match the library used to build the binaries.
</indexterm> </indexterm>
<para> <para>
To build (i.e., compile and link) your <application>libpq</application> programs you need to To build (i.e., compile and link) a program using
<application>libpq</application> you need to
do all of the following things: do all of the following things:
<itemizedlist> <itemizedlist>

52
doc/src/sgml/lobj.sgml
View File

@ -1,5 +1,5 @@
<!-- <!--
$PostgreSQL: pgsql/doc/src/sgml/lobj.sgml,v 1.33 2003/11/29 19:51:37 pgsql Exp $ $PostgreSQL: pgsql/doc/src/sgml/lobj.sgml,v 1.34 2004/12/28 22:47:15 tgl Exp $
--> -->
<chapter id="largeObjects"> <chapter id="largeObjects">
@ -9,15 +9,11 @@ $PostgreSQL: pgsql/doc/src/sgml/lobj.sgml,v 1.33 2003/11/29 19:51:37 pgsql Exp $
<indexterm><primary>BLOB</><see>large object</></> <indexterm><primary>BLOB</><see>large object</></>
<para> <para>
In <productname>PostgreSQL</productname> releases prior to 7.1, <productname>PostgreSQL</productname> has a <firstterm>large object</>
the size of any row in the database could not exceed the size of a facility, which provides stream-style access to user data that is stored
data page. Since the size of a data page is 8192 bytes (the in a special large-object structure. Streaming access is useful
default, which can be raised up to 32768), the upper limit on the when working with data values that are too large to manipulate
size of a data value was relatively low. To support the storage of conveniently as a whole.
larger atomic values, <productname>PostgreSQL</productname>
provided and continues to provide a large object interface. This
interface provides file-oriented access to user data that is stored in
a special large-object structure.
</para> </para>
<para> <para>
@ -59,10 +55,13 @@ $PostgreSQL: pgsql/doc/src/sgml/lobj.sgml,v 1.33 2003/11/29 19:51:37 pgsql Exp $
<indexterm><primary>sliced bread</><see>TOAST</></indexterm> <indexterm><primary>sliced bread</><see>TOAST</></indexterm>
<productname>PostgreSQL 7.1</productname> introduced a mechanism <productname>PostgreSQL 7.1</productname> introduced a mechanism
(nicknamed <quote><acronym>TOAST</acronym></quote>) that allows (nicknamed <quote><acronym>TOAST</acronym></quote>) that allows
data rows to be much larger than individual data pages. This data values to be much larger than single pages. This
makes the large object interface partially obsolete. One makes the large object facility partially obsolete. One
remaining advantage of the large object interface is that it allows values up remaining advantage of the large object facility is that it allows values
to 2 GB in size, whereas <acronym>TOAST</acronym> can only handle 1 GB. up to 2 GB in size, whereas <acronym>TOAST</acronym>ed fields can be at
most 1 GB. Also, large objects can be manipulated piece-by-piece much more
easily than ordinary data fields, so the practical limits are considerably
different.
</para> </para>
</sect1> </sect1>
@ -117,7 +116,7 @@ Oid lo_creat(PGconn *conn, int mode);
creates a new large object. creates a new large object.
<replaceable class="parameter">mode</replaceable> is a bit mask <replaceable class="parameter">mode</replaceable> is a bit mask
describing several different attributes of the new describing several different attributes of the new
object. The symbolic constants listed here are defined object. The symbolic constants used here are defined
in the header file <filename>libpq/libpq-fs.h</filename>. in the header file <filename>libpq/libpq-fs.h</filename>.
The access type (read, write, or both) is controlled by The access type (read, write, or both) is controlled by
or'ing together the bits <symbol>INV_READ</symbol> and or'ing together the bits <symbol>INV_READ</symbol> and
@ -149,6 +148,9 @@ Oid lo_import(PGconn *conn, const char *filename);
specifies the operating system name of specifies the operating system name of
the file to be imported as a large object. the file to be imported as a large object.
The return value is the OID that was assigned to the new large object. The return value is the OID that was assigned to the new large object.
Note that the file is read by the client interface library, not by
the server; so it must exist in the client filesystem and be readable
by the client application.
</para> </para>
</sect2> </sect2>
@ -164,7 +166,9 @@ int lo_export(PGconn *conn, Oid lobjId, const char *filename);
<indexterm><primary>lo_export</></> <indexterm><primary>lo_export</></>
The <parameter>lobjId</parameter> argument specifies the OID of the large The <parameter>lobjId</parameter> argument specifies the OID of the large
object to export and the <parameter>filename</parameter> argument specifies object to export and the <parameter>filename</parameter> argument specifies
the operating system name name of the file. the operating system name of the file.
Note that the file is written by the client interface library, not by
the server.
</para> </para>
</sect2> </sect2>
@ -200,7 +204,7 @@ int lo_write(PGconn *conn, int fd, const char *buf, size_t len);
</synopsis> </synopsis>
<indexterm><primary>lo_write</></> writes <indexterm><primary>lo_write</></> writes
<parameter>len</parameter> bytes from <parameter>buf</parameter> <parameter>len</parameter> bytes from <parameter>buf</parameter>
to large object <parameter>fd</>. The <parameter>fd</parameter> to large object descriptor <parameter>fd</>. The <parameter>fd</parameter>
argument must have been returned by a previous argument must have been returned by a previous
<function>lo_open</function>. The number of bytes actually <function>lo_open</function>. The number of bytes actually
written is returned. In the event of an error, the return value written is returned. In the event of an error, the return value
@ -217,7 +221,7 @@ int lo_write(PGconn *conn, int fd, const char *buf, size_t len);
int lo_read(PGconn *conn, int fd, char *buf, size_t len); int lo_read(PGconn *conn, int fd, char *buf, size_t len);
</synopsis> </synopsis>
<indexterm><primary>lo_read</></> reads <indexterm><primary>lo_read</></> reads
<parameter>len</parameter> bytes from large object <parameter>len</parameter> bytes from large object descriptor
<parameter>fd</parameter> into <parameter>buf</parameter>. The <parameter>fd</parameter> into <parameter>buf</parameter>. The
<parameter>fd</parameter> argument must have been returned by a <parameter>fd</parameter> argument must have been returned by a
previous <function>lo_open</function>. The number of bytes previous <function>lo_open</function>. The number of bytes
@ -227,16 +231,16 @@ int lo_read(PGconn *conn, int fd, char *buf, size_t len);
</sect2> </sect2>
<sect2> <sect2>
<title>Seeking on a Large Object</title> <title>Seeking in a Large Object</title>
<para> <para>
To change the current read or write location on a large To change the current read or write location associated with a
object, call large object descriptor, call
<synopsis> <synopsis>
int lo_lseek(PGconn *conn, int fd, int offset, int whence); int lo_lseek(PGconn *conn, int fd, int offset, int whence);
</synopsis> </synopsis>
<indexterm><primary>lo_lseek</></> This function moves the <indexterm><primary>lo_lseek</></> This function moves the
current location pointer for the large object described by current location pointer for the large object descriptor identified by
<parameter>fd</> to the new location specified by <parameter>fd</> to the new location specified by
<parameter>offset</>. The valid values for <parameter>whence</> <parameter>offset</>. The valid values for <parameter>whence</>
are <symbol>SEEK_SET</> (seek from object start), are <symbol>SEEK_SET</> (seek from object start),
@ -250,7 +254,7 @@ int lo_lseek(PGconn *conn, int fd, int offset, int whence);
<title>Obtaining the Seek Position of a Large Object</title> <title>Obtaining the Seek Position of a Large Object</title>
<para> <para>
To obtain the current read or write location of a large object, To obtain the current read or write location of a large object descriptor,
call call
<synopsis> <synopsis>
int lo_tell(PGconn *conn, int fd); int lo_tell(PGconn *conn, int fd);
@ -264,7 +268,7 @@ int lo_tell(PGconn *conn, int fd);
<title>Closing a Large Object Descriptor</title> <title>Closing a Large Object Descriptor</title>
<para> <para>
A large object may be closed by calling A large object descriptor may be closed by calling
<synopsis> <synopsis>
int lo_close(PGconn *conn, int fd); int lo_close(PGconn *conn, int fd);
</synopsis> </synopsis>