Connection.h File Reference

Detailed Description

A Connection class represent a connection to a SQL database system.

A Connection is used to execute SQL statements and return the result. There are three ways to execute a SQL statement: Connection_execute() is used to execute SQL statements that does not return a result set. Such statements are INSERT, UPDATE or DELETE. Connection_executeQuery() is used to execute a SQL SELECT statement and return the result set. These methods can only handle values which can be expressed as C-strings. If you need to handle binary data, such as inserting a blob value into the database, use a PreparedStatement object to execute the SQL statement. The factory method Connection_prepareStatement() is used to obtain a PreparedStatement object.

If an error occurred during execution, the method Connection_getLastError() can be used to obtain a string describing the error. The method Connection_executeQuery() will return an empty ResultSet (not NULL) if the SQL statement did not return any values. NULL is only returned if an error occurred. A ResultSet lives until the next call to Connection_executeQuery() or until the Connection is returned to the Connection Pool.

Any SQL statement that changes the database (basically, any SQL command other than SELECT) will automatically start a transaction if one is not already in effect. Automatically started transactions are committed at the conclusion of the command.

Transactions can also be started manually using the Connection_beginTransaction() method. Such transactions usually persist until the next call to Connection_commit() or Connection_rollback(). A transaction will also ROLLBACK if the database is closed or if an error occurs. Nested transactions are not allowed.

See also:: ResultSet.h PreparedStatement.h

Defines

#define T Connection_T

Typedefs

typedef T * T

Functions

URL_T Connection_getURL (T C)

Returns this Connection URL.

void Connection_close (T C)

Return connection to the connection pool.

void Connection_setQueryTimeout (T C, int ms)

Sets the number of milliseconds the Connection should wait for a SQL statement to finish if the database is busy.

int Connection_getQueryTimeout (T C)

Retrieves the number of milliseconds the Connection will wait for a SQL statement object to execute.

void Connection_setMaxRows (T C, int max)

Sets the limit for the maximum number of rows that any ResultSet object can contain.

int Connection_getMaxRows (T C)

Retrieves the maximum number of rows that a ResultSet object produced by this Connection object can contain.

int Connection_beginTransaction (T C)

Start a transaction.

int Connection_commit (T C)

Makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by this Connection object.

int Connection_rollback (T C)

Undoes all changes made in the current transaction and releases any database locks currently held by this Connection object.

long long int Connection_lastRowId (T C)

Returns the value for the most recent INSERT statement into a table with an AUTO_INCREMENT or INTEGER PRIMARY KEY column.

long long int Connection_rowsChanged (T C)

Returns the number of rows that was inserted, deleted or modified by the last Connection_execute() statement.

int Connection_execute (T C, const char *sql,...)

Executes the given SQL statement, which may be an INSERT, UPDATE, or DELETE statement or an SQL statement that returns nothing, such as an SQL DDL statement.

ResultSet_T Connection_executeQuery (T C, const char *sql,...)

Executes the given SQL statement, which returns a single ResultSet object.

PreparedStatement_T Connection_prepareStatement (T C, const char *sql)

Creates a PreparedStatement object for sending parameterized SQL statements to the database.

const char * Connection_getLastError (T C)

This method can be used to obtain a string describing the last error that occurred.

int Connection_isSupported (const char *url)

Class method, test if the specified database system is supported by this library.

Define Documentation

#define T Connection_T

Typedef Documentation

typedef struct T* T

Function Documentation

URL_T Connection_getURL ( T C )

Returns this Connection URL.

Parameters:

C A Connection object

Returns:
This Connection URL

See also:
URL.h

void Connection_close ( T C )

Return connection to the connection pool.
The same as calling ConnectionPool_returnConnection() on a connection.
Parameters:

C A Connection object

void Connection_setQueryTimeout ( T C,

int ms

)

Sets the number of milliseconds the Connection should wait for a SQL statement to finish if the database is busy.
If the limit is exceeded, then the execute methods will return immediately with an error. The default timeout is 3 seconds.
Parameters:

C A Connection object

ms The query timeout limit in milliseconds; zero means there is no limit

int Connection_getQueryTimeout ( T C )

Retrieves the number of milliseconds the Connection will wait for a SQL statement object to execute.

Parameters:

C A Connection object

Returns:
The query timeout limit in milliseconds; zero means there is no limit

void Connection_setMaxRows ( T C,

int max

)

Sets the limit for the maximum number of rows that any ResultSet object can contain.
If the limit is exceeded, the excess rows are silently dropped.
Parameters:

C A Connection object

max the new max rows limit; 0 means there is no limit

int Connection_getMaxRows ( T C )

Retrieves the maximum number of rows that a ResultSet object produced by this Connection object can contain.
If this limit is exceeded, the excess rows are silently dropped.
Parameters:

C A Connection object

Returns:
the new max rows limit; 0 means there is no limit

int Connection_beginTransaction ( T C )

Start a transaction.

Parameters:

C A Connection object

Returns:
TRUE on sucess otherwise FALSE

int Connection_commit ( T C )

Makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by this Connection object.

Parameters:

C A Connection object

Returns:
TRUE on sucess otherwise FALSE

int Connection_rollback ( T C )

Undoes all changes made in the current transaction and releases any database locks currently held by this Connection object.

