MySQL client API wrapper and support class. More...

#include <CMySQL.h>

Public Member Functions
	CMySQL ()
	This is the constructor for the CMySQL class. This class was designed to wrap the functions, and in some cases simplify the use of the mysql client api.
	~CMySQL ()
	This is the destructor for the CMySQL class.
const char *	GetClientInfo ()
	This routine returns the character string representing the MySQL library version.
BOOL	Connect (const char host=NULL, const char user=NULL, const char passwd=NULL, const char db=NULL, uint port=0, const char *usock=NULL, uint clflag=0)
	This routine attempts to connect to a MySQL server.
BOOL	Close (BOOL bInit)
	This routine returns the character string representing the MySQL library version.
BOOL	Init ()
	This routine Initializes the mysql structure.
BOOL	SelectDB (const char *db)
	This routine Causes the database *db to be the default database.
const char *	Stat ()
	This routine returns the character string representing the MySQL library version.
BOOL	Query (char *str)
	This routine executes an SQL query. Do not use this routine if the data is binary. Also do not include a simicolon or \g.
BOOL	RealQuery (char *str, uint len)
	This routine executes an SQL query. Do not use this routine if the data is binary. Also do not include a simicolon or \g.
BOOL	CreateDatabase (const char *db)
	This routine creates a database for the current user.
BOOL	DropDatabase (const char *db)
	This routine deletes a database for the current user.
int	GetAffectedRows ()
	This routine returns the number of affected rows (changed) by the the last 'UPDATE', 'DELETE', or 'INSERT' statements. For the 'SELECT' statement it returns the number of rows in the table.
MYSQL_RES *	StoreResult ()
	You must call StoreResult() or UseResult() for every query which successfully retrieves data ('SELECT', 'SHOW', 'DESCRIBE', 'EXPLAIN').
MYSQL_RES *	UseResult ()
	You must call StoreResult() or UseResult() for every query which successfully retrieves data ('SELECT', 'SHOW', 'DESCRIBE', 'EXPLAIN').
MYSQL_ROW	FetchRow (MYSQL_RES *res)
	Retrieves the next row from the result set.
void	FreeResult (MYSQL_RES *res)
	Frees the memory allocated for a result set by StoreResult(), UseResult(), ListDBs(), etc,.
int	NumRows (MYSQL_RES *res)
	This function returns the number of rows in the result set.
int	NumFields (MYSQL_RES *res)
	Get number of fields in result.
void	DataSeek (MYSQL_RES *result, ulong offset)
	This routine seeks to an arbitrary row in a query result set.
void	DataSeek (ulong offset)
	This routine seeks to an arbitrary row in a query result set.
const char *	GetError ()
	Returns the error message for the most recently invoked MySQL function.
uint	GetErrno ()
	Returns the error number for the most recently invoked MySQL function.
BOOL	CreateTable (const char name, struct SFieldInfo *sinfo)
	This routine creates a table.
BOOL	CreateTable (struct STableInfo *table)
	This routine creates a table.
MYSQL_RES *	ListTables (const char *wild=NULL)
	This routine returns a result set consisting of table names in the current database that match the simple regular expression specified by the wild parameter. Wild may contain the wildcard characters '' or '_', or may be a NULL pointer to match all tables. Calling ListTables() is the same as executing the Query "SHOW ALL TABLES [LIKE WILD]".
BOOL	TableExists (const char *name)
	This routine checks to see if the table specified exists in the current database.
BOOL	TableExists (struct STableInfo *table)
	This routine checks to see if the table specified exists in the current database.
BOOL	DropTable (const char *name, BOOL bCascade=FALSE, BOOL bRestrict=FALSE)
	This routine deletes a table.
BOOL	DropTable (struct STableInfo *table, BOOL bCascade=FALSE, BOOL bRestrict=FALSE)
	This routine deletes a table.
BOOL	InsertRow (const char name, struct SFieldInfo sinfo, const char Values)
	This routine inserts a row of data into the Table.
BOOL	InsertRow (struct STableInfo table, const char Values, int ValSize)
	This routine inserts a row of data into the Table.
long	GetTotalCount (struct STableInfo *table)
	This function queries the total number of records in a Table.

Private Attributes
MYSQL	mysql
	This structure represents a handle to one database connection. It is used for almost all MySQL functions.
