2000-03-31 05:27:42 +02:00
|
|
|
<!--
|
2000-04-03 00:59:40 +02:00
|
|
|
$Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.8 2000/04/02 22:59:40 tgl Exp $
|
2000-03-31 05:27:42 +02:00
|
|
|
-->
|
|
|
|
|
1999-07-22 17:11:05 +02:00
|
|
|
<chapter id="xplang">
|
|
|
|
<title id="xplang-title">Procedural Languages</title>
|
1998-10-21 07:30:16 +02:00
|
|
|
|
2000-03-31 00:13:30 +02:00
|
|
|
<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
|
2000-04-03 00:59:40 +02:00
|
|
|
no built-in knowledge about how to interpret the function's source
|
|
|
|
text. Instead, the task is passed to
|
2000-03-31 00:13:30 +02:00
|
|
|
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.
|
|
|
|
</para>
|
|
|
|
|
2000-04-03 00:59:40 +02:00
|
|
|
<para>
|
|
|
|
Writing a handler for a new procedural language (PL)
|
|
|
|
is outside the scope of this manual.
|
|
|
|
</para>
|
|
|
|
|
2000-03-31 00:13:30 +02:00
|
|
|
<sect1>
|
|
|
|
<title>Installing Procedural Languages</title>
|
|
|
|
|
|
|
|
<procedure>
|
1999-07-22 17:11:05 +02:00
|
|
|
<title>
|
2000-03-31 00:13:30 +02:00
|
|
|
Procedural Language Installation
|
1999-07-22 17:11:05 +02:00
|
|
|
</title>
|
1998-10-25 02:29:01 +02:00
|
|
|
|
|
|
|
<para>
|
2000-03-31 00:13:30 +02:00
|
|
|
A procedural language is installed in the database in three steps.
|
2000-04-03 00:59:40 +02:00
|
|
|
(For the languages supplied with the standard distribution, the
|
|
|
|
shell script <filename>createlang</filename> can be used instead
|
|
|
|
of carrying out the details manually.)
|
1998-12-29 03:24:47 +01:00
|
|
|
</para>
|
1999-07-22 17:11:05 +02:00
|
|
|
|
2000-03-31 00:13:30 +02:00
|
|
|
<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.
|
|
|
|
</para>
|
|
|
|
</step>
|
|
|
|
<step performance="Required">
|
|
|
|
<para>
|
|
|
|
The handler must be declared with the command
|
|
|
|
<programlisting>
|
|
|
|
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
|
2000-04-03 00:59:40 +02:00
|
|
|
the database that this function does not return one of
|
|
|
|
the defined <acronym>SQL</acronym> datatypes and is not directly usable
|
2000-03-31 00:13:30 +02:00
|
|
|
in <acronym>SQL</acronym> statements.
|
|
|
|
</para>
|
|
|
|
</step>
|
|
|
|
<step performance="Required">
|
|
|
|
<para>
|
|
|
|
The PL must be declared with the command
|
|
|
|
<programlisting>
|
|
|
|
CREATE [ TRUSTED ] PROCEDURAL LANGUAGE '<replaceable>language-name</replaceable>'
|
|
|
|
HANDLER <replaceable>handler_function_name</replaceable>
|
|
|
|
LANCOMPILER '<replaceable>description</replaceable>';
|
|
|
|
</programlisting>
|
|
|
|
The optional keyword <acronym>TRUSTED</acronym> tells
|
2000-04-03 00:59:40 +02:00
|
|
|
whether ordinary database users that have no superuser
|
|
|
|
privileges should be allowed to use this language to create functions
|
2000-03-31 00:13:30 +02:00
|
|
|
and trigger procedures. Since PL functions are
|
2000-04-03 00:59:40 +02:00
|
|
|
executed inside the database backend, the <acronym>TRUSTED</acronym>
|
|
|
|
flag should only be given for
|
|
|
|
languages that don't allow access to database backends
|
2000-03-31 00:13:30 +02:00
|
|
|
internals or the filesystem. The languages PL/pgSQL and
|
|
|
|
PL/Tcl are known to be trusted.
|
|
|
|
</para>
|
|
|
|
</step>
|
|
|
|
</procedure>
|
|
|
|
|
|
|
|
<procedure>
|
1999-07-22 17:11:05 +02:00
|
|
|
<title>Example</title>
|
|
|
|
<step performance="Required">
|
2000-03-31 00:13:30 +02:00
|
|
|
<para>
|
|
|
|
The following command tells the database where to find the
|
2000-04-03 00:59:40 +02:00
|
|
|
shared object for the PL/pgSQL language's call handler function.
|
2000-03-31 00:13:30 +02:00
|
|
|
|
|
|
|
<programlisting>
|
|
|
|
CREATE FUNCTION plpgsql_call_handler () RETURNS OPAQUE AS
|
|
|
|
'/usr/local/pgsql/lib/plpgsql.so' LANGUAGE 'C';
|
|
|
|
</programlisting>
|
|
|
|
</para>
|
1999-07-22 17:11:05 +02:00
|
|
|
</step>
|
1998-10-21 07:30:16 +02:00
|
|
|
|
1999-07-22 17:11:05 +02:00
|
|
|
<step performance="Required">
|
|
|
|
<para>
|
2000-03-31 00:13:30 +02:00
|
|
|
The command
|
|
|
|
<programlisting>
|
|
|
|
CREATE TRUSTED PROCEDURAL LANGUAGE 'plpgsql'
|
|
|
|
HANDLER plpgsql_call_handler
|
|
|
|
LANCOMPILER 'PL/pgSQL';
|
|
|
|
</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
|
|
|
|
given to the handler is the object ID in the <filename>pg_proc</filename>
|
|
|
|
tables entry for the function that should be executed.
|
|
|
|
The handler examines various system catalogs to analyze the
|
|
|
|
functions call arguments and it's return data type. The source
|
|
|
|
text of the functions body is found in the prosrc attribute of
|
|
|
|
<literal>pg_proc</literal>.
|
2000-04-03 00:59:40 +02:00
|
|
|
Due to this, PL functions
|
2000-03-31 00:13:30 +02:00
|
|
|
can be overloaded like SQL language functions. There can be
|
|
|
|
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>
|
1999-07-22 17:11:05 +02:00
|
|
|
</step>
|
2000-03-31 00:13:30 +02:00
|
|
|
</procedure>
|
|
|
|
</sect1>
|
1999-07-22 17:11:05 +02:00
|
|
|
|
2000-03-31 00:13:30 +02:00
|
|
|
<!-- **** End of PL installation **** -->
|
1999-07-22 17:11:05 +02:00
|
|
|
</chapter>
|
|
|
|
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
|
|
Local variables:
|
2000-03-31 00:13:30 +02:00
|
|
|
mode:sgml
|
1999-07-22 17:11:05 +02:00
|
|
|
sgml-omittag:nil
|
|
|
|
sgml-shorttag:t
|
|
|
|
sgml-minimize-attributes:nil
|
|
|
|
sgml-always-quote-attributes:t
|
|
|
|
sgml-indent-step:1
|
|
|
|
sgml-indent-data:t
|
|
|
|
sgml-parent-document:nil
|
|
|
|
sgml-default-dtd-file:"./reference.ced"
|
|
|
|
sgml-exposed-tags:nil
|
2000-03-31 05:27:42 +02:00
|
|
|
sgml-local-catalogs:("/usr/lib/sgml/catalog")
|
1999-07-22 17:11:05 +02:00
|
|
|
sgml-local-ecat-files:nil
|
|
|
|
End:
|
|
|
|
-->
|