c8h4/postgresql
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

Minor editing and markup changes as a result of preparing the Postscript

Browse source 
documentation for v6.4.
Bigger updates to the installation instructions (install and config).
This commit is contained in:
Thomas G. Lockhart 1998-10-30 19:37:19 +00:00
parent 3d83e28b2b
commit f1f9ec3344
23 changed files with 855 additions and 675 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
doc/src/sgml/Makefile
View file

@ -8,7 +8,7 @@
#
#
# IDENTIFICATION
# $Header: /cvsroot/pgsql/doc/src/sgml/Makefile,v 1.6 1998/09/30 05:41:39 thomas Exp $
# $Header: /cvsroot/pgsql/doc/src/sgml/Makefile,v 1.7 1998/10/30 19:36:51 thomas Exp $
#
#----------------------------------------------------------------------------
@ -119,5 +119,5 @@ distclean::
# Graphics
%.gif:
cp -p ../graphics/%.gif .
cp -p ../graphics/$@ .

23
doc/src/sgml/admin.sgml
View file

@ -1,11 +1,16 @@
<!--
$header$
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.7 1998/10/30 19:36:53 thomas Exp $
Postgres Administrator's Guide.
Derived from postgres.sgml.
thomas 1998-02-27
thomas 1998-10-27
$Log: admin.sgml,v $
Revision 1.7 1998/10/30 19:36:53 thomas
Minor editing and markup changes as a result of preparing the Postscript
documentation for v6.4.
Bigger updates to the installation instructions (install and config).
$log$
-->
@ -38,7 +43,7 @@ $log$
<Title>PostgreSQL Administrator's Guide</Title>
<BookInfo>
<ReleaseInfo>Covering v6.3 for general release</ReleaseInfo>
<ReleaseInfo>Covering v6.4 for general release</ReleaseInfo>
<BookBiblio>
<AuthorGroup>
<CorpAuthor>The PostgreSQL Development Team</CorpAuthor>
@ -61,12 +66,13 @@ $log$
<AuthorInitials>TGL</AuthorInitials>
-->
<Date>(last updated 1998-02-23)</Date>
<Date>(last updated 1998-10-27)</Date>
</BookBiblio>
<LegalNotice>
<Para>
<ProductName>PostgreSQL</ProductName> is copyright (C) 1998 by the Postgres Global Development Group.
<ProductName>PostgreSQL</ProductName> is copyright (C) 1998
by the Postgres Global Development Group.
</Para>
</LegalNotice>
@ -114,8 +120,9 @@ It provides SQL92/SQL3 language support,
&biblio;
<!-- Don't bother with an index until we get some index entries.
-- - thomas 1998-10-26
<!--
Don't bother with an index until we get some index entries.
- thomas 1998-10-26
<index id="index">
</index>
-->

2
doc/src/sgml/config.sgml
View file

@ -1,5 +1,5 @@
<chapter id="config">
<title>Configuration Options</title>
<title id="install-config">Configuration Options</title>
<sect1>
<title>Parameters for Configuration (<application>configure</application>)</title>

35
doc/src/sgml/datatype.sgml
View file

@ -386,8 +386,8 @@ should use the monetary conventions defined for
<Para>
<TABLE TOCENTRY="1">
<TITLE><ProductName>Postgres</ProductName> Numeric Types</TITLE>
<TITLEABBREV>Numerics</TITLEABBREV>
<TITLE><ProductName>Postgres</ProductName> Monetary Types</TITLE>
<TITLEABBREV>Money</TITLEABBREV>
<TGROUP COLS="4">
<THEAD>
<ROW>
@ -1461,7 +1461,7 @@ The <Type>inet</Type> type stores hosts and networks in CIDR notation.
<Para>
<TABLE TOCENTRY="1">
<TITLE><ProductName>Postgres</ProductName>IP Version 4 Type</TITLE>
<TITLE><ProductName>Postgres</ProductName>IP Version 4 Types</TITLE>
<TITLEABBREV>IPV4</TITLEABBREV>
<TGROUP COLS="4">
<THEAD>
@ -1500,51 +1500,48 @@ network and "/y" is the number of bits in the netmask.
If the "/y" part is left off, it is calculated using assumptions from
the old class system except that it is extended to include at least
all of the octets in the input.
Here are some examples.
<!-- There's a lot of examples here.
-- Take some out if you think there are too many...
-->
Here are some examples:
<Para>
<TABLE TOCENTRY="1">
<TGROUP COLS="4">
<TITLE><ProductName>Postgres</ProductName>IP Types Examples</TITLE>
<TGROUP COLS="2">
<THEAD>
<ROW>
<ENTRY>Input</ENTRY>
<ENTRY>Output</ENTRY>
<ENTRY>CIDR Input</ENTRY>
<ENTRY>CIDR Displayed</ENTRY>
</THEAD>
<TBODY>
<ROW>
<ENTRY>select '192.168.1'::cidr</ENTRY>
<ENTRY>192.168.1</ENTRY>
<ENTRY>192.168.1/24</ENTRY>
</ROW>
<ROW>
<ENTRY>select '192.168'::cidr</ENTRY>
<ENTRY>192.168</ENTRY>
<ENTRY>192.168.0/24</ENTRY>
</ROW>
<ROW>
<ENTRY>select '128.1'::cidr</ENTRY>
<ENTRY>128.1</ENTRY>
<ENTRY>128.1/16</ENTRY>
</ROW>
<ROW>
<ENTRY>select '128':::cidr</ENTRY>
<ENTRY>128</ENTRY>
<ENTRY>128.0/16</ENTRY>
</ROW>
<ROW>
<ENTRY>select '128.1.2'::cidr</ENTRY>
<ENTRY>128.1.2</ENTRY>
<ENTRY>128.1.2/24</ENTRY>
</ROW>
<ROW>
<ENTRY>select '10.1.2'::cidr</ENTRY>
<ENTRY>10.1.2</ENTRY>
<ENTRY>10.1.2/24</ENTRY>
</ROW>
<ROW>
<ENTRY>select '10.1'::cidr</ENTRY>
<ENTRY>10.1</ENTRY>
<ENTRY>10.1/16</ENTRY>
</ROW>
<ROW>
<ENTRY>select '10'::cidr</ENTRY>
<ENTRY>10</ENTRY>
<ENTRY>10/8</ENTRY>
</ROW>
</TBODY>

543
doc/src/sgml/docguide.sgml
View file

