.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
-.\" $Header: /cvsroot/pgsql/src/man/Attic/create_function.l,v 1.3 1997/09/10 20:19:23 momjian Exp $
+.\" $Header: /cvsroot/pgsql/src/man/Attic/create_function.l,v 1.4 1997/10/30 05:38:17 vadim Exp $
.TH "CREATE FUNCTION" SQL 11/05/95 PostgreSQL PostgreSQL
.SH "NAME"
create function \(em define a new function
\fB(\fP[type1 {, type-n}]\fB)\fP
\fBreturns\fP type-r
\fBas\fP {'/full/path/to/objectfile' | 'sql-queries'}
- \fBlanguage\fP {'c' \ 'sql' \ 'internal'}
+ \fBlanguage\fP {'c' \ 'sql' \ 'internal' \ 'plname'}
.fi
.SH "DESCRIPTION"
With this command, a Postgres user can register a function with Postgres.
.IR "\*(lqsql\*(rq" .
or
.IR "\*(lqinternal\*(rq" .
+or
+.IR "\*(lqplname\*(rq" .
+(The
+.IR "plname"
+is the language name of a created procedural language. See
+create language(l) for details.)
(The
.IR "arg is"
clause may be left out if the function has no arguments, or
on. If an argument is complex, then a \*(lqdot\*(rq notation may be
used to access attributes of the argument (e.g. \*(lq$1.emp\*(rq), or
to invoke functions via a nested-dot syntax.
+.SH "PL FUNCTIONS"
+Procedural languages aren't builtin to Postgres. They are offered
+by loadable modules. Please refer to the documentation for the
+PL in question for details about the syntax and how the
+.IR "as"
+clause is interpreted by the PL handler.
.SH "EXAMPLES: C Functions"
The following command defines a C function, overpaid, of two basetype
arguments.
language 'sql'
.SH "SEE ALSO"
.PP
-information(1), load(l), drop function(l).
+information(1), load(l), drop function(l), create language(l).
.SH "NOTES"
.SH "Name Space Conflicts"
More than one function may be defined with the same name, as long as
--- /dev/null
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/create_language.l,v 1.1 1997/10/30 05:38:19 vadim Exp $
+.TH "CREATE LANGUAGE" SQL 11/05/95 PostgreSQL PostgreSQL
+.SH "NAME"
+create language \(em define a new language for functions
+.SH "SYNOPSIS"
+.nf
+\fBcreate\fP [\fBtrusted\fP] \fBprocedural language\fP 'lanname'
+ \fBhandler\fP call_handler
+ \fBlancompiler\fP 'comment'
+.fi
+.SH "DESCRIPTION"
+With this command, a Postgres user can register a new language with
+Postgres. Subsequently, functions and trigger procedures can be
+defined in this new language. The user must have the Postgres superuser
+privilege to register a new language.
+.PP
+The lanname is the name of the new procedural language. It is converted
+to lower case before the new entry in the pg_language system catalog
+is inserted. Note that this case translation is also done on
+create function(l) and drop language(l). Thus, the language name
+is case insensitive. A procedural language cannot override one of the
+builtin languages of Postgres.
+.PP
+The argument for \fBhandler\fP
+is the name of a previously registered function that
+will be called to execute the PL procedures.
+.PP
+The \fBlancompiler\fP argument is the string that will be inserted
+in the lancompiler attribute of the new pg_language entry. Up to now,
+Postgres doesn't use this attribute in any way.
+.PP
+The \fBtrusted\fP keyword specifies, that the call handler for the
+language is safe - i.e. 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 Postgres superuser privilege
+can use this language to create new functions (like the 'C' language).
+.SH "WRITING PL HANDLERS"
+The call handler for a procedural language must be written in a compiler
+language such as 'C' and registered with Postgres as a function taking
+no arguments and returning
+.IR "opaque"
+type. This prevents the call handler from beeing called directly as a function
+from queries.
+But there are arguments
+on the actual call when a PL function or trigger procedure in the
+language offered by the handler is to be executed.
+.PP
+When called from the trigger manager, the only argument is the object ID from
+the procedures pg_proc entry. All other information from the trigger manager
+is found in the global CurrentTriggerData pointer.
+.PP
+When called from the function manager, the arguments are the object ID of the
+procedures 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.
+.PP
+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
+.IR "as"
+clause from the create function(l) 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.
+.SH "EXAMPLE"
+Following is a template for a PL handler written in 'C':
+.nf
+
+#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;
+}
+
+.fi
+Only a few thousand lines of code have to be added instead of the dots
+to complete the PL call handler. See create function(l) how to compile
+it into a loadable module. The following commands then register the
+sample procedural language.
+.nf
+
+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';
+
+.fi
+.SH "SEE ALSO"
+.PP
+create function(l), drop language(l).
+.SH "RESTRICTIONS"
+Since the call handler for a procedural language must be
+registered with Postgres in the 'C' language, it inherits
+all the restrictions of 'C' functions.
+.SH "BUGS"
+Currently, the definitions for a procedural language once
+created cannot be changed.
projects / postgresql.git / commitdiff