11<!--
2- $Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.11 2001/02/04 15:28:18 petere Exp $
2+ $Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.12 2001/02/09 02:20:52 tgl Exp $
33-->
44
55 <chapter id="xplang">
@@ -15,7 +15,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.11 2001/02/04 15:28:18 pete
1515 text. Instead, the task is passed to a special handler that knows
1616 the details of the language. The handler could either do all the
1717 work of parsing, syntax analysis, execution, etc. itself, or it
18- could serve asa <quote>glue</quote> between
18+ could serve as <quote>glue</quote> between
1919 <productname>Postgres</productname> and an existing implementation
2020 of a programming language. The handler itself is a special
2121 programming language function compiled into a shared object and
@@ -24,33 +24,52 @@ $Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.11 2001/02/04 15:28:18 pete
2424
2525 <para>
2626 Writing a handler for a new procedural language is outside the
27- scope of this manual. Several procedural languages are available
28- in the <productname>Postgres</productname> distribution.
27+ scope of this manual, although some information is provided in
28+ the CREATE LANGUAGE reference page. Several procedural languages are
29+ available in the standard <productname>Postgres</productname> distribution.
2930 </para>
3031
3132 <sect1 id="xplang-install">
3233 <title>Installing Procedural Languages</title>
3334
35+ <para>
36+ A procedural language must be <quote>installed</quote> into each
37+ database where it is to be used. But procedural languages installed in
38+ the template1 database are automatically available in all
39+ subsequently created databases. So the database administrator can
40+ decide which languages are available in which databases, and can make
41+ some languages available by default if he chooses.
42+ </para>
43+
44+ <para>
45+ For the languages supplied with the standard distribution, the
46+ shell script <filename>createlang</filename> may be used instead
47+ of carrying out the details by hand. For example, to install PL/pgSQL
48+ into the template1 database, use
49+ <programlisting>
50+ createlang plpgsql template1
51+ </programlisting>
52+ The manual procedure described below is only recommended for
53+ installing custom languages that <filename>createlang</filename>
54+ does not know about.
55+ </para>
56+
3457 <procedure>
3558 <title>
36- Procedural Language Installation
59+ Manual Procedural Language Installation
3760 </title>
3861
3962 <para>
4063 A procedural language is installed in the database in three
41- steps. A procedural language must be installed into each
42- database where it is to be used. Procedural languages defined in
43- the template1 database are automatically available in all
44- subsequently created databases. So the administrator can decide
45- which languages are available by default.
64+ steps, which must be carried out by a database superuser.
4665 </para>
4766
4867 <step performance="required">
4968 <para>
5069 The shared object for the language handler must be compiled and
51- installed. This works in the same way as building and
52- installing modules with regular user-defined C functions does;
53- see <xref linkend="dfunc">.
70+ installed into an appropriate library directory . This works in the same
71+ way as building and installing modules with regular user-defined C
72+ functions does; see <xref linkend="dfunc">.
5473 </para>
5574 </step>
5675
@@ -84,18 +103,21 @@ CREATE <optional>TRUSTED</optional> <optional>PROCEDURAL</optional> LANGUAGE '<r
84103 executed inside the database backend, the <acronym>TRUSTED</acronym>
85104 flag should only be given for
86105 languages that do not allow access to database backends
87- internals or the filesystem. The languages PL/pgSQL and
88- PL/Tcl are known to be trusted.
106+ internals or the filesystem. The languages PL/pgSQL,
107+ PL/Tcl, and PL/Perl are known to be trusted; the language PL/TclU
108+ should <emphasis>not</emphasis> be marked trusted.
89109 </para>
90110 </step>
91111 </procedure>
92112
93113 <para>
94114 In a default <productname>Postgres</productname> installation, the
95- handler for the PL/pgSQL is built and installed into the
115+ handler for the PL/pgSQLlanguage is built and installed into the
96116 <quote>library</quote> directory. If Tcl/Tk support is configured
97- in, the handler for PL/Tcl is also built and installed in the same
98- location.
117+ in, the handlers for PL/Tcl and PL/TclU are also built and installed in
118+ the same location. Likewise, the PL/Perl handler is built and installed
119+ if Perl support is configured. The <filename>createlang</filename>
120+ script automates the two CREATE steps described above.
99121 </para>
100122
101123 <procedure>
@@ -128,31 +150,6 @@ CREATE TRUSTED PROCEDURAL LANGUAGE 'plpgsql'
128150 </step>
129151 </procedure>
130152
131- <para>
132- For the languages supplied with the standard distribution, the
133- shell script <filename>createlang</filename> can be used instead
134- of carrying out the details manually. To install PL/pgSQL into
135- the template1 database, use
136- <programlisting>
137- createlang plpgsql template1
138- </programlisting>
139- </para>
140-
141- <para>
142- PL handler functions have a special call interface that is
143- different from regular C language functions. One of the arguments
144- given to the handler is the object ID in the <filename>pg_proc</filename>
145- tables entry for the function that should be executed.
146- The handler examines various system catalogs to analyze the
147- functions call arguments and it's return data type. The source
148- text of the functions body is found in the prosrc attribute of
149- <literal>pg_proc</literal>.
150- Due to this, PL functions
151- can be overloaded like SQL language functions. There can be
152- multiple different PL functions having the same function name,
153- as long as the call arguments differ.
154- </para>
155-
156153 </sect1>
157154
158155</chapter>