OSDN Git Service

Rearrange and consolidate the Admin Guide.
authorThomas G. Lockhart <lockhart@fourpalms.org>
Thu, 20 May 1999 05:39:29 +0000 (05:39 +0000)
committerThomas G. Lockhart <lockhart@fourpalms.org>
Thu, 20 May 1999 05:39:29 +0000 (05:39 +0000)
Add reference pages for utilities and remove standalone chapters for same.
Add material for an appendix on date/time properties, but not yet
 integrated with the User's Guide.
Break up the former chapter on pg_options
 into Admin and Programmer's Guides.

18 files changed:
doc/src/sgml/admin.sgml
doc/src/sgml/datetime.sgml [new file with mode: 0644]
doc/src/sgml/install.sgml
doc/src/sgml/layout.sgml [new file with mode: 0644]
doc/src/sgml/pg_options.sgml
doc/src/sgml/pgaccess.sgml [deleted file]
doc/src/sgml/postgres.sgml
doc/src/sgml/programmer.sgml
doc/src/sgml/psql.sgml [deleted file]
doc/src/sgml/query-ug.sgml [deleted file]
doc/src/sgml/query.sgml
doc/src/sgml/runtime.sgml
doc/src/sgml/security.sgml
doc/src/sgml/sql.sgml
doc/src/sgml/start-ag.sgml
doc/src/sgml/trouble.sgml [new file with mode: 0644]
doc/src/sgml/tutorial.sgml
doc/src/sgml/user.sgml

index 7850f4f..9bf1f39 100644 (file)
@@ -1,11 +1,19 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.12 1999/05/12 07:32:42 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.13 1999/05/20 05:39:25 thomas Exp $
 
 Postgres Administrator's Guide.
 Derived from postgres.sgml.
 - thomas 1998-10-27
 
 $Log: admin.sgml,v $
+Revision 1.13  1999/05/20 05:39:25  thomas
+Rearrange and consolidate the Admin Guide.
+Add reference pages for utilities and remove standalone chapters for same.
+Add material for an appendix on date/time properties, but not yet
+ integrated with the User's Guide.
+Break up the former chapter on pg_options
+ into Admin and Programmer's Guides.
+
 Revision 1.12  1999/05/12 07:32:42  thomas
 Include mention of CASE, COALESCE, and IFNULL.
 Add date/time parsing procedure (perhaps should be in appendix).
@@ -46,7 +54,7 @@ Bigger updates to the installation instructions (install and config).
 <!entity intro-ag SYSTEM "intro-ag.sgml">
 <!entity install  SYSTEM "install.sgml">
 <!entity installw SYSTEM "install-win32.sgml">
-<!entity options  SYSTEM "pg_options.sgml">
+<!entity layout   SYSTEM "layout.sgml">
 <!entity ports    SYSTEM "ports.sgml">
 <!entity recovery SYSTEM "recovery.sgml">
 <!entity regress  SYSTEM "regress.sgml">
@@ -54,6 +62,7 @@ Bigger updates to the installation instructions (install and config).
 <!entity runtime  SYSTEM "runtime.sgml">
 <!entity security SYSTEM "security.sgml">
 <!entity start-ag SYSTEM "start-ag.sgml">
+<!entity trouble  SYSTEM "trouble.sgml">
 
 <!entity biblio   SYSTEM "biblio.sgml">
 ]>
@@ -87,12 +96,12 @@ Bigger updates to the installation instructions (install and config).
     <AuthorInitials>TGL</AuthorInitials>
 -->
 
-   <Date>(last updated 1999-04-08)</Date>
+   <Date>(last updated 1999-05-19)</Date>
   </BookBiblio>
 
   <LegalNotice>
    <Para>
-    <ProductName>PostgreSQL</ProductName> is copyright (C) 1998-9
+    <ProductName>PostgreSQL</ProductName> is copyright (&copy;) 1998-9
     by the Postgres Global Development Group.
    </Para>
   </LegalNotice>
@@ -131,12 +140,13 @@ Your name here...
 
   &ports;
   &config;
+  &layout;
   &install;
   &installw;
   &runtime;
   &security;
-  &options;
   &start-ag;
+  &trouble;
   &recovery;
   &regress;
   &release;
@@ -155,7 +165,7 @@ Don't bother with an index until we get some index entries.
 <!-- Keep this comment at the end of the file
 Local variables:
 mode: sgml
-sgml-omittag:t
+sgml-omittag:nil
 sgml-shorttag:t
 sgml-minimize-attributes:nil
 sgml-always-quote-attributes:t
diff --git a/doc/src/sgml/datetime.sgml b/doc/src/sgml/datetime.sgml
new file mode 100644 (file)
index 0000000..eba6dbb
--- /dev/null
@@ -0,0 +1,155 @@
+From - Mon May 10 15:59:27 1999
+Received: from localhost (lockhart@localhost [127.0.0.1])
+       by localhost (8.8.7/8.8.7) with ESMTP id PAA24871
+       for <lockhart@localhost>; Wed, 14 Apr 1999 15:45:24 GMT
+Received: from apop-server.alumni.caltech.edu
+       by localhost with POP3 (fetchmail-4.7.9)
+       for lockhart@localhost (single-drop); Wed, 14 Apr 1999 15:45:26 +0000 (UTC)
+Received: from bologna.nettuno.it (bologna.nettuno.it [193.43.2.1])
+       by alumnus.caltech.edu (8.9.1/8.9.1) with ESMTP id IAA18386
+       for <lockhart@alumni.caltech.edu>; Wed, 14 Apr 1999 08:41:45 -0700 (PDT)
+Received: from proxy.sferacarta.com (mail@sfcabop1.nettuno.it [193.207.10.213])
+       by bologna.nettuno.it (8.8.6/8.8.6/NETTuno 3.1) with ESMTP id RAA15888;
+       Wed, 14 Apr 1999 17:41:33 +0200 (MDT)
+Received: from rosso.sferacarta.com (sferacarta.com) [10.20.30.5] 
+       by proxy.sferacarta.com with esmtp (Exim 2.05 #1 (Debian))
+       id 10XTfQ-00083Z-00; Wed, 14 Apr 1999 17:41:40 +0000
+Message-ID: <3714B6B6.F745D41D@sferacarta.com>
+Date: Wed, 14 Apr 1999 17:39:34 +0200
+From: José Soares <jose@sferacarta.com>
+X-Mailer: Mozilla 4.5 [it] (Win95; I)
+X-Accept-Language: it
+MIME-Version: 1.0
+To: Thomas Lockhart <lockhart@alumni.caltech.edu>
+CC: hackers <pgsql-hackers@postgresql.org>,
+        general <pgsql-general@postgresql.org>
+Subject: Re: [GENERAL] Re: [HACKERS] Gregorian Calendar
+References: <3711B1E5.80213DF6@sferacarta.com> <37135951.88FDB948@alumni.caltech.edu>
+Content-Transfer-Encoding: 8bit
+Content-Type: text/plain; charset=iso-8859-1
+X-UIDL: 25f0580d2a532247ac6af3aee9737b7c
+X-Mozilla-Status: 8011
+X-Mozilla-Status2: 00000000
+
+Hi Thomas,
+
+Thomas Lockhart ha scritto:
+
+> > I have a question about dates.
+> > The Gregorian reform of calendar skiped 10 days on Oct, 1582.
+> > This reform was accepted by Great Britain and Dominions (including
+> > what is now the USA) only in 1752.
+> > If I insert a date that doesn't exist PostgreSQL accepts it.
+> > Should it be considered normal ?
+>
+> As Peter says, this is tricky.
+>
+> Date conventions before the 19th century make for interesting reading,
+> but are not imho consistant enough to warrant coding into a date/time
+> handler.
+>
+> As you probably have noticed, we use Julian date calculations for our
+> date/time support.
+
+I suppose you refer to Julian Day invented by the French scholar
+Joseph Justus Scaliger (1540-1609)
+that probably takes its name from the Scaliger's father,
+the Italian scholar Julius Caesar Scaliger (1484-1558).
+Astronomers have used the Julian period to assign a unique number to
+every day since 1 January 4713 BC. This is the so-called Julian Day
+(JD). JD 0 designates the 24 hours from noon UTC on 1 January 4713 BC
+to noon UTC on 2 January 4713 BC.
+
+Julian Day is different from Julian Date
+
+The Julian calendar was introduced by Julius Caesar in 45 BC. It was
+in common use until the 1582, when countries started changing to the
+Gregorian calendar.
+
+In the Julian calendar, the tropical year is approximated as 365 1/4
+days = 365.25 days. This gives an error of 1 day in approximately 128
+
+and this is why  pope Gregory XIII  in accordance with instructions
+from the Council of Trent reformed the calendar to correct this error.
+
+In the Gregorian calendar, the tropical year is approximated as
+365 + 97 / 400 days = 365.2425 days. Thus it takes approximately 3300
+years for the tropical year to shift one day with respect to the
+Gregorian calendar.
+
+The approximation 365+97/400 is achieved by having 97 leap years
+every 400 years.
+
+The Gregorian calendar has 97 leap years every 400 years:
+
+        Every year divisible by 4 is a leap year.
+        However, every year divisible by 100 is not a leap year.
+        However, every year divisible by 400 is a leap year after all.
+
+So, 1700, 1800, 1900, 2100, and 2200 are not leap years. But 1600,
+2000, and 2400 are leap years.
+
+instead in the Julian calendar only years divisible by 4 are leap years.
+
+The papal bull of February 1582 decreed that 10 days should be dropped
+from October 1582 so that 15 October should follow immediately after
+4 October.
+This was observed in Italy, Poland, Portugal, and Spain. Other Catholic
+countries followed shortly after, but Protestant countries were
+reluctant to change, and the Greek orthodox countries didn't change
+until the start of this century.
+
+The reform was observed by Great Britain and Dominions (including what is
+now the USA)
+in 1752.
+The 2 Sep 1752 was followed by 14 Sep 1752.
+
+This is why unix has the cal 9 1752 like this:
+   September 1752
+ S  M Tu  W Th  F  S
+             1  2 14 15 16
+17 18 19 20 21 22 23
+24 25 26 27 28 29 30
+
+My question is:
+^^^^^^^^^^^^
+
+If SQL92 says:
+
+         (Second Informal Review Draft) ISO/IEC 9075:1992, Database
+         Language SQL- July 30, 1992
+
+5.3 literals
+         22)Within the definition of a <datetime literal>, the <datetime
+            value>s are constrained by the natural rules for dates and
+times
+            according to the Gregorian calendar.
+                                     ^^^^^^^^^^^^^^^
+
+Dates between 1752-09-03 and 1752-09-13.
+Are they valid dates?
+^^^^^^^^^^^^^^^^
+
+> They have the nice property of correctly
+> predicting/calculating any date more recent than something like 4013BC
+> to far into the future, using the assumption that the length of the
+> year is 365.25 days. This is a very recently adopted convention
+> (sometime in the 1800s I had thought, but perhaps it was during the
+> same "reform" in 1752).
+>
+> I've toyed with the idea of implementing a Chinese dynastic calendar,
+> since it seems to be more predictable than historical European
+> calendars.
+
+People's Republic of China uses the Gregorian calendar
+for civil purposes. Chinese calendar is used for determining
+festivals.
+
+The beginnings of the Chinese calendar can be traced back to the 14th
+century BC. Legend has it that the Emperor Huangdi invented the
+calendar in 2637 B
+
+José
+
+
+
index eeb747d..907bbfe 100644 (file)
-<Chapter Id="install">
-<Title>Installation</Title>
+ <Chapter Id="install">
+  <Title>Installation</Title>
 
-<Abstract>
-<Para>
-Complete installation instructions for 
-<ProductName>Postgres</ProductName> v6.5.
-</Para>
-</Abstract>
-
-<Para>
-Before installing <ProductName>Postgres</ProductName>, you may wish to visit
-<ULink url="http://www.postgresql.org">www.postgresql.org</ULink>
-for up to date information, patches, etc.
-</Para>
-
-<Para>
-These installation instructions assume:
-
-<ItemizedList Mark="bullet" Spacing="compact">
-<ListItem>
-<Para>
-Commands are Unix-compatible. See note below.
-</Para>
-</ListItem>
-<ListItem>
-<Para>
-Defaults are used except where noted.
-</Para>
-</ListItem>
-<ListItem>
-<Para>
-User <literal>postgres</literal> is the <ProductName>Postgres</ProductName> superuser.
-</Para>
-</ListItem>
-<ListItem>
-<Para>
-The source path is <filename>/usr/src/pgsql</filename> (other paths are possible).
-</Para>
-</ListItem>
-<ListItem>
-<Para>
-The runtime path is <filename>/usr/local/pgsql</filename> (other paths are possible).
-</Para>
-</ListItem>
-</ItemizedList>
-</para>
-<Para>
-Commands were tested on RedHat Linux version 4.2 using the tcsh shell.
-Except where noted, they will probably work on most systems. Commands
-like <command>ps</command> and <command>tar</command> may vary wildly 
-between platforms on what options you should use.
-<Emphasis>Use common sense</Emphasis> before typing in these commands.
-</Para>
-
-<Para>
-Our Makefiles require GNU <Application>make</Application> (called
-<Quote>gmake</Quote> in this document).  They will <Emphasis>not</Emphasis>
-work with non-GNU <Application>make</Application> programs.  If you
-have GNU <Application>make</Application> installed under the name 
-<Quote>make</Quote> instead of <Quote>gmake</Quote>, then you will use the
-command <command>make</command> instead. That's OK, but
-you need to have the GNU form of <Application>make</Application> to succeed with
-an installation.
-</Para>
-
-<Sect1>
-<Title>Requirements to Run <ProductName>Postgres</ProductName></Title>
-
-<Para>
-Up to date information on supported platforms is at
-<ulink url="http://www.postgresql.org/docs/admin/install.htm">
-http://www.postgresql.org/docs/admin/install.htm</ulink>.
-
- In general, most Unix-compatible
-platforms with modern libraries should be able to run <ProductName>Postgres</ProductName>.
-</para>
-<para>
-Although the minimum required memory for running <ProductName>Postgres</ProductName>
-is as little as 8MB, there are noticable improvements in runtimes for the regression
-tests when expanding memory up to 96MB on a relatively fast dual-processor system
-running X-Windows.
-The rule is you can never have too much memory.
-</para>
-<Para>
-Check that you have sufficient disk space.  You will need about
-      30 Mbytes for <filename>/usr/src/pgsql</filename>, 
-about 5 Mbytes for <filename>/usr/local/pgsql</filename>
-      (excluding your database) and 1 Mbyte for an empty database.
-      The database will temporarily grow to about 20 Mbytes during the
-      regression tests.  You will also need about 3 Mbytes for the
-      distribution tar file.
-</Para>
+  <Abstract>
+   <Para>
+    Complete installation instructions for 
+    <ProductName>Postgres</ProductName> v6.5.
+   </Para>
+  </Abstract>
+
+  <Para>
+   Before installing <ProductName>Postgres</ProductName>, you may wish to visit
+   <ULink url="http://www.postgresql.org">www.postgresql.org</ULink>
+   for up to date information, patches, etc.
+  </Para>
+
+  <Para>
+   These installation instructions assume:
+
+   <ItemizedList Mark="bullet" Spacing="compact">
+    <ListItem>
+     <Para>
+      Commands are Unix-compatible. See note below.
+     </Para>
+    </ListItem>
+    <ListItem>
+     <Para>
+      Defaults are used except where noted.
+     </Para>
+    </ListItem>
+    <ListItem>
+     <Para>
+      User <literal>postgres</literal> is the <ProductName>Postgres</ProductName> superuser.
+     </Para>
+    </ListItem>
+    <ListItem>
+     <Para>
+      The source path is <filename>/usr/src/pgsql</filename> (other paths are possible).
+     </Para>
+    </ListItem>
+    <ListItem>
+     <Para>
+      The runtime path is <filename>/usr/local/pgsql</filename> (other paths are possible).
+     </Para>
+    </ListItem>
+   </ItemizedList>
+  </para>
+
+  <Para>
+   Commands were tested on RedHat Linux version 5.2 using the tcsh shell.
+   Except where noted, they will probably work on most systems. Commands
+   like <command>ps</command> and <command>tar</command> may vary wildly 
+   between platforms on what options you should use.
+   <Emphasis>Use common sense</Emphasis> before typing in these commands.
+  </Para>
+
+  <Para>
+   Our Makefiles require GNU <Application>make</Application> (called
+   <Quote>gmake</Quote> in this document).  They will <Emphasis>not</Emphasis>
+   work with non-GNU <Application>make</Application> programs.  If you
+   have GNU <Application>make</Application> installed under the name 
+   <Quote>make</Quote> instead of <Quote>gmake</Quote>, then you will use the
+   command <command>make</command> instead. That's OK, but
+   you need to have the GNU form of <Application>make</Application> to succeed with
+   an installation.
+  </Para>
+
+  <Sect1>
+   <Title>Requirements to Run <ProductName>Postgres</ProductName></Title>
+
+   <Para>
+    Up to date information on supported platforms is at
+    <ulink url="http://www.postgresql.org/docs/admin/install.htm">
+     http://www.postgresql.org/docs/admin/install.htm</ulink>.
+
+    In general, most Unix-compatible
+    platforms with modern libraries should be able to run
+    <ProductName>Postgres</ProductName>.
+   </para>
+   <para>
+    Although the minimum required memory for running <ProductName>Postgres</ProductName>
+    is as little as 8MB, there are noticable improvements in runtimes for the regression
+    tests when expanding memory up to 96MB on a relatively fast dual-processor system
+    running X-Windows.
+    The rule is you can never have too much memory.
+   </para>
+   <Para>
+    Check that you have sufficient disk space.  You will need about
+    30 Mbytes for <filename>/usr/src/pgsql</filename>, 
+    about 5 Mbytes for <filename>/usr/local/pgsql</filename>
+    (excluding your database) and 1 Mbyte for an empty database.
+    The database will temporarily grow to about 20 Mbytes during the
+    regression tests.  You will also need about 3 Mbytes for the
+    distribution tar file.
+   </Para>
 