@ -1,9 +1,14 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.10 1998/10/25 00:25:30 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/docguide.sgml,v 1.11 1998/10/30 19:36:57 thomas Exp $
Documentation Guide
Thomas Lockhart
$Log: docguide.sgml,v $
Revision 1.11 1998/10/30 19:36:57 thomas
Minor editing and markup changes as a result of preparing the Postscript
documentation for v6.4.
Bigger updates to the installation instructions (install and config).
Revision 1.10 1998/10/25 00:25:30 thomas
Update info on source files for v6.4.
Should add/change ToDo list some more before release...
@ -48,6 +53,9 @@ It should be able to answer
common questions and to allow a user to find those answers on his own
without resorting to mailing list support.
<sect1>
<title>Documentation Roadmap</title>
<para>
<productname>Postgres</productname> has four primary documentation
formats:
@ -67,66 +75,6 @@ Hardcopy, for in-depth reading and reference.
</para></listitem>
</itemizedlist>
<para>
Documentation sources include plain text files, man pages, and html. However,
most new <productname>Postgres</productname> documentation will be written using the
<firstterm>Standard Generalized Markup Language</firstterm>
(<acronym>SGML</acronym>)
<ulink url="http://www.ora.com/davenport/"> <productname>DocBook</productname></ulink>
<firstterm>Document Type Definition</firstterm> (<acronym>DTD</acronym>).
Much of the existing documentation has been or will be converted to <acronym>SGML</acronym>.
</para>
<sect1>
<title>Documentation Roadmap</title>
<para>
Documentation has accumulated from several sources. As we integrate
and assimilate existing documentation into a coherent documentation set,
the older versions will become obsolete and will be removed from the
distribution. However, this will not happen immediately, and will not
happen to all documents at the same time. To ease the transition, and
to help guide developers and writers, we have defined a transition roadmap.
<para>
Here is the documentation plan for v6.4:
<itemizedlist>
<listitem>
<para>
Convert <ulink url="sferac@bo.nettuno.it">Jose Soares Da Silva</ulink>'s
text-based reference pages to <acronym>SGML</acronym>
reference sections for the User's Guide.
<ulink url="olly@lfix.co.uk">Oliver Elphick</ulink> is working on this
and it is roughly half-way completed.
<listitem>
<para>
Write more sections for the User's Guide covering areas outside the reference pages.
This would include introductory information and suggestions for approaches to typical
design problems.
<listitem>
<para>
Merge information in the existing man pages into the reference pages and User's Guide.
<listitem>
<para>
Convert the new sgml reference pages to new man pages, replacing the existing man pages.
Brandon Ibach is working on the conversion filter.
<listitem>
<para>
Rebuild the User's Guide, Reference Guide, and Administrator's Guide
(the admin guide only if we get release notes and installation
information updated in <acronym>SGML</acronym>).
</itemizedlist>
<itemizedlist>
<listitem><para>
</para></listitem>
</itemizedlist>
<para>
<table tocentry="1">
<title><ProductName>Postgres</ProductName> Documentation Products</title>
@ -161,9 +109,152 @@ Description
</tgroup>
</table>
<para>
There are man pages available for installation, as well as a large number
of plain-text README-type files throughout the <productname>Postgres</productname>
source tree.
<sect1>
<title>Documentation Sources</title>
<para>
Documentation sources include plain text files, man pages, and html. However,
most new <productname>Postgres</productname> documentation will be written using the
<firstterm>Standard Generalized Markup Language</firstterm>
(<acronym>SGML</acronym>)
<ulink url="http://www.ora.com/davenport/"> <productname>DocBook</productname></ulink>
<firstterm>Document Type Definition</firstterm> (<acronym>DTD</acronym>).
Much of the existing documentation has been or will be converted to <acronym>SGML</acronym>.
<para>
The purpose of <acronym>SGML</acronym> is to allow an author to
specify the structure and content of a document (e.g. using the
<productname>DocBook</productname> <acronym>DTD</acronym>), and to
have the document style define how that content is rendered into a
final form (e.g. using Norm Walsh's stylesheets).
<para>
Documentation has accumulated from several sources. As we integrate
and assimilate existing documentation into a coherent documentation set,
the older versions will become obsolete and will be removed from the
distribution. However, this will not happen immediately, and will not
happen to all documents at the same time. To ease the transition, and
to help guide developers and writers, we have defined a transition roadmap.
<para>
Here is the documentation plan for v6.5:
<itemizedlist>
<listitem>
<para>
Start compiling index information for the User's and Administrator's Guides.
<listitem>
<para>
Write more sections for the User's Guide covering areas outside the reference pages.
This would include introductory information and suggestions for approaches to typical
design problems.
<listitem>
<para>
Merge information in the existing man pages into the reference pages and User's Guide.
Condense the man pages down to reminder information, with references into the
primary doc set.
<listitem>
<para>
Convert the new sgml reference pages to new man pages, replacing the existing man pages.
<listitem>
<para>
Convert all source graphics to CGM format files for portability. Currently we mostly have
Applix Graphics sources from which we can generate .gif output. One graphic is only
available in .gif and .ps, and should be redrawn or removed.
</itemizedlist>
<sect2>
<title>Document Structure</title>
<para>
There are currently five separate documents written in DocBook. Each document
has a container source document which defines the DocBook environment and other
document source files. These primary source files are located in
<filename>doc/src/sgml/</filename>, along with many of the other source files
used for the documentation. The primary source files are:
<variablelist>
<varlistentry>
<term>postgres.sgml</term>
<listitem>
<para>
This is the integrated document, including all other documents as parts.
Output is generated in <acronym>HTML</acronym> since the browser interface
makes it easy to move around all of the documentation by just clicking.
The other documents are available in both <acronym>HTML</acronym> and hardcopy.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>tutorial.sgml</term>
<listitem>
<para>
The introductory tutorial, with examples. Does not include programming topics,
and is intended to help a reader unfamiliar with <acronym>SQL</acronym>.
This is the "getting started" document.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>user.sgml</term>
<listitem>
<para>
The User's Guide. Includes information on data types and user-level interfaces.
This is the place to put information on "why".
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>reference.sgml</term>
<listitem>
<para>
The Reference Manual. Includes <productname>Postgres</productname> <acronym>SQL</acronym> syntax.
This is the place to put information on "how".
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>programming.sgml</term>
<listitem>
<para>
The Programmer's Guide. Includes information on <productname>Postgres</productname>
extensibility and on the programming interfaces.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>admin.sgml</term>
<listitem>
<para>
The Administrator's Guide. Include installation and release notes.
</para>
</listitem>
</varlistentry>
</variablelist>
<!--
Disable for the hardcopy production release.
Too much tabular info and not very helpful in hardcopy.
- thomas 1998-10-27
<sect2>
<title>Documentation Files</title>
<para>
<table tocentry="1">
<title><ProductName>Postgres</ProductName> Documentation Sources</title>
@ -333,8 +424,8 @@ Status
</tgroup>
</table>
<sect1>
<title>Document Conversion Status</title>
<sect2>
<title>Document Conversion</title>
<para>
<table tocentry="1">
@ -579,82 +670,10 @@ Status
</tgroup>
</table>
<sect2>
<title>Document Structure</title>
<para>
There are currently five separate documents written in DocBook. Each document
has a container source document which defines the DocBook environment and other
document source files. These primary source files are located in
<filename>doc/src/sgml/</filename>, along with many of the other source files
used for the documentation. The primary source files are:
<variablelist>
<varlistentry>
<term>postgres.sgml</term>
<listitem>
<para>
This is the integrated document, including all other documents as parts.
Output is generated in <acronym>HTML</acronym> since the browser interface
makes it easy to move around all of the documentation by just clicking.
The other documents are available in both <acronym>HTML</acronym> and hardcopy.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>tutorial.sgml</term>
<listitem>
<para>
The introductory tutorial, with examples. Does not include programming topics,
and is intended to help a reader unfamiliar with <acronym>SQL</acronym>.
This is the "getting started" document.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>user.sgml</term>
<listitem>
<para>
The User's Guide. Includes information on data types and user-level interfaces.
This is the place to put information on "why".
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>reference.sgml</term>
<listitem>
<para>
The Reference Manual. Includes <productname>Postgres</productname> <acronym>SQL</acronym> syntax.
This is the place to put information on "how".
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>programming.sgml</term>
<listitem>
<para>
The Programmer's Guide. Includes information on <productname>Postgres</productname>
extensibility and on the programming interfaces.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>admin.sgml</term>
<listitem>
<para>
The Administrator's Guide. Include installation and release notes.
</para>
</listitem>
</varlistentry>
</variablelist>
-->
<sect1>
<title>Introduction</title>
<title>The Documentation Project</title>
<para>
Packaged documentation is available in both
@ -708,9 +727,9 @@ exporting as a Postscript file.</para>
for several reasons, including the inability to make minor format
fixes before committing to hardcopy and generally inadequate table
support in the <productname>TeX</productname>
stylesheets.</para></sect1>
stylesheets.</para>
<sect1>
<sect2>
<title>Styles and Conventions</title>
<para>
@ -756,80 +775,6 @@ be included below.
</para>
-->
</sect1>
<sect1>
<title>Document Writing</title>
<sect2>
<title>Document Structure</title>
<para>
There are currently five separate documents written in DocBook. Each document
has a container source document which defines the DocBook environment and other
document source files. These primary source files are located in
<filename>doc/src/sgml/</filename>, along with many of the other source files
used for the documentation. The primary source files are:
<variablelist>
<varlistentry>
<term>postgres.sgml</term>
<listitem>
<para>
This is the integrated document, including all other documents.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>tutorial.sgml</term>
<listitem>
<para>
The introductory tutorial, with examples. Does not include programming topics,
and is intended to help get someone unfamiliar with <acronym>SQL</acronym> started.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>user.sgml</term>
<listitem>
<para>
The User's Guide. Includes information on data types and user-level interfaces.
This is the place to put information on "why".
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>reference.sgml</term>
<listitem>
<para>
The Reference Manual. Includes <productname>Postgres</productname> <acronym>SQL</acronym> syntax.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>programming.sgml</term>
<listitem>
<para>
The Programmer's Guide. Includes information on <productname>Postgres</productname>
extensibility and on the programming interfaces.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>admin.sgml</term>
<listitem>
<para>
The Administrator's Guide. Include installation and release notes.
</para>
</listitem>
</varlistentry>
</variablelist>
<sect2>
<title>Authoring Tools</title>
@ -925,13 +870,14 @@ by typing
</para></sect1>
<sect1>
<title>Hardcopy Generation for v6.3</title>
<title>Hardcopy Generation for v6.4</title>
<para>
The hardcopy Postscript documentation is generated by converting the
<acronym>SGML</acronym> source code to <acronym>RTF</acronym>, then
importing into Applixware. After a little cleanup (see the following
section) the output is "printed" to a postscript file.</para>
importing into <productname>ApplixWare-4.4.1</productname>.
After a little cleanup (see the following
section) the output is "printed" to a postscript file.
<para>
Some figures were redrawn to avoid having bitmap
@ -941,9 +887,11 @@ was not time to redraw it. It was converted to fit using the
following commands:
<programlisting>
% convert -v -geometry 400x400'>' figure03.gif con.gif
% convert -v -crop 400x380 con.gif connections.gif
</programlisting></para>
% convert -monochrome -v -geometry 500x500'>' catalogs.ps catalogs.gif
% convert -v -crop 400x500 catalogs.gif catalogs-cropped.gif
</programlisting>
</para>
<sect2>
<title><acronym>RTF</acronym> Cleanup Procedure</title>
@ -1069,7 +1017,7 @@ described below.</para>
We understand that there are some other packaged distributions for
these tools. <productname>FreeBSD</productname> seems to have them
available. Please report package status to the docs mailing list and
we will include that information here.</para>
we will include that information here.
<sect2>
<title><acronym>RPM</acronym> installation on
@ -1085,10 +1033,17 @@ and related packages.
<sect2>
<title>Manual installation of tools</title>
<para>This is a brief run-through of the process of obtaining and
<para>
This is a brief run-through of the process of obtaining and
installing the software you'll need to edit DocBook source with Emacs
and process it with Norman Walsh's DSSSL style sheets to create <acronym>HTML</acronym>
and <acronym>RTF</acronym>.</para>
and <acronym>RTF</acronym>.
<para>
These instructions do not cover new <application>jade</application>/DocBook
support in the <productname>sgml-tools</productname> package. The authors have
not tried this package since it adopted DocBook, but it is almost certainly
a good candidate for use.
<sect3><title>Prerequisites</title>
@ -1114,9 +1069,9 @@ James Clark's <productname>Jade</productname> version 1.1</ulink>
<productname>DocBook</productname> version 3.0</ulink>
</para></listitem>
<listitem>
<para><ulink url="http://nwalsh.com/docbook/dsssl/db107.zip">
<para><ulink url="http://nwalsh.com/docbook/dsssl/db119.zip">
Norman Walsh's <productname>Modular Stylesheets</productname>
version 1.07</ulink>
version 1.19</ulink>
</para></listitem>
<listitem>
<para><ulink url="ftp://ftp.lysator.liu.se/pub/sgml/psgml-1.0.1.tar.gz">
@ -1145,22 +1100,30 @@ Steve Pepper's Whirlwind Guide</ulink></para></listitem>
Robin Cover's database of <acronym>SGML</acronym> software</ulink></para></listitem>
</itemizedlist>
</para>
</sect3>
<sect3><title>Installing Jade</title>
<sect3>
<title>Installing Jade</title>
<para>
<para>First, read the installation instructions at the above listed
URL.</para>
<procedure>
<title>Installing Jade</title>
<para>Unzip the distribution kit in a suitable place. The command to do
<step performance="required">
<para>
Read the installation instructions at the above listed
URL.
<step performance="required">
<para>
Unzip the distribution kit in a suitable place. The command to do
this will be something like
<programlisting>
unzip -aU jade1_1.zip
</programlisting>
</para>
<step performance="required">
<para><productname>Jade</productname> is not built using
<productname>GNU Autoconf</productname>, so you'll need to edit a
<filename>Makefile</filename> yourself. Since James Clark has been
@ -1202,17 +1165,24 @@ doesn't need the above settings for the math library and the
<filename>Makefile</filename>.
</para>
<para>Now type <command>make</command> to build Jade and the various
<step performance="required">
<para>Type <command>make</command> to build Jade and the various
<productname>SP</productname> tools.</para>
<step performance="required">
<para>Once the software is built, <command>make install</command> will
do the obvious.</para>
</sect3>
</procedure>
<sect3><title>Installing the <productname>DocBook</productname>
<acronym>DTD</acronym> kit</title>
<sect3>
<title>Installing the <productname>DocBook</productname> <acronym>DTD</acronym> Kit</title>
<para>
<procedure>
<title>Installing the <productname>DocBook</productname> <acronym>DTD</acronym> Kit</title>
<step performance="required">
<para>You'll want to place the files that make up the
<productname>DocBook</productname> <acronym>DTD</acronym> kit in the
directory you built <productname>Jade</productname> to expect them in,
@ -1234,6 +1204,9 @@ the former, by giving it the single line of content:
<programlisting>
CATALOG /usr/local/share/sgml/CATALOG
</programlisting>
<step performance="required">
<para>
The <filename>CATALOG</filename> file should then contain three types
of lines. The first is the (optional) <acronym>SGML</acronym>
declaration, thus:
@ -1250,6 +1223,9 @@ PUBLIC "-//Davenport//ELEMENTS DocBook Information Pool V3.0//EN" dbpool.mod
PUBLIC "-//Davenport//ELEMENTS DocBook Document Hierarchy V3.0//EN" dbhier.mod
PUBLIC "-//Davenport//ENTITIES DocBook Additional General Entities V3.0//EN" dbgenent.mod
</programlisting>
<step performance="required">
<para>
Of course, a file containing these comes with the
<productname>DocBook</productname> kit. Note that the last item on
each of these lines is a file name, given here without a path. You
@ -1270,14 +1246,20 @@ named <filename>ISO</filename>. Again, proper catalog entries should
accompany the entity kit you fetch.
</para>
</sect3>
</procedure>
<sect3><title>Installing Norman Walsh's <acronym>DSSSL</acronym>
style sheets</title>
<sect3>
<title>Installing Norman Walsh's <acronym>DSSSL</acronym> Style Sheets</title>
<para>
<para>First, read the installation instructions at the above listed
<procedure>
<title>Installing Norman Walsh's <acronym>DSSSL</acronym> Style Sheets</title>
<step performance="required">
<para>Read the installation instructions at the above listed
URL.</para>
<step performance="required">
<para>To install Norman's style sheets, simply unzip the distribution
kit in a suitable place. A good place to dot this would be
<filename>/usr/local/share</filename>, which places the kit in a
@ -1288,29 +1270,54 @@ unzip -aU db107.zip
</programlisting>
</para>
<step performance="required">
<para>One way to test the installation is to build the
<acronym>HTML</acronym> and <acronym>RTF</acronym> forms of the
<productname>PostgreSQL</productname> manual. Go to the <acronym>SGML</acronym> source
<productname>PostgreSQL</productname> manual.
<substeps>
<step performance="required">
<para>
To build the <acronym>HTML</acronym> files,
go to the <acronym>SGML</acronym> source
directory, <filename>doc/src/sgml</filename>, and say
<programlisting>
jade -t sgml -d /usr/local/share/docbook/html/docbook.dsl -D ../graphics postgres.sgml
</programlisting>
to build the <acronym>HTML</acronym> files ("book1.htm" is the top level node), and
<para>
<filename>book1.htm</filename> is the top level node of the output..
<step performance="required">
<para>
To generate the <acronym>RTF</acronym> output, ready for importing
into your favorite word processing system and printing, type:
<programlisting>
jade -t rtf -d /usr/local/share/docbook/print/docbook.dsl -D ../graphics postgres.sgml
</programlisting>
to generate the <acronym>RTF</acronym> output, ready for importing
into your favorite word processing system and printing.</para>
</sect3>
</substeps>
<sect3><title>Installing <productname>PSGML</productname></title>
</procedure>
<para>First, read the installation instructions at the above listed
<sect3>
<title>Installing <productname>PSGML</productname></title>
<para>
<procedure>
<title>Installing <productname>PSGML</productname></title>
<step performance="required">
<para>Read the installation instructions at the above listed
URL.</para>
<step performance="required">
<para>Unpack the distribution file, run configure, make and make
install to put the byte-compiled files and info library in place.
<step performance="required">
<para>
Then add the following lines to your
<filename>/usr/local/share/emacs/site-lisp/site-start.el</filename>
file to make <productname>Emacs</productname> properly load
@ -1320,6 +1327,9 @@ file to make <productname>Emacs</productname> properly load
(cons "/usr/local/share/emacs/site-lisp/psgml" load-path))
(autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t)
</programlisting>
<step performance="optional">
<para>
If you want to use <productname>PSGML</productname> when editing
<acronym>HTML</acronym> too, also add this:
<programlisting>
@ -1328,22 +1338,39 @@ If you want to use <productname>PSGML</productname> when editing
</programlisting>
</para>
<step performance="optional">
<para>There is one important thing to note with
<productname>PSGML</productname>: its author assumed that your main
<acronym>SGML</acronym> <acronym>DTD</acronym> directory would be
<filename>/usr/local/lib/sgml</filename>. If, as in the examples in
this chapter, you use <filename>/usr/local/share/sgml</filename>, you
have to compensate for this. You can set the
<filename>SGML_CATALOG_FILES</filename> environment variable, you can
have to compensate for this.
<substeps>
<step performance="optional">
<para>
You can set the
<filename>SGML_CATALOG_FILES</filename> environment variable.
<step performance="optional">
<para>
You can
customize your <productname>PSGML</productname> installation (its
manual tells you how), or you can even edit the source file
manual tells you how).
<step performance="optional">
<para>
You can even edit the source file
<filename>psgml.el</filename> before compiling and installing
<productname>PSGML</productname>, changing the hard-coded paths to
match your own default.</para>
</sect3>
</substeps>
<sect3><title>Optional: installing <productname>JadeTeX</productname></title>
</procedure>
<sect3><title>Installing <productname>JadeTeX</productname></title>
<para>If you want to, you can also install
<productname>JadeTeX</productname> to use
@ -1419,6 +1446,15 @@ vary according to your installation.
<sect1>
<title>Alternate Toolsets</title>
<para>
<productname>sgml-tools</productname> v2.x
now supports <application>jade</application>
and <productname>DocBook</productname>. It may be the preferred toolset
for working with <acronym>SGML</acronym> but we have not had a chance to
evaluate the new package.
<!--
<para>
The current stable release of <productname>sgml-tools</productname> is
version 1.0.4. The v1.0 release includes some restructuring of the
@ -1433,12 +1469,9 @@ version of <productname>sgml-tools</productname> evaluated for
<para>
Install
<productname>sgml-tools-0.99.0</productname>
<productname>sgml-tools-0.99.0</productname>.
</para>
<sect2>
<title><productname>sgml-tools</productname></title>
<para>
Apply <ulink
url="http://alumni.caltech.edu/~lockhart/postgres/linuxdoc/sgml-tools-patches-0.99.0.tar.gz">
@ -1485,5 +1518,7 @@ null.sty to texmf/tex/latex/tools/ or the appropriate area.
Run <productname>texhash</productname> to update the tex database.
</para></sect2></sect1>
-->
</appendix>

