From 53e66c8a756537f3a324d12150e023f6185b247c Mon Sep 17 00:00:00 2001 From: prabatuty Date: Mon, 14 May 2007 15:34:08 +0000 Subject: [PATCH] Bug: 1718744 doxygen comments missing for SqlConnection, SqlStatement --- include/SqlConnection.h | 55 +++++++++++++++++++++++++++++-- include/SqlStatement.h | 86 ++++++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 134 insertions(+), 7 deletions(-) diff --git a/include/SqlConnection.h b/include/SqlConnection.h index 136a3e3d..8e4914ac 100644 --- a/include/SqlConnection.h +++ b/include/SqlConnection.h @@ -20,23 +20,72 @@ #ifndef SQLCONNECTION_H #define SQLCONNECTION_H #include + +/** +* @class SqlConnection +* +* @brief Represents a database connection to sql engine. +* All database operations shall be done within the context of the connection.
+* Application should first create object of this class for accessing the database.
+* Each connection has only one active transaction at any given point of time, all
+* operations which happen using this connection object will be done as part of that
+* transaction.
+*
+* Functionality:
+* 1.Connection Management (connect and disconnect)
+* 2.Transaction Management (start, commit, abort)
+*
+* Note:
+* SERIALIZABLE isolation level is not supported. +* @author Prabakaran Thirumalai +*/ class SqlConnection { Connection conn; public: - // Connection handling. + /** opens connection to the sql engine + * @param user username for authentication + * @param pass password for authentication + * @return DbRetVal + */ DbRetVal connect (char *user, char * pass) { return conn.open(user, pass); } + + /** closes connection to the database and releases all the resources + * @return DbRetVal + */ DbRetVal disconnect () { return conn.close(); } - // Transaction handling. + /** Commits active transaction. + * It makes all the changes made in the current transaction permanent and
+ * it also releases the locks held by the current transaction.
+ * After a transaction commits, application is required to start another
+ * transaction for further database operations. + * @return DbRetVal + */ DbRetVal commit() { return conn.commit(); } + + /** Aborts the active transaction. + * undo all the changes made in the current transaction and it also
+ * releases the locks held by the current transaction.
+ * After a transaction rollback, application is required to start another
+ * transaction for further database operations. + * @return DbRetVal + */ DbRetVal rollback() { return conn.rollback(); } + + /** Starts a transaction. + * The previous transaction should be either committed or rollback
+ * before beginTrans is called.
+ * Applications are required to start transaction before they attempt any
+ * database operation. + * @param isoLevel isolation level. Default is read committed. + * @return DbRetVal + */ DbRetVal beginTrans (IsolationLevel isoLevel = READ_COMMITTED) { return conn.startTransaction(isoLevel); } - Connection& getConnObject(){ return conn; } }; diff --git a/include/SqlStatement.h b/include/SqlStatement.h index 384b6ae9..8844821a 100644 --- a/include/SqlStatement.h +++ b/include/SqlStatement.h @@ -23,24 +23,102 @@ #include "Statement.h" #include "SqlConnection.h" +/** +* @class SqlStatement +* +* @brief Handle to the sql statement. +* It is used to execute queries and return the values from the database
+* Sql Statement is fed to the prepare method first and then it should be executed.
+* Functionality:
+* 1.Input values for insert statement
+* 2.Iterator for retrieving rows from the table
+* 3.Parameter support for performance.
+*
+* @author Prabakaran Thirumalai +*/ class SqlStatement { public: + /** Default constructor + */ SqlStatement(); + /** sets connection handle to be used for subsequent operations + * @param con SqlConnection* + */ void setConnection(SqlConnection *con); - DbRetVal prepare(char *); + /** compiles the sql statement. It calls the parser and tokenizes the statement + * into logical plan. This method sets the statement string which needs to be executed. + * free method needs to be called, if application wants to use the same handle to compile + * another sql statement. + * @param stmt sql statement string + * @returns DbRetVal + */ + DbRetVal prepare(char *stmt); + + /** executes the sql statement. For insert, update, delete queries execute performs the + * required operation on the table. + * For Select queries, application should call execute before they start fetching + * the values from the table.This starts scan on the table. + * @param rowsAffect number of rows affected by the sql statement + * @returns DbRetVal + */ DbRetVal execute(int &rowsAffect); + + /**fetches the next tuple from the result of the execution of sql select query. + * execute should be called before calling this method. Application buffer should be + * binded to get the tuple values. + * @returns void* NULL if there is no tuple. + */ void* fetch(); - DbRetVal bindParam(int, void*); - DbRetVal bindField(int, void*); + /** binds application buffer to the specified parameter position in the sql statement. + * This method should be called for all the parameters in the sql statement.If not + * execute will return error. + *
+ * @param pos position of the parameter in the statement + * @param val address of the application buffer. Memory should be allocated by + * the application before binding the buffer. + */ + DbRetVal bindParam(int pos, void*); + + /** binds application buffer to the specified field position of the projection list + * in the select query. This method should be called only for select queries. + * Before executing select queries, required fields must be binded first. + *
+ * @param pos position in the projection list + * @param val address of the application buffer. Memory should be allocated by + * the application before binding the buffer. + */ + DbRetVal bindField(int pos, void* val); + + /**Fres all the resources held for the sql statement. Needs to be called before calling prepare again on the same statement handle. + * @returns DbRetVal + */ DbRetVal free(); - + /**Retrieves the total number of projection fields in the statement + * @returns int no of projection fields + */ int noOfProjFields(); + + /**Retrieves the total number of parameters in the statement + * @returns int no of parameters + */ int noOfParamFields(); + + /**Retrieves the field info for the required projection field position in statement + * @param projPos int - projection field position + * @param info FieldInfo*& - OUT parameter + * @returns DbRetVal + */ DbRetVal getProjFldInfo(int projPos, FieldInfo *&info); + + /**Retrieves the field info for the required parameter position in statement + * @param projPos int - parameter position + * @param info FieldInfo*& - OUT parameter + * @returns DbRetVal + */ DbRetVal getParamFldInfo(int paramPos, FieldInfo *&info); private: -- 2.11.4.GIT