CREATE PROCEDURAL LANGUAGE mans (Jan).

3 files changed, 180 insertions, 3 deletions

diff --git a/src/man/create_function.l b/src/man/create_function.l
index 917d3e7cdab..7fbc4d50790 100644
--- a/src/man/create_function.l
+++ b/src/man/create_function.l
@@ -1,6 +1,6 @@
 .\" 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
@@ -10,7 +10,7 @@ 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.
@@ -29,6 +29,12 @@ or
 .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
@@ -291,6 +297,12 @@ a $n syntax: $1 refers to the first argument, $2 to the second, and so
 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.
@@ -378,7 +390,7 @@ select function hobbies (EMP) returns set of HOBBIES
 	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
diff --git a/src/man/create_language.l b/src/man/create_language.l
new file mode 100644
index 00000000000..2b5c3047851
--- /dev/null
+++ b/src/man/create_language.l
@@ -0,0 +1,135 @@
+.\" 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. 
diff --git a/src/man/drop_language.l b/src/man/drop_language.l
new file mode 100644
index 00000000000..8ed598fec51
--- /dev/null
+++ b/src/man/drop_language.l
@@ -0,0 +1,30 @@
+.\" This is -*-nroff-*-
+.\" XXX standard disclaimer belongs here....
+.\" $Header: /cvsroot/pgsql/src/man/Attic/drop_language.l,v 1.1 1997/10/30 05:38:20 vadim Exp $
+.TH "DROP LANGUAGE" SQL 11/05/95 PostgreSQL PostgreSQL
+.SH NAME
+drop language \(em remove a user-defined procedural language
+.SH SYNOPSIS
+.nf
+\fBdrop procedural language\fR 'lanname'
+.fi
+.SH DESCRIPTION
+.BR "drop procedural language"
+will remove the definition of the previously registered PL with the
+name
+.IR lanname .
+.SH EXAMPLE
+.nf
+--
+--this command removes the PL/Sample language
+--
+drop procedural language 'plsample';
+.fi
+.SH "SEE ALSO"
+create language(l).
+.SH BUGS
+No checks are made if functions or trigger procedures registered
+in this language still exist. To reenable them without having to
+drop and recreate all the functions, the pg_proc's prolang attribute
+of the functions must be adjusted to the new object ID of the
+recreated pg_language entry for the PL.