MYSQL_RES *	res
	This structure represents the result of a query that returns rows (SELECT, SHOW, DESCRIBE, EXPLAIN). The information returned from a query is called the result set in the remainder of this section.
BOOL	bConnected
	The class keeps track of whether or not we are currently connected to the Database for this instance of the class.
BOOL	bInitialized
	This is used to keep track to see if everything has been initialized.

Detailed Description

MySQL client API wrapper and support class.

Remarks: This class was defined to support using MySQL as the Database engine.

Constructor & Destructor Documentation

CMySQL::CMySQL ( )

This is the constructor for the CMySQL class. This class was designed to wrap the functions, and in some cases simplify the use of the mysql client api.

CMySQL::~CMySQL ( )

This is the destructor for the CMySQL class.

Member Function Documentation

BOOL CMySQL::Close ( BOOL bInit )

This routine returns the character string representing the MySQL library version.

Parameters:

bInit If True this routine will re-initialize the mysql structure after closing.

Returns:

TRUE if successful, FALSE if not.

Error Returns:

CR_COMMANDS_OUT_OF_SYNC	Commands were executed out of sync.
CR_SERVER_GONE_ERROR	The MySQL server has gone away.
CR_SERVER_LOST	The connection to the server was lost during the Query.
CR_UNKNOWN_ERROR	An unknown error occurred.

BOOL CMySQL::Connect	(	const char *	host = `NULL`,
		const char *	user = `NULL`,
		const char *	passwd = `NULL`,
		const char *	db = `NULL`,
		uint	port = `0`,
		const char *	usock = `NULL`,
		uint	clflag = `0`
	)

This routine attempts to connect to a MySQL server.

Parameters:

host Hostname or IP address of the Server, NULL means use localhost

user Username, NULL means use the username that's logged in calling this program.

passwd The password for user, don't encrypt this since the API will.

db The database to use when the connection is made, NULL means use default db.

port The port number used for the TCP/IP connection, 0 means to use default.

usock unix_socket for a pipe connection. NULL is used for non-pipe connections.

clflag

client_flag is usually 0 but can be set to any of the following:

CLIENT_FOUND_ROWS	Return the number of found (matched) rows. Not the number of affected rows.
CLIENT_NO_SCHEMA	Don't allow the 'db_name.tbl_name.col_name' syntax. This if for ODBC; it causes the parser to generate an error if you use that syntax, which is useful for trapping bugs in some ODBC programs.
CLIENT_COMPRESS	Use compression protocol.
CLIENT_ODBC	The client is an ODBC client. This changes mysqld to be more ODBC friendly.

Returns:

TRUE if successful, FALSE if not.

Error Returns:

CR_CONN_HOST_ERROR	Failed to connect to the MySQL server.
CR_CONNECTION_ERROR	Failed to connect to the local MySQL server.
CR_IPSOCK_ERROR	Failed to create an IP socket.
CR_OUT_OF_MEMORY	Out of memory.
CR_SOCKET_CREATE_ERROR	Failed to create a Unix socket.
CR_UNKNOWN_HOST	Failed to fine the IP address for the hostname.
CR_VERSION_ERROR	A protocol mismatch resulted from attempting to connect to a server with a client library that uses a different protocol version. This can happen if you use a very old client library to connect to connect to a new server that wasn't started with the '–old-protocol' option.
CR_NAMEDPIPEOPEN_ERROR	Failed to create a named pipe on Win32.
CR_NAMEDPIPEWAIT_ERROR	Failed to wait for a named pipe on Win32.
CR_NAMEDPIPESETSTATE_ERROR	Failed to get a pipe handler on Win32.

BOOL CMySQL::CreateDatabase ( const char * db )

This routine creates a database for the current user.

Parameters:

db	The database to create.

Returns:

TRUE if successful, FALSE if not.

Error Returns:

CR_COMMANDS_OUT_OF_SYNC	Commands were executed out of sync.
CR_SERVER_GONE_ERROR	The MySQL server has gone away.
CR_SERVER_LOST	The connection to the server was lost during the Query.
CR_UNKNOWN_ERROR	An unknown error occurred.

BOOL CMySQL::CreateTable	(	const char *	name,
		struct SFieldInfo **	sinfo
	)