-<Para>
-      We therefore recommend that during installation and testing you
-      have well over 20 Mbytes free under <filename>/usr/local</filename> and another 25 Mbytes
-      free on the disk partition containing your database.  Once you
-      delete the source files, tar file and regression database, you
-      will need 2 Mbytes for <filename>/usr/local/pgsql</filename>, 1 Mbyte for the empty
-      database, plus about five times the space you would require to
-      store your database data in a flat file.
-</Para>
+   <Para>
+    We therefore recommend that during installation and testing you
+    have well over 20 Mbytes free under <filename>/usr/local</filename> and another 25 Mbytes
+    free on the disk partition containing your database.  Once you
+    delete the source files, tar file and regression database, you
+    will need 2 Mbytes for <filename>/usr/local/pgsql</filename>, 1 Mbyte for the empty
+    database, plus about five times the space you would require to
+    store your database data in a flat file.
+   </Para>
 
-<Para>
-      To check for disk space, use 
-<programlisting>
+   <Para>
+    To check for disk space, use 
+    <programlisting>
 $ df -k
-</programlisting>
-</para>
-</Sect1>
+    </programlisting>
+   </para>
+  </Sect1>
 
 <Sect1>
 <Title>Installation Procedure</Title>
@@ -1300,95 +1302,30 @@ For more information on the various support mailing lists.
 </Para>
 </Sect1>
 
-<Sect1>
-<Title>Porting Notes</Title>
+  <Sect1>
+   <Title>Porting Notes</Title>
 
-<Note>
-<Para>
-Check for any platform-specific FAQs in the <filename>doc/</filename> directory of
-the source distribution. For some ports, the notes below may be out of date.
-</Para>
-</Note>
-
-  <Sect2>
-   <Title>Ultrix4.x</Title>
-   
-   <para>
-    <note>
-     <para>
-      There have been no recent reports of Ultrix usage with <productname>Postgres</productname>.
-     </para>
-    </note>
-   </para>
-   <para>
-    You need to install the libdl-1.1 package since Ultrix 4.x doesn't
-    have a dynamic loader. It's available in
-    s2k-ftp.CS.Berkeley.EDU:pub/personal/andrew/libdl-1.1.tar.Z
+   <Para>
+    Check for any platform-specific FAQs in the <filename>doc/</filename> directory of
+    the source distribution.
    </Para>
-  </Sect2>
-  
-  <Sect2>
-   <Title>Linux</Title>
-   
-   <Sect3>
-    <Sect3Info>
-     <Author>
-      <FirstName>Thomas G.</FirstName>
-      <SurName>Lockhart</SurName>
-     </Author>
-     <Date>1998-02-19</Date>
-    </Sect3Info>
-    <Title>Linux ELF</Title>
-    
-    <Para>
-     The regression test reference machine is
-     a linux-2.0.30/libc-5.3.12/RedHat-4.2 installation running on a dual processor i686.
-     The linux-elf port installs cleanly. See the Linux FAQ for more details.
-    </Para>
-   </Sect3>
-
-<Sect3>
-<Sect3Info>
-<Date>1995-05-11</Date>
-</Sect3Info>
-<Title>Linux a.out</Title>
-
-<Para>
-        For non-ELF Linux, the dld library MUST be obtained and installed on
-        the system. It enables dynamic link loading capability to the <ProductName>Postgres</ProductName>
-        port. The dld library can be obtained from the sunsite linux
-        distributions. The current name is dld-3.2.5.
-<ULink url="sneaker@powergrid.electriciti.com">Jalon Q. Zimmerman</ULink>
-</Para>
-</Sect3>
-</Sect2>
-
-<Sect2>
-<Title>BSD/OS</Title>
-
-<Para>
-        For BSD/OS 2.0 and 2.01, you will need to get the GNU dld library.
-</Para>
-</Sect2>
-
-<Sect2>
-<Title>NeXT</Title>
-
-<Para>
-        The NeXT port for v1.09 was supplied by 
-<ULink url="mailto:tom@basil.icce.rug.nl">Tom R. Hageman</ULink>.
-        It requires a SysV IPC emulation library and header files for
-        shared libary and semaphore stuff.   Tom just happens to sell such
-        a product so contact him for information.  He has also indicated that
-        binary releases of <ProductName>Postgres</ProductName> for NEXTSTEP will be made available to
-        the general public.  Contact Info@RnA.nl for information.
-</para>
-<Para>
-We have no recent reports of successful NeXT installations (as of v6.2.1). 
-However, the client-side libraries should work even
-if the backend is not supported.
-</Para>
-</Sect2>
-</Sect1>
+  </sect1>
 
 </Chapter>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:nil
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"./reference.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
+sgml-local-ecat-files:nil
+End:
+-->
diff --git a/doc/src/sgml/layout.sgml b/doc/src/sgml/layout.sgml
new file mode 100644 (file)
index 0000000..398b5f9
--- /dev/null
@@ -0,0 +1,78 @@
+<chapter id="layout">
+<Title>System Layout</Title>
+
+<Para>
+<Figure Id="ADMIN-LAYOUT">
+<Title><ProductName>Postgres</ProductName> file layout</Title>
+<Graphic Align="center" FileRef="layout.gif" Format="GIF"></Graphic>
+</Figure>
+
+<XRef LinkEnd="ADMIN-LAYOUT" EndTerm="ADMIN-LAYOUT">
+shows how the <ProductName>Postgres</ProductName>  distribution  is  laid
+     out  when installed in the default way. For simplicity,
+     we will assume that <ProductName>Postgres</ProductName>
+ has been installed in  the
+     directory  <filename>/usr/local/pgsql</filename>.   Therefore, wherever
+     you see the directory <filename>/usr/local/pgsql</filename> you  should
+     substitute  the name of the directory where
+ <ProductName>Postgres</ProductName> is
+     actually installed.
+     All <ProductName>Postgres</ProductName> commands are installed
+     in  the  directory
+     <filename>/usr/local/pgsql/bin</filename>.   Therefore,  you should add
+     this directory to your shell command path.  If you  use
+     a variant of the Berkeley C shell, such as csh or tcsh,
+     you would add
+<ProgramListing>
+set path = ( /usr/local/pgsql/bin path )
+</ProgramListing>
+     in the .login file in your home directory.  If you  use
+     a  variant  of  the  Bourne  shell, such as sh, ksh, or
+     bash, then you would add
+<ProgramListing>
+PATH=/usr/local/pgsql/bin:$PATH
+export PATH
+</ProgramListing>
+     to the .profile file in your home directory.
+     From now on, we will assume that  you  have  added  the
+     <ProductName>Postgres</ProductName>  bin  directory to your path.
+     In addition, we
+     will make frequent reference to "setting a shell  
+     variable"  or  "setting an environment variable" throughout
+     this document.  If you did  not  fully  understand  the
+     last  paragraph  on  modifying  your  search  path, you
+     should consult the UNIX manual pages that describe your
+     shell before going any further.
+</Para>
+
+<Para>
+If you have not set things up in the
+default  way,  you may have some more work to do.  
+For example, if the database server machine is a remote machine, you
+will need to set the <envar>PGHOST</envar> environment variable to the name
+of the database server machine.   The  environment  variable
+<envar>PGPORT</envar> may also have to be set.  The bottom line is this: if
+you try to start an application  program  and  it  complains
+that it cannot connect to the <Application>postmaster</Application>,
+you must go back and make sure that your
+environment is properly set up.
+</Para>
+
+</Chapter>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:nil
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"./reference.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
+sgml-local-ecat-files:nil
+End:
+-->
index 434cf68..a95cf03 100644 (file)
@@ -1,45 +1,45 @@
-<Chapter Id="pg-options">
-<DocInfo>
-<AuthorGroup>
-<Author>
-<FirstName>Massimo</FirstName>
-<Surname>Dal Zotto</Surname>
-</Author>
-</AuthorGroup>
-<Date>Transcribed 1998-10-16</Date>
-</DocInfo>
-
-<Title>Using pg_options</Title>
-
-<Para>
-<Note>
-<Para>
-Contributed by <ULink url="mailto:dz@cs.unitn.it">Massimo Dal Zotto</ULink>
-</Para>
-</Note>
-</para>
-<Para>
-The optional file <filename>data/pg_options</filename> contains runtime
-options used by the backend to control trace messages and other backend
-tunable parameters.
-What makes this file interesting is the fact that it is re-read by a backend
-when it receives a SIGHUP signal, making thus possible to change run-time
-options on the fly without needing to restart 
-<productname>Postgres</productname>.
-The options specified in this file may be debugging flags used by the trace
-package (<filename>backend/utils/misc/trace.c</filename>) or numeric
-parameters which can be used by the backend to control its behaviour.
-New options and parameters must be defined in
-<filename>backend/utils/misc/trace.c</filename> and
-<filename>backend/include/utils/trace.h</filename>.
-</para>
-<Para>
-For example suppose we want to add conditional trace messages and a tunable
-numeric parameter to the code in file <filename>foo.c</filename>.
-All we need to do is to add the constant TRACE_FOO and OPT_FOO_PARAM into
-<filename>backend/include/utils/trace.h</filename>:
-
-<programlisting>
+ <Chapter Id="pg-options">
+  <DocInfo>
+   <AuthorGroup>
+    <Author>
+     <FirstName>Massimo</FirstName>
+     <Surname>Dal Zotto</Surname>
+    </Author>
+   </AuthorGroup>
+   <Date>Transcribed 1998-10-16</Date>
+  </DocInfo>
+
+  <Title>pg_options</Title>
+
+  <Para>
+   <Note>
+    <Para>
+     Contributed by <ULink url="mailto:dz@cs.unitn.it">Massimo Dal Zotto</ULink>
+    </Para>
+   </Note>
+  </para>
+  <Para>
+   The optional file <filename>data/pg_options</filename> contains runtime
+   options used by the backend to control trace messages and other backend
+   tunable parameters.
+   What makes this file interesting is the fact that it is re-read by a backend
+   when it receives a SIGHUP signal, making thus possible to change run-time
+   options on the fly without needing to restart 
+   <productname>Postgres</productname>.
+   The options specified in this file may be debugging flags used by the trace
+   package (<filename>backend/utils/misc/trace.c</filename>) or numeric
+   parameters which can be used by the backend to control its behaviour.
+   New options and parameters must be defined in
+   <filename>backend/utils/misc/trace.c</filename> and
+   <filename>backend/include/utils/trace.h</filename>.
+  </para>
+  <Para>
+   For example suppose we want to add conditional trace messages and a tunable
+   numeric parameter to the code in file <filename>foo.c</filename>.
+   All we need to do is to add the constant TRACE_FOO and OPT_FOO_PARAM into
+   <filename>backend/include/utils/trace.h</filename>:
+
+   <programlisting>
 /* file trace.h */
 enum pg_option_enum {
     ...
@@ -48,23 +48,23 @@ enum pg_option_enum {
 
     NUM_PG_OPTIONS              /* must be the last item of enum */
 };
-</programlisting>
+   </programlisting>
 
-and a corresponding line in <filename>backend/utils/misc/trace.c</filename>:
+   and a corresponding line in <filename>backend/utils/misc/trace.c</filename>:
 
-<programlisting>
+   <programlisting>
 /* file trace.c */
 static char *opt_names[] = {
     ...
     "foo",                     /* trace foo functions */
     "fooparam"                         /* foo tunable parameter */
 };
-</programlisting>
+   </programlisting>
 
-Options in the two files must be specified in exactly the same order.
-In the foo source files we can now reference the new flags with:
+   Options in the two files must be specified in exactly the same order.
+   In the foo source files we can now reference the new flags with:
 
-<programlisting>
+   <programlisting>
 /* file foo.c */
 #include "trace.h"
 #define foo_param pg_options[OPT_FOO_PARAM]
@@ -77,54 +77,54 @@ foo_function(int x, int y)
         do_more_foo(x, y);
     }
 }
-</programlisting>
-</para>
-<para>
-Existing files using private trace flags can be changed by simply adding
-the following code:
+   </programlisting>
+  </para>
+  <para>
+   Existing files using private trace flags can be changed by simply adding
+   the following code:
 
-<programlisting>
+   <programlisting>
 #include "trace.h"
 /* int my_own_flag = 0; -- removed */
 #define my_own_flag pg_options[OPT_MY_OWN_FLAG]
-</programlisting>
-</para>
-<para>
-All pg_options are initialized to zero at backend startup. If we need a
-different default value we must add some initialization code at the beginning
-of <function>PostgresMain</function>.
+   </programlisting>
+  </para>
+  <para>
+   All pg_options are initialized to zero at backend startup. If we need a
+   different default value we must add some initialization code at the beginning
+   of <function>PostgresMain</function>.
 
-Now we can set the foo_param and enable foo trace by writing values into the
-<filename>data/pg_options</filename> file:
+   Now we can set the foo_param and enable foo trace by writing values into the
+   <filename>data/pg_options</filename> file:
 
-<programlisting>
+   <programlisting>
 # file pg_options
 ...
 foo=1
 fooparam=17
-</programlisting>
-</para>
-<para>
-The new options will be read by all new backends when they are started.
-To make effective the changes for all running backends we need to send a
-SIGHUP to the postmaster. The signal will be automatically sent to all the
-backends. We can also activate the changes only for a specific backend by
-sending the SIGHUP directly to it.
-</para>
-<para>
-pg_options can also be specified with the <option>-T</option> switch of 
-<productname>Postgres</productname>:
-
-<programlisting>
+   </programlisting>
+  </para>
+  <para>
+   The new options will be read by all new backends when they are started.
+   To make effective the changes for all running backends we need to send a
+   SIGHUP to the postmaster. The signal will be automatically sent to all the
+   backends. We can also activate the changes only for a specific backend by
+   sending the SIGHUP directly to it.
+  </para>
+  <para>
+   pg_options can also be specified with the <option>-T</option> switch of 
+   <productname>Postgres</productname>:
+
+   <programlisting>
 postgres <replaceable>options</replaceable> -T "verbose=2,query,hostlookup-"
-</programlisting>
-</para>
-<Para>
-The functions used for printing errors and debug messages can now make use
-of the <citetitle>syslog(2)</citetitle> facility. Message printed to stdout
-or stderr are prefixed by a timestamp containing also the backend pid:
-
-<programlisting>
+   </programlisting>
+  </para>
+  <Para>
+   The functions used for printing errors and debug messages can now make use
+   of the <citetitle>syslog(2)</citetitle> facility. Message printed to stdout
+   or stderr are prefixed by a timestamp containing also the backend pid:
+   
+   <programlisting>
 #timestamp          #pid    #message
 980127.17:52:14.173 [29271] StartTransactionCommand
 980127.17:52:14.174 [29271] ProcessUtility: drop table t;
@@ -134,518 +134,103 @@ or stderr are prefixed by a timestamp containing also the backend pid:
 980127.19:52:14.292 [29286] Async_NotifyFrontEnd
 980127.19:52:14.413 [29286] Async_NotifyFrontEnd done
 980127.19:52:14.466 [29286] Async_NotifyHandler done
-</programlisting>
-</para>
-<para>
-This format improves readability of the logs and allows people to understand
-exactly which backend is doing what and at which time. It also makes
-easier to write simple awk or perl scripts which monitor the log to
-detect database errors or problem, or to compute transaction time statistics.
-</para>
-<para>
-Messages printed to syslog use the log facility LOG_LOCAL0.
-The use of syslog can be controlled with the syslog pg_option.
-Unfortunately many functions call directly <function>printf()</function>
-to print their messages to stdout or stderr and this output can't be
-redirected to syslog or have timestamps in it. 
-It would be advisable that all calls to printf would be replaced with the
-PRINTF macro and output to stderr be changed to use EPRINTF instead so that
-we can control all output in a uniform way.
-</Para>
-
-<Para>
-The new pg_options mechanism is more convenient than defining new backend
-option switches because:
-
-<ItemizedList Mark="bullet" Spacing="compact">
-<ListItem>
-<Para>
-we don't have to define a different switch for each thing we want to control.
-All options are defined as keywords in an external file stored in the data
-directory.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-we don't have to restart <productname>Postgres</productname> to change
- the setting of some option.
-Normally backend options are specified to the postmaster and passed to each
-backend when it is started. Now they are read from a file.
-</Para>
-</ListItem>
-
-<ListItem>
-<Para>
-we can change options on the fly while a backend is running. We can thus
-investigate some problem by activating debug messages only when the problem
-appears. We can also try different values for tunable parameters.
-</Para>
-</ListItem>
-</ItemizedList>
-
-The format of the <filename>pg_options</filename> file is as follows:
-
-<programlisting>
+   </programlisting>
+  </para>
+  <para>
+   This format improves readability of the logs and allows people to understand
+   exactly which backend is doing what and at which time. It also makes
+   easier to write simple awk or perl scripts which monitor the log to
+   detect database errors or problem, or to compute transaction time statistics.
+  </para>
+  <para>
+   Messages printed to syslog use the log facility LOG_LOCAL0.
+   The use of syslog can be controlled with the syslog pg_option.
+   Unfortunately many functions call directly <function>printf()</function>
+   to print their messages to stdout or stderr and this output can't be
+   redirected to syslog or have timestamps in it. 
+   It would be advisable that all calls to printf would be replaced with the
+   PRINTF macro and output to stderr be changed to use EPRINTF instead so that
+   we can control all output in a uniform way.
+  </Para>
+
+  <Para>
+   The new pg_options mechanism is more convenient than defining new backend
+   option switches because:
+
+   <ItemizedList Mark="bullet" Spacing="compact">
+    <ListItem>
+     <Para>
+      we don't have to define a different switch for each thing we want to control.
+      All options are defined as keywords in an external file stored in the data
+      directory.
+     </Para>
+    </ListItem>
+
+    <ListItem>
+     <Para>
+      we don't have to restart <productname>Postgres</productname> to change
     the setting of some option.
+      Normally backend options are specified to the postmaster and passed to each
+      backend when it is started. Now they are read from a file.
+     </Para>
+    </ListItem>
+
+    <ListItem>
+     <Para>
+      we can change options on the fly while a backend is running. We can thus
+      investigate some problem by activating debug messages only when the problem
+      appears. We can also try different values for tunable parameters.
+     </Para>
+    </ListItem>
+   </ItemizedList>
+
+   The format of the <filename>pg_options</filename> file is as follows:
+
+   <programlisting>
 # <replaceable>comment</replaceable>
 <replaceable>option</replaceable>=<replaceable class="parameter">integer_value</replaceable>  # set value for <replaceable>option</replaceable>
 <replaceable>option</replaceable>                # set <replaceable>option</replaceable> = 1
 <replaceable>option</replaceable>+               # set <replaceable>option</replaceable> = 1
 <replaceable>option</replaceable>-               # set <replaceable>option</replaceable> = 0
