From bc0afb715d5ec717e3f44ebbe0ac261700f755bf Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Sat, 6 Jan 2001 12:26:08 +0000 Subject: [PATCH] EXECUTE documentation, from "Robert B. Easter" . I threw in spell check run over the whole file. --- doc/src/sgml/plsql.sgml | 116 +++++++++++++++++++++++++++------------- 1 file changed, 80 insertions(+), 36 deletions(-) diff --git a/doc/src/sgml/plsql.sgml b/doc/src/sgml/plsql.sgml index 877903cea11..12cd5de6120 100644 --- a/doc/src/sgml/plsql.sgml +++ b/doc/src/sgml/plsql.sgml @@ -1,5 +1,5 @@ @@ -55,8 +55,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/plsql.sgml,v 2.11 2000/12/22 18:57:50 The PL/pgSQL call handler parses the functions source text and - produces an internal binary instruction tree on the first time, the - function is called by a backend. The produced bytecode is identified + produces an internal binary instruction tree on the first time the + function is called. The produced bytecode is identified in the call handler by the object ID of the function. This ensures, that changing a function by a DROP/CREATE sequence will take effect without establishing a new database connection. @@ -109,8 +109,8 @@ END; - There can be any number of subblocks in the statement section - of a block. Subblocks can be used to hide variables from outside a + There can be any number of sub-blocks in the statement section + of a block. Sub-blocks can be used to hide variables from outside a block of statements. The variables declared in the declarations section preceding a block are initialized to their default values every time the block is entered, @@ -132,7 +132,7 @@ END; There are two types of comments in PL/pgSQL. A double dash '--' starts a comment that extends to the end of the line. A '/*' - starts a block comment that extends to the next occurence of '*/'. + starts a block comment that extends to the next occurrence of '*/'. Block comments cannot be nested, but double dash comments can be enclosed into a block comment and a double dash can hide the block comment delimiters '/*' and '*/'. @@ -145,8 +145,8 @@ END; Declarations - All variables, rows and records used in a block or it's - subblocks must be declared in the declarations section of a block + All variables, rows and records used in a block or its + sub-blocks must be declared in the declarations section of a block except for the loop variable of a FOR loop iterating over a range of integer values. Parameters given to a PL/pgSQL function are automatically declared with the usual identifiers $n. @@ -174,7 +174,7 @@ END; assigning 'now' to a variable of type datetime causes the variable to have the time of the actual function call, not when the function was - precompiled into it's bytecode. + precompiled into its bytecode. @@ -186,7 +186,7 @@ END; Declares a row with the structure of the given class. Class must be - an existing table- or viewname of the database. The fields of the row + an existing table- or view name of the database. The fields of the row are accessed in the dot notation. Parameters to a function can be composite types (complete table rows). In that case, the corresponding identifier $n will be a rowtype, but it @@ -196,7 +196,7 @@ END; don't have useful system attributes). - The fields of the rowtype inherit the tables fieldsizes + The fields of the rowtype inherit the table's field sizes or precision for char() etc. data types. @@ -263,7 +263,7 @@ RENAME oldname TO newname; Data Types - The type of a varible can be any of the existing basetypes of + The type of a variable can be any of the existing base types of the database. type in the declarations section above is defined as: @@ -298,14 +298,14 @@ RENAME oldname TO newname; Using the class.field%TYPE - causes PL/pgSQL to lookup the attributes definitions at the + causes PL/pgSQL to look up the attributes definitions at the first call to the function during the lifetime of a backend. Have a table with a char(20) attribute and some PL/pgSQL functions - that deal with it's content in local variables. Now someone + that deal with its content in local variables. Now someone decides that char(20) isn't enough, dumps the table, drops it, recreates it now with the attribute in question defined as char(40) and restores the data. Ha - he forgot about the - funcitons. The computations inside them will truncate the values + functions. The computations inside them will truncate the values to 20 characters. But if they are defined using the class.field%TYPE declarations, they will automagically handle the size change or @@ -320,7 +320,7 @@ RENAME oldname TO newname; All expressions used in PL/pgSQL statements are processed using - the backends executor. Expressions that appear to contain + the backend's executor. Expressions that appear to contain constants may in fact require run-time evaluation (e.g. 'now' for the datetime type) so it is impossible for the PL/pgSQL parser @@ -329,11 +329,12 @@ RENAME oldname TO newname; SELECT expression - using the SPI manager. In the expression, occurences of variable + using the SPI manager. In the expression, occurrences of variable identifiers are substituted by parameters and the actual values from the variables are passed to the executor in the parameter array. All expressions used in a PL/pgSQL function are only prepared and - saved once. + saved once. The only exception to this rule is an EXECUTE statement + if parsing of a query is needed each time it is encountered. The type checking done by the Postgres @@ -379,7 +380,7 @@ CREATE FUNCTION logfunc2 (text) RETURNS datetime AS ' In the case of logfunc2(), the Postgres main parser does not know - what type 'now' should become and therefor it returns a datatype of + what type 'now' should become and therefore it returns a data type of text containing the string 'now'. During the assignment to the local variable curtime, the PL/pgSQL interpreter casts this string to the datetime type by calling the text_out() and datetime_in() @@ -467,7 +468,7 @@ END IF; Calling another function - All functions defined in a Prostgres + All functions defined in a Postgres database return a value. Thus, the normal way to call a function is to execute a SELECT query or doing an assignment (resulting in a PL/pgSQL internal SELECT). But there are cases where someone @@ -482,6 +483,49 @@ PERFORM query + + Executing dynamic queries + + + EXECUTE + query + + + + Unlike all other queries in PL/pgSQL, a + query run by an EXECUTE statement + is not prepared and saved just once during the life of the + server. Instead, the query is + prepared each time the statement is run. This allows the + query to be dynamically created + within the procedure to perform actions on variable tables and + fields. + + + + An example: + +EXECUTE ''UPDATE tbl SET '' + || quote_ident(fieldname) + || '' = '' + || quote_literal(newvalue) + || '' WHERE ...''; + + This example shows use of the functions + quote_ident(TEXT) and + quote_literal(TEXT). + Variables containing field and table identifiers should be + passed to function quote_ident(). + Variables containing literal elements of the dynamic query + string should be passed to + quote_literal(). Both take the + appropriate steps to return the input text enclosed in single + or double quotes and with any embedded special characters + intact. + + + + Returning from the function @@ -491,7 +535,7 @@ RETURN expression The function terminates and the value of expression will be returned to the upper executor. The return value of a function - cannot be undefined. If control reaches the end of the toplevel block + cannot be undefined. If control reaches the end of the top-level block of the function without hitting a RETURN statement, a runtime error will occur. @@ -619,7 +663,7 @@ EXIT [ label ] [ WHEN expression First they have some special variables created automatically in the - toplevel blocks declaration section. They are + top-level blocks declaration section. They are @@ -627,7 +671,7 @@ EXIT [ label ] [ WHEN expressionNEW - Datatype RECORD; variable holding the new database row on INSERT/UPDATE + Data type RECORD; variable holding the new database row on INSERT/UPDATE operations on ROW level triggers. @@ -637,7 +681,7 @@ EXIT [ label ] [ WHEN expressionOLD - Datatype RECORD; variable holding the old database row on UPDATE/DELETE + Data type RECORD; variable holding the old database row on UPDATE/DELETE operations on ROW level triggers. @@ -647,7 +691,7 @@ EXIT [ label ] [ WHEN expressionTG_NAME - Datatype name; variable that contains the name of the trigger actually + Data type name; variable that contains the name of the trigger actually fired. @@ -657,7 +701,7 @@ EXIT [ label ] [ WHEN expressionTG_WHEN - Datatype text; a string of either 'BEFORE' or 'AFTER' depending on the + Data type text; a string of either 'BEFORE' or 'AFTER' depending on the triggers definition. @@ -667,7 +711,7 @@ EXIT [ label ] [ WHEN expressionTG_LEVEL - Datatype text; a string of either 'ROW' or 'STATEMENT' depending on the + Data type text; a string of either 'ROW' or 'STATEMENT' depending on the triggers definition. @@ -677,7 +721,7 @@ EXIT [ label ] [ WHEN expressionTG_OP - Datatype text; a string of 'INSERT', 'UPDATE' or 'DELETE' telling + Data type text; a string of 'INSERT', 'UPDATE' or 'DELETE' telling for which operation the trigger is actually fired. @@ -687,7 +731,7 @@ EXIT [ label ] [ WHEN expressionTG_RELID - Datatype oid; the object ID of the table that caused the + Data type oid; the object ID of the table that caused the trigger invocation. @@ -697,7 +741,7 @@ EXIT [ label ] [ WHEN expressionTG_RELNAME - Datatype name; the name of the table that caused the trigger + Data type name; the name of the table that caused the trigger invocation. @@ -707,7 +751,7 @@ EXIT [ label ] [ WHEN expressionTG_NARGS - Datatype integer; the number of arguments given to the trigger + Data type integer; the number of arguments given to the trigger procedure in the CREATE TRIGGER statement. @@ -717,7 +761,7 @@ EXIT [ label ] [ WHEN expressionTG_ARGV[] - Datatype array of text; the arguments from the CREATE TRIGGER statement. + Data type array of text; the arguments from the CREATE TRIGGER statement. The index counts from 0 and can be given as an expression. Invalid indices (< 0 or >= tg_nargs) result in a NULL value. @@ -748,11 +792,11 @@ EXIT [ label ] [ WHEN expression It is possible to hook into the error mechanism to notice that this - happens. But currently it's impossible to tell what really + happens. But currently it is impossible to tell what really caused the abort (input/output conversion error, floating point error, parse error). And it is possible that the database backend is in an inconsistent state at this point so returning to the upper @@ -787,7 +831,7 @@ EXIT [ label ] [ WHEN expressionPostgres will be upward compatible. @@ -848,7 +892,7 @@ CREATE FUNCTION c_overpaid (EMP, int4) RETURNS bool AS ' This trigger ensures, that any time a row is inserted or updated - in the table, the current username and time are stamped into the + in the table, the current user name and time are stamped into the row. And it ensures that an employees name is given and that the salary is a positive value.