Main Page   Namespace List   Class Hierarchy   Alphabetical List   Compound List   File List   Namespace Members   Compound Members   File Members   Related Pages  

SQLDBC::SQLDBC_ConnectionItem Class Reference

#include <SQLDBC.h>

Inheritance diagram for SQLDBC::SQLDBC_ConnectionItem:

SQLDBC::SQLDBC_Connection SQLDBC::SQLDBC_ResultSet SQLDBC::SQLDBC_RowSet SQLDBC::SQLDBC_Statement SQLDBC::SQLDBC_UpdatableRowSet SQLDBC::SQLDBC_PreparedStatement List of all members.

Detailed Description

Base class to administrate the error handling within SQLDBC.

A ConnectionItem is an object that is referenced by connection, and it is directly bound to it. A Statement, PreparedStatement or a ResultSet object references this object.. Any SQLDBC_ConnectionItem has an ErrorHndl and a Warning member. They are set after an, unsuccessful operation.

Definition at line 196 of file SQLDBC.h.

Public Methods


Member Function Documentation

void SQLDBC::SQLDBC_ConnectionItem::clearError  
 

Deletes the error has been stored.

void SQLDBC::SQLDBC_ConnectionItem::clearWarnings  
 

Deletes the warning stored in the SQLWarning object.

SQLDBC_ErrorHndl& SQLDBC::SQLDBC_ConnectionItem::error  
 

Returns a reference to the ErrorHndl object.

Note:
Applications should retrieve the content of the SQLDBC_ErrorHndl object immediatly since an new call to any SQLDBC function except the warning() method will empty SQLDBC_ErrorHndl object.
Returns:
An SQLDBC_ErrorHndl object.

SQLDBC_SQLWarning* SQLDBC::SQLDBC_ConnectionItem::warning  
 

Returns a reference to an SQLWarning object stored in the SQLDBC_ConnectionItem object.

Note:
Getting the reference to the SQLWarning object will not clear the ErrorHndl object. All other function calls will empty the ErrorHndl object.
Returns:
The SQLWarning object stored in the item.


Friends And Related Function Documentation

friend class SQLDBC_Connection [friend]
 

Connection to the database kernel.

This class combines the functions necesary for managing a connection to the database. If a new connection object is created, it is not connected. The connection to the database is established when a successful connect() call was performed.

Todo:
Check more parameters after connection (version).

Distribute the results of a COMMIT or ROLLBACK statment into dependent objects (for correct handling of PUTVAL commands).

Reimplemented in SQLDBC::SQLDBC_Statement, and SQLDBC::SQLDBC_PreparedStatement.

Definition at line 237 of file SQLDBC.h.

friend class SQLDBC_Environment [friend]
 

The SQLDBC_Environment object is the basis for initializing the SQLDBC runtime library and making general settings in the SQLDBC interface.

Reimplemented in SQLDBC::SQLDBC_Connection.

Definition at line 236 of file SQLDBC.h.

friend class SQLDBC_PreparedStatement [friend]
 

A class for preparing and executing SQL statements.

A prepared SQL command can be parsed and contain input and output parameters. Parameters are marked with a '?' or ':<name>' tag. All DML commands can be parsed. DDL commands can be parsed, too. However, it is not recommended to do so. Prepared SQL commands increase the performance since they are parsed only once and executed several times. Applications only need to change the content of the bound parameters and execute the command again.

All prepared SQL commands are stored in an internally managed ParseInfo Cache . The ParseInfo Cache shares this information with different prepared SQL statements within the same connection.

The SQL statement may contain ASCII or UCS2 characters and must not zero-terminated. The execute() member function converts it to the adequate code set considering the code of the database. Therefore it is possible to write portable code for UNICODE and non-UNICODE databases.

Note:
To increase the performance, applications must use UCS2 statements for UNICODE databases only.
Example:
Preparation and execution of an SQL statement.
   SQLDBC_PrepareStatement *stmt = conn->createPreparedStatement();
   SQLDBC_Retcode rc = stmt->prepare("SELECT * FROM DUAL");
   if (rc != SQLDBC_OK) {
     // Handle error ...
   }
   rc = stmt->execute();
   if (rc != SQLDBC_OK) {
     // Handle error ...
   }
   

Hints:
  • The application must call createPreparedStatement() to retrieve a prepared SQL statement
  • For parsing the SQL statement, call the prepare() member function,
  • For a single-row execution, use the execute() member function,
  • For mass execution, bind arrays of parameter values, use setBatchSize() to set the row array size to the number of array elements bound, and use the execute() method.
  • Use the isQuery() method to check whether the parsed statement creates a result set upon execution.
  • Use SQLDBC_Statement for a direct execution, since the prepared statement inherits all direct-execution functions from SQLDBC_Statement.
  • The current result set is deleted when
    • A new statement is parsed
    • The statement is re-executed
    • The statement is deleted
Todo:
binding parameter by name

Reimplemented in SQLDBC::SQLDBC_Statement.

Definition at line 239 of file SQLDBC.h.

friend class SQLDBC_ResultSet [friend]
 

A class for presenting a database result set.

A database result set is generated by executing an SQL statement that queries the database.

Select statements, catalog functions, and some procedures create result sets. For example, the following SQL statement creates a result set containing all the rows and columns of the table DUAL:

SELECT * FROM DUAL

A result set can be empty, which is different from there being no result set at all. For example, the following SQL statement creates an empty result set:

SELECT * FROM DUAL WHERE 1 = 2

An SQLDBC_ResultSet object maintains a cursor pointing to its current row of data. Initially the cursor is positioned before the first row. The next() method moves the cursor to the next row, and as it returns SQLDBC_NO_DATA_FOUND when there are no more rows in the SQLDBC_ResultSet object, it can be used in a WHILE loop to iterate the result set.

Example for creating an SQLDBC_ResultSet object:

SQLDBC_Statement *stmt = conn->createStatement ();
stmt->execute ("SELECT * FROM DUAL");
SQLDBC_ResultSet *rs = stmt->getResultSet ();
rs->next();

To reduce the time needed for retrieving the data from the database, the SQLDBC_ResultSet class supports so called block cursors, which can return more than one row at a time. The rows returned by a block cursor are called a 'row set'. The result set is fixed, the rowset is not. It changes position and contents each time a new set of rows is retrieved from the database.

With block cursors, the method setRowSetSize() must be used with a parameter greater than 1.

Navigation within the data represented by the SQLDBC_ResultSet object is possible using of navigation methods like first(), next(), previous(), relative() etc.

When block cursors are used, after applying the navigation methods, the cursor points to the actual row set. For example assuming a result set size of 50 and a rowset size of 10, in the following sequence the block cursor points to the rows indicated:

  • first() : Rows 1 - 10 of the result set
  • next() : Rows 11 - 20 of the result set
  • next() : Rows 21 - 30 of the result set
  • previous() : Rows 11 - 20 of the result set
  • last() : Rows 41 - 50 of the result set

In order to perform operations that operate on a single row only when multiple rows have been fetched, the application must indicate which row is the current row. When a block cursor first returns a row set, the current row is the first row of that row set. To change the current row, the application must call the member function setPos().

The data of a certain column in the current row can be retrieved by calling the method getObject().

Data fetched from the database is passed on to the application in variables that the application has allocated for this purpose. Before fetching the data from the database, the application bind these variables to the columns of the result set. Applications can bind any number of columns of the result set, including binding no columns at all.

Binding of columns is done by calling to the member function bindColumn(). The column binding valid for all rows.

After positioning the cursor through navigation methods, the data from the database is written into the bound column variables by a call to the member function fetch() of the row set of this result set. When block cursors are used, the number of rows actually filled can be determined with the member function getResultCount().

For unbounded columns, data can be written into application variables with getObject(), or - in case of block cursors - by calling setPos() on the rowset and then calling getObject().

Reimplemented in SQLDBC::SQLDBC_RowSet.

Definition at line 240 of file SQLDBC.h.

friend class SQLDBC_RowSet [friend]
 

An SQLDBC_RowSet class for representing a SQLDBC row set.

A SQLDBC row set is a window on a result set.

The size of the row set is determined by the setRowSetSize() method of the SQLDBC_ResultSet object. The method fetch retrieves the rows from the SQLDBC_RowSet object into the bound columns. The getObject() method retrieves one column from the current row into the given buffer. The setPos() method moves the cursor within the row set.

Definition at line 241 of file SQLDBC.h.

friend class SQLDBC_Statement [friend]
 

Reimplemented in SQLDBC::SQLDBC_ResultSet.

Definition at line 238 of file SQLDBC.h.

friend class SQLDBC_UpdatableRowSet [friend]
 

A SQLDBC_UpdatableRowSet class for representing a SQLDBC updatable row set.

A SQLDBC updatable row set offers update, insert and delete operations on the underlying result set.

The insertAllRows() and insertOneRow() methods allow inserting either a whole row set or a single row (the first one) of the row set into the parent result set. The method updateRow() updates an arbitrary row of the result set while the method deleteRow() deletes a single row on a given position.

Definition at line 242 of file SQLDBC.h.


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