Class RDbRowSet

RDbRowSet

Support

Supported from 5.0

Description

An abstract base class that provides functionality which is shared between SQL view objects and Table objects. This functionality includes most of the cursor navigation, row retrieval and update behaviour of rowsets.

Rowset objects do not provide the data for the rowset on which they operate. It is the responsibility of the derived classes RDbView and RDbTable to specify the data source.

This class is not intended for user derivation.

Defined in RDbRowSet:
AtBeginning(), AtEnd(), AtRow(), BeginningL(), Bookmark(), Cancel(), Close(), ColCount(), ColDef(), ColDes(), ColDes16(), ColDes8(), ColInt(), ColInt16(), ColInt32(), ColInt64(), ColInt8(), ColLength(), ColReal(), ColReal32(), ColReal64(), ColSetL(), ColSize(), ColTime(), ColType(), ColUint(), ColUint16(), ColUint32(), ColUint8(), CountL(), DeleteL(), EBackwards, EBeginning, EEnd, EEnsure, EFirst, EForwards, EInsertOnly, ELast, ENext, EPrevious, EQuick, EReadOnly, EUpdatable, EndL(), FindL(), FirstL(), GetL(), GotoL(), InsertCopyL(), InsertL(), IsColNull(), IsEmptyL(), LastL(), MatchL(), NextL(), PreviousL(), PutL(), Reset(), SetColL(), SetColNullL(), TAccess, TAccuracy, TDirection, TPosition, UpdateL()

void Close();

Description

Closes the rowset and releases any owned resources. It is safe to close a rowset object which is not open.

void Reset();

Description

Resets the rowset.

For a Table, this just sets the rowset cursor to the beginning position.

For an SQL view, this discards any evaluated rows and returns the cursor to the beginning. The view then requires reevaluation.

The Store Database implementation requires this function to be called in order to recover an open rowset object after the database has been rolled back. The rowset does not need to be closed in this situation.

If a rowset object requires a reset, then all row functions return or leave with KErrNotReady.

Description

Rows within a rowset have a column structure which depends on how the set is generated. The rowset object provides a way to discover this structure. In order to access a column in a row, a column ordinal is required, and this can be found by looking up the column name in the rowset's column set.

TInt ColCount() const;

Description

Returns the number of columns which are defined in this rowset.

Return value

TInt The number of columns which are defined in this rowset.

TDbColType ColType(TDbColNo aCol) const;

Description

Returns the type of a column in the rowset.

Parameters

TDbColNo aCol The column ordinal for which the column type is required. Column ordinals range from 1 to ColCount().

Return value

TDbColType The type of the column aCol.

TDbCol ColDef(TDbColNo aCol) const;

Description

Returns the definition of a column in the rowset.

Parameters

TDbColNo aCol The column ordinal for which the column definition is required. Column ordinals range from 1 to ColCount().

Return value

TDbCol The definition of the column aCol.

CDbColSet* ColSetL() const;

Description

Returns the entire column set for the rowset. This can be used to discover column ordinals for named columns in this rowset.

The function leaves with KErrNoMemory if there is not enough memory to carry out the operation.

Return value

CDbColSet* The column set object which describes this rowset structure. The caller should delete it when it is no longer required.

TBool AtRow() const;

Description

Tests whether the cursor is on a row.

One of the following is true:

• the rowset is currently updating a row

• the rowset is currently inserting a row

• GetL() can be called to retrieve the row

Return value

TBool True if the cursor is on a valid row; false, otherwise.

TBool AtBeginning() const;

Description

Tests whether the cursor is at the beginning of the rowset.

Return value

TBool True if the cursor is at the beginning, otherwise false.

TBool AtEnd() const;

Description

Tests whether the cursor is at the end of the rowset.

Return value

TBool True if the cursor is at the end, otherwise false.

TInt CountL(TAccuracy anAccuracy=EEnsure) const;

Description

Returns the number of rows available in a rowset.

This can take some time to complete, and a parameter can be passed to request a quick but not always thorough count of the rows.

For SQL views, the value returned depends on the evaluation window being used by the view. If there is an evaluation window this function will always return the number of rows available in the window, not the total number which could be returned by the query.

Parameters