This routine creates a table.

Parameters:

name	The table name to create.
sinfo	This is a pointer to the field information specifying each field that is used for this table.

Returns:

TRUE if successful, FALSE if not.

Error Returns:

CR_COMMANDS_OUT_OF_SYNC	Commands were executed out of sync.
CR_SERVER_GONE_ERROR	The MySQL server has gone away.
CR_SERVER_LOST	The connection to the server was lost during the Query.
CR_UNKNOWN_ERROR	An unknown error occurred.

BOOL CMySQL::CreateTable ( struct STableInfo * table )

inline

This routine creates a table.

Parameters:

table The table structure that contains all the information needed to create the Table.

Returns:

TRUE if successful, FALSE if not.

Error Returns:

CR_COMMANDS_OUT_OF_SYNC	Commands were executed out of sync.
CR_SERVER_GONE_ERROR	The MySQL server has gone away.
CR_SERVER_LOST	The connection to the server was lost during the Query.
CR_UNKNOWN_ERROR	An unknown error occurred.

void CMySQL::DataSeek	(	MYSQL_RES *	result,
		ulong	offset
	)

This routine seeks to an arbitrary row in a query result set.

Parameters:

result	Result handle returned by mysql_db_query() or mysql_query().
offset	This should be a value in the range from 0 to NumRows() - 1.

Note:: This requires that the result set structure contains the entire result of the query, so DataSeek() may be used in conjunction only with SoreResult(), now with UseResult().

void CMySQL::DataSeek ( ulong offset )

inline

This routine seeks to an arbitrary row in a query result set.

Parameters:

offset This should be a value in the range from 0 to NumRows() - 1.

Note:: This requires that the result set structure contains the entire result of the query, so DataSeek() may be used in conjunction only with SoreResult(), now with UseResult().

BOOL CMySQL::DropDatabase ( const char * db )

This routine deletes a database for the current user.

Parameters:

db	The database to delete.

Returns:

TRUE if successful, FALSE if not.

Error Returns:

CR_COMMANDS_OUT_OF_SYNC	Commands were executed out of sync.
CR_SERVER_GONE_ERROR	The MySQL server has gone away.
CR_SERVER_LOST	The connection to the server was lost during the Query.
CR_UNKNOWN_ERROR	An unknown error occurred.

BOOL CMySQL::DropTable	(	const char *	name,
		BOOL	bCascade = `FALSE`,
		BOOL	bRestrict = `FALSE`
	)

This routine deletes a table.

Parameters:

name	The table to create.
bCascade	Not used
bRestrict	Not used

Returns:

TRUE if successful, FALSE if not.

Error Returns:

CR_COMMANDS_OUT_OF_SYNC	Commands were executed out of sync.
CR_SERVER_GONE_ERROR	The MySQL server has gone away.
CR_SERVER_LOST	The connection to the server was lost during the Query.
CR_UNKNOWN_ERROR	An unknown error occurred.

BOOL CMySQL::DropTable	(	struct STableInfo *	table,
		BOOL	bCascade = `FALSE`,
		BOOL	bRestrict = `FALSE`
	)

inline

This routine deletes a table.

Parameters:

table	The table structure that contains all the information needed to drop the Table.
bCascade	Not used
bRestrict	Not used

Returns:

TRUE if successful, FALSE if not.

Error Returns:

CR_COMMANDS_OUT_OF_SYNC	Commands were executed out of sync.
CR_SERVER_GONE_ERROR	The MySQL server has gone away.
CR_SERVER_LOST	The connection to the server was lost during the Query.
CR_UNKNOWN_ERROR	An unknown error occurred.

MYSQL_ROW CMySQL::FetchRow ( MYSQL_RES * res )

Retrieves the next row from the result set.

Parameters:

res	Result handle returned by mysql_db_query() or mysql_query()

Note:: When used after StoreResult(), FetchRow() returns NULL when there are no more rows to retrieve. When used after UseResult() returns NULL when there are no more rows to retrieve or when an error occurred.

The number of values in the row is given by NumFields(). If row holds the return value from a call to FetchRow(), pointers to the values are accessed as row[0] to row[NumFields(result)-1]. NULL values in the rows are indicated by a NULL pointer.

