mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-09-30 21:41:18 +02:00
CREATE PROCEDURAL LANGUAGE mans (Jan).
This commit is contained in:
parent
43514b8485
commit
6cfe951a42
@ -1,6 +1,6 @@
|
|||||||
.\" This is -*-nroff-*-
|
.\" This is -*-nroff-*-
|
||||||
.\" XXX standard disclaimer belongs here....
|
.\" 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
|
.TH "CREATE FUNCTION" SQL 11/05/95 PostgreSQL PostgreSQL
|
||||||
.SH "NAME"
|
.SH "NAME"
|
||||||
create function \(em define a new function
|
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
|
\fB(\fP[type1 {, type-n}]\fB)\fP
|
||||||
\fBreturns\fP type-r
|
\fBreturns\fP type-r
|
||||||
\fBas\fP {'/full/path/to/objectfile' | 'sql-queries'}
|
\fBas\fP {'/full/path/to/objectfile' | 'sql-queries'}
|
||||||
\fBlanguage\fP {'c' \ 'sql' \ 'internal'}
|
\fBlanguage\fP {'c' \ 'sql' \ 'internal' \ 'plname'}
|
||||||
.fi
|
.fi
|
||||||
.SH "DESCRIPTION"
|
.SH "DESCRIPTION"
|
||||||
With this command, a Postgres user can register a function with Postgres.
|
With this command, a Postgres user can register a function with Postgres.
|
||||||
@ -29,6 +29,12 @@ or
|
|||||||
.IR "\*(lqsql\*(rq" .
|
.IR "\*(lqsql\*(rq" .
|
||||||
or
|
or
|
||||||
.IR "\*(lqinternal\*(rq" .
|
.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
|
(The
|
||||||
.IR "arg is"
|
.IR "arg is"
|
||||||
clause may be left out if the function has no arguments, or
|
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
|
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
|
used to access attributes of the argument (e.g. \*(lq$1.emp\*(rq), or
|
||||||
to invoke functions via a nested-dot syntax.
|
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"
|
.SH "EXAMPLES: C Functions"
|
||||||
The following command defines a C function, overpaid, of two basetype
|
The following command defines a C function, overpaid, of two basetype
|
||||||
arguments.
|
arguments.
|
||||||
@ -378,7 +390,7 @@ select function hobbies (EMP) returns set of HOBBIES
|
|||||||
language 'sql'
|
language 'sql'
|
||||||
.SH "SEE ALSO"
|
.SH "SEE ALSO"
|
||||||
.PP
|
.PP
|
||||||
information(1), load(l), drop function(l).
|
information(1), load(l), drop function(l), create language(l).
|
||||||
.SH "NOTES"
|
.SH "NOTES"
|
||||||
.SH "Name Space Conflicts"
|
.SH "Name Space Conflicts"
|
||||||
More than one function may be defined with the same name, as long as
|
More than one function may be defined with the same name, as long as
|
||||||
|
135
src/man/create_language.l
Normal file
135
src/man/create_language.l
Normal file
@ -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.
|
30
src/man/drop_language.l
Normal file
30
src/man/drop_language.l
Normal file
@ -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.
|
Loading…
Reference in New Issue
Block a user