|
| 1 | +.\" This is -*-nroff-*- |
| 2 | +.\" XXX standard disclaimer belongs here.... |
| 3 | +.\" $Header: /cvsroot/pgsql/src/man/Attic/create_language.l,v 1.1 1997/10/30 05:38:19 vadim Exp $ |
| 4 | +.TH "CREATE LANGUAGE" SQL 11/05/95 PostgreSQL PostgreSQL |
| 5 | +.SH "NAME" |
| 6 | +create language\(em define a new language for functions |
| 7 | +.SH "SYNOPSIS" |
| 8 | +.nf |
| 9 | +\fBcreate\fP [\fBtrusted\fP]\fBprocedurallanguage\fP 'lanname' |
| 10 | +\fBhandler\fP call_handler |
| 11 | +\fBlancompiler\fP 'comment' |
| 12 | +.fi |
| 13 | +.SH "DESCRIPTION" |
| 14 | +With this command, a Postgres user can register a new language with |
| 15 | +Postgres. Subsequently, functions and trigger procedures can be |
| 16 | +defined in this new language. The user must have the Postgres superuser |
| 17 | +privilege to register a new language. |
| 18 | +.PP |
| 19 | +The lanname is the name of the new procedural language. It is converted |
| 20 | +to lower case before the new entry in the pg_language system catalog |
| 21 | +is inserted. Note that this case translation is also done on |
| 22 | +create function(l) and drop language(l). Thus, the language name |
| 23 | +is case insensitive. A procedural language cannot override one of the |
| 24 | +builtin languages of Postgres. |
| 25 | +.PP |
| 26 | +The argument for\fBhandler\fP |
| 27 | +is the name of a previously registered function that |
| 28 | +will be called to execute the PL procedures. |
| 29 | +.PP |
| 30 | +The\fBlancompiler\fP argument is the string that will be inserted |
| 31 | +in the lancompiler attribute of the new pg_language entry. Up to now, |
| 32 | +Postgres doesn't use this attribute in any way. |
| 33 | +.PP |
| 34 | +The\fBtrusted\fP keyword specifies, that the call handler for the |
| 35 | +language is safe - i.e. it offers an unprivileged user no functionality |
| 36 | +to get around access restrictions. If this keyword is omitted when |
| 37 | +registering the language, only users with the Postgres superuser privilege |
| 38 | +can use this language to create new functions (like the 'C' language). |
| 39 | +.SH "WRITING PL HANDLERS" |
| 40 | +The call handler for a procedural language must be written in a compiler |
| 41 | +language such as 'C' and registered with Postgres as a function taking |
| 42 | +no arguments and returning |
| 43 | +.IR"opaque" |
| 44 | +type. This prevents the call handler from beeing called directly as a function |
| 45 | +from queries. |
| 46 | +But there are arguments |
| 47 | +on the actual call when a PL function or trigger procedure in the |
| 48 | +language offered by the handler is to be executed. |
| 49 | +.PP |
| 50 | +When called from the trigger manager, the only argument is the object ID from |
| 51 | +the procedures pg_proc entry. All other information from the trigger manager |
| 52 | +is found in the global CurrentTriggerData pointer. |
| 53 | +.PP |
| 54 | +When called from the function manager, the arguments are the object ID of the |
| 55 | +procedures pg_proc entry, the number of arguments given to the PL function, |
| 56 | +the arguments in a FmgrValues structure and a pointer to a boolean where the |
| 57 | +function tells the caller if the return value is the SQL NULL value. |
| 58 | +.PP |
| 59 | +It's up to the call handler to fetch the pg_proc entry |
| 60 | +and to analyze the argument and return types of the called procedure. |
| 61 | +the |
| 62 | +.IR"as" |
| 63 | +clause from the create function(l) of the procedure will be found in |
| 64 | +the prosrc attribute of the pg_proc entry. This may be the source text |
| 65 | +in the procedural language itself (like for PL/Tcl), a pathname to a |
| 66 | +file or anything else that tells the call handler what to do in detail. |
| 67 | +.SH "EXAMPLE" |
| 68 | +Following is a template for a PL handler written in 'C': |
| 69 | +.nf |
| 70 | + |
| 71 | +#include "executor/spi.h" |
| 72 | +#include "commands/trigger.h" |
| 73 | +#include "utils/elog.h" |
| 74 | +#include "fmgr.h"/* for FmgrValues struct */ |
| 75 | +#include "access/heapam.h" |
| 76 | +#include "utils/syscache.h" |
| 77 | +#include "catalog/pg_proc.h" |
| 78 | +#include "catalog/pg_type.h" |
| 79 | + |
| 80 | +Datum |
| 81 | +plsample_call_handler( |
| 82 | +Oidprooid, |
| 83 | +intpronargs, |
| 84 | +FmgrValues*proargs, |
| 85 | +bool*isNull) |
| 86 | +{ |
| 87 | +Datumretval; |
| 88 | +TriggerData*trigdata; |
| 89 | + |
| 90 | +if (CurrentTriggerData == NULL) { |
| 91 | +/* |
| 92 | + * Called as a function |
| 93 | + */ |
| 94 | + |
| 95 | +retval = ... |
| 96 | +} else { |
| 97 | +/* |
| 98 | + * Called as a trigger procedure |
| 99 | + */ |
| 100 | +trigdata = CurrentTriggerData; |
| 101 | +CurrentTriggerData = NULL; |
| 102 | + |
| 103 | +retval = ... |
| 104 | +} |
| 105 | + |
| 106 | +*isNull = false; |
| 107 | +return retval; |
| 108 | +} |
| 109 | + |
| 110 | +.fi |
| 111 | +Only a few thousand lines of code have to be added instead of the dots |
| 112 | +to complete the PL call handler. See create function(l) how to compile |
| 113 | +it into a loadable module. The following commands then register the |
| 114 | +sample procedural language. |
| 115 | +.nf |
| 116 | + |
| 117 | +create function plsample_call_handler () returns opaque |
| 118 | +as '/usr/local/pgsql/lib/plsample.so' |
| 119 | +language 'C'; |
| 120 | + |
| 121 | +create procedural language 'plsample' |
| 122 | +handler plsample_call_handler |
| 123 | +lancompiler 'PL/Sample'; |
| 124 | + |
| 125 | +.fi |
| 126 | +.SH "SEE ALSO" |
| 127 | +.PP |
| 128 | +create function(l), drop language(l). |
| 129 | +.SH "RESTRICTIONS" |
| 130 | +Since the call handler for a procedural language must be |
| 131 | +registered with Postgres in the 'C' language, it inherits |
| 132 | +all the restrictions of 'C' functions. |
| 133 | +.SH "BUGS" |
| 134 | +Currently, the definitions for a procedural language once |
| 135 | +created cannot be changed. |