7
doc/src/sgml/info.sgml
View file

@ -48,7 +48,9 @@ Installation and management information. List of supported machines.
<Para>
Information for <ProductName>Postgres</ProductName> developers. This is intended
for those who are contributing to the <ProductName>Postgres</ProductName>
project; application development information should appear in the Programmer's Guide.
project; application development information should appear in the
<citetitle>Programmer's Guide</citetitle>.
Currently included in the <citetitle>Programmer's Guide</citetitle>.
</Para>
</ListItem>
</VarListEntry>
@ -58,8 +60,7 @@ project; application development information should appear in the Programmer's G
<ListItem>
<Para>
Detailed reference information on command syntax.
At the moment, this manual is very sparse, but eventually should contain
information similar to that in the man pages.
Currently included in the <citetitle>User's Guide</citetitle>.
</Para>
</ListItem>
</VarListEntry>

310
doc/src/sgml/install.sgml
View file

@ -414,16 +414,20 @@ $ gunzip -c ~/postgresql-v6.4.tar.gz | tar xvf -
the build process (see the --prefix option below). Type
<ProgramListing>
$ cd /usr/src/pgsql/src
$ ./configure [ <replaceable>options as described below</replaceable> ]
$ ./configure [ <replaceable>options</replaceable> ]
</ProgramListing>
</Para>
<substeps>
<Step Performance="optional">
<Para>
Among other chores, the configure script selects a system-specific
"template" file from the files provided in the template subdirectory.
If it cannot guess which one to use for your system, it will say so and
exit. In that case you'll need to figure out which one to use and run
configure again, this time giving the <option>--with-template=TEMPLATE</option> option to
configure again, this time giving the
<option>--with-template=TEMPLATE</option> option to
make the right file be chosen.
<note>
@ -438,7 +442,14 @@ If your system is not automatically recognized by configure and you have to do t
</Para>
<Step Performance="optional">
<Para>
Choose configuration options. Check <xref linkend="config" endterm="install-config">
for details. However, for a plain-vanilla first installation with no extra
options like multi-byte character support or locale collation support it may
be adequate to have chosen the installation areas and to run configure without
extra options specified.
The configure script accepts many additional options that you can use
if you don't like the default configuration. To see them all, type
<ProgramListing>
@ -449,35 +460,21 @@ If your system is not automatically recognized by configure and you have to do t
--prefix=BASEDIR Selects a different base directory for the
installation of the <ProductName>Postgres</ProductName> configuration.
The default is /usr/local/pgsql.
--with-template=TEMPLATE
Use template file TEMPLATE - the template
files are assumed to be in the directory
src/template, so look there for proper values.
--with-pgport=PORT Sets the port that the postmaster process
listens for incoming connections on. The
default is port 5432.
--with-tcl Build interface libraries and programs requiring
Tcl/Tk, including libpgtcl, pgtclsh, and pgtksh.
--with-perl Build the Perl interface library.
--with-odbc Build the ODBC driver package.
--enable-hba Enables Host Based Authentication (DEFAULT)
--disable-hba Disables Host Based Authentication
--enable-locale Enables USE_LOCALE
--enable-cassert Enables ASSERT_CHECKING
--with-CC=compiler
Use a specific C compiler that the configure
script cannot find.
--with-CXX=compiler
--without-CXX
Use a specific C++ compiler that the configure
@ -487,9 +484,11 @@ If your system is not automatically recognized by configure and you have to do t
</ProgramListing>
</Para>
<Step Performance="required">
<Para>
As an example, here is the configure script used on a Sparc Solaris 2.5 system
with <filename>/opt/postgres</filename> being the installation base directory:
Here is the configure script used on a Sparc Solaris 2.5 system
with <filename>/opt/postgres</filename> specified as
the installation base directory:
<ProgramListing>
$ ./configure --prefix=/opt/postgres \
@ -497,11 +496,17 @@ $ ./configure --prefix=/opt/postgres \
--enable-hba --disable-locale
</ProgramListing>
<tip>
<para>
Of course, you may type these three lines all
on the same line.
</tip>
</Para>
</Step>
</substeps>
<Step Performance="required">
<Para>
Install the <acronym>HTML</acronym> documentation. Type
@ -653,10 +658,13 @@ pg_id: can't load library 'libpq.so'
Any account that will use <ProductName>Postgres</ProductName> must
be similarly prepared.
<note>
<para>
There are several ways to influence the runtime environment of the <ProductName>Postgres</ProductName>
server. Refer to the chapter on <citetitle>Administrator's Guide</citetitle> for more information.
There are several ways to influence the runtime environment of the
<ProductName>Postgres</ProductName>
server. Refer to the <citetitle>Administrator's Guide</citetitle>
for more information.
<note>
<para>
The following instructions are for a
bash/sh shell. Adapt accordingly for other shells.
@ -664,8 +672,13 @@ The following instructions are for a
</Para>
<substeps>
<Step Performance="required">
<Para>
Add the following lines to your login shell, <filename>~/.bash_profile</filename>:
Add the following lines to your login environment:
shell, <filename>~/.bash_profile</filename>:
<ProgramListing>
PATH=$PATH:/usr/local/pgsql/bin
MANPATH=$MANPATH:/usr/local/pgsql/man
@ -675,6 +688,30 @@ export PATH MANPATH PGLIB PGDATA
</ProgramListing>
</Para>
<Step Performance="required">
<para>
Several regression tests could failed if the user's locale collation
scheme is different from that of standard C locale.
<para>
If you configure and compile <ProductName>Postgres</ProductName>
with the <option>--enable-locale</option> option then
set locale environment to C (or unset all LC_* variables)
by putting these additional lines to your login environment
before starting postmaster:
<ProgramListing>
LC_COLLATE=C
LC_CTYPE=C
LC_COLLATE=C
export LC_COLLATE LC_CTYPE LC_COLLATE
</ProgramListing>
<ProgramListing>
</ProgramListing>
<Step Performance="required">
<Para>
Make sure that you have defined these variables before continuing
with the remaining steps. The easiest way to do this is to type:
@ -684,10 +721,15 @@ $ source ~/.bash_profile
</Para>
</Step>
</substeps>
<Step Performance="required">
<Para>
Create the database. <Emphasis>Do not do the following as root!</Emphasis>
This would be a major security hole. Type
Create the database installation from your <ProductName>Postgres</ProductName>
superuser account (typically account <literal>postgres</literal>).
<Emphasis>Do not do the following as root!</Emphasis>
This would be a major security hole. Type
<ProgramListing>
$ initdb
</ProgramListing>
@ -710,15 +752,151 @@ $ initdb
</Step>
<Step Performance="required">
<Para>
Run postmaster from your <ProductName>Postgres</ProductName> superuser account (typically
account postgres).
<emphasis>Do not run <application>postmaster</application> from the root account!</emphasis>
<para>
Briefly test that the backend will start and run by running it from
the command line.
<substeps>
<Step Performance="required">
<para>
Start the postmaster daemon running in the background by typing
<ProgramListing>
$ cd
$ postmaster -i
</ProgramListing>
</Para>
</Step>
<Step Performance="required">
<para>
Create a database by typing
<ProgramListing>
$ createdb
</ProgramListing>
<Step Performance="required">
<para>
Connect to the new database:
<ProgramListing>
$ psql
</ProgramListing>
<Step Performance="required">
<para>
And run a sample query:
<ProgramListing>
postgres=> SELECT datetime 'now';
</ProgramListing>
<Step Performance="required">
<para>
Exit <application>psql</application>:
<ProgramListing>
postgres=> \q
</ProgramListing>
<Step Performance="required">
<para>
Remove the test database (unless you will want to use it later for other tests):
<ProgramListing>
$ destroydb
</ProgramListing>
</substeps>
<Step Performance="required">
<Para>
Run postmaster in the background from your <ProductName>Postgres</ProductName>
superuser account (typically account <literal>postgres</literal>).
<emphasis>Do not run <application>postmaster</application>
from the root account!</emphasis>
<Para>
Usually, you will want to modify
your computer so that it will automatically start postmaster whenever
it boots. It is not required; the <ProductName>Postgres</ProductName>
server can
be run successfully from non-privileged accounts without root intervention.
<para>
Here are some suggestions on how to do this, contributed by various
users.
<para>
Whatever you do, postmaster must be run by
the <ProductName>Postgres</ProductName> superuser (<literal>postgres</literal>?)
<emphasis>and not by root</emphasis>.
This is why all of the examples below start by switching user
(su) to postgres. These commands also take into account the fact
that environment variables like PATH and PGDATA may not be set properly.
The examples are as follows. Use them with extreme caution.
<itemizedlist mark="bullet">
<listitem>
<para>
If you are installing from a non-privileged account and have no root access, then
start the <application>postmaster</application> and send it to the background:
<ProgramListing>
$ cd
$ nohup postmaster > regress.log 2>&1 &
</ProgramListing>
<listitem>
<para>
Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris
2.5.1 to contain the following single line:
<programlisting>
su postgres -c "/usr/local/pgsql/bin/postmaster -S -D /usr/local/pgsql/data"
</programlisting>
<listitem>
<para>
In FreeBSD 2.2-RELEASE edit /usr/local/etc/rc.d/pgsql.sh to
contain the following lines and make it chmod 755 and chown
root:bin.
<programlisting>
#!/bin/sh
[ -x /usr/local/pgsql/bin/postmaster ] && {
su -l pgsql -c 'exec /usr/local/pgsql/bin/postmaster
-D/usr/local/pgsql/data
-S -o -F > /usr/local/pgsql/errlog' &
echo -n ' pgsql'
}
</programlisting>
You may put the line breaks as shown above. The shell is smart
enough to keep parsing beyond end-of-line if there is an
expression unfinished. The exec saves one layer of shell under
the postmaster process so the parent is init.
<listitem>
<para>
In RedHat Linux add a file <filename>/etc/rc.d/init.d/postgres.init</filename>
which is based on the example in <filename>contrib/linux/</filename>.
Then make a softlink to this file from
<filename>/etc/rc.d/rc5.d/S98postgres.init</filename>.
<listitem>
<para>
In RedHat Linux edit file /etc/inittab to add the
following as a single line:
<programlisting>
pg:2345:respawn:/bin/su - postgres -c
"/usr/local/pgsql/bin/postmaster -D/usr/local/pgsql/data
&gt;&gt; /usr/local/pgsql/server.log 2&gt;&1 &lt;/dev/null"
</programlisting>
(The author of this example says this example will revive the
postmaster if it dies, but he doesn't know if there are other side
effects.)
</itemizedlist>
</Para>
</Step>
@ -819,82 +997,6 @@ $ gmake clean
</substeps>
<Step Performance="required">
<Para>
If you haven't already done so, this would be a good time to modify
your computer so that it will automatically start postmaster whenever
you boot your computer.
Here are some suggestions on how to do this, contributed by various
users.
<para>
Whatever you do, postmaster must be run by
the <ProductName>Postgres</ProductName> superuser (<literal>postgres</literal>?)
<emphasis>and not by root</emphasis>.
This is why all of the examples below start by switching user
(su) to postgres. These commands also take into account the fact
that environment variables like PATH and PGDATA may not be set properly.
The examples are as follows. Use them with extreme caution.
<itemizedlist>
<listitem>
<para>
Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris
2.5.1 to contain the following single line:
<programlisting>
su postgres -c "/usr/local/pgsql/bin/postmaster -S -D /usr/local/pgsql/data"
</programlisting>
<listitem>
<para>
In FreeBSD 2.2-RELEASE edit /usr/local/etc/rc.d/pgsql.sh to
contain the following lines and make it chmod 755 and chown
root:bin.
<programlisting>
#!/bin/sh
[ -x /usr/local/pgsql/bin/postmaster ] && {
su -l pgsql -c 'exec /usr/local/pgsql/bin/postmaster
-D/usr/local/pgsql/data
-S -o -F > /usr/local/pgsql/errlog' &
echo -n ' pgsql'
}
</programlisting>
You may put the line breaks as shown above. The shell is smart
enough to keep parsing beyond end-of-line if there is an
expression unfinished. The exec saves one layer of shell under
the postmaster process so the parent is init.
<listitem>
<para>
In RedHat Linux add a file <filename>/etc/rc.d/init.d/postgres.init</filename>
which is based on the example in <filename>contrib/linux/</filename>.
Then make a softlink to this file from
<filename>/etc/rc.d/rc5.d/S98postgres.init</filename>.
<listitem>
<para>
In RedHat Linux edit file /etc/inittab to add the
following as a single line:
<programlisting>
pg:2345:respawn:/bin/su - postgres -c
"/usr/local/pgsql/bin/postmaster -D/usr/local/pgsql/data
&gt;&gt; /usr/local/pgsql/server.log 2&gt;&1 &lt;/dev/null"
</programlisting>
(The author of this example says this example will revive the
postmaster if it dies, but he doesn't know if there are other side
effects.)
</itemizedlist>
</Para>
</Step>
<Step Performance="required">
<Para>
If you haven't already done so, this would be a good time to modify

