Updated documentation with the latest FUNCTION stuff.

Docs/sp-imp-spec.txt

@@ -2,9 +2,6 @@
 	      Implementation specification for Stored Procedures
 	      ==================================================
 
-This is a first draft, only covering the basics for parsing, creating, and
-calling a PROCEDURE.
-
 
 - How parsing and execution of queries work
 
@@ -436,21 +433,37 @@ calling a PROCEDURE.
 
       // Return the "out" index for slot 'idx'
       int get_oindex(uint idx);
+
+      // Set the FUNCTION result
+      void set_result(Item *i);
+
+      // Get the FUNCTION result
+      Item *get_result();
     }
 
 
     - The procedure: sp_head.h
 
+      #define TYPE_ENUM_FUNCTION  1
+      #define TYPE_ENUM_PROCEDURE 2
+
       class sp_head
       {
+        int m_type;		// TYPE_ENUM_FUNCTION or TYPE_ENUM_PROCEDURE
+
         sp_head(LEX_STRING *name, LEX*);
 
         // Store this procedure in the database. This is a wrapper around
         // the function sp_create_procedure().
         int create(THD *);
 
-        // CALL this procedure.
-        int execute(THD *);
+	// Invoke a FUNCTION
+	int
+	execute_function(THD *thd, Item **args, uint argcount, Item **resp);
+
+	// CALL a PROCEDURE
+	int
+	execute_procedure(THD *thd, List<Item> *args);
 
         // Add the instruction to this procedure.
         void add_instr(sp_instr *);
@@ -524,7 +537,7 @@ calling a PROCEDURE.
 	  // 'dest' is the destination instruction index.
 	  sp_instr_jump(uint ip, uint dest);
 
-	  virtual int execute(THD *, uint *nextp);
+	  int execute(THD *, uint *nextp);
 
 	  // Set the destination instruction 'dest'.
 	  void set_destination(uint dest);
@@ -542,10 +555,28 @@ calling a PROCEDURE.
 	  int execute(THD *, uint *nextp);
         }
 
+      - Return a function value
+        class sp_instr_return : public sp_instr
+	{
+	  // Return the value 'val'
+	  sp_instr_return(uint ip, Item *val, enum enum_field_types type);
+	  
+	  int execute(THD *thd, uint *nextp);
+	}
+
+
     - Utility functions: sp.h
 
+      #define SP_OK                 0
+      #define SP_KEY_NOT_FOUND     -1
+      #define SP_OPEN_TABLE_FAILED -2
+      #define SP_WRITE_ROW_FAILED  -3
+      #define SP_DELETE_ROW_FAILED -4
+      #define SP_GET_FIELD_FAILED  -5
+      #define SP_PARSE_ERROR       -6
+
       // Finds a stored procedure given its name. Returns NULL if not found.
-      sp_head *sp_find(THD *, Item_string *name);
+      sp_head *sp_find_procedure(THD *, LEX_STRING *name);
 
       // Store the procedure 'name' in the database. 'def' is the complete
       // definition string ("create procedure ...").
@@ -554,6 +585,18 @@ calling a PROCEDURE.
 			      char *def, uint deflen);
 
       // Drop the procedure 'name' from the database.
-      int sp_drop(THD *, char *name, uint namelen);
+      int sp_drop_procedure(THD *, char *name, uint namelen);
+
+      // Finds a stored function given its name. Returns NULL if not found.
+      sp_head *sp_find_function(THD *, LEX_STRING *name);
+
+      // Store the function 'name' in the database. 'def' is the complete
+      // definition string ("create function ...").
+      int sp_create_function(THD *,
+                             char *name, uint namelen,
+			     char *def, uint deflen);
+
+      // Drop the function 'name' from the database.
+      int sp_drop_function(THD *, char *name, uint namelen);
 
 --

Docs/sp-implemented.txt

-Stored Procedures implemented 2003-02-02:
+Stored Procedures implemented 2003-03-07:
 
 
 Summary of Not Yet Implemented:
 
-  - Routine characteristics
+  - SQL queries (like SELECT, INSERT, UPDATE etc) in FUNCTION bodies
   - External languages
   - Access control
+  - Routine characteristics (mostly used for external languages)
   - Prepared SP caching; SPs are fetched and reparsed at each call
   - SQL-99 COMMIT (related to BEGIN/END)
   - DECLARE CURSOR ...
   - FOR-loops (as it requires cursors)
   - CASCADE/RESTRICT for ALTER and DROP
   - ALTER/DROP METHOD (as it implies User Defined Types)
+  - CONDITIONs, HANDLERs, SIGNAL and RESIGNAL (will probably not be implemented)
 
 
 Summary of what's implemented:
 
-  - SQL PROCEDURES (CREATE/DROP)
+  - SQL PROCEDUREs/FUNCTIONs (CREATE/DROP)
   - CALL
   - DECLARE of local variables
   - BEGIN/END, SET, CASE, IF, LOOP, WHILE, REPEAT, ITERATE, LEAVE
   - SELECT INTO local variables
+  - "Non-query" FUNCTIONs only
 
 
 List of what's implemented:
@@ -52,7 +55,8 @@ List of what's implemented:
       Note: Multiple statements requires a client that can send bodies
             containing ";". This is handled in the CLI clients mysql and
 	    mysqltest with the "delimiter" command. Changing the end-of-query
-	    delimiter ";" to for instance "|" allows 
+	    delimiter ";" to for instance "|" allows ";" to be used in the
+	    routine body.
     - SET of local variables
       Implemented as part of the pre-existing SET syntax. This allows an
       extended syntax of "SET a=x, b=y, ..." where different variable types
@@ -65,6 +69,12 @@ List of what's implemented:
     - SELECT ... INTO local variables (as well as global session variables)
       is implemented. (Note: This is not SQL-99 feature, but common in other
       databases.)
+    - A FUNCTION can have flow control contructs, but must not contain
+      an SQL query, like SELECT, INSERT, UPDATE, etc. The reason is that it's
+      hard to allow this is that a FUNCTION is executed as part of another
+      query (unlike a PROCEDURE, which is called as a statement). The table
+      locking scheme used makes it difficult to allow "subqueries" during
+      FUNCTION invokation.
 
 
 Closed questions:
@@ -87,17 +97,3 @@ Open questions/issues:
     any type checking, since this is the way MySQL works. I still don't know
     if we should keep it this way, or implement type checking. Possibly we
     should have optional, uset-settable, type checking.
-
-  - FUNCTIONs do not work correctly in all circumstances yet.
-    For instance a function like:
-      create function s() returns int
-      begin
-        declare s int;
-        select sum(test.t.y) into s from test.t;
-        return s;
-      end
-    do not work. Invoking this in queries like "SELECT * FROM t2 WHERE x = s()"
-    will make things very complicated. And, in fact, even "SET @s=s()" and
-    "SELECT s()" fail, although the exact reasons in these cases are a bit
-    obscure; part of the problem might be the way the lex structure is
-    bit-copied (a not completely sound thing to do).