postgresql/doc/src/sgml/xplang.sgml

<!--
$Header: /cvsroot/pgsql/doc/src/sgml/xplang.sgml,v 1.10 2000/11/04 21:06:37 momjian 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
   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.
  </para>

  <para>
   Writing a handler for a new procedural language (PL)
   is outside the scope of this manual. 
  </para>

  <sect1 id="xplang-install">
   <title>Installing Procedural Languages</title>

   <procedure>
    <title>
     Procedural Language Installation
    </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.)
    </para>

    <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
      the database that this function does not return one of
      the defined <acronym>SQL</acronym> datatypes and is not directly usable
      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
      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
      internals or the filesystem. The languages PL/pgSQL and
      PL/Tcl are known to be trusted.
     </para>
    </step>
   </procedure>

   <procedure>
    <title>Example</title>
    <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>
CREATE FUNCTION plpgsql_call_handler () RETURNS OPAQUE AS
    '/usr/local/pgsql/lib/plpgsql.so' LANGUAGE 'C';
      </programlisting>
     </para>
    </step>

    <step performance="Required">
    <para>
      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>.
      Due to this, PL functions
      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>
    </step>
   </procedure>
  </sect1>

 <!-- **** End of PL installation **** -->
</chapter>

<!-- Keep this comment at the end of the file
Local variables:
mode:sgml
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
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
-->