TAccuracy anAccuracy This specifies whether to ensure that an accurate count is returned, or to give up if this value is not readily available. The default is to ensure an accurate count.

Return value

TInt The number of rows available in the rowset, or KDbUndefinedCount if EQuick was specified and the count was not available.

Leave codes

The Store database can leave with KErrWrite if this rowset was created with insert-only access.

See also:

• Additional DBMS database error codes

TBool IsEmptyL() const;

Description

Tests whether there are any rows in the rowset. This is often faster than testing whether CountL()==0.

Return value

TBool True if there are no rows available in the rowset, false if there are one or more.

Leave codes

The Store database can leave with KErrWrite if this rowset was created with insert-only access. It can also leave with any of the general errors described in the class overview.

void BeginningL();

Description

Positions the cursor at the beginning of the rowset.

Leave codes

The Store database can leave with KErrWrite if this rowset was created with insert-only access.

void EndL();

Description

Positions the cursor at the end of the rowset.

Leave codes

The Store database can leave with KErrWrite if this rowset was created with insert-only access.

TBool FirstL();

Description

Positions the cursor on the first row in the rowset. If there are no rows, the cursor is positioned at the end.

Return value

TBool True if the cursor is now at a row, false if it is at the end.

Leave codes

The Store database can leave with KErrWrite if this rowset was created with insert-only access. It can also leave with any of the general errors described in the class overview.

TBool LastL();

Description

Positions the cursor on the last row in the rowset. If there are no rows, the cursor is positioned at the beginning.

Return value

TBool True if the cursor is now at a row, false if it is at the beginning.

Leave codes

The Store database can leave with KErrWrite if this rowset was created with insert-only access. It can also leave with any of the general errors described in the class overview.

TBool NextL();

Description

Moves the cursor to the next row in the rowset. If there are no more rows, the cursor is positioned to the end.

If the cursor is at the beginning prior to the function, it is equivalent to FirstL().

Return value

TBool

Leave codes

The Store database can leave with KErrWrite if this rowset was created with insert-only access. It can also leave with any of the general errors described in the class overview.

TBool PreviousL();

Description

Moves the cursor to the previous row in the rowset. If there are no more rows, the cursor is positioned to the beginning.

If the cursor is at the end prior to the function, it is equivalent to LastL().

Return value

TBool True if the cursor is now at a row, false if it is at the beginning.

Leave codes

The Store database can leave with KErrWrite if this rowset was created with insert-only access. It can also leave with any of the general errors described in the class overview.

TBool GotoL(TPosition aPosition);

Description

Moves the cursor to a specified position.

This is invoked by Beginning(), End(), FirstL(), LastL(), NextL() and PreviousL() to navigate the cursor. See those functions for descriptions of how the cursor behaves given different position specifications.

Parameters

TPosition aPosition Specifies the position to move the cursor to.

Return value

TBool True if the cursor is now at a row, false if it is at the beginning or end.

Leave codes

The Store database can leave with KErrWrite if this rowset was created with insert-only access. It can also leave with any of the general errors described in the class overview.

Description

The current cursor position can be saved into a bookmark, which can be used later to return the cursor to the same location in the rowset.

TDbBookmark Bookmark() const;

Description

Gets the bookmark for the current cursor position. Bookmarks cannot be extracted when the rowset is updating or inserting a row.

The Store Database implementation allows bookmarks to be extracted for any cursor position including the beginning and end.

Return value

TDbBookmark A bookmark which can be used to return to the current position using the GotoL() function.

void GotoL(const TDbBookmark& aMark);

Description

Goes to a previously bookmarked position in a rowset.

The Store Database implements bookmarks which are valid in any rowset based on the same table or generated by the same query, and which persist across transaction boundaries.

Parameters

const TDbBookmark& aMark The bookmark to return to. This should have been returned by a previous call to Bookmark() on this or an equivalent rowset object.

Leave codes

The Store database can leave with KErrWrite if the rowset was created with insert-only access, or KErrNotFound if the bookmarked row has been deleted or is not currently in the rowset evaluation window. It can also leave with any of the general errors described in the class overview.

Description

