Update PL documentation:

An article at WebProNews quoted from the PG docs as to the merits of
stored procedures.  I have added a bit more material on their merits,
as well as making a few changes to improve the introductions to
PL/Perl and PL/Tcl.

Chris Browne

diff --git a/doc/src/sgml/plperl.sgml b/doc/src/sgml/plperl.sgml
index 94a375587fc6f6d020ed500d93fa2845077f1e37..12ac0157c3ee37a79ea5e4631a7cfa60400c28cd 100644 (file)
--- a/doc/src/sgml/plperl.sgml
+++ b/doc/src/sgml/plperl.sgml
@@ -1,4 +1,4 @@
-
+
 
  
   PL/Perl - Perl Procedural Language
@@ -17,6 +17,12 @@
    Perl programming language.
   
 
+   The usual advantage to using PL/Perl is that this allows use,
+   within stored functions, of the manyfold string
+    munging operators and functions available for Perl.  Parsing
+   complex strings may be be easier using Perl than it is with the
+   string functions and control structures provided in PL/pgsql.
+  
   
    To install PL/Perl in a particular database, use
    createlang plperl dbname.

diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index 4f302a858e7167b61ecbbb35a62d6d34f535e9b1..2fc998ee909e8259d264fa10595d012590ea9bf5 100644 (file)
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -1,4 +1,4 @@
-
+
 
  
   <application>PL/pgSQL</application> - <acronym>SQL</acronym> Procedural Language
@@ -155,21 +155,36 @@ $$ LANGUAGE plpgsql;
 
     
      That means that your client application must send each query to
-     the database server, wait for it to be processed, receive the
-     results, do some computation, then send other queries to the
-     server. All this incurs interprocess communication and may also
-     incur network overhead if your client is on a different machine
-     than the database server.
+     the database server, wait for it to be processed, receive and
+     process the results, do some computation, then send further
+     queries to the server.  All this incurs interprocess
+     communication and will also incur network overhead if your client
+     is on a different machine than the database server.
     
 
     
-     With PL/pgSQL you can group a block of computation and a
-     series of queries inside the
-     database server, thus having the power of a procedural
-     language and the ease of use of SQL, but saving lots of
-     time because you don't have the whole client/server
-     communication overhead. This can make for a
-     considerable performance increase.
+     With PL/pgSQL you can group a block of
+     computation and a series of queries inside
+     the database server, thus having the power of a procedural
+     language and the ease of use of SQL, but with considerable
+     savings because you don't have the whole client/server
+     communication overhead.
+    
+    
+
+      Elimination of additional round trips between
+     client and server 
+
+      Intermediate results that the client does not
+     need do not need to be marshalled or transferred between server
+     and client 
+
+      There is no need for additional rounds of query
+     parsing 
+
+    
+     This can allow for a considerable performance increase as
+    compared to an application that does not use stored functions.
     
 
     

diff --git a/doc/src/sgml/pltcl.sgml b/doc/src/sgml/pltcl.sgml
index 3ffaf81fe5ee64762688ba37839e628ec25b7219..d4bdabeeaed46e15604736f66df6c58f2a0221d4 100644 (file)
--- a/doc/src/sgml/pltcl.sgml
+++ b/doc/src/sgml/pltcl.sgml
@@ -1,4 +1,4 @@
-
+
 
  
   PL/Tcl - Tcl Procedural Language
@@ -25,22 +25,27 @@
    Overview
 
    
-    PL/Tcl offers most of the capabilities a function
-    writer has in the C language, except for some restrictions.
+    PL/Tcl offers most of the capabilities a function writer has in
+    the C language, with a few restrictions, and with the addition of
+    the powerful string processing libraries that are available for
+    Tcl.
    
    
-    The good restriction is that everything is executed in a safe
-    Tcl interpreter. In addition to the limited command set of safe Tcl, only
-    a few commands are available to access the database via SPI and to raise
-    messages via elog(). There is no way to access internals of the
-    database server or to gain OS-level access under the permissions of the
-    PostgreSQL server process, as a C function can do.
-    Thus, any unprivileged database user may be
-    permitted to use this language.
+    One compelling good restriction is that
+    everything is executed from within the safety of the context of a
+    Tcl interpreter.  In addition to the limited command set of safe
+    Tcl, only a few commands are available to access the database via
+    SPI and to raise messages via elog().  PL/Tcl
+    provides no way to access internals of the database server or to
+    gain OS-level access under the permissions of the
+    PostgreSQL server process, as a C
+    function can do.  Thus, unprivileged database users may be trusted
+    to use this language; it does not give them unlimited authority.
    
    
-    The other, implementation restriction is that Tcl functions cannot
-    be used to create input/output functions for new data types.
+    The other notable implementation restriction is that Tcl functions
+    may not be used to create input/output functions for new data
+    types.
    
    
     Sometimes it is desirable to write Tcl functions that are not restricted
@@ -55,12 +60,12 @@
     a user logged in as the database administrator.
    
    
-    The shared object for the PL/Tcl and PL/TclU call handlers is
-    automatically built and installed in the
-    PostgreSQL 
-    library directory if Tcl support is specified
-    in the configuration step of the installation procedure.  To install
-    PL/Tcl and/or PL/TclU in a particular database, use the
+    The shared object code for the PL/Tcl and
+    PL/TclU call handlers is automatically built and
+    installed in the PostgreSQL library
+    directory if Tcl support is specified in the configuration step of
+    the installation procedure.  To install PL/Tcl
+    and/or PL/TclU in a particular database, use the
     createlang program, for example
     createlang pltcl dbname or
     createlang pltclu dbname.