From 934c21344ca83ec7b29f9fb88e566384e0d32739 Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter_e@gmx.net>
Date: Wed, 12 Nov 2003 22:47:47 +0000
Subject: [PATCH] Documentation cleanup
---
doc/src/sgml/ecpg.sgml | 20 +-
doc/src/sgml/extend.sgml | 102 +++++---
doc/src/sgml/install-win32.sgml | 4 +-
doc/src/sgml/libpq.sgml | 86 +++----
doc/src/sgml/lobj.sgml | 4 +-
doc/src/sgml/plpgsql.sgml | 334 +++++++++++++-------------
doc/src/sgml/plpython.sgml | 23 +-
doc/src/sgml/pltcl.sgml | 4 +-
doc/src/sgml/ref/create_function.sgml | 8 +-
doc/src/sgml/release.sgml | 38 +--
doc/src/sgml/typeconv.sgml | 6 +-
doc/src/sgml/xaggr.sgml | 14 +-
doc/src/sgml/xfunc.sgml | 96 ++++----
13 files changed, 377 insertions(+), 362 deletions(-)
diff --git a/doc/src/sgml/ecpg.sgml b/doc/src/sgml/ecpg.sgml
index 08f22ab64e4..0e426b179bb 100644
--- a/doc/src/sgml/ecpg.sgml
+++ b/doc/src/sgml/ecpg.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.53 2003/10/17 18:57:00 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ecpg.sgml,v 1.54 2003/11/12 22:47:47 petere Exp $
-->
<chapter id="ecpg">
@@ -284,7 +284,7 @@ EXEC SQL COMMIT;
</para>
<para>
- Single-row Select:
+ Single-row select:
<programlisting>
EXEC SQL SELECT foo INTO :FooBar FROM table1 WHERE ascii = 'doodad';
</programlisting>
@@ -359,7 +359,7 @@ EXEC SQL AT <replaceable>connection-name</replaceable> SELECT ...;
The second option is to execute a statement to switch the current
connection. That statement is:
<programlisting>
-SET CONNECTION <replaceable>connection-name</replaceable>;
+EXEC SQL SET CONNECTION <replaceable>connection-name</replaceable>;
</programlisting>
This option is particularly convenient if many statements are to be
executed on the same connection.
@@ -392,7 +392,7 @@ SET CONNECTION <replaceable>connection-name</replaceable>;
write the name of a C variable into the SQL statement, prefixed by
a colon. For example:
<programlisting>
-INSERT INTO sometable VALUES (:v1, 'foo', :v2);
+EXEC SQL INSERT INTO sometable VALUES (:v1, 'foo', :v2);
</programlisting>
This statements refers to two C variables named
<varname>v1</varname> and <varname>v2</varname> and also uses a
@@ -592,7 +592,7 @@ EXEC SQL BEGIN DECLARE SECTION;
const char *stmt = "CREATE TABLE test1 (...);";
EXEC SQL END DECLARE SECTION;
-EXECUTE IMMEDIATE :stmt;
+EXEC SQL EXECUTE IMMEDIATE :stmt;
</programlisting>
You may not execute statements that retrieve data (e.g.,
<command>SELECT</command>) this way.
@@ -611,9 +611,9 @@ EXEC SQL BEGIN DECLARE SECTION;
const char *stmt = "INSERT INTO test1 VALUES(?, ?);";
EXEC SQL END DECLARE SECTION;
-PREPARE mystmt FROM :stmt;
+EXEC SQL PREPARE mystmt FROM :stmt;
...
-EXECUTE mystmt USING 42, 'foobar';
+EXEC SQL EXECUTE mystmt USING 42, 'foobar';
</programlisting>
If the statement you are executing returns values, then add an
<literal>INTO</literal> clause:
@@ -624,9 +624,9 @@ int v1, v2;
VARCHAR v3;
EXEC SQL END DECLARE SECTION;
-PREPARE mystmt FROM :stmt;
+EXEC SQL PREPARE mystmt FROM :stmt;
...
-EXECUTE mystmt INTO v1, v2, v3 USING 37;
+EXEC SQL EXECUTE mystmt INTO v1, v2, v3 USING 37;
</programlisting>
An <command>EXECUTE</command> command may have an
<literal>INTO</literal> clause, a <literal>USING</literal> clause,
@@ -668,7 +668,7 @@ EXEC SQL DEALLOCATE PREPARE <replaceable>name</replaceable>;
EXEC SQL ALLOCATE DESCRIPTOR <replaceable>identifier</replaceable>;
</programlisting>
The identifier serves as the <quote>variable name</quote> of the
- descriptor area. The scope of the allocated descriptor is WHAT?.
+ descriptor area. <comment>The scope of the allocated descriptor is WHAT?.</comment>
When you don't need the descriptor anymore, you should deallocate
it:
<programlisting>
diff --git a/doc/src/sgml/extend.sgml b/doc/src/sgml/extend.sgml
index 1348d59d8ff..a73909fba67 100644
--- a/doc/src/sgml/extend.sgml
+++ b/doc/src/sgml/extend.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.25 2003/09/11 21:42:19 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.26 2003/11/12 22:47:47 petere Exp $
-->
<chapter id="extend">
@@ -105,52 +105,74 @@ $Header: /cvsroot/pgsql/doc/src/sgml/extend.sgml,v 1.25 2003/09/11 21:42:19 momj
<para>
<productname>PostgreSQL</productname> data types are divided into base
- types, composite types, domain types, and pseudo-types.
+ types, composite types, domains, and pseudo-types.
</para>
- <para>
- Base types are those, like <type>int4</type>, that are implemented
- below the level of the <acronym>SQL</> language (typically in a low-level
- language such as C). They generally correspond to
- what are often known as abstract data types.
- <productname>PostgreSQL</productname>
- can only operate on such types through functions provided
- by the user and only understands the behavior of such
- types to the extent that the user describes them. Base types are
- further subdivided into scalar and array types. For each scalar type,
- a corresponding array type is automatically created that can hold
- variable-size arrays of that scalar type.
- </para>
+ <sect2>
+ <title>Base Types</title>
- <para>
- Composite types, or row types, are created whenever the user creates a
- table; it's also possible to define a <quote>stand-alone</> composite
- type with no associated table. A composite type is simply a list of
- base types with associated field names. A value of a composite type
- is a row or record of field values. The user can access the component
- fields from <acronym>SQL</> queries.
- </para>
+ <para>
+ Base types are those, like <type>int4</type>, that are
+ implemented below the level of the <acronym>SQL</> language
+ (typically in a low-level language such as C). They generally
+ correspond to what are often known as abstract data types.
+ <productname>PostgreSQL</productname> can only operate on such
+ types through functions provided by the user and only understands
+ the behavior of such types to the extent that the user describes
+ them. Base types are further subdivided into scalar and array
+ types. For each scalar type, a corresponding array type is
+ automatically created that can hold variable-size arrays of that
+ scalar type.
+ </para>
+ </sect2>
- <para>
- A domain type is based on a particular base
- type and for many purposes is interchangeable with its base type.
- However, a domain may have constraints that restrict its valid values
- to a subset of what the underlying base type would allow. Domains can
- be created by simple <acronym>SQL</> commands.
- </para>
+ <sect2>
+ <title>Composite Types</title>
- <para>
- Finally, there are a few <quote>pseudo-types</> for special purposes.
- Pseudo-types cannot appear as fields of tables or composite types, but
- they can be used to declare the argument and result types of functions.
- This provides a mechanism within the type system to identify special
- classes of functions. <xref
- linkend="datatype-pseudotypes-table"> lists the existing
- pseudo-types.
- </para>
+ <para>
+ Composite types, or row types, are created whenever the user
+ creates a table; it's also possible to define a
+ <quote>stand-alone</> composite type with no associated table. A
+ composite type is simply a list of base types with associated
+ field names. A value of a composite type is a row or record of
+ field values. The user can access the component fields from
+ <acronym>SQL</> queries.
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Domains</title>
+
+ <para>
+ A domain is based on a particular base type and for many purposes
+ is interchangeable with its base type. However, a domain may
+ have constraints that restrict its valid values to a subset of
+ what the underlying base type would allow.
+ </para>
+
+ <para>
+ Domains can be created using the <acronym>SQL</> commands
+ <command>CREATE DOMAIN</command>. Their creation and use is not
+ discussed in this chapter.
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Pseudo-Types</title>
+
+ <para>
+ There are a few <quote>pseudo-types</> for special purposes.
+ Pseudo-types cannot appear as columns of tables or attributes of
+ composite types, but they can be used to declare the argument and
+ result types of functions. This provides a mechanism within the
+ type system to identify special classes of functions. <xref
+ linkend="datatype-pseudotypes-table"> lists the existing
+ pseudo-types.
+ </para>
+ </sect2>
<sect2 id="extend-types-polymorphic">
- <title>Polymorphic Types and Functions</title>
+ <title>Polymorphic Types</title>
<indexterm zone="extend-types-polymorphic">
<primary>polymorphic type</primary>
diff --git a/doc/src/sgml/install-win32.sgml b/doc/src/sgml/install-win32.sgml
index 7beb5ea97d1..5feb4e5a2c5 100644
--- a/doc/src/sgml/install-win32.sgml
+++ b/doc/src/sgml/install-win32.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/install-win32.sgml,v 1.15 2003/11/04 09:55:38 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/install-win32.sgml,v 1.16 2003/11/12 22:47:47 petere Exp $
-->
<chapter id="install-win32">
@@ -109,7 +109,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/install-win32.sgml,v 1.15 2003/11/04 09:55:
<para>
<application>psql</application> is compiled as a <quote>console
- application</>. As the Win32 console windows use a different
+ application</>. As the Windows console windows use a different
encoding than the rest of the system, you must take special care
when using 8-bit characters at the <application>psql</application>
prompt. When <application>psql</application> detects a problematic
diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml
index 4431df7911c..f1b96e2affe 100644
--- a/doc/src/sgml/libpq.sgml
+++ b/doc/src/sgml/libpq.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.141 2003/11/01 01:56:29 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/libpq.sgml,v 1.142 2003/11/12 22:47:47 petere Exp $
-->
<chapter id="libpq">
@@ -355,7 +355,7 @@ PostgresPollingStatusType PQconnectPoll(PGconn *conn);
whilst doing so.
The point of this approach is that the waits for I/O to complete can occur
in the application's main loop, rather than down inside
- <function>PQconnectdb()</>, and so the application can manage this
+ <function>PQconnectdb</>, and so the application can manage this
operation in parallel with other activities.
</para>
<para>
@@ -829,8 +829,8 @@ has been sent to the server and not yet completed.
<caution>
<para>
<function>PQtransactionStatus</> will give incorrect results when using
-a <productname>PostgreSQL</> 7.3 server that has <literal>AUTOCOMMIT</>
-set to <literal>OFF</>. The server-side autocommit feature has been
+a <productname>PostgreSQL</> 7.3 server that has the parameter <literal>autocommit</>
+set to off. The server-side autocommit feature has been
deprecated and does not exist in later server versions.
</para>
</caution>
@@ -1028,7 +1028,7 @@ PGresult *PQexec(PGconn *conn, const char *command);
It is allowed to include multiple SQL commands (separated by semicolons) in
the command string. Multiple queries sent in a single <function>PQexec</>
call are processed in a single transaction, unless there are explicit
-BEGIN/COMMIT commands included in the query string to divide it into multiple
+<command>BEGIN</command>/<command>COMMIT</command> commands included in the query string to divide it into multiple
transactions. Note however that the returned <structname>PGresult</structname>
structure describes only the result of the last command executed from the
string. Should one of the commands fail, processing of the string stops with
@@ -1737,7 +1737,7 @@ This function is deprecated (except for its use in connection with
<command>COPY</>), because it is possible for a single
<structname>PGresult</>
to contain text data in some columns and binary data in others.
-<function>PQfformat()</> is preferred. <function>PQbinaryTuples</>
+<function>PQfformat</> is preferred. <function>PQbinaryTuples</>
returns 1 only if all columns of the result are binary (format 1).
</para>
</listitem>
@@ -2068,7 +2068,7 @@ unsigned char *PQescapeBytea(const unsigned char *from,
<function>PQescapeBytea</> returns an escaped version of the
<parameter>from</parameter> parameter binary string in memory
allocated with <function>malloc()</>. This memory must be freed
- using <function>PQfreemem()</> when the result is no longer needed.
+ using <function>PQfreemem</> when the result is no longer needed.
The return string has all special characters replaced so that they
can be properly processed by the
<productname>PostgreSQL</productname> string literal parser, and
@@ -2102,7 +2102,7 @@ unsigned char *PQunescapeBytea(const unsigned char *from, size_t *to_length);
It returns a pointer to a buffer allocated with
<function>malloc()</function>, or null on error, and puts the size of
the buffer in <parameter>to_length</parameter>. The result must be
- freed using <function>PQfreemem()</> when it is no longer needed.
+ freed using <function>PQfreemem</> when it is no longer needed.
</para>
</listitem>
</varlistentry>
@@ -2122,9 +2122,9 @@ void PQfreemem(void *ptr);
<function>PQescapeBytea</function>,
<function>PQunescapeBytea</function>,
and <function>PQnotifies</function>.
- It is needed by Win32, which can not free memory across
+ It is needed by Microsoft Windows, which cannot free memory across
DLLs, unless multithreaded DLLs (<option>/MD</option> in VC6) are used.
- On other platforms it is the same as <function>free()</>.
+ On other platforms, this function is the same as the standard library function <function>free()</>.
</para>
</listitem>
</varlistentry>
@@ -2420,7 +2420,7 @@ while waiting for input from the database server. However, it is still
possible that the application will block waiting to send output to the
server. This is relatively uncommon but can happen if very long SQL commands
or data values are sent. (It is much more probable if the application
-sends data via COPY IN, however.) To prevent this possibility and achieve
+sends data via <command>COPY IN</command>, however.) To prevent this possibility and achieve
completely nonblocking database operation, the following additional
functions may be used.
@@ -2634,15 +2634,10 @@ After processing a <structname>PGnotify</structname> object returned by
<structname>PGnotify</structname> pointer; the
<structfield>relname</structfield> and <structfield>extra</structfield> fields
do not represent separate allocations.
+(At present, the <structfield>extra</structfield> field is unused and will
+always point to an empty string.)
</para>
-<note>
-<para>
- At present the <structfield>extra</structfield> field is unused and will
- always point to an empty string.
-</para>
-</note>
-
<note>
<para>
In <productname>PostgreSQL</productname> 6.4 and later,
@@ -2657,28 +2652,28 @@ of asynchronous notification.
</para>
<para>
-<function>PQnotifies()</function> does not actually read data from the server; it just
+<function>PQnotifies</function> does not actually read data from the server; it just
returns messages previously absorbed by another <application>libpq</application>
function. In prior releases of <application>libpq</application>, the only way
to ensure timely receipt of <command>NOTIFY</> messages was to constantly submit commands,
-even empty ones, and then check <function>PQnotifies()</function> after each
-<function>PQexec()</function>. While this still works, it is
+even empty ones, and then check <function>PQnotifies</function> after each
+<function>PQexec</function>. While this still works, it is
deprecated as a waste of processing power.
</para>
<para>
A better way to check for <command>NOTIFY</>
messages when you have no useful commands to execute is to call
-<function>PQconsumeInput()</function>, then check
-<function>PQnotifies()</function>.
+<function>PQconsumeInput</function>, then check
+<function>PQnotifies</function>.
You can use <function>select()</function> to wait for data to
arrive from the server, thereby using no <acronym>CPU</acronym> power unless there is something
-to do. (See <function>PQsocket()</function> to obtain the file descriptor
+to do. (See <function>PQsocket</function> to obtain the file descriptor
number to use with <function>select()</function>.)
Note that this will work OK whether you submit commands with
<function>PQsendQuery</function>/<function>PQgetResult</function> or simply
use <function>PQexec</function>. You should, however, remember to
-check <function>PQnotifies()</function> after each
+check <function>PQnotifies</function> after each
<function>PQgetResult</function> or <function>PQexec</function>, to see
if any notifications came in during the processing of the command.
</para>
@@ -2813,7 +2808,7 @@ int PQputCopyData(PGconn *conn,
</para>
<para>
-Transmits the COPY data in the specified <parameter>buffer</>, of length
+Transmits the <command>COPY</command> data in the specified <parameter>buffer</>, of length
<parameter>nbytes</>, to the server. The result is 1 if the data was sent,
zero if it was not sent because the attempt would block (this case is only
possible if the connection is in nonblocking mode), or -1 if an error occurred.
@@ -2896,7 +2891,7 @@ int PQgetCopyData(PGconn *conn,
</para>
<para>
-Attempts to obtain another row of data from the server during a COPY.
+Attempts to obtain another row of data from the server during a <command>COPY</command>.
Data is always returned one data row at a time; if only a partial row
is available, it is not returned. Successful return of a data row
involves allocating a chunk of memory to hold the data. The
@@ -2910,17 +2905,17 @@ buffer is returned. A non-<symbol>NULL</symbol> result buffer must be freed usi
When a row is successfully returned, the return value is the number of
data bytes in the row (this will always be greater than zero). The
returned string is always null-terminated, though this is probably only
-useful for textual COPY. A result of zero indicates that the COPY is
+useful for textual <command>COPY</command>. A result of zero indicates that the <command>COPY</command> is
still in progress, but no row is yet available (this is only possible
when <parameter>async</> is true). A
-result of -1 indicates that the COPY is done.
+result of -1 indicates that the <command>COPY</command> is done.
A result of -2 indicates that an error occurred (consult
<function>PQerrorMessage</> for the reason).
</para>
<para>
When <parameter>async</> is true (not zero), <function>PQgetCopyData</>
-will not block waiting for input; it will return zero if the COPY is still
+will not block waiting for input; it will return zero if the <command>COPY</command> is still
in progress but no complete row is available. (In this case wait for
read-ready before trying again; it does not matter whether you call
<function>PQconsumeInput</>.) When <parameter>async</> is
@@ -2992,7 +2987,7 @@ for a terminator line).
<term><function>PQgetlineAsync</function><indexterm><primary>PQgetlineAsync</></></term>
<listitem>
<para>
- Reads a row of COPY data
+ Reads a row of <command>COPY</command> data
(transmitted by the server) into a buffer
without blocking.
<synopsis>
@@ -3031,7 +3026,7 @@ a whole row will be returned at one time. But if the buffer offered by
the caller is too small to hold a row sent by the server, then a partial
data row will be returned. With textual data this can be detected by testing
whether the last returned byte is <literal>\n</literal> or not. (In a binary
-COPY, actual parsing of the COPY data format will be needed to make the
+<command>COPY</>, actual parsing of the <command>COPY</> data format will be needed to make the
equivalent determination.)
The returned string is not null-terminated. (If you want to add a
terminating null, be sure to pass a <parameter>bufsize</parameter> one smaller
@@ -3065,7 +3060,7 @@ call; it is okay to send a partial line or multiple lines per call.
Before <productname>PostgreSQL</productname> protocol 3.0, it was necessary
for the application to explicitly send the two characters
<literal>\.</literal> as a final line to indicate to the server that it had
-finished sending COPY data. While this still works, it is deprecated and the
+finished sending <command>COPY</> data. While this still works, it is deprecated and the
special meaning of <literal>\.</literal> can be expected to be removed in a
future release. It is sufficient to call <function>PQendcopy</function> after
having sent the actual data.
@@ -3162,17 +3157,19 @@ Determines the verbosity of messages returned by
<function>PQerrorMessage</> and <function>PQresultErrorMessage</>.
<synopsis>
typedef enum {
- PQERRORS_TERSE, PQERRORS_DEFAULT, PQERRORS_VERBOSE
+ PQERRORS_TERSE,
+ PQERRORS_DEFAULT,
+ PQERRORS_VERBOSE
} PGVerbosity;
PGVerbosity PQsetErrorVerbosity(PGconn *conn, PGVerbosity verbosity);
</synopsis>
<function>PQsetErrorVerbosity</> sets the verbosity mode, returning the
connection's previous setting.
-In TERSE mode, returned messages include severity, primary text, and position
-only; this will normally fit on a single line. The DEFAULT mode produces
+In <firstterm>terse</> mode, returned messages include severity, primary text, and position
+only; this will normally fit on a single line. The default mode produces
messages that include the above plus any detail, hint, or context fields
-(these may span multiple lines). The VERBOSE mode includes all available
+(these may span multiple lines). The <firstterm>VERBOSE</> mode includes all available
fields. Changing the verbosity does not affect the messages available from
already-existing <structname>PGresult</> objects, only subsequently-created
ones.
@@ -3568,7 +3565,7 @@ If the permissions are less strict than this, the file will be ignored.
</sect1>
<sect1 id="libpq-threading">
-<title>Threading Behavior</title>
+<title>Behavior in Threaded Programs</title>
<indexterm zone="libpq-threading">
<primary>threads</primary>
@@ -3576,11 +3573,14 @@ If the permissions are less strict than this, the file will be ignored.
</indexterm>
<para>
-<application>libpq</application> is thread-safe if the library is
-compiled using <filename>configure</filename>'s
-<literal>--enable-thread-safety</> command-line option.
-(In addition, you might need to use other threading command-line
-options to compile your client code.)
+<application>libpq</application> is reentrant and thread-safe if the
+<filename>configure</filename> command-line option
+<literal>--enable-thread-safety</> has been used when the PostgreSQL
+distribution was built.
+In addition, you might need to use additional compiler command-line
+options when you compile your application code. Refer to your system's
+documentation for information about how to build thread-enabled
+applications.
</para>
<para>
diff --git a/doc/src/sgml/lobj.sgml b/doc/src/sgml/lobj.sgml
index 4cdac668f0d..ce91bc3728e 100644
--- a/doc/src/sgml/lobj.sgml
+++ b/doc/src/sgml/lobj.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/lobj.sgml,v 1.31 2003/11/01 01:56:29 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/lobj.sgml,v 1.32 2003/11/12 22:47:47 petere Exp $
-->
<chapter id="largeObjects">
@@ -299,7 +299,7 @@ int lo_unlink(PGconn *conn, Oid lobjId);
</sect1>
<sect1 id="lo-funcs">
-<title>Server-side Functions</title>
+<title>Server-Side Functions</title>
<para>
There are two built-in server-side functions,
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 3ea94614520..8104c081500 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/plpgsql.sgml,v 1.28 2003/11/01 01:56:29 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/plpgsql.sgml,v 1.29 2003/11/12 22:47:47 petere Exp $
-->
<chapter id="plpgsql">
@@ -114,25 +114,25 @@ END;
<para>
Because <application>PL/pgSQL</application> saves execution plans
- in this way, SQL commands that appear directly in a
- <application>PL/pgSQL</application> function must refer to the
- same tables and columns on every execution; that is, you cannot use
- a parameter as the name of a table or column in an SQL command. To get
- around this restriction, you can construct dynamic commands using
- the <application>PL/pgSQL</application> <command>EXECUTE</command>
- statement --- at the price of constructing a new execution plan on
- every execution.
+ in this way, SQL commands that appear directly in a
+ <application>PL/pgSQL</application> function must refer to the
+ same tables and columns on every execution; that is, you cannot use
+ a parameter as the name of a table or column in an SQL command. To get
+ around this restriction, you can construct dynamic commands using
+ the <application>PL/pgSQL</application> <command>EXECUTE</command>
+ statement --- at the price of constructing a new execution plan on
+ every execution.
</para>
<note>
- <para>
- The <application>PL/pgSQL</application>
- <command>EXECUTE</command> statement is not related to the
- <command>EXECUTE</command> statement supported by the
- <productname>PostgreSQL</productname> server. The server's
- <command>EXECUTE</command> statement cannot be used within
- <application>PL/pgSQL</> functions (and is not needed).
- </para>
+ <para>
+ The <application>PL/pgSQL</application>
+ <command>EXECUTE</command> statement is not related to the
+ <command>EXECUTE</command> statement supported by the
+ <productname>PostgreSQL</productname> server. The server's
+ <command>EXECUTE</command> statement cannot be used within
+ <application>PL/pgSQL</> functions (and is not needed).
+ </para>
</note>
<para>
@@ -195,7 +195,7 @@ END;
<para>
<application>PL/pgSQL</> functions may also be declared to accept
- and return the <quote>polymorphic</> types
+ and return the polymorphic types
<type>anyelement</type> and <type>anyarray</type>. The actual
data types handled by a polymorphic function can vary from call to
call, as discussed in <xref linkend="extend-types-polymorphic">.
@@ -230,7 +230,7 @@ END;
the function definition. For example:
<programlisting>
CREATE OR REPLACE FUNCTION testfunc(integer) RETURNS integer AS '
- ....
+ ....
end;
' LANGUAGE plpgsql;
</programlisting>
@@ -255,7 +255,7 @@ end;
</para>
<sect2 id="plpgsql-quote-tips">
- <title>Handling of Quote Marks</title>
+ <title>Handling of Quotation Marks</title>
<para>
Since the code of a <application>PL/pgSQL</> function is specified in
@@ -265,13 +265,13 @@ end;
rather complicated code at times, especially if you are writing a
function that generates other functions, as in the example in <xref
linkend="plpgsql-statements-executing-dyn">. This chart may be useful
- as a summary of the needed numbers of quote marks in
+ as a summary of the needed numbers of quotation marks in
various situations.
</para>
<variablelist>
<varlistentry>
- <term>1 quote mark</term>
+ <term>1 quotation mark</term>
<listitem>
<para>
To begin and end the function body, for example:
@@ -279,14 +279,14 @@ end;
CREATE FUNCTION foo() RETURNS integer AS '...'
LANGUAGE plpgsql;
</programlisting>
- Anywhere within the function body, quote marks <emphasis>must</>
+ Anywhere within the function body, quotation marks <emphasis>must</>
appear in pairs.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term>2 quote marks</term>
+ <term>2 quotation marks</term>
<listitem>
<para>
For string literals inside the function body, for example:
@@ -303,10 +303,10 @@ SELECT * FROM users WHERE f_name='foobar';
</varlistentry>
<varlistentry>
- <term>4 quote marks</term>
+ <term>4 quotation marks</term>
<listitem>
<para>
- When you need a single quote in a string constant inside the function
+ When you need a single quotation mark in a string constant inside the function
body, for example:
<programlisting>
a_output := a_output || '' AND name LIKE ''''foobar'''' AND xyz''
@@ -318,10 +318,10 @@ a_output := a_output || '' AND name LIKE ''''foobar'''' AND xyz''
</varlistentry>
<varlistentry>
- <term>6 quote marks</term>
+ <term>6 quotation marks</term>
<listitem>
<para>
- When a single quote in a string inside the function body is
+ When a single quotation mark in a string inside the function body is
adjacent to the end of that string constant, for example:
<programlisting>
a_output := a_output || '' AND name LIKE ''''foobar''''''
@@ -333,11 +333,11 @@ a_output := a_output || '' AND name LIKE ''''foobar''''''
</varlistentry>
<varlistentry>
- <term>10 quote marks</term>
+ <term>10 quotation marks</term>
<listitem>
<para>
- When you want two single quotes in a string constant (which
- accounts for 8 quotes) and this is adjacent to the end of that
+ When you want two single quotation marks in a string constant (which
+ accounts for 8 quotation marks) and this is adjacent to the end of that
string constant (2 more). You will probably only need that if
you are writing a function that generates other functions. For
example:
@@ -358,7 +358,7 @@ if v_... like ''...'' then return ''...''; end if;
</variablelist>
<para>
- A different approach is to escape quote marks in the function body
+ A different approach is to escape quotation marks in the function body
with a backslash rather than by doubling them. With this method
you'll find yourself writing things like <literal>\'\'</> instead
of <literal>''''</>. Some find this easier to keep track of, some
@@ -568,7 +568,7 @@ END;
linkend="extend-types-polymorphic">).
This allows the function to access its actual return type
as shown in <xref linkend="plpgsql-declaration-type">.
- <literal>$0</literal> is initialized to NULL and can be modified by
+ <literal>$0</literal> is initialized to null and can be modified by
the function, so it can be used to hold the return value if desired,
though that is not required. <literal>$0</literal> can also be
given an alias. For example, this function works on any data type
@@ -689,14 +689,12 @@ END;
</para>
</sect2>
- <sect2 id="plpgsql-declaration-records">
- <title>Record Types</title>
+ <sect2 id="plpgsql-declaration-records">
+ <title>Record Types</title>
- <para>
<synopsis>
<replaceable>name</replaceable> RECORD;
</synopsis>
- </para>
<para>
Record variables are similar to row-type variables, but they have no
@@ -721,36 +719,38 @@ END;
</para>
</sect2>
- <sect2 id="plpgsql-declaration-renaming-vars">
- <title><literal>RENAME</></title>
+ <sect2 id="plpgsql-declaration-renaming-vars">
+ <title><literal>RENAME</></title>
- <para>
<synopsis>
RENAME <replaceable>oldname</replaceable> TO <replaceable>newname</replaceable>;
</synopsis>
- Using the RENAME declaration you can change the name of a variable,
- record or row. This is primarily useful if NEW or OLD should be
- referenced by another name inside a trigger procedure. See also ALIAS.
- </para>
+ <para>
+ Using the <literal>RENAME</literal> declaration you can change the
+ name of a variable, record or row. This is primarily useful if
+ <literal>NEW</literal> or <literal>OLD</literal> should be
+ referenced by another name inside a trigger procedure. See also
+ <literal>ALIAS</literal>.
+ </para>
- <para>
- Examples:
+ <para>
+ Examples:
<programlisting>
RENAME id TO user_id;
RENAME this_var TO that_var;
</programlisting>
- </para>
+ </para>
<note>
- <para>
- RENAME appears to be broken as of <productname>PostgreSQL</>
- 7.3. Fixing this is of low priority, since ALIAS covers most of
- the practical uses of RENAME.
- </para>
+ <para>
+ <literal>RENAME</literal> appears to be broken as of
+ <productname>PostgreSQL</> 7.3. Fixing this is of low priority,
+ since <literal>ALIAS</literal> covers most of the practical uses
+ of <literal>RENAME</literal>.
+ </para>
</note>
-
- </sect2>
+ </sect2>
</sect1>
<sect1 id="plpgsql-expressions">
@@ -1159,9 +1159,9 @@ END;
<title>Obtaining the Result Status</title>
<para>
- There are several ways to determine the effect of a command. The
- first method is to use the <command>GET DIAGNOSTICS</command>
- command, which has the form:
+ There are several ways to determine the effect of a command. The
+ first method is to use the <command>GET DIAGNOSTICS</command>
+ command, which has the form:
<synopsis>
GET DIAGNOSTICS <replaceable>variable</replaceable> = <replaceable>item</replaceable> <optional> , ... </optional> ;
@@ -1192,49 +1192,49 @@ GET DIAGNOSTICS integer_var = ROW_COUNT;
type <type>boolean</type>. <literal>FOUND</literal> starts out
false within each <application>PL/pgSQL</application> function call.
It is set by each of the following types of statements:
- <itemizedlist>
- <listitem>
- <para>
- A <command>SELECT INTO</command> statement sets
- <literal>FOUND</literal> true if it returns a row, false if no
- row is returned.
- </para>
- </listitem>
- <listitem>
- <para>
- A <command>PERFORM</> statement sets <literal>FOUND</literal>
- true if it produces (and discards) a row, false if no row is
- produced.
- </para>
- </listitem>
- <listitem>
- <para>
- <command>UPDATE</>, <command>INSERT</>, and <command>DELETE</>
- statements set <literal>FOUND</literal> true if at least one
- row is affected, false if no row is affected.
- </para>
- </listitem>
- <listitem>
- <para>
- A <command>FETCH</> statement sets <literal>FOUND</literal>
- true if it returns a row, false if no row is returned.
- </para>
- </listitem>
- <listitem>
- <para>
- A <command>FOR</> statement sets <literal>FOUND</literal> true
- if it iterates one or more times, else false. This applies to
- all three variants of the <command>FOR</> statement (integer
- <command>FOR</> loops, record-set <command>FOR</> loops, and
- dynamic record-set <command>FOR</>
- loops). <literal>FOUND</literal> is only set when the
- <command>FOR</> loop exits: inside the execution of the loop,
- <literal>FOUND</literal> is not modified by the
- <command>FOR</> statement, although it may be changed by the
- execution of other statements within the loop body.
- </para>
- </listitem>
- </itemizedlist>
+ <itemizedlist>
+ <listitem>
+ <para>
+ A <command>SELECT INTO</command> statement sets
+ <literal>FOUND</literal> true if it returns a row, false if no
+ row is returned.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A <command>PERFORM</> statement sets <literal>FOUND</literal>
+ true if it produces (and discards) a row, false if no row is
+ produced.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <command>UPDATE</>, <command>INSERT</>, and <command>DELETE</>
+ statements set <literal>FOUND</literal> true if at least one
+ row is affected, false if no row is affected.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A <command>FETCH</> statement sets <literal>FOUND</literal>
+ true if it returns a row, false if no row is returned.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A <command>FOR</> statement sets <literal>FOUND</literal> true
+ if it iterates one or more times, else false. This applies to
+ all three variants of the <command>FOR</> statement (integer
+ <command>FOR</> loops, record-set <command>FOR</> loops, and
+ dynamic record-set <command>FOR</>
+ loops). <literal>FOUND</literal> is only set when the
+ <command>FOR</> loop exits: inside the execution of the loop,
+ <literal>FOUND</literal> is not modified by the
+ <command>FOR</> statement, although it may be changed by the
+ execution of other statements within the loop body.
+ </para>
+ </listitem>
+ </itemizedlist>
<literal>FOUND</literal> is a local variable; any changes
to it affect only the current <application>PL/pgSQL</application>
function.
@@ -1583,7 +1583,7 @@ EXIT <optional> <replaceable>label</replaceable> </optional> <optional> WHEN <re
<para>
If <literal>WHEN</> is present, loop exit occurs only if the specified condition
- is true, otherwise control passes to the statement after <literal>EXIT</>.
+ is true, otherwise control passes to the statement after <literal>EXIT</>.
</para>
<para>
@@ -1624,8 +1624,8 @@ END LOOP;
<para>
The <literal>WHILE</> statement repeats a
sequence of statements so long as the condition expression
- evaluates to true. The condition is checked just before
- each entry to the loop body.
+ evaluates to true. The condition is checked just before
+ each entry to the loop body.
</para>
<para>
@@ -1654,12 +1654,12 @@ END LOOP;
<para>
This form of <literal>FOR</> creates a loop that iterates over a range of integer
- values. The variable
+ values. The variable
<replaceable>name</replaceable> is automatically defined as type
<type>integer</> and exists only inside the loop. The two expressions giving
the lower and upper bound of the range are evaluated once when entering
the loop. The iteration step is normally 1, but is -1 when <literal>REVERSE</> is
- specified.
+ specified.
</para>
<para>
@@ -1678,7 +1678,7 @@ END LOOP;
<para>
If the lower bound is greater than the upper bound (or less than,
- in the <literal>REVERSE</> case), the loop body is not
+ in the <literal>REVERSE</> case), the loop body is not
executed at all. No error is raised.
</para>
</sect3>
@@ -1841,13 +1841,13 @@ OPEN <replaceable>unbound-cursor</replaceable> FOR SELECT ...;
<para>
The cursor variable is opened and given the specified query to
- execute. The cursor cannot be open already, and it must have been
- declared as an unbound cursor (that is, as a simple
- <type>refcursor</> variable). The <command>SELECT</command> query
- is treated in the same way as other <command>SELECT</command>
- statements in <application>PL/pgSQL</>: <application>PL/pgSQL</>
- variable names are substituted, and the query plan is cached for
- possible reuse.
+ execute. The cursor cannot be open already, and it must have been
+ declared as an unbound cursor (that is, as a simple
+ <type>refcursor</> variable). The <command>SELECT</command> query
+ is treated in the same way as other <command>SELECT</command>
+ statements in <application>PL/pgSQL</>: <application>PL/pgSQL</>
+ variable names are substituted, and the query plan is cached for
+ possible reuse.
</para>
<para>
@@ -1865,14 +1865,14 @@ OPEN curs1 FOR SELECT * FROM foo WHERE key = mykey;
OPEN <replaceable>unbound-cursor</replaceable> FOR EXECUTE <replaceable class="command">query-string</replaceable>;
</synopsis>
- <para>
- The cursor variable is opened and given the specified query to
- execute. The cursor cannot be open already, and it must have been
- declared as an unbound cursor (that is, as a simple
- <type>refcursor</> variable). The query is specified as a string
- expression in the same way as in the <command>EXECUTE</command>
- command. As usual, this gives flexibility so the query can vary
- from one run to the next.
+ <para>
+ The cursor variable is opened and given the specified query to
+ execute. The cursor cannot be open already, and it must have been
+ declared as an unbound cursor (that is, as a simple
+ <type>refcursor</> variable). The query is specified as a string
+ expression in the same way as in the <command>EXECUTE</command>
+ command. As usual, this gives flexibility so the query can vary
+ from one run to the next.
</para>
<para>
@@ -1890,14 +1890,14 @@ OPEN curs1 FOR EXECUTE ''SELECT * FROM '' || quote_ident($1);
OPEN <replaceable>bound-cursor</replaceable> <optional> ( <replaceable>argument_values</replaceable> ) </optional>;
</synopsis>
- <para>
- This form of <command>OPEN</command> is used to open a cursor
- variable whose query was bound to it when it was declared. The
- cursor cannot be open already. A list of actual argument value
- expressions must appear if and only if the cursor was declared to
- take arguments. These values will be substituted in the query.
- The query plan for a bound cursor is always considered cacheable;
- there is no equivalent of <command>EXECUTE</command> in this case.
+ <para>
+ This form of <command>OPEN</command> is used to open a cursor
+ variable whose query was bound to it when it was declared. The
+ cursor cannot be open already. A list of actual argument value
+ expressions must appear if and only if the cursor was declared to
+ take arguments. These values will be substituted in the query.
+ The query plan for a bound cursor is always considered cacheable;
+ there is no equivalent of <command>EXECUTE</command> in this case.
</para>
<para>
@@ -1941,13 +1941,13 @@ OPEN curs3(42);
FETCH <replaceable>cursor</replaceable> INTO <replaceable>target</replaceable>;
</synopsis>
- <para>
- <command>FETCH</command> retrieves the next row from the
- cursor into a target, which may be a row variable, a record
- variable, or a comma-separated list of simple variables, just like
- <command>SELECT INTO</command>. As with <command>SELECT
- INTO</command>, the special variable <literal>FOUND</literal> may
- be checked to see whether a row was obtained or not.
+ <para>
+ <command>FETCH</command> retrieves the next row from the
+ cursor into a target, which may be a row variable, a record
+ variable, or a comma-separated list of simple variables, just like
+ <command>SELECT INTO</command>. As with <command>SELECT
+ INTO</command>, the special variable <literal>FOUND</literal> may
+ be checked to see whether a row was obtained or not.
</para>
<para>
@@ -1968,8 +1968,8 @@ CLOSE <replaceable>cursor</replaceable>;
<para>
<command>CLOSE</command> closes the portal underlying an open
- cursor. This can be used to release resources earlier than end of
- transaction, or to free up the cursor variable to be opened again.
+ cursor. This can be used to release resources earlier than end of
+ transaction, or to free up the cursor variable to be opened again.
</para>
<para>
@@ -1986,40 +1986,40 @@ CLOSE curs1;
<para>
<application>PL/pgSQL</> functions can return cursors to the
caller. This is useful to return multiple rows or columns,
- especially with very large result sets. To do this, the function
- opens the cursor and returns the cursor name to the caller (or simply
- opens the cursor using a portal name specified by or otherwise known
- to the caller). The caller can then fetch rows from the cursor. The
- cursor can be closed by the caller, or it will be closed automatically
+ especially with very large result sets. To do this, the function
+ opens the cursor and returns the cursor name to the caller (or simply
+ opens the cursor using a portal name specified by or otherwise known
+ to the caller). The caller can then fetch rows from the cursor. The
+ cursor can be closed by the caller, or it will be closed automatically
when the transaction closes.
</para>
<para>
The portal name used for a cursor can be specified by the
- programmer or automatically generated. To specify a portal name,
- simply assign a string to the <type>refcursor</> variable before
- opening it. The string value of the <type>refcursor</> variable
- will be used by <command>OPEN</> as the name of the underlying portal.
- However, if the <type>refcursor</> variable is NULL,
- <command>OPEN</> automatically generates a name that does not
- conflict with any existing portal, and assigns it to the
- <type>refcursor</> variable.
+ programmer or automatically generated. To specify a portal name,
+ simply assign a string to the <type>refcursor</> variable before
+ opening it. The string value of the <type>refcursor</> variable
+ will be used by <command>OPEN</> as the name of the underlying portal.
+ However, if the <type>refcursor</> variable is null,
+ <command>OPEN</> automatically generates a name that does not
+ conflict with any existing portal, and assigns it to the
+ <type>refcursor</> variable.
</para>
<note>
<para>
- A bound cursor variable is initialized to the string value
- representing its name, so that the portal name is the same as
- the cursor variable name, unless the programmer overrides it
- by assignment before opening the cursor. But an unbound cursor
- variable defaults to an initial value of NULL, so it will receive
- an automatically-generated unique name, unless overridden.
+ A bound cursor variable is initialized to the string value
+ representing its name, so that the portal name is the same as
+ the cursor variable name, unless the programmer overrides it
+ by assignment before opening the cursor. But an unbound cursor
+ variable defaults to the null value initially , so it will receive
+ an automatically-generated unique name, unless overridden.
</para>
</note>
<para>
The following example shows one way a cursor name can be supplied by
- the caller:
+ the caller:
<programlisting>
CREATE TABLE test (col text);
@@ -2104,7 +2104,7 @@ RAISE <replaceable class="parameter">level</replaceable> '<replaceable class="pa
<!--
This example should work, but does not:
- RAISE NOTICE ''Id number '' || key || '' not found!'';
+ RAISE NOTICE ''Id number '' || key || '' not found!'';
Put it back when we allow non-string-literal formats.
-->
@@ -2158,14 +2158,14 @@ RAISE EXCEPTION ''Inexistent ID --> %'', user_id;
</indexterm>
<para>
- <application>PL/pgSQL</application> can be used to define trigger
- procedures. A trigger procedure is created with the
- <command>CREATE FUNCTION</> command, declaring it as a function with
- no arguments and a return type of <type>trigger</type>. Note that
- the function must be declared with no arguments even if it expects
- to receive arguments specified in <command>CREATE TRIGGER</> ---
- trigger arguments are passed via <varname>TG_ARGV</>, as described
- below.
+ <application>PL/pgSQL</application> can be used to define trigger
+ procedures. A trigger procedure is created with the
+ <command>CREATE FUNCTION</> command, declaring it as a function with
+ no arguments and a return type of <type>trigger</type>. Note that
+ the function must be declared with no arguments even if it expects
+ to receive arguments specified in <command>CREATE TRIGGER</> ---
+ trigger arguments are passed via <varname>TG_ARGV</>, as described
+ below.
</para>
<para>
diff --git a/doc/src/sgml/plpython.sgml b/doc/src/sgml/plpython.sgml
index 802ea6bfc43..a4af101c288 100644
--- a/doc/src/sgml/plpython.sgml
+++ b/doc/src/sgml/plpython.sgml
@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/plpython.sgml,v 1.20 2003/09/12 22:17:23 tgl Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/plpython.sgml,v 1.21 2003/11/12 22:47:47 petere Exp $ -->
<chapter id="plpython">
<title>PL/Python - Python Procedural Language</title>
@@ -17,18 +17,6 @@
<literal>createlang plpythonu <replaceable>dbname</></literal>.
</para>
- <note>
- <para>
- As of <productname>PostgreSQL</productname> 7.4,
- PL/Python is only available as an <quote>untrusted</> language
- (meaning it does not offer any way of restricting what users
- can do in it). It has therefore been renamed to <literal>plpythonu</>.
- The trusted variant <literal>plpython</> may become available again in
- future, if a new secure execution mechanism is developed by the Python
- community.
- </para>
- </note>
-
<tip>
<para>
If a language is installed into <literal>template1</>, all subsequently
@@ -36,6 +24,15 @@
</para>
</tip>
+ <para>
+ As of <productname>PostgreSQL</productname> 7.4, PL/Python is only
+ available as an <quote>untrusted</> language (meaning it does not
+ offer any way of restricting what users can do in it). It has
+ therefore been renamed to <literal>plpythonu</>. The trusted
+ variant <literal>plpython</> may become available again in future,
+ if a new secure execution mechanism is developed in Python.
+ </para>
+
<note>
<para>
Users of source packages must specially enable the build of
diff --git a/doc/src/sgml/pltcl.sgml b/doc/src/sgml/pltcl.sgml
index c8b55ac4e75..b3542d2caf4 100644
--- a/doc/src/sgml/pltcl.sgml
+++ b/doc/src/sgml/pltcl.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/pltcl.sgml,v 2.26 2003/09/08 23:02:28 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/pltcl.sgml,v 2.27 2003/11/12 22:47:47 petere Exp $
-->
<chapter id="pltcl">
@@ -136,7 +136,7 @@ CREATE FUNCTION tcl_max(integer, integer) RETURNS integer AS '
<para>
As shown above,
- to return a NULL value from a PL/Tcl function, execute
+ to return a null value from a PL/Tcl function, execute
<literal>return_null</literal>. This can be done whether the
function is strict or not.
</para>
diff --git a/doc/src/sgml/ref/create_function.sgml b/doc/src/sgml/ref/create_function.sgml
index d094e3970ef..e4d83e6986a 100644
--- a/doc/src/sgml/ref/create_function.sgml
+++ b/doc/src/sgml/ref/create_function.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.53 2003/10/26 04:34:05 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_function.sgml,v 1.54 2003/11/12 22:47:47 petere Exp $
-->
<refentry id="SQL-CREATEFUNCTION">
@@ -95,7 +95,7 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
<para>
The data type(s) of the function's arguments (optionally
schema-qualified), if any. The argument types may be base, complex, or
- domain types, or copy the type of an existing column.
+ domains, or copy the type of an existing column.
</para>
<para>
The type of a column is referenced by writing
@@ -120,8 +120,8 @@ CREATE [ OR REPLACE ] FUNCTION <replaceable class="parameter">name</replaceable>
<listitem>
<para>
The return data type (optionally schema-qualified). The return type
- may be specified as a base, complex, or domain type,
- or may copy the type of an existing column. See the description
+ may be a base type, complex type, or a domain,
+ or may be specified to copy the type of an existing column. See the description
under <literal>argtype</literal> above on how to reference the type
of an existing column.
</para>
diff --git a/doc/src/sgml/release.sgml b/doc/src/sgml/release.sgml
index fca6a0fbe46..6a1c90a7ba6 100644
--- a/doc/src/sgml/release.sgml
+++ b/doc/src/sgml/release.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/release.sgml,v 1.237 2003/11/10 22:27:00 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/release.sgml,v 1.238 2003/11/12 22:47:47 petere Exp $
-->
<appendix id="release">
@@ -878,12 +878,12 @@ zero-row record variable (Tom)</para></listitem>
<itemizedlist>
<listitem><para>Allow PQcmdTuples() to return row counts for MOVE and FETCH (Neil)</para></listitem>
-<listitem><para>Add PQfreemem() for freeing memory on Win32, suggest for NOTIFY (Bruce)</para>
+<listitem><para>Add PQfreemem() for freeing memory on Windows, suggest for NOTIFY (Bruce)</para>
<para>
- Win32 requires that memory allocated in a library be freed by a
+ Windows requires that memory allocated in a library be freed by a
function in the same library, hence free() doesn't work for freeing
memory allocated by libpq. PQfreemem() is the proper way to free
- libpq memory, especially on Win32, and is recommended for other
+ libpq memory, especially on Windows, and is recommended for other
platforms as well.
</para>
</listitem>
@@ -961,8 +961,8 @@ zero-row record variable (Tom)</para></listitem>
<listitem><para>Convert administration scripts to C (Peter)</para></listitem>
<listitem><para>Bison >= 1.85 is now required to build the PostgreSQL grammar, if building from CVS</para></listitem>
<listitem><para>Merge documentation into one book (Peter)</para></listitem>
-<listitem><para>Add Win32 compatibility functions (Bruce)</para></listitem>
-<listitem><para>Allow client interfaces to compile under MinGW/Win32 (Bruce)</para></listitem>
+<listitem><para>Add Windows compatibility functions (Bruce)</para></listitem>
+<listitem><para>Allow client interfaces to compile under MinGW (Bruce)</para></listitem>
<listitem><para>New ereport() function for error reporting (Tom)</para></listitem>
<listitem><para>Support Intel Linux compiler (Peter)</para></listitem>
<listitem><para>Improve Linux startup scripts (Slawomir Sudnik, Darko Prenosil)</para></listitem>
@@ -1794,7 +1794,7 @@ of locale?</para></listitem>
<listitem><para>Fix for sending large queries over non-blocking connections (Bernhard Herzog)</para></listitem>
<listitem><para>Fix for libpq using timers on Win9X (David Ford)</para></listitem>
<listitem><para>Allow libpq notify to handle servers with different-length identifiers (Tom)</para></listitem>
-<listitem><para>Add libpq PQescapeString() and PQescapeBytea() to Win32 (Bruce)</para></listitem>
+<listitem><para>Add libpq PQescapeString() and PQescapeBytea() to Windows (Bruce)</para></listitem>
<listitem><para>Fix for SSL with non-blocking connections (Jack Bates)</para></listitem>
<listitem><para>Add libpq connection timeout parameter (Denis A Ustimenko)</para></listitem>
</itemizedlist>
@@ -1846,7 +1846,7 @@ of locale?</para></listitem>
<listitem><para>Always enable multibyte in compile, remove --enable-multibyte option (Tatsuo)</para></listitem>
<listitem><para>Always enable locale in compile, remove --enable-locale option (Peter)</para></listitem>
<listitem><para>Fix for Win9x DLL creation (Magnus Naeslund)</para></listitem>
-<listitem><para>Fix for link() usage by WAL code on Win32, BeOS (Jason Tishler)</para></listitem>
+<listitem><para>Fix for link() usage by WAL code on Windows, BeOS (Jason Tishler)</para></listitem>
<listitem><para>Add sys/types.h to c.h, remove from main files (Peter, Bruce)</para></listitem>
<listitem><para>Fix AIX hang on SMP machines (Tomoyuki Niijima)</para></listitem>
<listitem><para>AIX SMP hang fix (Tomoyuki Niijima)</para></listitem>
@@ -1871,7 +1871,7 @@ of locale?</para></listitem>
<listitem><para>New Polish FAQ (Marcin Mazurek)</para></listitem>
<listitem><para>Add Posix semaphore support (Tom)</para></listitem>
<listitem><para>Document need for reindex (Bruce)</para></listitem>
-<listitem><para>Rename some internal identifiers to simplify Win32 compile (Jan, Katherine Ward)</para></listitem>
+<listitem><para>Rename some internal identifiers to simplify Windows compile (Jan, Katherine Ward)</para></listitem>
<listitem><para>Add documentation on computing disk space (Bruce)</para></listitem>
<listitem><para>Remove KSQO from GUC (Bruce)</para></listitem>
<listitem><para>Fix memory leak in rtree (Kenneth Been)</para></listitem>
@@ -2588,8 +2588,8 @@ of locale?</para></listitem>
<itemizedlist>
<listitem><para>Configure, dynamic loader, and shared library fixes (Peter E)</para></listitem>
<listitem><para>Fixes in QNX 4 port (Bernd Tegge)</para></listitem>
-<listitem><para>Fixes in Cygwin and Win32 ports (Jason Tishler, Gerhard Haring, Dmitry Yurtaev, Darko Prenosil, Mikhail Terekhov)</para></listitem>
-<listitem><para>Fix for Win32 socket communication failures (Magnus, Mikhail Terekhov)</para></listitem>
+<listitem><para>Fixes in Cygwin and Windows ports (Jason Tishler, Gerhard Haring, Dmitry Yurtaev, Darko Prenosil, Mikhail Terekhov)</para></listitem>
+<listitem><para>Fix for Windows socket communication failures (Magnus, Mikhail Terekhov)</para></listitem>
<listitem><para>Hurd compile fix (Oliver Elphick)</para></listitem>
<listitem><para>BeOS fixes (Cyril Velter)</para></listitem>
<listitem><para>Remove configure --enable-unicode-conversion, now enabled by multibyte (Tatsuo)</para></listitem>
@@ -3675,7 +3675,7 @@ Clean up #include in /include directory (Bruce)
Add scripts for checking includes (Bruce)
Remove un-needed #include's from *.c files (Bruce)
Change #include's to use <> and "" as appropriate (Bruce)
-Enable WIN32 compilation of libpq
+Enable Windows compilation of libpq
Alpha spinlock fix from Uncle George <email>gatgul@voicenet.com</email>
Overhaul of optimizer data structures (Tom)
Fix to cygipc library (Yutaka Tanida)
@@ -3688,7 +3688,7 @@ New platform-specific regression handling (Tom)
Rename oid8 -> oidvector and int28 -> int2vector (Bruce)
Included all yacc and lex files into the distribution (Peter E.)
Remove lextest, no longer needed (Peter E)
-Fix for libpq and psql on Win32 (Magnus)
+Fix for libpq and psql on Windows (Magnus)
Internally change datetime and timespan into timestamp and interval (Thomas)
Fix for plpgsql on BSD/OS
Add SQL_ASCII test case to the regression test (Tatsuo)
@@ -3772,7 +3772,7 @@ Fixes for CASE in WHERE join clauses(Tom)
Fix BTScan abort(Tom)
Repair the check for redundant UNIQUE and PRIMARY KEY indexes(Thomas)
Improve it so that it checks for multicolumn constraints(Thomas)
-Fix for Win32 making problem with MB enabled(Hiroki Kataoka)
+Fix for Windows making problem with MB enabled(Hiroki Kataoka)
Allow BSD yacc and bison to compile pl code(Bruce)
Fix SET NAMES working
int8 fixes(Thomas)
@@ -4230,7 +4230,7 @@ Source Tree Changes
-------------------
Improve port matching(Tom)
Portability fixes for SunOS
-Add NT/Win32 backend port and enable dynamic loading(Magnus and Daniel Horak)
+Add Windows NT backend port and enable dynamic loading(Magnus and Daniel Horak)
New port to Cobalt Qube(Mips) running Linux(Tatsuo)
Port to NetBSD/m68k(Mr. Mutsuki Nakajima)
Port to NetBSD/sun3(Mr. Mutsuki Nakajima)
@@ -4338,7 +4338,7 @@ Timezone fixes(Tom)
HP-UX fixes(Tom)
Use implicit type coercion for matching DEFAULT values(Thomas)
Add routines to help with single-byte (internal) character type(Thomas)
-Compilation of libpq for Win32 fixes(Magnus)
+Compilation of libpq for Windows fixes(Magnus)
Upgrade to PyGreSQL 2.2(D'Arcy)
</programlisting>
</para>
@@ -4523,7 +4523,7 @@ New contrib/lo code for large object orphan removal(Peter)
New psql command "SET CLIENT_ENCODING TO 'encoding'" for multibytes
feature, see /doc/README.mb(Tatsuo)
/contrib/noupdate code to revoke update permission on a column
-libpq can now be compiled on win32(Magnus)
+libpq can now be compiled on Windows(Magnus)
Add PQsetdbLogin() in libpq
New 8-byte integer type, checked by configure for OS support(Thomas)
Better support for quoted table/column names(Thomas)
@@ -4586,7 +4586,7 @@ New setval() command to set sequence value(Massimo)
Auto-remove unix socket file on start-up if no postmaster running(Massimo)
Conditional trace package(Massimo)
New UNLISTEN command(Massimo)
-psql and libpq now compile under win32 using win32.mak(Magnus)
+psql and libpq now compile under Windows using win32.mak(Magnus)
Lo_read no longer stores trailing NULL(Bruce)
Identifiers are now truncated to 31 characters internally(Bruce)
Createuser options now availble on the command line
@@ -5551,7 +5551,7 @@ new OS-specific template files(Marc)
no more need to edit Makefile.global(Marc)
re-arrange include files(Marc)
nextstep patches (Gregor Hoffleit)
-removed WIN32-specific code(Bruce)
+removed Windows-specific code(Bruce)
removed postmaster -e option, now only postgres -e option (Bruce)
merge duplicate library code in front/backends(Martin)
now works with eBones, international Kerberos(Jun)
diff --git a/doc/src/sgml/typeconv.sgml b/doc/src/sgml/typeconv.sgml
index a0dd5cf0329..391176d682a 100644
--- a/doc/src/sgml/typeconv.sgml
+++ b/doc/src/sgml/typeconv.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/typeconv.sgml,v 1.37 2003/11/04 09:55:39 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/typeconv.sgml,v 1.38 2003/11/12 22:47:47 petere Exp $
-->
<chapter Id="typeconv">
@@ -289,7 +289,7 @@ candidate remains, use it; else continue to the next step.
<step performance="required">
<para>
Run through all candidates and keep those with the most exact matches
-on input types. (Domain types are considered the same as their base type
+on input types. (Domains are considered the same as their base type
for this purpose.) Keep all candidates if none have any exact matches.
If only one candidate remains, use it; else continue to the next step.
</para>
@@ -542,7 +542,7 @@ candidate remains, use it; else continue to the next step.
<step performance="required">
<para>
Run through all candidates and keep those with the most exact matches
-on input types. (Domain types are considered the same as their base type
+on input types. (Domains are considered the same as their base type
for this purpose.) Keep all candidates if none have any exact matches.
If only one candidate remains, use it; else continue to the next step.
</para>
diff --git a/doc/src/sgml/xaggr.sgml b/doc/src/sgml/xaggr.sgml
index 8f1bda7e79a..939faac3ae4 100644
--- a/doc/src/sgml/xaggr.sgml
+++ b/doc/src/sgml/xaggr.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/xaggr.sgml,v 1.22 2003/08/31 17:32:20 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/xaggr.sgml,v 1.23 2003/11/12 22:47:47 petere Exp $
-->
<sect1 id="xaggr">
@@ -140,16 +140,20 @@ CREATE AGGREGATE array_accum (
<programlisting>
SELECT attrelid::regclass, array_accum(attname)
-FROM pg_attribute WHERE attnum > 0
-AND attrelid = 'pg_user'::regclass GROUP BY attrelid;
+ FROM pg_attribute
+ WHERE attnum > 0 AND attrelid = 'pg_user'::regclass
+ GROUP BY attrelid;
+
attrelid | array_accum
----------+-----------------------------------------------------------------------------
pg_user | {usename,usesysid,usecreatedb,usesuper,usecatupd,passwd,valuntil,useconfig}
(1 row)
SELECT attrelid::regclass, array_accum(atttypid)
-FROM pg_attribute WHERE attnum > 0
-AND attrelid = 'pg_user'::regclass GROUP BY attrelid;
+ FROM pg_attribute
+ WHERE attnum > 0 AND attrelid = 'pg_user'::regclass
+ GROUP BY attrelid;
+
attrelid | array_accum
----------+------------------------------
pg_user | {19,23,16,16,16,25,702,1009}
diff --git a/doc/src/sgml/xfunc.sgml b/doc/src/sgml/xfunc.sgml
index 0c1a7610df2..42358431f78 100644
--- a/doc/src/sgml/xfunc.sgml
+++ b/doc/src/sgml/xfunc.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/xfunc.sgml,v 1.77 2003/11/01 01:56:29 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/xfunc.sgml,v 1.78 2003/11/12 22:47:47 petere Exp $
-->
<sect1 id="xfunc">
@@ -392,9 +392,9 @@ SELECT name(emp) AS youngster
result of the first function to it:
<screen>
-CREATE FUNCTION getname(emp) RETURNS text AS
-'SELECT $1.name;'
-LANGUAGE SQL;
+CREATE FUNCTION getname(emp) RETURNS text AS '
+ SELECT $1.name;
+' LANGUAGE SQL;
SELECT getname(new_emp());
getname
@@ -538,12 +538,12 @@ SELECT name, listchildren(name) FROM nodes;
<para>
<acronym>SQL</acronym> functions may be declared to accept and
- return the <quote>polymorphic</> types
- <type>anyelement</type> and <type>anyarray</type>.
- See <xref linkend="extend-types-polymorphic"> for a more detailed explanation
- of polymorphic functions. Here is a polymorphic function
- <function>make_array</function> that builds up an array from two
- arbitrary data type elements:
+ return the polymorphic types <type>anyelement</type> and
+ <type>anyarray</type>. See <xref
+ linkend="extend-types-polymorphic"> for a more detailed
+ explanation of polymorphic functions. Here is a polymorphic
+ function <function>make_array</function> that builds up an array
+ from two arbitrary data type elements:
<screen>
CREATE FUNCTION make_array(anyelement, anyelement) RETURNS anyarray AS '
SELECT ARRAY[$1, $2];
@@ -567,7 +567,7 @@ SELECT make_array(1, 2) AS intarray, make_array('a'::text, 'b') AS textarray;
Without the typecast, you will get errors like this:
<screen>
<computeroutput>
-ERROR: could not determine ANYARRAY/ANYELEMENT type because input is UNKNOWN
+ERROR: could not determine "anyarray"/"anyelement" type because input has type "unknown"
</computeroutput>
</screen>
</para>
@@ -576,7 +576,7 @@ ERROR: could not determine ANYARRAY/ANYELEMENT type because input is UNKNOWN
It is permitted to have polymorphic arguments with a deterministic
return type, but the converse is not. For example:
<screen>
-CREATE FUNCTION is_greater(anyelement, anyelement) RETURNS bool AS '
+CREATE FUNCTION is_greater(anyelement, anyelement) RETURNS boolean AS '
SELECT $1 > $2;
' LANGUAGE SQL;
@@ -589,8 +589,8 @@ SELECT is_greater(1, 2);
CREATE FUNCTION invalid_func() RETURNS anyelement AS '
SELECT 1;
' LANGUAGE SQL;
-ERROR: cannot determine result datatype
-DETAIL: A function returning ANYARRAY or ANYELEMENT must have at least one argument of either type.
+ERROR: cannot determine result data type
+DETAIL: A function returning "anyarray" or "anyelement" must have at least one argument of either type.
</screen>
</para>
</sect2>
@@ -758,15 +758,13 @@ CREATE FUNCTION square_root(double precision) RETURNS double precision
that fails as well, the load will fail.
</para>
- <note>
- <para>
- The user ID the <productname>PostgreSQL</productname> server runs
- as must be able to traverse the path to the file you intend to
- load. Making the file or a higher-level directory not readable
- and/or not executable by the <systemitem>postgres</systemitem> user is a
- common mistake.
- </para>
- </note>
+ <para>
+ The user ID the <productname>PostgreSQL</productname> server runs
+ as must be able to traverse the path to the file you intend to
+ load. Making the file or a higher-level directory not readable
+ and/or not executable by the <systemitem>postgres</systemitem>
+ user is a common mistake.
+ </para>
<para>
In any case, the file name that is given in the
@@ -785,16 +783,14 @@ CREATE FUNCTION square_root(double precision) RETURNS double precision
</para>
</note>
- <note>
- <para>
- After it is used for the first time, a dynamically loaded object
- file is retained in memory. Future calls in the same session to the
- function(s) in that file will only incur the small overhead of a symbol
- table lookup. If you need to force a reload of an object file, for
- example after recompiling it, use the <command>LOAD</> command or
- begin a fresh session.
- </para>
- </note>
+ <para>
+ After it is used for the first time, a dynamically loaded object
+ file is retained in memory. Future calls in the same session to
+ the function(s) in that file will only incur the small overhead of
+ a symbol table lookup. If you need to force a reload of an object
+ file, for example after recompiling it, use the <command>LOAD</>
+ command or begin a fresh session.
+ </para>
<para>
It is recommended to locate shared libraries either relative to
@@ -805,17 +801,15 @@ CREATE FUNCTION square_root(double precision) RETURNS double precision
command <literal>pg_config --pkglibdir</literal>.
</para>
- <note>
- <para>
- Before <productname>PostgreSQL</productname> release 7.2, only exact
- absolute paths to object files could be specified in <command>CREATE
- FUNCTION</>. This approach is now deprecated since it makes the
- function definition unnecessarily unportable. It's best to specify
- just the shared library name with no path nor extension, and let
- the search mechanism provide that information instead.
- </para>
- </note>
-
+ <para>
+ Before <productname>PostgreSQL</productname> release 7.2, only
+ exact absolute paths to object files could be specified in
+ <command>CREATE FUNCTION</>. This approach is now deprecated
+ since it makes the function definition unnecessarily unportable.
+ It's best to specify just the shared library name with no path nor
+ extension, and let the search mechanism provide that information
+ instead.
+ </para>
</sect2>
<sect2 id="xfunc-c-basetype">
@@ -1685,8 +1679,7 @@ c_overpaid(PG_FUNCTION_ARGS)
<function>c_overpaid</function> in SQL:
<programlisting>
-CREATE FUNCTION c_overpaid(emp, integer)
- RETURNS boolean
+CREATE FUNCTION c_overpaid(emp, integer) RETURNS boolean
AS '<replaceable>DIRECTORY</replaceable>/funcs', 'c_overpaid'
LANGUAGE C;
</programlisting>
@@ -2111,7 +2104,7 @@ CREATE OR REPLACE FUNCTION testpassbyval(integer, integer) RETURNS SETOF __testp
<para>
C-language functions may be declared to accept and
- return the <quote>polymorphic</> types
+ return the polymorphic types
<type>anyelement</type> and <type>anyarray</type>.
See <xref linkend="extend-types-polymorphic"> for a more detailed explanation
of polymorphic functions. When function arguments or return types
@@ -2178,14 +2171,13 @@ make_array(PG_FUNCTION_ARGS)
<function>make_array</function> in SQL:
<programlisting>
-CREATE FUNCTION make_array(anyelement)
- RETURNS anyarray
+CREATE FUNCTION make_array(anyelement) RETURNS anyarray
AS '<replaceable>DIRECTORY</replaceable>/funcs', 'make_array'
- LANGUAGE 'C' STRICT;
+ LANGUAGE C STRICT;
</programlisting>
- Note the use of STRICT; this is essential since the code is not
- bothering to test for a NULL input.
+ Note the use of <literal>STRICT</literal>; this is essential
+ since the code is not bothering to test for a null input.
</para>
</sect2>
</sect1>
--
GitLab