The lengths of the fields values in the row may be obtained by calling FetchLengths(). Empty fields and NULL fields both have length of 0; You can distinguish the difference between the two by checking for a NULL pointer for the field pointer. If the field is NULL then the pointer is NULL otherwise it's empty.

Returns:

NULL if no more rows or an error occurred, or the MYSQL_ROW result pointer if successful.

Error Returns:

CR_SERVER_LOST	The connection to the server was lost during the Query.
CR_UNKNOWN_ERROR	An unknown error occurred.

void CMySQL::FreeResult ( MYSQL_RES * res )

Frees the memory allocated for a result set by StoreResult(), UseResult(), ListDBs(), etc,.

Parameters:

res	Result handle returned by mysql_db_query() or mysql_query()

Note:: When you are done with the result set, you must free the memory by calling FreeResult().

int CMySQL::GetAffectedRows ( )

This routine returns the number of affected rows (changed) by the the last 'UPDATE', 'DELETE', or 'INSERT' statements. For the 'SELECT' statement it returns the number of rows in the table.

Returns:: > 0 = The number of rows affected by the SQL statement. 0 = No matches with the 'WHERE' statement. -1 = An error occurred or for a 'SELECT' statement, this was called before StoreResult

const char * CMySQL::GetClientInfo ( )

This routine returns the character string representing the MySQL library version.

Returns:: A string containing the library version information.

uint CMySQL::GetErrno ( )

inline

Returns the error number for the most recently invoked MySQL function.

Note:: For the connection specified by mysql, mysql_errno() returns the error code for the most recently invoked API function that can succeed or fail. A return value of zero means that no error occurred. Client error message numbers are listed in the MySQL `errmsg.h' header file. Server error message numbers are listed in `mysqld_error.h'. In the MySQL source distribution you can find a complete list of error messages and error numbers in the file `Docs/mysqld_error.txt'. The server error codes also are listed at section 22 Error Handling in MySQL.; that some functions like mysql_fetch_row() don't set mysql_errno() if they succeed.

A rule of thumb is that all functions that have to ask the server for information will reset mysql_errno() if they succeed.

Returns:: An error code value for the last mysql_xxx() call, if it failed. zero means no error occurred.

const char* CMySQL::GetError ( )

inline

Returns the error message for the most recently invoked MySQL function.

Note:: For the connection specified by mysql, mysql_error() returns a null-terminated string containing the error message for the most recently invoked API function that failed. If a function didn't fail, the return value of mysql_error() may be the previous error or an empty string to indicate no error.

A rule of thumb is that all functions that have to ask the server for information will reset mysql_error() if they succeed.

Returns:: A null-terminated character string that describes the error. An empty string if no error occurred.

long CMySQL::GetTotalCount ( struct STableInfo * table )

This function queries the total number of records in a Table.

Parameters:

table This is the Table structure that contains all the details of the table we are querying.

Returns:: -1 if the query failed, otherwise the number of records that match this query.

BOOL CMySQL::Init ( )

This routine Initializes the mysql structure.

Returns:: TRUE if successful, FALSE if not.

Error Returns: Not enough memory is this function fails.

BOOL CMySQL::InsertRow	(	const char *	name,
		struct SFieldInfo **	sinfo,
		const char *	Values
	)

This routine inserts a row of data into the Table.

Parameters:

name	The table to insert the data into.
sinfo	This is a pointer to the field information specifying each field that is used for this table.
Values	This is the data that will be placed into this record.

Returns:

TRUE if successful, FALSE if not.

Error Returns:

CR_COMMANDS_OUT_OF_SYNC	Commands were executed out of sync.
CR_SERVER_GONE_ERROR	The MySQL server has gone away.
CR_SERVER_LOST	The connection to the server was lost during the Query.
CR_UNKNOWN_ERROR	An unknown error occurred.

BOOL CMySQL::InsertRow	(	struct STableInfo *	table,
		const char *	Values,
		int	ValSize
	)

inline

This routine inserts a row of data into the Table.

Parameters:

table	The table structure that contains all the information needed to perform this function.
Values	This is the data that will be placed into this record.
ValSize	Not used.

Returns:

TRUE if successful, FALSE if not.

Error Returns:

