From ab298522247148417fe3d4165df6356b5b143755 Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter_e@gmx.net>
Date: Sun, 4 Feb 2001 15:28:18 +0000
Subject: [PATCH] Move PL docs to programmer's guide, "storage" chapter to
admin guide, clean up some things in the affected areas.
---
doc/src/sgml/admin.sgml | 3 +-
doc/src/sgml/environ.sgml | 62 -----------------
doc/src/sgml/filelist.sgml | 14 ++--
doc/src/sgml/manage-ag.sgml | 4 +-
doc/src/sgml/manage.sgml | 18 +----
doc/src/sgml/programmer.sgml | 16 ++++-
doc/src/sgml/user.sgml | 7 +-
doc/src/sgml/xplang.sgml | 126 ++++++++++++++++++++---------------
8 files changed, 97 insertions(+), 153 deletions(-)
delete mode 100644 doc/src/sgml/environ.sgml
diff --git a/doc/src/sgml/admin.sgml b/doc/src/sgml/admin.sgml
index 51a78b3b306..f4ae0b182d4 100644
--- a/doc/src/sgml/admin.sgml
+++ b/doc/src/sgml/admin.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.32 2001/02/03 19:03:26 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.33 2001/02/04 15:28:18 petere Exp $
-->
<book id="admin">
@@ -31,6 +31,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/admin.sgml,v 1.32 2001/02/03 19:03:26
&user-manag;
&backup;
&wal;
+ &storage;
&recovery;
®ress;
&release;
diff --git a/doc/src/sgml/environ.sgml b/doc/src/sgml/environ.sgml
deleted file mode 100644
index dc5741a95d8..00000000000
--- a/doc/src/sgml/environ.sgml
+++ /dev/null
@@ -1,62 +0,0 @@
-<Chapter Id="environ">
-<Title>Setting Up Your Environment</Title>
-
-<Para>
- This section discusses how to set up
- your own environment so that you can use frontend
- applications. We assume <ProductName>Postgres</ProductName> has already been
- successfully installed and started; refer to the Administrator's Guide
-and the installation notes
- for how to install Postgres.
-</Para>
-
-<Para>
-<ProductName>Postgres</ProductName> is a client/server application. As a user,
-you only need access to the client portions of the installation (an example
-of a client application is the interactive monitor <Application>psql</Application>).
- 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 <Application>csh</Application> or <Application>tcsh</Application>,
- you would add
-<ProgramListing>
-set path = ( /usr/local/pgsql/bin path )
-</ProgramListing>
- in the <FileName>.login</FileName> file in your home directory. If you use
- a variant of the Bourne shell, such as <Application>sh</Application>, <Application>ksh</Application>, or
- <Application>bash</Application>, then you would add
-<ProgramListing>
-$ PATH=/usr/local/pgsql/bin:$PATH
-$ export PATH
-</ProgramListing>
- to the <FileName>.profile</FileName> 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 your site administrator has 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 <Acronym>PGHOST</Acronym> environment variable to the name
-of the database server machine. The environment variable
-<Acronym>PGPORT</Acronym> 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 should immediately consult your site administrator to make sure that your
-environment is properly set up.
-</Para>
-
-</Chapter>
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index ae27be1999a..f38c6b0cd22 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -1,4 +1,4 @@
-<!-- $Header: /cvsroot/pgsql/doc/src/sgml/filelist.sgml,v 1.7 2001/02/03 19:03:26 petere Exp $ -->
+<!-- $Header: /cvsroot/pgsql/doc/src/sgml/filelist.sgml,v 1.8 2001/02/04 15:28:18 petere Exp $ -->
<!entity history SYSTEM "history.sgml">
<!entity info SYSTEM "info.sgml">
@@ -8,6 +8,7 @@
<!entity y2k SYSTEM "y2k.sgml">
<!-- tutorial -->
+<!entity advanced SYSTEM "advanced.sgml">
<!entity arch SYSTEM "arch.sgml">
<!entity intro SYSTEM "intro.sgml">
<!entity query SYSTEM "query.sgml">
@@ -15,23 +16,16 @@
<!entity start SYSTEM "start.sgml">
<!-- user's guide -->
-<!entity advanced SYSTEM "advanced.sgml">
<!entity array SYSTEM "array.sgml">
<!entity datatype SYSTEM "datatype.sgml">
<!entity datetime SYSTEM "datetime.sgml">
-<!entity environ SYSTEM "environ.sgml">
<!entity func SYSTEM "func.sgml">
<!entity indices SYSTEM "indices.sgml">
<!entity inherit SYSTEM "inherit.sgml">
<!entity manage SYSTEM "manage.sgml">
<!entity mvcc SYSTEM "mvcc.sgml">
<!entity perform SYSTEM "perform.sgml">
-<!entity plperl SYSTEM "plperl.sgml">
-<!entity plsql SYSTEM "plsql.sgml">
-<!entity pltcl SYSTEM "pltcl.sgml">
-<!entity psql SYSTEM "psql.sgml">
<!entity queries SYSTEM "queries.sgml">
-<!entity storage SYSTEM "storage.sgml">
<!entity syntax SYSTEM "syntax.sgml">
<!entity typeconv SYSTEM "typeconv.sgml">
<!entity keywords SYSTEM "keywords.sgml">
@@ -51,6 +45,7 @@
<!entity regress SYSTEM "regress.sgml">
<!entity release SYSTEM "release.sgml">
<!entity runtime SYSTEM "runtime.sgml">
+<!entity storage SYSTEM "storage.sgml">
<!entity user-manag SYSTEM "user-manag.sgml">
<!entity wal SYSTEM "wal.sgml">
@@ -79,6 +74,9 @@
<!entity xplang SYSTEM "xplang.sgml">
<!entity xoper SYSTEM "xoper.sgml">
<!entity xtypes SYSTEM "xtypes.sgml">
+<!entity plperl SYSTEM "plperl.sgml">
+<!entity plsql SYSTEM "plsql.sgml">
+<!entity pltcl SYSTEM "pltcl.sgml">
<!-- developer's guide -->
<!entity arch-dev SYSTEM "arch-dev.sgml">
diff --git a/doc/src/sgml/manage-ag.sgml b/doc/src/sgml/manage-ag.sgml
index 5ac9776eac1..1cd500b3b0b 100644
--- a/doc/src/sgml/manage-ag.sgml
+++ b/doc/src/sgml/manage-ag.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/manage-ag.sgml,v 2.11 2000/09/29 20:21:34 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/manage-ag.sgml,v 2.12 2001/02/04 15:28:18 petere Exp $
-->
<chapter id="managing-databases">
@@ -174,7 +174,7 @@ CREATE DATABASE <replaceable>name</> WITH LOCATION = '<replaceable>location</>'
risk. To allow it, you must compile <productname>Postgres</> with
the C preprocessor macro <literal>ALLOW_ABSOLUTE_DBPATHS</>
defined. One way to do this is to run the compilation step like
- this: <userinput>gmake COPT=-DALLOW_ABSOLUTE_DBPATHS all</>.
+ this: <userinput>gmake CPPFLAGS=-DALLOW_ABSOLUTE_DBPATHS all</>.
</para>
</note>
diff --git a/doc/src/sgml/manage.sgml b/doc/src/sgml/manage.sgml
index 43e21b30ef3..8c363d536ee 100644
--- a/doc/src/sgml/manage.sgml
+++ b/doc/src/sgml/manage.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/manage.sgml,v 1.12 2000/10/08 19:44:01 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/manage.sgml,v 1.13 2001/02/04 15:28:18 petere Exp $
-->
<Chapter Id="manage">
@@ -256,22 +256,6 @@ mydb=> \q
are denoted by "<literal>/* ... */</literal>".
</Para>
-<Sect2>
-<Title>Database Privileges</Title>
-
-<Para>
-</para>
-</Sect2>
-
-<Sect2>
-<Title>Table Privileges</Title>
-
-<Para>
-TBD
-</Para>
-
-</Sect2>
-
</Sect1>
<Sect1 id="db-destroy">
diff --git a/doc/src/sgml/programmer.sgml b/doc/src/sgml/programmer.sgml
index 81bbf426539..f4f3812fdd1 100644
--- a/doc/src/sgml/programmer.sgml
+++ b/doc/src/sgml/programmer.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.33 2001/02/03 19:03:27 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.34 2001/02/04 15:28:18 petere Exp $
PostgreSQL Programmer's Guide.
-->
@@ -28,7 +28,9 @@ PostgreSQL Programmer's Guide.
operators, aggregates, and both query language and programming
language functions. After a discussion of the
<productname>PostgreSQL</productname> rule system, we discuss the
- trigger and SPI interfaces.
+ trigger and SPI interfaces. The third part documents the
+ procedural languages available in the
+ <productname>PostgreSQL</productname> distribution.
</para>
<para>
@@ -61,7 +63,6 @@ PostgreSQL Programmer's Guide.
&xindex;
&indexcost;
&gist;
- &xplang;
<!-- reference -->
@@ -76,6 +77,15 @@ Disable it until we put in some info.
&spi;
</part>
+ <part id="programmer-pl">
+ <title>Procedural Languages</title>
+
+ &xplang;
+ &plsql;
+ &pltcl;
+ &plperl;
+ </part>
+
<![%single-book;[
&biblio;
]]>
diff --git a/doc/src/sgml/user.sgml b/doc/src/sgml/user.sgml
index f0b3f4e5e3b..7a4f8a3caa1 100644
--- a/doc/src/sgml/user.sgml
+++ b/doc/src/sgml/user.sgml
@@ -1,5 +1,5 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.27 2001/02/03 19:03:27 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.28 2001/02/04 15:28:18 petere Exp $
-->
<book id="user">
@@ -23,13 +23,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.27 2001/02/03 19:03:27
&array;
&indices;
&inherit;
- &plsql;
- &pltcl;
- &plperl;
&mvcc;
- &environ;
&manage;
- &storage;
&perform;
<!-- appendices -->
diff --git a/doc/src/sgml/xplang.sgml b/doc/src/sgml/xplang.sgml
index e83ee504690..5c135267774 100644
--- a/doc/src/sgml/xplang.sgml
+++ b/doc/src/sgml/xplang.sgml
@@ -1,26 +1,31 @@
<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.10 2000/11/04 21:06:37 momjian Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.11 2001/02/04 15:28:18 petere Exp $
-->
<chapter id="xplang">
<title id="xplang-title">Procedural Languages</title>
<para>
- <productname>Postgres</productname> supports
- the definition of procedural languages.
- In the case of a function or trigger
- procedure defined in a procedural language, the database has
+ <productname>Postgres</productname> allows users to add new
+ programming languages to be available for writing functions and
+ procedures. These are called <firstterm>procedural
+ languages</firstterm> (PL). In the case of a function or trigger
+ procedure written in a procedural language, the database server has
no built-in knowledge about how to interpret the function's source
- text. Instead, the task is passed to
- a handler that knows the details of the language. The
- handler itself is a special programming language function
- compiled into a shared object
- and loaded on demand.
+ text. Instead, the task is passed to a special handler that knows
+ the details of the language. The handler could either do all the
+ work of parsing, syntax analysis, execution, etc. itself, or it
+ could serve as a <quote>glue</quote> between
+ <productname>Postgres</productname> and an existing implementation
+ of a programming language. The handler itself is a special
+ programming language function compiled into a shared object and
+ loaded on demand.
</para>
<para>
- Writing a handler for a new procedural language (PL)
- is outside the scope of this manual.
+ Writing a handler for a new procedural language is outside the
+ scope of this manual. Several procedural languages are available
+ in the <productname>Postgres</productname> distribution.
</para>
<sect1 id="xplang-install">
@@ -32,86 +37,107 @@ $Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.10 2000/11/04 21:06:37 momj
</title>
<para>
- A procedural language is installed in the database in three steps.
- (For the languages supplied with the standard distribution, the
- shell script <filename>createlang</filename> can be used instead
- of carrying out the details manually.)
+ A procedural language is installed in the database in three
+ steps. A procedural language must be installed into each
+ database where it is to be used. Procedural languages defined in
+ the template1 database are automatically available in all
+ subsequently created databases. So the administrator can decide
+ which languages are available by default.
</para>
- <step performance="Required">
+ <step performance="required">
<para>
- The shared object for the language handler
- must be compiled and installed. By default the
- handler for PL/pgSQL is built and installed into the
- database library directory. If Tcl/Tk support is
- configured in, the handler for PL/Tcl is also built
- and installed in the same location.
+ The shared object for the language handler must be compiled and
+ installed. This works in the same way as building and
+ installing modules with regular user-defined C functions does;
+ see <xref linkend="dfunc">.
</para>
</step>
- <step performance="Required">
+
+ <step performance="required">
<para>
The handler must be declared with the command
- <programlisting>
+<synopsis>
CREATE FUNCTION <replaceable>handler_function_name</replaceable> ()
RETURNS OPAQUE AS
- '<filename>path-to-shared-object</filename>' LANGUAGE 'C';
- </programlisting>
- The special return type of <acronym>OPAQUE</acronym> tells
+ '<replaceable>path-to-shared-object</replaceable>' LANGUAGE 'C';
+</synopsis>
+ The special return type of <type>OPAQUE</type> tells
the database that this function does not return one of
- the defined <acronym>SQL</acronym> datatypes and is not directly usable
+ the defined <acronym>SQL</acronym> data types and is not directly usable
in <acronym>SQL</acronym> statements.
</para>
</step>
- <step performance="Required">
+
+ <step performance="required">
<para>
The PL must be declared with the command
- <programlisting>
-CREATE [ TRUSTED ] [ PROCEDURAL ] LANGUAGE '<replaceable>language-name</replaceable>'
+<synopsis>
+CREATE <optional>TRUSTED</optional> <optional>PROCEDURAL</optional> LANGUAGE '<replaceable>language-name</replaceable>'
HANDLER <replaceable>handler_function_name</replaceable>
LANCOMPILER '<replaceable>description</replaceable>';
- </programlisting>
- The optional keyword <acronym>TRUSTED</acronym> tells
+</synopsis>
+ The optional key word <token>TRUSTED</token> tells
whether ordinary database users that have no superuser
privileges should be allowed to use this language to create functions
and trigger procedures. Since PL functions are
executed inside the database backend, the <acronym>TRUSTED</acronym>
flag should only be given for
- languages that don't allow access to database backends
+ languages that do not allow access to database backends
internals or the filesystem. The languages PL/pgSQL and
PL/Tcl are known to be trusted.
</para>
</step>
</procedure>
+ <para>
+ In a default <productname>Postgres</productname> installation, the
+ handler for the PL/pgSQL is built and installed into the
+ <quote>library</quote> directory. If Tcl/Tk support is configured
+ in, the handler for PL/Tcl is also built and installed in the same
+ location.
+ </para>
+
<procedure>
<title>Example</title>
- <step performance="Required">
+
+ <step performance="required">
<para>
The following command tells the database where to find the
shared object for the PL/pgSQL language's call handler function.
- <programlisting>
+<programlisting>
CREATE FUNCTION plpgsql_call_handler () RETURNS OPAQUE AS
'/usr/local/pgsql/lib/plpgsql.so' LANGUAGE 'C';
- </programlisting>
+</programlisting>
</para>
</step>
<step performance="Required">
<para>
The command
- <programlisting>
+<programlisting>
CREATE TRUSTED PROCEDURAL LANGUAGE 'plpgsql'
HANDLER plpgsql_call_handler
LANCOMPILER 'PL/pgSQL';
- </programlisting>
+</programlisting>
+ then defines that the previously declared call handler function
+ should be invoked for functions and trigger procedures where the
+ language attribute is 'plpgsql'.
</para>
+ </step>
+ </procedure>
+
+ <para>
+ For the languages supplied with the standard distribution, the
+ shell script <filename>createlang</filename> can be used instead
+ of carrying out the details manually. To install PL/pgSQL into
+ the template1 database, use
+<programlisting>
+createlang plpgsql template1
+</programlisting>
+ </para>
- <para>
- then defines that the previously declared call handler
- function should be invoked for functions and trigger procedures
- where the language attribute is 'plpgsql'.
- </para>
<para>
PL handler functions have a special call interface that is
different from regular C language functions. One of the arguments
@@ -126,17 +152,9 @@ CREATE TRUSTED PROCEDURAL LANGUAGE 'plpgsql'
multiple different PL functions having the same function name,
as long as the call arguments differ.
</para>
- <para>
- Procedural languages defined in the <filename>template1</filename>
- database are automatically defined in all subsequently created
- databases. So the database administrator can decide which
- languages are available by default.
- </para>
- </step>
- </procedure>
+
</sect1>
- <!-- **** End of PL installation **** -->
</chapter>
<!-- Keep this comment at the end of the file
--
GitLab