Rowset objects support some extra search functionality over the generated rowset. The matching criterion is specified as an SQL search-condition and can either be pre-compiled into a RDbRowConstraint object and then tested against any row in the rowset with MatchL(), or used in a one-off search using FindL().

TInt FindL(TDirection aDirection,TDbQuery aCriteria);

Description

Searches through a rowset for a row which fulfils an SQL search-condition. The search begins from the current position (which must be a valid row) and proceeds forwards or backwards through the available rows until it finds a match or runs out of rows.

The cursor is positioned to the matching row (or beginning/end of set) on return.

This is a brute-force approach to finding a row — using an index for key-based retrieval on a Table rowset is a much faster but less flexible way of finding rows.

Parameters

TDirection aDirection Specifies which direction to search after testing the current row. TDbQuery aCriteria A query object containing an SQL search-condition to match against.

Return value

TInt If no match is found KErrNotFound is returned. Otherwise the number of rows navigated while finding a match, which may be 0 if the current row matches.

Leave codes

This function leaves if it encounters any of the general errors described in the class overview.

TBool MatchL(const RDbRowConstraint& aConstraint);

Description

Tests whether the current row in the rowset matches a previously compiled row constraint. The rowset must not currently be updating or inserting a row.

Parameters

const RDbRowConstraint& aConstraint A row constraint object which must have been previously opened on this rowset object.

Return value

TBool True if the current row fulfils the constraint, otherwise false.

Leave codes

This function leaves if it encounters any of the general errors described in the class overview.

void GetL();

Description

Gets the current row data for access using the column extractor functions. The cursor must be positioned at a valid row.

Leave codes

This function leaves if it encounters any of the general errors described in the class overview.

void InsertL();

Description

Inserts a new row into the rowset. All auto-increment columns will be initialised with their new values, all other columns will be initialised to NULL values. If no client-begun transaction is in progress, this function begins an automatic transaction, which is committed by PutL().

After the column values have been set using the SetColL() functions, the row can be written to the database using PutL().

Leave codes

The Store database can leave with KErrWrite if the rowset was created with read-only access. It also leaves if it encounters any of the general errors described in the class overview.

void InsertCopyL();

Description

Inserts a copy of the current row into the rowset. All auto-increment columns will be given a new value (as for InsertL()), the other columns will copy their values from the cursor's current row. If no client-begun transaction is in progress, this function begins an automatic transaction, which is committed by PutL().

After the column values have been modified using the SetColL() functions, the row can be written to the database using PutL().

Leave codes

The Store database can leave with KErrWrite if the rowset was created with read-only access. It also leaves if it encounters any of the general errors described in the class overview.

void UpdateL();

Description

Prepares the current row for update. If no client-begun transaction is in progress, this function begins an automatic transaction, which is committed by PutL().

After the column values have been modified using the SetColL() functions, the row can be written back to the database using PutL().

Leave codes

The Store database can leave with KErrWrite if the rowset was not created with updatable access. It also leaves if it encounters any of the general errors described in the class overview.

void PutL();

Description

Completes the update or insertion of a row.

First the new row data is validated:

• not-null columns are checked to be not NULL

• numerical columns are checked to be in range for their type

• variable length columns are checked to not exceed their maximum length

• unique index keys are checked to ensure uniqueness is not violated

Note that modifying auto-increment columns is not prevented by DBMS.

Following validation the data is written to the database and any affected indexes are updated. On successful completion of the write, PutL() will then commit any automatic transaction.

The cursor is left positioned on the updated or inserted row — where this lies in the rowset is not always well defined. To return to the row which was current prior to the update or insertion, a bookmark can be used.

In the Store Database implementation the written row is located in the rowset as follows:

• Tables without an active index will leave updated rows in the same location and append new rows to the end of the rowset.

• Tables with an active index place the row according to the active index ordering.

• SQL views without an evaluation window will place it according to the rowset ordering. The row may subsequently disappear if it does not match the WHERE clause of the SQL query.

• SQL views with a full evaluation window will leave updated rows in the same location and append new rows to the end of the rowset. Re-evaluation may cause the row to disappear if it does not match the WHERE clause of the SQL query.

• SQL views with a partial evaluation window will leave updated rows in the same location, new rows are not added to the window and navigation from the new row is undefined. Further navigation and evaluation of the partial window will place the rows in the correct location according to the query.