Parameters:

C A Connection object

Returns:
TRUE on sucess otherwise FALSE

long long int Connection_lastRowId ( T C )

Returns the value for the most recent INSERT statement into a table with an AUTO_INCREMENT or INTEGER PRIMARY KEY column.

Parameters:

C A Connection object

Returns:
The value of the rowid from the last insert statement

long long int Connection_rowsChanged ( T C )

Returns the number of rows that was inserted, deleted or modified by the last Connection_execute() statement.
If used with a transaction, this method should be called before commit is executed, otherwise 0 is returned.
Parameters:

C A Connection object

Returns:
The number of rows changed by the last (DIM) SQL statement

int Connection_execute ( T C,

const char * sql,

...

)

Executes the given SQL statement, which may be an INSERT, UPDATE, or DELETE statement or an SQL statement that returns nothing, such as an SQL DDL statement.
Several SQL statements can be used in the sql parameter string, each separated with the ; SQL statement separator character. Note, calling this method clears any previous ResultSets associated with the Connection.
Parameters:

C A Connection object

sql A SQL statement

Returns:
TRUE on success otherwise FALSE on error and the method Connection_getLastError() can be used to obtain the error string.

ResultSet_T Connection_executeQuery ( T C,

const char * sql,

...

)

Executes the given SQL statement, which returns a single ResultSet object.
You may only use one SQL statement with this method. This is different from the behavior of Connection_execute() which executes all SQL statements in its input string. If the sql parameter string contains more than one SQL statement, only the first statement is executed, the others are silently ignored. A ResultSet "lives" only until the next call to Connection_executeQuery(), Connection_execute() or until the Connection is returned to the Connection Pool. This means that Result Sets cannot be saved between queries.
Parameters:

C A Connection object

sql A SQL statement

Returns:
A ResultSet object that contains the data produced by the given query. If there was an error, NULL is returned and the method Connection_getLastError() can be used to obtain the error string.

See also:
ResultSet.h

PreparedStatement_T Connection_prepareStatement ( T C,

const char * sql

)

Creates a PreparedStatement object for sending parameterized SQL statements to the database.
The sql parameter may contain IN parameter placeholders. An IN placeholder is specified with a '?' character in the sql string. The placeholders are then replaced with actual values by using the PreparedStatement's setXXX methods. Only one SQL statement may be used in the sql parameter, this in difference to Connection_execute() which may take several statements. A PreparedStatement "lives" until the Connection is returned to the Connection Pool.
Parameters:

C A Connection object

sql a single SQL statement that may contain one or more '?' IN parameter placeholders

Returns:
a new PreparedStatement object containing the pre-compiled SQL statement or NULL if a database error occurred. If NULL was returned, the method Connection_getLastError() can be used to obtain the error string.

See also:
PreparedStatement.h

const char* Connection_getLastError ( T C )

This method can be used to obtain a string describing the last error that occurred.

Parameters:

C A Connection object

Returns:
A string explaining the last error

int Connection_isSupported ( const char * url )

Class method, test if the specified database system is supported by this library.
Clients may pass a full Connection URL, for example using URL_toString(), or for convenience only the protocol part of the URL. E.g. "mysql" or "sqlite".
Parameters:

url a database url string

Returns:
TRUE if supported otherwise FALSE


Defines
#define	T Connection_T
Typedefs
typedef T *	T
Functions
URL_T	Connection_getURL (T C)
	Returns this Connection URL.
void	Connection_close (T C)
	Return connection to the connection pool.
void	Connection_setQueryTimeout (T C, int ms)
	Sets the number of milliseconds the Connection should wait for a SQL statement to finish if the database is busy.
int	Connection_getQueryTimeout (T C)
	Retrieves the number of milliseconds the Connection will wait for a SQL statement object to execute.
void	Connection_setMaxRows (T C, int max)
	Sets the limit for the maximum number of rows that any ResultSet object can contain.
int	Connection_getMaxRows (T C)
	Retrieves the maximum number of rows that a ResultSet object produced by this Connection object can contain.
int	Connection_beginTransaction (T C)
	Start a transaction.
int	Connection_commit (T C)
	Makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by this Connection object.
int	Connection_rollback (T C)
	Undoes all changes made in the current transaction and releases any database locks currently held by this Connection object.
long long int	Connection_lastRowId (T C)
	Returns the value for the most recent INSERT statement into a table with an AUTO_INCREMENT or INTEGER PRIMARY KEY column.
long long int	Connection_rowsChanged (T C)
	Returns the number of rows that was inserted, deleted or modified by the last Connection_execute() statement.
int	Connection_execute (T C, const char *sql,...)
	Executes the given SQL statement, which may be an INSERT, UPDATE, or DELETE statement or an SQL statement that returns nothing, such as an SQL DDL statement.
ResultSet_T	Connection_executeQuery (T C, const char *sql,...)
	Executes the given SQL statement, which returns a single ResultSet object.
PreparedStatement_T	Connection_prepareStatement (T C, const char *sql)
	Creates a PreparedStatement object for sending parameterized SQL statements to the database.
const char *	Connection_getLastError (T C)
	This method can be used to obtain a string describing the last error that occurred.
int	Connection_isSupported (const char *url)
	Class method, test if the specified database system is supported by this library.