Support for MOVE in PL/PgSQL. Initial patch from Magnus, some improvements

by Pavel Stehule, and reviewed by Neil Conway.

doc/src/sgml/plpgsql.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/plpgsql.sgml,v 1.108 2007/04/28 23:54:58 neilc Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/plpgsql.sgml,v 1.109 2007/04/29 01:21:08 neilc Exp $ -->
 
 <chapter id="plpgsql"> 
   <title><application>PL/pgSQL</application> - <acronym>SQL</acronym> Procedural Language</title>
@@ -1522,6 +1522,13 @@ GET DIAGNOSTICS integer_var = ROW_COUNT;
                 true if it returns a row, false if no row is returned.
            </para>
           </listitem>
+          <listitem>
+           <para>
+                A <command>MOVE</> statement sets <literal>FOUND</literal>
+                true if it successfully repositions the cursor, false otherwise.
+           </para>
+          </listitem>
+
           <listitem>
            <para>
                 A <command>FOR</> statement sets <literal>FOUND</literal> true
@@ -2562,6 +2569,53 @@ FETCH curs1 INTO rowvar;
 FETCH curs2 INTO foo, bar, baz;
 FETCH LAST FROM curs3 INTO x, y;
 FETCH RELATIVE -2 FROM curs4 INTO x;
+</programlisting>
+       </para>
+     </sect3>
+
+    <sect3>
+     <title><literal>MOVE</></title>
+
+<synopsis>
+MOVE <optional> <replaceable>direction</replaceable> { FROM | IN } </optional> <replaceable>cursor</replaceable>;
+</synopsis>
+
+    <para>
+     <command>MOVE</command> repositions a cursor without retrieving
+     any data. <command>MOVE</command> works exactly like the
+     <command>FETCH</command> command, except it only positions the
+     cursor and does not return rows. As with <command>SELECT
+      INTO</command>, the special variable <literal>FOUND</literal> can
+     be checked to see whether the cursor was successfully
+     repositioned or not.
+    </para>
+
+    <para>
+     The <replaceable>direction</replaceable> clause can be any of the
+     variants allowed in the SQL <xref linkend="sql-move"
+     endterm="sql-move-title"> command except the ones that can move by
+     more than one row; namely, it can be
+     <literal>NEXT</>,
+     <literal>PRIOR</>,
+     <literal>FIRST</>,
+     <literal>LAST</>,
+     <literal>ABSOLUTE</> <replaceable>count</replaceable>,
+     <literal>RELATIVE</> <replaceable>count</replaceable>,
+     <literal>FORWARD</>, or
+     <literal>BACKWARD</>.
+     Omitting <replaceable>direction</replaceable> is the same
+     as specifying <literal>NEXT</>.
+     <replaceable>direction</replaceable> values that require moving
+     backward are likely to fail unless the cursor was declared or opened
+     with the <literal>SCROLL</> option.
+    </para>
+
+    <para>
+     Examples:
+<programlisting>
+MOVE curs1;
+MOVE LAST FROM curs3;
+MOVE RELATIVE -2 FROM curs4;
 </programlisting>
        </para>
      </sect3>

src/pl/plpgsql/src/gram.y

@@ -9,7 +9,7 @@
  *
  *
  * IDENTIFICATION
