Macros | Typedefs | Functions
Connection.h File Reference

Detailed Description

A Connection represent a connection to a SQL database system.

Use a Connection to execute SQL statements. There are three ways to execute statements: 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 a 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.

The method Connection_executeQuery() will return an empty ResultSet (not null) if the SQL statement did not return any values. A ResultSet lives until the next call to Connection execute or until the Connection is returned to the Connection Pool. If an error occur during execution, an SQLException is thrown.

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 Connection_beginTransaction(). 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.

A Connection is reentrant, but not thread-safe and should only be used by one thread (at the time).

See also
ResultSet.h PreparedStatement.h SQLException.h

Macros

#define T   Connection_T
 

Typedefs

typedef struct Connection_S * T
 

Functions

int Connection_ping (T C)
 Ping the database server and return true if this Connection is alive, otherwise false in which case the Connection should be closed. More...
 
void Connection_clear (T C)
 Close any ResultSet and PreparedStatements in the Connection. More...
 
void Connection_close (T C)
 Return connection to the connection pool. More...
 
void Connection_beginTransaction (T C)
 Start a transaction. More...
 
void 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. More...
 
void Connection_rollback (T C)
 Undoes all changes made in the current transaction and releases any database locks currently held by this Connection object. More...
 
long long 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. More...
 
long long Connection_rowsChanged (T C)
 Returns the number of rows that was inserted, deleted or modified by the last Connection_execute() statement. More...
 
void 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. More...
 
ResultSet_T Connection_executeQuery (T C, const char *sql,...)
 Executes the given SQL statement, which returns a single ResultSet object. More...
 
PreparedStatement_T Connection_prepareStatement (T C, const char *sql,...)
 Creates a PreparedStatement object for sending parameterized SQL statements to the database. More...
 
const char * Connection_getLastError (T C)
 This method can be used to obtain a string describing the last error that occurred. More...
 
Properties
void Connection_setQueryTimeout (T C, int ms)
 Sets the number of milliseconds the Connection should wait for a SQL (select) statement to finish if the database is busy. More...
 
int Connection_getQueryTimeout (T C)
 Retrieves the number of milliseconds the Connection will wait for a SQL statement object to execute. More...
 
void Connection_setMaxRows (T C, int max)
 Sets the limit for the maximum number of rows that any ResultSet object can contain. More...
 
int Connection_getMaxRows (T C)
 Retrieves the maximum number of rows that a ResultSet object produced by this Connection object can contain. More...
 
void Connection_setFetchSize (T C, int rows)
 Specify the number of rows that should be fetched from the database when more rows are needed for ResultSet objects generated by this Connection. More...
 
int Connection_getFetchSize (T C)
 Get the number of rows that should be fetched from the database when more rows are needed for ResultSet objects generated by this Connection. More...
 
URL_T Connection_getURL (T C)
 Returns this Connection URL. More...
 
Class methods
int Connection_isSupported (const char *url)
 Class method, test if the specified database system is supported by this library. More...
 

Macro Definition Documentation

◆ T

#define T   Connection_T

Typedef Documentation

◆ T

typedef struct Connection_S* T

Function Documentation

◆ Connection_setQueryTimeout()

void Connection_setQueryTimeout ( T  C,
int  ms 
)

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

If the limit is exceeded, the statement will return immediately with an error. The timeout is set per connection/session. Not all database systems supports query timeout. The default is no query timeout.

Parameters
CA Connection object
msThe query timeout limit in milliseconds; zero means there is no timeout limit. Zero is the default value.

◆ Connection_getQueryTimeout()

int Connection_getQueryTimeout ( T  C)

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

Parameters
CA Connection object
Returns
The query timeout limit in milliseconds; zero means there is no timeout limit

◆ Connection_setMaxRows()

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
CA Connection object
maxThe new max rows limit; 0 means there is no limit

◆ Connection_getMaxRows()

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
CA Connection object
Returns
The new max rows limit; 0 means there is no limit

