From d44367f80bdf85ba16a5c327e37e077a5a4f1caf Mon Sep 17 00:00:00 2001
From: dimitr <dimitr@users.sourceforge.net>
Date: Thu, 6 Jan 2005 18:32:22 +0000
Subject: [PATCH] Added some docs.

---
 doc/sql.extensions/README.cursors      | 65 ++++++++++++++++++++++++++
 doc/sql.extensions/README.leave_labels | 64 +++++++++++++++++++++++++
 2 files changed, 129 insertions(+)
 create mode 100644 doc/sql.extensions/README.cursors
 create mode 100644 doc/sql.extensions/README.leave_labels

diff --git a/doc/sql.extensions/README.cursors b/doc/sql.extensions/README.cursors
new file mode 100644
index 0000000000..f73a0ef575
--- /dev/null
+++ b/doc/sql.extensions/README.cursors
@@ -0,0 +1,65 @@
+---------------------
+PSQL cursors (FB 2.0)
+---------------------
+
+  Function:
+    Allows explicit cursor operations.
+
+  Author:
+    Dmitry Yemanov <dimitr@users.sf.net>
+
+  Syntax rules:
+    DECLARE [VARIABLE] <cursor_name> CURSOR FOR ( <select_statement> );
+    OPEN <cursor_name>;
+    FETCH <cursor_name> INTO <var_name> [, <var_name> ...];
+    CLOSE <cursor_name>;
+    
+  Example(s):
+    1. DECLARE C CURSOR FOR ( SELECT RDB$RELATION_NAME
+                              FROM RDB$RELATIONS );
+       BEGIN
+         OPEN C;
+         WHILE (1 = 1) DO
+         BEGIN
+           FETCH C INTO :RNAME;
+           IF (ROW_COUNT = 0) THEN
+             LEAVE;
+           SUSPEND;
+         END
+         CLOSE C;
+       END
+
+    2. DECLARE RNAME CHAR(31);
+       DECLARE FNAME CHAR(31);
+       DECLARE C CURSOR FOR ( SELECT RDB$FIELD_NAME
+                              FROM RDB$RELATION_FIELDS
+                              WHERE RDB$RELATION_NAME = :RNAME
+                              ORDER BY RDB$FIELD_POSITION );
+       BEGIN
+         FOR
+           SELECT RDB$RELATION_NAME
+           FROM RDB$RELATIONS
+           INTO :RNAME
+         DO
+         BEGIN
+           OPEN C;
+           FETCH C INTO :FNAME;
+           CLOSE C;
+           SUSPEND;
+         END
+       END
+
+  Note(s):
+    1. Cursor declaration is allowed only in the beginning of a PSQL block/procedure/trigger
+       (like a regular local variable declaration).
+    2. Cursor names are required to be unique in the given context. They cannot interfere
+       with FOR SELECT cursor (declared via the AS CURSOR clause) names. But a cursor can
+       share its name with any variable in this context, as possible operations are different.
+    3. Positioned updates and deletes with cursors using the WHERE CURRENT OF clause are allowed.
+    4. Attempts to fetch from or close a FOR SELECT cursor are prohibited.
+    5. Attempts to open cursor which is already open, as well as to fetch from or close cursor
+       which is already closed, will fail.
+    6. All cursors which were not explicitly closed will be closed automatically on exit of
+       the current PSQL block/procedure/trigger.
+    7. ROW_COUNT system variable can be used to check whether the last FETCH statement returned
+       any row.
diff --git a/doc/sql.extensions/README.leave_labels b/doc/sql.extensions/README.leave_labels
new file mode 100644
index 0000000000..d0410778db
--- /dev/null
+++ b/doc/sql.extensions/README.leave_labels
@@ -0,0 +1,64 @@
+----------------------------------------
+PSQL labels and LEAVE statement (FB 2.0)
+----------------------------------------
+
+  Function:
+    Allows to stop execution of the current block and unwind to the specified label.
+    After that execution continues from the statement following by the terminated loop statement.
+
+  Author:
+    Dmitry Yemanov <dimitr@users.sf.net>
+
+  Syntax rules:
+    <label_name>: <loop_statement>
+    ...
+    LEAVE [<label_name>]
+    
+    Where <loop_statement> is one of: WHILE, FOR SELECT, FOR EXECUTE STATEMENT
+
+  Example(s):
+    1. FOR
+         SELECT COALESCE(RDB$SYSTEM_FLAG, 0), RDB$RELATION_NAME
+         FROM RDB$RELATIONS
+         ORDER BY 1
+         INTO :RTYPE, :RNAME
+       DO
+       BEGIN
+         IF (RTYPE = 0) THEN
+           SUSPEND;
+         ELSE
+           LEAVE; -- exits current loop
+       END
+
+    2. CNT = 100;
+       L1:
+       WHILE (CNT >= 0) DO
+       BEGIN
+         IF (CNT < 50) THEN
+           LEAVE L1; -- exists WHILE loop
+         CNT = CNT - l;
+       END
+
+    3. STMT1 = 'SELECT RDB$RELATION_NAME FROM RDB$RELATIONS';
+       L1:
+       FOR
+         EXECUTE STATEMENT :STMT1 INTO :RNAME
+       DO
+       BEGIN
+         STMT2 = 'SELECT RDB$FIELD_NAME FROM RDB$RELATION_FIELDS WHERE RDB$RELATION_NAME = ';
+         L2:
+         FOR
+           EXECUTE STATEMENT :STMT2 || :RNAME INTO :FNAME
+         DO
+         BEGIN
+           IF (RNAME = 'RDB$DATABASE') THEN
+             LEAVE L1; -- exits the outer loop
+           ELSE IF (RNAME = 'RDB$RELATIONS') THEN
+             LEAVE L2; -- exits the inner loop
+           ELSE
+             SUSPEND;
+         END
+       END
+
+  Note(s):
+    LEAVE without explicit lable means interrupting the current (most inner) loop.