followup to handler cleanup

mysql-test/r/bdb.result:
  bug#4000
mysql-test/t/bdb.test:
  bug#4000
sql/sql_select.cc:
  cleanup

sql/examples/ha_example.h

@@ -14,7 +14,7 @@
   along with this program; if not, write to the Free Software
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA */
 
-/* 
+/*
   Please read ha_exmple.cc before reading this file.
   Please keep in mind that the example storage engine implements all methods
   that are required to be implemented. handler.h has a full list of methods
@@ -48,55 +48,68 @@ public:
   ha_example(TABLE *table): handler(table)
   {
   }
-  ~ha_example() 
+  ~ha_example()
   {
   }
   /* The name that will be used for display purposes */
-  const char *table_type() const { return "EXAMPLE"; } 
-  /* The name of the index type that will be used for display */
-  const char *index_type(uint inx) { return "NONE"; }
+  const char *table_type() const { return "EXAMPLE"; }
+  /*
+    The name of the index type that will be used for display
+    don't implement this method unless you really have indexes
+   */
+  const char *index_type(uint inx) { return "HASH"; }
   const char **bas_ext() const;
-  /* 
-    This is a list of flags that says what the storage engine 
+  /*
+    This is a list of flags that says what the storage engine
     implements. The current table flags are documented in
-    table_flags.
+    handler.h
   */
   ulong table_flags() const
   {
     return 0;
   }
-  /* 
-    This is a list of flags that says how the storage engine 
+  /*
+    This is a list of flags that says how the storage engine
     implements indexes. The current index flags are documented in
-    handler.h. If you do not implement indexes, just return zero 
+    handler.h. If you do not implement indexes, just return zero
     here.
   */
-  ulong index_flags(uint inx) const
+  ulong index_flags(uint inx, uint part) const
   {
     return 0;
   }
-  /* 
+  /*
     unireg.cc will call the following to make sure that the storage engine can
     handle the data it is about to send.
+
+    Return *real* limits of your storage engine here. MySQL will do
+    min(your_limits, MySQL_limits) automatically
+
+    There is no need to implement ..._key_... methods if you don't suport
+    indexes.
   */
-  uint max_record_length() const { return HA_MAX_REC_LENGTH; }
-  uint max_keys()          const { return 0; }
-  uint max_key_parts()     const { return 0; }
-  uint max_key_length()    const { return 0; }
+  uint max_supported_record_length() const { return HA_MAX_REC_LENGTH; }
+  uint max_supported_keys()          const { return 0; }
+  uint max_supported_key_parts()     const { return 0; }
+  uint max_supported_key_length()    const { return 0; }
   /*
     Called in test_quick_select to determine if indexes should be used.
   */
   virtual double scan_time() { return (double) (records+deleted) / 20.0+10; }
-  /* 
+  /*
     The next method will never be called if you do not implement indexes.
   */
   virtual double read_time(ha_rows rows) { return (double) rows /  20.0+1; }
 
-  /* 
+  /*
     Everything below are methods that we implment in ha_example.cc.
+
+    Most of these methods are not obligatory, skip them and
+    MySQL will treat them as not implemented
   */
-  int open(const char *name, int mode, uint test_if_locked);
-  int close(void);
+  int open(const char *name, int mode, uint test_if_locked);    // required
+  int close(void);                                              // required
+
   int write_row(byte * buf);
   int update_row(const byte * old_data, byte * new_data);
   int delete_row(const byte * buf);
@@ -108,21 +121,32 @@ public:
   int index_prev(byte * buf);
   int index_first(byte * buf);
   int index_last(byte * buf);
-  int rnd_init(bool scan=1);
-  int rnd_next(byte *buf);
-  int rnd_pos(byte * buf, byte *pos);
-  void position(const byte *record);
-  void info(uint);
+  /*
+    unlike index_init(), rnd_init() can be called two times
+    without rnd_end() in between (it only makes sense if scan=1).
+    then the second call should prepare for the new table scan
+    (e.g if rnd_init allocates the cursor, second call should
+    position it to the start of the table, no need to deallocate
+    and allocate it again
+  */
+  int rnd_init(bool scan);                                      //required
+  int rnd_end();
+  int rnd_next(byte *buf);                                      //required
+  int rnd_pos(byte * buf, byte *pos);                           //required
+  void position(const byte *record);                            //required
+  void info(uint);                                              //required
+
   int extra(enum ha_extra_function operation);
   int reset(void);
-  int external_lock(THD *thd, int lock_type);
+  int external_lock(THD *thd, int lock_type);                   //required
   int delete_all_rows(void);
   ha_rows records_in_range(uint inx, key_range *min_key,
                            key_range *max_key);
   int delete_table(const char *from);
   int rename_table(const char * from, const char * to);
-  int create(const char *name, TABLE *form, HA_CREATE_INFO *create_info);
+  int create(const char *name, TABLE *form,
+             HA_CREATE_INFO *create_info);                      //required
 
   THR_LOCK_DATA **store_lock(THD *thd, THR_LOCK_DATA **to,
-                             enum thr_lock_type lock_type);
+                             enum thr_lock_type lock_type);     //required
 };