CR_COMMANDS_OUT_OF_SYNC	Commands were executed out of sync.
CR_SERVER_GONE_ERROR	The MySQL server has gone away.
CR_SERVER_LOST	The connection to the server was lost during the Query.
CR_UNKNOWN_ERROR	An unknown error occurred.

MYSQL_RES * CMySQL::ListTables ( const char * wild = NULL )

This routine returns a result set consisting of table names in the current database that match the simple regular expression specified by the wild parameter. Wild may contain the wildcard characters '' or '_', or may be a NULL pointer to match all tables. Calling ListTables() is the same as executing the Query "SHOW ALL TABLES [LIKE WILD]".

Parameters:

wild	The wildcard characters for the search.

Note:: You must call FreeResult() when you are done with the result.

Returns:

NULL if error, or the MYSQL_RES result pointer if successful.

Error Returns:

CR_COMMANDS_OUT_OF_SYNC	Commands were executed out of sync.
CR_SERVER_GONE_ERROR	The MySQL server has gone away.
CR_SERVER_LOST	The connection to the server was lost during the Query.
CR_UNKNOWN_ERROR	An unknown error occurred.

int CMySQL::NumFields ( MYSQL_RES * res )

Get number of fields in result.

Parameters:

res	Result handle returned by mysql_db_query() or mysql_query().

Returns:: The number of fields in a result set.

int CMySQL::NumRows ( MYSQL_RES * res )

This function returns the number of rows in the result set.

Parameters:

res	Result handle returned by mysql_db_query() or mysql_query()

Note:: The use of NumRows() depends on whether or not you use StoreResult() or UseResult() to return the result set. If you use ResultStore(), NumRows() may be called immediately. If you use ResultUse() NumRows() will not return the correct value until all the rows in the result set have been retreived.

Returns:: The number of rows in the result set.

BOOL CMySQL::Query ( char * str )

This routine executes an SQL query. Do not use this routine if the data is binary. Also do not include a simicolon or \g.

Parameters:

str	The query string to use.

Returns:

TRUE if successful, FALSE if not.

Error Returns:

CR_COMMANDS_OUT_OF_SYNC	Commands were executed out of sync.
CR_SERVER_GONE_ERROR	The MySQL server has gone away.
CR_SERVER_LOST	The connection to the server was lost during the Query.
CR_UNKNOWN_ERROR	An unknown error occurred.

BOOL CMySQL::RealQuery	(	char *	str,
		uint	len
	)

This routine executes an SQL query. Do not use this routine if the data is binary. Also do not include a simicolon or \g.

Parameters:

str	The query string to use.
len	The length of the query string (allowing the use of binary data when required).

Returns:

TRUE if successful, FALSE if not.

Error Returns:

CR_COMMANDS_OUT_OF_SYNC	Commands were executed out of sync.
CR_SERVER_GONE_ERROR	The MySQL server has gone away.
CR_SERVER_LOST	The connection to the server was lost during the Query.
CR_UNKNOWN_ERROR	An unknown error occurred.

BOOL CMySQL::SelectDB ( const char * db )

This routine Causes the database *db to be the default database.

Note:: This function will fail if the user cannot be authenticated for access to the database specified. If a MySQL server isn't already connected this routine will attempt to connect to the local server selecting the database specified.

Parameters:

db	The database to use.

Returns:

TRUE if successful, FALSE if not.

Error Returns:

CR_COMMANDS_OUT_OF_SYNC	Commands were executed out of sync.
CR_SERVER_GONE_ERROR	The MySQL server has gone away.
CR_SERVER_LOST	The connection to the server was lost during the Query.
CR_UNKNOWN_ERROR	An unknown error occurred.

const char * CMySQL::Stat ( )

This routine returns the character string representing the MySQL library version.

Returns:

The character string indicating the status of the server.

Error Returns:

CR_COMMANDS_OUT_OF_SYNC	Commands were executed out of sync.
CR_SERVER_GONE_ERROR	The MySQL server has gone away.
CR_SERVER_LOST	The connection to the server was lost during the Query.
CR_UNKNOWN_ERROR	An unknown error occurred.

MYSQL_RES * CMySQL::StoreResult ( )

You must call StoreResult() or UseResult() for every query which successfully retrieves data ('SELECT', 'SHOW', 'DESCRIBE', 'EXPLAIN').

Note:: StoreResult() reads the entire result of a query to the client, allocates a 'MySQL_RES' structure, and places the result into this structure.

