From 467f43d2fae9ac58c3d96e56eb7c8dde25e4ab67 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Fri, 9 Feb 2001 03:06:38 +0000 Subject: [PATCH] Document PL/TclU language variant, and do some minor copy-editing. --- doc/src/sgml/pltcl.sgml | 79 ++++++++++++++++++++++++++--------------- 1 file changed, 50 insertions(+), 29 deletions(-) diff --git a/doc/src/sgml/pltcl.sgml b/doc/src/sgml/pltcl.sgml index 6267d8c412..e21e92e4c9 100644 --- a/doc/src/sgml/pltcl.sgml +++ b/doc/src/sgml/pltcl.sgml @@ -1,5 +1,5 @@ @@ -9,7 +9,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/pltcl.sgml,v 2.6 2000/09/29 20:21:34 petere PL/Tcl is a loadable procedural language for the Postgres database system that enables the Tcl language to be used to create functions and - trigger-procedures. + trigger procedures. @@ -26,24 +26,39 @@ $Header: /cvsroot/pgsql/doc/src/sgml/pltcl.sgml,v 2.6 2000/09/29 20:21:34 petere writer has in the C language, except for some restrictions. - The good restriction is, that everything is executed in a safe - Tcl-interpreter. In addition to the limited command set of safe Tcl, only - a few commands are available to access the database over SPI and to raise + The good restriction is that everything is executed in a safe + Tcl interpreter. In addition to the limited command set of safe Tcl, only + a few commands are available to access the database via SPI and to raise messages via elog(). There is no way to access internals of the - database backend or gaining OS-level access under the permissions of the - Postgres user ID like in C. + database backend or to gain OS-level access under the permissions of the + Postgres user ID, as a C function can do. Thus, any unprivileged database user may be permitted to use this language. - The other, internal given, restriction is, that Tcl procedures cannot - be used to create input-/output-functions for new data types. + The other, implementation restriction is that Tcl procedures cannot + be used to create input/output functions for new data types. - The shared object for the PL/Tcl call handler is automatically built - and installed in the Postgres - library directory if the Tcl/Tk support is specified - in the configuration step of the installation procedure. + Sometimes it is desirable to write Tcl functions that are not restricted + to safe Tcl --- for example, one might want a Tcl function that sends + mail. To handle these cases, there is a variant of PL/Tcl called PL/TclU + (for untrusted Tcl). This is the exact same language except that a full + Tcl interpreter is used. If PL/TclU is used, it must be + installed as an untrusted procedural language so that only + database superusers can create functions in it. The writer of a PL/TclU + function must take care that the function cannot be used to do anything + unwanted, since it will be able to do anything that could be done by + a user logged in as the database administrator. + + + The shared object for the PL/Tcl and PL/TclU call handlers is + automatically built and installed in the + Postgres + library directory if Tcl/Tk support is specified + in the configuration step of the installation procedure. To install + PL/Tcl and/or PL/TclU in a particular database, use the + createlang script. @@ -61,7 +76,7 @@ $Header: /cvsroot/pgsql/doc/src/sgml/pltcl.sgml,v 2.6 2000/09/29 20:21:34 petere different functions as long as the number of arguments or their types differ. This would collide with Tcl procedure names. To offer the same flexibility in PL/Tcl, the internal Tcl procedure names contain the object - ID of the procedures pg_proc row as part of their name. Thus, different + ID of the procedure's pg_proc row as part of their name. Thus, different argtype versions of the same Postgres function are different for Tcl too. @@ -72,17 +87,18 @@ $Header: /cvsroot/pgsql/doc/src/sgml/pltcl.sgml,v 2.6 2000/09/29 20:21:34 petere Defining Functions in PL/Tcl - To create a function in the PL/Tcl language, use the known syntax + To create a function in the PL/Tcl language, use the standard syntax -CREATE FUNCTION funcname argument-types) RETURNS return-type AS ' +CREATE FUNCTION funcname (argument-types) RETURNS return-type AS ' # PL/Tcl function body ' LANGUAGE 'pltcl'; - When calling this function in a query, the arguments are given as - variables $1 ... $n to the Tcl procedure body. So a little max function - returning the higher of two int4 values would be created as: + When the function is called, the arguments are given as + variables $1 ... $n to the Tcl procedure body. For example, + a function + returning the higher of two int4 values could be defined as: CREATE FUNCTION tcl_max (int4, int4) RETURNS int4 AS ' @@ -120,13 +136,18 @@ CREATE FUNCTION overpaid_2 (EMP) RETURNS bool AS ' Sometimes (especially when using the SPI functions described later) it is useful to have some global status data that is held between two - calls to a procedure. - All PL/Tcl procedures executed in one backend share the same + calls to a procedure. This is easily done since + all PL/Tcl procedures executed in one backend share the same safe Tcl interpreter. - To help protecting PL/Tcl procedures from side effects, + + + To help protect PL/Tcl procedures from unwanted side effects, an array is made available to each procedure via the upvar - command. The global name of this variable is the procedures internal - name and the local name is GD. + command. The global name of this variable is the procedure's internal + name and the local name is GD. It is recommended that GD be used + for private status data of a procedure. Use regular Tcl global variables + only for values that you specifically intend to be shared among multiple + procedures. @@ -140,7 +161,7 @@ CREATE FUNCTION overpaid_2 (EMP) RETURNS bool AS ' language. - The informations from the trigger manager are given to the procedure body + The information from the trigger manager is given to the procedure body in the following variables: @@ -259,8 +280,8 @@ CREATE FUNCTION overpaid_2 (EMP) RETURNS bool AS ' Here's a little example trigger procedure that forces an integer value - in a table to keep track of the # of updates that are performed on the - row. For new row's inserted, the value is initialized to 0 and then + in a table to keep track of the number of updates that are performed on the + row. For new rows inserted, the value is initialized to 0 and then incremented on every update operation: @@ -305,7 +326,7 @@ CREATE TRIGGER trig_mytab_modcount BEFORE INSERT OR UPDATE ON mytab Fire a log message. Possible levels are NOTICE, ERROR, FATAL, DEBUG and NOIND - like for the elog C function. + as for the elog C function. @@ -332,7 +353,7 @@ CREATE TRIGGER trig_mytab_modcount BEFORE INSERT OR UPDATE ON mytab "SELECT 'doesn't' AS ret" - what would cause a parse error during + which would cause a parse error during spi_exec or spi_prepare. It should contain -- 2.40.0