File: sql-createlanguage.html

package info (click to toggle)
mpsql 2.1-2
links: PTS
area: non-free
in suites: potato
size: 3,528 kB
ctags: 4,886
sloc: ansic: 35,184; makefile: 3,761; sh: 44
file content (605 lines) | stat: -rw-r--r-- 10,075 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML
><HEAD
><TITLE
>   CREATE LANGUAGE
  </TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet version 1.19"><LINK
REL="HOME"
TITLE="PostgreSQL User's Guide"
HREF="user.html"><LINK
REL="UP"
TITLE="SQL Commands"
HREF="sql-commands.html"><LINK
REL="PREVIOUS"
TITLE="   CREATE INDEX
  "
HREF="sql-createindex.html"><LINK
REL="NEXT"
TITLE="   CREATE OPERATOR
  "
HREF="sql-createoperator.html"></HEAD
><BODY
BGCOLOR="#FFFFFF"
TEXT="#000000"
><DIV
CLASS="NAVHEADER"
><TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>PostgreSQL User's Guide</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="sql-createindex.html"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="sql-createoperator.html"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
>CREATE LANGUAGE</H1
><DIV
CLASS="REFNAMEDIV"
><H2
>Name</H2
>   CREATE LANGUAGE
   &#8212;    Defines a new language for functions
  </DIV
><DIV
CLASS="REFSYNOPSISDIV"
><PRE
CLASS="SYNOPSIS"
>CREATE [ TRUSTED ] PROCEDURAL LANGUAGE '<TT
CLASS="REPLACEABLE"
><I
>langname</I
></TT
>'
    HANDLER <TT
CLASS="REPLACEABLE"
><I
>call_handler</I
></TT
>
    LANCOMPILER '<TT
CLASS="REPLACEABLE"
><I
>comment</I
></TT
>'
  </PRE
><DIV
CLASS="REFSECT2"
><H3
>    Inputs
   </H3
><P
>       <P
></P
></P><DL
><DT
><TT
CLASS="FUNCTION"
>TRUSTED</TT
></DT
><DD
><P
>	   <TT
CLASS="FUNCTION"
> TRUSTED</TT
> specifies that the call handler for
	   the language is safe; that is, it offers an unprivileged user
	   no functionality to bypass access restrictions. If
	   this keyword is omitted when registering the language,
	   only users with the <SPAN
CLASS="PRODUCTNAME"
>Postgres</SPAN
>
superuser privilege can use
	   this language to create new functions
	   (like the 'C' language).  
	  </P
></DD
><DT
><TT
CLASS="REPLACEABLE"
><I
>langname</I
></TT
></DT
><DD
><P
>   
	   The name of the new procedural language.
	   The language name is case insensitive. A procedural 
	   language cannot override one of the built-in languages of
	   <SPAN
CLASS="PRODUCTNAME"
>Postgres</SPAN
>.
	  </P
></DD
><DT
>HANDLER <TT
CLASS="REPLACEABLE"
><I
>call_handler</I
></TT
></DT
><DD
><P
>	   <TT
CLASS="REPLACEABLE"
><I
>call_handler</I
></TT
> is the name
	   of a previously
	   registered function that will be called to execute the PL
	   procedures.
	  </P
></DD
><DT
><TT
CLASS="REPLACEABLE"
><I
>comment</I
></TT
></DT
><DD
><P
>	   The <TT
CLASS="FUNCTION"
>LANCOMPILER</TT
> argument is the
	   string that will be
	   inserted in the <TT
CLASS="LITERAL"
>LANCOMPILER</TT
> attribute
	   of the new
	   <TT
CLASS="FILENAME"
>pg_language</TT
> entry. At present,
	   <SPAN
CLASS="PRODUCTNAME"
>Postgres</SPAN
> does not use
	   this attribute in any way.
	  </P
></DD
></DL
><P>

  </P
></DIV
><DIV
CLASS="REFSECT2"
><H3
>    Outputs
   </H3
><P
>       <P
></P
></P><DL
><DT
><SPAN
CLASS="RETURNVALUE"
>CREATE</SPAN
></DT
><DD
><P
>	   This message is returned if the language is successfully
	   created.
	  </P
></DD
><DT
><SPAN
CLASS="RETURNVALUE"
>ERROR:  PL handler function <TT
CLASS="REPLACEABLE"
><I
>funcname</I
></TT
>() doesn't exist</SPAN
></DT
><DD
><P
>           This error is returned if the function
	   <TT
CLASS="REPLACEABLE"
><I
>funcname</I
></TT
>()
	   is not found.
   </P
></DD
></DL
><P>
  </P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><H2
>   Description
  </H2
><P
>   Using <B
CLASS="COMMAND"
>CREATE LANGUAGE</B
>, a 
<SPAN
CLASS="PRODUCTNAME"
>Postgres</SPAN
> user can register
   a new language with <SPAN
CLASS="PRODUCTNAME"
>Postgres</SPAN
>. 
Subsequently, functions and
   trigger procedures can be defined in this new language.
   The user must have the <SPAN
CLASS="PRODUCTNAME"
>Postgres</SPAN
>
 superuser privilege to
   register a new language.
  </P
><DIV
CLASS="REFSECT2"
><H3
>    Writing PL handlers
   </H3
><P
>    The call handler for a procedural language must be written
    in a compiler language such as 'C' and registered with
    <SPAN
CLASS="PRODUCTNAME"
>Postgres</SPAN
> as a function taking
 no arguments and returning the
    <SPAN
CLASS="TYPE"
>opaque</SPAN
> type, a placeholder for unspecified or undefined types..
    This prevents the call handler from being
    called directly as a function from queries.
   </P