13
doc/src/sgml/installation.sgml
View file

@ -1,10 +1,15 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.1 1998/10/27 06:11:08 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/installation.sgml,v 1.2 1998/10/30 19:37:00 thomas Exp $
Postgres quick Installation Guide.
thomas 1998-10-26
$Log: installation.sgml,v $
Revision 1.2 1998/10/30 19:37:00 thomas
Minor editing and markup changes as a result of preparing the Postscript
documentation for v6.4.
Bigger updates to the installation instructions (install and config).
Revision 1.1 1998/10/27 06:11:08 thomas
First cut at standalone installation guide to replace INSTALL text source.
@ -20,6 +25,7 @@ First cut at standalone installation guide to replace INSTALL text source.
<!entity notation SYSTEM "notation.sgml">
<!entity y2k SYSTEM "y2k.sgml">
<!entity config SYSTEM "config.sgml">
<!entity intro-ag SYSTEM "intro-ag.sgml">
<!entity install SYSTEM "install.sgml">
<!entity options SYSTEM "pg_options.sgml">
@ -37,9 +43,9 @@ First cut at standalone installation guide to replace INSTALL text source.
<!-- Title information -->
<Title>PostgreSQL Administrator's Guide</Title>
<Title>PostgreSQL Installation Guide</Title>
<BookInfo>
<ReleaseInfo>Covering v6.3 for general release</ReleaseInfo>
<ReleaseInfo>Covering v6.4 for general release</ReleaseInfo>
<BookBiblio>
<AuthorGroup>
<CorpAuthor>The PostgreSQL Development Team</CorpAuthor>
@ -115,6 +121,7 @@ and installing documentation, and then print or browse the
</chapter>
&ports;
&config;
&install;
&release;