Leave codes

If PutL() fails during validation, the current transaction (automatic or user) is unaffected, and the update or insertion can be cancelled by calling Cancel() ; or the row data can be modified further and PutL() can be reattempted, though this is not recommended. If PutL() fails during write or commit, the current transaction (automatic or user) is aborted, and will require rollback. In this case Cancel() must be called next on the rowset object, this will cause any automatic transaction to roll back. The rowset object will also need to be Reset() in this situation. The Store database can leave with the following validation errors as well as any of the general errors described in the class overview: KErrNotFound   — A not-null column has a NULL . KErrOverflow   — A numerical column is out of range or a variable length column value exceeds its maximum length. KErrAlreadyExists   — A unique index has a duplicate key.

void Cancel();

Description

Cancels the update or insertion of a row, or recovers the rowset if PutL() fails. The cursor will return to the location prior to starting the update or insertion. It is also safe to call this function when the rowset object is not updating or inserting a row, in which case it does nothing.

In the Store database implementation, if this is called to abort a row update or insertion before PutL() is called or during row validation in PutL(), all the changes are discarded without requiring a transaction rollback and the rowset to be Reset().

void DeleteL();

Description

Deletes the current row in a rowset. The rowset must not currently be updating or inserting the row.

The rowset cursor is left positioned at the "hole" left by the deletion of the current row. Navigation to the next or previous row will have the same effect as if this row had not been deleted. Once the cursor has been moved from the "hole" it will disappear from the rowset.

If the client has not begun a transaction, this function will use an automatic transaction to update the rowset.

Leave codes

If this function leaves having begun an automatic transaction, the transaction will have been rolled back. This will make the rowset non-operational until it has been Reset() . The error codes which may be returned are given in the class overview.

Description

Small integral columns can be extracted as a wider integral type (up to 32-bits) provided that the following rule is used:

In order to extract column data for a row, either

• the row must first have been retrieved using GetL(), or

• the rowset object is updating or inserting the row

Long columns can only be read using the RDbColReadStream object, and the above conditions also apply.

• signed columns must be extracted using a signed column accessor

• unsigned columns must be extracted using an unsigned column accessor

Bit columns are considered to be single bit unsigned integers.

TPtrC ColDes(TDbColNo aCol) const;

Description

Extracts a Text column value. The column type must match the default descriptor type to use this extractor, ie. it must be equal to EDbColText.

Parameters

TDbColNo aCol The column ordinal of the column to extract.

Return value

TPtrC A descriptor of column aCol's value.

TPtrC8 ColDes8(TDbColNo aCol) const;

Description

Extracts any column type, except Long columns, as binary data.

Parameters

TDbColNo aCol The column ordinal of the column to extract.

Return value

TPtrC8 A descriptor of column aCol's value.

TPtrC16 ColDes16(TDbColNo aCol) const;

Description

Extracts a column as Unicode text.

Parameters

TDbColNo aCol The column ordinal of the column to extract

Return value

TPtrC16 A descriptor of column aCol's value.

TInt ColInt(TDbColNo aCol) const;

Description

Extracts a signed integer column value. The type should fit within a TInt.

Parameters

TDbColNo aCol The column ordinal of the column to extract.

Return value

TInt The value of column aCol.

TInt8 ColInt8(TDbColNo aCol) const;

Description

Extracts a TInt8 column value.

Parameters

TDbColNo aCol The column ordinal of the column to extract.

Return value

TInt8 The value of column aCol.

TInt16 ColInt16(TDbColNo aCol) const;

Description

Extracts a TInt16 or TInt8 column value.

Parameters

TDbColNo aCol The column ordinal of the column to extract.

Return value

TInt16 The value of column aCol.

TInt32 ColInt32(TDbColNo aCol) const;

Description

Extracts a TInt32, TInt16 or TInt8 column value.

Parameters

TDbColNo aCol The column ordinal of the column to extract.

Return value

TInt32 The value of column aCol.

TInt64 ColInt64(TDbColNo aCol) const;

Description

Extracts a TInt64 column value.

Parameters

TDbColNo aCol The column ordinal of the column to extract.

Return value

TInt64 The value of column aCol.

TInt ColLength(TDbColNo aCol) const;

Description

Gets the length of a column value. As compared with ColSize(), this returns the number of "units" in the column:

• NULL columns have a length of 0

• non-NULL numerical and date-time columns have a length of 1

• for Text columns the length is the character count

• for Binary columns the length is the byte count

Parameters

TDbColNo aCol The column ordinal of the column to check.

Return value

TInt The length in "units" of column aCol's value.

TReal ColReal(TDbColNo aCol) const;

Description

Extracts a TReal64 column value.

Parameters

TDbColNo aCol The column ordinal of the column to extract.

Return value

TReal The value of column aCol.

TReal32 ColReal32(TDbColNo aCol) const;

Description

Extracts a TReal32 column value.

Parameters

TDbColNo aCol The column ordinal of the column to extract.

Return value

TReal32 The value of column aCol.

TReal64 ColReal64(TDbColNo aCol) const;

Description

Extracts a TReal64 column value.

Parameters

TDbColNo aCol The column ordinal of the column to extract.

Return value

TReal64 The value of column aCol.

TInt ColSize(TDbColNo aCol) const;

Description

Gets the size in bytes of a column value. This can be used for all column types, including Long columns. NULL columns return a size of 0.

Note:

• This may yield unexpected results for small numerical column types as they are stored in memory as 32-bit values.

Parameters

TDbColNo aCol The column ordinal of the column to check.

Return value

TInt The length in bytes of column aCol's value.

TTime ColTime(TDbColNo aCol) const;

Description

Extracts a TTime column value.

Parameters

TDbColNo aCol The column ordinal of the column to extract.

Return value

TTime The value of column aCol.

TUint ColUint(TDbColNo aCol) const;

Description

Extracts an unsigned integer column value.

Parameters

TDbColNo aCol The column ordinal of the column to extract.

Return value

TUint The value of column aCol.

TUint8 ColUint8(TDbColNo aCol) const;

Description

Extracts a Uint8 or Bit column value.

Parameters

TDbColNo aCol The column ordinal of the column to extract.

Return value

TUint8 The value of column aCol.

TUint16 ColUint16(TDbColNo aCol) const;

Description

Extracts a Uint16, Uint8 or Bit column value.

Parameters

TDbColNo aCol The column ordinal of the column to extract.

Return value

TUint16 The value of column aCol.

TUint32 ColUint32(TDbColNo aCol) const;

Description

Extracts a Uint32, Uint16, Uint8 or Bit column value.

Parameters

TDbColNo aCol The column ordinal of the column to extract.

Return value

TUint32 The value of column aCol.

TBool IsColNull(TDbColNo aCol) const;

Description

Tests whether a column has the NULL value.

Columns which have the NULL value can still be extracted with the correct accessor function, in which case numerical columns will return a 0 (or equivalent) value, and text and binary columns will have a zero length.

Parameters

TDbColNo aCol The column ordinal for the column to test.

Return value

TBool True if column aCol is NULL, otherwise false.

Description

Invalid column values — such as NULL in columns specified as not-null, out of range integers in small integral columns or variable length columns which exceed the maximum length — are not checked until the row update or insertion is completed with PutL().

Small integral columns are set as a wider integral type ensuring that signed columns use the signed integer overload of SetColL(), and similarly for unsigned column types. Bit columns are considered to be single bit unsigned integers.

Long columns can be set using either the RDbColWriteStream object, or using the appropriate descriptor overload of SetColL().

In order to set column data for a row, the rowset object must be updating or inserting the row.

void SetColL(TDbColNo aCol,TInt aValue);

Description

Sets a signed integer column value. The type should fit into a TInt.

Parameters

TDbColNo aCol The column ordinal of the column to set. TInt aValue The new column value.

Leave codes

This function will leave with KErrNoMemory if there is not enough space in the row buffer for the value.

void SetColL(TDbColNo aCol,TInt32 aValue);

Description

Sets a TInt32, TInt16 or TInt8 column value.

Parameters

TDbColNo aCol The column ordinal of the column to set. TInt32 aValue The new column value.

Leave codes

This function will leave with KErrNoMemory if there is not enough space in the row buffer for the value.

void SetColL(TDbColNo aCol,TInt64 aValue);

Description

Sets a TInt64 column value.

Parameters

TDbColNo aCol The column ordinal of the column to set. TInt64 aValue The new column value.

Leave codes

This function will leave with KErrNoMemory if there is not enough space in the row buffer for the value.

void SetColL(TDbColNo aCol,TUint aValue);

Description

Sets an unsigned integer column value. The type should fit into a TUint.

Parameters

TDbColNo aCol The column ordinal of the column to set. TUint aValue The new column value.

Leave codes

This function will leave with KErrNoMemory if there is not enough space in the row buffer for the value.

void SetColL(TDbColNo aCol,TUint32 aValue);

Description

Sets a TUint32, TUint16, TUint8 or Bit column value.

Parameters

TDbColNo aCol The column ordinal of the column to set. TUint32 aValue The new column value.

Leave codes

This function will leave with KErrNoMemory if there is not enough space in the row buffer for the value.

void SetColL(TDbColNo aCol,TReal32 aValue);

Description

Sets a TReal32 column value.

Parameters

TDbColNo aCol The column ordinal of the column to set. TReal32 aValue The new column value.

Leave codes

This function will leave with KErrNoMemory if there is not enough space in the row buffer for the value.

void SetColL(TDbColNo aCol,TReal64 aValue);

Description

Sets a TReal64 column value.

Parameters

TDbColNo aCol The column ordinal of the column to set. TReal64 aValue The new column value.

Leave codes

This function will leave with KErrNoMemory if there is not enough space in the row buffer for the value.

void SetColL(TDbColNo aCol,TTime aValue);

Description

Sets a TTime column value.

Parameters

TDbColNo aCol The column ordinal of the column to set. TTime aValue The new column value.

Leave codes

This function will leave with KErrNoMemory if there is not enough space in the row buffer for the value.

void SetColL(TDbColNo aCol,const TDesC8& aValue);

Description

Sets a column value from an 8 bit descriptor. This function can also set the value of Long columns.

Usually this is used to set a Text8 or LongText8 column from a non-Unicode text descriptor, but can be used for any column type: the data content is validated when the row is PutL().

Parameters

TDbColNo aCol The column ordinal of the column to set. const TDesC8& aValue The new column value.

Leave codes

This function will leave with KErrNoMemory if there is not enough space in the row buffer for the value. When setting Long columns other errors may be encountered, see the class overview for more information.

void SetColL(TDbColNo aCol,const TDesC16& aValue);

Description

Set a column value from Unicode text.

Parameters

TDbColNo aCol The column ordinal of the column to set. const TDesC16& aValue The new column value.

Leave codes

This function will leave with KErrNoMemory if there is not enough space in the row buffer for the value. When setting a LongText16 column other errors may be encountered, see the class overview for more information.

void SetColNullL(TDbColNo aCol);

Description

Use this function to set the value of a column to NULL.

Parameters

TDbColNo aCol The column ordinal of the column to set to NULL.

Leave codes

This function cannot fail for any of the non-Long column types. It can leave if it encounters any of the general errors described in the class overview.

TAccess

Description

Specifies which operations can be performed on a rowset.

EUpdatable All operations can be performed on the rowset. EReadOnly Row navigation and reading are permitted. EInsertOnly Inserting new rows is the only valid operation on the rowset.

TAccuracy

Description

Specifies whether the CountL() function should ensure that it returns the exact value — which may be a non-trivial task.

EEnsure Take the time, if necessary, to return the exact value. EQuick Return any immediately available value.

TDirection

Description

Specifies the direction to search through the rowset when using the FindL() function.

EForwards Search from the current row forwards through the set. EBackwards Search from the current row backwards through the set.

TPosition

Description

Specifies where the rowset should navigate to in the GotoL() function. Their use is encapsulated by the respective member functions FirstL(), NextL() etc.

EFirst Move to the first row in the rowset. ENext Move to the next row in the rowset. EPrevious Move to the previous row in the rowset. ELast Move to the last row in the rowset. EBeginning Move to the position before the first row in the rowset. EEnd Move to the position after the last row in the rowset.