><P
>    However, arguments must be supplied on the actual call when a
    PL function or trigger
    procedure in the language offered by the handler is to be
    executed.
    <P
></P
></P><UL
><LI
><P
>       When called from the trigger manager, the only argument is
       the object ID from the procedure's <TT
CLASS="FILENAME"
>pg_proc</TT
>
       entry. All other
       information from the trigger manager is found in the
       global <SPAN
CLASS="STRUCTNAME"
>CurrentTriggerData</SPAN
> pointer.
      </P
></LI
><LI
><P
>       When called from the function manager, the arguments are
       the object ID of the procedure's <TT
CLASS="FILENAME"
>pg_proc</TT
>
       entry, the number
       of arguments given to the PL function, the arguments in a
       <SPAN
CLASS="STRUCTNAME"
>FmgrValues</SPAN
> structure and a pointer
       to a boolean where the
       function tells the caller if the return value is the SQL
       NULL value.
      </P
></LI
></UL
><P>
   </P
><P
>    It's up to the call handler to fetch the
    <TT
CLASS="FILENAME"
>pg_proc</TT
> entry and
    to analyze the argument and return types of the called
    procedure. The AS clause from the
    <B
CLASS="COMMAND"
>CREATE FUNCTION</B
> of
    the procedure will be found in the <TT
CLASS="LITERAL"
>prosrc</TT
>
    attribute of the
    <TT
CLASS="FILENAME"
>pg_proc</TT
> table entry. This may be the
    source text in the procedural
    language itself (like for PL/Tcl), a pathname to a
    file or anything else that tells the call handler what to
    do in detail.
   </P
></DIV
><DIV
CLASS="REFSECT2"
><H3
>    Notes
   </H3
><P
>    Use <B
CLASS="COMMAND"
>CREATE FUNCTION</B
>
    to create a function.
   </P
><P
>    Use <B
CLASS="COMMAND"
>DROP LANGUAGE</B
>  to drop procedural languages.
   </P
><P
>    Refer to the table <TT
CLASS="FILENAME"
>pg_language</TT
>
    for further information:
<PRE
CLASS="PROGRAMLISTING"
><TT
CLASS="COMPUTEROUTPUT"
>Table    = pg_language
+--------------------------+--------------------------+-------+
|          Field           |          Type            | Length|
+--------------------------+--------------------------+-------+
| lanname                  | name                     |    32 |
| lancompiler              | text                     |   var |
+--------------------------+--------------------------+-------+

lanname |lancompiler   
--------+--------------
internal|n/a           
lisp    |/usr/ucb/liszt
C       |/bin/cc       
sql     |postgres</TT
></PRE
>

   </P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><H2
>   Restrictions
  </H2
><P
>   Since the call handler for a procedural language must be
   registered with <SPAN
CLASS="PRODUCTNAME"
>Postgres</SPAN
> in the 'C' language,
 it inherits
   all the capabilities and restrictions of 'C' functions.
  </P
></DIV
><DIV
CLASS="REFSECT1"
><H2
>   Bugs
  </H2
><P
> 
   At present, the definitions for a procedural language cannot be
   changed once they have been created.
  </P
></DIV
><DIV
CLASS="REFSECT1"
><H2
>   Usage
  </H2
><P
>   This is a template for a PL handler written in 'C':
  </P
><PRE
CLASS="PROGRAMLISTING"
>   #include "executor/spi.h"
   #include "commands/trigger.h"
   #include "utils/elog.h"
   #include "fmgr.h"        /* for FmgrValues struct */
   #include "access/heapam.h"
   #include "utils/syscache.h"
   #include "catalog/pg_proc.h"
   #include "catalog/pg_type.h"
        
   Datum
   plsample_call_handler(
        Oid       prooid,
        int       pronargs,
        FmgrValues     *proargs,
        bool      *isNull)
   {
        Datum          retval;
        TriggerData    *trigdata;

        if (CurrentTriggerData == NULL) {
             /*
              * Called as a function
              */

             retval = ...
        } else {
             /*
              * Called as a trigger procedure
              */
             trigdata = CurrentTriggerData;
             CurrentTriggerData = NULL;

             retval = ...
        }

        *isNull = false;
        return retval;
   }
  </PRE
><P
>   Only a few thousand lines of code have to be added instead
   of the dots to complete the PL call handler. 
See <B
CLASS="COMMAND"
>CREATE FUNCTION</B
> for information on how to compile
   it into a loadable module
.</P
><P
>   The following commands then register the sample procedural
   language:
  <PRE
CLASS="PROGRAMLISTING"
>CREATE FUNCTION plsample_call_handler () RETURNS opaque
    AS '/usr/local/pgsql/lib/plsample.so'
    LANGUAGE 'C';
        
CREATE PROCEDURAL LANGUAGE 'plsample'
    HANDLER plsample_call_handler
    LANCOMPILER 'PL/Sample';
  </PRE
>
 </P
></DIV
><DIV
CLASS="REFSECT1"
><H2
>   Compatibility
  </H2
><P
>   CREATE LANGUAGE is a <SPAN
CLASS="PRODUCTNAME"
>Postgres</SPAN
> extension.
  </P
><DIV
CLASS="REFSECT2"
><H3
>    SQL92
   </H3
><P
>    There is no <B
CLASS="COMMAND"
>CREATE LANGUAGE</B
> statement in
 <SPAN
CLASS="ACRONYM"
>SQL92</SPAN
>.
   </P
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="sql-createindex.html"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="user.html"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="sql-createoperator.html"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>CREATE INDEX</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="sql-commands.html"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>CREATE OPERATOR</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>