From 0898d71f66ed884af726556ac9ffc8081dddc757 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Sat, 15 Oct 2011 13:02:37 -0400
Subject: [PATCH] Marginal improvements to documentation of plpgsql's OPEN
cursor statement.
Rearrange text to improve clarity, and add an example of implicit reference
to a plpgsql variable in a bound cursor's query. Byproduct of some work
I'd done on the "named cursor parameters" patch before giving up on it.
---
doc/src/sgml/plpgsql.sgml | 44 +++++++++++++++++++++++++--------------
1 file changed, 28 insertions(+), 16 deletions(-)
diff --git a/doc/src/sgml/plpgsql.sgml b/doc/src/sgml/plpgsql.sgml
index c14c34cd322..19c15ad26fc 100644
--- a/doc/src/sgml/plpgsql.sgml
+++ b/doc/src/sgml/plpgsql.sgml
@@ -2720,7 +2720,7 @@ END;
DECLARE
curs1 refcursor;
curs2 CURSOR FOR SELECT * FROM tenk1;
- curs3 CURSOR (key integer) IS SELECT * FROM tenk1 WHERE unique1 = key;
+ curs3 CURSOR (key integer) FOR SELECT * FROM tenk1 WHERE unique1 = key;
</programlisting>
All three of these variables have the data type <type>refcursor</>,
but the first can be used with any query, while the second has
@@ -2836,31 +2836,43 @@ OPEN <replaceable>bound_cursorvar</replaceable> <optional> ( <replaceable>argume
cursor cannot be open already. A list of actual argument value
expressions must appear if and only if the cursor was declared to
take arguments. These values will be substituted in the query.
+ </para>
+
+ <para>
The query plan for a bound cursor is always considered cacheable;
there is no equivalent of <command>EXECUTE</command> in this case.
- Notice that <literal>SCROLL</> and
- <literal>NO SCROLL</> cannot be specified, as the cursor's scrolling
+ Notice that <literal>SCROLL</> and <literal>NO SCROLL</> cannot be
+ specified in <command>OPEN</>, as the cursor's scrolling
behavior was already determined.
</para>
<para>
- Note that because variable substitution is done on the bound
- cursor's query, there are two ways to pass values into the cursor:
- either with an explicit argument to <command>OPEN</>, or
- implicitly by referencing a <application>PL/pgSQL</> variable
- in the query. However, only variables declared before the bound
- cursor was declared will be substituted into it. In either case
- the value to be passed is determined at the time of the
- <command>OPEN</>.
- </para>
-
- <para>
- Examples:
+ Examples (these use the cursor declaration examples above):
<programlisting>
OPEN curs2;
OPEN curs3(42);
</programlisting>
- </para>
+ </para>
+
+ <para>
+ Because variable substitution is done on a bound cursor's query,
+ there are really two ways to pass values into the cursor: either
+ with an explicit argument to <command>OPEN</>, or implicitly by
+ referencing a <application>PL/pgSQL</> variable in the query.
+ However, only variables declared before the bound cursor was
+ declared will be substituted into it. In either case the value to
+ be passed is determined at the time of the <command>OPEN</>.
+ For example, another way to get the same effect as the
+ <literal>curs3</> example above is
+<programlisting>
+DECLARE
+ key integer;
+ curs4 CURSOR FOR SELECT * FROM tenk1 WHERE unique1 = key;
+BEGIN
+ key := 42;
+ OPEN curs4;
+</programlisting>
+ </para>
</sect3>
</sect2>
--
GitLab