database/postgres
database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-04-29 13:56:47 +03:00
Code

General editing

Browse Source
This commit is contained in:
Peter Eisentraut 2003-04-07 01:29:26 +00:00
parent cb1d036acb
commit a8cb3368db
8 changed files with 1395 additions and 1717 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/src/sgml/datetime.sgml
View File

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/datetime.sgml,v 2.30 2003/03/13 01:30:27 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/datetime.sgml,v 2.31 2003/04/07 01:29:25 petere Exp $
-->
<appendix id="datetime-appendix">
@ -210,7 +210,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/datetime.sgml,v 2.30 2003/03/13 01:30:27 pe
</sect1>
<sect1>
<sect1 id="datetime-keywords">
<title>Date/Time Key Words</title>
<para>

572
doc/src/sgml/jdbc.sgml
View File

File diff suppressed because it is too large Load Diff

24
doc/src/sgml/plperl.sgml
View File

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/plperl.sgml,v 2.18 2002/09/21 18:32:53 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/plperl.sgml,v 2.19 2003/04/07 01:29:25 petere Exp $
-->
<chapter id="plperl">
@ -34,8 +34,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/plperl.sgml,v 2.18 2002/09/21 18:32:53 pete
<note>
<para>
Users of source packages must specially enable the build of
PL/Perl during the installation process (refer to the installation
instructions for more information). Users of binary packages
PL/Perl during the installation process. (Refer to the installation
instructions for more information.) Users of binary packages
might find PL/Perl in a separate subpackage.
</para>
</note>
@ -57,8 +57,12 @@ CREATE FUNCTION <replaceable>funcname</replaceable> (<replaceable>argument-types
Arguments and results are handled as in any other Perl subroutine:
Arguments are passed in <varname>@_</varname>, and a result value
is returned with <literal>return</> or as the last expression
evaluated in the function. For example, a function returning the
greater of two integer values could be defined as:
evaluated in the function.
</para>
<para>
For example, a function returning the greater of two integer values
could be defined as:
<programlisting>
CREATE FUNCTION perl_max (integer, integer) RETURNS integer AS '
@ -145,7 +149,7 @@ SELECT name, empcomp(employee) FROM employee;
<title>Data Values in PL/Perl</title>
<para>
The argument values supplied to a PL/Perl function's script are
The argument values supplied to a PL/Perl function's code are
simply the input arguments converted to text form (just as if they
had been displayed by a <literal>SELECT</literal> statement).
Conversely, the <literal>return</> command will accept any string
@ -206,8 +210,8 @@ SELECT name, empcomp(employee) FROM employee;
environment. This includes file handle operations,
<literal>require</literal>, and <literal>use</literal> (for
external modules). There is no way to access internals of the
database backend process or to gain OS-level access with the
permissions of the <productname>PostgreSQL</productname> user ID,
database server process or to gain OS-level access with the
permissions of the server process,
as a C function can do. Thus, any unprivileged database user may
be permitted to use this language.
</para>
@ -227,7 +231,7 @@ CREATE FUNCTION badfunc() RETURNS integer AS '
<para>
Sometimes it is desirable to write Perl functions that are not
restricted --- for example, one might want a Perl function that
restricted. For example, one might want a Perl function that
sends mail. To handle these cases, PL/Perl can also be installed
as an <quote>untrusted</> language (usually called
<application>PL/PerlU</application>). In this case the full Perl language is
@ -255,7 +259,7 @@ CREATE FUNCTION badfunc() RETURNS integer AS '
<para>
The following features are currently missing from PL/Perl, but they
would make welcome contributions:
would make welcome contributions.
<itemizedlist>
<listitem>

1819
doc/src/sgml/plpgsql.sgml
View File

File diff suppressed because it is too large Load Diff

62
doc/src/sgml/plpython.sgml
View File

@ -1,4 +1,4 @@
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/plpython.sgml,v 1.15 2002/10/21 20:34:09 momjian Exp $ -->
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/plpython.sgml,v 1.16 2003/04/07 01:29:25 petere Exp $ -->
<chapter id="plpython">
<title>PL/Python - Python Procedural Language</title>
@ -17,11 +17,18 @@
<literal>createlang plpython <replaceable>dbname</></literal>.
</para>
<tip>
<para>
If a language is installed into <literal>template1</>, all subsequently
created databases will have the language installed automatically.
</para>
</tip>
<note>
<para>
Users of source packages must specially enable the build of
PL/Python during the installation process (refer to the
installation instructions for more information). Users of binary
PL/Python during the installation process. (Refer to the
installation instructions for more information.) Users of binary
packages might find PL/Python in a separate subpackage.
</para>
</note>
@ -30,11 +37,11 @@
<title>PL/Python Functions</title>
<para>
The Python code you write gets transformed into a function. E.g.,
The Python code you write gets transformed into a Python function. E.g.,
<programlisting>
CREATE FUNCTION myfunc(text) RETURNS text
AS 'return args[0]'
LANGUAGE 'plpython';
LANGUAGE plpython;
</programlisting>
gets transformed into
@ -49,7 +56,7 @@ def __plpython_procedure_myfunc_23456():
<para>
If you do not provide a return value, Python returns the default
<symbol>None</symbol> which may or may not be what you want. The
<symbol>None</symbol>. The
language module translates Python's <symbol>None</symbol> into the
SQL null value.
</para>
@ -60,8 +67,8 @@ def __plpython_procedure_myfunc_23456():
<function>myfunc</function> example, <varname>args[0]</> contains
whatever was passed in as the text argument. For
<literal>myfunc2(text, integer)</literal>, <varname>args[0]</>
would contain the <type>text</type> variable and
<varname>args[1]</varname> the <type>integer</type> variable.
would contain the <type>text</type> argument and
<varname>args[1]</varname> the <type>integer</type> argument.
</para>
<para>
@ -95,14 +102,14 @@ def __plpython_procedure_myfunc_23456():
<literal>TD["level"]</> contains one of <literal>ROW</>,
<literal>STATEMENT</>, and <literal>UNKNOWN</>.
<literal>TD["name"]</> contains the trigger name, and
<literal>TD["relid"]</> contains the relation ID of the table on
<literal>TD["relid"]</> contains the OID of the table on
which the trigger occurred. If the trigger was called with
arguments they are available in <literal>TD["args"][0]</> to
<literal>TD["args"][(n-1)]</>.
</para>
<para>
If the <literal>TD["when"]</literal> is <literal>BEFORE</>, you may
If <literal>TD["when"]</literal> is <literal>BEFORE</>, you may
return <literal>None</literal> or <literal>"OK"</literal> from the
Python function to indicate the row is unmodified,
<literal>"SKIP"</> to abort the event, or <literal>"MODIFY"</> to
@ -147,10 +154,10 @@ def __plpython_procedure_myfunc_23456():
optional limit argument causes that query to be run and the result
to be returned in a result object. The result object emulates a
list or dictionary object. The result object can be accessed by
row number and field name. It has these additional methods:
<function>nrows()</function> which returns the number of rows
row number and column name. It has these additional methods:
<function>nrows</function> which returns the number of rows
returned by the query, and <function>status</function> which is the
<function>SPI_exec</function> return variable. The result object
<function>SPI_exec()</function> return value. The result object
can be modified.
</para>
@ -161,27 +168,27 @@ rv = plpy.execute("SELECT * FROM my_table", 5)
</programlisting>
returns up to 5 rows from <literal>my_table</literal>. If
<literal>my_table</literal> has a column
<literal>my_field</literal>, it would be accessed as
<literal>my_column</literal>, it would be accessed as
<programlisting>
foo = rv[i]["my_field"]
foo = rv[i]["my_column"]
</programlisting>
</para>
<para>
The second function <function>plpy.prepare</function> is called
with a query string and a list of argument types if you have bind
variables in the query. For example:
The second function, <function>plpy.prepare</function>, prepares the
execution plan for a query. It is called with a query string and a
list of parameter types, if you have parameter references in the
query. For example:
<programlisting>
plan = plpy.prepare("SELECT last_name FROM my_users WHERE first_name = $1", [ "text" ])
</programlisting>
<literal>text</literal> is the type of the variable you will be
passing as <literal>$1</literal>. After preparing a statement, you
passing for <literal>$1</literal>. After preparing a statement, you
use the function <function>plpy.execute</function> to run it:
<programlisting>
rv = plpy.execute(plan, [ "name" ], 5)
</programlisting>
The limit argument is optional in the call to
<function>plpy.execute</function>.
The third argument is the limit and is optional.
</para>
<para>
@ -190,7 +197,7 @@ rv = plpy.execute(plan, [ "name" ], 5)
in the immediate termination of that function by the server; it is
not possible to trap error conditions using Python <literal>try
... catch</literal> constructs. For example, a syntax error in an
SQL statement passed to the <literal>plpy.execute()</literal> call
SQL statement passed to the <literal>plpy.execute</literal> call
will terminate the function. This behavior may be changed in a
future release.
</para>
@ -199,22 +206,19 @@ rv = plpy.execute(plan, [ "name" ], 5)
When you prepare a plan using the PL/Python module it is
automatically saved. Read the SPI documentation (<xref
linkend="spi">) for a description of what this means.
</para>
<para>
In order to make effective use of this across function calls
one needs to use one of the persistent storage dictionaries
<literal>SD</literal> or <literal>GD</literal>, see
<xref linkend="plpython-funcs">. For example:
<literal>SD</literal> or <literal>GD</literal> (see
<xref linkend="plpython-funcs">). For example:
<programlisting>
CREATE FUNCTION usesavedplan ( ) RETURNS TRIGGER AS '
CREATE FUNCTION usesavedplan() RETURNS trigger AS '
if SD.has_key("plan"):
plan = SD["plan"]
else:
plan = plpy.prepare("SELECT 1")
SD["plan"] = plan
# rest of function
' LANGUAGE 'plpython';
' LANGUAGE plpython;
</programlisting>
</para>
</sect1>

353
doc/src/sgml/pltcl.sgml
View File

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/pltcl.sgml,v 2.22 2002/09/21 18:32:53 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/pltcl.sgml,v 2.23 2003/04/07 01:29:25 petere Exp $
-->
<chapter id="pltcl">
@ -20,10 +20,6 @@ $Header: /cvsroot/pgsql/doc/src/sgml/pltcl.sgml,v 2.22 2002/09/21 18:32:53 peter
trigger procedures.
</para>
<para>
This package was originally written by Jan Wieck.
</para>
<!-- **** PL/Tcl overview **** -->
<sect1 id="pltcl-overview">
@ -38,19 +34,19 @@ $Header: /cvsroot/pgsql/doc/src/sgml/pltcl.sgml,v 2.22 2002/09/21 18:32:53 peter
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 <function>elog()</>. There is no way to access internals of the
database backend or to gain OS-level access under the permissions of the
<productname>PostgreSQL</productname> user ID, as a C function can do.
database server or to gain OS-level access under the permissions of the
<productname>PostgreSQL</productname> server process, as a C function can do.
Thus, any unprivileged database user may be
permitted to use this language.
</para>
<para>
The other, implementation restriction is that Tcl procedures cannot
The other, implementation restriction is that Tcl functions cannot
be used to create input/output functions for new data types.
</para>
<para>
Sometimes it is desirable to write Tcl functions that are not restricted
to safe Tcl --- for example, one might want a Tcl function that sends
mail. To handle these cases, there is a variant of <application>PL/Tcl</> called <literal>PL/TclU</>
to safe Tcl. For example, one might want a Tcl function that sends
email. To handle these cases, there is a variant of <application>PL/Tcl</> called <literal>PL/TclU</>
(for untrusted Tcl). This is the exact same language except that a full
Tcl interpreter is used. <emphasis>If <application>PL/TclU</> is used, it must be
installed as an untrusted procedural language</emphasis> so that only
@ -66,7 +62,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/pltcl.sgml,v 2.22 2002/09/21 18:32:53 peter
library directory if Tcl/Tk support is specified
in the configuration step of the installation procedure. To install
<application>PL/Tcl</> and/or <application>PL/TclU</> in a particular database, use the
<filename>createlang</filename> script, for example
<command>createlang</command> program, for example
<literal>createlang pltcl <replaceable>dbname</></literal> or
<literal>createlang pltclu <replaceable>dbname</></literal>.
</para>
@ -74,58 +70,59 @@ $Header: /cvsroot/pgsql/doc/src/sgml/pltcl.sgml,v 2.22 2002/09/21 18:32:53 peter
<!-- **** PL/Tcl description **** -->
<sect1 id="pltcl-description">
<title>Description</title>
<sect2>
<sect1 id="pltcl-functions">
<title>PL/Tcl Functions and Arguments</title>
<para>
To create a function in the <application>PL/Tcl</> language, use the standard syntax
To create a function in the <application>PL/Tcl</> language, use the standard syntax:
<programlisting>
<programlisting>
CREATE FUNCTION <replaceable>funcname</replaceable> (<replaceable>argument-types</replaceable>) RETURNS <replaceable>return-type</replaceable> AS '
# PL/Tcl function body
' LANGUAGE 'pltcl';
</programlisting>
' LANGUAGE pltcl;
</programlisting>
<application>PL/TclU</> is the same, except that the language should be specified as
<application>PL/TclU</> is the same, except that the language has to be specified as
<literal>pltclu</>.
</para>
<para>
The body of the function is simply a piece of Tcl script.
When the function is called, the argument values are passed as
variables <literal>$1</literal> ... <literal>$n</literal> to the
variables <literal>$1</literal> ... <literal>$<replaceable>n</replaceable></literal> to the
Tcl script. The result is returned
from the Tcl code in the usual way, with a <literal>return</literal>
statement. For example, a function
statement.
</para>
<para>
For example, a function
returning the greater of two integer values could be defined as:
<programlisting>
CREATE FUNCTION tcl_max (integer, integer) RETURNS integer AS '
<programlisting>
CREATE FUNCTION tcl_max(integer, integer) RETURNS integer AS '
if {$1 > $2} {return $1}
return $2
' LANGUAGE 'pltcl' WITH (isStrict);
</programlisting>
' LANGUAGE pltcl STRICT;
</programlisting>
Note the clause <literal>WITH (isStrict)</>, which saves us from
having to think about NULL input values: if a NULL is passed, the
function will not be called at all, but will just return a NULL
Note the clause <literal>STRICT</>, which saves us from
having to think about null input values: if a null value is passed, the
function will not be called at all, but will just return a null
result automatically.
</para>
<para>
In a non-strict function,
if the actual value of an argument is NULL, the corresponding
<literal>$n</literal> variable will be set to an empty string.
To detect whether a particular argument is NULL, use the function
In a nonstrict function,
if the actual value of an argument is null, the corresponding
<literal>$<replaceable>n</replaceable></literal> variable will be set to an empty string.
To detect whether a particular argument is null, use the function
<literal>argisnull</>. For example, suppose that we wanted <function>tcl_max</function>
with one null and one non-null argument to return the non-null
argument, rather than NULL:
with one null and one nonnull argument to return the nonnull
argument, rather than null:
<programlisting>
CREATE FUNCTION tcl_max (integer, integer) RETURNS integer AS '
<programlisting>
CREATE FUNCTION tcl_max(integer, integer) RETURNS integer AS '
if {[argisnull 1]} {
if {[argisnull 2]} { return_null }
return $2
@ -133,8 +130,8 @@ CREATE FUNCTION tcl_max (integer, integer) RETURNS integer AS '
if {[argisnull 2]} { return $1 }
if {$1 > $2} {return $1}
return $2
' LANGUAGE 'pltcl';
</programlisting>
' LANGUAGE pltcl;
</programlisting>
</para>
<para>
@ -145,15 +142,19 @@ CREATE FUNCTION tcl_max (integer, integer) RETURNS integer AS '
</para>
<para>
Composite-type arguments are passed to the procedure as Tcl arrays.
The element names of the array are the attribute names of the composite
type. If an attribute in the passed row
has the NULL value, it will not appear in the array! Here is
an example that defines the overpaid_2 function (as found in the
older <productname>PostgreSQL</productname> documentation) in PL/Tcl:
Composite-type arguments are passed to the function as Tcl
arrays. The element names of the array are the attribute names
of the composite type. If an attribute in the passed row has the
null value, it will not appear in the array. Here is an example:
<programlisting>
CREATE FUNCTION overpaid_2 (EMP) RETURNS bool AS '
<programlisting>
CREATE TABLE employee (
name text,
salary integer,
age integer
);
CREATE FUNCTION overpaid(employee) RETURNS boolean AS '
if {200000.0 < $1(salary)} {
return "t"
}
@ -161,110 +162,109 @@ CREATE FUNCTION overpaid_2 (EMP) RETURNS bool AS '
return "t"
}
return "f"
' LANGUAGE 'pltcl';
</programlisting>
' LANGUAGE pltcl;
</programlisting>
</para>
<para>
There is not currently any support for returning a composite-type
There is currently no support for returning a composite-type
result value.
</para>
</sect2>
</sect1>
<sect2>
<sect1 id="pltcl-data">
<title>Data Values in PL/Tcl</title>
<para>
The argument values supplied to a PL/Tcl function's script are simply
The argument values supplied to a PL/Tcl function's code are simply
the input arguments converted to text form (just as if they had been
displayed by a SELECT statement). Conversely, the <literal>return</>
displayed by a <command>SELECT</> statement). Conversely, the <literal>return</>
command will accept any string that is acceptable input format for
the function's declared return type. So, the PL/Tcl programmer can
manipulate data values as if they were just text.
</para>
</sect2>
</sect1>
<sect2>
<sect1 id="pltcl-global">
<title>Global Data in PL/Tcl</title>
<para>
Sometimes it
is useful to have some global status data that is held between two
calls to a procedure or is shared between different procedures.
is useful to have some global data that is held between two
calls to a function or is shared between different functions.
This is easily done since
all PL/Tcl procedures executed in one backend share the same
all PL/Tcl functions executed in one session share the same
safe Tcl interpreter. So, any global Tcl variable is accessible to
all PL/Tcl procedure calls, and will persist for the duration of the
SQL client connection. (Note that <application>PL/TclU</> functions likewise share
all PL/Tcl function calls and will persist for the duration of the
SQL session. (Note that <application>PL/TclU</> functions likewise share
global data, but they are in a different Tcl interpreter and cannot
communicate with PL/Tcl functions.)
</para>
<para>
To help protect PL/Tcl procedures from unintentionally interfering
To help protect PL/Tcl functions from unintentionally interfering
with each other, a global
array is made available to each procedure via the <function>upvar</>
command. The global name of this variable is the procedure's internal
name and the local name is <literal>GD</>. It is recommended that
array is made available to each function via the <function>upvar</>
command. The global name of this variable is the function's internal
name, and the local name is <literal>GD</>. It is recommended that
<literal>GD</> be used
for private status data of a procedure. Use regular Tcl global variables
for private data of a function. Use regular Tcl global variables
only for values that you specifically intend to be shared among multiple
procedures.
functions.
</para>
<para>
An example of using <literal>GD</> appears in the
<function>spi_execp</function> example below.
</para>
</sect2>
</sect1>
<sect2>
<sect1 id="pltcl-dbaccess">
<title>Database Access from PL/Tcl</title>
<para>
The following commands are available to access the database from
the body of a PL/Tcl procedure:
</para>
the body of a PL/Tcl function:
<variablelist>
<varlistentry>
<term><function>spi_exec</function> <literal>?-count <replaceable>n</replaceable>? ?-array <replaceable>name</replaceable>? <replaceable>query</replaceable> ?<replaceable>loop-body</replaceable>?</literal></term>
<term><function>spi_exec</function> <literal>?-count <replaceable>n</replaceable>? ?-array <replaceable>name</replaceable>? <replaceable>command</replaceable> ?<replaceable>loop-body</replaceable>?</literal></term>
<listitem>
<para>
Execute an SQL query given as a string. An error in the query
causes an error to be raised. Otherwise, the command's return value
Executes an SQL command given as a string. An error in the command
causes an error to be raised. Otherwise, the return value of <function>spi_exec</function>
is the number of rows processed (selected, inserted, updated, or
deleted) by the query, or zero if the query is a utility
statement. In addition, if the query is a SELECT statement, the
deleted) by the command, or zero if the command is a utility
statement. In addition, if the command is a <command>SELECT</> statement, the
values of the selected columns are placed in Tcl variables as
described below.
</para>
<para>
The optional <literal>-count</> value tells
<function>spi_exec</function> the maximum number of rows
to process in the query. The effect of this is comparable to
setting up the query as a cursor and then saying <literal>FETCH n</>.
to process in the command. The effect of this is comparable to
setting up a query as a cursor and then saying <literal>FETCH <replaceable>n</></>.
</para>
<para>
If the query is a <literal>SELECT</> statement, the values of the statement's
If the command is a <command>SELECT</> statement, the values of the
result columns are placed into Tcl variables named after the columns.
If the <literal>-array</> option is given, the column values are
instead stored into the named associative array, with the SELECT
instead stored into the named associative array, with the
column names used as array indexes.
</para>
<para>
If the query is a SELECT statement and no <replaceable>loop-body</>
If the command is a <command>SELECT</> statement and no <replaceable>loop-body</>
script is given, then only the first row of results are stored into
Tcl variables; remaining rows, if any, are ignored. No store occurs
Tcl variables; remaining rows, if any, are ignored. No storing occurs
if the
SELECT returns no rows (this case can be detected by checking the
result of <function>spi_exec</function>). For example,
query returns no rows. (This case can be detected by checking the
result of <function>spi_exec</function>.) For example,
<programlisting>
<programlisting>
spi_exec "SELECT count(*) AS cnt FROM pg_proc"
</programlisting>
</programlisting>
will set the Tcl variable <literal>$cnt</> to the number of rows in
the <structname>pg_proc</> system catalog.
@ -272,23 +272,23 @@ spi_exec "SELECT count(*) AS cnt FROM pg_proc"
<para>
If the optional <replaceable>loop-body</> argument is given, it is
a piece of Tcl script that is executed once for each row in the
SELECT result (note: <replaceable>loop-body</> is ignored if the given
query is not a SELECT). The values of the current row's fields
query result. (<replaceable>loop-body</> is ignored if the given
command is not a <command>SELECT</>.) The values of the current row's columns
are stored into Tcl variables before each iteration. For example,
<programlisting>
<programlisting>
spi_exec -array C "SELECT * FROM pg_class" {
elog DEBUG "have table $C(relname)"
}
</programlisting>
</programlisting>
will print a DEBUG log message for every row of pg_class. This
will print a log message for every row of <literal>pg_class</>. This
feature works similarly to other Tcl looping constructs; in
particular <literal>continue</> and <literal>break</> work in the
usual way inside the loop body.
</para>
<para>
If a field of a SELECT result is NULL, the target
If a column of a query result is null, the target
variable for it is <quote>unset</> rather than being set.
</para>
</listitem>
@ -299,18 +299,18 @@ spi_exec -array C "SELECT * FROM pg_class" {
<listitem>
<para>
Prepares and saves a query plan for later execution. The saved plan
will be retained for the life of the current backend.
will be retained for the life of the current session.
</para>
<para>
The query may use <firstterm>arguments</>, which are placeholders for
The query may use parameters, that is, placeholders for
values to be supplied whenever the plan is actually executed.
In the query string, refer to arguments
by the symbols <literal>$1</literal> ... <literal>$n</literal>.
If the query uses arguments, the names of the argument types
In the query string, refer to parameters
by the symbols <literal>$1</literal> ... <literal>$<replaceable>n</replaceable></literal>.
If the query uses parameters, the names of the parameter types
must be given as a Tcl list. (Write an empty list for
<replaceable>typelist</replaceable> if no arguments are used.)
Presently, the argument types must be identified by the internal
type names shown in pg_type; for example <literal>int4</> not
<replaceable>typelist</replaceable> if no parameters are used.)
Presently, the parameter types must be identified by the internal
type names shown in the system table <literal>pg_type</>; for example <literal>int4</> not
<literal>integer</>.
</para>
<para>
@ -325,24 +325,24 @@ spi_exec -array C "SELECT * FROM pg_class" {
<term><function>spi_execp</> <literal>?-count <replaceable>n</replaceable>? ?-array <replaceable>name</replaceable>? ?-nulls <replaceable>string</replaceable>? <replaceable>queryid</replaceable> ?<replaceable>value-list</replaceable>? ?<replaceable>loop-body</replaceable>?</literal></term>
<listitem>
<para>
Execute a query previously prepared with <function>spi_prepare</>.
Executes a query previously prepared with <function>spi_prepare</>.
<replaceable>queryid</replaceable> is the ID returned by
<function>spi_prepare</>. If the query references arguments,
a <replaceable>value-list</replaceable> must be supplied: this
is a Tcl list of actual values for the arguments. This must be
the same length as the argument type list previously given to
<function>spi_prepare</>. If the query references parameters,
a <replaceable>value-list</replaceable> must be supplied. This
is a Tcl list of actual values for the parameters. The list must be
the same length as the parameter type list previously given to
<function>spi_prepare</>. Omit <replaceable>value-list</replaceable>
if the query has no arguments.
if the query has no parameters.
</para>
<para>
The optional value for <literal>-nulls</> is a string of spaces and
<literal>'n'</> characters telling <function>spi_execp</function>
which of the arguments are null values. If given, it must have exactly the
which of the parameters are null values. If given, it must have exactly the
same length as the <replaceable>value-list</replaceable>. If it
is not given, all the argument values are non-NULL.
is not given, all the parameter values are nonnull.
</para>
<para>
Except for the way in which the query and its arguments are specified,
Except for the way in which the query and its parameters are specified,
<function>spi_execp</> works just like <function>spi_exec</>.
The <literal>-count</>, <literal>-array</>, and
<replaceable>loop-body</replaceable> options are the same,
@ -351,7 +351,7 @@ spi_exec -array C "SELECT * FROM pg_class" {
<para>
Here's an example of a PL/Tcl function using a prepared plan:
<programlisting>
<programlisting>
CREATE FUNCTION t1_count(integer, integer) RETURNS integer AS '
if {![ info exists GD(plan) ]} {
# prepare the saved plan on the first call
@ -361,14 +361,14 @@ CREATE FUNCTION t1_count(integer, integer) RETURNS integer AS '
}
spi_execp -count 1 $GD(plan) [ list $1 $2 ]
return $cnt
' LANGUAGE 'pltcl';
</programlisting>
' LANGUAGE pltcl;
</programlisting>
Note that each backslash that Tcl should see must be doubled when
we type in the function, since the main parser processes
backslashes too in CREATE FUNCTION. We need backslashes inside
backslashes, too, in <command>CREATE FUNCTION</>. We need backslashes inside
the query string given to <function>spi_prepare</> to ensure that
the <literal>$n</> markers will be passed through to
the <literal>$<replaceable>n</replaceable></> markers will be passed through to
<function>spi_prepare</> as-is, and not
replaced by Tcl variable substitution.
</para>
@ -383,8 +383,8 @@ CREATE FUNCTION t1_count(integer, integer) RETURNS integer AS '
<listitem>
<para>
Returns the OID of the row inserted by the last
<function>spi_exec</>'d or <function>spi_execp</>'d query,
if that query was a single-row INSERT. (If not, you get zero.)
<function>spi_exec</> or <function>spi_execp</>,
if the command was a single-row <command>INSERT</>. (If not, you get zero.)
</para>
</listitem>
</varlistentry>
@ -395,18 +395,18 @@ CREATE FUNCTION t1_count(integer, integer) RETURNS integer AS '
<para>
Duplicates all occurrences of single quote and backslash characters
in the given string. This may be used to safely quote strings
that are to be inserted into SQL queries given
that are to be inserted into SQL commands given
to <function>spi_exec</function> or
<function>spi_prepare</function>.
For example, think about a query string like
For example, think about an SQL command string like
<programlisting>
"SELECT '$val' AS ret"
</programlisting>
where the Tcl variable val actually contains
where the Tcl variable <literal>val</> actually contains
<literal>doesn't</literal>. This would result
in the final query string
in the final command string
<programlisting>
SELECT 'doesn't' AS ret
@ -415,21 +415,21 @@ SELECT 'doesn't' AS ret
which would cause a parse error during
<function>spi_exec</function> or
<function>spi_prepare</function>.
The submitted query should contain
The submitted command should contain
<programlisting>
SELECT 'doesn''t' AS ret
</programlisting>
which can be formed in PL/Tcl as
which can be formed in PL/Tcl using
<programlisting>
"SELECT '[ quote $val ]' AS ret"
</programlisting>
One advantage of <function>spi_execp</function> is that you don't
have to quote argument values like this, since the arguments are never
parsed as part of an SQL query string.
have to quote parameter values like this, since the parameters are never
parsed as part of an SQL command string.
</para>
</listitem>
</varlistentry>
@ -441,26 +441,27 @@ SELECT 'doesn''t' AS ret
<term><function>elog</> <replaceable>level</replaceable> <replaceable>msg</replaceable></term>
<listitem>
<para>
Emit a log or error message. Possible levels are
Emits a log or error message. Possible levels are
<literal>DEBUG</>, <literal>LOG</>, <literal>INFO</>,
<literal>NOTICE</>, <literal>WARNING</>, <literal>ERROR</>, and
<literal>FATAL</>. Most simply emit the given message just like
the <literal>elog</> backend C function. <literal>ERROR</>
the <literal>elog</> C function. <literal>ERROR</>
raises an error condition: further execution of the function is
abandoned, and the current transaction is aborted.
<literal>FATAL</> aborts the transaction and causes the current
backend to shut down (there is probably no good reason to use
session to shut down. (There is probably no good reason to use
this error level in PL/Tcl functions, but it's provided for
completeness).
completeness.)
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect2>
</sect1>
<sect2>
<sect1 id="pltcl-trigger">
<title>Trigger Procedures in PL/Tcl</title>
<indexterm>
@ -469,8 +470,8 @@ SELECT 'doesn''t' AS ret
</indexterm>
<para>
Trigger procedures can be written in PL/Tcl. As is customary in
<productname>PostgreSQL</productname>, a procedure that's to be called
Trigger procedures can be written in PL/Tcl.
<productname>PostgreSQL</productname> requires that a procedure that is to be called
as a trigger must be declared as a function with no arguments
and a return type of <literal>trigger</>.
</para>
@ -481,16 +482,16 @@ SELECT 'doesn''t' AS ret
<variablelist>
<varlistentry>
<term><replaceable class="Parameter">$TG_name</replaceable></term>
<term><varname>$TG_name</varname></term>
<listitem>
<para>
The name of the trigger from the CREATE TRIGGER statement.
The name of the trigger from the <command>CREATE TRIGGER</command> statement.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="Parameter">$TG_relid</replaceable></term>
<term><varname>$TG_relid</varname></term>
<listitem>
<para>
The object ID of the table that caused the trigger procedure
@ -500,20 +501,20 @@ SELECT 'doesn''t' AS ret
</varlistentry>
<varlistentry>
<term><replaceable class="Parameter">$TG_relatts</replaceable></term>
<term><varname>$TG_relatts</varname></term>
<listitem>
<para>
A Tcl list of the table field names, prefixed with an empty list
element. So looking up an element name in the list with <application>Tcl</>'s
A Tcl list of the table column names, prefixed with an empty list
element. So looking up a column name in the list with <application>Tcl</>'s
<function>lsearch</> command returns the element's number starting
with 1 for the first column, the same way the fields are customarily
with 1 for the first column, the same way the columns are customarily
numbered in <productname>PostgreSQL</productname>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="Parameter">$TG_when</replaceable></term>
<term><varname>$TG_when</varname></term>
<listitem>
<para>
The string <literal>BEFORE</> or <literal>AFTER</> depending on the
@ -523,7 +524,7 @@ SELECT 'doesn''t' AS ret
</varlistentry>
<varlistentry>
<term><replaceable class="Parameter">$TG_level</replaceable></term>
<term><varname>$TG_level</varname></term>
<listitem>
<para>
The string <literal>ROW</> or <literal>STATEMENT</> depending on the
@ -533,44 +534,46 @@ SELECT 'doesn''t' AS ret
</varlistentry>
<varlistentry>
<term><replaceable class="Parameter">$TG_op</replaceable></term>
<term><varname>$TG_op</varname></term>
<listitem>
<para>
The string <literal>INSERT</>, <literal>UPDATE</> or
The string <literal>INSERT</>, <literal>UPDATE</>, or
<literal>DELETE</> depending on the type of trigger call.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="Parameter">$NEW</replaceable></term>
<term><varname>$NEW</varname></term>
<listitem>
<para>
An associative array containing the values of the new table row for
INSERT/UPDATE actions, or empty for DELETE. The array is indexed
by field name. Fields that are NULL will not appear in the array!
An associative array containing the values of the new table
row for <command>INSERT</> or <command>UPDATE</> actions, or
empty for <command>DELETE</>. The array is indexed by column
name. Columns that are null will not appear in the array.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="Parameter">$OLD</replaceable></term>
<term><varname>$OLD</varname></term>
<listitem>
<para>
An associative array containing the values of the old table row for
UPDATE/DELETE actions, or empty for INSERT. The array is indexed
by field name. Fields that are NULL will not appear in the array!
An associative array containing the values of the old table
row for <command>UPDATE</> or <command>DELETE</> actions, or
empty for <command>INSERT</>. The array is indexed by column
name. Columns that are null will not appear in the array.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="Parameter">$args</replaceable></term>
<term><varname>$args</varname></term>
<listitem>
<para>
A Tcl list of the arguments to the procedure as given in the
CREATE TRIGGER statement. These arguments are also accessible as
<literal>$1</literal> ... <literal>$n</literal> in the procedure body.
<command>CREATE TRIGGER</command> statement. These arguments are also accessible as
<literal>$1</literal> ... <literal>$<replaceable>n</replaceable></literal> in the procedure body.
</para>
</listitem>
</varlistentry>
@ -582,22 +585,22 @@ SELECT 'doesn''t' AS ret
The return value from a trigger procedure can be one of the strings
<literal>OK</> or <literal>SKIP</>, or a list as returned by the
<literal>array get</> Tcl command. If the return value is <literal>OK</>,
the operation (INSERT/UPDATE/DELETE) that fired the trigger will proceed
the operation (<command>INSERT</>/<command>UPDATE</>/<command>DELETE</>) that fired the trigger will proceed
normally. <literal>SKIP</> tells the trigger manager to silently suppress
the operation for this row. If a list is returned, it tells PL/Tcl to
return a modified row to the trigger manager that will be inserted
instead of the one given in $NEW (this works for INSERT/UPDATE
only). Needless to say that all this is only meaningful when the trigger
is BEFORE and FOR EACH ROW; otherwise the return value is ignored.
instead of the one given in <varname>$NEW</>. (This works for <command>INSERT</> and <command>UPDATE</>
only.) Needless to say that all this is only meaningful when the trigger
is <literal>BEFORE</> and <command>FOR EACH ROW</>; otherwise the return value is ignored.
</para>
<para>
Here's a little example trigger procedure that forces an integer value
in a table to keep track of the number of updates that are performed on the
row. For new rows inserted, the value is initialized to 0 and then
incremented on every update operation:
incremented on every update operation.
<programlisting>
CREATE FUNCTION trigfunc_modcount() RETURNS TRIGGER AS '
<programlisting>
CREATE FUNCTION trigfunc_modcount() RETURNS trigger AS '
switch $TG_op {
INSERT {
set NEW($1) 0
@ -611,24 +614,24 @@ CREATE FUNCTION trigfunc_modcount() RETURNS TRIGGER AS '
}
}
return [array get NEW]
' LANGUAGE 'pltcl';
' LANGUAGE pltcl;
CREATE TABLE mytab (num integer, description text, modcnt integer);
CREATE TRIGGER trig_mytab_modcount BEFORE INSERT OR UPDATE ON mytab
FOR EACH ROW EXECUTE PROCEDURE trigfunc_modcount('modcnt');
</programlisting>
</programlisting>
Notice that the trigger procedure itself does not know the column
name; that's supplied from the trigger arguments. This lets the
trigger procedure be re-used with different tables.
trigger procedure be reused with different tables.
</para>
</sect2>
</sect1>
<sect2>
<title> Modules and the <function>unknown</> command</title>
<sect1 id="pltcl-unknown">
<title>Modules and the <function>unknown</> command</title>
<para>
PL/Tcl has support for auto-loading Tcl code when used.
PL/Tcl has support for autoloading Tcl code when used.
It recognizes a special table, <literal>pltcl_modules</>, which
is presumed to contain modules of Tcl code. If this table
exists, the module <literal>unknown</> is fetched from the table
@ -638,7 +641,7 @@ CREATE TRIGGER trig_mytab_modcount BEFORE INSERT OR UPDATE ON mytab
<para>
While the <literal>unknown</> module could actually contain any
initialization script you need, it normally defines a Tcl
<quote>unknown</> procedure that is invoked whenever Tcl does
<function>unknown</> procedure that is invoked whenever Tcl does
not recognize an invoked procedure name. <application>PL/Tcl</>'s standard version
of this procedure tries to find a module in <literal>pltcl_modules</>
that will define the required procedure. If one is found, it is
@ -653,7 +656,7 @@ CREATE TRIGGER trig_mytab_modcount BEFORE INSERT OR UPDATE ON mytab
support scripts to maintain these tables:
<command>pltcl_loadmod</>, <command>pltcl_listmod</>,
<command>pltcl_delmod</>, as well as source for the standard
unknown module <filename>share/unknown.pltcl</>. This module
<literal>unknown</> module in <filename>share/unknown.pltcl</>. This module
must be loaded
into each database initially to support the autoloading mechanism.
</para>
@ -662,9 +665,9 @@ CREATE TRIGGER trig_mytab_modcount BEFORE INSERT OR UPDATE ON mytab
must be readable by all, but it is wise to make them owned and
writable only by the database administrator.
</para>
</sect2>
</sect1>
<sect2>
<sect1 id="pltcl-procnames">
<title>Tcl Procedure Names</title>
<para>
@ -674,15 +677,13 @@ CREATE TRIGGER trig_mytab_modcount BEFORE INSERT OR UPDATE ON mytab
differ. Tcl, however, requires all procedure names to be distinct.
PL/Tcl deals with this by making the internal Tcl procedure names contain
the object
ID of the procedure's <structname>pg_proc</> row as part of their name. Thus,
ID of the function from the system table <structname>pg_proc</> as part of their name. Thus,
<productname>PostgreSQL</productname> functions with the same name
and different argument types will be different Tcl procedures too. This
and different argument types will be different Tcl procedures, too. This
is not normally a concern for a PL/Tcl programmer, but it might be visible
when debugging.
</para>
</sect2>
</sect1>
</chapter>

49
doc/src/sgml/pygresql.sgml
View File

@ -1,4 +1,4 @@
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/Attic/pygresql.sgml,v 1.9 2002/12/12 22:49:27 momjian Exp $ -->
<!-- $Header: /cvsroot/pgsql/doc/src/sgml/Attic/pygresql.sgml,v 1.10 2003/04/07 01:29:25 petere Exp $ -->
<chapter id="pygresql">
<title><application>PyGreSQL</application> - <application>Python</application> Interface</title>
@ -334,13 +334,10 @@ make && make install
<acronym>API</acronym> at <ulink
url="http://www.python.org/topics/database/DatabaseAPI-2.0.html"
>http://www.python.org/topics/database/DatabaseAPI-2.0.html</ulink>.
</para>
<para>
A tutorial-like introduction to the <acronym>DB-API</acronym> can be
found at <ulink
url="http://www2.linuxjournal.com/lj-issues/issue49/2605.html"
>http://www2.linuxjournal.com/lj-issues/issue49/2605.html</ulink>
>http://www2.linuxjournal.com/lj-issues/issue49/2605.html</ulink>.
</para>
<sect1 id="pygresql-pg">
@ -365,16 +362,15 @@ make && make install
<listitem>
<para>
<classname>pgqueryobject</classname> that handles query results.
<classname>pgqueryobject</classname>, which handles query results.
</para>
</listitem>
</itemizedlist>
</para>
<para>
If you want to see a simple example of the use of some of these
functions, see <ulink url="http://www.druid.net/rides"
>http://www.druid.net/rides</ulink> where you can find a link at the
If you want to see a simple example of the use this module,
see <ulink url="http://www.druid.net/rides"></ulink> where you can find a link at the
bottom to the actual <application>Python</application> code for the
page.
</para>
@ -395,9 +391,9 @@ make && make install
<term><varname>INV_WRITE</varname></term>
<listitem>
<para>
large objects access modes, used by
Large objects access modes, used by
<function>(pgobject.)locreate</function> and
<function>(pglarge.)open</function>.
<function>(pglarge.)open</function>
</para>
</listitem>
</varlistentry>
@ -408,7 +404,7 @@ make && make install
<term><varname>SEEK_END</varname></term>
<listitem>
<para>
positional flags, used by <function>(pglarge.)seek</function>.
Positional flags, used by <function>(pglarge.)seek</function>
</para>
</listitem>
</varlistentry>
@ -418,7 +414,7 @@ make && make install
<term><varname>__version__</varname></term>
<listitem>
<para>
constants that give the current version
Constants that give the current version
</para>
</listitem>
</varlistentry>
@ -443,13 +439,13 @@ make && make install
to handle general connection parameters without heavy code in your
programs. You can prompt the user for a value, put it in the
default variable, and forget it, without having to modify your
environment. The support for default variables can be disabled by
environment. The support for default variables can be disabled at build time by
setting the <option>-DNO_DEF_VAR</option> option in the Python
<filename>Setup</> file. Methods relative to this are specified by the tag [DV].
</para>
<para>
All variables are set to <symbol>None</symbol> at module
All default values are set to <symbol>None</symbol> at module
initialization, specifying that standard environment variables
should be used.
</para>
@ -478,7 +474,7 @@ connect(<optional><parameter>dbname</parameter></optional>, <optional><parameter
<term><parameter>dbname</parameter></term>
<listitem>
<para>Name of connected database (string/<symbol>None</>).</para>
<para>Name of connected database (string/<symbol>None</>)</para>
</listitem>
</varlistentry>
@ -486,7 +482,7 @@ connect(<optional><parameter>dbname</parameter></optional>, <optional><parameter
<term><parameter>host</parameter></term>
<listitem>
<para>Name of the server host (string/<symbol>None</>).</para>
<para>Name of the server host (string/<symbol>None</>)</para>
</listitem>
</varlistentry>
@ -494,7 +490,7 @@ connect(<optional><parameter>dbname</parameter></optional>, <optional><parameter
<term><parameter>port</parameter></term>
<listitem>
<para>Port used by the database server (integer/-1).</para>
<para>Port used by the database server (integer/-1)</para>
</listitem>
</varlistentry>
@ -503,7 +499,7 @@ connect(<optional><parameter>dbname</parameter></optional>, <optional><parameter
<listitem>
<para>
Options for the server (string/<symbol>None</>).
Options for the server (string/<symbol>None</>)
</para>
</listitem>
</varlistentry>
@ -513,8 +509,8 @@ connect(<optional><parameter>dbname</parameter></optional>, <optional><parameter
<listitem>
<para>
File or tty for optional debug output from backend
(string/<symbol>None</>).
File or TTY for optional debug output from server
(string/<symbol>None</>)
</para>
</listitem>
</varlistentry>
@ -524,7 +520,7 @@ connect(<optional><parameter>dbname</parameter></optional>, <optional><parameter
<listitem>
<para>
<productname>PostgreSQL</productname> user (string/<symbol>None</>).
<productname>PostgreSQL</productname> user (string/<symbol>None</>)
</para>
</listitem>
</varlistentry>
@ -533,7 +529,7 @@ connect(<optional><parameter>dbname</parameter></optional>, <optional><parameter
<term><parameter>passwd</parameter></term>
<listitem>
<para>Password for user (string/<symbol>None</>).</para>
<para>Password for user (string/<symbol>None</>)</para>
</listitem>
</varlistentry>
</variablelist>
@ -601,12 +597,11 @@ connect(<optional><parameter>dbname</parameter></optional>, <optional><parameter
<para>
This method opens a connection to a specified database on a given
<productname>PostgreSQL</productname> server. You can use
key words here, as described in the
<application>Python</application> tutorial. The names of the
<productname>PostgreSQL</productname> server. The arguments can be
given using key words here. The names of the
key words are the name of the parameters given in the syntax
line. For a precise description of the parameters, please refer
to the <productname>PostgreSQL</productname> user manual.
to <xref linkend="libpq">.
</para>
</refsect1>

71
doc/src/sgml/xplang.sgml
View File

@ -1,13 +1,10 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.20 2003/01/31 00:10:51 tgl Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.21 2003/04/07 01:29:26 petere Exp $
-->
<chapter id="xplang">
<title id="xplang-title">Procedural Languages</title>
<sect1 id="xplang-intro">
<title>Introduction</title>
<para>
<productname>PostgreSQL</productname> allows users to add new
programming languages to be available for writing functions and
@ -21,7 +18,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.20 2003/01/31 00:10:51 tgl
could serve as <quote>glue</quote> between
<productname>PostgreSQL</productname> and an existing implementation
of a programming language. The handler itself is a special
programming language function compiled into a shared object and
C language function compiled into a shared object and
loaded on demand.
</para>
@ -31,7 +28,6 @@ $Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.20 2003/01/31 00:10:51 tgl
available in the standard <productname>PostgreSQL</productname>
distribution, which can serve as examples.
</para>
</sect1>
<sect1 id="xplang-install">
<title>Installing Procedural Languages</title>
@ -39,22 +35,24 @@ $Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.20 2003/01/31 00:10:51 tgl
<para>
A procedural language must be <quote>installed</quote> into each
database where it is to be used. But procedural languages installed in
the template1 database are automatically available in all
the database <literal>template1</> are automatically available in all
subsequently created databases. So the database administrator can
decide which languages are available in which databases, and can make
decide which languages are available in which databases and can make
some languages available by default if he chooses.
</para>
<para>
For the languages supplied with the standard distribution, the
shell script <filename>createlang</filename> may be used instead
of carrying out the details by hand. For example, to install <application>PL/pgSQL</application>
into the template1 database, use
program <command>createlang</command> may be used to install the
language instead of carrying out the details by hand. For
example, to install the language
<application>PL/pgSQL</application> into the database
<literal>template1</>, use
<programlisting>
createlang plpgsql template1
</programlisting>
The manual procedure described below is only recommended for
installing custom languages that <filename>createlang</filename>
installing custom languages that <command>createlang</command>
does not know about.
</para>
@ -64,8 +62,11 @@ createlang plpgsql template1
</title>
<para>
A procedural language is installed in the database in three
steps, which must be carried out by a database superuser.
A procedural language is installed in a database in three steps,
which must be carried out by a database superuser. The
<command>createlang</command> programm automates <xref
linkend="xplang-install-cr1"> and <xref
linkend="xplang-install-cr2">.
</para>
<step performance="required">
@ -81,12 +82,13 @@ createlang plpgsql template1
<para>
The handler must be declared with the command
<synopsis>
CREATE FUNCTION <replaceable>handler_function_name</replaceable> ()
RETURNS LANGUAGE_HANDLER AS
'<replaceable>path-to-shared-object</replaceable>' LANGUAGE C;
CREATE FUNCTION <replaceable>handler_function_name</replaceable>()
RETURNS language_handler
AS '<replaceable>path-to-shared-object</replaceable>'
LANGUAGE C;
</synopsis>
The special return type of <type>LANGUAGE_HANDLER</type> tells
the database that this function does not return one of
The special return type of <type>language_handler</type> tells
the database system that this function does not return one of
the defined <acronym>SQL</acronym> data types and is not directly usable
in <acronym>SQL</acronym> statements.
</para>
@ -99,7 +101,7 @@ CREATE FUNCTION <replaceable>handler_function_name</replaceable> ()
CREATE <optional>TRUSTED</optional> <optional>PROCEDURAL</optional> LANGUAGE <replaceable>language-name</replaceable>
HANDLER <replaceable>handler_function_name</replaceable>;
</synopsis>
The optional key word <literal>TRUSTED</literal> tells whether
The optional key word <literal>TRUSTED</literal> specifies that
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
@ -119,20 +121,12 @@ CREATE <optional>TRUSTED</optional> <optional>PROCEDURAL</optional> LANGUAGE <re
</procedure>
<para>
In a default <productname>PostgreSQL</productname> installation,
the handler for the <application>PL/pgSQL</application> language
is built and installed into the <quote>library</quote>
directory. If <application>Tcl/Tk</> support is configured in, the handlers for
<application>PL/Tcl</> and <application>PL/TclU</> are also built and installed in the same
location. Likewise, the <application>PL/Perl</> and <application>PL/PerlU</> handlers are built
and installed if Perl support is configured, and <application>PL/Python</> is
installed if Python support is configured. The
<filename>createlang</filename> script automates <xref
linkend="xplang-install-cr1"> and <xref
linkend="xplang-install-cr2"> described above.
<xref linkend="xplang-install-example"> shows how the manual
installation procedure would work with the language
<application>PL/pgSQL</application>.
</para>
<example>
<example id="xplang-install-example">
<title>Manual Installation of <application>PL/pgSQL</application></title>
<para>
@ -140,7 +134,7 @@ CREATE <optional>TRUSTED</optional> <optional>PROCEDURAL</optional> LANGUAGE <re
shared object for the <application>PL/pgSQL</application> language's call handler function.
<programlisting>
CREATE FUNCTION plpgsql_call_handler () RETURNS LANGUAGE_HANDLER AS
CREATE FUNCTION plpgsql_call_handler() RETURNS language_handler AS
'$libdir/plpgsql' LANGUAGE C;
</programlisting>
</para>
@ -157,6 +151,17 @@ CREATE TRUSTED PROCEDURAL LANGUAGE plpgsql
</para>
</example>
<para>
In a default <productname>PostgreSQL</productname> installation,
the handler for the <application>PL/pgSQL</application> language
is built and installed into the <quote>library</quote>
directory. If <application>Tcl/Tk</> support is configured in, the handlers for
<application>PL/Tcl</> and <application>PL/TclU</> are also built and installed in the same
location. Likewise, the <application>PL/Perl</> and <application>PL/PerlU</> handlers are built
and installed if Perl support is configured, and <application>PL/Python</> is
installed if Python support is configured.
</para>
</sect1>
</chapter>