Skip to content

P
Postgres FD Implementation
Commit 797c2b25 authored by Tom Lane's avatar Tom Lane
Browse files
Options

More minor updates and copy-editing.

parent 7737d01e
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 156 additions and 123 deletions
doc/src/sgml/ecpg.sgml
View file @ 797c2b25
<!--
$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>
......
doc/src/sgml/external-projects.sgml
View file @ 797c2b25
<!--
$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>
......@@ -54,20 +63,20 @@ $PostgreSQL: pgsql/doc/src/sgml/external-projects.sgml,v 1.5 2004/12/13 18:05:08
</varlistentry>
<varlistentry>
<term>Npgsql</term>
<term>pgjdbc</term>
<listitem>
<para>
<application>.Net</> interface for more recent
<application>Windows</> applications.
A <application>JDBC</> interface.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>libpq++</term>
<term>Npgsql</term>
<listitem>
<para>
An older <application>C++</> interface.
<application>.Net</> interface for more recent
<application>Windows</> applications.
</para>
</listitem>
</varlistentry>
......@@ -82,57 +91,57 @@ $PostgreSQL: pgsql/doc/src/sgml/external-projects.sgml,v 1.5 2004/12/13 18:05:08
</varlistentry>
<varlistentry>
<term>pgperl</term>
<term>libpq++</term>
<listitem>
<para>
A <application>Perl</> interface with an <acronym>API</> similar
to <application>libpq</>.
An older <application>C++</> interface.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DBD-Pg</term>
<term>pgperl</term>
<listitem>
<para>
A <application>Perl</> interface that uses the
<acronym>DBD</>-standard <application>API</>.
A <application>Perl</> interface with an <acronym>API</> similar
to <application>libpq</>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>pgtcl</term>
<term>DBD-Pg</term>
<listitem>
<para>
The original version of the <application>TCL</> interface.
A <application>Perl</> interface that uses the
<acronym>DBD</>-standard <application>API</>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>PyGreSQL</term>
<term>pgtclng</term>
<listitem>
<para>
A <application>Python</> interface library.
A newer version of the <application>Tcl</> interface.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>pgjdbc</term>
<term>pgtcl</term>
<listitem>
<para>
A <application>JDBC</> interface.
The original version of the <application>Tcl</> interface.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>pgtclng</term>
<term>PyGreSQL</term>
<listitem>
<para>
A newer version of the <application>TCL</> interface.
A <application>Python</> interface library.
</para>
</listitem>
</varlistentry>
......@@ -140,14 +149,6 @@ $PostgreSQL: pgsql/doc/src/sgml/external-projects.sgml,v 1.5 2004/12/13 18:05:08
</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>
......
doc/src/sgml/information_schema.sgml
View file @ 797c2b25
<!-- $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
......
doc/src/sgml/libpq.sgml
View file @ 797c2b25
This diff is collapsed.
doc/src/sgml/lobj.sgml
View file @ 797c2b25
<!--
$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>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment