CVS update of libmysequoia/include (CarobStmt.hpp)

    Date: Monday, January 30, 2006 @ 12:16:05
  Author: zsolt
    Path: /cvsroot/carob/libmysequoia/include

Modified: CarobStmt.hpp (1.6 -> 1.7)

Introduced comments to each function and variable


---------------+
 CarobStmt.hpp |  153 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 153 insertions(+)


Index: libmysequoia/include/CarobStmt.hpp
diff -u libmysequoia/include/CarobStmt.hpp:1.6 
libmysequoia/include/CarobStmt.hpp:1.7
--- libmysequoia/include/CarobStmt.hpp:1.6      Tue Jan 17 09:38:38 2006
+++ libmysequoia/include/CarobStmt.hpp  Mon Jan 30 12:16:05 2006
@@ -34,45 +34,198 @@
 class CarobStmt : public CarobCommon
 {
 public:
+  /**
+   * Initialize and constructs the class. Allocate a MYSQL_STMT and initialize 
a Carob::ParameterStatement.
+   * @param mysql object (must be initialized with mysql_init)
+   */
   CarobStmt(MYSQL *mysql);
+  /**
+   * Free the allocated statement and resources used by it. Also delete Carob 
statement
+   */
        ~CarobStmt();
   
+  /**
+   * Executes the prepared statement. The parameter should be already bind to 
the statement, and
+   * prepare had to be called before.
+   * @return 1 if an error occured 
+   *         0 no error
+   */
   int execute();
+
+  /**
+   * Returns the next row in the result set. It can be called only while the 
result set exists; 
+   * that is, after a call to execute() that creates a result set or after 
store_result(), 
+   * to buffer the entire result set.
+   * fetch() returns row data using the buffers bound by bind_result(). It 
returns the data in those
+   * buffers for all the columns in the current row set and the lengths are 
returned to the length pointer. 
+   * Data conversion can occure if the fetched data is different to the buffer 
type.
+   * @return 1 if an error occured
+   *         0 no error
+   *         MYSQL_NO_DATA if there are no more data to fetch
+   *         MYSQL_DATA_TRUNCATED if a truncation occured while fetching
+   */
   int fetch();
+  
+  /**
+   * Fetch one column from the current result set row. This should be used 
only with character type results.
+   * @param bind provides the buffer where data should be placed. It should be 
set up the same way as for bind_result().
+   * @param column indicates which column to fetch. The first column is 
numbered 0.
+   * @param offset is the offset within the data value at which to begin 
retrieving data. 
+   *        This can be used for fetching the data value in pieces. The 
beginning of the value is offset 0.
+   * @return 1 if an error occured 
+   *         0 no error
+   */
   int fetch_column (MYSQL_BIND * bind, unsigned int column, unsigned long 
offset);
+  
+  /**
+   * Prepare the query to be executed. Fetch the metadata of the query. Sets 
the param count and result column.
+   * It destroy any previously prepared query within the same statement.
+   * @param query sql query needed to be prepared
+   * @param length length of the query
+   * @return 1 if an error occured
+   *         0 no error
+   */
   int prepare(const char *query, unsigned long length);
+  
+  /**
+   * Is used to bind data for the parameter markers in the SQL statement that 
was passed to prepare().
+   * It uses MYSQL_BIND structures to supply the data.
+   * @param bind is the address of an array of MYSQL_BIND structures. The 
library expects the array 
+   *              to contain an element for each â???â?? parameter marker that 
is present in the query.
+   * @return 1 if an error occured 
+   *         0 no error
+   */
   bool bind_param(const MYSQL_BIND *bind);
+
+  /** 
+   * It should allow an application to send parameter data to the server in 
pieces (or "chunks"). 
+   * But this implementation is only of an emulation of this feature, because 
the data is collected 
+   * in an internal buffer, concatenated and only at the execute() state is 
sent.
+   * If sequoia will support this "chunk" feeding, then this algorithm will 
change.
+   * @param parameter_number indicates which parameter to associate the data 
with. Parameters are 
+   *                          numbered beginning with 0. 
+   * @param data is a pointer to a buffer containing data to be sent
+   * @param length indicates the number of bytes in the buffer.
+   * @return 1 if an error occured 
+   *         0 no error
+   */
   bool send_long_data (unsigned int parameter_number, const char *data, 
unsigned long length);
+
+  /**
+   * Is used to associate (bind) columns in the result set to data buffers and 
length buffers. 
+   * When fetch() is called to fetch data, the data is placed into the 
specified buffers defined by
+   * the bound columns. Each column must be bound prior of calling fetch().
+   * @param bind is the address of an array of MYSQL_BIND structures. The 
library expects the array 
+   *              to contain an element for column in the result set.
+   * @return 1 if an error occured 
+   *         0 no error
+   */
   bool bind_result(const MYSQL_BIND *bind);
+
+  /**
+   * Reset the prepared statement to state after prepare.
+   * This is mainly used to reset data sent with send_long_data().
+   * @return 1 if an error occured 
+   *         0 no error
+   */
   bool reset();
   
+  /**
+   * Set the number of rows to fetch from sequoia. The number of rows will be 
present only at the next fetch(),
+   * and when the previous fetch buffer is exausted.
+   */
   void set_fetch_size(unsigned size) { if (c_stmt) c_stmt->setFetchSize(size); 
}
   
+  /**
+   * If a statement passed to prepare() is one that produces a result set, 
result_metadata() returns 
+   * the result set metadata in the form of a pointer to a MYSQL_RES structure 
that can be used to process 
+   * the meta information such as total number of fields and individual field 
information.
+   * @return pointer to a MYSQL_RES in case of success
+   *         0 in case of failure
+   */
   MYSQL_RES *result_metadata();
 
+  /**
+   * Buffers the entire resultset from the server in the client buffers. The 
result on the server is released.
+   * @return 1 if an error occured 
+   *         0 no error
+   */
   int store_result();
+
+  /**
+   * Releases memory associated with the result set produced by execution of 
the prepared statement.
+   * @return 1 if an error occured 
+   *         0 no error
+   */
   static bool free_result(MYSQL_STMT *stmt);
 
+  /**
+   * Return the pointer to the internal allocated MYSQL_STMT.
+   */
   MYSQL_STMT *getMYSQL_STMT() {return m_stmt;}
 
 private:
+  //Internal MYSQL_STMT associated with the statement
   MYSQL_STMT *m_stmt;
+  //Associated carob parameter statement
   CarobNS::ParameterStatement *c_stmt;
+  //Pointer to the CarobMYSQL from which this statement was created
   CarobMYSQL *cmysql;
+  //In case the result was not stored with store_result(), contain a pointer 
to the result set resulted by executing
+  //the statement with execute()
   CarobNS::DriverResultSet *liveResultSet;
 
+  /**
+   * Private constructor
+   */
+  CarobStmt() {}
+
+  /**
+   * Release memory, and structure. Also destroy carob parameter statement
+   */
   void clear();
 
+  /**
+   * Link the error, is_null, length fields to the internal ones, if one of 
them is null.
+   * @param bind pointer to a MYSQL_BIND structure
+   */
   void link_bind(MYSQL_BIND *bind);
 
+  /**
+   * Fetch one field either from internal buffer or from liveResultSet and 
store the converted result
+   * in the bind buffer. If truncation occures set the error in MYSQL_BIND
+   * @param fPtr pointer to a MYSQL_FIELD it is used to check the field type
+   * @param bPtr pointer to a MYSQL_BIND. it is used to store the result, and 
if the result type is not equal with
+   *             field type then a conversion is occured.
+   * @param colNo contains the column number starting from 0
+   */
   void fetch_field(MYSQL_FIELD *fPtr, MYSQL_BIND *bPtr, unsigned colNo);
 
+  /**
+   * Fetch from carob and allocate memory for the result of one field.
+   * @param fPtr pointer to a MYSQL_FIELD
+   * @param colNo contains the column number starting from 1
+   * @return the pointer to the allocated result. The result will be in it's 
original binary form. In case of 
+   *             characters the result will point to a string *
+   */
   void *alloc_fetch_field(MYSQL_FIELD *fPtr, unsigned colNo);
   
+  /**
+   * Release the memory allocated by alloc_fetch_field().
+   * @param fPtr pointer to a MYSQL_FIELD, needed to determine the field type
+   * @param buffer points to the data to be deleted.
+   */
   static void delete_fetch_field(MYSQL_FIELD *fPtr, void *buffer);
   
+  /**
+   * Free the internal cached buffer created when store_result() was called.
+   * @param stmt points to the statement which internal cached buffer should 
be released
+   */
   static void free_catched_result(MYSQL_STMT *stmt);
 
+  /**
+   * Free the long data created with send_long_data().
+   */
   static void free_long_data(MYSQL_STMT *m_stmt);
   
   /**