mirror of https://github.com/postgres/postgres
More minor updates and copy-editing.
This commit is contained in:
Tom Lane
parent
7737d01ece
commit
797c2b2501
|
|
@ -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">
|
||||
|
|
@ -19,7 +19,7 @@ $PostgreSQL: pgsql/doc/src/sgml/ecpg.sgml,v 1.59 2003/12/26 20:00:00 meskes Exp
|
|||
</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
|
||||
many resources about SQL.
|
||||
</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
|
||||
programming language, in this case C, mixed with SQL commands in
|
||||
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
|
||||
compilation tool chain.
|
||||
compiler.
|
||||
</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>
|
||||
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
|
||||
code inserted to perform database-related actions. This special
|
||||
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 ...;
|
||||
</programlisting>
|
||||
These statements syntactically take the place of a C statement.
|
||||
Depending on the particular statement, they may appear in the
|
||||
global context or within a function. Embedded
|
||||
Depending on the particular statement, they may appear at the
|
||||
global level or within a function. Embedded
|
||||
<acronym>SQL</acronym> statements follow the case-sensitivity rules
|
||||
of normal <acronym>SQL</acronym> code, and not those of C.
|
||||
</para>
|
||||
|
|
@ -326,9 +326,9 @@ EXEC SQL COMMIT;
|
|||
<para>
|
||||
In the default mode, statements are committed only when
|
||||
<command>EXEC SQL COMMIT</command> is issued. The embedded SQL
|
||||
interface also supports autocommit of transactions (as known from
|
||||
other interfaces) via the <option>-t</option> command-line option
|
||||
to <command>ecpg</command> (see below) or via the <literal>EXEC SQL
|
||||
interface also supports autocommit of transactions (similar to
|
||||
<application>libpq</> behavior) via the <option>-t</option> command-line
|
||||
option to <command>ecpg</command> (see below) or via the <literal>EXEC SQL
|
||||
SET AUTOCOMMIT TO ON</literal> statement. In autocommit mode, each
|
||||
command is automatically committed unless it is inside an explicit
|
||||
transaction block. This mode can be explicitly turned off using
|
||||
|
|
@ -448,7 +448,7 @@ char foo[16], bar[16];
|
|||
<para>
|
||||
The declarations are also echoed to the output file as a normal C
|
||||
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.
|
||||
</para>
|
||||
|
||||
|
|
@ -553,7 +553,7 @@ do {
|
|||
second host variable specification to each host variable that
|
||||
contains data. This second host variable is called the
|
||||
<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
|
||||
retrieval of null values correctly:
|
||||
<programlisting>
|
||||
|
|
@ -1043,7 +1043,7 @@ static void set_error_handler(void)
|
|||
<title>sqlca</title>
|
||||
|
||||
<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>
|
||||
that has the following structure:
|
||||
<programlisting>
|
||||
|
|
@ -1064,7 +1064,7 @@ struct
|
|||
} sqlca;
|
||||
</programlisting>
|
||||
(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
|
||||
<varname>errno</varname>.)
|
||||
</para>
|
||||
|
|
@ -1132,7 +1132,7 @@ struct
|
|||
<para>
|
||||
The structure <varname>sqlca</varname> is not defined in the SQL
|
||||
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
|
||||
different implementations carefully.
|
||||
</para>
|
||||
|
|
@ -1539,7 +1539,7 @@ ecpg prog1.pgc
|
|||
<programlisting>
|
||||
cc -c prog1.c
|
||||
</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</> in a location that is not searched by
|
||||
default, you have to add an option such as
|
||||
|
|
@ -1575,9 +1575,9 @@ ECPG = ecpg
|
|||
</para>
|
||||
|
||||
<para>
|
||||
<application>ecpg</application> is thread-safe if it is compiled using
|
||||
the <option>--enable-thread-safety</> <filename>configure</filename>
|
||||
command-line option. (You might need to use other threading
|
||||
The <application>ecpg</application> library is thread-safe if it is built
|
||||
using the <option>--enable-thread-safety</> command-line option to
|
||||
<filename>configure</filename>. (You might need to use other threading
|
||||
command-line options to compile your client code.)
|
||||
</para>
|
||||
</sect1>
|
||||
|
|
@ -1621,7 +1621,7 @@ ECPG = ecpg
|
|||
<title>Internals</title>
|
||||
|
||||
<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
|
||||
users understand how to use <application>ECPG</application>.
|
||||
</para>
|
||||
|
|
|
|||
|
|
@ -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">
|
||||
|
|
@ -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,
|
||||
and managing it is difficult. We have found that many
|
||||
enhancements to <productname>PostgreSQL</productname> can be more
|
||||
efficiently developed independently of the main project. They can
|
||||
have their own developer teams, email lists, their own bug tracking,
|
||||
and their own release schedule. While their independence makes
|
||||
development easier, it makes user's jobs harder. They have to hunt
|
||||
efficiently developed separately from the core project. Separate
|
||||
projects can
|
||||
have their own developer teams, email lists, bug tracking,
|
||||
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.
|
||||
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.
|
||||
</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">
|
||||
<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>
|
||||
To use other interfaces, you have to do some searching. For example,
|
||||
<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:
|
||||
Some of the more popular interfaces are:
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
|
|
@ -53,6 +62,15 @@ $PostgreSQL: pgsql/doc/src/sgml/external-projects.sgml,v 1.5 2004/12/13 18:05:08
|
|||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>pgjdbc</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A <application>JDBC</> interface.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>Npgsql</term>
|
||||
<listitem>
|
||||
|
|
@ -64,19 +82,19 @@ $PostgreSQL: pgsql/doc/src/sgml/external-projects.sgml,v 1.5 2004/12/13 18:05:08
|
|||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>libpq++</term>
|
||||
<term>libpqxx</term>
|
||||
<listitem>
|
||||
<para>
|
||||
An older <application>C++</> interface.
|
||||
A newer <application>C++</> interface.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>libpqxx</term>
|
||||
<term>libpq++</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A newer <application>C++</> interface.
|
||||
An older <application>C++</> interface.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
|
@ -101,11 +119,20 @@ $PostgreSQL: pgsql/doc/src/sgml/external-projects.sgml,v 1.5 2004/12/13 18:05:08
|
|||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>pgtclng</term>
|
||||
<listitem>
|
||||
<para>
|
||||
A newer version of the <application>Tcl</> interface.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term>pgtcl</term>
|
||||
<listitem>
|
||||
<para>
|
||||
The original version of the <application>TCL</> interface.
|
||||
The original version of the <application>Tcl</> interface.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
|
@ -119,35 +146,9 @@ $PostgreSQL: pgsql/doc/src/sgml/external-projects.sgml,v 1.5 2004/12/13 18:05:08
|
|||
</listitem>
|
||||
</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>
|
||||
</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 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</>
|
||||
replication solutions are developed externally. For example,
|
||||
<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>
|
||||
|
|
|
|||
|
|
@ -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">
|
||||
<title>The Information Schema</title>
|
||||
|
|
@ -30,7 +30,7 @@
|
|||
exists in all databases. The owner of this schema is the initial
|
||||
database user in the cluster, and that user naturally has all the
|
||||
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>
|
||||
|
|
@ -1003,7 +1003,7 @@
|
|||
function (as parameter or return type) and stores some information
|
||||
about how the data type is used in that instance (for example, the
|
||||
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
|
||||
(table, domain, function). This view is probably not useful for
|
||||
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
|
||||
key, or foreign key constraint. Check constraints are not included
|
||||
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>
|
||||
|
||||
<table>
|
||||
|
|
@ -3320,7 +3320,7 @@ ORDER BY c.ordinal_position;
|
|||
|
||||
<para>
|
||||
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
|
||||
linkend="features"> for background information on feature packages.
|
||||
</para>
|
||||
|
|
@ -3888,7 +3888,7 @@ ORDER BY c.ordinal_position;
|
|||
incompatibilities with the SQL standard that affect the
|
||||
representation in the information schema. First, trigger names are
|
||||
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
|
||||
different tables. (<literal>trigger_catalog</literal> and
|
||||
<literal>trigger_schema</literal> are really the values pertaining
|
||||
|
|
|
|||
|
|
@ -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">
|
||||
|
|
@ -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
|
||||
client programs to pass queries to the <productname>PostgreSQL</>
|
||||
backend server and to receive the results of these queries.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<application>libpq</> is also the underlying engine for several
|
||||
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
|
||||
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>
|
||||
|
|
@ -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
|
||||
one time. (One reason to do that is to access more than one
|
||||
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
|
||||
<function>PQsetdbLogin</>. Note that these functions will always
|
||||
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
|
||||
parameter settings separated by whitespace.
|
||||
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.,
|
||||
<literal>keyword = 'a value'</literal>.
|
||||
Single quotes and backslashes within the value must be escaped with a
|
||||
backslash, i.e., <literal>\'</literal> and <literal>\\</literal>.)
|
||||
Spaces around the equal sign are optional.
|
||||
backslash, i.e., <literal>\'</literal> and <literal>\\</literal>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
|
|
@ -172,6 +180,8 @@ PGconn *PQconnectdb(const char *conninfo);
|
|||
<listitem>
|
||||
<para>
|
||||
<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>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
|
@ -235,7 +245,7 @@ PGconn *PQconnectdb(const char *conninfo);
|
|||
If <productname>PostgreSQL</> is compiled without SSL support,
|
||||
using option <literal>require</> will cause an error, while
|
||||
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</>
|
||||
connection.<indexterm><primary>SSL</><secondary
|
||||
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.
|
||||
This allows applications to specify only a service name so connection parameters
|
||||
can be centrally maintained. See
|
||||
<filename><replaceable>PREFIX</>/share/pg_service.conf.sample</> for
|
||||
information on how to set up the file.
|
||||
<filename>share/pg_service.conf.sample</> in the installation
|
||||
directory for information on how to set up the file.
|
||||
</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
|
@ -283,7 +293,7 @@ PGconn *PQconnectdb(const char *conninfo);
|
|||
If any parameter is unspecified, then the corresponding
|
||||
environment variable (see <xref linkend="libpq-envars">)
|
||||
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>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
|
@ -489,7 +499,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn);
|
|||
</variablelist>
|
||||
|
||||
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
|
||||
documented values. An application might do something like this:
|
||||
<programlisting>
|
||||
|
|
@ -877,7 +887,8 @@ Pre-3.0-protocol servers do not report parameter settings, but
|
|||
<application>libpq</> includes logic to obtain values for
|
||||
<literal>server_version</> and <literal>client_encoding</> anyway.
|
||||
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
|
||||
<command>SET</> after connection startup will not be reflected by
|
||||
<function>PQparameterStatus</>.) For <literal>server_version</>,
|
||||
|
|
@ -905,8 +916,8 @@ Applications may wish to use this to determine whether certain features
|
|||
are supported.
|
||||
Currently, the possible values are 2 (2.0 protocol), 3 (3.0 protocol),
|
||||
or zero (connection bad). This will not change after connection
|
||||
startup is complete, but it could theoretically change during a reset.
|
||||
The 3.0 protocol will normally be used when communicating with
|
||||
startup is complete, but it could theoretically change during a connection
|
||||
reset. The 3.0 protocol will normally be used when communicating with
|
||||
<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>.)
|
||||
</para>
|
||||
|
|
@ -950,7 +961,9 @@ char *PQerrorMessage(const PGconn *conn);
|
|||
<function>PQerrorMessage</function> result will
|
||||
include a trailing newline. The caller should not free the result
|
||||
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>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
|
@ -1014,7 +1027,7 @@ SSL *PQgetssl(const PGconn *conn);
|
|||
</para>
|
||||
<para>
|
||||
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>.
|
||||
</para>
|
||||
</listitem>
|
||||
|
|
@ -1768,7 +1781,8 @@ exactly which table is referenced.
|
|||
<para>
|
||||
Returns the column number (within its table) of the column making up
|
||||
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>
|
||||
int PQftablecol(const PGresult *res,
|
||||
int column_number);
|
||||
|
|
@ -2678,7 +2692,7 @@ server, using the functions described in this section.
|
|||
<listitem>
|
||||
<para>
|
||||
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>
|
||||
PGcancel *PQgetCancel(PGconn *conn);
|
||||
</synopsis>
|
||||
|
|
@ -3614,8 +3628,9 @@ information into simple client applications, for example.
|
|||
</indexterm>
|
||||
<envar>PGHOST</envar> sets the database server name.
|
||||
If this begins with a slash, it specifies Unix-domain communication
|
||||
rather than TCP/IP communication; the value is the name of the
|
||||
directory in which the socket file is stored (default <filename>/tmp</filename>).
|
||||
rather than TCP/IP communication; the value is then the name of the
|
||||
directory in which the socket file is stored (in a default installation
|
||||
setup this would be <filename>/tmp</filename>).
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
|
|
@ -3624,8 +3639,8 @@ directory in which the socket file is stored (default <filename>/tmp</filename>)
|
|||
<primary><envar>PGHOSTADDR</envar></primary>
|
||||
</indexterm>
|
||||
<envar>PGHOSTADDR</envar> specifies the numeric IP address of the database
|
||||
server. This can be set instead of <envar>PGHOST</envar> to avoid DNS
|
||||
lookup overhead. See the documentation of
|
||||
server. This can be set instead of or in addition to <envar>PGHOST</envar>
|
||||
to avoid DNS lookup overhead. See the documentation of
|
||||
these parameters, under <function>PQconnectdb</function> above, for details
|
||||
on their interaction.
|
||||
</para>
|
||||
|
|
@ -3666,7 +3681,7 @@ sets the user name used to connect to the database.
|
|||
<envar>PGPASSWORD</envar>
|
||||
sets the password used if the server demands password
|
||||
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">).
|
||||
</para>
|
||||
</listitem>
|
||||
|
|
@ -3718,9 +3733,9 @@ trying an <acronym>SSL</> connection; <literal>prefer</>
|
|||
connection, then if that fails, trying a regular non-<acronym>SSL</>
|
||||
connection; <literal>require</> will try only an <acronym>SSL</>
|
||||
connection. If <productname>PostgreSQL</> is compiled without SSL support,
|
||||
using option <literal>require</> will cause an error, and options
|
||||
<literal>allow</> and <literal>prefer</> will be tolerated but
|
||||
<application>libpq</> will be unable to negotiate an <acronym>SSL</>
|
||||
using option <literal>require</> will cause an error, while options
|
||||
<literal>allow</> and <literal>prefer</> will be accepted but
|
||||
<application>libpq</> will not in fact attempt an <acronym>SSL</>
|
||||
connection.
|
||||
</para>
|
||||
</listitem>
|
||||
|
|
@ -3758,7 +3773,9 @@ It is not recommended to set the timeout to less than 2 seconds.
|
|||
<para>
|
||||
The following environment variables can be used to specify default
|
||||
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
|
||||
basis.)
|
||||
|
||||
|
|
@ -3803,6 +3820,18 @@ sets the default mode for the genetic query optimizer.
|
|||
(Equivalent to <literal>SET geqo TO ...</literal>.)
|
||||
</para>
|
||||
</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>
|
||||
<para>
|
||||
<indexterm>
|
||||
|
|
@ -3818,13 +3847,11 @@ sets the directory containing the <filename>pg_service.conf</> file.
|
|||
<primary><envar>PGLOCALEDIR</envar></primary>
|
||||
</indexterm>
|
||||
<envar>PGLOCALEDIR</envar>
|
||||
sets the directory containing the <literal>locale</> files.
|
||||
sets the directory containing the <literal>locale</> files for message
|
||||
internationalization.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
Refer to the <acronym>SQL</acronym> command <command>SET</command>
|
||||
for information on correct values for these environment variables.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
|
@ -3910,7 +3937,7 @@ If the permissions are less strict than this, the file will be ignored.
|
|||
<para>
|
||||
<application>libpq</application> is reentrant and thread-safe if the
|
||||
<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
|
||||
addition, you might need to use additional compiler command-line
|
||||
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>
|
||||
|
||||
<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:
|
||||
|
||||
<itemizedlist>
|
||||
|
|
|
|||
|
|
@ -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">
|
||||
|
|
@ -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</></>
|
||||
|
||||
<para>
|
||||
In <productname>PostgreSQL</productname> releases prior to 7.1,
|
||||
the size of any row in the database could not exceed the size of a
|
||||
data page. Since the size of a data page is 8192 bytes (the
|
||||
default, which can be raised up to 32768), the upper limit on the
|
||||
size of a data value was relatively low. To support the storage of
|
||||
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.
|
||||
<productname>PostgreSQL</productname> has a <firstterm>large object</>
|
||||
facility, which provides stream-style access to user data that is stored
|
||||
in a special large-object structure. Streaming access is useful
|
||||
when working with data values that are too large to manipulate
|
||||
conveniently as a whole.
|
||||
</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>
|
||||
<productname>PostgreSQL 7.1</productname> introduced a mechanism
|
||||
(nicknamed <quote><acronym>TOAST</acronym></quote>) that allows
|
||||
data rows to be much larger than individual data pages. This
|
||||
makes the large object interface partially obsolete. One
|
||||
remaining advantage of the large object interface is that it allows values up
|
||||
to 2 GB in size, whereas <acronym>TOAST</acronym> can only handle 1 GB.
|
||||
data values to be much larger than single pages. This
|
||||
makes the large object facility partially obsolete. One
|
||||
remaining advantage of the large object facility is that it allows values
|
||||
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>
|
||||
|
||||
</sect1>
|
||||
|
|
@ -117,7 +116,7 @@ Oid lo_creat(PGconn *conn, int mode);
|
|||
creates a new large object.
|
||||
<replaceable class="parameter">mode</replaceable> is a bit mask
|
||||
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>.
|
||||
The access type (read, write, or both) is controlled by
|
||||
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
|
||||
the file to be imported as a 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>
|
||||
</sect2>
|
||||
|
||||
|
|
@ -164,7 +166,9 @@ int lo_export(PGconn *conn, Oid lobjId, const char *filename);
|
|||
<indexterm><primary>lo_export</></>
|
||||
The <parameter>lobjId</parameter> argument specifies the OID of the large
|
||||
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>
|
||||
</sect2>
|
||||
|
||||
|
|
@ -200,7 +204,7 @@ int lo_write(PGconn *conn, int fd, const char *buf, size_t len);
|
|||
</synopsis>
|
||||
<indexterm><primary>lo_write</></> writes
|
||||
<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
|
||||
<function>lo_open</function>. The number of bytes actually
|
||||
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);
|
||||
</synopsis>
|
||||
<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> argument must have been returned by a
|
||||
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>
|
||||
<title>Seeking on a Large Object</title>
|
||||
<title>Seeking in a Large Object</title>
|
||||
|
||||
<para>
|
||||
To change the current read or write location on a large
|
||||
object, call
|
||||
To change the current read or write location associated with a
|
||||
large object descriptor, call
|
||||
<synopsis>
|
||||
int lo_lseek(PGconn *conn, int fd, int offset, int whence);
|
||||
</synopsis>
|
||||
<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>offset</>. The valid values for <parameter>whence</>
|
||||
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>
|
||||
|
||||
<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
|
||||
<synopsis>
|
||||
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>
|
||||
|
||||
<para>
|
||||
A large object may be closed by calling
|
||||
A large object descriptor may be closed by calling
|
||||
<synopsis>
|
||||
int lo_close(PGconn *conn, int fd);
|
||||
</synopsis>
|
||||
|
|
|
|||
Loading…
Reference in New Issue