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

SQLDBC::SQLDBC_RowSet Class Reference

#include <SQLDBC.h>

Inheritance diagram for SQLDBC::SQLDBC_RowSet:

SQLDBC::SQLDBC_ConnectionItem SQLDBC::SQLDBC_UpdatableRowSet List of all members.

Detailed Description

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 769 of file SQLDBC.h.

Public Methods

Protected Methods


Constructor & Destructor Documentation

SQLDBC::SQLDBC_RowSet::SQLDBC_RowSet IFR_ResultSet *    resultset [protected]
 


Member Function Documentation

void SQLDBC::SQLDBC_ConnectionItem::clearError   [inherited]
 

Deletes the error has been stored.

void SQLDBC::SQLDBC_ConnectionItem::clearWarnings   [inherited]
 

Deletes the warning stored in the SQLWarning object.

SQLDBC_ErrorHndl& SQLDBC::SQLDBC_ConnectionItem::error   [inherited]
 

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_Retcode SQLDBC::SQLDBC_RowSet::fetch  
 

Writes the retrieved data to the bound columns.

Returns:
SQLDBC_OK if successful; SQLDBC_NOT_OK otherwise

SQLDBC_Retcode SQLDBC::SQLDBC_RowSet::getObject const SQLDBC_Int4    Index,
const SQLDBC_HostType    Type,
void *    paramAddr,
SQLDBC_Length   LengthIndicator,
const SQLDBC_Length    Size,
SQLDBC_Length    StartPos,
const SQLDBC_Bool    Terminate = SQLDBC_TRUE
 

Retrieves and converts the value with an start offset in of the specified column from a of the current row to a buffer.

The specified column value in the current row of this SQLDBC_RowSet object is converted to the given length and SQLDBC_HostType and written to the output parameter buffer pointed to paramAddr.

It can be called multiple times to retrieve character or binary data in parts. For fixed-length datatypes getObject retrieves the same data multiple times. Mixing variable-length datatypes and fixed-length datatypes may produce unexpected results.

The current row may be set by a positioning command from SQLDBC_ResultSet (current row = 1) or by the setPos method of the SQLDBC_RowSet object.

Parameters:
Index Index of the column. The first column is column number 1, the second is column number 2, ...
Type Parameter type of the output buffer.
paramAddr A pointer to the parameters output buffer.
LengthIndicator [out] Pointer to a variable that stores the column length or the indicator value SQLDBC_NULL_DATA if the column contains the NULL value. For character data it contains on success the number of bytes copied to the buffer, except the number of bytes necessary for the zero-terminator, if the Terminate flag was set. If the source string exceeds the Size value SQLDBC_DATA_TRUNC will be returned and LengthIndicator is set to the number of bytes (except the terminator bytes) needed to copy without truncation.
Size [in] Length of the parameter buffer in bytes. The Size argument is only necessary for non-integral data types. For character data the Size argument must be large enough to store the terminator byte(s) if the Terminate flag is set.
StartPos [in] Start position in long column from which on the data should be retrieved. Start position is counted in bytes from 1. Negative StartPos counts from the end of the long column.
Terminate [in] Specifies that the output buffer must be finished with a C-style zero-terminator. The Terminate flag works only for the host var type character (ASCII, UCS2 or UTF8). As a default, all character data is zero-terminated.
Returns:
SQLDBC_OK on success SQLDBC_DATA_TRUNC if the output buffer was too small. SQLDBC_NOT_OK if a database access or conversion error occurred. In this case an error is set on this SQLDBC_RowSet object.
See also:
bindColumn

SQLDBC_Retcode SQLDBC::SQLDBC_RowSet::getObject const SQLDBC_Int4    Index,
const SQLDBC_HostType    Type,
void *    paramAddr,
SQLDBC_Length   LengthIndicator,
const SQLDBC_Length    Size,
const SQLDBC_Bool    Terminate = SQLDBC_TRUE
 

Retrieves and converts the value of the specified column of the current row to a buffer.

The specified column value in the current row of this SQLDBC_RowSet object is converted to the given length and SQLDBC_HostType and written to the output parameter buffer pointed to paramAddr.

It can be called multiple times to retrieve character or binary data in parts. For fixed-length datatypes getObject retrieves the same data multiple times. Mixing variable-length datatypes and fixed-length datatypes may produce unexpected results.

The current row may be set by a positioning command from SQLDBC_ResultSet (current row = 1) or by the setPos method of the SQLDBC_RowSet object.

Parameters:
Index Index of the column. The first column is column number 1, the second is column number 2, ...
Type Parameter type of the output buffer.
paramAddr A pointer to the parameters output buffer.
LengthIndicator [out] Pointer to a variable that stores the column length or the indicator value SQLDBC_NULL_DATA if the column contains the NULL value. For character data it contains on success the number of bytes copied to the buffer, except the number of bytes necessary for the zero-terminator, if the Terminate flag was set. If the source string exceeds the Size value SQLDBC_DATA_TRUNC will be returned and LengthIndicator is set to the number of bytes (except the terminator bytes) needed to copy without truncation.
Size [in] Length of the parameter buffer in bytes. The Size argument is only necessary for non-integral data types. For character data the Size argument must be large enough to store the terminator byte(s) if the Terminate flag is set.
Terminate [in] Specifies that the output buffer must be finished with a C-style zero-terminator. The Terminate flag works only for the host var type character (ASCII, UCS2 or UTF8). As a default, all character data is zero-terminated.
Returns:
SQLDBC_OK on success SQLDBC_DATA_TRUNC if the output buffer was too small. SQLDBC_NOT_OK if a database access or conversion error occurred. In this case an error is set on this SQLDBC_RowSet object.
See also:
bindColumn

const SQLDBC_Int4 SQLDBC::SQLDBC_RowSet::getRowsAffected   const
 

Returns the number of rows written to the bound parameters.

Returns:
The number of rows fetched with the last fetch() call.
Note:
The number of fetched rows is updated by the next fetch() call. Positioning of the cursor within result set with SQLDBC_ResultSet::next(), SQLDBC_ResultSet::first(), ... does not change the number of rows.

const SQLDBC_Int4* SQLDBC::SQLDBC_RowSet::getRowStatus   const
 

Returns the row status array for the last fetch call.

The row status array describes the state of each row. The maximum size of the row status array is given by the setRowSetSize(). The row status array is filled during the fetch() call. The return code of the first row matches to the first member of the row status array.

Returns:
A pointer to the first element of the row status array.
See also:
setRowSetSize(), getRowsAffected

SQLDBC_Retcode SQLDBC::SQLDBC_RowSet::setPos SQLDBC_UInt4    pos
 

Sets the cursor to row pos in the SQLDBC_RowSet.

Parameters:
pos Row number within the row set. The first row of a row set is row number one.
Returns:
SQLDBC_OK if the cursor is positioned on a row; SQLDBC_NO_DATA_FOUND otherwise; SQLDBC_NOT_OK if a database access error occurs or the result set type is FORWARD_ONLY.

SQLDBC_SQLWarning* SQLDBC::SQLDBC_ConnectionItem::warning   [inherited]
 

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_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 from SQLDBC::SQLDBC_ConnectionItem.

Definition at line 942 of file SQLDBC.h.

friend struct SQLDBC_ResultSetStorage [friend]
 

Reimplemented in SQLDBC::SQLDBC_UpdatableRowSet.

Definition at line 943 of file SQLDBC.h.


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