An empty result set is returned if there are no rows returned. (An empty result set differs from a 'NULL' return value).

Once you have called StoreResult(), you may call NumRows() to find out how many rows are in the result set.

You can call FetchRow() to fetch rows from the result set, or RowSeek() and RowTell() to obtain or set the current row position within the result set.

You must call FreeResult() when you are done with the result.

Returns:

NULL if error, or the MYSQL_RES result pointer if successful.

Error Returns:

CR_COMMANDS_OUT_OF_SYNC	Commands were executed out of sync.
CR_SERVER_GONE_ERROR	The MySQL server has gone away.
CR_SERVER_LOST	The connection to the server was lost during the Query.
CR_UNKNOWN_ERROR	An unknown error occurred.

BOOL CMySQL::TableExists ( const char * name )

This routine checks to see if the table specified exists in the current database.

Parameters:

name	The table name to check against.

Returns:

TRUE if found, FALSE if not.

Error Returns:

CR_COMMANDS_OUT_OF_SYNC	Commands were executed out of sync.
CR_SERVER_GONE_ERROR	The MySQL server has gone away.
CR_SERVER_LOST	The connection to the server was lost during the Query.
CR_UNKNOWN_ERROR	An unknown error occurred.

BOOL CMySQL::TableExists ( struct STableInfo * table )

inline

This routine checks to see if the table specified exists in the current database.

Parameters:

table The table structure that contains all the information needed to check if the Table exists.

Returns:

TRUE if found, FALSE if not.

Error Returns:

CR_COMMANDS_OUT_OF_SYNC	Commands were executed out of sync.
CR_SERVER_GONE_ERROR	The MySQL server has gone away.
CR_SERVER_LOST	The connection to the server was lost during the Query.
CR_UNKNOWN_ERROR	An unknown error occurred.

MYSQL_RES * CMySQL::UseResult ( )

You must call StoreResult() or UseResult() for every query which successfully retrieves data ('SELECT', 'SHOW', 'DESCRIBE', 'EXPLAIN').

Note:: UseResult() initiates a result set retrieval but does not actually read the result set into the client like StoreResult() does. Instead, each row must be manually retrieved by making calls to FetchRow(). This reads the result of a query directly from the server without storing in a temporary table or local buffer, which is somewhat faster and uses less memory then StoreResult(). The client will only allocate memory for the current row and a communication buffer that may grow up to 'max_allowed_packets' bytes.

On the other hand, you shouldn't use UseResult() if you are doing alot of processing for each row on the client side, or if the output is being displayed to the user and they can hit ^S to stop the display. This will stop tie up the server and prevent other threads from updating any tables from which the data is fetched.

When using UseResult(), you must execute FetchRow() for until is returns a NULL value, otherwise the unfetched rows will be part of the result set for your next Query. The C API will give the error 'Commands of sync; You can't run this command now.' if you forget to do this.

You may not use DataSeek(), RowSeek(), RowTell(), NumRows(), or AffectedRows() with a result returned from UseResult(), nor may you issue other Queries until the UseResult() has finished. (However, you have fetched all the rows, NumRows() will accurately return the number of rows fetched).

You must call FreeResult() when you are done with the result.

Returns:

NULL if error, or the MYSQL_RES result pointer if successful.
Error Returns:

CR_COMMANDS_OUT_OF_SYNC	Commands were executed out of sync.
CR_SERVER_GONE_ERROR	The MySQL server has gone away.
CR_SERVER_LOST	The connection to the server was lost during the Query.
CR_UNKNOWN_ERROR	An unknown error occurred.

Member Data Documentation

BOOL CMySQL::bConnected

private

The class keeps track of whether or not we are currently connected to the Database for this instance of the class.

BOOL CMySQL::bInitialized

private

This is used to keep track to see if everything has been initialized.

MYSQL CMySQL::mysql

private

This structure represents a handle to one database connection. It is used for almost all MySQL functions.

MYSQL_RES* CMySQL::res

private

This structure represents the result of a query that returns rows (SELECT, SHOW, DESCRIBE, EXPLAIN). The information returned from a query is called the result set in the remainder of this section.

The documentation for this class was generated from the following files:

include/CMySQL.h
src/CMySQL.cpp

Public Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation