mirrors/postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

EXECUTE documentation, from "Robert B. Easter" <reaster@comptechnews.com>.

Browse Source 
I threw in spell check run over the whole file.
This commit is contained in:
Peter Eisentraut 2001-01-06 12:26:08 +00:00
parent 3942ee389c
commit bc0afb715d
1 changed files with 80 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

116
doc/src/sgml/plsql.sgml
View File

@ -1,5 +1,5 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/plsql.sgml,v 2.11 2000/12/22 18:57:50 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/plsql.sgml,v 2.12 2001/01/06 12:26:08 petere Exp $
-->
<chapter id="plsql">
@ -55,8 +55,8 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/plsql.sgml,v 2.11 2000/12/22 18:57:50
</para>
<para>
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;
</para>
<para>
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;
<para>
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;
<title>Declarations</title>
<para>
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 '<replaceable>now</replaceable>' to a variable of type
<replaceable>datetime</replaceable> 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.
</para>
</listitem>
</varlistentry>
@ -186,7 +186,7 @@ END;
<listitem>
<para>
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).
</para>
<para>
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.
</para>
</listitem>
@ -263,7 +263,7 @@ RENAME <replaceable>oldname</replaceable> TO <replaceable>newname</replaceable>;
<title>Data Types</title>
<para>
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. <replaceable>type</replaceable> in the declarations
section above is defined as:
</para>
@ -298,14 +298,14 @@ RENAME <replaceable>oldname</replaceable> TO <replaceable>newname</replaceable>;
</para>
<para>
Using the <replaceable>class.field</replaceable>%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
<replaceable>class.field</replaceable>%TYPE
declarations, they will automagically handle the size change or
@ -320,7 +320,7 @@ RENAME <replaceable>oldname</replaceable> TO <replaceable>newname</replaceable>;
<para>
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 <replaceable>oldname</replaceable> TO <replaceable>newname</replaceable>;
<programlisting>
SELECT <replaceable>expression</replaceable>
</programlisting>
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.
</para>
<para>
The type checking done by the <productname>Postgres</productname>
@ -379,7 +380,7 @@ CREATE FUNCTION logfunc2 (text) RETURNS datetime AS '
<para>
In the case of logfunc2(), the <productname>Postgres</productname>
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;
<term>Calling another function</term>
<listitem>
<para>
All functions defined in a <productname>Prostgres</productname>
All functions defined in a <productname>Postgres</productname>
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 <replaceable>query</replaceable>
</listitem>
</varlistentry>
<varlistentry>
<term>Executing dynamic queries</term>
<listitem>
<cmdsynopsis>
<command>EXECUTE</command>
<arg choice="req"><replaceable class="command">query</replaceable></arg>
</cmdsynopsis>
<para>
Unlike all other queries in PL/pgSQL, a
<replaceable>query</replaceable> run by an EXECUTE statement
is not prepared and saved just once during the life of the
server. Instead, the <replaceable>query</replaceable> is
prepared each time the statement is run. This allows the
<replaceable>query</replaceable> to be dynamically created
within the procedure to perform actions on variable tables and
fields.
</para>
<para>
An example:
<programlisting>
EXECUTE ''UPDATE tbl SET ''
|| quote_ident(fieldname)
|| '' = ''
|| quote_literal(newvalue)
|| '' WHERE ...'';
</programlisting>
This example shows use of the functions
<function>quote_ident</function>(<type>TEXT</type>) and
<function>quote_literal</function>(<type>TEXT</type>).
Variables containing field and table identifiers should be
passed to function <function>quote_ident()</function>.
Variables containing literal elements of the dynamic query
string should be passed to
<function>quote_literal()</function>. Both take the
appropriate steps to return the input text enclosed in single
or double quotes and with any embedded special characters
intact.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Returning from the function</term>
<listitem>
@ -491,7 +535,7 @@ RETURN <replaceable>expression</replaceable>
</programlisting>
The function terminates and the value of <replaceable>expression</replaceable>
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.
</para>
@ -619,7 +663,7 @@ EXIT [ <replaceable>label</replaceable> ] [ WHEN <replaceable>expression</replac
</para>
<para>
First they have some special variables created automatically in the
toplevel blocks declaration section. They are
top-level blocks declaration section. They are
</para>
<variablelist>
@ -627,7 +671,7 @@ EXIT [ <replaceable>label</replaceable> ] [ WHEN <replaceable>expression</replac
<term>NEW</term>
<listitem>
<para>
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.
</para>
</listitem>
@ -637,7 +681,7 @@ EXIT [ <replaceable>label</replaceable> ] [ WHEN <replaceable>expression</replac
<term>OLD</term>
<listitem>
<para>
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.
</para>
</listitem>
@ -647,7 +691,7 @@ EXIT [ <replaceable>label</replaceable> ] [ WHEN <replaceable>expression</replac
<term>TG_NAME</term>
<listitem>
<para>
Datatype name; variable that contains the name of the trigger actually
Data type name; variable that contains the name of the trigger actually
fired.
</para>
</listitem>
@ -657,7 +701,7 @@ EXIT [ <replaceable>label</replaceable> ] [ WHEN <replaceable>expression</replac
<term>TG_WHEN</term>
<listitem>
<para>
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.
</para>
</listitem>
@ -667,7 +711,7 @@ EXIT [ <replaceable>label</replaceable> ] [ WHEN <replaceable>expression</replac
<term>TG_LEVEL</term>
<listitem>
<para>
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.
</para>
</listitem>
@ -677,7 +721,7 @@ EXIT [ <replaceable>label</replaceable> ] [ WHEN <replaceable>expression</replac
<term>TG_OP</term>
<listitem>
<para>
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.
</para>
</listitem>
@ -687,7 +731,7 @@ EXIT [ <replaceable>label</replaceable> ] [ WHEN <replaceable>expression</replac
<term>TG_RELID</term>
<listitem>
<para>
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.
</para>
</listitem>
@ -697,7 +741,7 @@ EXIT [ <replaceable>label</replaceable> ] [ WHEN <replaceable>expression</replac
<term>TG_RELNAME</term>
<listitem>
<para>
Datatype name; the name of the table that caused the trigger
Data type name; the name of the table that caused the trigger
invocation.
</para>
</listitem>
@ -707,7 +751,7 @@ EXIT [ <replaceable>label</replaceable> ] [ WHEN <replaceable>expression</replac
<term>TG_NARGS</term>
<listitem>
<para>
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.
</para>
</listitem>
@ -717,7 +761,7 @@ EXIT [ <replaceable>label</replaceable> ] [ WHEN <replaceable>expression</replac
<term>TG_ARGV[]</term>
<listitem>
<para>
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 (&lt; 0 or &gt;= tg_nargs) result in a NULL value.
</para>
@ -748,11 +792,11 @@ EXIT [ <replaceable>label</replaceable> ] [ WHEN <replaceable>expression</replac
exception handling model. Whenever the parser, planner/optimizer
or executor decide that a statement cannot be processed any longer,
the whole transaction gets aborted and the system jumps back
into the mainloop to get the next query from the client application.
into the main loop to get the next query from the client application.
</para>
<para>
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 [ <replaceable>label</replaceable> ] [ WHEN <replaceable>expression</replac
of single quotes. The functions source text on CREATE FUNCTION must
be a literal string. Single quotes inside of literal strings must be
either doubled or quoted with a backslash. We are still looking for
an elegant alternative. In the meantime, doubling the single qoutes
an elegant alternative. In the meantime, doubling the single quotes
as in the examples below should be used. Any solution for this
in future versions of <productname>Postgres</productname> will be
upward compatible.
@ -848,7 +892,7 @@ CREATE FUNCTION c_overpaid (EMP, int4) RETURNS bool AS '
<para>
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.