Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Namespace Members | Class Members | File Members | Related Pages
SQLDBC::SQLDBC_ResultSet

SQLDBC::SQLDBC_ResultSet Class Reference

Inheritance diagram for SQLDBC::SQLDBC_ResultSet:

SQLDBC::SQLDBC_ConnectionItem List of all members.

Detailed Description

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:

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

Definition at line 1433 of file SQLDBC.h.

Public Member Functions

Member Function Documentation

SQLDBC_Retcode SQLDBC::SQLDBC_ResultSet::absolute (  int  row  ) 
 

Moves the cursor to the specified row number in this SQLDBC_ResultSet object.

If the row number is positive, the cursor moves to this specified row number with respect to the beginning of the result set. The first row is row number 1, the second is row number 2, and so on.

If the given row number is negative, the cursor moves to an 'absolute' position with respect to the end of the result set. For example, calling the method absolute(-1) positions the cursor on the last row; calling the method absolute(-2) moves the cursor to the next-to-last row, and so on.

An attempt to position the cursor beyond the first or last row in the result set leaves the cursor before the first row or after the last row.

Parameters:
row Row number where the cursor is moved to. A positive number specifies the absolute row number with respect to the beginning of the result set; a negative number specifies a absolute row number respect to the end of the result set.
Returns:
SQLDBC_OK if the cursor is on the result set; SQLDBC_NO_DATA_FOUND otherwise; SQLDBC_NOT_OK if a database access error occurs.

SQLDBC_Retcode SQLDBC::SQLDBC_ResultSet::bindColumn (  const SQLDBC_UInt4  Index,
const SQLDBC_HostType  Type,
void *  paramAddr,
SQLDBC_Length *  LengthIndicator,
SQLDBC_Length *  PositionIndicator,
const SQLDBC_Length  Size,
const SQLDBC_Bool  Terminate = SQLDBC_TRUE
) 
 

Binds a user-supplied memory buffer to an SQL column of a result set.

Applications must use SQLDBC_ResultSetMetadata to retrieve information about the type and length of the columns of a result set.

Parameters:
Index [in] Parameter number. The parameter numbers in an SQL statement are, in increasing order, starting with 1.
Type [in] Parametertype of the output buffer
paramAddr [in] A pointer to a buffer for the parameter's data.
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.
PositionIndicator [in] Pointer to a variable that stores the start position in bytes from which to read non-integral data.
Size [in] Length of the parameter buffer in bytes. The Size argument is only necessary for non-integral datatypes. 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_NOT_OK If a wrong argument value was passed. In this case an error is set on this SQLDBC_ResultSet object.
See also:
getObject
Todo:
: Indicator handling and truncation handling

SQLDBC_Retcode SQLDBC::SQLDBC_ResultSet::bindColumn (  const SQLDBC_UInt4  Index,
const SQLDBC_HostType  Type,
void *  paramAddr,
SQLDBC_Length *  LengthIndicator,
const SQLDBC_Length  Size,
const SQLDBC_Bool  Terminate = SQLDBC_TRUE
) 
 

Binds a user-supplied memory buffer to an SQL column of a result set.

Applications must use SQLDBC_ResultSetMetadata to retrieve information about the type and length of the columns of a result set.

Parameters:
Index [in] Parameter number. The parameter numbers in an SQL statement are, in increasing order, starting with 1.
Type [in] Parametertype of the output buffer
paramAddr [in] A pointer to a buffer for the parameter's data.
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_NOT_OK If a wrong argument value was passed. In this case an error is set on this SQLDBC_ResultSet object.
See also:
getObject
Todo:
: Indicator handling and truncation handling

SQLDBC_Retcode SQLDBC::SQLDBC_ResultSet::clearColumns (   ) 
 

Clears the information about columns that have been bound.

All information about columns that have been bound before using bindColumn. method is cleared.

Returns:
SQLDBC_OK on success.

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.

void SQLDBC::SQLDBC_ResultSet::close (   ) 
 

Closes this result set.

Further operations are not allowed.

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_ResultSet::first (   ) 
 

Moves the cursor to the first row in this SQLDBC_ResultSet object.

Returns:
SQLDBC_OK if the cursor is on a valid row; SQLDBC_NO_DATA_FOUND if there are no rows in the result set; SQLDBC_NOT_OK if a database access error occurs or the result set type is FORWARD_ONLY

SQLDBC_Retcode SQLDBC::SQLDBC_ResultSet::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 datatypes. 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 the 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 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_ResultSet object.
See also:
bindColumn

SQLDBC_Retcode SQLDBC::SQLDBC_ResultSet::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 neccessary for non-integral datatypes. 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 occursed. In this case an error is set on this SQLDBC_ResultSet object.
See also:
bindColumn

const SQLDBC_Int4 SQLDBC::SQLDBC_ResultSet::getResultCount (   )  const
 

Returns number of rows of the current result set.

Returns:
The number of rows in the result set, or -1 if not known.

SQLDBC_ResultSetMetaData* SQLDBC::SQLDBC_ResultSet::getResultSetMetaData (   ) 
 

Retrieves an SQLDBC_ResultSetMetaData object that contains information about the columns of this SQLDBC_ResultSet object.

Returns:
An SQLDBC_ResultSetMetaData object that describes the columns or NULL if the meta data cannot be retrieved.

const SQLDBC_UInt4 SQLDBC::SQLDBC_ResultSet::getRowNumber (   )  const
 

Returns the current row number.

The first row is row number 1, the second row number 2, and so on.

Returns:
The current row number or 0 if the cursor is positioned outside the result set.

SQLDBC_RowSet* SQLDBC::SQLDBC_ResultSet::getRowSet (   ) 
 

Retrieves the SQLDBC_RowSet returned by block cursor operations.

Returns:
A reference to an SQLDBC_RowSet object if the SQLDBC_ResultSet object has an SQLDBC_RowSet or NULL otherwise.

const SQLDBC_UInt4 SQLDBC::SQLDBC_ResultSet::getRowSetSize (   )  const
 

Returns the size of the row array of bounded parameters.

Returns:
The size of the array of bound parameters
See also:
setRowSetSize

SQLDBC_Statement* SQLDBC::SQLDBC_ResultSet::getStatement (   ) 
 

Retrieves the SQLDBC_Statement object that belongs to the result set.

Returns:
A reference to the SQLDBC_Statement object that generate this result set.

SQLDBC_UpdatableRowSet* SQLDBC::SQLDBC_ResultSet::getUpdatableRowSet (   ) 
 

Retrieves the SQLDBC_UpdatableRowSet returned by block cursor operations.

Returns:
A reference to an SQLDBC_UpdatableRowSet object if the SQLDBC_ResultSet object has an SQLDBC_UpdatableRowSet or NULL otherwise.

SQLDBC_Bool SQLDBC::SQLDBC_ResultSet::isUpdatable (   ) 
 

Returns SQLDBC_TRUE, if the result set is updatable.

Returns:
SQLDBC_TRUE or SQLDBC_FALSE

SQLDBC_Retcode SQLDBC::SQLDBC_ResultSet::last (   ) 
 

Moves the cursor to the last row in this SQLDBC_ResultSet object.

Returns:
SQLDBC_OK if the cursor is on a valid row; SQLDBC_NO_DATA_FOUND if there are no rows in the result set; SQLDBC_NOT_OK if a database access error occurs or the result set type is FORWARD_ONLY.

SQLDBC_Retcode SQLDBC::SQLDBC_ResultSet::next (   ) 
 

Moves the cursor down one row from its current position.

A result set cursor is initially positioned before the first row; the first call of the member function next() positions the cursor to the first row set; the second call positions the cursor on the second row set, and so on.

An SQLDBC_ResultSet object's warning chain is cleared when the next call is done.

Returns:
SQLDBC_OK if the new current row is valid; SQLDBC_NO_DATA_FOUND if there are no more rows; SQLDBC_NOT_OK if a database access error occurs

SQLDBC_Retcode SQLDBC::SQLDBC_ResultSet::previous (   ) 
 

Moves the cursor to the previous row in this SQLDBC_ResultSet object.

Returns:
SQLDBC_OK if the cursor is on a valid row; SQLDBC_NO_DATA_FOUND if it is outside the result set; SQLDBC_NOT_OK if a database access error occurs or the result set type is FORWARD_ONLY

SQLDBC_Retcode SQLDBC::SQLDBC_ResultSet::relative (  int  relativePos  ) 
 

Moves the cursor by a relative number of rows, either positive or negative.

Attempting to move the cursor beyond the first or last row in the result set positions the cursor before or after the first or last row. Calling relative(0) is valid, but does not change the cursor position.

Note:
Calling the method relative(1) is identical to calling the method next(). Calling the method relative(-1) is identical to calling the method previous().
Parameters:
relativePos An integer value specifying the number of rows by which the cursor is to be moved from its current position; a positive number moves the cursor forward; a negative number moves the cursor backward.
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_Retcode SQLDBC::SQLDBC_ResultSet::setBindingType (  SQLDBC_size_t  size  ) 
 

Sets the binding type for columns.

The value of the parameter offset is normally 0, which implies a column-wise binding. If it is set to a value other than 0, a row-wise binding is applied. So, the address offset of the respective next parameter value is computed differently for column-wise and row-wise binding:

Column-wise Binding
Byte length of the column.
Row-wise Binding
size
Parameters:
size The column offset for row-wise binding, if set to 0, column-wise binding is applied.
Returns:
SQLDBC_OK always.
See also:
bindParameterAddr

void SQLDBC::SQLDBC_ResultSet::setFetchSize (  SQLDBC_Int2  fetchsize  ) 
 

Sets the desired fetch size.

The fetch size setting is a hint to the runtime, and not a strict setting such as the row set size. If it is 1, the FETCH statements issued by the library will not be mass statements, making additional functionality, such as updating using the CURRENT OF predicate possible. Use a value = 0 to reset the fetch size to the default value. The default value is 'unlimited' (32767).

Parameters:
fetchsize The new fetch size.

void SQLDBC::SQLDBC_ResultSet::setRowSetSize (  SQLDBC_UInt4  rowsetsize  ) 
 

Sets the size of the row array of bounded parameters.

Parameters:
rowsetsize The number of rows.
See also:
getRowSetSize

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.