Fix documentation of EXECUTE, add documentation of FOR ... EXECUTE.
This commit is contained in:
parent
af0a15287d
commit
618733de1a
|
@ -1,5 +1,5 @@
|
||||||
<!--
|
<!--
|
||||||
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/plsql.sgml,v 2.18 2001/01/20 20:59:29 petere Exp $
|
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/plsql.sgml,v 2.19 2001/02/10 05:32:33 tgl Exp $
|
||||||
-->
|
-->
|
||||||
|
|
||||||
<chapter id="plsql">
|
<chapter id="plsql">
|
||||||
|
@ -54,26 +54,35 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/plsql.sgml,v 2.18 2001/01/20 20:59:29
|
||||||
</itemizedlist>
|
</itemizedlist>
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
The PL/pgSQL call handler parses the functions source text and
|
The PL/pgSQL call handler parses the function's source text and
|
||||||
produces an internal binary instruction tree on the first time the
|
produces an internal binary instruction tree the first time the
|
||||||
function is called. The produced bytecode is identified
|
function is called. The produced bytecode is identified
|
||||||
in the call handler by the object ID of the function. This ensures,
|
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
|
that changing a function by a DROP/CREATE sequence will take effect
|
||||||
without establishing a new database connection.
|
without establishing a new database connection.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
For all expressions and <acronym>SQL</acronym> statements used in
|
For all expressions and <acronym>SQL</acronym> statements used in
|
||||||
the function, the PL/pgSQL bytecode interpreter creates a
|
the function, the PL/pgSQL bytecode interpreter creates a
|
||||||
prepared execution plan using the SPI managers SPI_prepare() and
|
prepared execution plan using the SPI manager's SPI_prepare() and
|
||||||
SPI_saveplan() functions. This is done the first time, the individual
|
SPI_saveplan() functions. This is done the first time the individual
|
||||||
statement is processed in the PL/pgSQL function. Thus, a function with
|
statement is processed in the PL/pgSQL function. Thus, a function with
|
||||||
conditional code that contains many statements for which execution
|
conditional code that contains many statements for which execution
|
||||||
plans would be required, will only prepare and save those plans
|
plans would be required, will only prepare and save those plans
|
||||||
that are really used during the entire lifetime of the database
|
that are really used during the lifetime of the database
|
||||||
connection.
|
connection.
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
Except for input-/output-conversion and calculation functions
|
Because PL/pgSQL saves execution plans in this way, queries that appear
|
||||||
|
directly in a PL/pgSQL function must refer to the same tables and fields
|
||||||
|
on every execution; that is, you cannot use a parameter as the name of
|
||||||
|
a table or field in a query. To get around
|
||||||
|
this restriction, you can construct dynamic queries using the PL/pgSQL
|
||||||
|
EXECUTE statement --- at the price of constructing a new query plan
|
||||||
|
on every execution.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Except for input/output conversion and calculation functions
|
||||||
for user defined types, anything that can be defined in C language
|
for user defined types, anything that can be defined in C language
|
||||||
functions can also be done with PL/pgSQL. It is possible to
|
functions can also be done with PL/pgSQL. It is possible to
|
||||||
create complex conditional computation functions and later use
|
create complex conditional computation functions and later use
|
||||||
|
@ -118,11 +127,13 @@ END;
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
It is important not to misunderstand the meaning of BEGIN/END for
|
It is important not to confuse the use of BEGIN/END for
|
||||||
grouping statements in PL/pgSQL and the database commands for
|
grouping statements in PL/pgSQL with the database commands for
|
||||||
transaction control. Functions and trigger procedures cannot
|
transaction control. PL/pgSQL's BEGIN/END are only for grouping;
|
||||||
start or commit transactions and <productname>Postgres</productname>
|
they do not start or end a transaction. Functions and trigger procedures
|
||||||
does not have nested transactions.
|
are always executed within a transaction established by an outer query
|
||||||
|
--- they cannot start or commit transactions, since
|
||||||
|
<productname>Postgres</productname> does not have nested transactions.
|
||||||
</para>
|
</para>
|
||||||
</sect2>
|
</sect2>
|
||||||
|
|
||||||
|
@ -146,8 +157,8 @@ END;
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
All variables, rows and records used in a block or its
|
All variables, rows and records used in a block or its
|
||||||
sub-blocks must be declared in the declarations section of a block
|
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
|
except for the loop variable of a FOR-loop iterating over a range
|
||||||
of integer values. Parameters given to a PL/pgSQL function are
|
of integer values. Parameters given to a PL/pgSQL function are
|
||||||
automatically declared with the usual identifiers $n.
|
automatically declared with the usual identifiers $n.
|
||||||
The declarations have the following syntax:
|
The declarations have the following syntax:
|
||||||
|
@ -439,7 +450,11 @@ CREATE FUNCTION logfunc2 (text) RETURNS timestamp AS '
|
||||||
SELECT INTO <replaceable>target</replaceable> <replaceable>expressions</replaceable> FROM ...;
|
SELECT INTO <replaceable>target</replaceable> <replaceable>expressions</replaceable> FROM ...;
|
||||||
</programlisting>
|
</programlisting>
|
||||||
<replaceable>target</replaceable> can be a record, a row variable or a
|
<replaceable>target</replaceable> can be a record, a row variable or a
|
||||||
comma separated list of variables and record-/row-fields.
|
comma separated list of variables and record-/row-fields. Note that
|
||||||
|
this is quite different from Postgres' normal interpretation of
|
||||||
|
SELECT INTO, which is that the INTO target is a newly created table.
|
||||||
|
(If you want to create a table from a SELECT result inside a PL/pgSQL
|
||||||
|
function, use the equivalent syntax CREATE TABLE AS SELECT.)
|
||||||
</para>
|
</para>
|
||||||
<para>
|
<para>
|
||||||
if a row or a variable list is used as target, the selected values
|
if a row or a variable list is used as target, the selected values
|
||||||
|
@ -508,8 +523,10 @@ PERFORM <replaceable>query</replaceable>
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The results from SELECT queries are discarded by EXECUTE unless
|
The results from SELECT queries are discarded by EXECUTE, and
|
||||||
SELECT INTO is used to save the results into a table.
|
SELECT INTO is not currently supported within EXECUTE. So, the
|
||||||
|
only way to extract a result from a dynamically-created SELECT
|
||||||
|
is to use the FOR ... EXECUTE form described later.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
|
@ -531,7 +548,7 @@ EXECUTE ''UPDATE tbl SET ''
|
||||||
<function>quote_literal()</function>. Both take the
|
<function>quote_literal()</function>. Both take the
|
||||||
appropriate steps to return the input text enclosed in single
|
appropriate steps to return the input text enclosed in single
|
||||||
or double quotes and with any embedded special characters
|
or double quotes and with any embedded special characters
|
||||||
intact.
|
properly escaped.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
@ -587,7 +604,7 @@ IF <replaceable>expression</replaceable> THEN
|
||||||
END IF;
|
END IF;
|
||||||
</programlisting>
|
</programlisting>
|
||||||
The <replaceable>expression</replaceable> must return a value that
|
The <replaceable>expression</replaceable> must return a value that
|
||||||
at least can be casted into a boolean type.
|
is a boolean or can be casted into a boolean.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
@ -635,9 +652,21 @@ FOR <replaceable>record | row</replaceable> IN <replaceable>select_clause</repla
|
||||||
END LOOP;
|
END LOOP;
|
||||||
</programlisting>
|
</programlisting>
|
||||||
The record or row is assigned all the rows resulting from the select
|
The record or row is assigned all the rows resulting from the select
|
||||||
clause and the statements executed for each. If the loop is terminated
|
clause and the loop body is executed for each row. If the loop is
|
||||||
with an EXIT statement, the last assigned row is still accessible
|
terminated with an EXIT statement, the last assigned row is still
|
||||||
after the loop.
|
accessible after the loop.
|
||||||
|
<programlisting>
|
||||||
|
[<<label>>]
|
||||||
|
FOR <replaceable>record | row</replaceable> IN EXECUTE <replaceable>text_expression</replaceable> LOOP
|
||||||
|
<replaceable>statements</replaceable>
|
||||||
|
END LOOP;
|
||||||
|
</programlisting>
|
||||||
|
This is like the previous form, except that the source SELECT
|
||||||
|
statement is specified as a string expression, which is evaluated
|
||||||
|
and re-planned on each entry to the FOR loop. This allows the
|
||||||
|
programmer to choose the speed of a pre-planned query or the
|
||||||
|
flexibility of a dynamic query, just as with a plain EXECUTE
|
||||||
|
statement.
|
||||||
<programlisting>
|
<programlisting>
|
||||||
EXIT [ <replaceable>label</replaceable> ] [ WHEN <replaceable>expression</replaceable> ];
|
EXIT [ <replaceable>label</replaceable> ] [ WHEN <replaceable>expression</replaceable> ];
|
||||||
</programlisting>
|
</programlisting>
|
||||||
|
|
Loading…
Reference in New Issue