-</programlisting>
-
-Note that <replaceable class="parameter">keyword</replaceable> can also be
-an abbreviation of the option name defined in
-<filename>backend/utils/misc/trace.c</filename>.
-</Para>
-
-<Para>
-The options currently defined in
-<filename>backend/utils/misc/trace.c</filename> are the following:
-
-<variablelist>
-<varlistentry>
-<term>
-all
-</term>
-<listitem>
-<para>
-Global trace flag. Allowed values are:
-</para>
-
-<variablelist>
-<varlistentry>
-<term>
-0
-</term>
-<listitem>
-<para>
-Trace messages enabled individually
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>
-1
-</term>
-<listitem>
-<para>
-Enable all trace messages
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>
--1
-</term>
-<listitem>
-<para>
-Disable all trace messages
-</para>
-</listitem>
-</varlistentry>
-
-</variablelist>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>
-verbose
-</term>
-<listitem>
-<para>
-Verbosity flag. Allowed values are:
-</para>
-
-<variablelist>
-<varlistentry>
-<term>
-0
-</term>
-<listitem>
-<para>
-No messages. This is the default.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>
-1
-</term>
-<listitem>
-<para>
-Print information messages.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>
-2
-</term>
-<listitem>
-<para>
-Print more information messages.
-</para>
-</listitem>
-</varlistentry>
-
-</variablelist>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>
-query
-</term>
-<listitem>
-<para>
-Query trace flag. Allowed values are:
-</para>
-
-<variablelist>
-<varlistentry>
-<term>
-0
-</term>
-<listitem>
-<para>
-Don't print query.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>
-1
-</term>
-<listitem>
-<para>
-Print a condensed query in one line.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>
-4
-</term>
-<listitem>
-<para>
-Print the full query.
-</para>
-</listitem>
-</varlistentry>
-
-</variablelist>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>
-plan
-</term>
-<listitem>
-<para>
-Print query plan.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>
-parse
-</term>
-<listitem>
-<para>
-Print parser output.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>
-rewritten
-</term>
-<listitem>
-<para>
-Print rewritten query.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>
-parserstats
-</term>
-<listitem>
-<para>
-Print parser statistics.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>
-plannerstats
-</term>
-<listitem>
-<para>
-Print planner statistics.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>
-executorstats
-</term>
-<listitem>
-<para>
-Print executor statistics.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>
-shortlocks
-</term>
-<listitem>
-<para>
-Currently unused but needed to enable features in the future.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>
-locks
-</term>
-<listitem>
-<para>
-Trace locks.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>
-userlocks
-</term>
-<listitem>
-<para>
-Trace user locks.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>
-spinlocks
-</term>
-<listitem>
-<para>
-Trace spin locks.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>
-notify
-</term>
-<listitem>
-<para>
-Trace notify functions.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>
-malloc
-</term>
-<listitem>
-<para>
-Currently unused.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>
-palloc
-</term>
-<listitem>
-<para>
-Currently unused.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>
-lock_debug_oidmin
-</term>
-<listitem>
-<para>
-Minimum relation oid traced by locks.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>
-lock_debug_relid
-</term>
-<listitem>
-<para>
-oid, if not zero, of relation traced by locks.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>
-lock_read_priority
-</term>
-<listitem>
-<para>
-Currently unused.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>
-deadlock_timeout
-</term>
-<listitem>
-<para>
-Deadlock check timer.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>
-syslog
-</term>
-<listitem>
-<para>
-syslog flag. Allowed values are:
-</para>
-
-<variablelist>
-<varlistentry>
-<term>
-0
-</term>
-<listitem>
-<para>
-Messages to stdout/stderr.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>
-1
-</term>
-<listitem>
-<para>
-Messages to stdout/stderr and syslog.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>
-2
-</term>
-<listitem>
-<para>
-Messages only to syslog.
-</para>
-</listitem>
-</varlistentry>
-
-</variablelist>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>
-hostlookup
-</term>
-<listitem>
-<para>
-Enable hostname lookup in ps_status.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>
-showportnumber
-</term>
-<listitem>
-<para>
-Show port number in ps_status.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>
-notifyunlock
-</term>
-<listitem>
-<para>
-Unlock of pg_listener after notify.
-</para>
-</listitem>
-</varlistentry>
-
-<varlistentry>
-<term>
-notifyhack
-</term>
-<listitem>
-<para>
-Remove duplicate tuples from pg_listener.
-</para>
-</listitem>
-</varlistentry>
-
-</variablelist>
-
-For example my pg_options file contains the following values:
-
-<programlisting>
-verbose=2
-query
-hostlookup
-showportnumber
-</programlisting>
-
-</Para>
-
-
-<Para>
-Some of the existing code using private variables and option switches has
-been changed to make use of the pg_options feature, mainly in
-<filename>postgres.c</filename>. It would be advisable to modify
-all existing code
-in this way, so that we can get rid of many of the switches on
-the <productname>Postgres</productname> command line 
-and can have more tunable options 
-with a unique place to put option values.
-</Para>
-
-</Chapter>
+   </programlisting>
+
+   Note that <replaceable class="parameter">keyword</replaceable> can also be
+   an abbreviation of the option name defined in
+   <filename>backend/utils/misc/trace.c</filename>.
+  </Para>
+
+  <para>
+   Refer to <citetitle>The Administrator's Guide</citetitle> chapter
+   on runtime options for a complete list of currently supported
+   options.
+  </para>
+
+  <Para>
+   Some of the existing code using private variables and option switches has
+   been changed to make use of the pg_options feature, mainly in
+   <filename>postgres.c</filename>. It would be advisable to modify
+   all existing code
+   in this way, so that we can get rid of many of the switches on
+   the <productname>Postgres</productname> command line 
+   and can have more tunable options 
+   with a unique place to put option values.
+  </Para>
+
+ </Chapter>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:nil
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"./reference.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
+sgml-local-ecat-files:nil
+End:
+-->
diff --git a/doc/src/sgml/pgaccess.sgml b/doc/src/sgml/pgaccess.sgml
deleted file mode 100644 (file)
index 90e02cd..0000000
+++ /dev/null
@@ -1,8 +0,0 @@
-<Chapter Id="pgaccess">
-<Title><Command>pgaccess</Command></Title>
-
-<Para>
-This section needs to be written. Volunteers?
-</Para>
-
-</Chapter>
index 5d7e1e6..1db1f03 100644 (file)
@@ -1,11 +1,19 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.21 1999/05/04 02:19:20 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.22 1999/05/20 05:39:27 thomas Exp $
 
 Postgres integrated documentation.
 Other subset docs should be copied and shrunk from here.
 thomas 1998-02-23
 
 $Log: postgres.sgml,v $
+Revision 1.22  1999/05/20 05:39:27  thomas
+Rearrange and consolidate the Admin Guide.
+Add reference pages for utilities and remove standalone chapters for same.
+Add material for an appendix on date/time properties, but not yet
+ integrated with the User's Guide.
+Break up the former chapter on pg_options
+ into Admin and Programmer's Guides.
+
 Revision 1.21  1999/05/04 02:19:20  thomas
 Include chapters on security and an intro to SQL.
 
@@ -105,7 +113,6 @@ Move SQL reference pages up into the User's Guide.
 <!entity install  SYSTEM "install.sgml">
 <!entity installw SYSTEM "install-win32.sgml">
 <!entity intro-ag SYSTEM "intro-ag.sgml">
-<!entity options  SYSTEM "pg_options.sgml">
 <!entity ports    SYSTEM "ports.sgml">
 <!entity runtime  SYSTEM "runtime.sgml">
 <!entity recovery SYSTEM "recovery.sgml">
@@ -146,6 +153,7 @@ Move SQL reference pages up into the User's Guide.
 <!entity contacts SYSTEM "contacts.sgml">
 <!entity docguide SYSTEM "docguide.sgml">
 <!entity geqo     SYSTEM "geqo.sgml">
+<!entity options  SYSTEM "pg_options.sgml">
 <!entity page     SYSTEM "page.sgml">
 <!entity protocol SYSTEM "protocol.sgml">
 <!entity signals  SYSTEM "signals.sgml">
@@ -157,7 +165,7 @@ Move SQL reference pages up into the User's Guide.
 
  <Title>PostgreSQL</Title>
  <BookInfo>
-  <ReleaseInfo>Covering v6.4 for general release</ReleaseInfo>
+  <ReleaseInfo>Covering v6.5 for general release</ReleaseInfo>
   <BookBiblio>
    <AuthorGroup>
     <CorpAuthor>The PostgreSQL Development Team</CorpAuthor>
@@ -180,7 +188,7 @@ Move SQL reference pages up into the User's Guide.
     <AuthorInitials>TGL</AuthorInitials>
 -->
 
-   <Date>(last updated 1998-02-23)</Date>
+   <Date>(last updated 1998-05-19)</Date>
   </BookBiblio>
 
   <LegalNotice>
@@ -242,21 +250,18 @@ Your name here...
    </Para>
   </PartIntro>
 
-  &sql;
-   &environ;
-  &manage;
-  &syntax;
+   &sql;
+   &syntax;
    &datatype;
    &oper;
    &func;
    &typeconv;
-  &keys;
+   &keys;
    &array;
    &inherit;
-   &query-ug;
+   &environ;
+   &manage;
    &storage;
-   &psql;
-   &pgaccess;
    &commands;
  </Part>
 
@@ -274,7 +279,6 @@ Your name here...
    &installw;
    &runtime;
    &security;
-   &options;
    &start-ag;
    &recovery;
    &regress;
@@ -331,6 +335,7 @@ Your name here...
    </Para>
   </PartIntro>
    &arch-dev;
+   &options;
    &geqo;
    &protocol;
    &signals;
index b71dd86..c29876f 100644 (file)
@@ -1,10 +1,18 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.13 1999/04/08 13:28:22 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.14 1999/05/20 05:39:27 thomas Exp $
 
 Postgres Programmer's Guide.
 - thomas 1998-10-27
 
 $Log: programmer.sgml,v $
+Revision 1.14  1999/05/20 05:39:27  thomas
+Rearrange and consolidate the Admin Guide.
+Add reference pages for utilities and remove standalone chapters for same.
+Add material for an appendix on date/time properties, but not yet
+ integrated with the User's Guide.
+Break up the former chapter on pg_options
+ into Admin and Programmer's Guides.
+
 Revision 1.13  1999/04/08 13:28:22  thomas
 Add emacs editor hints to bottom of file.
 
@@ -80,6 +88,7 @@ Bigger updates to the installation instructions (install and config).
 <!entity jdbc     SYSTEM "jdbc.sgml">
 <!entity xplang   SYSTEM "xplang.sgml">
 
+<!-- developer's guide -->
 <!entity arch-dev SYSTEM "arch-dev.sgml">
 <!entity biblio   SYSTEM "biblio.sgml">
 <!entity bki      SYSTEM "bki.sgml">
@@ -87,6 +96,7 @@ Bigger updates to the installation instructions (install and config).
 <!entity contacts SYSTEM "contacts.sgml">
 <!entity docguide SYSTEM "docguide.sgml">
 <!entity geqo     SYSTEM "geqo.sgml">
+<!entity options  SYSTEM "pg_options.sgml">
 <!entity page     SYSTEM "page.sgml">
 <!entity protocol SYSTEM "protocol.sgml">
 <!entity signals  SYSTEM "signals.sgml">
@@ -96,23 +106,23 @@ Bigger updates to the installation instructions (install and config).
 
 <!-- Title information -->
 
-<Title>PostgreSQL Programmer's Guide</Title>
-<BookInfo>
-    <ReleaseInfo>Covering v6.4 for general release</ReleaseInfo>
-    <BookBiblio>
-    <AuthorGroup>
-      <CorpAuthor>The PostgreSQL Development Team</CorpAuthor>
-    </AuthorGroup>
+ <Title>PostgreSQL Programmer's Guide</Title>
+ <BookInfo>
+  <ReleaseInfo>Covering v6.5 for general release</ReleaseInfo>
+  <BookBiblio>
+   <AuthorGroup>
+    <CorpAuthor>The PostgreSQL Development Team</CorpAuthor>
+   </AuthorGroup>
 <!-- editor in authorgroup is not supported
     <AuthorGroup>
 -->
-      <Editor>
-        <FirstName>Thomas</FirstName>
-        <SurName>Lockhart</SurName>
-        <Affiliation>
-          <OrgName>Caltech/JPL</OrgName>
-        </Affiliation>
-      </Editor>
+   <Editor>
+    <FirstName>Thomas</FirstName>
+    <SurName>Lockhart</SurName>
+    <Affiliation>
+     <OrgName>Caltech/JPL</OrgName>
+    </Affiliation>
+   </Editor>
 <!--
     </AuthorGroup>
 -->
@@ -121,17 +131,17 @@ Bigger updates to the installation instructions (install and config).
     <AuthorInitials>TGL</AuthorInitials>
 -->
 
-    <Date>(last updated 1998-10-27)</Date>
-    </BookBiblio>
+   <Date>(last updated 1999-05-19)</Date>
+  </BookBiblio>
 
-<LegalNotice>
-<Para>
-<ProductName>PostgreSQL</ProductName> is copyright (C) 1998 
-by the Postgres Global Development Group.
-</Para>
-</LegalNotice>
+  <LegalNotice>
+   <Para>
+    <ProductName>PostgreSQL</ProductName> is copyright (&copy;) 1998-9
+    by the Postgres Global Development Group.
+   </Para>
+  </LegalNotice>
 
-</BookInfo>
+ </BookInfo>
 
 <!--
 <TOC> </TOC>
@@ -146,33 +156,33 @@ Your name here...
 </Dedication>
 -->
 
-<Preface id="preface">
-<Title>Summary</Title>
-
-<Para>
-<ProductName>Postgres</ProductName>, 
- developed originally in the UC Berkeley Computer Science Department,
- pioneered many of the object-relational concepts
- now becoming available in some commercial databases.
-It provides SQL92/SQL3 language support,
- transaction integrity, and type extensibility.
- <ProductName>PostgreSQL</ProductName> is a public-domain, 
- open source descendant of this original Berkeley code.
-</Para>
-</Preface>
-
-&intro-pg;
-&arch-pg;
-&extend;
-&xfunc;
-&xtypes;
-&xoper;
-&xaggr;
-&rules;
-&xindex;
-&gist;
-&xplang;
-&dfunc;
+ <Preface id="preface">
+  <Title>Summary</Title>
+
+  <Para>
+   <ProductName>Postgres</ProductName>, 
  developed originally in the UC Berkeley Computer Science Department,
  pioneered many of the object-relational concepts
  now becoming available in some commercial databases.
+   It provides SQL92/SQL3 language support,
  transaction integrity, and type extensibility.
  <ProductName>PostgreSQL</ProductName> is a public-domain, 
  open source descendant of this original Berkeley code.
+  </Para>
+ </Preface>
+
+  &intro-pg;
+  &arch-pg;
+  &extend;
+  &xfunc;
+  &xtypes;
+  &xoper;
+  &xaggr;
+  &rules;
+  &xindex;
+  &gist;
+  &xplang;
+  &dfunc;
 
 <!-- reference -->
 
@@ -183,33 +193,34 @@ Disable it until we put in some info.
 &func-ref;
 -->
 
-&trigger;
-&spi;
-&lobj;
-&libpq;
-&libpqpp;
-&libpgtcl;
-&ecpg;
-&odbc;
-&jdbc;
-
+  &trigger;
+  &spi;
+  &lobj;
+  &libpq;
+  &libpqpp;
+  &libpgtcl;
+  &ecpg;
+  &odbc;
+  &jdbc;
 <!-- development -->
-
-&arch-dev; 
-&geqo;
-&protocol;
-&signals;
-&compiler;
-&bki;
-&page;
+  &arch-dev; 
+  &options;
+  &geqo;
+  &protocol;
+  &signals;
+  &compiler;
+  &bki;
+  &page;
 
 <!-- appendices -->
 
-&docguide;
+  &docguide;
 <!--
 &contacts;
 -->
-&biblio;
+  &biblio;
 
 <!--
 <index id="index">
diff --git a/doc/src/sgml/psql.sgml b/doc/src/sgml/psql.sgml
deleted file mode 100644 (file)
index bbb8fab..0000000
+++ /dev/null
@@ -1,45 +0,0 @@
-<Chapter Id="psql">
-<Title><Command>psql</Command></Title>
-
-<Para>
-This section needs to be converted from the original psql man page. Volunteers?
-</Para>
-
-<Tip>
-<Para>
-To change the paging behavior of your results, set/unset your PAGER environment variable.
-</Para>
-</Tip>
-
-<Sect1>
-<Title>Paging To Screen</Title>
-
-<Note>
-<Title>Author</Title>
-<Para>
-From Brett McCormick on the mailing list 1998-04-04.
-</Para>
-</Note>
-
-<Para>
-To affect the paging behavior of your <Command>psql</Command> output,
-set or unset your PAGER environment variable.  I always have to set mine
-before it will pause.  And of course you have to do this before
-starting the program.
-</para>
-
-<Para>
-In csh/tcsh or other C shells:
-
-<ProgramListing>
-  unsetenv PAGER
-</ProgramListing>
-
-while in sh/bash or other Bourne shells:
-
-<ProgramListing>
-  unset PAGER
-</ProgramListing>
-</para>
-</sect1>
-</Chapter>
diff --git a/doc/src/sgml/query-ug.sgml b/doc/src/sgml/query-ug.sgml
deleted file mode 100644 (file)
index 3685dbf..0000000
+++ /dev/null
@@ -1,363 +0,0 @@
-<Chapter Id="query-ug">
-<TITLE>The Query Language</TITLE>
-
-<Para>
-<Note>
-<Para>
-This chapter must go into depth on each area of the query language. 
-Currently a copy of the tutorial.
-- thomas 1998-01-12
-</Para>
-</Note>
-</Para>
-
-<Para>
-     The  <ProductName>Postgres</ProductName>  query language is a variant of
- <Acronym>SQL3</Acronym>. It
-     has many extensions such as an extensible type  system,
-     inheritance,  functions and production rules. Those are
-     features carried over from the original <ProductName>Postgres</ProductName>  
-query
-     language,  <ProductName>PostQuel</ProductName>.  
-This section provides an overview
-     of how to use <ProductName>Postgres</ProductName> <Acronym>SQL</Acronym>
-  to  perform  simple  operations.
-     This manual is only intended to give you an idea of our
-     flavor of <Acronym>SQL</Acronym> and is in no way a complete  tutorial  on
-     <Acronym>SQL</Acronym>.  Numerous  books  have  been  written  on <Acronym>SQL</Acronym>. For
-     instance, consult <xref linkend="MELT93" endterm="MELT93-full"> or 
-     <xref linkend="DATE97" endterm="DATE97-full">. You should also
-     be  aware  that  some features of <ProductName>Postgres</ProductName>
-are not part of the <Acronym>ANSI</Acronym> standard.
-</Para>
-
-<Sect1>
-<Title>Concepts</Title>
-
-<Para>
-     The fundamental notion in <ProductName>Postgres</ProductName> 
-is that of a  class,
-     which  is a named collection of object instances.  Each
-     instance has the same collection of  named  attributes,
-     and each attribute is of a specific type.  Furthermore,
-     each instance has a permanent <FirstTerm>object  
-identifier</FirstTerm> (<Acronym>OID</Acronym>)
-     that  is  unique  throughout the installation.  Because
-     <Acronym>SQL</Acronym> syntax refers to tables,  we  will use  the  terms
-     <FirstTerm>table</FirstTerm> and <FirstTerm>class</FirstTerm> interchangeably.
-  Likewise, an <Acronym>SQL</Acronym> <FirstTerm>row</FirstTerm> is an
-     <FirstTerm>instance</FirstTerm> and <Acronym>SQL</Acronym> 
-<FirstTerm>columns</FirstTerm>
- are <FirstTerm>attributes</FirstTerm>.
-     As  previously  discussed,  classes  are  grouped  into
-     databases,  and  a collection of databases managed by a
-     single <FileName>postmaster</FileName> process constitutes  an  installation
-     or site.
-</Para>
-</sect1>
-
-<Sect1>
-<Title>Creating a New Class</Title>
-
-<Para>
-     You  can  create  a  new  class by specifying the class
-     name, along with all attribute names and their types:
-
-<ProgramListing>
-CREATE TABLE weather (
-    city            varchar(80),
-    temp_lo         int,           -- low temperature
-    temp_hi         int,           -- high temperature
-    prcp            real,          -- precipitation
-    date            date
-);
-</ProgramListing>
-</para>
-
-<Para>
-     Note that keywords are case-insensitive and identifiers
-     are usually case-insensitive.
-<Acronym>Postgres</Acronym> allows <Acronym>SQL92</Acronym> <FirstTerm>delimited identifiers</FirstTerm>
-(identifiers surrounded by double-quotes) to include mixed-case and spaces, tabs, etc.
-</para>
-
-<Para>
-  <ProductName>Postgres</ProductName>  <Acronym>SQL</Acronym> supports the usual
-     <Acronym>SQL</Acronym> types <Type>int</Type>,
- <Type>float</Type>,  <Type>real</Type>,  <Type>smallint</Type>,  <Type>char(N)</Type>,  
-     <Type>varchar(N)</Type>,  <Type>date</Type>, <Type>time</Type>,
-and <Type>timestamp</Type>, as well as other types of general utility and
-a rich set of geometric types.  As we will 
-     see later, <ProductName>Postgres</ProductName> can be customized  with  an  
-     arbitrary  number  of
-     user-defined  data types.  Consequently, type names are
-     not syntactical keywords, except where required to support special cases in the <Acronym>SQL92</Acronym> standard.
-     So far, the <ProductName>Postgres</ProductName> create command looks exactly  like
-     the  command  used  to  create a table in a traditional
-     relational system.  However, we will presently see that
-     classes  have  properties  that  are  extensions of the
-     relational model.
-</Para>
-</sect1>
-
-<Sect1>
-<Title>Populating a Class with Instances</Title>
-
-<Para>
-     The <Command>insert</Command> statement is used to populate a  class  with
-     instances:
-
-<ProgramListing>
-INSERT INTO weather
-    VALUES ('San Francisco', 46, 50, 0.25, '11/27/1994')
-</ProgramListing>
-</para>
-
-<Para>
-     You can also use the <Command>copy</Command> command to perform load large
-     amounts of data from flat (<Acronym>ASCII</Acronym>) files.
-This is usually faster because the data is read (or written) as a single atomic
-transaction directly to or from the target table. An example would be:
-
-<ProgramListing>
-COPY INTO weather FROM '/home/user/weather.txt'
-    USING DELIMITERS '|';
-</ProgramListing>
-
-where the path name for the source file must be available to the backend server
-machine, not just the client.
-</para>
-</sect1>
-
-<Sect1>
-<Title>Querying a Class</Title>
-
-<Para>
-     The weather class can be queried with normal relational
-     selection  and projection queries.  A <Acronym>SQL</Acronym> <Command>select</Command> 
-     statement is used to do this.  The statement is divided into
-     a target list (the part that lists the attributes to be
-     returned) and a qualification (the part that  specifies
-     any  restrictions).   For  example, to retrieve all the
-     rows of weather, type:
-<ProgramListing>
-SELECT * FROM WEATHER;
-</ProgramListing>
-
-     and the output should be:
-<ProgramListing>
-+--------------+---------+---------+------+------------+
-|city          | temp_lo | temp_hi | prcp | date       |
-+--------------+---------+---------+------+------------+
-|San Francisco | 46      | 50      | 0.25 | 11-27-1994 |
-+--------------+---------+---------+------+------------+
-|San Francisco | 43      | 57      | 0    | 11-29-1994 |
-+--------------+---------+---------+------+------------+
-|Hayward       | 37      | 54      |      | 11-29-1994 |
-+--------------+---------+---------+------+------------+
-</ProgramListing>
-     You may specify any arbitrary expressions in the  target list. For example, you can do:
-<ProgramListing>
-SELECT city, (temp_hi+temp_lo)/2 AS temp_avg, date FROM weather;
-</ProgramListing>
-</para>
-
-<Para>
-     Arbitrary  Boolean  operators
- (<Command>and</Command>,  <Command>or</Command> and <Command>not</Command>) are
-     allowed in the qualification of any query.   For  example,
-
-<ProgramListing>
-SELECT * FROM weather
-    WHERE city = 'San Francisco'
-    AND prcp > 0.0;
-
-+--------------+---------+---------+------+------------+
-|city          | temp_lo | temp_hi | prcp | date       |
-+--------------+---------+---------+------+------------+
-|San Francisco | 46      | 50      | 0.25 | 11-27-1994 |
-+--------------+---------+---------+------+------------+
-</ProgramListing>
-</Para>
-
-<Para>
-     As  a final note, you can specify that the results of a
-     select can be returned in a <FirstTerm>sorted order</FirstTerm>
- or with <FirstTerm>duplicate instances</FirstTerm> removed.
-
-<ProgramListing>
-SELECT DISTINCT city
-    FROM weather
-    ORDER BY city;
-</ProgramListing>
-</Para>
-</sect1>
-
-<Sect1>
-<Title>Redirecting SELECT Queries</Title>
-
-<Para>
-     Any select query can be redirected to a new class
-<ProgramListing>
-SELECT * INTO TABLE temp FROM weather;
-</ProgramListing>
-</para>
-
-<Para>
-     This forms an implicit <Command>create</Command> command, creating a new
-     class temp with the attribute names and types specified
-     in  the target list of the <Command>select into</Command> command.  We can
-     then, of course, perform any operations on the  resulting 
-     class that we can perform on other classes.
-</Para>
-</sect1>
-
-<Sect1>
-<Title>Joins Between Classes</Title>
-
-<Para>
-     Thus far, our queries have only accessed one class at a
-     time.  Queries can access multiple classes at once,  or
-     access  the  same  class  in  such  a way that multiple
-     instances of the class are being processed at the  same
-     time.   A query that accesses multiple instances of the
-     same or different classes at one time is called a  join
-     query.
-     As an example, say we wish to find all the records that
-     are in the  temperature  range  of  other  records.  In
-     effect,  we  need  to  compare  the temp_lo and temp_hi
-     attributes of each EMP  instance  to  the  temp_lo  and
-     temp_hi  attributes of all other EMP instances.
-<Note>
-<Para>
-This  is only a conceptual model.  The actual join may
-   be performed in a more efficient manner, but this is invisible to the user.
-</Para>
-</Note>
-
- We can do this with the following query:
-
-<ProgramListing>
-SELECT W1.city, W1.temp_lo, W1.temp_hi,
-    W2.city, W2.temp_lo, W2.temp_hi
-    FROM weather W1, weather W2
-    WHERE W1.temp_lo < W2.temp_lo
-    AND W1.temp_hi > W2.temp_hi;
-
-+--------------+---------+---------+---------------+---------+---------+
-|city          | temp_lo | temp_hi | city          | temp_lo | temp_hi |
-+--------------+---------+---------+---------------+---------+---------+
-|San Francisco | 43      | 57      | San Francisco | 46      | 50      |
-+--------------+---------+---------+---------------+---------+---------+
-|San Francisco | 37      | 54      | San Francisco | 46      | 50      |
-+--------------+---------+---------+---------------+---------+---------+
-</ProgramListing>     
-
-<Note>
-<Para>
-The semantics of such a join are 
-   that the qualification
-   is a truth expression defined for the Cartesian  product  of
-   the  classes indicated in the query.  For those instances in
-   the Cartesian product for which the qualification  is  true,
-   <ProductName>Postgres</ProductName>  computes  and  returns the values specified in the
-   target list.  <ProductName>Postgres</ProductName> <Acronym>SQL</Acronym> does not assign  any  meaning  to
-   duplicate values in such expressions.  This means that <ProductName>Postgres</ProductName> 
-   sometimes recomputes the same target list several times;
-   this frequently happens when Boolean expressions are connected 
-   with an "or".  To remove such duplicates, you must  use
-   the <Command>select distinct</Command> statement.
-</Para>
-</Note>
-</para>
-
-<Para>
-     In this case, both W1 and  W2  are  surrogates for  an
-     instance  of the class weather, and both range over all
-     instances of the class.  (In the  terminology  of  most
-     database  systems,  W1 and W2 are known as <FirstTerm>range variables</FirstTerm>.)  
-     A query can contain an  arbitrary  number  of
-     class names and surrogates.
-</Para>
-</sect1>
-
-<Sect1>
-<Title>Updates</Title>
-
-<Para>
-     You can update existing instances using the update command. 
-     Suppose you discover the temperature readings are
-     all  off  by 2 degrees as of Nov 28, you may update the
-     data as follow:
-
-<ProgramListing>
-UPDATE weather
-    SET temp_hi = temp_hi - 2,  temp_lo = temp_lo - 2
-    WHERE date > '11/28/1994';
-</ProgramListing>
-</Para>
-</sect1>
-
-<Sect1>
-<Title>Deletions</Title>
-
-<Para>
-     Deletions are performed using the <Command>delete</Command> command:
-<ProgramListing>
-DELETE FROM weather WHERE city = 'Hayward';
-</ProgramListing>
-
-     All weather recording belongs to Hayward is removed.
-     One should be wary of queries of the form
-<ProgramListing>
-DELETE FROM classname;
-</ProgramListing>
-
-     Without a qualification, <Command>delete</Command> will simply
-     remove  all  instances  of  the given class, leaving it
-     empty.  The system will not request confirmation before
-     doing this.
-</Para>
-</sect1>
-
-<Sect1>
-<Title>Using Aggregate Functions</Title>
-
-<Para>
-     Like  most  other  query  languages,  <ProductName>PostgreSQL</ProductName> supports
-     aggregate functions.
-The current  implementation  of  <ProductName>Postgres</ProductName> aggregate functions have some limitations.
-     Specifically, while there  are  aggregates  to  compute
-     such  functions as the <Function>count</Function>, <Function>sum</Function>,
- <Function>avg</Function> (average), <Function>max</Function> (maximum) and
-     <Function>min</Function> (minimum) over a set of instances,  aggregates  can  only
-     appear  in  the  target  list of a query and not directly in the
-     qualification (the <FirstTerm>where</FirstTerm> clause). As an example,
-
-<ProgramListing>
-SELECT max(temp_lo) FROM weather;
-</ProgramListing>
-
-is allowed, while
-
-<ProgramListing>
-SELECT city FROM weather WHERE temp_lo = max(temp_lo);
-</ProgramListing>
-
-is not. However, as is often the case the query can be restated to accomplish
-the intended result; here by using a <FirstTerm>subselect</FirstTerm>:
-<ProgramListing>
-SELECT city FROM weather WHERE temp_lo = (SELECT max(temp_lo) FROM weather);
-</ProgramListing>
-</Para>
-
-<Para>
-     Aggregates may also have <FirstTerm>group by</FirstTerm> clauses:
-<ProgramListing>
-SELECT city, max(temp_lo)
-    FROM weather
-    GROUP BY city;
-</ProgramListing>
-</Para>
-</sect1>
-</Chapter>
index 6308aea..cafeb4a 100644 (file)
@@ -1,38 +1,40 @@
-<Chapter ID="query">
-<TITLE>The Query Language</TITLE>
-
-<Para>
-     The  <ProductName>Postgres</ProductName>  query language is a variant of
-the <Acronym>SQL3</Acronym> draft next-generation standard. It
-     has many extensions such as an extensible type  system,
-     inheritance,  functions and production rules. These are
-     features carried over from the original <ProductName>Postgres</ProductName>  query
-     language,  <ProductName>PostQuel</ProductName>.  This section provides an overview
-     of how to use <ProductName>Postgres</ProductName> <Acronym>SQL</Acronym>  to  perform  simple  operations.
-     This manual is only intended to give you an idea of our
-     flavor of <Acronym>SQL</Acronym> and is in no way a complete  tutorial  on
-     <Acronym>SQL</Acronym>.  Numerous  books  have  been  written  on <Acronym>SQL</Acronym>, including
+ <Chapter ID="query">
+  <TITLE>The Query Language</TITLE>
+
+  <Para>
+   The  <ProductName>Postgres</ProductName>  query language is a variant of
+   the <Acronym>SQL3</Acronym> draft next-generation standard. It
+   has many extensions such as an extensible type  system,
+   inheritance,  functions and production rules. These are
+   features carried over from the original <ProductName>Postgres</ProductName>  query
+   language,  <ProductName>PostQuel</ProductName>.  This section provides an overview
+   of how to use <ProductName>Postgres</ProductName>
+   <Acronym>SQL</Acronym>  to  perform  simple  operations.
+   This manual is only intended to give you an idea of our
+   flavor of <Acronym>SQL</Acronym> and is in no way a complete  tutorial  on
+   <Acronym>SQL</Acronym>.  Numerous  books  have  been  written  on
+   <Acronym>SQL</Acronym>, including
 <!--
 <XRef LinkEnd="MELT93"> and <XRef LinkEnd="DATE97">.
 -->
 [MELT93] and [DATE97].
-     You should be  aware  that  some language features 
-are not part of the <Acronym>ANSI</Acronym> standard.
-</Para>
-
-<Sect1>
-<Title>Interactive Monitor</Title>
-
-<Para>
-     In the examples that follow, we assume  that  you  have
-     created  the mydb database as described in the previous
-     subsection and have started <Application>psql</Application>.
-     Examples  in  this  manual  can  also   be   found   in
-     <FileName>/usr/local/pgsql/src/tutorial/</FileName>.    Refer   to   the
-     <FileName>README</FileName> file in that directory for how to use them.   To
-     start the tutorial, do the following:
-
-<ProgramListing>
+   You should be  aware  that  some language features 
+   are extensions to the <Acronym>ANSI</Acronym> standard.
+  </Para>
+
+  <Sect1>
+   <Title>Interactive Monitor</Title>
+
+   <Para>
+    In the examples that follow, we assume  that  you  have
+    created  the mydb database as described in the previous
+    subsection and have started <Application>psql</Application>.
+    Examples  in  this  manual  can  also   be   found   in
+    <FileName>/usr/local/pgsql/src/tutorial/</FileName>.    Refer   to   the
+    <FileName>README</FileName> file in that directory for how to use them.   To
+    start the tutorial, do the following:
+
+    <ProgramListing>
 % cd /usr/local/pgsql/src/tutorial
 % psql -s mydb
 Welcome to the POSTGRESQL interactive sql monitor:
@@ -44,54 +46,55 @@ Welcome to the POSTGRESQL interactive sql monitor:
  You are currently connected to the database: postgres
 
 mydb=> \i basics.sql
-</ProgramListing>
-</Para>
-
-<Para>
-     The  <Literal>\i</Literal>  command  read  in  queries  from the specified
-     files. The <Literal>-s</Literal> option puts you in single step mode which
-     pauses  before  sending a query to the backend. Queries
-     in this section are in the file <FileName>basics.sql</FileName>.
-</Para>
-
-<Para>
-<Application>psql</Application>
-has a variety of <Literal>\d</Literal> commands for showing system information.
-Consult these commands for more details;
-for a listing, type <Literal>\?</Literal> at the <Application>psql</Application> prompt.
-</Para>
-</sect1>
-
-<Sect1>
-<Title>Concepts</Title>
-
-<Para>
-     The fundamental notion in <ProductName>Postgres</ProductName> is that of a  class,
-     which  is a named collection of object instances.  Each
-     instance has the same collection of  named  attributes,
-     and each attribute is of a specific type.  Furthermore,
-     each instance has a permanent <FirstTerm>object  identifier</FirstTerm> (<Acronym>OID</Acronym>)
-     that  is  unique  throughout the installation.  Because
-     <Acronym>SQL</Acronym> syntax refers to tables,  we  will use  the  terms
-     <FirstTerm>table</FirstTerm> and <FirstTerm>class</FirstTerm> interchangeably.
-  Likewise, an <Acronym>SQL</Acronym> <FirstTerm>row</FirstTerm> is an
-     <FirstTerm>instance</FirstTerm> and <Acronym>SQL</Acronym> <FirstTerm>columns</FirstTerm>
- are <FirstTerm>attributes</FirstTerm>.
-     As  previously  discussed,  classes  are  grouped  into
-     databases,  and  a collection of databases managed by a
-     single <Application>postmaster</Application> process constitutes  an  installation
-     or site.
-</Para>
-</sect1>
-
-<Sect1>
-<Title>Creating a New Class</Title>
-
-<Para>
-     You  can  create  a  new  class by specifying the class
-     name, along with all attribute names and their types:
-
-<ProgramListing>
+    </ProgramListing>
+   </Para>
+
+   <Para>
+    The  <Literal>\i</Literal>  command  read  in  queries  from the specified
+    files. The <Literal>-s</Literal> option puts you in single step mode which
+    pauses  before  sending a query to the backend. Queries
+    in this section are in the file <FileName>basics.sql</FileName>.
+   </Para>
+
+   <Para>
+    <Application>psql</Application>
+    has a variety of <Literal>\d</Literal> commands for showing system information.
+    Consult these commands for more details;
+    for a listing, type <Literal>\?</Literal> at the <Application>psql</Application> prompt.
+   </Para>
+  </sect1>
+
+  <Sect1>
+   <Title>Concepts</Title>
+
+   <Para>
+    The fundamental notion in <ProductName>Postgres</ProductName> is that of a  class,
+    which  is a named collection of object instances.  Each
+    instance has the same collection of  named  attributes,
+    and each attribute is of a specific type.  Furthermore,
+    each instance has a permanent <FirstTerm>object identifier</FirstTerm>
+    (<Acronym>OID</Acronym>)
+    that  is  unique  throughout the installation.  Because
+    <Acronym>SQL</Acronym> syntax refers to tables,  we  will use  the  terms
+    <FirstTerm>table</FirstTerm> and <FirstTerm>class</FirstTerm> interchangeably.
+    Likewise, an <Acronym>SQL</Acronym> <FirstTerm>row</FirstTerm> is an
+    <FirstTerm>instance</FirstTerm> and <Acronym>SQL</Acronym> <FirstTerm>columns</FirstTerm>
+    are <FirstTerm>attributes</FirstTerm>.
+    As  previously  discussed,  classes  are  grouped  into
+    databases,  and  a collection of databases managed by a
+    single <Application>postmaster</Application> process constitutes  an  installation
+    or site.
+   </Para>
+  </sect1>
+
+  <Sect1>
+   <Title>Creating a New Class</Title>
+
+   <Para>
+    You  can  create  a  new  class by specifying the class
+    name, along with all attribute names and their types:
+
+    <ProgramListing>
 CREATE TABLE weather (
     city            varchar(80),
     temp_lo         int,           -- low temperature
@@ -99,66 +102,82 @@ CREATE TABLE weather (
     prcp            real,          -- precipitation
     date            date
 );
-</ProgramListing>
-</para>
-
-<Para>
-     Note that both keywords and identifiers are case-insensitive; identifiers can become
-case-sensitive by surrounding them with double-quotes as allowed by <Acronym>SQL92</Acronym>.
-     <ProductName>Postgres</ProductName>  <Acronym>SQL</Acronym> supports the usual
-     <Acronym>SQL</Acronym> types <Type>int</Type>,
- <Type>float</Type>,  <Type>real</Type>,  <Type>smallint</Type>,  <Type>char(N)</Type>,  
-     <Type>varchar(N)</Type>,  <Type>date</Type>, <Type>time</Type>,
-and <Type>timestamp</Type>, as well as other types of general utility and
-a rich set of geometric types.  As we will 
-     see later, <ProductName>Postgres</ProductName> can be customized  with  an  
-     arbitrary  number  of
-     user-defined  data types.  Consequently, type names are
-     not syntactical keywords, except where required to support special cases in the <Acronym>SQL92</Acronym> standard.
-     So far, the <ProductName>Postgres</ProductName> create command looks exactly  like
-     the  command  used  to  create a table in a traditional
-     relational system.  However, we will presently see that
-     classes  have  properties  that  are  extensions of the
-     relational model.
-</Para>
-</sect1>
-
-<Sect1>
-<Title>Populating a Class with Instances</Title>
-
-<Para>
-     The <Command>insert</Command> statement is used to populate a  class  with
-     instances:
-
-<ProgramListing>
+    </ProgramListing>
+   </para>
+
+   <Para>
+    Note that both keywords and identifiers are case-insensitive; identifiers can become
+    case-sensitive by surrounding them with double-quotes as allowed
+    by <Acronym>SQL92</Acronym>.
+    <ProductName>Postgres</ProductName>  <Acronym>SQL</Acronym> supports the usual
+    <Acronym>SQL</Acronym> types <Type>int</Type>,
+    <Type>float</Type>,  <Type>real</Type>,  <Type>smallint</Type>,  <Type>char(N)</Type>,  
+    <Type>varchar(N)</Type>,  <Type>date</Type>, <Type>time</Type>,
+    and <Type>timestamp</Type>, as well as other types of general utility and
+    a rich set of geometric types.  As we will 
+    see later, <ProductName>Postgres</ProductName> can be customized  with  an  
+    arbitrary  number  of
+    user-defined  data types.  Consequently, type names are
+    not syntactical keywords, except where required to support special
+    cases in the <Acronym>SQL92</Acronym> standard.
+    So far, the <ProductName>Postgres</ProductName> create command
+    looks exactly  like
+    the  command  used  to  create a table in a traditional
+    relational system.  However, we will presently see that
+    classes  have  properties  that  are  extensions of the
+    relational model.
+   </Para>
+  </sect1>
+
+  <Sect1>
+   <Title>Populating a Class with Instances</Title>
+
+   <Para>
+    The <Command>insert</Command> statement is used to populate a  class  with
+    instances:
+
+    <ProgramListing>
 INSERT INTO weather
     VALUES ('San Francisco', 46, 50, 0.25, '11/27/1994')
-</ProgramListing>
-</Para>
-
-<Para>
-     You can also use the <Command>copy</Command> command to perform load large
-     amounts of data from flat (<Acronym>ASCII</Acronym>) files.
-</Para>
-</sect1>
-
-<Sect1>
-<Title>Querying a Class</Title>
-
-<Para>
-     The weather class can be queried with normal relational
-     selection  and projection queries.  A <Acronym>SQL</Acronym> <Command>select</Command> 
-     statement is used to do this.  The statement is divided into
-     a target list (the part that lists the attributes to be
-     returned) and a qualification (the part that  specifies
-     any  restrictions).   For  example, to retrieve all the
-     rows of weather, type:
-<ProgramListing>
+    </ProgramListing>
+   </Para>
+
+   <Para>
+    You can also use the <Command>copy</Command> command to perform load large
+    amounts of data from flat (<Acronym>ASCII</Acronym>) files.
+    This is usually faster because the data is read (or written) as a single atomic
+    transaction directly to or from the target table. An example would be:
+
+    <ProgramListing>
+COPY INTO weather FROM '/home/user/weather.txt'
+    USING DELIMITERS '|';
+    </ProgramListing>
+
+    where the path name for the source file must be available to the backend server
+    machine, not the client, since the backend server reads the file directly.
+   </para>
+  </sect1>
+
+ </Para>
+ </sect1>
+
+  <Sect1>
+   <Title>Querying a Class</Title>
+
+   <Para>
+    The weather class can be queried with normal relational
+    selection  and projection queries.  A <Acronym>SQL</Acronym> <Command>select</Command> 
+    statement is used to do this.  The statement is divided into
+    a target list (the part that lists the attributes to be
+    returned) and a qualification (the part that  specifies
+    any  restrictions).   For  example, to retrieve all the
+    rows of weather, type:
+    <ProgramListing>
 SELECT * FROM WEATHER;
-</ProgramListing>
+    </ProgramListing>
 
-     and the output should be:
-<ProgramListing>
+    and the output should be:
+    <ProgramListing>
 +--------------+---------+---------+------+------------+
 |city          | temp_lo | temp_hi | prcp | date       |
 +--------------+---------+---------+------+------------+
@@ -168,89 +187,91 @@ SELECT * FROM WEATHER;
 +--------------+---------+---------+------+------------+
 |Hayward       | 37      | 54      |      | 11-29-1994 |
 +--------------+---------+---------+------+------------+
-</ProgramListing>
-     You may specify any arbitrary expressions in the  target list. For example, you can do:
-<ProgramListing>
+    </ProgramListing>
+    You may specify any arbitrary expressions in the  target list. For example, you can do:
+    <ProgramListing>
 SELECT city, (temp_hi+temp_lo)/2 AS temp_avg, date FROM weather;
-</ProgramListing>
-</Para>
+    </ProgramListing>
+   </Para>
 
-<Para>
-     Arbitrary  Boolean  operators
- (<Command>and</Command>,  <Command>or</Command> and <Command>not</Command>) are
-     allowed in the qualification of any query.   For  example,
+   <Para>
+    Arbitrary  Boolean  operators
   (<Command>and</Command>,  <Command>or</Command> and <Command>not</Command>) are
+    allowed in the qualification of any query.   For  example,
 
-<ProgramListing>
+    <ProgramListing>
 SELECT * FROM weather
     WHERE city = 'San Francisco'
     AND prcp > 0.0;
-
+    </programlisting>
+results in:
+    <programlisting>
 +--------------+---------+---------+------+------------+
 |city          | temp_lo | temp_hi | prcp | date       |
 +--------------+---------+---------+------+------------+
 |San Francisco | 46      | 50      | 0.25 | 11-27-1994 |
 +--------------+---------+---------+------+------------+
-</ProgramListing>
-</Para>
+    </ProgramListing>
+   </Para>
 
-<Para>
-     As  a final note, you can specify that the results of a
-     select can be returned in a <FirstTerm>sorted order</FirstTerm>
- or with <FirstTerm>duplicate instances</FirstTerm> removed.
+   <Para>
+    As  a final note, you can specify that the results of a
+    select can be returned in a <FirstTerm>sorted order</FirstTerm>
   or with <FirstTerm>duplicate instances</FirstTerm> removed.
 
-<ProgramListing>
+    <ProgramListing>
 SELECT DISTINCT city
     FROM weather
     ORDER BY city;
-</ProgramListing>
-</Para>
-</sect1>
+    </ProgramListing>
+   </Para>
+  </sect1>
 
-<Sect1>
-<Title>Redirecting SELECT Queries</Title>
+  <Sect1>
+   <Title>Redirecting SELECT Queries</Title>
 
-<Para>
-     Any select query can be redirected to a new class
-<ProgramListing>
+   <Para>
+    Any select query can be redirected to a new class
+    <ProgramListing>
 SELECT * INTO TABLE temp FROM weather;
-</ProgramListing>
-</Para>
-
-<Para>
-     This forms an implicit <Command>create</Command> command, creating a new
-     class temp with the attribute names and types specified
-     in  the target list of the <Command>select into</Command> command.  We can
-     then, of course, perform any operations on the  resulting 
-     class that we can perform on other classes.
-</Para>
-</sect1>
-
-<Sect1>
-<Title>Joins Between Classes</Title>
-
-<Para>
-     Thus far, our queries have only accessed one class at a
-     time.  Queries can access multiple classes at once,  or
-     access  the  same  class  in  such  a way that multiple
-     instances of the class are being processed at the  same
-     time.   A query that accesses multiple instances of the
-     same or different classes at one time is called a  join
-     query.
-     As an example, say we wish to find all the records that
-     are in the  temperature  range  of  other  records.  In
-     effect,  we  need  to  compare  the temp_lo and temp_hi
-     attributes of each EMP  instance  to  the  temp_lo  and
-     temp_hi  attributes of all other EMP instances.
-<Note>
-<Para>
-This  is only a conceptual model.  The actual join may
-   be performed in a more efficient manner, but this is invisible to the user.
-</Para>
-</Note>
-
- We can do this with the following query:
-
-<ProgramListing>
+    </ProgramListing>
+   </Para>
+
+   <Para>
+    This forms an implicit <Command>create</Command> command, creating a new
+    class temp with the attribute names and types specified
+    in  the target list of the <Command>select into</Command> command.  We can
+    then, of course, perform any operations on the  resulting 
+    class that we can perform on other classes.
+   </Para>
+  </sect1>
+
+  <Sect1>
+   <Title>Joins Between Classes</Title>
+
+   <Para>
+    Thus far, our queries have only accessed one class at a
+    time.  Queries can access multiple classes at once,  or
+    access  the  same  class  in  such  a way that multiple
+    instances of the class are being processed at the  same
+    time.   A query that accesses multiple instances of the
+    same or different classes at one time is called a  join
+    query.
+    As an example, say we wish to find all the records that
+    are in the  temperature  range  of  other  records.  In
+    effect,  we  need  to  compare  the temp_lo and temp_hi
+    attributes of each EMP  instance  to  the  temp_lo  and
+    temp_hi  attributes of all other EMP instances.
+    <Note>
+     <Para>
+      This  is only a conceptual model.  The actual join may
+      be performed in a more efficient manner, but this is invisible to the user.
+     </Para>
+    </Note>
+
   We can do this with the following query:
+
+    <ProgramListing>
 SELECT W1.city, W1.temp_lo AS low, W1.temp_hi AS high,
     W2.city, W2.temp_lo AS low, W2.temp_hi AS high
     FROM weather W1, weather W2
@@ -264,113 +285,135 @@ SELECT W1.city, W1.temp_lo AS low, W1.temp_hi AS high,
 +--------------+-----+------+---------------+-----+------+
 |San Francisco | 37  | 54   | San Francisco | 46  | 50   |
 +--------------+-----+------+---------------+-----+------+
-</ProgramListing>     
-
-<Note>
-<Para>
-The semantics of such a join are 
-   that the qualification
-   is a truth expression defined for the Cartesian  product  of
-   the  classes indicated in the query.  For those instances in
-   the Cartesian product for which the qualification  is  true,
-   <ProductName>Postgres</ProductName>  computes  and  returns the values specified in the
-   target list.  <ProductName>Postgres</ProductName> <Acronym>SQL</Acronym> does not assign  any  meaning  to
-   duplicate values in such expressions.  This means that <ProductName>Postgres</ProductName> 
-   sometimes recomputes the same target list several times;
-   this frequently happens when Boolean expressions are connected 
-   with an "or".  To remove such duplicates, you must  use
-   the <Command>select distinct</Command> statement.
-</Para>
-</Note>
-</para>
-
-<Para>
-     In this case, both W1 and  W2  are  surrogates for  an
-     instance  of the class weather, and both range over all
-     instances of the class.  (In the  terminology  of  most
-     database  systems,  W1 and W2 are known as <FirstTerm>range variables</FirstTerm>.)  
-     A query can contain an  arbitrary  number  of
-     class names and surrogates.
-</Para>
-</sect1>
-
-<Sect1>
-<Title>Updates</Title>
-
-<Para>
-     You can update existing instances using the update command. 
-     Suppose you discover the temperature readings are
-     all  off  by 2 degrees as of Nov 28, you may update the
-     data as follow:
-
-<ProgramListing>
+    </ProgramListing>     
+
+    <Note>
+     <Para>
+      The semantics of such a join are 
+      that the qualification
+      is a truth expression defined for the Cartesian  product  of
+      the  classes indicated in the query.  For those instances in
+      the Cartesian product for which the qualification  is  true,
+      <ProductName>Postgres</ProductName>  computes  and  returns the
+      values specified in the target list.  
+      <ProductName>Postgres</ProductName> <Acronym>SQL</Acronym>
+      does not assign  any  meaning  to
+      duplicate values in such expressions. 
+      This means that <ProductName>Postgres</ProductName> 
+      sometimes recomputes the same target list several times;
+      this frequently happens when Boolean expressions are connected 
+      with an "or".  To remove such duplicates, you must  use
+      the <Command>select distinct</Command> statement.
+     </Para>
+    </Note>
+   </para>
+
+   <Para>
+    In this case, both W1 and  W2  are  surrogates for  an
+    instance  of the class weather, and both range over all
+    instances of the class.  (In the  terminology  of  most
+    database  systems,  W1 and W2 are known as <FirstTerm>range variables</FirstTerm>.)  
+    A query can contain an  arbitrary  number  of
+    class names and surrogates.
+   </Para>
+  </sect1>
+
+  <Sect1>
+   <Title>Updates</Title>
+
+   <Para>
+    You can update existing instances using the update command. 
+    Suppose you discover the temperature readings are
+    all  off  by 2 degrees as of Nov 28, you may update the
+    data as follow:
+
+    <ProgramListing>
 UPDATE weather
     SET temp_hi = temp_hi - 2,  temp_lo = temp_lo - 2
     WHERE date > '11/28/1994';
-</ProgramListing>
-</Para>
-</sect1>
+    </ProgramListing>
+   </Para>
+  </sect1>
 
-<Sect1>
-<Title>Deletions</Title>
+  <Sect1>
+   <Title>Deletions</Title>
 
-<Para>
-     Deletions are performed using the <Command>delete</Command> command:
-<ProgramListing>
+   <Para>
+    Deletions are performed using the <Command>delete</Command> command:
+    <ProgramListing>
 DELETE FROM weather WHERE city = 'Hayward';
-</ProgramListing>
+    </ProgramListing>
 
-     All weather recording belongs to Hayward is removed.
-     One should be wary of queries of the form
-<ProgramListing>
+    All weather recording belongs to Hayward is removed.
+    One should be wary of queries of the form
+    <ProgramListing>
 DELETE FROM classname;
-</ProgramListing>
-
-     Without a qualification, <Command>delete</Command> will simply
-     remove  all  instances  of  the given class, leaving it
-     empty.  The system will not request confirmation before
-     doing this.
-</Para>
-</sect1>
-
-<Sect1>
-<Title>Using Aggregate Functions</Title>
-
-<Para>
-     Like  most  other  query  languages,  <ProductName>PostgreSQL</ProductName> supports
-     aggregate functions.
-The current  implementation  of  <ProductName>Postgres</ProductName> aggregate functions have some limitations.
-     Specifically, while there  are  aggregates  to  compute
-     such  functions as the <Function>count</Function>, <Function>sum</Function>,
- <Function>avg</Function> (average), <Function>max</Function> (maximum) and
-     <Function>min</Function> (minimum) over a set of instances,  aggregates  can  only
-     appear  in  the  target  list of a query and not directly in the
-     qualification (the where clause). As an example,
-
-<ProgramListing>
+    </ProgramListing>
+
+    Without a qualification, <Command>delete</Command> will simply
+    remove  all  instances  of  the given class, leaving it
+    empty.  The system will not request confirmation before
+    doing this.
+   </Para>
+  </sect1>
+
+  <Sect1>
+   <Title>Using Aggregate Functions</Title>
+
+   <Para>
+    Like  most  other  query  languages, 
+    <ProductName>PostgreSQL</ProductName> supports
+    aggregate functions.
+    The current  implementation  of
+    <ProductName>Postgres</ProductName> aggregate functions have some limitations.
+    Specifically, while there  are  aggregates  to  compute
+    such  functions as the <Function>count</Function>, <Function>sum</Function>,
+    <Function>avg</Function> (average), <Function>max</Function> (maximum) and
+    <Function>min</Function> (minimum) over a set of instances,  aggregates  can  only
+    appear  in  the  target  list of a query and not directly in the
+    qualification (the where clause). As an example,
+
+    <ProgramListing>
 SELECT max(temp_lo) FROM weather;
-</ProgramListing>
+    </ProgramListing>
 
-is allowed, while
+    is allowed, while
 
-<ProgramListing>
+    <ProgramListing>
 SELECT city FROM weather WHERE temp_lo = max(temp_lo);
-</ProgramListing>
+    </ProgramListing>
 
-is not. However, as is often the case the query can be restated to accomplish 
-the intended result; here by using a <FirstTerm>subselect</FirstTerm>:
-<ProgramListing>
+    is not. However, as is often the case the query can be restated to accomplish 
+    the intended result; here by using a <FirstTerm>subselect</FirstTerm>:
+    <ProgramListing>
 SELECT city FROM weather WHERE temp_lo = (SELECT max(temp_lo) FROM weather);
-</ProgramListing>
-</Para>
+    </ProgramListing>
+   </Para>
 
-<Para>
-     Aggregates may also have <FirstTerm>group by</FirstTerm> clauses:
-<ProgramListing>
+   <Para>
+    Aggregates may also have <FirstTerm>group by</FirstTerm> clauses:
+    <ProgramListing>
 SELECT city, max(temp_lo)
     FROM weather
     GROUP BY city;
-</ProgramListing>
-</Para>
-</sect1>
-</Chapter>
+    </ProgramListing>
+   </Para>
+  </sect1>
+ </Chapter>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:nil
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"./reference.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
+sgml-local-ecat-files:nil
+End:
+-->
index af6b300..521dcb9 100644 (file)
-<Chapter Id="runtime">
-<Title>Runtime Environment</Title>
-
-<Para>
-This chapter outlines the interaction between <Productname>Postgres</Productname> and
-the operating system.
-</para>
-<sect1>
-<title>Using <Productname>Postgres</Productname> from Unix</title>
-
-<para>
-All <Productname>Postgres</Productname> commands that are executed 
-directly from a Unix shell are
-found in the directory <quote>.../bin</quote>.  Including this directory in
-your search path will make executing the commands easier.
-</para>
-<para>
-A collection of system catalogs exist at each site.  These include a
-class (<literal>pg_user</literal>) that contains an instance for each valid
-<Productname>Postgres</Productname> user.  The instance specifies a set of
- <Productname>Postgres</Productname> privileges, such as
-the ability to act as <Productname>Postgres</Productname> super-user,
- the ability to create/destroy
-databases, and the ability to update the system catalogs.  A Unix
-user cannot do anything with <Productname>Postgres</Productname> 
-until an appropriate instance is
-installed in this class.  Further information on the system catalogs
-is available by running queries on the appropriate classes.
-</para>
-</sect1>
-</chapter>
-
-<chapter id="layout">
-<Title>System Layout</Title>
-
-<Para>
-<Figure Id="ADMIN-LAYOUT">
-<Title><ProductName>Postgres</ProductName> file layout</Title>
-<Graphic Align="center" FileRef="layout.gif" Format="GIF"></Graphic>
-</Figure>
-
-<XRef LinkEnd="ADMIN-LAYOUT" EndTerm="ADMIN-LAYOUT">
-shows how the <ProductName>Postgres</ProductName>  distribution  is  laid
-     out  when installed in the default way. For simplicity,
-     we will assume that <ProductName>Postgres</ProductName>
- has been installed in  the
-     directory  <filename>/usr/local/pgsql</filename>.   Therefore, wherever
-     you see the directory <filename>/usr/local/pgsql</filename> you  should
-     substitute  the name of the directory where
- <ProductName>Postgres</ProductName> is
-     actually installed.
-     All <ProductName>Postgres</ProductName> commands are installed
-     in  the  directory
-     <filename>/usr/local/pgsql/bin</filename>.   Therefore,  you should add
-     this directory to your shell command path.  If you  use
-     a variant of the Berkeley C shell, such as csh or tcsh,
-     you would add
-<ProgramListing>
-set path = ( /usr/local/pgsql/bin path )
-</ProgramListing>
-     in the .login file in your home directory.  If you  use
-     a  variant  of  the  Bourne  shell, such as sh, ksh, or
-     bash, then you would add
-<ProgramListing>
-PATH=/usr/local/pgsql/bin:$PATH
-export PATH
-</ProgramListing>
-     to the .profile file in your home directory.
-     From now on, we will assume that  you  have  added  the
-     <ProductName>Postgres</ProductName>  bin  directory to your path.
-     In addition, we
-     will make frequent reference to "setting a shell  
-     variable"  or  "setting an environment variable" throughout
-     this document.  If you did  not  fully  understand  the
-     last  paragraph  on  modifying  your  search  path, you
-     should consult the UNIX manual pages that describe your
-     shell before going any further.
-</Para>
-
-<Para>
-If you have not set things up in the
-default  way,  you may have some more work to do.  
-For example, if the database server machine is a remote machine, you
-will need to set the <envar>PGHOST</envar> environment variable to the name
-of the database server machine.   The  environment  variable
-<envar>PGPORT</envar> may also have to be set.  The bottom line is this: if
-you try to start an application  program  and  it  complains
-that it cannot connect to the <Application>postmaster</Application>,
-you must go back and make sure that your
-environment is properly set up.
-</Para>
+ <Chapter Id="runtime">
+  <Title>Runtime Environment</Title>
+
+  <Para>
+   This chapter outlines the interaction between <Productname>Postgres</Productname> and
+   the operating system.
+  </para>
+
+  <sect1>
+   <title>Using <Productname>Postgres</Productname> from Unix</title>
+
+   <para>
+    All <Productname>Postgres</Productname> commands that are executed 
+    directly from a Unix shell are
+    found in the directory <quote>.../bin</quote>.  Including this directory in
+    your search path will make executing the commands easier.
+   </para>
+
+   <para>
+    A collection of system catalogs exist at each site.  These include a
+    class (<literal>pg_user</literal>) that contains an instance for each valid
+    <Productname>Postgres</Productname> user.  The instance specifies a set of
+    <Productname>Postgres</Productname> privileges, such as
+    the ability to act as <Productname>Postgres</Productname> super-user,
+    the ability to create/destroy
+    databases, and the ability to update the system catalogs.  A Unix
+    user cannot do anything with <Productname>Postgres</Productname> 
+    until an appropriate instance is
+    installed in this class.  Further information on the system catalogs
+    is available by running queries on the appropriate classes.
+   </para>
+  </sect1>
+
+  <sect1 Id="postmaster">
+   <Title>Starting <Application>postmaster</Application></Title>
+
+   <Para>
+    Nothing can happen to a database unless the
+    <Application>postmaster</Application>
+    process  is  running.  As the site administrator, there
+    are a number  of  things  you  should  remember  before
+    starting  the  <Application>postmaster</Application>.   
+    These are discussed in the installation and configuration sections
+    of this manual.
+    However, if <ProductName>Postgres</ProductName> has been installed by following 
+    the installation instructions exactly  as  written,  the  
+    following  simple  command is all you should
+    need to start the <Application>postmaster</Application>:
+
+    <ProgramListing>
+% postmaster
+    </ProgramListing>
+   </para>
+
+   <para>
+    The <Application>postmaster</Application> occasionally prints out  
+    messages  which
+    are  often helpful during troubleshooting.  If you wish
+    to view debugging messages from the <Application>postmaster</Application>, 
+    you can
+    start  it with the -d option and redirect the output to
+    the log file:
+
+    <ProgramListing>
+% postmaster -d >& pm.log &
+    </ProgramListing>
+
+    If you do not wish to see these messages, you can type
+    <ProgramListing>
+% postmaster -S
+    </ProgramListing>
+    and the <Application>postmaster</Application> will be "S"ilent.  
+    Notice that there
+    is no ampersand ("&amp") at the end of the last example so
+    postmaster will be running in the foreground.
+   </Para>
+  </sect1>
+
+  <sect1 Id="pg-options">
+   <Title id="pg-options-title">Using pg_options</Title>
+
+   <Para>
+    <Note>
+     <Para>
+      Contributed by <ULink url="mailto:dz@cs.unitn.it">Massimo Dal Zotto</ULink>
+     </Para>
+    </Note>
+   </para>
+   <Para>
+    The optional file <filename>data/pg_options</filename> contains runtime
+    options used by the backend to control trace messages and other backend
+    tunable parameters.
+    The file is re-read by a backend
+    when it receives a SIGHUP signal, making thus possible to change run-time
+    options on the fly without needing to restart 
+    <productname>Postgres</productname>.
+    The options specified in this file may be debugging flags used by the trace
+    package (<filename>backend/utils/misc/trace.c</filename>) or numeric
+    parameters which can be used by the backend to control its behaviour.
+   </para>
+
+   <para>
+    All pg_options are initialized to zero at backend startup.
+    New or modified options will be read by all new backends when they are started.
+    To make effective any changes for all running backends we need to send a
+    SIGHUP to the postmaster. The signal will be automatically sent to all the
+    backends. We can also activate the changes only for a specific backend by
+    sending the SIGHUP directly to it.
+   </para>
+   <para>
+    pg_options can also be specified with the <option>-T</option> switch of 
+    <productname>Postgres</productname>:
+
+    <programlisting>
+postgres <replaceable>options</replaceable> -T "verbose=2,query,hostlookup-"
+    </programlisting>
+   </para>
+
+   <Para>
+    The functions used for printing errors and debug messages can now make use
+    of the <citetitle>syslog(2)</citetitle> facility. Message printed to stdout
+    or stderr are prefixed by a timestamp containing also the backend pid:
+
+    <programlisting>
+#timestamp          #pid    #message
+980127.17:52:14.173 [29271] StartTransactionCommand
+980127.17:52:14.174 [29271] ProcessUtility: drop table t;
+980127.17:52:14.186 [29271] SIIncNumEntries: table is 70% full
+980127.17:52:14.186 [29286] Async_NotifyHandler
+980127.17:52:14.186 [29286] Waking up sleeping backend process
+980127.19:52:14.292 [29286] Async_NotifyFrontEnd
+980127.19:52:14.413 [29286] Async_NotifyFrontEnd done
+980127.19:52:14.466 [29286] Async_NotifyHandler done
+    </programlisting>
+   </para>
+   <para>
+    This format improves readability of the logs and allows people to understand
+    exactly which backend is doing what and at which time. It also makes
+    easier to write simple awk or perl scripts which monitor the log to
+    detect database errors or problem, or to compute transaction time statistics.
+   </para>
+   <para>
+    Messages printed to syslog use the log facility LOG_LOCAL0.
+    The use of syslog can be controlled with the syslog pg_option.
+    Unfortunately many functions call directly <function>printf()</function>
+    to print their messages to stdout or stderr and this output can't be
+    redirected to syslog or have timestamps in it. 
+    It would be advisable that all calls to printf would be replaced with the
+    PRINTF macro and output to stderr be changed to use EPRINTF instead so that
+    we can control all output in a uniform way.
+   </Para>
+
+   <para>
+    The format of the <filename>pg_options</filename> file is as follows:
+
+    <programlisting>
+# <replaceable>comment</replaceable>
+<replaceable>option</replaceable>=<replaceable class="parameter">integer_value</replaceable>  # set value for <replaceable>option</replaceable>
+<replaceable>option</replaceable>                # set <replaceable>option</replaceable> = 1
+<replaceable>option</replaceable>+               # set <replaceable>option</replaceable> = 1
+<replaceable>option</replaceable>-               # set <replaceable>option</replaceable> = 0
+    </programlisting>
+
+    Note that <replaceable class="parameter">keyword</replaceable> can also be
+    an abbreviation of the option name defined in
+    <filename>backend/utils/misc/trace.c</filename>.
+
+    <example>
+     <title>pg_options File</title>
+
+     <para>
+      For example my pg_options file contains the following values:
+
+      <programlisting>
+verbose=2
+query
+hostlookup
+showportnumber
+      </programlisting>
+     </para>
+    </example>
+   </para>
+
+   <sect2>
+    <title>Recognized Options</title>
+
+    <Para>
+     The options currently defined are:
+
+     <variablelist>
+      <varlistentry>
+       <term>
+       all
+       </term>
+       <listitem>
+       <para>
+        Global trace flag. Allowed values are:
+       </para>
+
+       <variablelist>
+       <varlistentry>
+        <term>
+         0
+        </term>
+        <listitem>
+         <para>
+          Trace messages enabled individually
+         </para>
+        </listitem>
+       </varlistentry>
+
+       <varlistentry>
+        <term>
+         1
+        </term>
+        <listitem>
+         <para>
+          Enable all trace messages
+         </para>
+        </listitem>
+       </varlistentry>
+       
+       <varlistentry>
+        <term>
+         -1
+        </term>
+        <listitem>
+         <para>
+          Disable all trace messages
+         </para>
+        </listitem>
+       </varlistentry>
+
+       </variablelist>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>
+       verbose
+      </term>
+      <listitem>
+       <para>
+       Verbosity flag. Allowed values are:
+       </para>
+
+       <variablelist>
+       <varlistentry>
+        <term>
+         0
+        </term>
+        <listitem>
+         <para>
+          No messages. This is the default.
+         </para>
+        </listitem>
+       </varlistentry>
+
+       <varlistentry>
+        <term>
+         1
+        </term>
+        <listitem>
+         <para>
+          Print information messages.
+         </para>
+        </listitem>
+       </varlistentry>
+
+       <varlistentry>
+        <term>
+         2
+        </term>
+        <listitem>
+         <para>
+          Print more information messages.
+         </para>
+        </listitem>
+       </varlistentry>
+
+       </variablelist>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>
+       query
+      </term>
+      <listitem>
+       <para>
+       Query trace flag. Allowed values are:
+       </para>
+
+       <variablelist>
+       <varlistentry>
+        <term>
+         0
+        </term>
+        <listitem>
+         <para>
+          Don't print query.
+         </para>
+        </listitem>
+       </varlistentry>
+
+       <varlistentry>
+        <term>
+         1
+        </term>
+        <listitem>
+         <para>
+          Print a condensed query in one line.
+         </para>
+        </listitem>
+       </varlistentry>
+
+       <varlistentry>
+        <term>
+         4
+        </term>
+        <listitem>
+         <para>
+          Print the full query.
+         </para>
+        </listitem>
+       </varlistentry>
+
+       </variablelist>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>
+       plan
+      </term>
+      <listitem>
+       <para>
+       Print query plan.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>
+       parse
+      </term>
+      <listitem>
+       <para>
+       Print parser output.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>
+       rewritten
+      </term>
+      <listitem>
+       <para>
+       Print rewritten query.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>
+       parserstats
+      </term>
+      <listitem>
+       <para>
+       Print parser statistics.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>
+       plannerstats
+      </term>
+      <listitem>
+       <para>
+       Print planner statistics.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>
+       executorstats
+      </term>
+      <listitem>
+       <para>
+       Print executor statistics.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>
+       shortlocks
+      </term>
+      <listitem>
+       <para>
+       Currently unused but needed to enable features in the future.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>
+       locks
+      </term>
+      <listitem>
+       <para>
+       Trace locks.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>
+       userlocks
+      </term>
+      <listitem>
+       <para>
+       Trace user locks.
+       </para>
+      </listitem>
+     </varlistentry>
+     
+     <varlistentry>
+      <term>
+       spinlocks
+      </term>
+      <listitem>
+       <para>
+       Trace spin locks.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>
+       notify
+      </term>
+      <listitem>
+       <para>
+       Trace notify functions.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>
+       malloc
+      </term>
+      <listitem>
+       <para>
+       Currently unused.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>
+       palloc
+      </term>
+      <listitem>
+       <para>
+       Currently unused.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>
+       lock_debug_oidmin
+      </term>
+      <listitem>
+       <para>
+       Minimum relation oid traced by locks.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>
+       lock_debug_relid
+      </term>
+      <listitem>
+       <para>
+       oid, if not zero, of relation traced by locks.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>
+       lock_read_priority
+      </term>
+      <listitem>
+       <para>
+       Currently unused.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>
+       deadlock_timeout
+      </term>
+      <listitem>
+       <para>
+       Deadlock check timer.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>
+       syslog
+      </term>
+      <listitem>
+       <para>
+       syslog flag. Allowed values are:
+       </para>
+
+       <variablelist>
+       <varlistentry>
+        <term>
+         0
+        </term>
+        <listitem>
+         <para>
+          Messages to stdout/stderr.
+         </para>
+        </listitem>
+       </varlistentry>
+
+       <varlistentry>
+        <term>
+         1
+        </term>
+        <listitem>
+         <para>
+          Messages to stdout/stderr and syslog.
+         </para>
+        </listitem>
+       </varlistentry>
+
+       <varlistentry>
+        <term>
+         2
+        </term>
+        <listitem>
+         <para>
+          Messages only to syslog.
+         </para>
+        </listitem>
+       </varlistentry>
+
+       </variablelist>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>
+       hostlookup
+      </term>
+      <listitem>
+       <para>
+       Enable hostname lookup in ps_status.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>
+       showportnumber
+      </term>
+      <listitem>
+       <para>
+       Show port number in ps_status.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>
+       notifyunlock
+      </term>
+      <listitem>
+       <para>
+       Unlock of pg_listener after notify.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term>
+       notifyhack
+      </term>
+      <listitem>
+       <para>
+       Remove duplicate tuples from pg_listener.
+       </para>
+      </listitem>
+     </varlistentry>
+
+    </variablelist>
+    </para>
+   </sect2>
+  </sect1>
 
 </Chapter>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:nil
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"./reference.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
+sgml-local-ecat-files:nil
+End:
+-->
index 4980c12..1539f98 100644 (file)
        two exceptions: manual system catalog updates are not permitted if the
        user does not have <literal>pg_user.usecatupd</literal> set, and destruction of
        system catalogs (or modification of their schemas) is never allowed.
+       </para>
+      </listitem>
+     </varlistentry>
 
      <varlistentry>
       <term>
index 9d14640..47d7feb 100644 (file)
@@ -288,7 +288,7 @@ attributes are taken from. We often write a relation scheme as
     <parameter>D<subscript>i</subscript></parameter>,
     for each attribute
     <parameter>A<subscript>i</subscript></parameter>,
-    1 &le; <literal>i</literal> &le; <literal>k</literal>,
+    1 &lt;&equal; <literal>i</literal> &lt;&equal; <literal>k</literal>,
     where the values of the attributes are taken from. We often write
     a relation scheme as
     <literal>R(<parameter>A<subscript>1</subscript></parameter>,
@@ -325,10 +325,12 @@ attributes are taken from. We often write a relation scheme as
      integers. We define this by assigning a data type to each
      attribute. The type of <classname>SNAME</classname> will be
      <type>VARCHAR(20)</type> (this is the <acronym>SQL</acronym> type
-     for character strings of length &le; 20), the type of <classname>SNO</classname> will be
+     for character strings of length &lt;&equal; 20),
+     the type of <classname>SNO</classname> will be
      <type>INTEGER</type>. With the assignment of a data type we also have selected
      a domain for an attribute. The domain of <classname>SNAME</classname> is the set of all
-     character strings of length &le; 20, the domain of <classname>SNO</classname> is the set of
+     character strings of length &lt;&equal; 20,
+     the domain of <classname>SNO</classname> is the set of
      all integer numbers.
     </para>
    </sect2>
@@ -339,7 +341,7 @@ attributes are taken from. We often write a relation scheme as
     Model</title>
 
    <para>
-    In section <xref linkend="formal-notion" endterm="formal-notion">
+    In <xref linkend="formal-notion" endterm="formal-notion">
     we defined the mathematical notion of
     the relational model. Now we know how the data can be stored using a
     relational data model but we do not know what to do with all these
@@ -481,19 +483,23 @@ attributes are taken from. We often write a relation scheme as
        projecting out the duplicate column.
        </para>
 
-       <para id="join-example">
-       Let's have a look at the tables that are produced by evaluating the steps
-       necessary for a join.
-       Let the following two tables be given:
+       <example id="join-example">
+       <title>An Inner Join</title>
 
-       <programlisting>
+       <para>
+        Let's have a look at the tables that are produced by evaluating the steps
+        necessary for a join.
+        Let the following two tables be given:
+
+        <programlisting>
          R   A | B | C      S   C | D | E
             ---+---+---        ---+---+---
              1 | 2 | 3          3 | a | b
              4 | 5 | 6          6 | c | d
              7 | 8 | 9
-       </programlisting>
-       </para>
+        </programlisting>
+       </para>
+       </example>
 
        <para>
        First we calculate the Cartesian product
index f0fdeb2..2f35e49 100644 (file)
 -      - thomas 1998-02-24
 -->
 
-<Chapter Id="postmaster">
-<Title>Starting <Application>postmaster</Application></Title>
-
-<Para>
-     Nothing can happen to a database unless the
-  <Application>postmaster</Application>
-     process  is  running.  As the site administrator, there
-     are a number  of  things  you  should  remember  before
-     starting  the  <Application>postmaster</Application>.   
-These are discussed in the installation and configuration sections
-of this manual.
-     However, if <ProductName>Postgres</ProductName> has been installed by following 
-     the installation instructions exactly  as  written,  the  
-     following  simple  command is all you should
-     need to start the <Application>postmaster</Application>:
-<ProgramListing>
-% postmaster
-</ProgramListing>
-     The <Application>postmaster</Application> occasionally prints out  
-messages  which
-     are  often helpful during troubleshooting.  If you wish
-     to view debugging messages from the <Application>postmaster</Application>, 
-you can
-     start  it with the -d option and redirect the output to
-     the log file:
-<ProgramListing>
-% postmaster -d >& pm.log &
-</ProgramListing>
-     If you do not wish to see these messages, you can type
-<ProgramListing>
-% postmaster -S
-</ProgramListing>
-     and the <Application>postmaster</Application> will be "S"ilent.  
-Notice that there
-     is no ampersand ("&amp") at the end of the last example.
-</Para>
-</Chapter>
-
-<Chapter Id="newuser">
-<Title>Adding and Deleting Users</Title>
-
-<Para>
-     <Application>createuser</Application> enables specific users to access
-     <ProductName>Postgres</ProductName>.  
-<Application>destroyuser</Application> removes  users  and
-     prevents them from accessing <ProductName>Postgres</ProductName>.  
-Note that these
-     commands only affect users with  respect  to  
-<ProductName>Postgres</ProductName>;
-     they  have  no  effect on users other privileges or status with regards
-to the underlying 
-     operating system.
-</Para>
-</Chapter>
-
-<Chapter Id="disk">
-<Title>Disk Management</Title>
-
-<Para>
-</Para>
-
-<Sect1>
-<Title>Alternate Locations</Title>
-
-<Para>
-It is possible to create a database in a location other than the default
-location for the installation. Remember that all database access actually
-occurs through the database backend, so that any location specified must
-be accessible by the backend.
-</para>
-<Para>
- Alternate database locations are created and referenced by an environment variable
- which gives the absolute path to the intended storage location.
-This environment variable must have been defined before the backend was started
-and must be writable by the postgres administrator account.
-Any valid environment variable name may be used to reference an alternate 
-location, although using variable name with a prefix of PGDATA is recommended
-to avoid confusion and conflict with other variables.
-</para>
-<Note>
-<Para>
- In previous versions of <ProductName>Postgres</ProductName>, 
-it was also permissable to use an absolute path name to specify an alternate storage location.
-The environment variable style of specification
-is to be preferred since it allows the site administrator more flexibility in
-managing disk storage.
-If you prefer using absolute paths, you may do so by defining 
-"ALLOW_ABSOLUTE_DBPATHS" and recompiling <ProductName>Postgres</ProductName>
- To do this, either add this line
-<ProgramListing>
+ <Chapter Id="newuser">
+  <Title>Adding and Deleting Users</Title>
+
+  <Para>
+   <Application>createuser</Application> enables specific users to access
+   <ProductName>Postgres</ProductName>.  
+   <Application>destroyuser</Application> removes  users  and
+   prevents them from accessing <ProductName>Postgres</ProductName>.  
+   Note that these
+   commands only affect users with  respect  to  
+   <ProductName>Postgres</ProductName>;
+   they  have  no  effect on users other privileges or status with regards
+   to the underlying 
+   operating system.
+  </Para>
+ </Chapter>
+
+ <Chapter Id="disk">
+  <Title>Disk Management</Title>
+
+  <Sect1>
+   <Title>Alternate Locations</Title>
+
+   <Para>
+    It is possible to create a database in a location other than the default
+    location for the installation. Remember that all database access actually
+    occurs through the database backend, so that any location specified must
+    be accessible by the backend.
+   </para>
+
+   <Para>
+    Alternate database locations are created and referenced by an environment variable
+    which gives the absolute path to the intended storage location.
+    This environment variable must have been defined before the backend was started
+    and must be writable by the postgres administrator account.
+    Any valid environment variable name may be used to reference an alternate 
+    location, although using variable name with a prefix of PGDATA is recommended
+    to avoid confusion and conflict with other variables.
+   </para>
+
+   <Note>
+    <Para>
+     In previous versions of <ProductName>Postgres</ProductName>, 
+     it was also permissable to use an absolute path name
+     to specify an alternate storage location.
+     The environment variable style of specification
+     is to be preferred since it allows the site administrator more flexibility in
+     managing disk storage.
+     If you prefer using absolute paths, you may do so by defining 
+     "ALLOW_ABSOLUTE_DBPATHS" and recompiling <ProductName>Postgres</ProductName>
+     To do this, either add this line
+
+     <ProgramListing>
 #define ALLOW_ABSOLUTE_DBPATHS 1
-</ProgramListing>
-to the file <filename>src/include/config.h</filename>, or by specifying
-<ProgramListing>
+     </ProgramListing>
+
+     to the file <filename>src/include/config.h</filename>, or by specifying
+
+     <ProgramListing>
  CFLAGS+= -DALLOW_ABSOLUTE_DBPATHS
-</ProgramListing>
-in your <filename>Makefile.custom</filename>.
-</Para>
-</Note>
-
-<Para>
-Remember that database creation is actually performed by the database backend.
-Therefore, any environment variable specifying an alternate location must have
-been defined before the backend was started. To define an alternate location
-PGDATA2 pointing to <filename>/home/postgres/data</filename>, first type
-<ProgramListing>
+     </ProgramListing>
+
+     in your <filename>Makefile.custom</filename>.
+    </Para>
+   </Note>
+
+   <Para>
+    Remember that database creation is actually performed by the database backend.
+    Therefore, any environment variable specifying an alternate location must have
+    been defined before the backend was started. To define an alternate location
+    PGDATA2 pointing to <filename>/home/postgres/data</filename>, first type
+
+    <ProgramListing>
 % setenv PGDATA2 /home/postgres/data
-</ProgramListing>
-to define the environment variable to be used with subsequent commands.
-Usually, you will want to define this variable in the 
-<ProductName>Postgres</ProductName> superuser's
-<filename>.profile</filename>
-or
-<filename>.cshrc</filename>
-initialization file to ensure that it is defined upon system startup. 
-Any environment variable can be used to reference alternate location, 
-although it is preferred that the variables be prefixed with "PGDATA" 
-to eliminate confusion and the possibility of conflicting with or 
-overwriting other variables.
-</para>
-<Para>
-To create a data storage area in PGDATA2, ensure
-that <filename>/home/postgres</filename> already exists and is writable 
-by the postgres administrator.
-Then from the command line, type
-<ProgramListing>
+    </ProgramListing>
+
+    to define the environment variable to be used with subsequent commands.
+    Usually, you will want to define this variable in the 
+    <ProductName>Postgres</ProductName> superuser's
+    <filename>.profile</filename>
+    or
+    <filename>.cshrc</filename>
+    initialization file to ensure that it is defined upon system startup. 
+    Any environment variable can be used to reference alternate location, 
+    although it is preferred that the variables be prefixed with "PGDATA" 
+    to eliminate confusion and the possibility of conflicting with or 
+    overwriting other variables.
+   </para>
+
+   <Para>
+    To create a data storage area in PGDATA2, ensure
+    that <filename>/home/postgres</filename> already exists and is writable 
+    by the postgres administrator.
+    Then from the command line, type
+
+    <ProgramListing>
 % setenv PGDATA2 /home/postgres/data
 % initlocation $PGDATA2
 Creating Postgres database system directory /home/postgres/data
 
 Creating Postgres database system directory /home/postgres/data/base
 
-</ProgramListing>
-</para>
-<Para>
-To test the new location, create a database <Database>test</Database> by typing
-<ProgramListing>
+    </ProgramListing>
+
+   </para>
+   <Para>
+    To test the new location, create a database <Database>test</Database> by typing
+
+    <ProgramListing>
 % createdb -D PGDATA2 test
 % destroydb test
-</ProgramListing>
-</para>
-</Sect1>
-</Chapter>
-
-<Chapter Id="trouble">
-<Title>Troubleshooting</Title>
-
-<Para>
-     Assuming that  your  site  administrator  has  properly
-     started  the  <Application>postmaster</Application>  process 
-and authorized you to use the database, you (as a user) may begin to start up
-     applications.   As previously mentioned, you should add
-     <filename>/usr/local/pgsql/bin</filename> to your  shell  search  path.
-     In  most  cases,  this  is all you should have to do in
-     terms of preparation.
-</para>
-<Para>
-     If  you get the following error message from a 
-<ProductName>Postgres</ProductName>
-     command (such as <Application>psql</Application> or 
-<Application>createdb</Application>):
-<ProgramListing>
-connectDB() failed: Is the postmaster running at 'localhost' on port '5432'?
-</ProgramListing>
-     it is usually because either the <Application>postmaster</Application> is not running,
- or you are attempting to connect to the wrong server host.
-     If you get the following error message:
-<ProgramListing>
-FATAL 1:Feb 17 23:19:55:process userid (2360) != database owner (268)
-</ProgramListing>
-     it means that the site administrator started the  <Application>postmaster</Application>
-  as  the  wrong user.  Tell him to restart it as
-     the <ProductName>Postgres</ProductName> superuser.
-</Para>
-</Chapter>
-
-<Chapter Id="manage-ag">
-<Title>Managing a Database</Title>
-
-<Para>
-     Now that <ProductName>Postgres</ProductName> is up and running we can create
-  some     databases  to  experiment  with.  Here, we describe the
-     basic commands for managing a database.
-</Para>
-
-<Sect1>
-<Title>Creating a Database</Title>
-
-<Para>
-     Let's say you want to create  a  database  named  mydb.
-     You can do this with the following command:
-<ProgramListing>
+    </ProgramListing>
+
+   </para>
+  </Sect1>
+ </Chapter>
+
+ <Chapter Id="manage-ag">
+  <Title>Managing a Database</Title>
+
+  <Para>
+   Now that <ProductName>Postgres</ProductName> is up and running we can create
+   some databases  to  experiment  with.  Here, we describe the
+   basic commands for managing a database.
+  </Para>
+
+  <Sect1>
+   <Title>Creating a Database</Title>
+
+   <Para>
+    Let's say you want to create  a  database  named  mydb.
+    You can do this with the following command:
+
+    <ProgramListing>
 % createdb mydb
-</ProgramListing>
-
-     <ProductName>Postgres</ProductName>  allows  you to create 
-any number of databases
-     at a  given  site  and  you  automatically  become  the
-     database  administrator  of  the database you just created.  
-Database names must  have  an  alphabetic  first
-     character and are limited to 16 characters in length.
-     Not  every  user has authorization to become a database
-     administrator.  If <ProductName>Postgres</ProductName> 
-refuses to create databases
-     for you, then the site administrator needs to grant you
-     permission to  create  databases.   Consult  your  site
-     administrator if this occurs.
-</Para>
-</Sect1>
-
-<Sect1>
-<Title>Accessing a Database</Title>
-
-<Para>
-     Once you have constructed a database, you can access it
-     by:
-
-<ItemizedList Mark="bullet" Spacing="compact">
-<ListItem>
-<Para>
-running the <ProductName>Postgres</ProductName>  terminal  monitor  program 
-(<Application>psql</Application>) which allows you to interactively
-        enter, edit, and execute <Acronym>SQL</Acronym> commands.
-</Para>
-</ListItem>
-<ListItem>
-<Para>
-      writing a  C  program  using  the  <literal>libpq</literal>  subroutine
-        library.   This  allows  you  to submit <Acronym>SQL</Acronym> commands
-        from C and get answers and status messages  back  to
-        your  program.   This interface is discussed further
-        in the <citetitle>PostgreSQL Programmer's Guide</citetitle>.
-</Para>
-</ListItem>
-</ItemizedList>
-
-     You might want to start up <Application>psql</Application>, 
-to try out  the  examples  in  this manual. It can be activated for the mydb
-     database by typing the command:
-<ProgramListing>
+    </ProgramListing>
+
+    <ProductName>Postgres</ProductName>  allows  you to create 
+    any number of databases
+    at a  given  site  and  you  automatically  become  the
+    database  administrator  of  the database you just created.  
+    Database names must  have  an  alphabetic  first
+    character and are limited to 16 characters in length.
+    Not  every  user has authorization to become a database
+    administrator.  If <ProductName>Postgres</ProductName> 
+    refuses to create databases
+    for you, then the site administrator needs to grant you
+    permission to  create  databases.   Consult  your  site
+    administrator if this occurs.
+   </Para>
+  </Sect1>
+
+  <Sect1>
+   <Title>Accessing a Database</Title>
+
+   <Para>
+    Once you have constructed a database, you can access it
+    by:
+
+    <ItemizedList Mark="bullet" Spacing="compact">
+     <ListItem>
+      <Para>
+       running the <ProductName>Postgres</ProductName>  terminal  monitor  program 
+       (<Application>psql</Application>) which allows you to interactively
+       enter, edit, and execute <Acronym>SQL</Acronym> commands.
+      </Para>
+     </ListItem>
+     <ListItem>
+      <Para>
+       writing a  C  program  using  the  <literal>libpq</literal>  subroutine
+       library.   This  allows  you  to submit <Acronym>SQL</Acronym> commands
+       from C and get answers and status messages  back  to
+       your  program.   This interface is discussed further
+       in the <citetitle>PostgreSQL Programmer's Guide</citetitle>.
+      </Para>
+     </ListItem>
+    </ItemizedList>
+
+    You might want to start up <Application>psql</Application>, 
+    to try out  the  examples  in  this manual. It can be activated for the mydb
+    database by typing the command:
+
+    <ProgramListing>
 % psql mydb
-</ProgramListing>
+    </ProgramListing>
 
-     You will be greeted with the following message:
-<ProgramListing>
+    You will be greeted with the following message:
+    <ProgramListing>
 Welcome to the Postgres interactive sql monitor:
 
   type \? for help on slash commands
@@ -257,70 +200,94 @@ Welcome to the Postgres interactive sql monitor:
 You are currently connected to the database: mydb
 
 mydb=>
-</ProgramListing>
-</Para>
-
-<Para>
-This prompt indicates that the terminal monitor is listening  
-to you and that you can type <Acronym>SQL</Acronym> queries into a
-     workspace maintained by the terminal monitor.
-     The <Application>psql</Application> program responds to escape
-  codes  that  begin
-     with  the  backslash  character, "\".  For example, you
-     can get help on the syntax of various 
-<ProductName>Postgres</ProductName> <Acronym>SQL</Acronym> commands by typing:
-<ProgramListing>
+    </ProgramListing>
+   </Para>
+
+   <Para>
+    This prompt indicates that the terminal monitor is listening  
+    to you and that you can type <Acronym>SQL</Acronym> queries into a
+    workspace maintained by the terminal monitor.
+    The <Application>psql</Application> program responds to escape
+    codes  that  begin
+    with  the  backslash  character, "\".  For example, you
+    can get help on the syntax of various 
+    <ProductName>Postgres</ProductName> <Acronym>SQL</Acronym> commands by typing:
+
+    <ProgramListing>
 mydb=> \h
-</ProgramListing>
+    </ProgramListing>
 
-     Once  you  have finished entering your queries into the
-     workspace, you can pass the contents of  the  workspace
-     to the <ProductName>Postgres</ProductName> server by typing:
-<ProgramListing>
+    Once  you  have finished entering your queries into the
+    workspace, you can pass the contents of  the  workspace
+    to the <ProductName>Postgres</ProductName> server by typing:
+
+    <ProgramListing>
 mydb=> \g
-</ProgramListing>
-
-     This  tells  the  server  to process the query.  If you
-     terminate your query with a semicolon, the  backslash-g is  not
-     necessary.   <Application>psql</Application> will automatically 
-process semicolon terminated queries.
-     To read queries from a file,  say  myFile,  instead  of
-     entering them interactively, type:
-<ProgramListing>
+    </ProgramListing>
+
+    This  tells  the  server  to process the query.  If you
+    terminate your query with a semicolon, the  backslash-g is  not
+    necessary.   <Application>psql</Application> will automatically 
+    process semicolon terminated queries.
+    To read queries from a file,  say  myFile,  instead  of
+    entering them interactively, type:
+
+    <ProgramListing>
 mydb=> \i fileName
-</ProgramListing>
+    </ProgramListing>
+
+    To get out of <Application>psql</Application> and return to UNIX, type
 
-     To get out of <Application>psql</Application> and return to UNIX, type
-<ProgramListing>
+    <ProgramListing>
 mydb=> \q
-</ProgramListing>
-
-     and  <Application>psql</Application>  will  quit  and  return  
-you to your command
-     shell. (For more escape codes, type backslash-h at  the  monitor
-     prompt.)
-     White  space  (i.e.,  spaces, tabs and newlines) may be
-     used freely in <Acronym>SQL</Acronym> queries.  
-Single-line comments  are  denoted  by
-     <Quote>--</Quote>.   Everything  after the dashes up to the end of the
-     line is ignored. Multiple-line comments, and comments within a line,
-     are denoted by <Quote>/* ... */</Quote>
-</Para>
-</Sect1>
+    </ProgramListing>
+
+    and  <Application>psql</Application>  will  quit  and  return  
+    you to your command
+    shell. (For more escape codes, type backslash-h at  the  monitor
+    prompt.)
+    White  space  (i.e.,  spaces, tabs and newlines) may be
+    used freely in <Acronym>SQL</Acronym> queries.  
+    Single-line comments  are  denoted  by two dashes
+    (<Quote>--</Quote>).   Everything  after the dashes up to the end of the
+    line is ignored. Multiple-line comments, and comments within a line,
+    are denoted by <Quote>/* ... */</Quote>, a convention borrowed
+    from <productname>Ingres</productname>.
+   </Para>
+  </Sect1>
      
-<Sect1>
-<Title>Destroying a Database</Title>
+  <Sect1>
+   <Title>Destroying a Database</Title>
 
-<Para>
-     If you are the database administrator for the  database
-     mydb,  you can destroy it using the following UNIX command:
-<ProgramListing>
+   <Para>
+    If you are the database administrator for the  database
+    mydb,  you can destroy it using the following UNIX command:
+
+    <ProgramListing>
 % destroydb mydb
-</ProgramListing>
-     This action physically removes all of  the  UNIX  files
-     associated  with  the database and cannot be undone, so
-     this should only be done with a  great  deal  of  forethought.
-</Para>
-</Sect1>
-
-</Chapter>
+    </ProgramListing>
+
+    This action physically removes all of  the  UNIX  files
+    associated  with  the database and cannot be undone, so
+    this should only be done with a  great  deal  of  forethought.
+   </Para>
+  </Sect1>
+
+ </Chapter>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:nil
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"./reference.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
+sgml-local-ecat-files:nil
+End:
+-->
diff --git a/doc/src/sgml/trouble.sgml b/doc/src/sgml/trouble.sgml
new file mode 100644 (file)
index 0000000..a1b1001
--- /dev/null
@@ -0,0 +1,166 @@
+ <Chapter Id="trouble">
+  <Title>Troubleshooting</Title>
+
+  <sect1>
+   <title>Client Connections</title>
+   <Para>
+    If  you get the following error message from a 
+    <ProductName>Postgres</ProductName>
+    command (such as <Application>psql</Application> or 
+    <Application>createdb</Application>):
+
+    <ProgramListing>
+connectDB() failed: Is the postmaster running at 'localhost' on port '5432'?
+    </ProgramListing>
+
+    it is usually because either the <Application>postmaster</Application> is not running,
+    or you are attempting to connect to the wrong server host.
+    If you get the following error message:
+
+    <ProgramListing>
+FATAL 1:Feb 17 23:19:55:process userid (2360) != database owner (268)
+    </ProgramListing>
+
+    it means that the site administrator started the  <Application>postmaster</Application>
+    as  the  wrong user.  Tell him to restart it as
+    the <ProductName>Postgres</ProductName> superuser.
+   </Para>
+  </sect1>
+
+  <sect1>
+   <title>Debugging Messages</title>
+
+   <para>
+    The <Application>postmaster</Application> occasionally prints out  
+    messages  which
+    are  often helpful during troubleshooting.  If you wish
+    to view debugging messages from the <Application>postmaster</Application>, 
+    you can
+    start  it with the -d option and redirect the output to
+    the log file:
+
+    <ProgramListing>
+% postmaster -d >& pm.log &
+    </ProgramListing>
+
+    If you do not wish to see these messages, you can type
+    <ProgramListing>
+% postmaster -S
+    </ProgramListing>
+    and the <Application>postmaster</Application> will be "S"ilent.  
+    Notice that there
+    is no ampersand ("&amp") at the end of the last example so
+    postmaster will be running in the foreground.
+   </Para>
+
+   <sect2 Id="pg-options-trouble">
+    <Title>pg_options</Title>
+
+    <Para>
+     <Note>
+      <Para>
+       Contributed by <ULink url="mailto:dz@cs.unitn.it">Massimo Dal Zotto</ULink>
+      </Para>
+     </Note>
+    </para>
+    <Para>
+     The optional file <filename>data/pg_options</filename> contains runtime
+     options used by the backend to control trace messages and other backend
+     tunable parameters.
+     What makes this file interesting is the fact that it is re-read by a backend
+     when it receives a SIGHUP signal, making thus possible to change run-time
+     options on the fly without needing to restart 
+     <productname>Postgres</productname>.
+     The options specified in this file may be debugging flags used by the trace
+     package (<filename>backend/utils/misc/trace.c</filename>) or numeric
+     parameters which can be used by the backend to control its behaviour.
+     New options and parameters must be defined in
+     <filename>backend/utils/misc/trace.c</filename> and
+     <filename>backend/include/utils/trace.h</filename>.
+    </para>
+
+   <para>
+    pg_options can also be specified with the <option>-T</option> switch of 
+    <productname>Postgres</productname>:
+
+    <programlisting>
+postgres <replaceable>options</replaceable> -T "verbose=2,query,hostlookup-"
+    </programlisting>
+   </para>
+
+   <Para>
+    The functions used for printing errors and debug messages can now make use
+    of the <citetitle>syslog(2)</citetitle> facility. Message printed to stdout
+    or stderr are prefixed by a timestamp containing also the backend pid:
+
+    <programlisting>
+#timestamp          #pid    #message
+980127.17:52:14.173 [29271] StartTransactionCommand
+980127.17:52:14.174 [29271] ProcessUtility: drop table t;
+980127.17:52:14.186 [29271] SIIncNumEntries: table is 70% full
+980127.17:52:14.186 [29286] Async_NotifyHandler
+980127.17:52:14.186 [29286] Waking up sleeping backend process
+980127.19:52:14.292 [29286] Async_NotifyFrontEnd
+980127.19:52:14.413 [29286] Async_NotifyFrontEnd done
+980127.19:52:14.466 [29286] Async_NotifyHandler done
+    </programlisting>
+   </para>
+
+   <para>
+    This format improves readability of the logs and allows people to understand
+    exactly which backend is doing what and at which time. It also makes
+    easier to write simple awk or perl scripts which monitor the log to
+    detect database errors or problem, or to compute transaction time statistics.
+   </para>
+
+   <para>
+    Messages printed to syslog use the log facility LOG_LOCAL0.
+    The use of syslog can be controlled with the syslog pg_option.
+    Unfortunately many functions call directly <function>printf()</function>
+    to print their messages to stdout or stderr and this output can't be
+    redirected to syslog or have timestamps in it. 
+    It would be advisable that all calls to printf would be replaced with the
+    PRINTF macro and output to stderr be changed to use EPRINTF instead so that
+    we can control all output in a uniform way.
+   </Para>
+
+    <para>
+     The format of the <filename>pg_options</filename> file is as follows:
+
+     <programlisting>
+# <replaceable>comment</replaceable>
+<replaceable>option</replaceable>=<replaceable class="parameter">integer_value</replaceable>  # set value for <replaceable>option</replaceable>
+<replaceable>option</replaceable>                # set <replaceable>option</replaceable> = 1
+<replaceable>option</replaceable>+               # set <replaceable>option</replaceable> = 1
+<replaceable>option</replaceable>-               # set <replaceable>option</replaceable> = 0
+     </programlisting>
+
+     Note that <replaceable class="parameter">keyword</replaceable> can also be
+     an abbreviation of the option name defined in
+     <filename>backend/utils/misc/trace.c</filename>.
+    </Para>
+
+    <Para>
+     Refer to <xref linkend="pg-options-title" endterm="pg-options-title">
+     for a complete list of option keywords and possible values.
+    </para>
+   </sect2>
+  </sect1>
+ </Chapter>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:nil
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"./reference.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
+sgml-local-ecat-files:nil
+End:
+-->
index 3cedf0a..f51b941 100644 (file)
 
 <!-- Title information -->
 
-<Title>PostgreSQL Tutorial</Title>
-<BookInfo>
-    <ReleaseInfo>Covering v6.3 for general release</ReleaseInfo>
-    <BookBiblio>
-    <AuthorGroup>
-      <CorpAuthor>The PostgreSQL Development Team</CorpAuthor>
-    </AuthorGroup>
+ <Title>PostgreSQL Tutorial</Title>
+ <BookInfo>
+  <ReleaseInfo>Covering v6.5 for general release</ReleaseInfo>
+  <BookBiblio>
+   <AuthorGroup>
+    <CorpAuthor>The PostgreSQL Development Team</CorpAuthor>
+   </AuthorGroup>
 <!-- editor in authorgroup is not supported
     <AuthorGroup>
 -->
-      <Editor>
-        <FirstName>Thomas</FirstName>
-        <SurName>Lockhart</SurName>
-        <Affiliation>
-          <OrgName>Caltech/JPL</OrgName>
-        </Affiliation>
-      </Editor>
+   <Editor>
+    <FirstName>Thomas</FirstName>
+    <SurName>Lockhart</SurName>
+    <Affiliation>
+     <OrgName>Caltech/JPL</OrgName>
+    </Affiliation>
+   </Editor>
 <!--
     </AuthorGroup>
 -->
     <AuthorInitials>TGL</AuthorInitials>
 -->
 
-    <Date>(last updated 1998-02-23)</Date>
-    </BookBiblio>
+   <Date>(last updated 1999-05-19)</Date>
+  </BookBiblio>
 
-<LegalNotice>
-<Para>
-<ProductName>PostgreSQL</ProductName> is copyright (C) 1998 by the Postgres Global Development Group.
-</Para>
-</LegalNotice>
+  <LegalNotice>
+   <Para>
+    <ProductName>PostgreSQL</ProductName> is copyright (&copy;) 1998-9
+    by the Postgres Global Development Group.
+   </Para>
+  </LegalNotice>
 
-</BookInfo>
+ </BookInfo>
 
 <!--
 <TOC> </TOC>
@@ -73,30 +74,48 @@ Your name here...
 </Dedication>
 -->
 
-<Preface>
-<Title>Summary</Title>
-
-<Para>
-<ProductName>Postgres</ProductName>, 
- developed originally in the UC Berkeley Computer Science Department,
- pioneered many of the object-relational concepts
- now becoming available in some commercial databases.
-It provides SQL92/SQL3 language support,
- transaction integrity, and type extensibility.
- <ProductName>PostgreSQL</ProductName> is a public-domain, open source descendant
- of this original Berkeley code.
-</Para>
-</Preface>
-
-&intro;
-&arch;
-&start;
-&query;
-&advanced;
-
-&biblio;
+ <Preface>
+  <Title>Summary</Title>
+
+  <Para>
+   <ProductName>Postgres</ProductName>, 
  developed originally in the UC Berkeley Computer Science Department,
  pioneered many of the object-relational concepts
  now becoming available in some commercial databases.
+   It provides SQL92/SQL3 language support,
  transaction integrity, and type extensibility.
  <ProductName>PostgreSQL</ProductName> is a public-domain, open source descendant
  of this original Berkeley code.
+  </Para>
+ </Preface>
+
+  &intro;
+  &arch;
+  &start;
+  &query;
+  &advanced;
+
+  &biblio;
 
+<!--
 <INDEX> </INDEX>
+-->
 
 </Book>
 
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:nil
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:"./reference.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
+sgml-local-ecat-files:nil
+End:
+-->
index 87278c7..ae5dd13 100644 (file)
@@ -1,11 +1,19 @@
 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.8 1999/05/04 02:26:06 thomas Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.9 1999/05/20 05:39:29 thomas Exp $
 
 Postgres User's Manual.
 Derived from postgres.sgml.
 thomas 1998-02-24
 
 $Log: user.sgml,v $
+Revision 1.9  1999/05/20 05:39:29  thomas
+Rearrange and consolidate the Admin Guide.
+Add reference pages for utilities and remove standalone chapters for same.
+Add material for an appendix on date/time properties, but not yet
+ integrated with the User's Guide.
+Break up the former chapter on pg_options
+ into Admin and Programmer's Guides.
+
 Revision 1.8  1999/05/04 02:26:06  thomas
 Include new introductory chapter on SQL from Stefan S.
 Should this be in the tutorial instead?
@@ -48,9 +56,6 @@ Move SQL reference pages up into the User's Guide.
 <!entity keys     SYSTEM "keys.sgml">
 <!entity manage   SYSTEM "manage.sgml">
 <!entity oper     SYSTEM "oper.sgml">
-<!entity pgaccess SYSTEM "pgaccess.sgml">
-<!entity psql     SYSTEM "psql.sgml">
-<!entity query-ug SYSTEM "query-ug.sgml">
 <!entity sql      SYSTEM "sql.sgml">
 <!entity storage  SYSTEM "storage.sgml">
 <!entity syntax   SYSTEM "syntax.sgml">
@@ -65,42 +70,42 @@ Move SQL reference pages up into the User's Guide.
 
 <!-- Title information -->
 
-<Title>PostgreSQL User's Guide</Title>
-<BookInfo>
-    <ReleaseInfo>Covering v6.4 for general release</ReleaseInfo>
-    <BookBiblio>
-    <AuthorGroup>
-      <CorpAuthor>The PostgreSQL Development Team</CorpAuthor>
-    </AuthorGroup>
+ <Title>PostgreSQL User's Guide</Title>
+ <BookInfo>
+  <ReleaseInfo>Covering v6.5 for general release</ReleaseInfo>
+  <BookBiblio>
+   <AuthorGroup>
+    <CorpAuthor>The PostgreSQL Development Team</CorpAuthor>
+   </AuthorGroup>
 <!-- editor in authorgroup is not supported
-    <AuthorGroup>
+  <AuthorGroup>
 -->
-      <Editor>
-        <FirstName>Thomas</FirstName>
-        <SurName>Lockhart</SurName>
-        <Affiliation>
-          <OrgName>Caltech/JPL</OrgName>
-        </Affiliation>
-      </Editor>
+   <Editor>
+    <FirstName>Thomas</FirstName>
+    <SurName>Lockhart</SurName>
+    <Affiliation>
+     <OrgName>Caltech/JPL</OrgName>
+    </Affiliation>
+   </Editor>
 <!--
-    </AuthorGroup>
+  </AuthorGroup>
 -->
  
 <!--
-    <AuthorInitials>TGL</AuthorInitials>
+  <AuthorInitials>TGL</AuthorInitials>
 -->
 
-    <Date>(last updated 1998-02-23)</Date>
-    </BookBiblio>
+   <Date>(last updated 1999-05-19)</Date>
+  </BookBiblio>
 
-<LegalNotice>
-<Para>
-<ProductName>PostgreSQL</ProductName> is copyright (C) 1998 
-by the Postgres Global Development Group.
-</Para>
-</LegalNotice>
+  <LegalNotice>
+   <Para>
+    <ProductName>PostgreSQL</ProductName> is copyright (&copy;) 1998-9
+    by the Postgres Global Development Group.
+   </Para>
+  </LegalNotice>
 
-</BookInfo>
+ </BookInfo>
 
 <!--
 <TOC> </TOC>
@@ -115,42 +120,39 @@ Your name here...
 </Dedication>
 -->
 
-<preface id="preface">
-<Title>Summary</Title>
-
-<Para>
-<ProductName>Postgres</ProductName>, 
- developed originally in the UC Berkeley Computer Science Department,
- pioneered many of the object-relational concepts
- now becoming available in some commercial databases.
-It provides SQL92/SQL3 language support,
- transaction integrity, and type extensibility.
- <ProductName>PostgreSQL</ProductName> is a public-domain, open source descendant
- of this original Berkeley code.
-</Para>
-</Preface>
-
 &intro;
+ <preface id="preface">
+  <Title>Summary</Title>
+
+  <Para>
+   <ProductName>Postgres</ProductName>, 
  developed originally in the UC Berkeley Computer Science Department,
  pioneered many of the object-relational concepts
  now becoming available in some commercial databases.
+   It provides SQL92/SQL3 language support,
  transaction integrity, and type extensibility.
  <ProductName>PostgreSQL</ProductName> is a public-domain, open source descendant
  of this original Berkeley code.
+  </Para>
+ </Preface>
+
+ &intro;
  &sql;
-  &environ;
- &manage;
  &syntax;
 &datatype;
 &oper;
 &func;
 &typeconv;
+ &datatype;
+ &oper;
+ &func;
+ &typeconv;
  &keys;
-  &array;
-  &inherit;
-  &query-ug;
-  &storage;
-  &psql;
-  &pgaccess;
-  &commands;
-
-<!--
-&contacts;
--->
+ &array;
+ &inherit;
+ &environ;
+ &manage;
+ &storage;
+ &commands;
+ <!--
+ &contacts;
+ -->
 
  &biblio;