From 7402eda97c4d1903f4c63b3a05af749b740d5e91 Mon Sep 17 00:00:00 2001 From: "Thomas G. Lockhart" Date: Wed, 13 May 1998 05:34:00 +0000 Subject: First files for reference pages. --- doc/src/sgml/ref/create_language.sgml | 400 ++++++++++++++++++++++++++++++++++ 1 file changed, 400 insertions(+) create mode 100644 doc/src/sgml/ref/create_language.sgml (limited to 'doc/src/sgml/ref/create_language.sgml') diff --git a/doc/src/sgml/ref/create_language.sgml b/doc/src/sgml/ref/create_language.sgml new file mode 100644 index 0000000000..57b41f7793 --- /dev/null +++ b/doc/src/sgml/ref/create_language.sgml @@ -0,0 +1,400 @@ + + + + CREATE LANGUAGE + + SQL - Language Statements + + + + CREATE LANGUAGE + + + Defines a new language for functions + + + + + 1998-04-15 + + + CREATE [TRUSTED] PROCEDURAL LANGUAGE 'langname' + HANDLER call_handler + LANCOMPILER 'comment' + + + + + 1998-04-15 + + + Inputs + + + + + + + + + + + + + TRUSTED + + + + TRUSTED specifies that the call handler for + the language is safe; that is, it offers an unprivileged user + no functionality to get around access restrictions. If + this keyword is omitted when registering the language, + only users with the PostgreSQL superuser privilege can use + this language to create new functions + (like the 'C' language). + + + + + + + langname + + + + 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 + PostgreSQL. + + + + + + call_handler + + + + The argument for HANDLER is the name + of a previously + registered function that will be called to execute the PL + procedures. + + + + + + comment + + + + The LANCOMPILER argument is the + string that will be + inserted in the LANCOMPILER attribute + of the new + pg_language entry. At present, + PostgreSQL doesn't use + this attribute in any way. + + + + + + + + + + + + 1998-04-15 + + + Outputs + + + + + + + + + + + + + CREATE + + + + This message is returned if the language is successfully + created. + + + + + + ERROR: PL handler function funcname() doesn't exist + + + + This error is returned if the function + funcname() + is not found. + + + + + + + + + + + + + 1998-04-15 + + + Description + + + Using CREATE LANGUAGE, a PostgreSQL user can register + a new language with PostgreSQL. Subsequently, functions and + trigger procedures can be defined in this new language. + The user must have the PostgreSQL superuser privilege to + register a new language. + + + + + 1998-04-15 + + + Writing PL handlers + + + The call handler for a procedural language must be written + in a compiler language such as 'C' and registered with + PostgreSQL as a function taking no arguments and returning + opaque type. + What does `opaque type' mean? + This prevents the call handler from being + called directly as a function from queries. + + + 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. + + + + When called from the trigger manager, the only argument is + the object ID from the procedure's pg_proc + entry. All other + information from the trigger manager is found in the + global CurrentTriggerData pointer. + + + + + When called from the function manager, the arguments are + the object ID of the procedure's pg_proc + entry, the number + of arguments given to the PL function, the arguments in a + FmgrValues structure and a pointer + to a boolean where the + function tells the caller if the return value is the SQL + NULL value. + + + + + + It's up to the call handler to fetch the + pg_proc entry and + to analyze the argument and return types of the called + procedure. The AS clause from the + CREATE FUNCTION of + the procedure will be found in the prosrc + attribute of the + pg_proc 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. + + + + + 1998-04-15 + + + Notes + + + Use + CREATE FUNCTION + + to create a function. + + + Use + DROP LANGUAGE + to drop procedural languages. + + + Refer to the table pg_language + for further information: + + + 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 + + + + + + + + + Restrictions + + + Since the call handler for a procedural language must be + registered with PostgreSQL in the 'C' language, it inherits + all the restrictions of 'C' functions. + + What are these restrictions? + + + + + + Bugs + + + At present, the definitions for a procedural language cannot be + changed once they have been created. + + + + + + Usage + + + This is a template for a PL handler written in 'C': + + + #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; + } + + + Only a few thousand lines of code have to be added instead + of the dots to complete the PL call handler. See + CREATE FUNCTION + for information on how to compile + it into a loadable module +. + + The following commands then register the sample procedural + language. + + 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'; + + + + + + Compatibility + + + CREATE LANGUAGE is a PostgreSQL extension. + + + + + 1998-04-15 + + + SQL92 + + + There is no CREATE LANGUAGE statement in SQL92. + + + + + + + -- cgit v1.2.1