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);
/**
_______________________________________________
Carob-commits mailing list
[email protected]
https://forge.continuent.org/mailman/listinfo/carob-commits
