diff --git a/doc/src/sgml/ref/alter_group.sgml b/doc/src/sgml/ref/alter_group.sgml
index b9819f4a5268b372682b7a36075e0a7c13fa6b0e..31e94d76efc8993e97cda9d2375283ea2741390a 100644
--- a/doc/src/sgml/ref/alter_group.sgml
+++ b/doc/src/sgml/ref/alter_group.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_group.sgml,v 1.12 2003/09/09 18:28:52 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_group.sgml,v 1.13 2003/09/12 00:12:47 tgl Exp $
PostgreSQL documentation
-->
@@ -45,7 +45,7 @@ ALTER GROUP <replaceable class="PARAMETER">groupname</replaceable> RENAME TO <re
</refsect1>
<refsect1>
- <title>Parameter</title>
+ <title>Parameters</title>
<variablelist>
<varlistentry>
diff --git a/doc/src/sgml/ref/alter_language.sgml b/doc/src/sgml/ref/alter_language.sgml
index 61595252ebff1009564547a2756b5b202a3be5fc..b0374a2c49e4dd0f3ebfc1b1a431fc137cd6d021 100644
--- a/doc/src/sgml/ref/alter_language.sgml
+++ b/doc/src/sgml/ref/alter_language.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_language.sgml,v 1.3 2003/09/09 18:28:52 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_language.sgml,v 1.4 2003/09/12 00:12:47 tgl Exp $
PostgreSQL documentation
-->
@@ -35,7 +35,7 @@ ALTER LANGUAGE <replaceable>name</replaceable> RENAME TO <replaceable>newname</r
</refsect1>
<refsect1>
- <title>Parameter</title>
+ <title>Parameters</title>
<variablelist>
<varlistentry>
diff --git a/doc/src/sgml/ref/alter_schema.sgml b/doc/src/sgml/ref/alter_schema.sgml
index 473b57314d4a46bd6025a3aae099e7726321bcbf..6f61cc5672efe24903b911f5961880e4ffd4bf4a 100644
--- a/doc/src/sgml/ref/alter_schema.sgml
+++ b/doc/src/sgml/ref/alter_schema.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_schema.sgml,v 1.3 2003/09/09 18:28:52 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_schema.sgml,v 1.4 2003/09/12 00:12:47 tgl Exp $
PostgreSQL documentation
-->
@@ -36,7 +36,7 @@ ALTER SCHEMA <replaceable>name</replaceable> RENAME TO <replaceable>newname</rep
</refsect1>
<refsect1>
- <title>Parameter</title>
+ <title>Parameters</title>
<variablelist>
<varlistentry>
diff --git a/doc/src/sgml/ref/cluster.sgml b/doc/src/sgml/ref/cluster.sgml
index 1eaa97e2e1e3121cd5aed555a0cc03e38fc69021..54efd0c4be0c8729551c6f5319bae3b65ae7ca6b 100644
--- a/doc/src/sgml/ref/cluster.sgml
+++ b/doc/src/sgml/ref/cluster.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/cluster.sgml,v 1.28 2003/09/09 18:28:52 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/cluster.sgml,v 1.29 2003/09/12 00:12:47 tgl Exp $
PostgreSQL documentation
-->
@@ -74,7 +74,7 @@ CLUSTER
</refsect1>
<refsect1>
- <title>Parameter</title>
+ <title>Parameters</title>
<variablelist>
<varlistentry>
diff --git a/doc/src/sgml/ref/clusterdb.sgml b/doc/src/sgml/ref/clusterdb.sgml
index 8d4e082ec079e7f8897fe3dbb898eda49ed0b081..7be6d0959dab2be7f60e90d0dab3ff6df4c01178 100644
--- a/doc/src/sgml/ref/clusterdb.sgml
+++ b/doc/src/sgml/ref/clusterdb.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/clusterdb.sgml,v 1.13 2003/09/09 18:28:52 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/clusterdb.sgml,v 1.14 2003/09/12 00:12:47 tgl Exp $
PostgreSQL documentation
-->
@@ -48,16 +48,17 @@ PostgreSQL documentation
<application>clusterdb</application> is a wrapper around the SQL
command <xref linkend="SQL-CLUSTER" endterm="sql-cluster-title">.
There is no effective difference between clustering databases via
- this or other methods. The database server must be running at the
- targeted host. Also, any default settings and environment
- variables used by the <application>libpq</application> front-end
- library will apply.
+ this utility and via other methods for accessing the server.
</para>
<para>
In case of difficulty, see <xref linkend="SQL-CLUSTER"
endterm="sql-cluster-title"> and <xref linkend="APP-PSQL"> for
discussions of potential problems and error messages.
+ The database server must be running at the
+ targeted host. Also, any default connection settings and environment
+ variables used by the <application>libpq</application> front-end
+ library will apply.
</para>
</refsect1>
diff --git a/doc/src/sgml/ref/commit.sgml b/doc/src/sgml/ref/commit.sgml
index 1c72ea0b459e7a1af3d039a1c7226e09afcace65..4b026ccfd504b09b1777ee085781ebdfca2b570f 100644
--- a/doc/src/sgml/ref/commit.sgml
+++ b/doc/src/sgml/ref/commit.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/commit.sgml,v 1.17 2003/09/09 18:28:52 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/commit.sgml,v 1.18 2003/09/12 00:12:47 tgl Exp $
PostgreSQL documentation
-->
@@ -12,8 +12,8 @@ PostgreSQL documentation
<refnamediv>
<refname>COMMIT</refname>
<refpurpose>commit the current transaction</refpurpose>
- </refnamediv>
-
+ </refnamediv>
+
<indexterm zone="sql-commit">
<primary>COMMIT</primary>
</indexterm>
@@ -74,7 +74,7 @@ COMMIT;
</programlisting>
</para>
</refsect1>
-
+
<refsect1>
<title>Compatibility</title>
diff --git a/doc/src/sgml/ref/create_database.sgml b/doc/src/sgml/ref/create_database.sgml
index ddde0df33470938b6b6c0a8b4d6cd6376193bd07..9441c9841bde98698e4a8fd8d8453d5a2f9d8a12 100644
--- a/doc/src/sgml/ref/create_database.sgml
+++ b/doc/src/sgml/ref/create_database.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_database.sgml,v 1.35 2003/08/31 17:32:22 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_database.sgml,v 1.36 2003/09/12 00:12:47 tgl Exp $
PostgreSQL documentation
-->
@@ -36,6 +36,12 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
<productname>PostgreSQL</productname> database.
</para>
+ <para>
+ To create a database, you must be a superuser or have the special
+ <literal>CREATEDB</> privilege.
+ See <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">.
+ </para>
+
<para>
Normally, the creator becomes the owner of the new database.
Superusers can create databases owned by other users using the
@@ -63,6 +69,8 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
a leading slash
(e.g., <filename>/usr/local/pgsql/data</filename>),
are allowed as well.
+ In either case, the final path name must be absolute and must not
+ contain any single quotes.
</para>
<para>
@@ -86,7 +94,7 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
</refsect1>
<refsect1>
- <title>Parameter</title>
+ <title>Parameters</title>
<variablelist>
<varlistentry>
@@ -147,78 +155,20 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
</refsect1>
<refsect1>
- <title>Diagnostics</title>
-
- <variablelist>
- <varlistentry>
- <term><computeroutput>CREATE DATABASE</computeroutput></term>
- <listitem>
- <para>
- Message returned if the database was successfully created.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>ERROR: user '<replaceable class="parameter">username</replaceable>' is not allowed to create/drop databases</computeroutput></term>
- <listitem>
- <para>
- You must have the special <literal>CREATEDB</> privilege to create databases.
- See <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">.
- </para>
- </listitem>
- </varlistentry>
-
-
- <varlistentry>
- <term><computeroutput>ERROR: createdb: database "<replaceable class="parameter">name</replaceable>" already exists</computeroutput></term>
- <listitem>
- <para>
- This occurs if a database with the specified name already
- exists.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>ERROR: database path may not contain single quotes</computeroutput></term>
- <listitem>
- <para>
- The database location
- <replaceable class="parameter">dbpath</replaceable> cannot contain
- single quotes. This is required so that the shell commands that
- create the database directory can execute safely.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>ERROR: CREATE DATABASE: may not be called in a transaction block</computeroutput></term>
- <listitem>
- <para>
- If you have an explicit transaction block in progress you cannot call
- <command>CREATE DATABASE</command>. You must finish the transaction first.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>ERROR: Unable to create database directory '<replaceable>path</replaceable>'.</computeroutput></term>
- <term><computeroutput>ERROR: Could not initialize database directory.</computeroutput></term>
- <listitem>
- <para>
- These are most likely related to insufficient permissions on the data
- directory, a full disk, or other file system problems. The user under
- which the database server is running must have access to the location.
- </para>
- </listitem>
- </varlistentry>
+ <title>Notes</title>
- </variablelist>
- </refsect1>
+ <para>
+ <command>CREATE DATABASE</> cannot be executed inside a transaction
+ block.
+ </para>
- <refsect1>
- <title>Notes</title>
+ <para>
+ Errors along the line of <quote>could not initialize database directory</>
+ are most likely related to insufficient permissions on the data
+ directory, a full disk, or other file system problems. When using an
+ alternate location, the user under
+ which the database server is running must have access to the location.
+ </para>
<para>
Use <xref linkend="SQL-DROPDATABASE" endterm="SQL-DROPDATABASE-title"> to remove a database.
@@ -231,7 +181,8 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
<para>
There are security issues involved with using alternate database
- locations specified with absolute path names. See <xref
+ locations specified with absolute path names; this is why the feature
+ is not enabled by default. See <xref
linkend="manage-ag-alternate-locs"> for more information.
</para>
diff --git a/doc/src/sgml/ref/create_sequence.sgml b/doc/src/sgml/ref/create_sequence.sgml
index 5a9210fbcd353e12a33389ceea64cfe0c469976a..089695b1bbc7edcfacc8b4041c9af6b94753fda2 100644
--- a/doc/src/sgml/ref/create_sequence.sgml
+++ b/doc/src/sgml/ref/create_sequence.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_sequence.sgml,v 1.34 2003/08/31 17:32:22 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_sequence.sgml,v 1.35 2003/09/12 00:12:47 tgl Exp $
PostgreSQL documentation
-->
@@ -196,49 +196,6 @@ SELECT * FROM <replaceable>seqname</replaceable>;
</variablelist>
</refsect1>
- <refsect1>
- <title>Diagnostics</title>
-
- <variablelist>
- <varlistentry>
- <term><computeroutput>CREATE SEQUENCE</computeroutput></term>
- <listitem>
- <para>
- Message returned if the sequence was successfully created.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>ERROR: Relation '<replaceable class="parameter">seqname</replaceable>' already exists</computeroutput></term>
- <listitem>
- <para>
- A sequence, table, view, or index of the specified name already exists.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>ERROR: DefineSequence: MINVALUE (<replaceable class="parameter">start</replaceable>) can't be >= MAXVALUE (<replaceable class="parameter">max</replaceable>)</computeroutput></term>
- <term><computeroutput>ERROR: DefineSequence: START value (<replaceable class="parameter">start</replaceable>) can't be < MINVALUE (<replaceable class="parameter">min</replaceable>)</computeroutput></term>
- <listitem>
- <para>
- The specified starting value is out of range.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>ERROR: DefineSequence: MINVALUE (<replaceable class="parameter">min</replaceable>) can't be >= MAXVALUE (<replaceable class="parameter">max</replaceable>)</computeroutput></term>
- <listitem>
- <para>
- The minimum and maximum values are inconsistent.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
<refsect1>
<title>Notes</title>
diff --git a/doc/src/sgml/ref/create_view.sgml b/doc/src/sgml/ref/create_view.sgml
index 6bf9434a1b1e57ae0848a688e2dfbd54d6ce3726..a8d4a20f09a27f76ba610af89d591ee2c34c419a 100644
--- a/doc/src/sgml/ref/create_view.sgml
+++ b/doc/src/sgml/ref/create_view.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_view.sgml,v 1.23 2003/08/31 17:32:22 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_view.sgml,v 1.24 2003/09/12 00:12:47 tgl Exp $
PostgreSQL documentation
-->
@@ -90,39 +90,6 @@ class="PARAMETER">column_name</replaceable> [, ...] ) ] AS <replaceable class="P
</variablelist>
</refsect1>
- <refsect1>
- <title>Diagnostics</title>
-
- <variablelist>
- <varlistentry>
- <term><computeroutput>CREATE VIEW</computeroutput></term>
- <listitem>
- <para>
- Message returned if the view was successfully created.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>WARNING: Attribute '<replaceable class="parameter">column</replaceable>' has an unknown type</computeroutput></term>
- <listitem>
- <para>
- The view will be created having a column with an unknown type if
- you do not specify it. For example, the following command gives
- this warning:
-<programlisting>
-CREATE VIEW vista AS SELECT 'Hello World'
-</programlisting>
- whereas this command does not:
-<programlisting>
-CREATE VIEW vista AS SELECT text 'Hello World'
-</programlisting>
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
<refsect1>
<title>Notes</title>
@@ -137,6 +104,20 @@ CREATE VIEW vista AS SELECT text 'Hello World'
<para>
Use the <command>DROP VIEW</command> statement to drop views.
</para>
+
+ <para>
+ Be careful that the names and types of the view's columns will be
+ assigned the way you want. For example,
+<programlisting>
+CREATE VIEW vista AS SELECT 'Hello World';
+</programlisting>
+ is bad form in two ways: the column name defaults to <literal>?column?</>,
+ and the column datatype defaults to <type>unknown</>. If you want a
+ string literal in a view's result, use something like
+<programlisting>
+CREATE VIEW vista AS SELECT text 'Hello World' AS hello;
+</programlisting>
+ </para>
</refsect1>
<refsect1>
diff --git a/doc/src/sgml/ref/createdb.sgml b/doc/src/sgml/ref/createdb.sgml
index 0af10c05843511fa6cb72e0211a5ddccec681df1..1c7e0ec4af8212c1f5e2f558706b20b3554fe485 100644
--- a/doc/src/sgml/ref/createdb.sgml
+++ b/doc/src/sgml/ref/createdb.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/createdb.sgml,v 1.34 2003/08/31 17:32:22 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/createdb.sgml,v 1.35 2003/09/12 00:12:47 tgl Exp $
PostgreSQL documentation
-->
@@ -48,12 +48,21 @@ PostgreSQL documentation
<para>
<application>createdb</application> is a wrapper around the
<acronym>SQL</acronym> command <xref linkend="SQL-CREATEDATABASE"
- endterm="SQL-CREATEDATABASE-title">. The database server must be
- running on the targeted host. There is nothing special about creating
- databases via this or other methods. Also, any default settings and
- environment variables used by the <application>libpq</application>
- front-end library will apply.
+ endterm="SQL-CREATEDATABASE-title">.
+ There is no effective difference between creating databases via
+ this utility and via other methods for accessing the server.
</para>
+
+ <para>
+ In case of difficulty, see <xref linkend="SQL-CREATEDATABASE"
+ endterm="sql-createdatabase-title"> and <xref linkend="APP-PSQL"> for
+ discussions of potential problems and error messages.
+ The database server must be running at the
+ targeted host. Also, any default connection settings and environment
+ variables used by the <application>libpq</application> front-end
+ library will apply.
+ </para>
+
</refsect1>
@@ -212,45 +221,6 @@ PostgreSQL documentation
</refsect1>
- <refsect1>
- <title>Diagnostics</title>
-
- <variablelist>
- <varlistentry>
- <term><computeroutput>CREATE DATABASE</computeroutput></term>
- <listitem>
- <para>The database was successfully created.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>createdb: Database creation failed.</computeroutput></term>
- <listitem>
- <para>(Says it all.)</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>createdb: Comment creation failed. (Database was created.)</computeroutput></term>
- <listitem>
- <para>
- The comment/description for the database could not be created.
- The database itself will have been created already. You can use the
- <acronym>SQL</acronym> command <command>COMMENT ON DATABASE</command> to
- create the comment later on.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- If there is an error condition, the backend error message will be displayed.
- See <xref linkend="SQL-CREATEDATABASE" endterm="SQL-CREATEDATABASE-TITLE">
- for possibilities.
- </para>
- </refsect1>
-
-
<refsect1>
<title>Environment</title>
diff --git a/doc/src/sgml/ref/createuser.sgml b/doc/src/sgml/ref/createuser.sgml
index 0e6935f536b3dfe4da8605efd8c0faa6f179e8db..484f7fbe11f70e0cb4f658a3896b3cb412a5b2ee 100644
--- a/doc/src/sgml/ref/createuser.sgml
+++ b/doc/src/sgml/ref/createuser.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/createuser.sgml,v 1.36 2003/08/31 17:32:22 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/createuser.sgml,v 1.37 2003/09/12 00:12:47 tgl Exp $
PostgreSQL documentation
-->
@@ -49,17 +49,19 @@ PostgreSQL documentation
<para>
<application>createuser</application> is a wrapper around the
<acronym>SQL</acronym> command <xref linkend="SQL-CREATEUSER"
- endterm="SQL-CREATEUSER-title">. The database server must be
- running on the targeted host. There is nothing special
- about creating users via this or other methods. Also, any
- default settings and environment variables used by the
- <application>libpq</application> front-end library will apply.
+ endterm="SQL-CREATEUSER-title">.
+ There is no effective difference between creating users via
+ this utility and via other methods for accessing the server.
</para>
<para>
- Passwords can only be added later or changed using the
- <acronym>SQL</acronym> command <xref linkend="SQL-ALTERUSER"
- endterm="SQL-ALTERUSER-title">.
+ In case of difficulty, see <xref linkend="SQL-CREATEUSER"
+ endterm="sql-createuser-title"> and <xref linkend="APP-PSQL"> for
+ discussions of potential problems and error messages.
+ The database server must be running at the
+ targeted host. Also, any default connection settings and environment
+ variables used by the <application>libpq</application> front-end
+ library will apply.
</para>
</refsect1>
@@ -101,6 +103,7 @@ PostgreSQL documentation
<para>
The new user is not allowed to create other users (i.e.,
the new user is a regular user, not a superuser).
+ This is the default.
</para>
</listitem>
</varlistentry>
@@ -121,6 +124,7 @@ PostgreSQL documentation
<listitem>
<para>
The new user is not allowed to create databases.
+ This is the default.
</para>
</listitem>
</varlistentry>
@@ -142,7 +146,7 @@ PostgreSQL documentation
<listitem>
<para>
Encrypts the user's password stored in the database. If not
- specified, the default is used.
+ specified, the default password behavior is used.
</para>
</listitem>
</varlistentry>
@@ -164,7 +168,7 @@ PostgreSQL documentation
<listitem>
<para>
Does not encrypt the user's password stored in the database. If
- not specified, the default is used.
+ not specified, the default password behavior is used.
</para>
</listitem>
</varlistentry>
@@ -272,38 +276,6 @@ PostgreSQL documentation
</refsect1>
- <refsect1>
- <title>Diagnostics</title>
-
- <variablelist>
- <varlistentry>
- <term><computeroutput>CREATE USER</computeroutput></term>
- <listitem>
- <para>
- The user was successfully created.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>createuser: creation of user "<replaceable class="parameter">username</replaceable>" failed</computeroutput></term>
- <listitem>
- <para>
- Something went wrong. The user was not created.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
-
- <para>
- If there is an error condition, the backend error message will be displayed.
- See <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">
- for possibilities.
- </para>
- </refsect1>
-
-
<refsect1>
<title>Examples</title>
diff --git a/doc/src/sgml/ref/declare.sgml b/doc/src/sgml/ref/declare.sgml
index 1a3e3ccaffe47d2bfcd520727818eb3de8af99a4..a1884b5ee0bd512ff42208019142274ccd049770 100644
--- a/doc/src/sgml/ref/declare.sgml
+++ b/doc/src/sgml/ref/declare.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/declare.sgml,v 1.27 2003/09/11 21:42:20 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/declare.sgml,v 1.28 2003/09/12 00:12:47 tgl Exp $
PostgreSQL documentation
-->
@@ -44,9 +44,10 @@ DECLARE <replaceable class="parameter">cursorname</replaceable> [ BINARY ] [ INS
format. Once the information comes back in text form, the client
application may need to convert it to a binary format to manipulate
it. In addition, data in the text format is often larger in size
- than in the binary format. Binary cursors return the data in the
- native binary representation. Nevertheless, if you intend to
- display the data as text anyway, retrieving it in text form will
+ than in the binary format. Binary cursors return the data in a
+ binary representation that may be more easily manipulated.
+ Nevertheless, if you intend to display the data as text anyway,
+ retrieving it in text form will
save you some effort on the client side.
</para>
@@ -54,7 +55,8 @@ DECLARE <replaceable class="parameter">cursorname</replaceable> [ BINARY ] [ INS
As an example, if a query returns a value of one from an integer column,
you would get a string of <literal>1</> with a default cursor
whereas with a binary cursor you would get
- a 4-byte value containing the internal representation of the value.
+ a 4-byte field containing the internal representation of the value
+ (in big-endian byte order).
</para>
<para>
@@ -64,16 +66,16 @@ DECLARE <replaceable class="parameter">cursorname</replaceable> [ BINARY ] [ INS
format.
</para>
- <para>
- The string representation is architecture-neutral whereas binary
- representation can differ between different machine architectures.
- <emphasis><productname>PostgreSQL</productname> does not resolve
- byte ordering or representation issues for binary
- cursors.</emphasis> Therefore, if your client machine and server
- machine use different representations (e.g.,
- <quote>big-endian</quote> versus <quote>little-endian</quote>), you
- will probably not want your data returned in binary format.
- </para>
+ <note>
+ <para>
+ When the client application uses the <quote>extended query</> protocol
+ to issue a <command>FETCH</> command, the Bind protocol message
+ specifies whether data is to be retrieved in text or binary format.
+ This choice overrides the way that the cursor is defined. The concept
+ of a binary cursor as such is thus obsolete when using extended query
+ protocol --- any cursor can be treated as either text or binary.
+ </para>
+ </note>
</refsect1>
<refsect1>
@@ -84,8 +86,7 @@ DECLARE <replaceable class="parameter">cursorname</replaceable> [ BINARY ] [ INS
<term><replaceable class="parameter">cursorname</replaceable></term>
<listitem>
<para>
- The name of the cursor to be used in subsequent
- <command>FETCH</command> operations.
+ The name of the cursor to be created.
</para>
</listitem>
</varlistentry>
@@ -192,48 +193,18 @@ DECLARE <replaceable class="parameter">cursorname</replaceable> [ BINARY ] [ INS
</para>
</refsect1>
- <refsect1>
- <title>Diagnostics</title>
-
- <variablelist>
- <varlistentry>
- <term><computeroutput>DECLARE CURSOR</computeroutput></term>
- <listitem>
- <para>
- The message returned if the cursor was successfully defined.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>ERROR: cursor "<replaceable class="parameter">cursorname</replaceable>" already exists</computeroutput></term>
- <listitem>
- <para>
- This error occurs if a cursor with the same name already exists.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>ERROR: DECLARE CURSOR may only be used in begin/end transaction blocks</computeroutput></term>
- <listitem>
- <para>
- This error occurs if the cursor is not declared within a
- transaction block, and <literal>WITH HOLD</literal> is not
- specified.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
<refsect1>
<title>Notes</title>
<para>
- If <literal>WITH HOLD</literal> is not specified, the cursor
+ Unless <literal>WITH HOLD</literal> is specified, the cursor
created by this command can only be used within the current
- transaction. Use
+ transaction. Thus, <command>DECLARE</> without <literal>WITH
+ HOLD</literal> is useless outside a transaction block: the cursor would
+ survive only to the completion of the statement. Therefore
+ <productname>PostgreSQL</productname> reports an error if this
+ command is used outside a transaction block.
+ Use
<xref linkend="sql-begin" endterm="sql-begin-title">,
<xref linkend="sql-commit" endterm="sql-commit-title">
and
diff --git a/doc/src/sgml/ref/delete.sgml b/doc/src/sgml/ref/delete.sgml
index fea6a268abb648c124e307f8c655b056e09691dc..c0a58bd7ff7adda9994b17244c48fb206bb50584 100644
--- a/doc/src/sgml/ref/delete.sgml
+++ b/doc/src/sgml/ref/delete.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/delete.sgml,v 1.18 2003/08/31 17:32:22 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/delete.sgml,v 1.19 2003/09/12 00:12:47 tgl Exp $
PostgreSQL documentation
-->
@@ -52,7 +52,7 @@ DELETE FROM [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ WHERE
<para>
You must have the <literal>DELETE</literal> privilege on the table
to delete from it, as well as the <literal>SELECT</literal>
- privilege to any table whose values are read in the <replaceable
+ privilege for any table whose values are read in the <replaceable
class="parameter">condition</replaceable>.
</para>
</refsect1>
@@ -84,22 +84,20 @@ DELETE FROM [ ONLY ] <replaceable class="PARAMETER">table</replaceable> [ WHERE
</refsect1>
<refsect1>
- <title>Diagnostics</title>
+ <title>Outputs</title>
- <variablelist>
- <varlistentry>
- <term><computeroutput>DELETE <replaceable class="parameter">count</replaceable></computeroutput></term>
- <listitem>
- <para>
- Message returned if rows are successfully deleted. The
- <replaceable class="parameter">count</replaceable> is the number
- of rows deleted. If <replaceable
- class="parameter">count</replaceable> is 0, no rows were
- deleted.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
+ <para>
+ On successful completion, a <command>DELETE</> command returns a command
+ tag of the form
+<screen>
+DELETE <replaceable class="parameter">count</replaceable>
+</screen>
+ The <replaceable class="parameter">count</replaceable> is the number
+ of rows deleted. If <replaceable class="parameter">count</replaceable> is
+ 0, no rows matched the <replaceable
+ class="parameter">condition</replaceable> (this is not considered
+ an error).
+ </para>
</refsect1>
<refsect1>
diff --git a/doc/src/sgml/ref/drop_database.sgml b/doc/src/sgml/ref/drop_database.sgml
index 1224b4142ec37ec2fd53eeae999b5e33663315a6..afb26d6a49af9abf22494fe2e1207d553e50c5f7 100644
--- a/doc/src/sgml/ref/drop_database.sgml
+++ b/doc/src/sgml/ref/drop_database.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_database.sgml,v 1.17 2003/08/31 17:32:22 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_database.sgml,v 1.18 2003/09/12 00:12:47 tgl Exp $
PostgreSQL documentation
-->
@@ -31,6 +31,9 @@ DROP DATABASE <replaceable class="PARAMETER">name</replaceable>
<command>DROP DATABASE</command> drops a database. It removes the
catalog entries for the database and deletes the directory
containing the data. It can only be executed by the database owner.
+ Also, it cannot be executed while you or anyone else are connected
+ to the target database. (Connect to <literal>template1</literal> or any
+ other database to issue this command.)
</para>
<para>
@@ -53,44 +56,14 @@ DROP DATABASE <replaceable class="PARAMETER">name</replaceable>
</variablelist>
</refsect1>
- <refsect1>
- <title>Diagnostics</title>
-
- <variablelist>
- <varlistentry>
- <term><computeroutput>DROP DATABASE</computeroutput></term>
- <listitem>
- <para>
- This message is returned if the command was successful.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>DROP DATABASE: cannot be executed on the currently open database</computeroutput></term>
- <listitem>
- <para>
- You cannot be connected to the database you are about to remove.
- Instead, connect to <literal>template1</literal> or any other
- database and run this command again.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>DROP DATABASE: may not be called in a transaction block</computeroutput></term>
- <listitem>
- <para>
- You must finish the transaction in progress before you can call this command.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
<refsect1>
<title>Notes</title>
+ <para>
+ <command>DROP DATABASE</> cannot be executed inside a transaction
+ block.
+ </para>
+
<para>
This command cannot be executed while connected to the target
database. Thus, it might be more convenient to use the program
diff --git a/doc/src/sgml/ref/drop_user.sgml b/doc/src/sgml/ref/drop_user.sgml
index 143efbca9bd96a03be2195026f4237873a7d4cd5..b125c23a8e71a0e042f503e8889022c0ece6f0fd 100644
--- a/doc/src/sgml/ref/drop_user.sgml
+++ b/doc/src/sgml/ref/drop_user.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_user.sgml,v 1.17 2003/08/31 17:32:23 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_user.sgml,v 1.18 2003/09/12 00:12:47 tgl Exp $
PostgreSQL documentation
-->
@@ -49,39 +49,6 @@ DROP USER <replaceable class="PARAMETER">name</replaceable>
</variablelist>
</refsect1>
- <refsect1>
- <title>Diagnostics</title>
-
- <variablelist>
- <varlistentry>
- <term><computeroutput>DROP USER</computeroutput></term>
- <listitem>
- <para>
- Message returned if the user was successfully deleted.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>ERROR: DROP USER: user "<replaceable class="parameter">name</replaceable>" does not exist</computeroutput></term>
- <listitem>
- <para>
- Message returned if the specified user does not exist.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>DROP USER: user "<replaceable class="parameter">name</replaceable>" owns database "<replaceable class="parameter">name</replaceable>", cannot be removed</computeroutput></term>
- <listitem>
- <para>
- You must drop the database first or change its ownership.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
<refsect1>
<title>Notes</title>
@@ -91,6 +58,11 @@ DROP USER <replaceable class="PARAMETER">name</replaceable>
same functionality as this command (in fact, it calls this command)
but can be run from the command shell.
</para>
+
+ <para>
+ To drop a user who owns a database, first drop the database or change
+ its ownership.
+ </para>
</refsect1>
<refsect1>
diff --git a/doc/src/sgml/ref/dropdb.sgml b/doc/src/sgml/ref/dropdb.sgml
index 725eaf8991ff817dba0b758a00814e96b78b99f3..e1c28fe29313a90e32ea93d4550b4d1402f64de4 100644
--- a/doc/src/sgml/ref/dropdb.sgml
+++ b/doc/src/sgml/ref/dropdb.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropdb.sgml,v 1.23 2003/08/31 17:32:23 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropdb.sgml,v 1.24 2003/09/12 00:12:47 tgl Exp $
PostgreSQL documentation
-->
@@ -41,12 +41,21 @@ PostgreSQL documentation
<para>
<application>dropdb</application> is a wrapper around the
<acronym>SQL</acronym> command <xref linkend="SQL-DROPDATABASE"
- endterm="SQL-DROPDATABASE-title">. The database server must be
- running on the targeted host. There is nothing special
- about dropping databases via this or other methods. Also, any
- default settings and environment variables used by the
- <application>libpq</application> front-end library will apply.
+ endterm="SQL-DROPDATABASE-title">.
+ There is no effective difference between dropping databases via
+ this utility and via other methods for accessing the server.
</para>
+
+ <para>
+ In case of difficulty, see <xref linkend="SQL-DROPDATABASE"
+ endterm="sql-dropdatabase-title"> and <xref linkend="APP-PSQL"> for
+ discussions of potential problems and error messages.
+ The database server must be running at the
+ targeted host. Also, any default connection settings and environment
+ variables used by the <application>libpq</application> front-end
+ library will apply.
+ </para>
+
</refsect1>
@@ -100,7 +109,7 @@ PostgreSQL documentation
</para>
<para>
- <application>createdb</application> also accepts the following
+ <application>dropdb</application> also accepts the following
command-line arguments for connection parameters:
<variablelist>
@@ -153,33 +162,6 @@ PostgreSQL documentation
</refsect1>
- <refsect1>
- <title>Diagnostics</title>
-
- <variablelist>
- <varlistentry>
- <term><computeroutput>DROP DATABASE</computeroutput></term>
- <listitem>
- <para>The database was successfully removed.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>dropdb: Database removal failed.</computeroutput></term>
- <listitem>
- <para>Something didn't work out.</para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- If there is an error condition, the backend error message will be displayed.
- See <xref linkend="SQL-DROPDATABASE" endterm="SQL-DROPDATABASE-title">
- for possibilities.
- </para>
- </refsect1>
-
-
<refsect1>
<title>Environment</title>
diff --git a/doc/src/sgml/ref/dropuser.sgml b/doc/src/sgml/ref/dropuser.sgml
index 27d67f9ba885617d9e7b7b2e2654dff3755978c5..5c26050db96d094763df9cff96d0cd08ffbcc245 100644
--- a/doc/src/sgml/ref/dropuser.sgml
+++ b/doc/src/sgml/ref/dropuser.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropuser.sgml,v 1.28 2003/08/31 17:32:23 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/dropuser.sgml,v 1.29 2003/09/12 00:12:47 tgl Exp $
PostgreSQL documentation
-->
@@ -43,12 +43,21 @@ PostgreSQL documentation
<para>
<application>dropuser</application> is a wrapper around the
<acronym>SQL</acronym> command <xref linkend="SQL-DROPUSER"
- endterm="SQL-DROPUSER-title">. The database server must be running
- on the targeted host. There is nothing special about removing
- users via this or other methods. Also, any default settings and
- environment variables used by the <application>libpq</application>
- front-end library will apply.
+ endterm="SQL-DROPUSER-title">.
+ There is no effective difference between dropping users via
+ this utility and via other methods for accessing the server.
</para>
+
+ <para>
+ In case of difficulty, see <xref linkend="SQL-DROPUSER"
+ endterm="sql-dropuser-title"> and <xref linkend="APP-PSQL"> for
+ discussions of potential problems and error messages.
+ The database server must be running at the
+ targeted host. Also, any default connection settings and environment
+ variables used by the <application>libpq</application> front-end
+ library will apply.
+ </para>
+
</refsect1>
@@ -103,7 +112,7 @@ PostgreSQL documentation
</para>
<para>
- <application>createuser</application> also accepts the following
+ <application>dropuser</application> also accepts the following
command-line arguments for connection parameters:
<variablelist>
@@ -176,38 +185,6 @@ PostgreSQL documentation
</refsect1>
- <refsect1>
- <title>Diagnostics</title>
-
- <variablelist>
- <varlistentry>
- <term><computeroutput>DROP USER</computeroutput></term>
- <listitem>
- <para>
- The user was successfully removed.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>dropuser: deletion of user "<replaceable class="parameter">username</replaceable>" failed</computeroutput></term>
- <listitem>
- <para>
- Something went wrong. The user was not removed.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
-
- <para>
- If there is an error condition, the backend error message will be displayed.
- See <xref linkend="SQL-DROPUSER" endterm="SQL-DROPUSER-title">
- and <xref linkend="APP-PSQL"> for possibilities.
- </para>
- </refsect1>
-
-
<refsect1>
<title>Examples</title>
diff --git a/doc/src/sgml/ref/end.sgml b/doc/src/sgml/ref/end.sgml
index 7772184ae835d5075113ec101109740287de18ae..115d25f00535b1678db9f01f938e95a5b979bd85 100644
--- a/doc/src/sgml/ref/end.sgml
+++ b/doc/src/sgml/ref/end.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/end.sgml,v 1.11 2003/09/11 21:42:20 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/end.sgml,v 1.12 2003/09/12 00:12:47 tgl Exp $
PostgreSQL documentation
-->
@@ -30,9 +30,10 @@ END [ WORK | TRANSACTION ]
<para>
<command>END</command> commits the current transaction. All changes
made by the transaction become visible to others and are guaranteed
- to be durable if a crash occurs. It is a
- <productname>PostgreSQL</productname> extension that is equivalent
- to <xref linkend="sql-commit" endterm="sql-commit-title">.
+ to be durable if a crash occurs. This command is a
+ <productname>PostgreSQL</productname> extension
+ that is equivalent to <xref linkend="sql-commit"
+ endterm="sql-commit-title">.
</para>
</refsect1>
@@ -51,31 +52,7 @@ END [ WORK | TRANSACTION ]
</varlistentry>
</variablelist>
</refsect1>
-
- <refsect1>
- <title>Diagnostics</title>
- <variablelist>
- <varlistentry>
- <term><computeroutput>COMMIT</computeroutput></term>
- <listitem>
- <para>
- Message returned if the transaction was successfully committed.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>WARNING: COMMIT: no transaction in progress</computeroutput></term>
- <listitem>
- <para>
- Message if there is no transaction in progress.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
<refsect1>
<title>Notes</title>
@@ -83,6 +60,11 @@ END [ WORK | TRANSACTION ]
Use <xref linkend="SQL-ROLLBACK" endterm="SQL-ROLLBACK-TITLE"> to
abort a transaction.
</para>
+
+ <para>
+ Issuing <command>END</> when not inside a transaction does
+ no harm, but it will provoke a warning message.
+ </para>
</refsect1>
<refsect1>
@@ -106,6 +88,16 @@ END;
specified in the SQL standard.
</para>
</refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+
+ <simplelist type="inline">
+ <member><xref linkend="sql-begin" endterm="sql-begin-title"></member>
+ <member><xref linkend="sql-commit" endterm="sql-commit-title"></member>
+ <member><xref linkend="sql-rollback" endterm="sql-rollback-title"></member>
+ </simplelist>
+ </refsect1>
</refentry>
<!-- Keep this comment at the end of the file
diff --git a/doc/src/sgml/ref/explain.sgml b/doc/src/sgml/ref/explain.sgml
index bb9016d69a674a18d2d94e45b18d2dd81d437cb4..754863881d00bfe95906118c65ddbc65713831f6 100644
--- a/doc/src/sgml/ref/explain.sgml
+++ b/doc/src/sgml/ref/explain.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/explain.sgml,v 1.29 2003/09/09 18:28:53 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/explain.sgml,v 1.30 2003/09/12 00:12:47 tgl Exp $
PostgreSQL documentation
-->
@@ -80,7 +80,7 @@ ROLLBACK;
</refsect1>
<refsect1>
- <title>Parameter</title>
+ <title>Parameters</title>
<variablelist>
<varlistentry>
diff --git a/doc/src/sgml/ref/fetch.sgml b/doc/src/sgml/ref/fetch.sgml
index 9c1050b835e3089514198464da8bad1c499771bf..5f3639d4c7fd19040a7756ff5e38cf45ec8108b7 100644
--- a/doc/src/sgml/ref/fetch.sgml
+++ b/doc/src/sgml/ref/fetch.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/fetch.sgml,v 1.32 2003/09/09 18:28:53 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/fetch.sgml,v 1.33 2003/09/12 00:12:47 tgl Exp $
PostgreSQL documentation
-->
@@ -45,7 +45,7 @@ where <replaceable class="PARAMETER">direction</replaceable> can be empty or one
<title>Description</title>
<para>
- <command>FETCH</command> retrieves rows using a cursor.
+ <command>FETCH</command> retrieves rows using a previously-created cursor.
</para>
<para>
@@ -280,6 +280,23 @@ where <replaceable class="PARAMETER">direction</replaceable> can be empty or one
</variablelist>
</refsect1>
+ <refsect1>
+ <title>Outputs</title>
+
+ <para>
+ On successful completion, a <command>FETCH</> command returns a command
+ tag of the form
+<screen>
+FETCH <replaceable class="parameter">count</replaceable>
+</screen>
+ The <replaceable class="parameter">count</replaceable> is the number
+ of rows fetched (possibly zero). Note that in
+ <application>psql</application>, the command tag will not actually be
+ displayed, since <application>psql</application> displays the fetched
+ rows instead.
+ </para>
+ </refsect1>
+
<refsect1>
<title>Notes</title>
diff --git a/doc/src/sgml/ref/insert.sgml b/doc/src/sgml/ref/insert.sgml
index 76160d6dbec9d8cdd7cd44dabd231d7cae6b7fd3..40ecaccdaf86b1bf0b1b4e9c025658bc04d05ba8 100644
--- a/doc/src/sgml/ref/insert.sgml
+++ b/doc/src/sgml/ref/insert.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/insert.sgml,v 1.24 2003/08/31 17:32:23 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/insert.sgml,v 1.25 2003/09/12 00:12:47 tgl Exp $
PostgreSQL documentation
-->
@@ -119,30 +119,21 @@ INSERT INTO <replaceable class="PARAMETER">table</replaceable> [ ( <replaceable
</refsect1>
<refsect1>
- <title>Diagnostics</title>
+ <title>Outputs</title>
- <variablelist>
- <varlistentry>
- <term><computeroutput>INSERT <replaceable>oid</replaceable> 1</computeroutput></term>
- <listitem>
- <para>
- Message returned if only one row was inserted.
- <returnvalue><replaceable>oid</replaceable></returnvalue> is the
- <acronym>OID</acronym> of the inserted row.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>INSERT 0 <replaceable>count</replaceable></computeroutput></term>
- <listitem>
- <para>
- Message returned if more than one rows were inserted.
- <replaceable>count</replaceable> is the number of rows inserted.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
+ <para>
+ On successful completion, an <command>INSERT</> command returns a command
+ tag of the form
+<screen>
+INSERT <replaceable>oid</replaceable> <replaceable class="parameter">count</replaceable>
+</screen>
+ The <replaceable class="parameter">count</replaceable> is the number
+ of rows inserted. If <replaceable class="parameter">count</replaceable>
+ is exactly one, and the target table has OIDs, then
+ <replaceable class="parameter">oid</replaceable> is the
+ <acronym>OID</acronym> assigned to the inserted row. Otherwise
+ <replaceable class="parameter">oid</replaceable> is zero.
+ </para>
</refsect1>
<refsect1>
diff --git a/doc/src/sgml/ref/listen.sgml b/doc/src/sgml/ref/listen.sgml
index 7de13387dbde947df3a903561cf786c0fd9cb2d7..8029b5ed036afde73ede82022ca016fda50c0956 100644
--- a/doc/src/sgml/ref/listen.sgml
+++ b/doc/src/sgml/ref/listen.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/listen.sgml,v 1.17 2003/08/31 17:32:23 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/listen.sgml,v 1.18 2003/09/12 00:12:47 tgl Exp $
PostgreSQL documentation
-->
@@ -31,6 +31,9 @@ LISTEN <replaceable class="PARAMETER">name</replaceable>
<command>LISTEN</command> registers the current session as a
listener on the notification condition <replaceable
class="PARAMETER">name</replaceable>.
+ If the current session is already registered as a listener for
+ this notification condition, a warning message appears and nothing
+ is done.
</para>
<para>
@@ -85,30 +88,6 @@ LISTEN <replaceable class="PARAMETER">name</replaceable>
</variablelist>
</refsect1>
- <refsect1>
- <title>Diagnostics</title>
-
- <variablelist>
- <varlistentry>
- <term><computeroutput>LISTEN</computeroutput></term>
- <listitem>
- <para>
- Message returned upon successful completion of registration.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>WARNING: Async_Listen: We are already listening on <replaceable class="PARAMETER">name</replaceable></computeroutput></term>
- <listitem>
- <para>
- Message returned if this session is already registered for that notification condition.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
<refsect1>
<title>Examples</title>
@@ -117,7 +96,7 @@ LISTEN <replaceable class="PARAMETER">name</replaceable>
<programlisting>
LISTEN virtual;
NOTIFY virtual;
-Asynchronous NOTIFY 'virtual' from backend with pid '8448' received.
+Asynchronous notification "virtual" received from server process with PID 8448.
</programlisting>
</para>
</refsect1>
diff --git a/doc/src/sgml/ref/move.sgml b/doc/src/sgml/ref/move.sgml
index 471e0529790cc6825afd9ecc84907b88f2490a99..c13cdc9ead3d41e7eb0d0b800595f54cfb7c7165 100644
--- a/doc/src/sgml/ref/move.sgml
+++ b/doc/src/sgml/ref/move.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/move.sgml,v 1.23 2003/08/31 17:32:23 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/move.sgml,v 1.24 2003/09/12 00:12:47 tgl Exp $
PostgreSQL documentation
-->
@@ -41,12 +41,16 @@ MOVE [ <replaceable class="PARAMETER">direction</replaceable> { FROM | IN } ] <r
</refsect1>
<refsect1>
- <title>Diagnostics</title>
+ <title>Outputs</title>
<para>
- The count returned in <command>MOVE</command>'s status string is
- the count of the number of rows that would have been returned by
- the equivalent <command>FETCH</command> command.
+ On successful completion, a <command>MOVE</> command returns a command
+ tag of the form
+<screen>
+MOVE <replaceable class="parameter">count</replaceable>
+</screen>
+ The <replaceable class="parameter">count</replaceable> is the number
+ of rows moved over (possibly zero).
</para>
</refsect1>
diff --git a/doc/src/sgml/ref/postmaster.sgml b/doc/src/sgml/ref/postmaster.sgml
index 07c6f2bfc024536b4bfb2df11a7f9eb0574301a3..77aecf70310fc2b5f112d8268d28820059ae7585 100644
--- a/doc/src/sgml/ref/postmaster.sgml
+++ b/doc/src/sgml/ref/postmaster.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.38 2003/09/11 17:31:45 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.39 2003/09/12 00:12:47 tgl Exp $
PostgreSQL documentation
-->
@@ -419,73 +419,52 @@ PostgreSQL documentation
<refsect1>
<title>Diagnostics</title>
- <para>
- <variablelist>
- <varlistentry>
- <term><computeroutput>semget: No space left on device</computeroutput></term>
- <listitem>
- <para>
- If you see this message, you probably need to configure
- your kernel for shared memory and semaphores as described in <xref linkend="kernel-resources">.
- If you run multiple instances of
- <command>postmaster</command>
- on a single host, or have a kernel with particularly small shared memory
- and/or semaphore limits, you may have to reconfigure your kernel to increase
- its shared memory or semaphore parameters.
- </para>
+ <para>
+ A failure message mentioning <literal>semget</> or <literal>shmget</>
+ probably indicates you need to configure your kernel to provide adequate
+ shared memory and semaphores. For more discussion see <xref
+ linkend="kernel-resources">.
+ </para>
- <tip>
- <para>
- You may be able to postpone
- reconfiguring your kernel by decreasing <option>-B</option> to reduce
- the shared memory consumption of <productname>PostgreSQL</>,
- and/or by reducing <option>-N</option> to reduce the semaphore
- consumption.
- </para>
- </tip>
- </listitem>
- </varlistentry>
+ <tip>
+ <para>
+ You may be able to postpone reconfiguring your kernel by decreasing
+ <varname>shared_buffers</varname> to reduce the shared memory consumption
+ of <productname>PostgreSQL</>, and/or by reducing
+ <varname>max_connections</varname> to reduce the semaphore consumption.
+ </para>
+ </tip>
- <varlistentry>
- <term><computeroutput>StreamServerPort: cannot bind to port</computeroutput></term>
- <listitem>
- <para>
- If you see this message, you should make certain that there is no
- other <command>postmaster</command>
- process already running on the same port number. The easiest way to
- determine this is by using the command
+ <para>
+ A failure message suggesting that another postmaster is already running
+ should be checked carefully, for example by using the command
<screen>
<prompt>$</prompt> <userinput>ps ax | grep postmaster</userinput>
</screen>
or
<screen>
-<prompt>$</prompt> <userinput>ps -e | grep postmaster</userinput>
+<prompt>$</prompt> <userinput>ps -ef | grep postmaster</userinput>
</screen>
- depending on your system.
- </para>
+ depending on your system. If you are certain that no conflicting
+ postmaster is running, you may remove the lock file mentioned in the
+ message and try again.
+ </para>
- <para>
- If you
- are sure that no other
- <command>postmaster</command>
- processes are running and you still get this error, try specifying a
- different port using the
- <literal>-p</literal>
- option. You may also get this error if you terminate the
- <command>postmaster</command>
- and immediately restart it using the same port; in this case, you must
- simply wait a few seconds until the operating system closes the port
- before trying again. Finally, you may get this error if you specify
- a port number that your operating system considers to be reserved.
- For example, many versions of Unix consider port numbers under 1024 to
- be <quote>trusted</quote>
- and only permit the Unix superuser to access them.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
+ <para>
+ A failure message indicating inability to bind to a port may indicate
+ that that port is already in use by some non-PostgreSQL process.
+ You may also get this error if you terminate the
+ <command>postmaster</command>
+ and immediately restart it using the same port; in this case, you must
+ simply wait a few seconds until the operating system closes the port
+ before trying again. Finally, you may get this error if you specify
+ a port number that your operating system considers to be reserved.
+ For example, many versions of Unix consider port numbers under 1024 to
+ be <quote>trusted</quote>
+ and only permit the Unix superuser to access them.
</para>
+
</refsect1>
<refsect1>
diff --git a/doc/src/sgml/ref/set.sgml b/doc/src/sgml/ref/set.sgml
index cf9f0468adedf72bd05fc439a68c8b562ef04f85..1bdb3d0ebb40ff131aa82637f587f6707f47945e 100644
--- a/doc/src/sgml/ref/set.sgml
+++ b/doc/src/sgml/ref/set.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/set.sgml,v 1.81 2003/08/31 17:32:24 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/set.sgml,v 1.82 2003/09/12 00:12:47 tgl Exp $
PostgreSQL documentation
-->
@@ -224,48 +224,6 @@ SELECT setseed(<replaceable>value</replaceable>);
</para>
</refsect1>
- <refsect1>
- <title>Diagnostics</title>
-
- <variablelist>
- <varlistentry>
- <term><computeroutput>SET</computeroutput></term>
- <listitem>
- <para>
- Message returned if successful.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>ERROR: '<replaceable>name</replaceable>' is not a valid option name</computeroutput></term>
- <listitem>
- <para>
- The parameter you tried to set does not exist.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>ERROR: '<replaceable>name</replaceable>': permission denied</computeroutput></term>
- <listitem>
- <para>
- You must be a superuser to alter certain settings.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>ERROR: '<replaceable>name</replaceable>' cannot be changed after server start</computeroutput></term>
- <listitem>
- <para>
- Some parameters are fixed once the server is started.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </refsect1>
-
<refsect1>
<title>Notes</title>
diff --git a/doc/src/sgml/ref/truncate.sgml b/doc/src/sgml/ref/truncate.sgml
index 3fca86910359593a32c3ee86ac2399757c7b96c5..fc65f65db55ed98df99eb53f5fbb1ee4a9e10ca1 100644
--- a/doc/src/sgml/ref/truncate.sgml
+++ b/doc/src/sgml/ref/truncate.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/truncate.sgml,v 1.12 2003/09/09 18:28:53 tgl Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/truncate.sgml,v 1.13 2003/09/12 00:12:47 tgl Exp $
PostgreSQL documentation
-->
@@ -36,7 +36,7 @@ TRUNCATE [ TABLE ] <replaceable class="PARAMETER">name</replaceable>
</refsect1>
<refsect1>
- <title>Parameter</title>
+ <title>Parameters</title>
<variablelist>
<varlistentry>
diff --git a/doc/src/sgml/ref/update.sgml b/doc/src/sgml/ref/update.sgml
index 01917b362df9df5e353b71a1d00f741ea6379b6c..10d5886b3b26acc1bd9d1ddb469f9f0b48ec5feb 100644
--- a/doc/src/sgml/ref/update.sgml
+++ b/doc/src/sgml/ref/update.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/update.sgml,v 1.25 2003/09/11 21:42:20 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/update.sgml,v 1.26 2003/09/12 00:12:47 tgl Exp $
PostgreSQL documentation
-->
@@ -118,21 +118,20 @@ UPDATE [ ONLY ] <replaceable class="PARAMETER">table</replaceable> SET <replacea
</refsect1>
<refsect1>
- <title>Diagnostics</title>
+ <title>Outputs</title>
- <variablelist>
- <varlistentry>
- <term><computeroutput>UPDATE <replaceable class="parameter">count</replaceable></computeroutput></term>
- <listitem>
- <para>
- Message returned if successful. The value <replaceable
- class="parameter">count</replaceable> is the number of rows
- updated. If <replaceable class="parameter">count</replaceable>
- is 0, no rows were updated.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
+ <para>
+ On successful completion, an <command>UPDATE</> command returns a command
+ tag of the form
+<screen>
+UPDATE <replaceable class="parameter">count</replaceable>
+</screen>
+ The <replaceable class="parameter">count</replaceable> is the number
+ of rows updated. If <replaceable class="parameter">count</replaceable> is
+ 0, no rows matched the <replaceable
+ class="parameter">condition</replaceable> (this is not considered
+ an error).
+ </para>
</refsect1>
<refsect1>
diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml
index 7102a3d0d336273d39bdef92e3a11c4f098cf3f9..aab2f74bf1425b7144d84c577abf3e79d1857dd7 100644
--- a/doc/src/sgml/ref/vacuum.sgml
+++ b/doc/src/sgml/ref/vacuum.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuum.sgml,v 1.32 2003/08/31 17:32:24 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuum.sgml,v 1.33 2003/09/12 00:12:47 tgl Exp $
PostgreSQL documentation
-->
@@ -143,49 +143,13 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] ANALYZE [ <replaceable class="PARAMETER">
</refsect1>
<refsect1>
- <title>Diagnostics</title>
+ <title>Outputs</title>
- <variablelist>
- <varlistentry>
- <term><computeroutput>VACUUM</computeroutput></term>
- <listitem>
- <para>
- The command is complete.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>INFO: --Relation <replaceable class="PARAMETER">table</replaceable>--</computeroutput></term>
- <listitem>
- <para>
- The report header for <replaceable class="PARAMETER">table</replaceable>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>INFO: Pages 98: Changed 25, Reapped 74, Empty 0, New 0;
- Tup 1000: Vac 3000, Crash 0, UnUsed 0, MinLen 188, MaxLen 188;
- Re-using: Free/Avail. Space 586952/586952; EndEmpty/Avail. Pages 0/74.
- Elapsed 0/0 sec.</computeroutput></term>
- <listitem>
- <para>
- The analysis for <replaceable class="PARAMETER">table</replaceable> itself.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>INFO: Index <replaceable class="PARAMETER">index</replaceable>: Pages 28;
- Tuples 1000: Deleted 3000. Elapsed 0/0 sec.</computeroutput></term>
- <listitem>
- <para>
- The analysis for an index on the target table.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
+ <para>
+ When <literal>VERBOSE</> is specified, <command>VACUUM</> emits
+ progress messages to indicate which table is currently being
+ processed. Various statistics about the tables are printed as well.
+ </para>
</refsect1>
<refsect1>
@@ -216,25 +180,37 @@ VACUUM [ FULL ] [ FREEZE ] [ VERBOSE ] ANALYZE [ <replaceable class="PARAMETER">
<title>Examples</title>
<para>
- The following is an example from running <command>VACUUM</command> on a table
- in the regression database:
+ The following is an example from running <command>VACUUM</command> on a
+ table in the regression database:
<programlisting>
-=> VACUUM VERBOSE ANALYZE onek;
-INFO: --Relation onek--
-INFO: Index onek_unique1: Pages 14; Tuples 1000: Deleted 3000.
- CPU 0.00s/0.11u sec elapsed 0.12 sec.
-INFO: Index onek_unique2: Pages 16; Tuples 1000: Deleted 3000.
- CPU 0.00s/0.10u sec elapsed 0.10 sec.
-INFO: Index onek_hundred: Pages 13; Tuples 1000: Deleted 3000.
- CPU 0.00s/0.10u sec elapsed 0.10 sec.
-INFO: Index onek_stringu1: Pages 31; Tuples 1000: Deleted 3000.
- CPU 0.01s/0.09u sec elapsed 0.10 sec.
-INFO: Removed 3000 tuples in 70 pages.
- CPU 0.02s/0.04u sec elapsed 0.07 sec.
-INFO: Pages 94: Changed 0, Empty 0; Tup 1000: Vac 3000, Keep 0, UnUsed 0.
- Total CPU 0.05s/0.45u sec elapsed 0.59 sec.
-INFO: Analyzing onek
+regression=# VACUUM VERBOSE ANALYZE onek;
+INFO: vacuuming "public.onek"
+INFO: index "onek_unique1" now contains 1000 tuples in 14 pages
+DETAIL: 3000 index tuples were removed.
+0 index pages have been deleted, 0 are currently reusable.
+CPU 0.01s/0.08u sec elapsed 0.18 sec.
+INFO: index "onek_unique2" now contains 1000 tuples in 16 pages
+DETAIL: 3000 index tuples were removed.
+0 index pages have been deleted, 0 are currently reusable.
+CPU 0.00s/0.07u sec elapsed 0.23 sec.
+INFO: index "onek_hundred" now contains 1000 tuples in 13 pages
+DETAIL: 3000 index tuples were removed.
+0 index pages have been deleted, 0 are currently reusable.
+CPU 0.01s/0.08u sec elapsed 0.17 sec.
+INFO: index "onek_stringu1" now contains 1000 tuples in 48 pages
+DETAIL: 3000 index tuples were removed.
+0 index pages have been deleted, 0 are currently reusable.
+CPU 0.01s/0.09u sec elapsed 0.59 sec.
+INFO: "onek": removed 3000 tuples in 108 pages
+DETAIL: CPU 0.01s/0.06u sec elapsed 0.07 sec.
+INFO: "onek": found 3000 removable, 1000 nonremovable tuples in 143 pages
+DETAIL: 0 dead tuples cannot be removed yet.
+There were 0 unused item pointers.
+0 pages are entirely empty.
+CPU 0.07s/0.39u sec elapsed 1.56 sec.
+INFO: analyzing "public.onek"
+INFO: "onek": 36 pages, 1000 rows sampled, 1000 estimated total rows
VACUUM
</programlisting>
</para>
diff --git a/doc/src/sgml/ref/vacuumdb.sgml b/doc/src/sgml/ref/vacuumdb.sgml
index 31390050c298d61ce24f313e224e475df860687c..63d7b4d3ee49ec2e5bb5ff5ddb70fed7e4debcb4 100644
--- a/doc/src/sgml/ref/vacuumdb.sgml
+++ b/doc/src/sgml/ref/vacuumdb.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuumdb.sgml,v 1.31 2003/08/31 17:32:24 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/vacuumdb.sgml,v 1.32 2003/09/12 00:12:47 tgl Exp $
PostgreSQL documentation
-->
@@ -55,13 +55,19 @@ PostgreSQL documentation
<application>vacuumdb</application> is a wrapper around the SQL
command <xref linkend="SQL-VACUUM" endterm="SQL-VACUUM-title">.
There is no effective difference between vacuuming databases via
- this or other methods. The database server must be running at the
- targeted host. Also, any default settings and environment
+ this utility and via other methods for accessing the server.
+ </para>
+
+ <para>
+ In case of difficulty, see <xref linkend="SQL-VACUUM"
+ endterm="sql-vacuum-title"> and <xref linkend="APP-PSQL"> for
+ discussions of potential problems and error messages.
+ The database server must be running at the
+ targeted host. Also, any default connection settings and environment
variables used by the <application>libpq</application> front-end
library will apply.
</para>
-
<para>
<application>vacuumdb</application> might need to connect several
times to the <productname>PostgreSQL</productname> server, asking
@@ -230,37 +236,6 @@ PostgreSQL documentation
</refsect1>
- <refsect1>
- <title>Diagnostics</title>
-
- <para>
- <variablelist>
- <varlistentry>
- <term><computeroutput>VACUUM</computeroutput></term>
- <listitem>
- <para>
- The database was successfully vacuumed.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><computeroutput>vacuumdb: Vacuum failed.</computeroutput></term>
- <listitem>
- <para>
- Something went wrong. <application>vacuumdb</application> is only a wrapper
- script. See <xref linkend="SQL-VACUUM" endterm="SQL-VACUUM-title">
- and <xref linkend="APP-PSQL"> for a detailed
- discussion of error messages and potential problems.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
- </para>
- </refsect1>
-
-
<refsect1>
<title>Environment</title>