- *	  $PostgreSQL: pgsql/src/pl/plpgsql/src/gram.y,v 1.101 2007/04/28 23:54:59 neilc Exp $
+ *	  $PostgreSQL: pgsql/src/pl/plpgsql/src/gram.y,v 1.102 2007/04/29 01:21:09 neilc Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -125,7 +125,7 @@ static	void			 check_labels(const char *start_label,
 %type <stmt>	stmt_assign stmt_if stmt_loop stmt_while stmt_exit
 %type <stmt>	stmt_return stmt_raise stmt_execsql stmt_execsql_insert
 %type <stmt>	stmt_dynexecute stmt_for stmt_perform stmt_getdiag
-%type <stmt>	stmt_open stmt_fetch stmt_close stmt_null
+%type <stmt>	stmt_open stmt_fetch stmt_move stmt_close stmt_null
 
 %type <list>	proc_exceptions
 %type <exception_block> exception_sect
@@ -179,6 +179,7 @@ static	void			 check_labels(const char *start_label,
 %token	K_IS
 %token	K_LOG
 %token	K_LOOP
+%token	K_MOVE
 %token	K_NEXT
 %token	K_NOSCROLL
 %token	K_NOT
@@ -635,6 +636,8 @@ proc_stmt		: pl_block ';'
 						{ $$ = $1; }
 				| stmt_fetch
 						{ $$ = $1; }
+				| stmt_move
+						{ $$ = $1; }
 				| stmt_close
 						{ $$ = $1; }
 				| stmt_null
@@ -1478,6 +1481,19 @@ stmt_fetch		: K_FETCH lno opt_fetch_direction cursor_variable K_INTO
 						fetch->rec		= rec;
 						fetch->row		= row;
 						fetch->curvar	= $4->varno;
+						fetch->is_move	= false;
+
+						$$ = (PLpgSQL_stmt *)fetch;
+					}
+				;
+				
+stmt_move		: K_MOVE lno opt_fetch_direction cursor_variable ';'
+					{
+						PLpgSQL_stmt_fetch *fetch = $3;
+
+						fetch->lineno = $2;
+						fetch->curvar	= $4->varno;
+						fetch->is_move	= true;
 
 						$$ = (PLpgSQL_stmt *)fetch;
 					}

src/pl/plpgsql/src/pl_exec.c

@@ -8,7 +8,7 @@
  *
  *
  * IDENTIFICATION
- *	  $PostgreSQL: pgsql/src/pl/plpgsql/src/pl_exec.c,v 1.195 2007/04/19 16:33:24 tgl Exp $
+ *	  $PostgreSQL: pgsql/src/pl/plpgsql/src/pl_exec.c,v 1.196 2007/04/29 01:21:09 neilc Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -3114,7 +3114,8 @@ exec_stmt_open(PLpgSQL_execstate *estate, PLpgSQL_stmt_open *stmt)
 
 
 /* ----------
- * exec_stmt_fetch			Fetch from a cursor into a target
+ * exec_stmt_fetch			Fetch from a cursor into a target, or just
+ *                          move the current position of the cursor
  * ----------
  */
 static int
@@ -3163,6 +3164,8 @@ exec_stmt_fetch(PLpgSQL_execstate *estate, PLpgSQL_stmt_fetch *stmt)
 		exec_eval_cleanup(estate);
 	}
 
+	if (!stmt->is_move)
+	{
 		/* ----------
 		 * Determine if we fetch into a record or a row
 		 * ----------
@@ -3198,10 +3201,19 @@ exec_stmt_fetch(PLpgSQL_execstate *estate, PLpgSQL_stmt_fetch *stmt)
 		}
 
 		SPI_freetuptable(tuptab);
+	}
+	else
+	{
+		/* Move the cursor */
+		SPI_scroll_cursor_move(portal, stmt->direction, how_many);
+		n = SPI_processed;
 
-	return PLPGSQL_RC_OK;
+		/* Set the global FOUND variable appropriately. */
+		exec_set_found(estate, n != 0);
 	}
 
+	return PLPGSQL_RC_OK;
+}
 
 /* ----------
  * exec_stmt_close			Close a cursor

src/pl/plpgsql/src/pl_funcs.c

@@ -8,7 +8,7 @@
  *
  *
  * IDENTIFICATION
- *	  $PostgreSQL: pgsql/src/pl/plpgsql/src/pl_funcs.c,v 1.58 2007/03/18 05:36:49 neilc Exp $
+ *	  $PostgreSQL: pgsql/src/pl/plpgsql/src/pl_funcs.c,v 1.59 2007/04/29 01:21:09 neilc Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -493,6 +493,7 @@ static void dump_dynfors(PLpgSQL_stmt_dynfors *stmt);
 static void dump_getdiag(PLpgSQL_stmt_getdiag *stmt);
 static void dump_open(PLpgSQL_stmt_open *stmt);
 static void dump_fetch(PLpgSQL_stmt_fetch *stmt);
+static void dump_cursor_direction(PLpgSQL_stmt_fetch *stmt);
 static void dump_close(PLpgSQL_stmt_close *stmt);
 static void dump_perform(PLpgSQL_stmt_perform *stmt);
 static void dump_expr(PLpgSQL_expr *expr);
@@ -761,7 +762,11 @@ static void
 dump_fetch(PLpgSQL_stmt_fetch *stmt)
 {
 	dump_ind();
+	
+	if (!stmt->is_move)
+	{
 		printf("FETCH curvar=%d\n", stmt->curvar);
+		dump_cursor_direction(stmt);
 
 		dump_indent += 2;
 		if (stmt->rec != NULL)
@@ -775,7 +780,46 @@ dump_fetch(PLpgSQL_stmt_fetch *stmt)
 			printf("    target = %d %s\n", stmt->row->rowno, stmt->row->refname);
 		}
 		dump_indent -= 2;
+	}
+	else
+	{
+		printf("MOVE curvar=%d\n", stmt->curvar);
+		dump_cursor_direction(stmt);
+	}
+}
 
+static void
+dump_cursor_direction(PLpgSQL_stmt_fetch *stmt)
+{
+	dump_indent += 2;
+	dump_ind();
+	switch (stmt->direction)
+	{
+		case FETCH_FORWARD:
+			printf("    FORWARD ");
+			break;
+		case FETCH_BACKWARD:
+			printf("    BACKWARD ");
+			break;
+		case FETCH_ABSOLUTE:
+			printf("    ABSOLUTE ");
+			break;
+		case FETCH_RELATIVE:
+			printf("    RELATIVE ");
+			break;
+		default:
+			printf("??? unknown cursor direction %d", stmt->direction);
+	}
+	
+	if (stmt->expr)
+	{
+		dump_expr(stmt->expr);
+		printf("\n");
+	}
+	else
+		printf("%d\n", stmt->how_many);
+		
+	dump_indent -= 2;
 }
 
 static void
@@ -1067,3 +1111,4 @@ plpgsql_dumptree(PLpgSQL_function *func)
 	printf("\nEnd of execution tree of function %s\n\n", func->fn_name);
 	fflush(stdout);
 }
+

src/pl/plpgsql/src/plpgsql.h

@@ -8,7 +8,7 @@
  *
  *
  * IDENTIFICATION
- *	  $PostgreSQL: pgsql/src/pl/plpgsql/src/plpgsql.h,v 1.87 2007/04/16 17:21:23 tgl Exp $
+ *	  $PostgreSQL: pgsql/src/pl/plpgsql/src/plpgsql.h,v 1.88 2007/04/29 01:21:09 neilc Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -446,7 +446,7 @@ typedef struct
 
 
 typedef struct
-{								/* FETCH statement */
+{								/* FETCH or MOVE statement */
 	int			cmd_type;
 	int			lineno;
 	PLpgSQL_rec *rec;			/* target, as record or row */
@@ -455,6 +455,7 @@ typedef struct
 	FetchDirection direction;	/* fetch direction */
 	int			how_many;		/* count, if constant (expr is NULL) */
 	PLpgSQL_expr *expr;			/* count, if expression */
+	bool		is_move;		/* is this a fetch or move? */
 } PLpgSQL_stmt_fetch;
 
 

src/pl/plpgsql/src/scan.l

@@ -9,7 +9,7 @@
  *
  *
  * IDENTIFICATION
- *	  $PostgreSQL: pgsql/src/pl/plpgsql/src/scan.l,v 1.56 2007/04/16 17:21:23 tgl Exp $
+ *	  $PostgreSQL: pgsql/src/pl/plpgsql/src/scan.l,v 1.57 2007/04/29 01:21:09 neilc Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -142,6 +142,7 @@ into			{ return K_INTO;			}
 is				{ return K_IS;				}
 log				{ return K_LOG;				}
 loop			{ return K_LOOP;			}
+move			{ return K_MOVE;			}
 next			{ return K_NEXT;			}
 no{space}+scroll { return K_NOSCROLL;		}
 not				{ return K_NOT;				}

src/test/regress/expected/plpgsql.out

@@ -3023,4 +3023,31 @@ select * from sc_test();
            0
 (3 rows)
 
+create or replace function sc_test() returns setof integer as $$
+declare
+  c cursor for select * from generate_series(1, 10);
+  x integer;
+begin
+  open c;
+  loop
+      move relative 2 in c;
+      if not found then
+          exit;
+      end if;
+      fetch next from c into x;
+      if found then
+          return next x;
+      end if;
+  end loop;
+  close c;
+end;
+$$ language plpgsql;
+select * from sc_test();
+ sc_test 
+---------
+       3
+       6
+       9
+(3 rows)
+
 drop function sc_test();

src/test/regress/sql/plpgsql.sql

@@ -2511,4 +2511,27 @@ $$ language plpgsql;
 
 select * from sc_test();
 
+create or replace function sc_test() returns setof integer as $$
+declare
+  c cursor for select * from generate_series(1, 10);
+  x integer;
+begin
+  open c;
+  loop
+      move relative 2 in c;
+      if not found then
+          exit;
+      end if;
+      fetch next from c into x;
+      if found then
+          return next x;
+      end if;
+  end loop;
+  close c;
+end;
+$$ language plpgsql;
+
+select * from sc_test();
+
 drop function sc_test();
+