◆ Connection_setFetchSize()

void Connection_setFetchSize ( T  C,
int  rows 
)

Specify the number of rows that should be fetched from the database when more rows are needed for ResultSet objects generated by this Connection.

The default value is 100, meaning that a ResultSet will prefetch rows in batches of 100 rows to reduce the network roundtrip to the database. This value can also be set via the URL parameter fetch-size to apply to all connections. This method and the concept of pre-fetching rows are only applicable to MySQL and Oracle.

Parameters
CA Connection object
rowsThe number of rows to fetch (1..INT.MAX)
Exceptions
AssertExceptionIf rows is less than 1

◆ Connection_getFetchSize()

int Connection_getFetchSize ( T  C)

Get the number of rows that should be fetched from the database when more rows are needed for ResultSet objects generated by this Connection.

This method and the concept of pre-fetching rows are only applicable to MySQL and Oracle.

Parameters
CA Connection object
Returns
The number of rows to fetch

◆ Connection_getURL()

URL_T Connection_getURL ( T  C)

Returns this Connection URL.

Parameters
CA Connection object
Returns
This Connection URL
See also
URL.h

◆ Connection_ping()

int Connection_ping ( T  C)

Ping the database server and return true if this Connection is alive, otherwise false in which case the Connection should be closed.

Parameters
CA Connection object
Returns
true if Connection is connected to a database server otherwise false

◆ Connection_clear()

void Connection_clear ( T  C)

Close any ResultSet and PreparedStatements in the Connection.

Normally it is not necessary to call this method, but for some implementation (SQLite) it may, in some situations, be necessary to call this method if a execution sequence error occurs.

Parameters
CA Connection object

◆ Connection_close()

void Connection_close ( T  C)

Return connection to the connection pool.

The same as calling ConnectionPool_returnConnection() on a connection.

Parameters
CA Connection object

◆ Connection_beginTransaction()

void Connection_beginTransaction ( T  C)

Start a transaction.

Parameters
CA Connection object
Exceptions
SQLExceptionIf a database error occurs
See also
SQLException.h

◆ Connection_commit()

void 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
CA Connection object
Exceptions
SQLExceptionIf a database error occurs
See also
SQLException.h

◆ Connection_rollback()

void Connection_rollback ( T  C)

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

This method will first call Connection_clear() before performing the rollback to clear any statements in progress such as selects.

Parameters
CA Connection object
Exceptions
SQLExceptionIf a database error occurs
See also
SQLException.h

◆ Connection_lastRowId()

long long 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
CA Connection object
Returns
The value of the rowid from the last insert statement

◆ Connection_rowsChanged()

long long 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
CA Connection object
Returns
The number of rows changed by the last (DIM) SQL statement

◆ Connection_execute()

void 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
CA Connection object
sqlA SQL statement
Exceptions
SQLExceptionIf a database error occurs.
See also
SQLException.h

◆ Connection_executeQuery()

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
CA Connection object
sqlA SQL statement
Returns
A ResultSet object that contains the data produced by the given query.
Exceptions
SQLExceptionIf a database error occurs.
See also
ResultSet.h
SQLException.h

◆ Connection_prepareStatement()

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
CA Connection object
sqlA single SQL statement that may contain one or more '?' IN parameter placeholders
Returns
A new PreparedStatement object containing the pre-compiled SQL statement.
Exceptions
SQLExceptionIf a database error occurs.
See also
PreparedStatement.h
SQLException.h

◆ Connection_getLastError()

const char* Connection_getLastError ( T  C)

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

Inside a CATCH-block you can also find the error message directly in the variable Exception_frame.message. It is recommended to use this variable instead since it contains both SQL errors and API errors such as parameter index out of range etc, while Connection_getLastError() might only show SQL errors

Parameters
CA Connection object
Returns
A string explaining the last error

◆ Connection_isSupported()

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
urlA database url string
Returns
true if supported otherwise false

Copyright © Tildeslash Ltd. All rights reserved.