Documentation for CORE-4403 - Allow referencing cursors as record variables in PSQL.

doc/sql.extensions/README.cursor_variables.txt

@@ -0,0 +1,86 @@
+----------------
+Cursor variables
+----------------
+
+  Function:
+    Allow usage of explicit or implicit cursors without needing the use of INTO clause in FETCH and
+    FOR SELECT.
+    An explicit cursor automatically becomes a cursor variable.
+    An implicit cursor (FOR SELECT) needs the {AS CURSOR <name>} clause.
+
+  Author:
+	Adriano dos Santos Fernandes <adrianosf@gmail.com>
+    Dmitry Yemanov <dimitr@users.sf.net>
+
+  Syntax rules:
+    1) To unambiguously access a cursor variable, the cursor name should be prefixed by a colon.
+    2) A cursor variable may be accessed without a colon prefix, but in this case, depending on the
+       scope of contexts present in a query, the name may resolve to a query context intead of a
+       cursor.
+    3) It's allowed to use the colon prefix with trigger's NEW and OLD contexts.
+    4) Cursor variables are read-only.
+    5) A FOR SELECT without AS CURSOR needs the use of INTO, while with AS CURSOR it's not required,
+       but still allowed.
+
+  Examples:
+    1.
+       execute block returns (o char(31))
+       as
+         declare c cursor for (
+           select rdb$relation_name name
+             from rdb$relations
+         );
+       begin
+         open c;
+         while (1 = 1) do
+         begin
+           fetch c;
+
+           if (row_count = 0) then
+               leave;
+
+           o = :c.name;
+           suspend;
+         end
+
+         close c;
+       end
+
+    2.
+       execute block returns (o char(31))
+       as
+       begin
+         for select rdb$relation_name name
+               from rdb$relations
+             as cursor c
+         do
+         begin
+           o = :c.name;
+           suspend;
+         end
+       end
+
+    3.
+       execute block returns (o1 char(31), o2 char(31))
+       as
+       begin
+         for select rdb$relation_name
+               from rdb$relations
+               where rdb$relation_name = 'RDB$RELATIONS'
+             as cursor c
+         do
+         begin
+           for select :c.rdb$relation_name x1, -- prefixed, resolves to C cursor
+                      c.rdb$relation_name x2   -- unprefixed, resolved to this query rdb$relations (c)
+                 from rdb$relations c
+                 where rdb$relation_name = 'RDB$DATABASE'
+               as cursor d
+           do
+           begin
+             o1 = :d.x1;
+             o2 = :d.x2;
+             suspend;
+           end
+         end
+       end
+

doc/sql.extensions/README.cursors

@@ -11,8 +11,8 @@ PSQL cursors
   Syntax rules:
     DECLARE [VARIABLE] <cursor_name> [SCROLL | NO SCROLL] CURSOR FOR ( <select_statement> );
     OPEN <cursor_name>;
-    FETCH <cursor_name> INTO <var_name> [, <var_name> ...];
+    FETCH <cursor_name> [INTO <var_name> [, <var_name> ...]];
-    FETCH {NEXT | PRIOR | FIRST | LAST | ABSOLUTE <n> | RELATIVE <n>} FROM <cursor_name> INTO <var_name> [, <var_name> ...];
+    FETCH {NEXT | PRIOR | FIRST | LAST | ABSOLUTE <n> | RELATIVE <n>} FROM <cursor_name> [INTO <var_name> [, <var_name> ...]];
     CLOSE <cursor_name>;
     
   Example(s):
@@ -68,3 +68,4 @@ PSQL cursors
 
   See also:
     README.context_variables
+    README.cursor_variables.txt