Update refcursor documentation with examples of how to return pl/pgsql

refcursors.

diff --git a/doc/src/sgml/plsql.sgml b/doc/src/sgml/plsql.sgml
index 8e87b41d9b7d111e7e7c516f3a878f42da75ec5a..72298da8e3962b88c5ccb1853ff4218a93e538e6 100644 (file)
--- a/doc/src/sgml/plsql.sgml
+++ b/doc/src/sgml/plsql.sgml
@@ -1,5 +1,5 @@
 
 
  
@@ -762,7 +762,7 @@ CREATE FUNCTION logfunc2 (TEXT) RETURNS TIMESTAMP AS '
     
      If the expression's result data type doesn't match the variable's
      data type, or the variable has a specific size/precision
-     (as for char(20)), the result value will be implicitly
+     (like char(20)), the result value will be implicitly
      converted by the PL/pgSQL interpreter using
      the result type's output-function and 
      the variable type's input-function. Note that this could potentially
@@ -880,7 +880,7 @@ PERFORM query;
      This executes a SELECT
      query and discards the
      result. PL/pgSQL variables are substituted
-     into the query as usual.
+     in the query as usual.
     
 
     
@@ -927,7 +927,7 @@ EXECUTE query-string;
     
      Note in particular that no substitution of PL/pgSQL
      variables is done on the query string.  The values of variables must
-     be inserted into the query string as it is constructed.
+     be inserted in the query string as it is constructed.
     
 
     
@@ -1441,16 +1441,16 @@ END LOOP;
    Cursors
 
    
-    Rather than executing a whole query at once, it is possible to
-    set up a cursor that encapsulates the query, and
-    then read the query result a few rows at a time.  One reason
-    for doing this is to avoid memory overrun when the result contains
-    a large number of rows.  (However, PL/pgSQL users
-    don't normally need to worry about that, since FOR loops automatically
-    use a cursor internally to avoid memory problems.)  A more interesting
-    possibility is that a function can return a reference to a cursor
-    that it has set up, allowing the caller to read the rows.  This
-    provides one way of returning a row set from a function.
+    Rather than executing a whole query at once, it is possible to set
+    up a cursor that encapsulates the query, and then read
+    the query result a few rows at a time. One reason for doing this is
+    to avoid memory overrun when the result contains a large number of
+    rows. (However, PL/pgSQL users don't normally need
+    to worry about that, since FOR loops automatically use a cursor
+    internally to avoid memory problems.) A more interesting usage is to
+    return a reference to a cursor that it has created, allowing the
+    caller to read the rows. This provides one way of returning multiple
+    rows and columns from a function.
    
    
    
@@ -1498,11 +1498,10 @@ DECLARE
 
     
      Before a cursor can be used to retrieve rows, it must be
-     opened.  (This is the equivalent action to
-     the SQL command DECLARE CURSOR.)
-     PL/pgSQL has four forms of the OPEN statement,
-     two of which are for use with unbound cursor variables
-     and the other two for use with bound cursor variables.
+     opened. (This is the equivalent action to the SQL
+     command DECLARE CURSOR.) PL/pgSQL has
+     four forms of the OPEN statement, two of which use unbound cursor
+     variables and the other two use bound cursor variables.
     
 
     
@@ -1518,7 +1517,7 @@ OPEN unbound-cursor FOR SELECT ...;
    have been declared as an unbound cursor (that is, as a simple
    refcursor variable).  The SELECT query is treated
    in the same way as other SELECTs in PL/pgSQL:
-   PL/pgSQL variable names are substituted for,
+   PL/pgSQL variable names are substituted,
    and the query plan is cached for possible re-use.
 
 
@@ -1539,8 +1538,8 @@ OPEN unbound-cursor FOR EXECUTE 
    to execute.  The cursor cannot be open already, and it must
    have been declared as an unbound cursor (that is, as a simple
    refcursor variable).  The query is specified as a
-   string expression in the same way as for the EXECUTE command.
-   As usual, this gives flexibility for the query to vary
+   string expression in the same way as in the EXECUTE command.
+   As usual, this gives flexibility so the query can vary
    from one run to the next.
 
 
@@ -1562,7 +1561,7 @@ OPEN bound-cursor  ( argument_
    The 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
-   into the query.
+   in the query.
    The query plan for a bound cursor is always considered
    cacheable --- there is no equivalent of EXECUTE in this case.
 
@@ -1593,7 +1592,7 @@ OPEN curs3(42);
     
 
     
-     All Portals are implicitly closed at end of transaction.  Therefore
+     All Portals are implicitly closed at transaction end.  Therefore
      a refcursor value is useful to reference an open cursor
      only until the end of the transaction.
     
@@ -1608,7 +1607,7 @@ FETCH cursor INTO target;
 
         FETCH retrieves the next row from the cursor into a target,
    which may be a row variable, a record variable, or a comma-separated
-   list of simple variables, just as for SELECT INTO.  As with
+   list of simple variables, just like SELECT INTO.  As with
    SELECT INTO, the special variable FOUND may be checked to see
    whether a row was obtained or not.
 
@@ -1633,6 +1632,70 @@ CLOSE cursor;
 
 
 CLOSE curs1;
+
+       
+     
+ 
+    
+     Returning Cursors
+
+       
+
+        PL/pgSQL functions can return cursors to the
+        caller. This is used to return multiple rows or columns from the
+        function. The function opens the cursor and returns the cursor
+        name to the caller. The caller can then FETCH rows from the
+        cursor. The cursor can be CLOSEd by the caller, or it will be
+        closed automatically when the transaction closes.
+
+       
+
+       
+        The cursor name returned by the function can be specified by the
+        caller or automatically generated. The following example shows
+        how a cursor name can be supplied by the caller:
+
+
+CREATE TABLE test (col text);
+INSERT INTO test VALUES ('123');
+
+CREATE FUNCTION reffunc(refcursor) RETURNS refcursor AS '
+BEGIN
+        OPEN $1 FOR SELECT col FROM test;
+        RETURN $1;
+END;
+' LANGUAGE 'plpgsql';
+
+BEGIN;
+SELECT reffunc('funccursor');
+FETCH ALL IN funccursor;
+COMMIT;
+
+       
+
+       
+        The following example uses automatic cursor name generation:
+         
+
+CREATE FUNCTION reffunc2() RETURNS refcursor AS '
+DECLARE
+        ref refcursor;
+BEGIN
+        OPEN ref FOR SELECT col FROM test;
+        RETURN ref;
+END;
+' LANGUAGE 'plpgsql';
+
+BEGIN;
+SELECT reffunc2();
+  
+        reffunc2      
+  --------------------
+   
+  (1 row)
+
+FETCH ALL IN "";
+COMMIT;