Skip to content

P
Postgres FD Implementation
Commit 731204e0 authored by Peter Eisentraut's avatar Peter Eisentraut
Browse files
Options

Editorial review

parent a510bf43
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 1391 additions and 1328 deletions
doc/src/sgml/biblio.sgml
View file @ 731204e0
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/biblio.sgml,v 1.16 2001/11/21 05:53:40 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/biblio.sgml,v 1.17 2002/01/07 02:29:11 petere Exp $
-->
<bibliography id="biblio">
......@@ -148,76 +148,6 @@ $Header: /cvsroot/pgsql/doc/src/sgml/biblio.sgml,v 1.16 2001/11/21 05:53:40 thom
<title>PostgreSQL-Specific Documentation</title>
<para>This section is for related documentation.</para>
<biblioentry id="admin-guide">
<title>The <productname>PostgreSQL</productname> Administrator's Guide</title>
<titleabbrev>The Administrator's Guide</titleabbrev>
<editor>
<firstname>Thomas</firstname>
<surname>Lockhart</surname>
</editor>
<pubdate>2001-04-13</pubdate>
<publisher>
<publishername>The PostgreSQL Global Development Group</publishername>
</publisher>
</biblioentry>
<biblioentry id="dev-guide">
<title>The <productname>PostgreSQL</productname> Developer's Guide</title>
<titleabbrev>The Developer's Guide</titleabbrev>
<editor>
<firstname>Thomas</firstname>
<surname>Lockhart</surname>
</editor>
<pubdate>2001-04-13</pubdate>
<publisher>
<publishername>The PostgreSQL Global Development Group</publishername>
</publisher>
</biblioentry>
<biblioentry id="pro-guide">
<title>The <productname>PostgreSQL</productname> Programmer's Guide</title>
<titleabbrev>The Programmer's Guide</titleabbrev>
<editor>
<firstname>Thomas</firstname>
<surname>Lockhart</surname>
</editor>
<pubdate>2001-04-13</pubdate>
<publisher>
<publishername>The PostgreSQL Global Development Group</publishername>
</publisher>
</biblioentry>
<biblioentry id="tutorial-guide">
<title>The <productname>PostgreSQL</productname> Tutorial Introduction</title>
<titleabbrev>The Tutorial</titleabbrev>
<editor>
<firstname>Thomas</firstname>
<surname>Lockhart</surname>
</editor>
<pubdate>2001-04-13</pubdate>
<publisher>
<publishername>The PostgreSQL Global Development Group</publishername>
</publisher>
</biblioentry>
<biblioentry id="users-guide">
<title>The <productname>PostgreSQL</productname> User's Guide</title>
<titleabbrev>The User's Guide</titleabbrev>
<editor>
<firstname>Thomas</firstname>
<surname>Lockhart</surname>
</editor>
<pubdate>2001-04-13</pubdate>
<publisher>
<publishername>The PostgreSQL Global Development Group</publishername>
</publisher>
</biblioentry>
<biblioentry id="SIM98">
<title>Enhancement of the ANSI SQL Implementation of PostgreSQL</title>
<titleabbrev>Simkovics, 1998</titleabbrev>
......
doc/src/sgml/datatype.sgml
View file @ 731204e0
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.82 2002/01/04 17:02:02 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.83 2002/01/07 02:29:11 petere Exp $
-->
<chapter id="datatype">
......@@ -270,7 +270,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.82 2002/01/04 17:02:02 th
paths, or have several possibilities for formats, such as the date
and time types.
Most of the input and output functions corresponding to the
base types (e.g., integers and floating point numbers) do some
base types (e.g., integers and floating-point numbers) do some
error-checking.
Some of the input and output functions are not invertible. That is,
the result of an output function may lose precision when compared to
......@@ -354,7 +354,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.82 2002/01/04 17:02:02 th
<para>
Numeric types consist of two-, four-, and eight-byte integers,
four- and eight-byte
floating point numbers and fixed-precision decimals.
floating-point numbers and fixed-precision decimals.
</para>
<para>
......@@ -511,7 +511,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datatype.sgml,v 1.82 2002/01/04 17:02:02 th
numbers and carry out all calculations exactly. It is especially
recommended for storing monetary amounts and other quantities
where exactness is required. However, the <type>numeric</type>
type is very slow compared to the floating point types described
type is very slow compared to the floating-point types described
in the next section.
</para>
......@@ -568,11 +568,11 @@ NUMERIC
<sect2 id="datatype-float">
<title>Floating Point Types</title>
<title>Floating-Point Types</title>
<para>
The data types <type>real</type> and <type>double
precision</type> are inexact, variable precision numeric types.
precision</type> are inexact, variable-precision numeric types.
In practice, these types are usually implementations of <acronym>IEEE</acronym> 754
binary floating point (single and double precision,
respectively), to the extent that the underlying processor,
......@@ -606,7 +606,7 @@ NUMERIC
<listitem>
<para>
Comparing two floating point values for equality may or may
Comparing two floating-point values for equality may or may
not work as expected.
</para>
</listitem>
......@@ -682,14 +682,6 @@ CREATE TABLE <replaceable class="parameter">tablename</replaceable> (
will never be duplicates, either.
</para>
<important>
<para>
The implicit sequence created for the <type>serial</type> type will
<emphasis>not</emphasis> be automatically removed when the
table is dropped.
</para>
</important>
<para>
The type names <type>serial</type> and <type>serial4</type> are
equivalent: both create <type>integer</type> columns. The type
......@@ -741,7 +733,7 @@ CREATE TABLE <replaceable class="parameter">tablename</replaceable> (<replaceabl
<para>
Input is accepted in a variety of formats, including integer and
floating point literals, as well as <quote>typical</quote>
floating-point literals, as well as <quote>typical</quote>
currency formatting, such as <literal>'$1,000.00'</literal>.
Output is in the latter form.
</para>
......@@ -1165,8 +1157,6 @@ SELECT b, char_length(b) FROM test2;
escape character.
</para>
<sect2 id="datatype-binary-compat">
<title>Compatibility</title>
<para>
<type>Bytea</type> provides most of the functionality of the binary
string type per SQL99 section 4.3. A comparison of SQL99 Binary
......@@ -1248,7 +1238,6 @@ SELECT b, char_length(b) FROM test2;
</tbody>
</tgroup>
</table>
</sect2>
</sect1>
......@@ -1335,7 +1324,7 @@ SELECT b, char_length(b) FROM test2;
specifies the number of fractional digits retained in the seconds
field. By default, there is no explicit bound on precision. The
effective limit of precision is determined by the underlying double
precision floating point number used to store values (in seconds
precision floating-point number used to store values (in seconds
for <type>interval</type> and
in seconds since 2000-01-01 for <type>timestamp</type>). The
useful range of <replaceable>p</replaceable> is from 0 to about
......
doc/src/sgml/dfunc.sgml
View file @ 731204e0
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/dfunc.sgml,v 1.17 2001/11/21 05:53:41 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/dfunc.sgml,v 1.18 2002/01/07 02:29:11 petere Exp $
-->
<sect2 id="dfunc">
......@@ -40,7 +40,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/dfunc.sgml,v 1.17 2001/11/21 05:53:41 thoma
<para>
In the following examples we assume that your source code is in a
file <filename>foo.c</filename> and we will create an shared library
file <filename>foo.c</filename> and we will create a shared library
<filename>foo.so</filename>. The intermediate object file will be
called <filename>foo.o</filename> unless otherwise noted. A shared
library can contain more than one object file, but we only use one
......@@ -121,8 +121,8 @@ ld -b -o foo.sl foo.o
</varlistentry>
<varlistentry>
<term><productname>Irix</productname></term>
<indexterm><primary>Irix</></>
<term><productname>IRIX</productname></term>
<indexterm><primary>IRIX</></>
<listitem>
<para>
<acronym>PIC</acronym> is the default, no special compiler
......
doc/src/sgml/ecpg.sgml
View file @ 731204e0
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.32 2002/01/06 17:54:14 momjian Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.33 2002/01/07 02:29:11 petere Exp $
-->
<chapter id="ecpg">
......@@ -300,7 +300,7 @@ struct sqlca
</varlistentry>
<varlistentry>
<term><computeroutput>-206 (ECPG_FLOAT_FORMAT): Not correctly formatted floating point type: %s line %d.</computeroutput></term>
<term><computeroutput>-206 (ECPG_FLOAT_FORMAT): Not correctly formatted floating-point type: %s line %d.</computeroutput></term>
<listitem>
<para>
This means the host variable is of type <type>float</type> and
......
doc/src/sgml/extend.sgml
View file @ 731204e0
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.14 2001/11/21 05:53:41 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.15 2002/01/07 02:29:11 petere Exp $
-->
<chapter id="extend">
......@@ -18,7 +18,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.14 2001/11/21 05:53:41 thom
</listitem>
<listitem>
<para>
types
data types
</para>
</listitem>
<listitem>
......@@ -56,17 +56,16 @@ $Header: /cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.14 2001/11/21 05:53:41 thom
extended by users. By comparison, conventional
database systems can only be extended by changing hardcoded
procedures within the <acronym>DBMS</acronym> or by loading modules
specially-written by the <acronym>DBMS</acronym> vendor.
specially written by the <acronym>DBMS</acronym> vendor.
</para>
<para>
<productname>PostgreSQL</productname> is also unlike most other data managers in
that the server can incorporate user-written code into
itself through dynamic loading. That is, the user can
specify an object code file (e.g., a compiled .o file
or shared library) that implements a new type or function
specify an object code file (e.g., a shared library) that implements a new type or function
and <productname>PostgreSQL</productname> will load it as required. Code written
in <acronym>SQL</acronym> are even more trivial to add to the server.
in <acronym>SQL</acronym> is even more trivial to add to the server.
This ability to modify its operation <quote>on the fly</quote> makes
<productname>PostgreSQL</productname> uniquely suited for rapid prototyping of new
applications and storage structures.
......@@ -80,14 +79,14 @@ $Header: /cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.14 2001/11/21 05:53:41 thom
The <productname>PostgreSQL</productname> type system
can be broken down in several ways.
Types are divided into base types and composite types.
Base types are those, like <firstterm>int4</firstterm>, that are implemented
in a language such as <productname>C</productname>. They generally correspond to
Base types are those, like <type>int4</type>, that are implemented
in a language such as C. They generally correspond to
what are often known as <firstterm>abstract data types</firstterm>; <productname>PostgreSQL</productname>
can only operate on such types through methods provided
by the user and only understands the behavior of such
types to the extent that the user describes them.
Composite types are created whenever the user creates a
table. EMP is an example of a composite type.
table.
</para>
<para>
......@@ -100,10 +99,10 @@ $Header: /cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.14 2001/11/21 05:53:41 thom
<productname>PostgreSQL</productname> base types are further
divided into built-in
types and user-defined types. Built-in types (like
<firstterm>int4</firstterm>) are those that are compiled
<type>int4</type>) are those that are compiled
into the system.
User-defined types are those created by the user in the
manner to be described below.
manner to be described later.
</para>
</sect1>
......@@ -118,7 +117,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.14 2001/11/21 05:53:41 thom
information given here, so mark this page for later
reference.
All system catalogs have names that begin with
<firstterm>pg_</firstterm>.
<literal>pg_</literal>.
The following tables contain information that may be
useful to the end user. (There are many other system
catalogs, but there should rarely be a reason to query
......@@ -149,15 +148,15 @@ $Header: /cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.14 2001/11/21 05:53:41 thom
</row>
<row>
<entry>pg_index</entry>
<entry> secondary indexes</entry>
<entry> indexes</entry>
</row>
<row>
<entry>pg_proc</entry>
<entry> procedures (both C and SQL)</entry>
<entry> procedures/functions </entry>
</row>
<row>
<entry>pg_type</entry>
<entry> types (both base and complex)</entry>
<entry> data types (both base and complex)</entry>
</row>
<row>
<entry>pg_operator</entry>
......@@ -165,7 +164,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.14 2001/11/21 05:53:41 thom
</row>
<row>
<entry>pg_aggregate</entry>
<entry> aggregates and aggregate functions</entry>
<entry> aggregate functions</entry>
</row>
<row>
<entry>pg_am</entry>
......@@ -198,7 +197,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.14 2001/11/21 05:53:41 thom
</mediaobject>
</figure>
The Reference Manual gives a more detailed explanation
The <citetitle>Developer's Guide</citetitle> gives a more detailed explanation
of these catalogs and their columns. However,
<xref linkend="EXTEND-CATALOGS">
shows the major entities and their relationships
......@@ -257,10 +256,9 @@ $Header: /cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.14 2001/11/21 05:53:41 thom
have obvious meanings, but there are many
(particularly those that have to do with access
methods) that do not. The relationships between
pg_am, pg_amop, pg_amproc, pg_operator and
pg_opclass are particularly hard to understand
and will be described in depth (in the section
on interfacing types and operators to indexes)
<classname>pg_am</>, <classname>pg_amop</>, <classname>pg_amproc</>, <classname>pg_operator</>, and
<classname>pg_opclass</> are particularly hard to understand
and will be described in depth (in <xref linkend="xindex">)
after we have discussed basic extensions.
</para>
</listitem>
......
doc/src/sgml/func.sgml
View file @ 731204e0
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/func.sgml,v 1.89 2001/12/27 21:36:57 tgl Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/func.sgml,v 1.90 2002/01/07 02:29:12 petere Exp $
PostgreSQL documentation
-->
......@@ -4506,7 +4506,7 @@ SELECT NULLIF(value, '(none)') ...
<type>bigint</type>, <type>real</type>, <type>double
precision</type>, <type>numeric</type>, <type>interval</type>.
The result is of type <type>numeric</type> for any integer type
input, <type>double precision</type> for floating point input,
input, <type>double precision</type> for floating-point input,
otherwise the same as the input data type.
</entry>
</row>
......@@ -4555,7 +4555,7 @@ SELECT NULLIF(value, '(none)') ...
data types: <type>smallint</type>, <type>integer</type>,
<type>bigint</type>, <type>real</type>, <type>double
precision</type>, <type>numeric</type>. The result is of type
<type>double precision</type> for floating point input,
<type>double precision</type> for floating-point input,
otherwise <type>numeric</type>.
</entry>
</row>
......@@ -4571,7 +4571,7 @@ SELECT NULLIF(value, '(none)') ...
The result is of type <type>bigint</type> for <type>smallint</type>
or <type>integer</type> input, <type>numeric</type> for
<type>bigint</type>
input, <type>double precision</type> for floating point input,
input, <type>double precision</type> for floating-point input,
otherwise the same as the input data type.
</entry>
</row>
......
doc/src/sgml/history.sgml
View file @ 731204e0
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/history.sgml,v 1.18 2001/11/28 20:49:10 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/history.sgml,v 1.19 2002/01/07 02:29:12 petere Exp $
-->
<sect1 id="history">
......@@ -9,7 +9,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/history.sgml,v 1.18 2001/11/28 20:49:10 pet
The object-relational database management system now known as
<productname>PostgreSQL</productname> (and briefly called
<productname>Postgres95</productname>) is derived from the
<productname>Postgres</productname> package written at the University of
<productname>POSTGRES</productname> package written at the University of
California at Berkeley. With over a decade of
development behind it, <productname>PostgreSQL</productname>
is the most advanced open-source database available anywhere,
......@@ -20,10 +20,10 @@ $Header: /cvsroot/pgsql/doc/src/sgml/history.sgml,v 1.18 2001/11/28 20:49:10 pet
</para>
<sect2>
<title>The Berkeley <productname>Postgres</productname> Project</title>
<title>The Berkeley <productname>POSTGRES</productname> Project</title>
<para>
Implementation of the <productname>Postgres</productname>
Implementation of the <productname>POSTGRES</productname>
<acronym>DBMS</acronym> began in 1986. The
initial concepts for the system were presented in
<xref linkend="STON86">
......@@ -60,24 +60,24 @@ $Header: /cvsroot/pgsql/doc/src/sgml/history.sgml,v 1.18 2001/11/28 20:49:10 pet
</para>
<para>
<productname>Postgres</productname> has been used
<productname>POSTGRES</productname> has been used
to implement many different
research and production applications. These include: a
financial data analysis system, a jet engine
performance monitoring package, an asteroid tracking
database, a medical information database, and several
geographic information systems.
<productname>Postgres</productname> has also been
<productname>POSTGRES</productname> has also been
used as an educational tool at several universities.
Finally,
<ulink url="http://www.illustra.com/">Illustra Information Technologies</ulink>
(since merged into
<ulink url="http://www.informix.com/"><productname>Informix</productname></ulink>)
Illustra Information Technologies (later merged into
<ulink url="http://www.informix.com/"><productname>Informix</productname></ulink>,
which is now owned by <ulink url="http://www.ibm.com/">IBM</ulink>.)
picked up
the code and commercialized it.
<productname>Postgres</productname> became the primary data manager
<productname>POSTGRES</productname> became the primary data manager
for the
<ulink url="http://www.sdsc.edu/0/Parts_Collabs/S2K/s2k_home.html">Sequoia 2000</ulink>
<ulink url="http://meteora.ucsd.edu/s2k/s2k_home.html">Sequoia 2000</ulink>
scientific computing project in late 1992.
</para>
......@@ -88,7 +88,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/history.sgml,v 1.18 2001/11/28 20:49:10 pet
support was taking up large amounts of time that should
have been devoted to database research. In an effort
to reduce this support burden, the Berkeley
<productname>Postgres</productname> project officially
<productname>POSTGRES</productname> project officially
ended with Version 4.2.
</para>
</sect2>
......@@ -98,10 +98,10 @@ $Header: /cvsroot/pgsql/doc/src/sgml/history.sgml,v 1.18 2001/11/28 20:49:10 pet
<para>
In 1994, Andrew Yu and Jolly Chen
added a SQL language interpreter to <productname>Postgres</productname>.
added a SQL language interpreter to <productname>POSTGRES</productname>.
<productname>Postgres95</productname> was subsequently released to
the Web to find its own way in the world as an
open-source descendant of the original <productname>Postgres</productname>
open-source descendant of the original <productname>POSTGRES</productname>
Berkeley code.
</para>
......@@ -109,15 +109,15 @@ $Header: /cvsroot/pgsql/doc/src/sgml/history.sgml,v 1.18 2001/11/28 20:49:10 pet
<productname>Postgres95</productname> code was completely
ANSI C and trimmed in size by 25%. Many
internal changes improved performance and maintainability.
<productname>Postgres95</productname> v1.0.x ran about 30-50%
<productname>Postgres95</productname> release 1.0.x ran about 30-50%
faster on the Wisconsin Benchmark compared to
<productname>Postgres</productname> v4.2.
Apart from bug fixes, these were the major enhancements:
<productname>POSTGRES</productname>, Version 4.2.
Apart from bug fixes, the following were the major enhancements:
<itemizedlist>
<listitem>
<para>
The query language <productname>Postquel</productname> was replaced with
The query language PostQUEL was replaced with
<acronym>SQL</acronym> (implemented in the server).
Subqueries were not supported until
<productname>PostgreSQL</productname> (see below), but they
......@@ -150,7 +150,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/history.sgml,v 1.18 2001/11/28 20:49:10 pet
<listitem>
<para>
The large object interface was overhauled. The Inversion large objects were
The large-object interface was overhauled. The Inversion large objects were
the only mechanism for storing large objects.
(The Inversion file system was removed.)
</para>
......@@ -175,7 +175,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/history.sgml,v 1.18 2001/11/28 20:49:10 pet
<para>
<acronym>GNU</acronym> make (instead of <acronym>BSD</acronym> make) was used
for the build. Also, <productname>Postgres95</productname> could be
compiled with an unpatched <productname>gcc</productname>
compiled with an unpatched <productname>GCC</productname>
(data alignment of doubles was fixed).
</para>
</listitem>
......@@ -190,11 +190,11 @@ $Header: /cvsroot/pgsql/doc/src/sgml/history.sgml,v 1.18 2001/11/28 20:49:10 pet
By 1996, it became clear that the name <quote>Postgres95</quote> would
not stand the test of time. We chose a new name,
<productname>PostgreSQL</productname>, to reflect the relationship
between the original <productname>Postgres</productname> and the more
between the original <productname>POSTGRES</productname> and the more
recent versions with <acronym>SQL</acronym> capability. At the same
time, we set the version numbering to start at 6.0, putting the
numbers back into the sequence originally begun by the
<productname>Postgres</productname> Project.
numbers back into the sequence originally begun by the Berkeley
<productname>POSTGRES</productname> project.
</para>
<para>
......@@ -212,9 +212,9 @@ $Header: /cvsroot/pgsql/doc/src/sgml/history.sgml,v 1.18 2001/11/28 20:49:10 pet
<itemizedlist>
<listitem>
<para>
Table-level locking has been replaced with multiversion concurrency control,
Table-level locking has been replaced by multiversion concurrency control,
which allows readers to continue reading consistent data during writer activity
and enables hot backups from pg_dump while the database stays available for
and enables hot backups from <application>pg_dump</> while the database stays available for
queries.
</para>
</listitem>
......@@ -244,7 +244,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/history.sgml,v 1.18 2001/11/28 20:49:10 pet
<listitem>
<para>
Overall backend code speed has been increased by approximately 20-40%,
and backend start-up time has decreased 80% since version 6.0 was released.
and backend start-up time has decreased by 80% since version 6.0 was released.
</para>
</listitem>
</itemizedlist>
......
doc/src/sgml/indices.sgml
View file @ 731204e0
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/indices.sgml,v 1.30 2001/12/04 01:22:13 tgl Exp $ -->
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/indices.sgml,v 1.31 2002/01/07 02:29:12 petere Exp $ -->
<chapter id="indexes">
<title id="indexes-title">Indexes</title>
......@@ -397,8 +397,8 @@ CREATE INDEX <replaceable>name</replaceable> ON <replaceable>table</replaceable>
<literal>bigbox_ops</literal> both support R-tree indexes on the
<literal>box</literal> data type. The difference between them is
that <literal>bigbox_ops</literal> scales box coordinates down,
to avoid floating point exceptions from doing multiplication,
addition, and subtraction on very large floating point
to avoid floating-point exceptions from doing multiplication,
addition, and subtraction on very large floating-point
coordinates. If the field on which your rectangles lie is about
20 000 units square or larger, you should use
<literal>bigbox_ops</literal>.
......
doc/src/sgml/inherit.sgml
View file @ 731204e0
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/inherit.sgml,v 1.17 2001/11/21 05:53:41 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/inherit.sgml,v 1.18 2002/01/07 02:29:12 petere Exp $
-->
<chapter id="inherit">
......@@ -28,7 +28,7 @@ CREATE TABLE capitals (
<type>text</type>, a native <productname>PostgreSQL</productname> type for variable length
ASCII strings. The type of the attribute population is
<type>float</type>, a native <productname>PostgreSQL</productname> type for double precision
floating point numbers. State capitals have an extra
floating-point numbers. State capitals have an extra
attribute, state, that shows their state. In <productname>PostgreSQL</productname>,
a table can inherit from zero or more other tables,
and a query can reference either all rows of a
......
doc/src/sgml/intro.sgml
View file @ 731204e0
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/intro.sgml,v 1.18 2001/11/23 22:06:20 tgl Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/intro.sgml,v 1.19 2002/01/07 02:29:12 petere Exp $
-->
<preface id="preface">
......@@ -38,8 +38,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/intro.sgml,v 1.18 2001/11/23 22:06:20 tgl E
type. In current commercial systems, possible types
include floating point numbers, integers, character
strings, money, and dates. It is commonly recognized
that this model is inadequate for future data
processing applications.
that this model is inadequate for future data-processing applications.
The relational model successfully replaced previous
models in part because of its <quote>Spartan simplicity</quote>.
However, this simplicity makes the
......@@ -76,7 +75,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/intro.sgml,v 1.18 2001/11/23 22:06:20 tgl E
<simpara>rules</simpara>
</listitem>
<listitem>
<simpara>transaction integrity</simpara>
<simpara>transactional integrity</simpara>
</listitem>
</itemizedlist>
</para>
......
doc/src/sgml/libpgeasy.sgml
View file @ 731204e0
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpgeasy.sgml,v 2.7 2001/10/01 21:47:24 momjian Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpgeasy.sgml,v 2.8 2002/01/07 02:29:12 petere Exp $
-->
<chapter id="pgeasy-chapter">
<title id="pgeasy"><application>libpgeasy</application> - Simplified C Library</title>
<chapter id="pgeasy">
<title><application>libpgeasy</application> - Simplified C Library</title>
<note>
<title>Author</title>
......@@ -16,9 +16,10 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/libpgeasy.sgml,v 2.7 2001/10/01 21:47
</note>
<para>
<productname>pgeasy</productname> allows you to cleanly interface
to the <productname>libpq</productname> library,
more like a 4GL SQL interface.
<application>pgeasy</application> allows you to cleanly interface
to the <application>libpq</application> library, more like a 4GL
SQL interface. Refer to <xref linkend="libpq"> for more
information about <application>libpq</application>
</para>
<para>
......@@ -111,8 +112,8 @@ void unset_result(PGresult *oldres);
For <literal>SELECT</literal> queries, <function>fetch</function>
allows you to pass pointers as parameters, and on return the variables
are filled with data from the binary cursor you opened. These binary
cursors can not be used if you are running the
<productname>pgeasy</productname>
cursors cannot be used if you are running the
<application>pgeasy</application>
client on a system with a different architecture than the database
server. If you pass a NULL pointer parameter, the column is skipped.
<function>fetchwithnulls</function> allows you to retrieve the NULL
......
doc/src/sgml/libpgtcl.sgml
View file @ 731204e0
......@@ -9,22 +9,28 @@
<primary>Tcl</primary>
</indexterm>
<Para>
<literal>pgtcl</literal> is a Tcl package for front-end programs
to interface with <ProductName>PostgreSQL</ProductName>
backends. It makes most of the functionality of <literal>libpq</literal> available to
Tcl scripts.
</Para>
<sect1 id="pgtcl-intro">
<title>Introduction</title>
<Para>
This package was originally written by Jolly Chen.
</Para>
<para>
<application>pgtcl</application> is a Tcl package for client
programs to interface with <ProductName>PostgreSQL</ProductName>
servers. It makes most of the functionality of
<application>libpq</application> available to Tcl scripts.
</para>
<Sect1 id="libpgtcl-commands">
<Title>Commands</Title>
<para>
This package was originally written by Jolly Chen.
</para>
<Para>
<TABLE TOCENTRY="1">
<para>
<xref linkend="pgtcl-commands-table"> gives an overview over the
commands available in <application>pgtcl</application>. These
commands are described further on subsequent pages.
</para>
<TABLE TOCENTRY="1" id="pgtcl-commands-table">
<TITLE><literal>pgtcl</literal> Commands</TITLE>
<TGROUP COLS="2">
<THEAD>
......@@ -106,34 +112,30 @@ This package was originally written by Jolly Chen.
</TBODY>
</TGROUP>
</TABLE>
</Para>
<Para>
These commands are described further on subsequent pages.
</Para>
<Para>
The pg_lo* routines are interfaces to the Large Object features of
<ProductName>PostgreSQL</ProductName>.
The functions are designed to mimic the analogous file system functions in
the standard Unix file system interface.
The pg_lo* routines should be used within a BEGIN/END transaction
block because the file descriptor returned by pg_lo_open is only valid for
the current transaction. pg_lo_import and pg_lo_export MUST be used
in a BEGIN/END transaction block.
</Para>
</Sect1>
<Sect1 id="libpgtcl-examples">
<Title>Examples</Title>
<example>
<para>
The <function>pg_lo_*</function> routines are interfaces to the
large object features of <ProductName>PostgreSQL</ProductName>.
The functions are designed to mimic the analogous file system
functions in the standard Unix file system interface. The
<function>pg_lo_*</function> routines should be used within a
<command>BEGIN</command>/<command>COMMIT</command> transaction
block because the file descriptor returned by
<function>pg_lo_open</function> is only valid for the current
transaction. <function>pg_lo_import</function> and
<function>pg_lo_export</function> <emphasis>must</emphasis> be used
in a <command>BEGIN</command>/<command>COMMIT</command> transaction
block.
</para>
<para>
<xref linkend="pgtcl-example"> shows a small example of how to use
the routines.
</para>
<example id="pgtcl-example">
<title><application>pgtcl</application> Example Program</title>
<para>
Here's a small example of how to use the routines:
<programlisting>
# getDBs :
# get the names of all the databases at a given host and port number
......@@ -151,10 +153,9 @@ proc getDBs { {host "localhost"} {port "5432"} } {
pg_disconnect $conn
return $datnames
}
</ProgramListing>
</para>
</programlisting>
</example>
</Sect1>
</sect1>
<Sect1 id="libpgtcl-loading">
<Title>Loading <application>pgtcl</application> into your application</Title>
......@@ -165,7 +166,7 @@ proc getDBs { {host "localhost"} {port "5432"} } {
done with the Tcl <literal>load</> command. Here is an example:
<programlisting>
load libpgtcl[info sharedlibextension]
load libpgtcl[info sharedlibextension]
</programlisting>
The use of <literal>info sharedlibextension</> is recommended in
......@@ -174,11 +175,13 @@ proc getDBs { {host "localhost"} {port "5432"} } {
</para>
<para>
The <literal>load</> command will fail unless the system's dynamic loader
knows where to look for the <filename>libpgtcl</> shared library file.
You may need to work with <literal>ldconfig</>, or set the environment
variable <envar>LD_LIBRARY_PATH</>, or use some equivalent facility for
your platform to make it work.
The <literal>load</> command will fail unless the system's dynamic
loader knows where to look for the <filename>libpgtcl</> shared
library file. You may need to work with <command>ldconfig</>, or
set the environment variable <envar>LD_LIBRARY_PATH</>, or use
some equivalent facility for your platform to make it work. Refer
to the <productname>PostgreSQL</> installation instructions for
more information.
</para>
<para>
......@@ -209,7 +212,7 @@ proc getDBs { {host "localhost"} {port "5432"} } {
<REFNAMEDIV>
<REFNAME>pg_connect
</REFNAME>
<REFPURPOSE>opens a connection to the backend server
<REFPURPOSE>open a connection to the backend server
</REFPURPOSE>
<INDEXTERM ID="IX-PGTCL-PGCONNECT-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>connecting</SECONDARY></INDEXTERM>
<INDEXTERM ID="IX-PGTCL-PGCONNECT-2"><PRIMARY>pg_connect</PRIMARY></INDEXTERM>
......@@ -363,7 +366,7 @@ for info about the available options in the newer syntax.
<REFNAMEDIV>
<REFNAME>pg_disconnect
</REFNAME>
<REFPURPOSE>closes a connection to the backend server
<REFPURPOSE>close a connection to the backend server
</REFPURPOSE>
<INDEXTERM ID="IX-PGTCL-PGDISCONNECT-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>connecting</SECONDARY></INDEXTERM>
<INDEXTERM ID="IX-PGTCL-PGDISCONNECT-2"><PRIMARY>pg_connect</PRIMARY></INDEXTERM>
......@@ -522,7 +525,7 @@ current default value for each option.
<REFNAME>pg_exec
</REFNAME>
<REFPURPOSE>
send a query string to the backend
send a command string to the server
</REFPURPOSE>
<INDEXTERM ID="IX-PGTCL-PGEXEC-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>connecting</SECONDARY></INDEXTERM>
<INDEXTERM ID="IX-PGTCL-PGEXEC-2"><PRIMARY>pg_connect</PRIMARY></INDEXTERM>
......@@ -999,7 +1002,7 @@ This would work if table <classname>table</> has fields <structfield>control</>
<REFNAMEDIV>
<REFNAME>pg_listen
</REFNAME>
<REFPURPOSE>sets or changes a callback for asynchronous NOTIFY messages
<REFPURPOSE>set or change a callback for asynchronous NOTIFY messages
</REFPURPOSE>
<INDEXTERM ID="IX-PGTCL-PGLISTEN-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>notify</SECONDARY></INDEXTERM>
<INDEXTERM ID="IX-PGTCL-PGLISTEN-2"><PRIMARY>notify</PRIMARY></INDEXTERM>
......@@ -1859,7 +1862,7 @@ None
<REFNAMEDIV>
<REFNAME>pg_lo_import
</REFNAME>
<REFPURPOSE>import a large object from a Unix file
<REFPURPOSE>import a large object from a file
</REFPURPOSE>
<INDEXTERM ID="IX-PGTCL-PGLOIMPORT-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>import</SECONDARY></INDEXTERM>
<INDEXTERM ID="IX-PGTCL-PGLOIMPORT-2"><PRIMARY>pg_lo_import</PRIMARY></INDEXTERM>
......@@ -1944,7 +1947,7 @@ None
<REFNAMEDIV>
<REFNAME>pg_lo_export
</REFNAME>
<REFPURPOSE>export a large object to a Unix file
<REFPURPOSE>export a large object to a file
</REFPURPOSE>
<INDEXTERM ID="IX-PGTCL-PGLOEXPORT-1"><PRIMARY>pgtcl</PRIMARY><SECONDARY>export</SECONDARY></INDEXTERM>
<INDEXTERM ID="IX-PGTCL-PGLOEXPORT-2"><PRIMARY>pg_lo_export</PRIMARY></INDEXTERM>
......
doc/src/sgml/libpq++.sgml
View file @ 731204e0
This diff is collapsed.
doc/src/sgml/libpq.sgml
View file @ 731204e0
This diff is collapsed.
doc/src/sgml/lobj.sgml
View file @ 731204e0
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/lobj.sgml,v 1.24 2001/11/12 19:19:39 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/lobj.sgml,v 1.25 2002/01/07 02:29:12 petere Exp $
-->
<chapter id="largeObjects">
......@@ -106,19 +106,19 @@ $Header: /cvsroot/pgsql/doc/src/sgml/lobj.sgml,v 1.24 2001/11/12 19:19:39 petere
<para>
The <productname>PostgreSQL</productname> large object interface is modeled after
the <acronym>Unix</acronym> file system interface, with analogues of
the <acronym>Unix</acronym> file-system interface, with analogues of
<function>open(2)</function>, <function>read(2)</function>,
<function>write(2)</function>,
<function>lseek(2)</function>, etc. User
functions call these routines to retrieve only the data of
interest from a large object. For example, if a large
object type called <type>mugshot</type> existed that stored
photographs of faces, then a function called beard could
be declared on <type>mugshot</type> data. Beard could look at the
photographs of faces, then a function called <function>beard</function> could
be declared on <type>mugshot</type> data. <function>beard</> could look at the
lower third of a photograph, and determine the color of
the beard that appeared there, if any. The entire
large object value need not be buffered, or even
examined, by the beard function.
large-object value need not be buffered, or even
examined, by the <function>beard</function> function.
Large objects may be accessed from dynamically-loaded <acronym>C</acronym>
functions or database client programs that link the
library. <productname>PostgreSQL</productname> provides a set of routines that
......@@ -140,7 +140,7 @@ Oid lo_creat(PGconn *<replaceable class="parameter">conn</replaceable>, int <rep
object. The symbolic constants listed 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
or'ing together the bits <symbol>INV_READ</symbol> and
<symbol>INV_WRITE</symbol>. The low-order sixteen bits of the mask have
historically been used at Berkeley to designate the storage manager number on which the large object
should reside. These
......@@ -156,12 +156,12 @@ inv_oid = lo_creat(INV_READ|INV_WRITE);
<title>Importing a Large Object</title>
<para>
To import a <acronym>UNIX</acronym> file as a large object, call
To import an operating system file as a large object, call
<synopsis>
Oid lo_import(PGconn *<replaceable class="parameter">conn</replaceable>, const char *<replaceable class="parameter">filename</replaceable>)
</synopsis>
<replaceable class="parameter">filename</replaceable>
specifies the <acronym>Unix</acronym> path name of
specifies the operating system name of
the file to be imported as a large object.
</para>
</sect2>
......@@ -171,13 +171,13 @@ Oid lo_import(PGconn *<replaceable class="parameter">conn</replaceable>, const c
<para>
To export a large object
into <acronym>UNIX</acronym> file, call
into an operating system file, call
<synopsis>
int lo_export(PGconn *<replaceable class="parameter">conn</replaceable>, Oid <replaceable class="parameter">lobjId</replaceable>, const char *<replaceable class="parameter">filename</replaceable>)
</synopsis>
The <parameter>lobjId</parameter> argument specifies the Oid of the large
object to export and the <parameter>filename</parameter> argument specifies
the <acronym>UNIX</acronym> path name of the file.
the operating system name name of the file.
</para>
</sect2>
......@@ -191,7 +191,7 @@ int lo_open(PGconn *conn, Oid lobjId, int mode)
</synopsis>
The <parameter>lobjId</parameter> argument specifies the Oid of the large
object to open. The <parameter>mode</parameter> bits control whether the
object is opened for reading (<symbol>INV_READ</>), writing or
object is opened for reading (<symbol>INV_READ</>), writing (<symbol>INV_WRITE</symbol>), or
both.
A large object cannot be opened before it is created.
<function>lo_open</function> returns a large object descriptor
......@@ -241,9 +241,9 @@ int lo_read(PGconn *conn, int fd, char *buf, size_t len)
int lo_lseek(PGconn *conn, int fd, int offset, int whence)
</programlisting>
This routine moves the current location pointer for the
large object described by fd to the new location specified
by offset. The valid values for whence are
SEEK_SET, SEEK_CUR, and SEEK_END.
large object described by <parameter>fd</> to the new location specified
by <parameter>offset</>. The valid values for <parameter>whence</> are
<symbol>SEEK_SET</>, <symbol>SEEK_CUR</>, and <symbol>SEEK_END</>.
</para>
</sect2>
......@@ -255,7 +255,7 @@ int lo_lseek(PGconn *conn, int fd, int offset, int whence)
<programlisting>
int lo_close(PGconn *conn, int fd)
</programlisting>
where fd is a large object descriptor returned by
where <parameter>fd</> is a large object descriptor returned by
<function>lo_open</function>. On success, <function>lo_close</function>
returns zero. On error, the return value is negative.
</para>
......@@ -281,8 +281,8 @@ Oid lo_unlink(PGconn *<replaceable class="parameter">conn</replaceable>, Oid lob
<title>Server-side Built-in Functions</title>
<para>
There are two built-in registered functions, <acronym>lo_import</acronym>
and <acronym>lo_export</acronym> which are convenient for use
There are two built-in registered functions, <function>lo_import</function>
and <function>lo_export</function> which are convenient for use
in <acronym>SQL</acronym>
queries.
Here is an example of their use
......@@ -295,7 +295,7 @@ CREATE TABLE image (
INSERT INTO image (name, raster)
VALUES ('beautiful image', lo_import('/etc/motd'));
SELECT lo_export(image.raster, '/tmp/motd') from image
SELECT lo_export(image.raster, '/tmp/motd') FROM image
WHERE name = 'beautiful image';
</programlisting>
</para>
......@@ -305,24 +305,18 @@ SELECT lo_export(image.raster, '/tmp/motd') from image
<title>Accessing Large Objects from <application>Libpq</application></title>
<para>
Below is a sample program which shows how the large object
<xref linkend="lo-example"> is a sample program which shows how the large object
interface
in <application>libpq</> can be used. Parts of the program are
commented out but are left in the source for the readers
commented out but are left in the source for the reader's
benefit. This program can be found in
<filename>
../src/test/examples
</filename>
<filename>src/test/examples/testlo.c</filename> in the source distribution.
Frontend applications which use the large object interface
in <application>libpq</application> should include the header file
<filename>libpq/libpq-fs.h</filename> and link with the <application>libpq</application> library.
</para>
</sect1>
<sect1 id="lo-example">
<title>Example Program</title>
<example>
<example id="lo-example">
<title>Large Objects with <application>Libpq</application> Example Program</title>
<programlisting>
/*--------------------------------------------------------------
......
doc/src/sgml/odbc.sgml
View file @ 731204e0
This diff is collapsed.
doc/src/sgml/plperl.sgml
View file @ 731204e0
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/plperl.sgml,v 2.11 2001/11/21 05:53:41 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/plperl.sgml,v 2.12 2002/01/07 02:29:13 petere Exp $
-->
<chapter id="plperl">
......@@ -13,15 +13,19 @@ $Header: /cvsroot/pgsql/doc/src/sgml/plperl.sgml,v 2.11 2001/11/21 05:53:41 thom
<primary>Perl</primary>
</indexterm>
<sect1 id="intro">
<title>Introduction</title>
<para>
PL/Perl allows you to write functions in the Perl programming
language that may be used in SQL queries as if they were built into
PL/Perl allows you to write functions in the <ulink
url="http://www.perl.com">Perl</ulink> programming language that may
be used in SQL queries as if they were built into
<productname>PostgreSQL</productname>.
</para>
<para>
The PL/Perl interpreter (when installed as trusted interpreter with
default name <literal>plperl</>) interpreter is a full Perl interpreter. However, certain
default name <literal>plperl</>) is a full Perl interpreter. However, certain
operations have been disabled in order to maintain the security of
the system. In general, the operations that are restricted are
those that interact with the environment. This includes file handle
......@@ -33,8 +37,9 @@ $Header: /cvsroot/pgsql/doc/src/sgml/plperl.sgml,v 2.11 2001/11/21 05:53:41 thom
</para>
<para>
When PL/Perl is installed as <quote>untrusted</> interpreter (with name <literal>plperlu</literal>),
everything is permitted, and any Perl code can be loaded (by superuser only).
everything is permitted, and any Perl code can be loaded (by a superuser only).
</para>
</sect1>
<sect1 id="plperl-install">
<title>Building and Installing</title>
......@@ -54,10 +59,9 @@ $Header: /cvsroot/pgsql/doc/src/sgml/plperl.sgml,v 2.11 2001/11/21 05:53:41 thom
fact:
<screen>
<computeroutput>
*****
* Cannot build PL/Perl because libperl is not a shared library.
* Skipped.
*****
*** Cannot build PL/Perl because libperl is not a shared library.
*** You might have to rebuild your Perl installation. Refer to
*** the documentation for details.
</computeroutput>
</screen>
Therefore it is likely that you will have to re-build and install
......@@ -84,7 +88,7 @@ gmake install
<prompt>$</prompt> <userinput>createlang plperl template1</userinput>
</screen>
Alternatively, to create untrusted interpreter (where functions can only
be created by superuser, but the functions are not restricted), use:
be created by a superuser, but the functions are not restricted), use:
<screen>
<prompt>$</prompt> <userinput>createlang plperlu template1</userinput>
</screen>
......@@ -99,7 +103,7 @@ be created by superuser, but the functions are not restricted), use:
<para>
Assume you have the following table:
<programlisting>
CREATE TABLE EMPLOYEE (
CREATE TABLE employee (
name text,
basesalary integer,
bonus integer
......@@ -111,7 +115,7 @@ CREATE TABLE EMPLOYEE (
<programlisting>
CREATE FUNCTION totalcomp(integer, integer) RETURNS integer
AS 'return $_[0] + $_[1]'
LANGUAGE 'plperl';
LANGUAGE plperl;
</programlisting>
Notice that the arguments to the function are passed in
......@@ -131,7 +135,7 @@ SELECT name, totalcomp(basesalary, bonus) FROM employee;
CREATE FUNCTION empcomp(employee) RETURNS integer AS '
my $emp = shift;
return $emp->{''basesalary''} + $emp->{''bonus''};
' LANGUAGE 'plperl';
' LANGUAGE plperl;
</programlisting>
A tuple is passed as a reference to a hash. The keys are the names
of the fields in the tuples. The hash values are values of the
......@@ -151,7 +155,7 @@ CREATE FUNCTION empcomp(employee) RETURNS integer AS '
</tip>
<para>
The new function <function>empcomp</function> can used like:
The new function <function>empcomp</function> can be used like:
<programlisting>
SELECT name, empcomp(employee) FROM employee;
</programlisting>
......@@ -165,18 +169,22 @@ CREATE FUNCTION badfunc() RETURNS integer AS '
open(TEMP, ">/tmp/badfile");
print TEMP "Gotcha!\n";
return 1;
' LANGUAGE 'plperl';
' LANGUAGE plperl;
</programlisting>
The creation of the function will succeed, but executing it will not.
</para>
<para>
Note that if same function was created by superuser using language
<literal>plperlu</>, execution would succeed.
</para>
<para>
Access to database itself from your Perl function can be done via
an experimental module <ulink url="http://www.formenos.org/PgSPI/"><literal>DBD::PgSPI</literal></ulink>. This module makes available a <acronym>DBI</>-compliant
database-handle named <varname>$pg_dbh</varname>, and you can use that to make queries with
normal <acronym>DBI</> syntax.
Access to database itself from your Perl function can be done via
an experimental module <ulink
url="http://www.formenos.org/PgSPI/"><literal>DBD::PgSPI</literal></ulink>
(also on <ulink url="http://www.cpan.org">CPAN</ulink>). This
module makes available a <acronym>DBI</>-compliant database-handle
named <varname>$pg_dbh</varname>, and you can use that to perform
queries with normal <acronym>DBI</> syntax.
</para>
</sect1>
......
doc/src/sgml/plpython.sgml
View file @ 731204e0
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/plpython.sgml,v 1.7 2001/11/21 05:53:41 thomas Exp $ -->
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/plpython.sgml,v 1.8 2002/01/07 02:29:13 petere Exp $ -->
<chapter id="plpython">
<title>PL/Python - Python Procedural Language</title>
......@@ -6,44 +6,74 @@
<indexterm zone="plpython"><primary>PL/Python</></>
<indexterm zone="plpython"><primary>Python</></>
<note>
<sect1 id="plpython-intro">
<title>Introduction</title>
<para>
This chapter is not fully developed yet.
The <application>PL/Python</application> procedural language allows
<productname>PostgreSQL</productname> functions to be written in
the <ulink url="http://www.python.org">Python</ulink> language.
</para>
<para>
The current version of PL/Python functions as a trusted language only;
access to the filesystem and other local resources are disabled.
Specifically, PL/Python uses the Python restricted execution environment,
further restricts it to prevent the use of the file open call, and
allows only modules from a specific list to be imported. Presently,
that list includes: array, bisect, binascii, calendar, cmath, codecs,
errno, marshal, math, md5, mpz, operator, pcre, pickle, random, re,
regex, sre, sha, string, StringIO, struct, time, whrandom, and zlib.
The current version of <application>PL/Python</application>
functions as a trusted language only; access to the file system and
other local resources is disabled. Specifically,
<application>PL/Python</application> uses the Python restricted
execution environment, further restricts it to prevent the use of
the file <function>open</> call, and allows only modules from a
specific list to be imported. Presently, that list includes:
array, bisect, binascii, calendar, cmath, codecs, errno, marshal,
math, md5, mpz, operator, pcre, pickle, random, re, regex, sre,
sha, string, StringIO, struct, time, whrandom, and zlib.
</para>
<para>
There is discussion on creating an untrusted language variant for a
In the current version, any database error encountered while
running a <application>PL/Python</application> function will result
in the immediate termination of that function by the server. It is
not possible to trap error conditions using Python <literal>try
... catch</literal> constructs. For example, a syntax error in an
SQL statement passed to the <literal>plpy.execute()</literal> call
will terminate the function. This behavior may be changed in a
future release.
</para>
<para>
In the current version, any postgresql error encountered while running
a PL/Python function will result in the immediate termination of that
function by the backend. It is not possible to trap error conditions
using Python try ... catch constructs. For example, a syntax error in
an SQL statement passed to the plpy.execute() call will terminate the
function. This behavior may be changed in a future release.
</para>
</note>
</sect1>
<sect1 id="plpython-install">
<title>Installation</title>
<para>
... needs to be worked out.
To build PL/Python, the <option>--with-python</option> option needs
to be specified when running <filename>configure</filename>. If
after building and installing you have a file called
<filename>plpython.so</filename> (possibly a different extension),
then everything went well. Otherwise you should have seen a notice
like this flying by:
<screen>
*** Cannot build PL/Python because libpython is not a shared library.
*** You might have to rebuild your Python installation. Refer to
*** the documentation for details.
</screen>
That means you have to rebuild (part of) your Python installation
to supply this shared library.
</para>
<para>
The catch is that the Python distribution or the Python maintainers
do not provide any direct way to do this. The closest thing we can
offer you is the information in <ulink
url="http://www.python.org/doc/FAQ.html#3.30">Python FAQ
3.30</ulink>. On some operating systems you don't really have to
build a shared library, but then you will have to convince the
PostgreSQL build system of this. Consult the
<filename>Makefile</filename> in the
<filename>src/pl/plpython</filename> directory for details.
</para>
</sect1>
<sect1 id="plpython-using">
<title>Using</title>
<title>Using PL/Python</title>
<para>
There are sample functions in
......
doc/src/sgml/plsql.sgml
View file @ 731204e0
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/plsql.sgml,v 2.52 2002/01/02 00:41:26 tgl Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/plsql.sgml,v 2.53 2002/01/07 02:29:13 petere Exp $
-->
<chapter id="plpgsql">
......@@ -1700,7 +1700,7 @@ RAISE EXCEPTION ''Inexistent ID --> %'',user_id;
<para>
It is possible to hook into the error mechanism to notice that this
happens. But currently it is impossible to tell what really
caused the abort (input/output conversion error, floating point
caused the abort (input/output conversion error, floating-point
error, parse error). And it is possible that the database backend
is in an inconsistent state at this point so returning to the upper
executor or issuing more commands might corrupt the whole database.
......
doc/src/sgml/problems.sgml
View file @ 731204e0
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/problems.sgml,v 2.11 2001/11/21 05:53:41 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/problems.sgml,v 2.12 2002/01/07 02:29:13 petere Exp $
-->
<sect1 id="bug-reporting">
......@@ -252,7 +252,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/problems.sgml,v 2.11 2001/11/21 05:53:41 th
Do not spend all your time to figure out which changes in the input make
the problem go away. This will probably not help solving it. If it turns
out that the bug cannot be fixed right away, you will still have time to
find and share your work around. Also, once again, do not waste your time
find and share your work-around. Also, once again, do not waste your time
guessing why the bug exists. We will find that out soon enough.
</para>
......
doc/src/sgml/programmer.sgml
View file @ 731204e0
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.38 2001/05/12 22:51:35 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.39 2002/01/07 02:29:13 petere Exp $
PostgreSQL Programmer's Guide.
-->
......@@ -16,30 +16,17 @@ PostgreSQL Programmer's Guide.
&intro;
]]>
<preface id="organization">
<title>Organization</title>
<para>
The first part of this manual is the description of the client-side
programming interfaces and support libraries for various languages.
The second part explains the <productname>PostgreSQL</productname>
approach to extensibility and describe how users can extend
<productname>PostgreSQL</productname> by adding user-defined types,
operators, aggregates, and both query language and programming
language functions. After a discussion of the
<productname>PostgreSQL</productname> rule system, we discuss the
trigger and SPI interfaces. The third part documents the
procedural languages available in the
<productname>PostgreSQL</productname> distribution.
</para>
<para>
Proficiency with Unix and C programming is assumed.
</para>
</preface>
<part id="programmer-client">
<title>Client Interfaces</title>
<partintro>
<para>
This part of the manual is the description of the client-side
programming interfaces and support libraries for various
languages.
</para>
</partintro>
&libpq;
&lobj;
&libpqpp;
......@@ -53,6 +40,20 @@ PostgreSQL Programmer's Guide.
<part id="programmer-server">
<title>Server Programming</title>
<partintro>
<para>
This second part of the manual explains the
<productname>PostgreSQL</productname> approach to extensibility
and describe how users can extend
<productname>PostgreSQL</productname> by adding user-defined
types, operators, aggregates, and both query language and
programming language functions. After a discussion of the
<productname>PostgreSQL</productname> rule system, we discuss the
trigger and SPI interfaces.
</para>
</partintro>
&arch-pg;
&extend;
&xfunc;
......@@ -70,6 +71,14 @@ PostgreSQL Programmer's Guide.
<part id="programmer-pl">
<title>Procedural Languages</title>
<partintro>
<para>
This part documents the procedural languages available in the
<productname>PostgreSQL</productname> distribution as well as
general issues concerning procedural languages.
</para>
</partintro>
&xplang;
&plsql;
&pltcl;
......
doc/src/sgml/query.sgml
View file @ 731204e0
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/query.sgml,v 1.23 2001/11/28 20:49:10 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/query.sgml,v 1.24 2002/01/07 02:29:13 petere Exp $
-->
<chapter id="tutorial-sql">
......@@ -137,7 +137,7 @@ CREATE TABLE weather (
<type>varchar(80)</type> specifies a data type that can store
arbitrary character strings up to 80 characters in length.
<type>int</type> is the normal integer type. <type>real</type> is
a type for storing single precision floating point numbers.
a type for storing single precision floating-point numbers.
<type>date</type> should be self-explanatory. (Yes, the column of
type <type>date</type> is also named <literal>date</literal>.
This may be convenient or confusing -- you choose.)
......
doc/src/sgml/ref/create_operator.sgml
View file @ 731204e0
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_operator.sgml,v 1.22 2001/12/08 03:24:34 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_operator.sgml,v 1.23 2002/01/07 02:29:15 petere Exp $
PostgreSQL documentation
-->
......@@ -343,7 +343,7 @@ MYBOXES.description &lt;&lt;&lt; box '((0,0), (1,1))'
<replaceable class="parameter">res_proc</replaceable>
must be a registered function (meaning it is already defined using
<command>CREATE FUNCTION</command>) which accepts arguments of the correct
data types and returns a floating point number. The
data types and returns a floating-point number. The
query optimizer simply calls this function, passing the
parameter <literal>((0,0), (1,1))</literal> and multiplies the result by the relation
size to get the expected number of instances.
......@@ -352,7 +352,7 @@ MYBOXES.description &lt;&lt;&lt; box '((0,0), (1,1))'
Similarly, when the operands of the operator both contain
instance variables, the query optimizer must estimate the
size of the resulting join. The function join_proc will
return another floating point number which will be multiplied
return another floating-point number which will be multiplied
by the cardinalities of the two tables involved to
compute the expected result size.
</para>
......
doc/src/sgml/ref/set.sgml
View file @ 731204e0
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/set.sgml,v 1.56 2001/12/29 20:29:49 momjian Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/set.sgml,v 1.57 2002/01/07 02:29:15 petere Exp $
PostgreSQL documentation
-->
......@@ -195,8 +195,8 @@ SET TIME ZONE { '<replaceable class="PARAMETER">timezone</replaceable>' | LOCAL
<para>
The value for the seed to be used by the
<function>random</function> function. Allowed
values are floating point numbers between 0 and 1, which
are then multiplied by 2^31-1. This product will
values are floating-point numbers between 0 and 1, which
are then multiplied by 2<superscript>31</>-1. This product will
silently overflow if a number outside the range is used.
</para>
......
doc/src/sgml/regress.sgml
View file @ 731204e0
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/regress.sgml,v 1.23 2001/12/04 01:49:17 tgl Exp $ -->
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/regress.sgml,v 1.24 2002/01/07 02:29:13 petere Exp $ -->
<chapter id="regress">
<title id="regress-title">Regression Tests</title>
......@@ -135,7 +135,7 @@
Some properly installed and fully functional
<productname>PostgreSQL</productname> installations can
<quote>fail</quote> some of these regression tests due to
platform-specific artifacts such as varying floating point representation
platform-specific artifacts such as varying floating-point representation
and time zone support. The tests are currently evaluated using a simple
<application>diff</application> comparison against the outputs
generated on a reference system, so the results are sensitive to
......@@ -248,7 +248,7 @@ PGTZ='PST8PDT7,M04.01.0,M10.05.03'; export PGTZ
</sect2>
<sect2>
<title>Floating point differences</title>
<title>Floating-point differences</title>
<para>
Some of the tests involve computing 64-bit (<type>double
......
doc/src/sgml/rules.sgml
View file @ 731204e0
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/rules.sgml,v 1.19 2001/11/21 06:09:45 thomas Exp $ -->
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/rules.sgml,v 1.20 2002/01/07 02:29:13 petere Exp $ -->
<Chapter Id="rules">
<Title>The Rule System</Title>
......@@ -14,6 +14,9 @@
</para>
</note>
<sect1 id="rules-intro">
<title>Introduction</title>
<Para>
Production rule systems are conceptually simple, but
there are many subtle points involved in actually using
......@@ -42,6 +45,9 @@
as well as
<XRef LinkEnd="STON90b">.
</para>
</sect1>
<Sect1 id="querytree">
<Title>What is a Query Tree?</Title>
......
doc/src/sgml/runtime.sgml
View file @ 731204e0
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.100 2001/12/27 21:37:34 tgl Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/runtime.sgml,v 1.101 2002/01/07 02:29:13 petere Exp $
-->
<Chapter Id="runtime">
......@@ -128,9 +128,9 @@ postgres$ <userinput>initdb -D /usr/local/pgsql/data</userinput>
password to the database superuser. After <command>initdb</command>,
modify <filename>pg_hba.conf</filename> to use <literal>md5</> or
<literal>password</>, instead of <literal>trust</>, authentication
<emphasis>before</> you first start the postmaster. (Other, possibly
<emphasis>before</> you start the server for the first time. (Other, possibly
more convenient approaches include using <literal>ident</literal>
authentication or filesystem permissions to restrict connections. See
authentication or file system permissions to restrict connections. See
<xref linkend="client-authentication"> for more information.)
</para>
......@@ -493,7 +493,7 @@ log_connections = yes
syslog = 2
</programlisting>
As you see, options are one per line. The equal sign between name
and value is optional. White space is insignificant, blank lines
and value is optional. Whitespace is insignificant, blank lines
are ignored. Hash marks (<quote>#</quote>) introduce comments
anywhere.
</para>
......@@ -504,7 +504,7 @@ syslog = 2
</indexterm>
The configuration file is reread whenever the postmaster receives
a <systemitem>SIGHUP</> signal (which is most easily sent by means
of <application>pg_ctl reload</>). The postmaster also propagates
of <literal>pg_ctl reload</>). The postmaster also propagates
this signal to all already-running backend processes, so that
existing sessions also get the new default.
Alternatively, you can send the signal to only one backend process
......@@ -886,7 +886,7 @@ env PGOPTIONS='-c geqo=off' psql
<term><varname>LOG_PID</varname> (<type>boolean</type>)</term>
<listitem>
<para>
Prefixes each server log message with the process id of the
Prefixes each server log message with the process ID of the
backend process. This is useful to sort out which messages
pertain to which connection. The default is off.
</para>
......
doc/src/sgml/syntax.sgml
View file @ 731204e0
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/syntax.sgml,v 1.55 2001/12/08 03:24:23 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/syntax.sgml,v 1.56 2002/01/07 02:29:13 petere Exp $
-->
<chapter id="sql-syntax">
......@@ -102,7 +102,8 @@ INSERT INTO MY_TABLE VALUES (3, 'hi there');
<para>
SQL identifiers and key words must begin with a letter
(<literal>a</literal>-<literal>z</literal>) or underscore
(<literal>a</literal>-<literal>z</literal>, but also letters with
diacritical marks and non-Latin letters) or an underscore
(<literal>_</literal>). Subsequent characters in an identifier or
key word can be letters, digits
(<literal>0</literal>-<literal>9</literal>), or underscores,
......@@ -200,9 +201,9 @@ UPDATE "my_table" SET "a" = 5;
</indexterm>
<para>
There are four kinds of <firstterm>implicitly typed
There are four kinds of <firstterm>implicitly-typed
constants</firstterm> in <productname>PostgreSQL</productname>:
strings, bit strings, integers, and floating point numbers.
strings, bit strings, integers, and floating-point numbers.
Constants can also be specified with explicit types, which can
enable more accurate representation and more efficient handling by
the system. The implicit constants are described below; explicit
......@@ -266,12 +267,12 @@ SELECT 'foobar';
SELECT 'foo' 'bar';
</programlisting>
is not valid syntax, and <productname>PostgreSQL</productname> is
consistant with <acronym>SQL9x</acronym> in this regard.
consistent with <acronym>SQL9x</acronym> in this regard.
</para>
</sect3>
<sect3 id="sql-syntax-bit-strings">
<title>Bit String Constants</title>
<title>Bit-String Constants</title>
<indexterm zone="sql-syntax-bit-strings">
<primary>bit strings</primary>
......@@ -279,12 +280,12 @@ SELECT 'foo' 'bar';
</indexterm>
<para>
Bit string constants look like string constants with a
Bit-string constants look like string constants with a
<literal>B</literal> (upper or lower case) immediately before the
opening quote (no intervening whitespace), e.g.,
<literal>B'1001'</literal>. The only characters allowed within
bit string constants are <literal>0</literal> and
<literal>1</literal>. Bit string constants can be continued
bit-string constants are <literal>0</literal> and
<literal>1</literal>. Bit-string constants can be continued
across lines in the same way as regular string constants.
</para>
</sect3>
......@@ -303,7 +304,7 @@ SELECT 'foo' 'bar';
</sect3>
<sect3>
<title>Floating Point Constants</title>
<title>Floating-Point Constants</title>
<indexterm>
<primary>floating point</primary>
......@@ -311,7 +312,7 @@ SELECT 'foo' 'bar';
</indexterm>
<para>
Floating point constants are accepted in these general forms:
Floating-point constants are accepted in these general forms:
<synopsis>
<replaceable>digits</replaceable>.<optional><replaceable>digits</replaceable></optional><optional>e<optional>+-</optional><replaceable>digits</replaceable></optional>
<optional><replaceable>digits</replaceable></optional>.<replaceable>digits</replaceable><optional>e<optional>+-</optional><replaceable>digits</replaceable></optional>
......@@ -321,7 +322,7 @@ SELECT 'foo' 'bar';
digits. At least one digit must be before or after the decimal
point. At least one digit must follow the exponent delimiter
(<literal>e</literal>) if that field is present.
Thus, a floating point constant is distinguished from an integer
Thus, a floating-point constant is distinguished from an integer
constant by the presence of either the decimal point or the
exponent clause (or both). There must not be a space or other
characters embedded in the constant.
......@@ -329,7 +330,7 @@ SELECT 'foo' 'bar';
<informalexample>
<para>
These are some examples of valid floating point constants:
These are some examples of valid floating-point constants:
<literallayout>
3.5
4.
......@@ -341,7 +342,7 @@ SELECT 'foo' 'bar';
</informalexample>
<para>
Floating point constants are of type <type>DOUBLE
Floating-point constants are of type <type>DOUBLE
PRECISION</type>. <type>REAL</type> can be specified explicitly
by using <acronym>SQL</acronym> string notation or
<productname>PostgreSQL</productname> type notation:
......@@ -385,9 +386,13 @@ CAST ( '<replaceable>string</replaceable>' AS <replaceable>type</replaceable> )
<replaceable>typename</replaceable> ( <replaceable>value</replaceable> )
</synopsis>
although this only works for types whose names are also valid as
function names. (For example, <literal>double precision</literal>
can't be used this way --- but the equivalent <literal>float8</literal>
can.)
function names. For example, <literal>double precision</literal>
can't be used this way, but the equivalent <literal>float8</literal>
can. Also, the names <literal>interval</>, <literal>time</>, and
<literal>timestamp</> can only be used in this context if they are
double-quoted, because of parser conflicts. Therefore, the use of
the function-like cast syntax leads to inconsistencies and should
probably be avoided in new applications.
</para>
<para>
......@@ -429,8 +434,8 @@ CAST ( '<replaceable>string</replaceable>' AS <replaceable>type</replaceable> )
<para>
Individual array elements can be placed between double-quote
marks (<literal>"</literal>) <!-- " --> to avoid ambiguity
problems with respect to white space. Without quote marks, the
array-value parser will skip leading white space.
problems with respect to whitespace. Without quote marks, the
array-value parser will skip leading whitespace.
</para>
<para>
......@@ -495,7 +500,7 @@ CAST ( '<replaceable>string</replaceable>' AS <replaceable>type</replaceable> )
<para>
When working with non-SQL-standard operator names, you will usually
need to separate adjacent operators with spaces to avoid ambiguity.
For example, if you have defined a left-unary operator named <literal>@</literal>,
For example, if you have defined a left unary operator named <literal>@</literal>,
you cannot write <literal>X*@Y</literal>; you must write
<literal>X* @Y</literal> to ensure that
<productname>PostgreSQL</productname> reads it as two operator names
......@@ -574,7 +579,7 @@ CAST ( '<replaceable>string</replaceable>' AS <replaceable>type</replaceable> )
<listitem>
<para>
The period (<literal>.</literal>) is used in floating point
The period (<literal>.</literal>) is used in floating-point
constants, and to separate table and column names.
</para>
</listitem>
......@@ -670,8 +675,8 @@ CAST ( '<replaceable>string</replaceable>' AS <replaceable>type</replaceable> )
<listitem>
<para>
The identity (transaction ID) of the inserting transaction for
this tuple. (Note: a tuple is an individual state of a row;
each UPDATE of a row creates a new tuple for the same logical row.)
this tuple. (Note: A tuple is an individual state of a row;
each update of a row creates a new tuple for the same logical row.)
</para>
</listitem>
</varlistentry>
......@@ -733,7 +738,7 @@ CAST ( '<replaceable>string</replaceable>' AS <replaceable>type</replaceable> )
counter to wrap around. Hence, it is bad practice to assume that OIDs
are unique, unless you take steps to ensure that they are unique.
Recommended practice when using OIDs for row identification is to create
a unique index on the OID column of each table for which the OID will be
a unique constraint on the OID column of each table for which the OID will be
used. Never assume that OIDs are unique across tables; use the
combination of <structfield>tableoid</> and row OID if you need a database-wide
identifier. (Future releases of <productname>PostgreSQL</productname> are likely to use a separate
......@@ -756,12 +761,6 @@ CAST ( '<replaceable>string</replaceable>' AS <replaceable>type</replaceable> )
In practice this limit is not a problem --- note that the limit is on
number of SQL queries, not number of tuples processed.
</para>
<para>
For further information on the system attributes consult
<xref linkend="STON87a">.
</para>
</sect1>
......@@ -916,7 +915,7 @@ $<replaceable>number</replaceable>
<programlisting>
CREATE FUNCTION dept (text) RETURNS dept
AS 'SELECT * FROM dept WHERE name = $1'
LANGUAGE 'sql';
LANGUAGE SQL;
</programlisting>
Here the <literal>$1</literal> will be replaced by the first
......
doc/src/sgml/xaggr.sgml
View file @ 731204e0
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/xaggr.sgml,v 1.15 2001/11/21 06:09:45 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/xaggr.sgml,v 1.16 2002/01/07 02:29:14 petere Exp $
-->
<chapter id="xaggr">
......@@ -39,42 +39,42 @@ $Header: /cvsroot/pgsql/doc/src/sgml/xaggr.sgml,v 1.15 2001/11/21 06:09:45 thoma
the column values from each row. <function>Sum</> is an
example of this kind of aggregate. <function>Sum</> starts at
zero and always adds the current row's value to
its running total. For example, if we want to make a Sum
its running total. For example, if we want to make a <function>sum</>
aggregate to work on a data type for complex numbers,
we only need the addition function for that data type.
The aggregate definition is:
<programlisting>
<programlisting>
CREATE AGGREGATE complex_sum (
sfunc = complex_add,
basetype = complex,
stype = complex,
initcond = '(0,0)'
);
</programlisting>
<screen>
SELECT complex_sum(a) FROM test_complex;
+------------+
|complex_sum |
+------------+
|(34,53.9) |
+------------+
</programlisting>
complex_sum
-------------
(34,53.9)
</screen>
(In practice, we'd just name the aggregate <function>sum</function>, and rely on
<productname>PostgreSQL</productname> to figure out which kind
of sum to apply to a complex column.)
of sum to apply to a column of type <type>complex</type>.)
</para>
<para>
The above definition of <function>Sum</function> will return zero (the initial
The above definition of <function>sum</function> will return zero (the initial
state condition) if there are no non-null input values.
Perhaps we want to return NULL in that case instead --- SQL92
expects <function>Sum</function> to behave that way. We can do this simply by
Perhaps we want to return NULL in that case instead --- the SQL standard
expects <function>sum</function> to behave that way. We can do this simply by
omitting the <literal>initcond</literal> phrase, so that the initial state
condition is NULL. Ordinarily this would mean that the <literal>sfunc</literal>
would need to check for a NULL state-condition input, but for
<function>Sum</function> and some other simple aggregates like <function>Max</> and <function>Min</>,
<function>sum</function> and some other simple aggregates like <function>max</> and <function>min</>,
it's sufficient to insert the first non-null input value into
the state variable and then start applying the transition function
at the second non-null input value. <productname>PostgreSQL</productname>
......@@ -93,7 +93,7 @@ SELECT complex_sum(a) FROM test_complex;
</para>
<para>
<function>Average</> is a more complex example of an aggregate. It requires
<function>Avg</> (average) is a more complex example of an aggregate. It requires
two pieces of running state: the sum of the inputs and the count
of the number of inputs. The final result is obtained by dividing
these quantities. Average is typically implemented by using a
......@@ -101,7 +101,7 @@ SELECT complex_sum(a) FROM test_complex;
the built-in implementation of <function>avg(float8)</function>
looks like:
<programlisting>
<programlisting>
CREATE AGGREGATE avg (
sfunc = float8_accum,
basetype = float8,
......@@ -109,18 +109,13 @@ CREATE AGGREGATE avg (
finalfunc = float8_avg,
initcond = '{0,0}'
);
</programlisting>
</programlisting>
</para>
<para>
For further details see
<!--
Not available in the Programmer's Guide
<xref endterm="sql-createaggregate-title"
linkend="sql-createaggregate-title">.
-->
<command>CREATE AGGREGATE</command> in
<citetitle>The PostgreSQL User's Guide</citetitle>.
For further details see the description of the <command>CREATE
AGGREGATE</command> command in the <citetitle>Reference
Manual</citetitle>.
</para>
</chapter>
......
doc/src/sgml/xfunc.sgml
View file @ 731204e0
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/xfunc.sgml,v 1.45 2001/11/21 06:09:45 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/xfunc.sgml,v 1.46 2002/01/07 02:29:14 petere Exp $
-->
<chapter id="xfunc">
......@@ -59,7 +59,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/xfunc.sgml,v 1.45 2001/11/21 06:09:45 thoma
<para>
Every kind
of function can take a base type, a composite type or
of function can take a base type, a composite type, or
some combination as arguments (parameters). In addition,
every kind of function can return a base type or
a composite type. It's easiest to define <acronym>SQL</acronym>
......@@ -67,6 +67,12 @@ $Header: /cvsroot/pgsql/doc/src/sgml/xfunc.sgml,v 1.45 2001/11/21 06:09:45 thoma
can also be found in <filename>funcs.sql</filename>
and <filename>funcs.c</filename> in the tutorial directory.
</para>
<para>
Throughout this chapter, it can be useful to look at the reference
page of the <command>CREATE FUNCTION</command> command to
understand the examples better.
</para>
</sect1>
<sect1 id="xfunc-sql">
......@@ -268,7 +274,7 @@ SELECT name, double_salary(EMP) AS dream
<para>
Notice the use of the syntax <literal>$1.salary</literal>
to select one field of the argument row value. Also notice
how the calling SELECT command uses a table name to denote
how the calling <command>SELECT</> command uses a table name to denote
the entire current row of that table as a composite value.
</para>
......@@ -376,7 +382,7 @@ ERROR: parser: parse error at or near "."
<para>
Another way to use a function returning a row result is to declare a
second function accepting a rowtype parameter, and pass the function
second function accepting a row type parameter, and pass the function
result to it:
<programlisting>
......@@ -400,15 +406,15 @@ SELECT getname(new_emp());
<para>
As previously mentioned, an SQL function may be declared as
returning <literal>SETOF</literal> <replaceable>sometype</>.
In this case the function's final SELECT query is executed to
returning <literal>SETOF <replaceable>sometype</></literal>.
In this case the function's final <command>SELECT</> query is executed to
completion, and each row it outputs is returned as an element
of the set.
</para>
<para>
Functions returning sets may only be called in the target list
of a SELECT query. For each row that the SELECT generates by itself,
of a <command>SELECT</> query. For each row that the <command>SELECT</> generates by itself,
the function returning set is invoked, and an output row is generated
for each element of the function's result set. An example:
......@@ -449,9 +455,9 @@ SELECT name, listchildren(name) FROM nodes;
(5 rows)
</screen>
In the last SELECT,
notice that no output row appears for Child2, Child3, etc.
This happens because listchildren() returns an empty set
In the last <command>SELECT</command>,
notice that no output row appears for <literal>Child2</>, <literal>Child3</>, etc.
This happens because <function>listchildren</function> returns an empty set
for those inputs, so no output rows are generated.
</para>
</sect2>
......@@ -607,7 +613,7 @@ CREATE FUNCTION square_root(double precision) RETURNS double precision
<note>
<para>
The user id the <application>PostgreSQL</application> server runs
The user ID the <application>PostgreSQL</application> server runs
as must be able to traverse the path to the file you intend to
load. Making the file or a higher-level directory not readable
and/or not executable by the <quote>postgres</quote> user is a
......@@ -671,7 +677,7 @@ CREATE FUNCTION square_root(double precision) RETURNS double precision
<para>
<xref linkend="xfunc-c-type-table"> gives the C type required for
parameters in the C functions that will be loaded into
<productname>PostgreSQL</>
<productname>PostgreSQL</>.
The <quote>Defined In</quote> column gives the header file that
needs to be included to get the type definition. (The actual
definition may be in a different file that is included by the
......@@ -1262,9 +1268,9 @@ concat_text(PG_FUNCTION_ARGS)
At first glance, the version-1 coding conventions may appear to
be just pointless obscurantism. However, they do offer a number
of improvements, because the macros can hide unnecessary detail.
An example is that in coding add_one_float8, we no longer need to
be aware that float8 is a pass-by-reference type. Another
example is that the GETARG macros for variable-length types hide
An example is that in coding <function>add_one_float8</>, we no longer need to
be aware that <type>float8</type> is a pass-by-reference type. Another
example is that the <literal>GETARG</> macros for variable-length types hide
the need to deal with fetching <quote>toasted</quote> (compressed or
out-of-line) values. The old-style <function>copytext</function>
and <function>concat_text</function> functions shown above are
......@@ -1277,7 +1283,7 @@ concat_text(PG_FUNCTION_ARGS)
<para>
One big improvement in version-1 functions is better handling of NULL
inputs and results. The macro <function>PG_ARGISNULL(n)</function>
inputs and results. The macro <function>PG_ARGISNULL(<replaceable>n</>)</function>
allows a function to test whether each input is NULL (of course, doing
this is only necessary in functions not declared <quote>strict</>).
As with the
......@@ -1287,7 +1293,7 @@ concat_text(PG_FUNCTION_ARGS)
<function>PG_GETARG_<replaceable>xxx</replaceable>()</function> until
one has verified that the argument isn't NULL.
To return a NULL result, execute <function>PG_RETURN_NULL()</function>;
this works in both strict and non-strict functions.
this works in both strict and nonstrict functions.
</para>
<para>
......@@ -1323,7 +1329,7 @@ FROM emp
WHERE name = 'Bill' OR name = 'Sam';
</programlisting>
In the query above, we can define c_overpaid as:
In the query above, we can define <function>c_overpaid</> as:
<programlisting>
#include "postgres.h"
......@@ -1371,13 +1377,13 @@ c_overpaid(PG_FUNCTION_ARGS)
three arguments: the argument of type <type>TupleTableSlot*</type> passed into
the function, the name of the desired attribute, and a
return parameter that tells whether the attribute
is null. <function>GetAttributeByName</function> returns a Datum
value that you can convert to the proper datatype by using the
is null. <function>GetAttributeByName</function> returns a <type>Datum</type>
value that you can convert to the proper data type by using the
appropriate <function>DatumGet<replaceable>XXX</replaceable>()</function> macro.
</para>
<para>
The following query lets <productname>PostgreSQL</productname>
The following command lets <productname>PostgreSQL</productname>
know about the <function>c_overpaid</function> function:
<programlisting>
......
doc/src/sgml/xindex.sgml
View file @ 731204e0
This diff is collapsed.
doc/src/sgml/xoper.sgml
View file @ 731204e0
This diff is collapsed.
doc/src/sgml/xplang.sgml
View file @ 731204e0
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.16 2001/11/21 06:09:45 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.17 2002/01/07 02:29:14 petere Exp $
-->
<chapter id="xplang">
<title id="xplang-title">Procedural Languages</title>
<sect1 id="xplang-intro">
<title>Introduction</title>
<para>
<productname>PostgreSQL</productname> allows users to add new
programming languages to be available for writing functions and
......@@ -23,11 +26,12 @@ $Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.16 2001/11/21 06:09:45 thom
</para>
<para>
Writing a handler for a new procedural language is outside the
scope of this manual, although some information is provided in
the CREATE LANGUAGE reference page. Several procedural languages are
available in the standard <productname>PostgreSQL</productname> distribution.
Writing a handler for a new procedural language is described in
<xref linkend="xfunc-plhandler">. Several procedural languages are
available in the standard <productname>PostgreSQL</productname>
distribution, which can serve as examples.
</para>
</sect1>
<sect1 id="xplang-install">
<title>Installing Procedural Languages</title>
......@@ -73,7 +77,7 @@ createlang plpgsql template1
</para>
</step>
<step performance="required">
<step performance="required" id="xplang-install-cr1">
<para>
The handler must be declared with the command
<synopsis>
......@@ -88,43 +92,51 @@ CREATE FUNCTION <replaceable>handler_function_name</replaceable> ()
</para>
</step>
<step performance="required">
<step performance="required" id="xplang-install-cr2">
<para>
The PL must be declared with the command
<synopsis>
CREATE <optional>TRUSTED</optional> <optional>PROCEDURAL</optional> LANGUAGE <replaceable>language-name</replaceable>
HANDLER <replaceable>handler_function_name</replaceable>;
</synopsis>
The optional key word <token>TRUSTED</token> tells
whether ordinary database users that have no superuser
privileges should be allowed to use this language to create functions
and trigger procedures. Since PL functions are
executed inside the database backend, the <acronym>TRUSTED</acronym>
flag should only be given for
languages that do not allow access to database backends
internals or the file system. The languages <application>PL/pgSQL</application>,
<application>PL/Tcl</application>, and <application>PL/Perl</application> are known to be trusted; the language <application>PL/TclU</application>
should <emphasis>not</emphasis> be marked trusted.
The optional key word <literal>TRUSTED</literal> tells whether
ordinary database users that have no superuser privileges should
be allowed to use this language to create functions and trigger
procedures. Since PL functions are executed inside the database
server, the <literal>TRUSTED</literal> flag should only be given
for languages that do not allow access to database server
internals or the file system. The languages
<application>PL/pgSQL</application>,
<application>PL/Tcl</application>,
<application>PL/Perl</application>, and
<application>PL/Python</application> are known to be trusted;
the languages <application>PL/TclU</application> and
<application>PL/PerlU</application> are designed to provide
unlimited functionality should <emphasis>not</emphasis> be
marked trusted.
</para>
</step>
</procedure>
<para>
In a default <productname>PostgreSQL</productname> installation, the
handler for the <application>PL/pgSQL</application> language is built and installed into the
<quote>library</quote> directory. If Tcl/Tk support is configured
in, the handlers for PL/Tcl and PL/TclU are also built and installed in
the same location. Likewise, the PL/Perl handler is built and installed
if Perl support is configured. The <filename>createlang</filename>
script automates the two CREATE steps described above.
In a default <productname>PostgreSQL</productname> installation,
the handler for the <application>PL/pgSQL</application> language
is built and installed into the <quote>library</quote>
directory. If Tcl/Tk support is configured in, the handlers for
PL/Tcl and PL/TclU are also built and installed in the same
location. Likewise, the PL/Perl and PL/PerlU handlers are built
and installed if Perl support is configured, and PL/Python is
installed if Python support is configured. The
<filename>createlang</filename> script automates <xref
linkend="xplang-install-cr1"> and <xref
linkend="xplang-install-cr2"> described above.
</para>
<procedure>
<title>Example</title>
<example>
<title>Manual Installation of <application>PL/pgSQL</application></title>
<step performance="required">
<para>
The following command tells the database where to find the
The following command tells the database server where to find the
shared object for the <application>PL/pgSQL</application> language's call handler function.
<programlisting>
......@@ -132,9 +144,7 @@ CREATE FUNCTION plpgsql_call_handler () RETURNS OPAQUE AS
'$libdir/plpgsql' LANGUAGE C;
</programlisting>
</para>
</step>
<step performance="Required">
<para>
The command
<programlisting>
......@@ -145,8 +155,7 @@ CREATE TRUSTED PROCEDURAL LANGUAGE plpgsql
should be invoked for functions and trigger procedures where the
language attribute is <literal>plpgsql</literal>.
</para>
</step>
</procedure>
</example>
</sect1>
......
doc/src/sgml/xtypes.sgml
View file @ 731204e0
This diff is collapsed.
src/interfaces/ecpg/lib/error.c
View file @ 731204e0
/* $Header: /cvsroot/pgsql/src/interfaces/ecpg/lib/Attic/error.c,v 1.14 2001/12/23 12:17:41 meskes Exp $ */
/* $Header: /cvsroot/pgsql/src/interfaces/ecpg/lib/Attic/error.c,v 1.15 2002/01/07 02:29:15 petere Exp $ */
#include "postgres_fe.h"
......@@ -54,7 +54,7 @@ ECPGraise(int line, int code, const char *str)
case ECPG_FLOAT_FORMAT:
snprintf(sqlca.sqlerrm.sqlerrmc, sizeof(sqlca.sqlerrm.sqlerrmc),
"Not correctly formatted floating point type: %s in line %d.", str, line);
"Not correctly formatted floating-point type: %s in line %d.", str, line);
break;
case ECPG_CONVERT_BOOL:
......
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