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

I threw in spell check run over the whole file.

doc/src/sgml/plsql.sgml

@@ -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
+    produces an internal binary instruction tree on the first time the
-    function is called by a backend. 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,
     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
+     There can be any number of sub-blocks in the statement section
-     of a block. Subblocks can be used to hide variables from outside a
+     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
+     All variables, rows and records used in a block or its
-     subblocks 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
      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>
@@ -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>
@@ -301,11 +301,11 @@ RENAME <replaceable>oldname</replaceable> TO <replaceable>newname</replaceable>;
      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>
@@ -752,7 +796,7 @@ EXIT [ <replaceable>label</replaceable> ] [ WHEN <replaceable>expression</replac
     </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.