Commit 731204e0 authored by Peter Eisentraut's avatar Peter Eisentraut

Editorial review

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