217
doc/src/sgml/jdbc.sgml
View file

@ -50,7 +50,7 @@ as the driver uses some dynamic
loading techniques for performance reasons,
and <application>javac</application> cannot cope.
The <filename>Makefile</filename> will generate the jar archive.
<para>
</note>
<sect2>
<title>Installing the Driver</title>
@ -76,7 +76,7 @@ Loading the driver is covered later on in this chapter.
<para>
<sect1>
<title>Preparing the database for <acronym>JDBC</acronym></title>
<title>Preparing the Database for <acronym>JDBC</acronym></title>
<para>
Because Java can only use TCP/IP connections, the <application>Postgres</application> postmaster
@ -89,10 +89,12 @@ to add something like:
<para>
host all 127.0.0.1 255.255.255.255 password
<para>
Here access to all databases are possible from the local machine with <acronym>JDBC</acronym>.
Here access to all databases are possible from the local machine
with <acronym>JDBC</acronym>.
<para>
The <acronym>JDBC</acronym> Driver supports trust, ident, password and crypt authentication methods.
The <acronym>JDBC</acronym> Driver supports trust, ident,
password and crypt authentication methods.
<para>
@ -193,15 +195,15 @@ forms:
<itemizedlist>
<listitem>
<para>
jdbc:postgresql:<replaceable class="parameter>database</replaceable>
jdbc:postgresql:<replaceable class="parameter">database</replaceable>
<listitem>
<para>
jdbc:postgresql://<replaceable class="parameter>host</replaceable>/<replaceable class="parameter>database</replaceable>
jdbc:postgresql://<replaceable class="parameter">host</replaceable>/<replaceable class="parameter">database</replaceable>
<listitem>
<para>
jdbc:postgresql://<replaceable class="parameter>host</replaceable>:<replaceable class="parameter>port</replaceable>/<replaceable class="parameter>database</replaceable>
jdbc:postgresql://<replaceable class="parameter">host</replaceable>:<replaceable class="parameter">port</replaceable>/<replaceable class="parameter">database</replaceable>
</itemizedlist>
where:
@ -209,7 +211,7 @@ where:
<variablelist>
<varlistentry>
<term>
<replaceable class="parameter>host</replaceable>
<replaceable class="parameter">host</replaceable>
<listitem>
<para>
@ -217,7 +219,7 @@ The hostname of the server. Defaults to "localhost".
<varlistentry>
<term>
<replaceable class="parameter>port</replaceable>
<replaceable class="parameter">port</replaceable>
<listitem>
<para>
@ -226,7 +228,7 @@ standard port number (5432).
<varlistentry>
<term>
<replaceable class="parameter>database</replaceable>
<replaceable class="parameter">database</replaceable>
<listitem>
<para>
@ -243,7 +245,7 @@ Connection db = DriverManager.getConnection(url,user,pwd);
<para>
<sect1>
<title>Issuing a query and processing the result</title>
<title>Issuing a Query and Processing the Result</title>
<para>
Any time you want to issue SQL statements to the database, you require a
@ -252,11 +254,13 @@ method to issue a query. This will return a ResultSet instance, which contains
the entire result.
<para>
<sect1>
<title>Some notes about using the Statement interface:</title>
<sect2>
<title>Using the Statement Interface</title>
<para>
The following must be considered when using the Statement interface:
<itemizedlist>
<para>
<listitem>
<para>
You can use a Statement instance as many times as you want. You could
@ -276,14 +280,16 @@ as it covers some important points.
</itemizedlist>
<sect1>
<title>Some notes about using the ResultSet interface:</title>
<sect2>
<title>Using the ResultSet Interface</title>
<para>
The following must be considered when using the ResultSet interface:
<itemizedlist>
<para>
<listitem>
<para>
Before reading any values, you must call next(). This returns true if
Before reading any values, you must call <function>next()</function>. This returns true if
there is a result, but more importantly, it prepares the row for processing.
<listitem>
@ -291,58 +297,60 @@ there is a result, but more importantly, it prepares the row for processing.
Under the <acronym>JDBC</acronym> spec, you should access a field only once. It's safest
to stick to this rule, although at the current time, the <application>Postgres</application> driver
will allow you to access a field as many times as you want.
<listitem>
<para>
You must close() a ResultSet once you have finished with it.
You must close a ResultSet by calling <function>close()</function> once you have finished with it.
<listitem>
<para>
Once you request another query with the Statement used to create a
ResultSet, the currently open instance is closed().
ResultSet, the currently open instance is closed.
</itemizedlist>
<para>
An example is as follows:
<programlisting>
Statement st = db.createStatement();
ResultSet rs = st.executeQuery(<literal>select * from mytable</literal>);
while(rs.next()) {
<itemizedlist>
<para>
<listitem>
<para>
System.out.print(<literal>Column 1 returned </literal>);
<listitem>
<para>
System.out.println(rs.getString(1));
System.out.print(<literal>Column 1 returned </literal>);
System.out.println(rs.getString(1));
}
rs.close();
st.close();
</itemizedlist>
</programlisting>
<sect1>
<title>Performing updates</title>
<title>Performing Updates</title>
<para>
To perform an update (or any other SQL statement that does not return a
result), you simply use the executeUpdate() method:
<para>
st.executeUpdate(<literal>create table basic (a int2, b int2)</literal>);
<para>
<programlisting>
st.executeUpdate(<literal>create table basic (a int2, b int2)</literal>);
</programlisting>
<sect1>
<title>Closing the connection</title>
<title>Closing the Connection</title>
<para>
To close the database connection, simply call the close() method to the Connection:
<para>
<programlisting>
db.close();
<para>
</programlisting>
<sect1>
<title>Using Large Objects</title>
<para>
In <application>Postgres</application>, large objects (also known as BLOBS) are used to hold data in
In <application>Postgres</application>,
large objects (also known as <firstterm>blobs</firstterm>) are used to hold data in
the database that cannot be stored in a normal SQL table. They are stored as a
Table/Index pair, and are refered to from your own tables, by an OID value.
@ -357,118 +365,83 @@ In <acronym>JDBC</acronym>, the standard way to access them is using the getBina
method in ResultSet, and setBinaryStream() method in PreparedStatement. These
methods make the large object appear as a Java stream, allowing you to use the
java.io package, and others, to manipulate the object.
<para>
Example:
<para>
You have a table containing the file name of an image, and a large object
For example, suppose
you have a table containing the file name of an image, and a large object
containing that image:
<para>
create table images (imgname name,imgoid oid);
<programlisting>
create table images (imgname name,imgoid oid);
</programlisting>
<para>
To insert an image, you would use:
<para>
<itemizedlist>
<para>
<listitem>
<para>
File file = new File(<literal>myimage.gif</literal>);
<listitem>
<para>
FileInputStream fis = new FileInputStream(file);
<listitem>
<para>
PreparedStatement ps = conn.prepareStatement(<literal>insert into images
values (?,?)<literal>);
<listitem>
<para>
ps.setString(1,file.getName());
<listitem>
<para>
ps.setBinaryStream(2,fis,file.length());
<listitem>
<para>
ps.executeUpdate();
<listitem>
<para>
ps.close();
<listitem>
<para>
fis.close();
</itemizedlist>
<programlisting>
File file = new File(<literal>myimage.gif</literal>);
FileInputStream fis = new FileInputStream(file);
PreparedStatement ps = conn.prepareStatement(<literal>insert into images values (?,?)</literal>);
ps.setString(1,file.getName());
ps.setBinaryStream(2,fis,file.length());
ps.executeUpdate();
ps.close();
fis.close();
</programlisting>
<para>
Now in this example, setBinaryStream transfers a set number of bytes from a
stream into a large object, and stores the OID into the field holding a
reference to it.
<para>
Retrieving an image is even easier (I'm using PreparedStatement here, but
Statement can equally be used):
<para>
<itemizedlist>
<para>
<listitem>
<para>
PreparedStatement ps = con.prepareStatement(<literal>select oid from
images where name=?<literal>);
<listitem>
<para>
ps.setString(1,<literal>myimage.gif</literal>);
<listitem>
<para>
ResultSet rs = ps.executeQuery();
<listitem>
<para>
if(rs!=null) {
<listitem>
<para>
while(rs.next()) {
<listitem>
<para>
&#9;InputStream is = rs.getBinaryInputStream(1);
<listitem>
<para>
&#9;// use the stream in some way here
<listitem>
<para>
&#9;is.close();
<listitem>
<para>
}
<listitem>
<para>
rs.close();
<listitem>
<para>
}
<listitem>
<para>
ps.close();
</itemizedlist>
<programlisting>
PreparedStatement ps = con.prepareStatement(<literal>select oid from images where name=?</literal>);
ps.setString(1,<literal>myimage.gif</literal>);
ResultSet rs = ps.executeQuery();
if(rs!=null) {
while(rs.next()) {
InputStream is = rs.getBinaryInputStream(1);
// use the stream in some way here
is.close();
}
rs.close();
}
ps.close();
</programlisting>
<para>
Now here you can see where the Large Object is retrieved as an InputStream.
You'll also notice that we close the stream before processing the next row in
the result. This is part of the <acronym>JDBC</acronym> Specification, which states that any
InputStream returned is closed when ResultSet.next() or ResultSet.close() is called.
<para>
<sect1>
<title><application>Postgres</application> Extensions to the <acronym>JDBC</acronym> <acronym>API</acronym></title>
<para>
<application>Postgres</application> is an extensible database system. You can add your own functions
<application>Postgres</application> is an extensible database system.
You can add your own functions
to the backend, which can then be called from queries, or even add your own
data types.
<para>
Now, as these are facilities unique to us, we support them from Java, with
a set of extension <acronym>API</acronym>'s. Some features within the core of the standard driver
a set of extension <acronym>API</acronym>'s. Some features within
the core of the standard driver
actually use these extensions to implement Large Objects, etc.
<para>
<!--
-- Nothing marked up from here on. It looks like it will be tricky:
-- what do we want to do with the class inheritance diagrams?
-- - thomas 1998-10-23
-->
************************************************************
Nothing marked up from here on. It looks like it will be tricky:
what do we want to do with the class inheritance diagrams?
- thomas 1998-10-23
************************************************************
-->
<programlisting>
Accessing the extensions
@ -2548,10 +2521,10 @@ If you have not yet read it, I'd advise you read the <acronym>JDBC</acronym>
Documentation (supplied with Sun's <acronym>JDK</acronym>),
and the <acronym>JDBC</acronym> Specification.
Both are available on
<ulink url="http://www.javasoft.com>JavaSoft's web site</ulink>.
<ulink url="http://www.javasoft.com">JavaSoft's web site</ulink>.
<para>
<ulink url="http://www.retep.org.uk>My own web site</ulink>
<ulink url="http://www.retep.org.uk">My own web site</ulink>
contains updated information not included in this
document, and also includes precompiled drivers for v6.4, and earlier.

7
doc/src/sgml/libpgtcl.sgml
View file

@ -2,8 +2,9 @@
<Title>pgtcl</Title>
<Para>
pgtcl is a tcl package for front-end programs to interface with <ProductName>Postgres</ProductName>
backends. It makes most of the functionality of libpq available to
<literal>pgtcl</literal> is a tcl package for front-end programs
to interface with <ProductName>Postgres</ProductName>
backends. It makes most of the functionality of <literal>libpq</literal> available to
tcl scripts.
</Para>
@ -16,7 +17,7 @@ This package was originally written by Jolly Chen.
<Para>
<TABLE TOCENTRY="1">
<TITLE>PGTCL Commands</TITLE>
<TITLE><literal>pgtcl</literal> Commands</TITLE>
<TGROUP COLS="2">
<THEAD>
<ROW>

2
doc/src/sgml/libpq.sgml
View file

@ -1,5 +1,5 @@
<Chapter Id="libpq-chapter">
<Title id="libpq"><FileName>libpq</FileName></Title>
<Title id="libpq">libpq</Title>
<Para>

3
doc/src/sgml/odbc.sgml
View file

@ -577,8 +577,7 @@ be able to access the <productname>Postgres</productname>
<title>Enabling ApplixWare Database Access</title>
<para>
Note that
these instructions are for the 4.4.1 release of
These instructions are for the 4.4.1 release of
<productname>ApplixWare</productname> on <productname>Linux</productname>.
Refer to the <citetitle>Linux Sys Admin</citetitle> on-line book
for more detailed information.

2
doc/src/sgml/page.sgml
View file

@ -34,8 +34,10 @@ classes (e.g., a B-tree index) are structured.
<thead>
<row>
<entry>
Item
</entry>
<entry>
Description
</entry>
</row>
</thead>

156
doc/src/sgml/ports.sgml
View file

@ -1,14 +1,19 @@
<Chapter Id="ports">
<Title>Ports</Title>
<Sect1>
<Title>Currently Supported Platforms</Title>
<Para>
This manual describes version 6.4 of <ProductName>Postgres</ProductName>.
The <ProductName>Postgres</ProductName> developer community has
compiled and tested <ProductName>Postgres</ProductName> on the following
platforms:
compiled and tested <ProductName>Postgres</ProductName> on a
number of platforms. Check
<ulink url="http://www.postgresql.org/docs/admin/ports.htm">the web site</ulink>
for the latest information.
<Sect1>
<Title>Currently Supported Platforms</Title>
<para>
At the time of publication, the following platforms have been tested:
<TABLE TOCENTRY="1">
<TITLE>Supported Platforms</TITLE>
@ -24,13 +29,11 @@ platforms:
</THEAD>
<TBODY>
<ROW>
<ENTRY>AIX 4.1.x-4.2</ENTRY>
<ENTRY>AIX 4.2.1</ENTRY>
<ENTRY>RS6000</ENTRY>
<ENTRY>v6.3</ENTRY>
<ENTRY>1998-03-01</ENTRY>
<ENTRY>4.1.4.0,4.2 (<ULink url="mailto:darrenk@insightdist.com">Darren King</ULink>),
4.1.5 (<ULink url="mailto:Andreas.Zeugswetter@telecom.at">Andreas Zeugswetter</ULink>);
3.2.5 confirmed on v6.2.1 (<ULink url="mailto:danaf@ans.net">Frank Dana</ULink>)</ENTRY>
<ENTRY>v6.4</ENTRY>
<ENTRY>1998-10-27</ENTRY>
<ENTRY>(<ULink url="mailto:Andreas.Zeugswetter@telecom.at">Andreas Zeugswetter</ULink>)</ENTRY>
</ROW>
<ROW>
<ENTRY>BSDI</ENTRY>
@ -42,45 +45,25 @@ platforms:
<ROW>
<ENTRY>FreeBSD 2.2.x-3.x</ENTRY>
<ENTRY>x86</ENTRY>
<ENTRY>v6.3</ENTRY>
<ENTRY>1998-03-01</ENTRY>
<ENTRY>v6.4</ENTRY>
<ENTRY>1998-10-26</ENTRY>
<ENTRY>(<ULink url="mailto:t-ishii@sra.co.jp">Tatsuo Ishii</ULink>,
<ULink url="mailto:scrappy@hub.org">Marc Fournier</ULink>)</ENTRY>
</ROW>
<ROW>
<ENTRY>NetBSD 1.3.2</ENTRY>
<ENTRY>x86</ENTRY>
<ENTRY>v6.4</ENTRY>
<ENTRY>1998-10-25</ENTRY>
<ENTRY>(<ULink url="mailto:brook@trillium.NMSU.Edu">Brook Milligan</ULink>)</ENTRY>
</ROW>
<ROW>
<ENTRY>NetBSD 1.3</ENTRY>
<ENTRY>NS32532</ENTRY>
<ENTRY>v6.3</ENTRY>
<ENTRY>1998-07-20</ENTRY>
<ENTRY>(<ULink url="mailto:phil@steelhead.cs.wwu.edu">Phil Nelson</ULink>)</ENTRY>
</ROW>
<ROW>
<ENTRY>NetBSD 1.3</ENTRY>
<ENTRY>Sparc</ENTRY>
<ENTRY>v6.3</ENTRY>
<ENTRY>1998-03-01</ENTRY>
<ENTRY>(<ULink url="mailto:tih@hamartun.priv.no">Tom I Helbekkmo</ULink>)</ENTRY>
</ROW>
<ROW>
<ENTRY>NetBSD 1.3</ENTRY>
<ENTRY>VAX</ENTRY>
<ENTRY>v6.3</ENTRY>
<ENTRY>1998-03-01</ENTRY>
<ENTRY>(<ULink url="mailto:tih@hamartun.priv.no">Tom I Helbekkmo</ULink>)</ENTRY>
</ROW>
<ROW>
<ENTRY>DGUX 5.4R4.11</ENTRY>
<ENTRY>m88k</ENTRY>
<ENTRY>v6.3</ENTRY>
<ENTRY>1998-03-01</ENTRY>
<ENTRY>(<ULink url="mailto:geek+@cmu.edu">Brian E Gallew</ULink>)</ENTRY>
<ENTRY>v6.4 probably OK. Needs new maintainer. (<ULink url="mailto:geek+@cmu.edu">Brian E Gallew</ULink>)</ENTRY>
</ROW>
<ROW>
<ENTRY>Digital Unix 4.0</ENTRY>
<ENTRY>Alpha</ENTRY>
<ENTRY>v6.4</ENTRY>
<ENTRY>1998-10-29</ENTRY>
<ENTRY>Minor patchable problems
(<ULink url="mailto:pjlobo@euitt.upm.es">Pedro J. Lobo</ULink>)</ENTRY>
</ROW>
<ROW>
<ENTRY>HPUX</ENTRY>
@ -99,30 +82,20 @@ platforms:
<ENTRY>5.x is different
(<ULink url="mailto:martin@biochemistry.ucl.ac.uk">Andrew Martin</ULink>)</ENTRY>
</ROW>
<ROW>
<ENTRY>Digital 4.0</ENTRY>
<ENTRY>Alpha</ENTRY>
<ENTRY>v6.3.2</ENTRY>
<ENTRY>1998-04-16</ENTRY>
<ENTRY>reported working for DUnix/v3.2g
(<ULink url="mailto:pjlobo@euitt.upm.es">Pedro J. Lobo</ULink>)</ENTRY>
</ROW>
<ROW>
<ENTRY>linux 2.0.x</ENTRY>
<ENTRY>Alpha</ENTRY>
<ENTRY>v6.3.2</ENTRY>
<ENTRY>1998-04-16</ENTRY>
<ENTRY>mostly successful
(<ULink url="mailto:rkirkpat@nag.cs.colorado.edu">Ryan Kirkpatrick</ULink>,
<ULink url="mailto:jsturm@zenacomp.com"> Jeff Sturm </ULink>)</ENTRY>
<ENTRY>Mostly successful. Needs work for v6.4.
(<ULink url="mailto:rkirkpat@nag.cs.colorado.edu">Ryan Kirkpatrick</ULink>)</ENTRY>
</ROW>
<ROW>
<ENTRY>linux 2.0.x</ENTRY>
<ENTRY>x86</ENTRY>
<ENTRY>v6.4</ENTRY>
<ENTRY>1998-10-09</ENTRY>
<ENTRY>(<ULink url="mailto:lockhart@alumni.caltech.edu">Thomas Lockhart</ULink>,
<ULink url="mailto:t-ishii@sra.co.jp">Tatsuo Ishii</ULink>)</ENTRY>
<ENTRY>1998-10-27</ENTRY>
<ENTRY>(<ULink url="mailto:lockhart@alumni.caltech.edu">Thomas Lockhart</ULink>)</ENTRY>
</ROW>
<ROW>
<ENTRY>linux 2.0.x/glibc2</ENTRY>
@ -140,33 +113,76 @@ platforms:
<ENTRY>(<ULink url="mailto:szybist@boxhill.com">Tom Szybist</ULink>)</ENTRY>
</ROW>
<ROW>
<ENTRY>mklinux</ENTRY>
<ENTRY>linuxPPC 2.1.24</ENTRY>
<ENTRY>PPC603e</ENTRY>
<ENTRY>v6.4</ENTRY>
<ENTRY>1998-10-26</ENTRY>
<ENTRY>Powerbook 2400c(<ULink url="mailto:t-ishii@sra.co.jp">Tatsuo Ishii</ULink>)</ENTRY>
</ROW>
<ROW>
<ENTRY>mklinux DR3</ENTRY>
<ENTRY>PPC750</ENTRY>
<ENTRY>v6.4</ENTRY>
<ENTRY>1998-09-16</ENTRY>
<ENTRY>(<ULink url="mailto:t-ishii@sra.co.jp">Tatsuo Ishii</ULink>)</ENTRY>
<ENTRY>PowerMac 7600 (<ULink url="mailto:t-ishii@sra.co.jp">Tatsuo Ishii</ULink>)</ENTRY>
</ROW>
<ROW>
<ENTRY>SCO</ENTRY>
<ENTRY>NetBSD/i386 1.3.2</ENTRY>
<ENTRY>x86</ENTRY>
<ENTRY>v6.4</ENTRY>
<ENTRY>1998-10-25</ENTRY>
<ENTRY>(<ULink url="mailto:brook@trillium.NMSU.Edu">Brook Milligan</ULink>)</ENTRY>
</ROW>
<ROW>
<ENTRY>NetBSD-current</ENTRY>
<ENTRY>NS32532</ENTRY>
<ENTRY>v6.4</ENTRY>
<ENTRY>1998-10-27</ENTRY>
<ENTRY>(small problems in date/time math (<ULink url="mailto:jonb@metronet.com">Jon Buller</ULink>)</ENTRY>
</ROW>
<ROW>
<ENTRY>NetBSD/sparc 1.3H</ENTRY>
<ENTRY>Sparc</ENTRY>
<ENTRY>v6.4</ENTRY>
<ENTRY>1998-10-27</ENTRY>
<ENTRY>(<ULink url="mailto:tih@hamartun.priv.no">Tom I Helbekkmo</ULink>)</ENTRY>
</ROW>
<ROW>
<ENTRY>NetBSD 1.3</ENTRY>
<ENTRY>VAX</ENTRY>
<ENTRY>v6.3</ENTRY>
<ENTRY>1998-03-01</ENTRY>
<ENTRY>(<ULink url="mailto:tih@hamartun.priv.no">Tom I Helbekkmo</ULink>)</ENTRY>
</ROW>
<ROW>
<ENTRY>SCO UnixWare 2.x</ENTRY>
<ENTRY>x86</ENTRY>
<ENTRY>v6.3</ENTRY>
<ENTRY>1998-03-01</ENTRY>
<ENTRY>partial success
<ENTRY>aka UNIVEL
(<ULink url="mailto:Bill.Allie@mug.org">Billy G. Allie</ULink>)</ENTRY>
</ROW>
<ROW>
<ENTRY>SCO UnixWare 7</ENTRY>
<ENTRY>x86</ENTRY>
<ENTRY>v6.4</ENTRY>
<ENTRY>1998-10-04</ENTRY>
<ENTRY>(<ULink url="mailto:Bill.Allie@mug.org">Billy G. Allie</ULink>)</ENTRY>
</ROW>
<ROW>
<ENTRY>Solaris</ENTRY>
<ENTRY>x86</ENTRY>
<ENTRY>v6.3</ENTRY>
<ENTRY>1998-03-01</ENTRY>
<ENTRY>v6.4</ENTRY>
<ENTRY>1998-10-28</ENTRY>
<ENTRY>(<ULink url="mailto:scrappy@hub.org">Marc Fournier</ULink>)</ENTRY>
</ROW>
<ROW>
<ENTRY>Solaris 2.5.1-2.6</ENTRY>
<ENTRY>Solaris 2.6-2.7</ENTRY>
<ENTRY>Sparc</ENTRY>
<ENTRY>v6.4</ENTRY>
<ENTRY>1998-10-25</ENTRY>
<ENTRY>(<ULink url="mailto:szybist@boxhill.com">Tom Szybist</ULink>)</ENTRY>
<ENTRY>1998-10-28</ENTRY>
<ENTRY>(<ULink url="mailto:szybist@boxhill.com">Tom Szybist</ULink>,
<ULink url="mailto:ridderbusch.pad@sni.de">Frank Ridderbusch</ULink>)</ENTRY>
</ROW>
<ROW>
<ENTRY>SunOS 4.1.4</ENTRY>
@ -180,7 +196,7 @@ platforms:
<ENTRY>SVR4</ENTRY>
<ENTRY>MIPS</ENTRY>
<ENTRY>v6.4</ENTRY>
<ENTRY>1998-10-08</ENTRY>
<ENTRY>1998-10-28</ENTRY>
<ENTRY>no 64-bit int support
(<ULink url="mailto:ridderbusch.pad@sni.de">Frank Ridderbusch</ULink>)</ENTRY>
</ROW>
@ -192,14 +208,6 @@ platforms:
<ENTRY>confirmed with patching
(<ULink url="mailto:dlw@seavme.xroads.com">Doug Winterburn</ULink>)</ENTRY>
</ROW>
<ROW>
<ENTRY>Unixware</ENTRY>
<ENTRY>x86</ENTRY>
<ENTRY>v6.4</ENTRY>
<ENTRY>1998-10-04</ENTRY>
<ENTRY>aka UNIVEL
(<ULink url="mailto:Bill.Allie@mug.org">Billy G. Allie</ULink>)</ENTRY>
</ROW>
<ROW>
<ENTRY>Windows NT</ENTRY>
<ENTRY>x86</ENTRY>

21
doc/src/sgml/postgres.sgml
View file

@ -1,11 +1,16 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.12 1998/10/27 06:14:01 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.13 1998/10/30 19:37:09 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.13 1998/10/30 19:37:09 thomas
Minor editing and markup changes as a result of preparing the Postscript
documentation for v6.4.
Bigger updates to the installation instructions (install and config).
Revision 1.12 1998/10/27 06:14:01 thomas
Include configuration chapter with new info on configure and make.
@ -13,23 +18,16 @@ Revision 1.11 1998/10/25 00:24:31 thomas
Add Y2K statement for intros.
Make sure notation section is included in most intros.
Revision 1.10 1998/10/21 05:31:52 thomas
Revision 1.7-1.10 1998/10/21 05:31:52 thomas
Include new information from Massimo. Rearrange ODBC docs.
Revision 1.9 1998/09/30 05:41:49 thomas
Clean up pages. Add information for operator precedence.
Add information for operator precedence.
Split introduction sections into separate files to allow the legal notice
and notation sections appear in all documents without having the history
show up everplace too.
Add full list of reserved and non-reserved key words in syntax.sgml.
Add a separate chapter to the admin guide on security.
Revision 1.8 1998/08/17 16:20:33 thomas
Move SQL reference pages up into the User's Guide.
Revision 1.7 1998/08/15 06:52:53 thomas
Include new chapters.
-->
<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
@ -149,7 +147,8 @@ Include new chapters.
<LegalNotice>
<Para>
<ProductName>PostgreSQL</ProductName> is copyright (C) 1998 by the Postgres Global Development Group.
<ProductName>PostgreSQL</ProductName> is copyright (C) 1998
by the Postgres Global Development Group.
</Para>
</LegalNotice>

30
doc/src/sgml/programmer.sgml
View file

@ -1,11 +1,16 @@
<!--
$header$
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.9 1998/10/30 19:37:11 thomas Exp $
Postgres programmer's guide.
Derived from postgres.sgml.
thomas 1998-02-24
thomas 1998-10-27
$Log: programmer.sgml,v $
Revision 1.9 1998/10/30 19:37:11 thomas
Minor editing and markup changes as a result of preparing the Postscript
documentation for v6.4.
Bigger updates to the installation instructions (install and config).
$log$
-->
@ -81,7 +86,7 @@ $log$
<Title>PostgreSQL Programmer's Guide</Title>
<BookInfo>
<ReleaseInfo>Covering v6.3 for general release</ReleaseInfo>
<ReleaseInfo>Covering v6.4 for general release</ReleaseInfo>
<BookBiblio>
<AuthorGroup>
<CorpAuthor>The PostgreSQL Development Team</CorpAuthor>
@ -104,7 +109,7 @@ $log$
<AuthorInitials>TGL</AuthorInitials>
-->
<Date>(last updated 1998-02-24)</Date>
<Date>(last updated 1998-10-27)</Date>
</BookBiblio>
<LegalNotice>
@ -129,7 +134,7 @@ Your name here...
</Dedication>
-->
<Preface>
<Preface id="preface">
<Title>Summary</Title>
<Para>
@ -153,13 +158,19 @@ It provides SQL92/SQL3 language support,
&xaggr;
&rules;
&xindex;
&xplang;
&gist;
&xplang;
&dfunc;
<!-- reference -->
<!--
The func-ref chapter is not currently useful.
Disable it until we put in some info.
- thomas 1998-10-27
&func-ref;
-->
&trigger;
&spi;
&lobj;
@ -176,7 +187,7 @@ It provides SQL92/SQL3 language support,
The arch-dev chapter is current almost identical
to the arch-pg chapter appearing earlier in the
Programmer's Guide. If the Developer's Guide is
split into a separate document the start using this
split into a separate document then start using this
again.
- thomas 1998-10-23
&arch-dev;
@ -198,7 +209,8 @@ again.
&biblio;
<!--
<INDEX> </INDEX>
<index id="index">
</index>
-->
</Book>

25
doc/src/sgml/reference.sgml
View file

@ -1,9 +1,18 @@
<!-- reference.sgml
-
- Postgres User's Reference documentation.
$Header: /cvsroot/pgsql/doc/src/sgml/reference.sgml,v 1.4 1998/10/30 19:37:12 thomas Exp $
Postgres User's Reference documentation.
- thomas 1998-08-31
-
- -->
$Log: reference.sgml,v $
Revision 1.4 1998/10/30 19:37:12 thomas
Minor editing and markup changes as a result of preparing the Postscript
documentation for v6.4.
Bigger updates to the installation instructions (install and config).
-->
<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
<!entity intro SYSTEM "intro.sgml">
@ -61,7 +70,8 @@
<LegalNotice>
<Para>
<ProductName>PostgreSQL</ProductName> is copyright (C) 1998 by the Postgres Global Development Group.
<ProductName>PostgreSQL</ProductName> is copyright (C) 1998
by the Postgres Global Development Group.
</Para>
</LegalNotice>
@ -101,11 +111,16 @@ It provides SQL92/SQL3 language support,
&commands;
<!--
&contacts;
-->
&biblio;
<!--
<index Id="index">
</index>
-->
</Book>

36
doc/src/sgml/spi.sgml
View file

@ -12,47 +12,49 @@
<Title>Server Programming Interface</Title>
<Para>
The <FirstTerm>Server Programming Interface</FirstTerm> (<Acronym>SPI</Acronym>) is an attempt to give users the
ability to run <Acronym>SQL</Acronym> queries inside user-defined <Acronym>C</Acronym> functions.
Given the lack
of a proper <FirstTerm>Procedural Language</FirstTerm> (<Acronym>PL</Acronym>) in the current version of
<ProductName>Postgres</ProductName>,
<Acronym>SPI</Acronym> is the only way to write server-stored procedures and triggers. In the future
<Acronym>SPI</Acronym> will be used as the "workhorse" for a <Acronym>PL</Acronym>.
The <FirstTerm>Server Programming Interface</FirstTerm>
(<Acronym>SPI</Acronym>) gives users the
ability to run <Acronym>SQL</Acronym> queries inside user-defined
<Acronym>C</Acronym> functions.
The available Procedural Languages (<Acronym>PL</Acronym>) give an alternate
means to access these capabilities.
</Para>
<Para>
In fact, <Acronym>SPI</Acronym> is just a set of native interface functions to simplify
access to the Parser, Planner, Optimizer and Executor. <Acronym>SPI</Acronym> also does some
memory management.
In fact, <Acronym>SPI</Acronym> is just a set of native interface functions
to simplify access to the Parser, Planner, Optimizer and Executor.
<Acronym>SPI</Acronym> also does some memory management.
</Para>
<Para>
To avoid misunderstanding we'll use <FirstTerm>function</FirstTerm> to mean <Acronym>SPI</Acronym> interface
functions and <FirstTerm>procedure</FirstTerm> for user-defined C-functions using <Acronym>SPI</Acronym>.
To avoid misunderstanding we'll use <FirstTerm>function</FirstTerm>
to mean <Acronym>SPI</Acronym> interface functions and
<FirstTerm>procedure</FirstTerm> for user-defined C-functions
using <Acronym>SPI</Acronym>.
</Para>
<Para>
<Acronym>SPI</Acronym> procedures are always called by some (upper) Executor and the <Acronym>SPI</Acronym>
<Acronym>SPI</Acronym> procedures are always called by some (upper)
Executor and the <Acronym>SPI</Acronym>
manager uses the Executor to run your queries. Other procedures may be
called by the Executor running queries from your procedure.
</Para>
<Para>
Note, that if during execution of a query from a procedure the transaction
Note, that if during execution of a query from a procedure the transaction
is aborted then control will not be returned to your procedure. Rather, all work
will be rolled back and the server will wait for the next command from the
client. This will be changed in future versions.
</Para>
<Para>
Other restrictions are the inability to execute BEGIN, END and ABORT
Other restrictions are the inability to execute BEGIN, END and ABORT
(transaction control statements) and cursor operations. This will also be
changed in the future.
</Para>
<Para>
If successful, <Acronym>SPI</Acronym> functions return a non-negative result (either via
If successful, <Acronym>SPI</Acronym> functions return a non-negative result (either via
a returned integer value or in SPI_result global variable, as described below).
On error, a negative or NULL result will be returned.
</Para>
@ -892,7 +894,7 @@ TBD
<REFNAME>SPI_execp
</REFNAME>
<REFPURPOSE>
Executes a plan prepared or returned by <Function>SPI_saveplan</Function>
Executes a plan from <Function>SPI_saveplan</Function>
</REFPURPOSE>
<INDEXTERM ID="IX-SPI-SPIEXECP-1"><PRIMARY>SPI</PRIMARY><SECONDARY>connecting</SECONDARY></INDEXTERM>
<INDEXTERM ID="IX-SPI-SPIEXECP-2"><PRIMARY>SPI_execp</PRIMARY></INDEXTERM>

7
doc/src/sgml/trigger.sgml
View file

@ -2,9 +2,10 @@
<Title>Triggers</Title>
<Para>
While the current version of <ProductName>Postgres</ProductName> has various client interfaces
such as Perl, Tcl, Python and C, it lacks an actual <FirstTerm>Procedural Language</FirstTerm>
(PL). We hope to have a proper PL one day. In the meantime it is possible
<ProductName>Postgres</ProductName> has various client interfaces
such as Perl, Tcl, Python and C, as well as two
<FirstTerm>Procedural Languages</FirstTerm>
(PL). It is also possible
to call C functions as trigger actions. Note that STATEMENT-level trigger
events are not supported in the current version. You can currently specify
BEFORE or AFTER on INSERT, DELETE or UPDATE of a tuple as a trigger event.

17
doc/src/sgml/user.sgml
View file

@ -1,11 +1,16 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.6 1998/09/30 05:41:54 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.7 1998/10/30 19:37:16 thomas Exp $
Postgres User's Manual.
Derived from postgres.sgml.
thomas 1998-02-24
$Log: user.sgml,v $
Revision 1.7 1998/10/30 19:37:16 thomas
Minor editing and markup changes as a result of preparing the Postscript
documentation for v6.4.
Bigger updates to the installation instructions (install and config).
Revision 1.6 1998/09/30 05:41:54 thomas
Clean up pages. Add information for operator precedence.
Split introduction sections into separate files to allow the legal notice
@ -17,9 +22,6 @@ Add a separate chapter to the admin guide on security.
Revision 1.5 1998/08/17 16:20:32 thomas
Move SQL reference pages up into the User's Guide.
Revision 1.4 1998/08/15 06:52:54 thomas
Include new chapters.
-->
<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
@ -29,6 +31,7 @@ Include new chapters.
<!entity info SYSTEM "info.sgml">
<!entity legal SYSTEM "legal.sgml">
<!entity notation SYSTEM "notation.sgml">
<!entity y2k SYSTEM "y2k.sgml">
<!entity intro SYSTEM "intro.sgml">
<!entity advanced SYSTEM "advanced.sgml">
@ -87,7 +90,8 @@ Include new chapters.
<LegalNotice>
<Para>
<ProductName>PostgreSQL</ProductName> is copyright (C) 1998 by the Postgres Global Development Group.
<ProductName>PostgreSQL</ProductName> is copyright (C) 1998
by the Postgres Global Development Group.
</Para>
</LegalNotice>
@ -141,10 +145,13 @@ It provides SQL92/SQL3 language support,
<!--
&contacts;
-->
&biblio;
<!--
<index Id="index">
</index>
-->
</Book>

66
doc/src/sgml/xaggr.sgml
View file

@ -2,31 +2,36 @@
<Title>Extending <Acronym>SQL</Acronym>: Aggregates</Title>
<Para>
Aggregates in <ProductName>Postgres</ProductName> are expressed in terms of state
Aggregates in <ProductName>Postgres</ProductName>
are expressed in terms of state
transition functions. That is, an aggregate can be
defined in terms of state that is modified whenever an
instance is processed. Some state functions look at a
particular value in the instance when computing the new
state (<Acronym>sfunc1</Acronym> in the create aggregate syntax) while
state (<Acronym>sfunc1</Acronym> in the
create aggregate syntax) while
others only keep track of their own internal state
(<Acronym>sfunc2</Acronym>).
If we define an aggregate that uses only <Acronym>sfunc1</Acronym>, we
If we define an aggregate that uses only
<Acronym>sfunc1</Acronym>, we
define an aggregate that computes a running function of
the attribute values from each instance. "Sum" is an
example of this kind of aggregate. "Sum" starts at
zero and always adds the current instance's value to
its running total. We will use the <Acronym>int4pl</Acronym> that is
built into <ProductName>Postgres</ProductName> to perform this addition.
its running total. We will use the
<Acronym>int4pl</Acronym> that is
built into <ProductName>Postgres</ProductName>
to perform this addition.
<ProgramListing>
CREATE AGGREGATE complex_sum (
sfunc1 = complex_add,
basetype = complex,
stype1 = complex,
initcond1 = '(0,0)'
);
CREATE AGGREGATE complex_sum (
sfunc1 = complex_add,
basetype = complex,
stype1 = complex,
initcond1 = '(0,0)'
);
SELECT complex_sum(a) FROM test_complex;
SELECT complex_sum(a) FROM test_complex;
+------------+
|complex_sum |
@ -37,22 +42,27 @@
</Para>
<Para>
If we define only <Acronym>sfunc2</Acronym>, we are specifying an aggregate
If we define only <Acronym>sfunc2</Acronym>, we are
specifying an aggregate
that computes a running function that is independent of
the attribute values from each instance.
"Count" is the most common example of this kind of
aggregate. "Count" starts at zero and adds one to its
running total for each instance, ignoring the instance
value. Here, we use the built-in <Acronym>int4inc</Acronym> routine to do
value. Here, we use the built-in
<Acronym>int4inc</Acronym> routine to do
the work for us. This routine increments (adds one to)
its argument.
<ProgramListing>
CREATE AGGREGATE my_count (sfunc2 = int4inc, -- add one
basetype = int4, stype2 = int4,
initcond2 = '0')
CREATE AGGREGATE my_count (
sfunc2 = int4inc, -- add one
basetype = int4,
stype2 = int4,
initcond2 = '0'
);
SELECT my_count(*) as emp_count from EMP;
SELECT my_count(*) as emp_count from EMP;
+----------+
|emp_count |
@ -74,16 +84,18 @@
the count.
<ProgramListing>
CREATE AGGREGATE my_average (sfunc1 = int4pl, -- sum
basetype = int4,
stype1 = int4,
sfunc2 = int4inc, -- count
stype2 = int4,
finalfunc = int4div, -- division
initcond1 = '0',
initcond2 = '0')
CREATE AGGREGATE my_average (
sfunc1 = int4pl, -- sum
basetype = int4,
stype1 = int4,
sfunc2 = int4inc, -- count
stype2 = int4,
finalfunc = int4div, -- division
initcond1 = '0',
initcond2 = '0'
);
SELECT my_average(salary) as emp_average FROM EMP;
SELECT my_average(salary) as emp_average FROM EMP;
+------------+
|emp_average |

2
doc/src/sgml/xplang.sgml
View file

@ -1,5 +1,5 @@
<Chapter Id="xplang">
<Title>Extending <Acronym>SQL</Acronym>: Procedural languages</Title>
<Title>Procedural Languages</Title>
<!-- **********
* General information about procedural language support

2
doc/src/sgml/y2k.sgml
View file

@ -42,7 +42,7 @@ are documented in the current
<ulink url="http://www.postgresql.org/docs/user/datatype.htm">User's Guide</ulink>
in the chapter on data types.
For two-digit years, the significant transition year is 1970, not 2000;
i.e. <quote>70-01-01</quote> is interpreted as <quote>1970-01-01</quote>,
e.g. <quote>70-01-01</quote> is interpreted as <quote>1970-01-01</quote>,
whereas <quote>69-01-01</quote> is interpreted as <quote>2069-01-01</quote>.
<listitem>