RDbIncremental in DBMS Database Incremental Operations

RDbIncremental

Support

Supported from 5.0

Description

Provides the interface for performing long-running database operations in incremental steps, allowing application programs to remain responsive to other events.

After an operation has begun, a standard interface is used to continue and complete all incremental operations. On successful return from one of the initiating functions, a step value is also returned. This gives the progress indication and is, initially, positive. This value should be passed into subsequent steps in the operation, each of which may decrement the value by some amount, although they are allowed to leave it unchanged. The value reaches zero, if, and only if the operation completes.

While an incremental operation is in progress, the database cannot be used for any other operations such as opening tables or preparing views.

Starting an incremental operation also requires that no rowsets are open on the database and that no commit is pending for data manipulation transactions.

If no explicit transaction has been started by the database, then an automatic transaction is begun when any incremental operation is started and is committed when complete or rolled back if the operation either fails or is abandoned prior to completion.

Defined in RDbIncremental:
AlterTable(), Close(), Compact(), CreateIndex(), DropIndex(), DropTable(), Execute(), Execute(), Next(), Next(), Recover(), UpdateStats()

void Close();

Description

Releases the resources used by the incremental operations object. If the operation is not yet complete, then the operation is abandoned and the database is rolled back to its state before the operation started.

TInt AlterTable(RDbDatabase& aDatabase,const TDesC& aTable,const CDbColSet& aNewDef,TInt& aStep);

Description

Initiates a table alteration operation on a database. This is the incremental form of RDbDatabase::AlterTable().

Parameters

`RDbDatabase& aDatabase`	The database which has the table to be altered.
`const TDesC& aTable`	The name of the table which is to be altered.
`const CDbColSet& aNewDef`	A column set describing the new definition for the table.
`TInt& aStep`	On return, contains the initial step count for the incremental operation. This value should be passed in to subsequent calls to `NextL()`.

Return value

TInt

KErrNone if successful, or one of the DBMS database error codes. Specifically, the function returns: KErrNotFound, if the table does not exist in the database. KErrBadName if a column name is invalid. KErrArgument if the new column set is empty, or there are duplicate column names, or if a column's maximum length is non-positive but not KDbUndefinedLength, or a non-numeric column has the auto-increment attribute, or an indexed column has been dropped, or a column has changed its type or attributes, or a not-null or auto-increment column has been added to a table which is not empty. KErrNotSupported if a column type is out of the recognised range, or an unknown attribute bit is set, or the maximum length for a Text8, Text16 or Binary column is more than 255. KErrTooBig if the resulting record size can be larger than 8200 bytes.

Description

Initiates the operation of compacting a database. This is the incremental form of RDbDatabase::Compact().

Parameters

`RDbDatabase& aDatabase`	The database to compact.
`TInt& aStep`	On return, contains the initial step count for the incremental operation. This value should be passed in to subsequent calls to `Next()` to continue the operation.

Return value

TInt

KErrNone if successful, otherwise another of the system-wide error codes.

Description

Initiates an index creation operation on a database. This is the incremental form of RDbDatabase::CreateIndex().

Parameters

`RDbDatabase& aDatabase`	The database on which to create the index.
`const TDesC& aName`	A name for the created index.
`const TDesC& aTable`	The name of the table on which to create the index.
`const CDbKey& aKey`	The key for the new index.
`TInt& aStep`	On return, contains the initial step count for the incremental operation. This value should be passed in to subsequent calls to `NextL()`.

Return value

TInt

KErrNone if successful, or one of the DBMS database error codes. Specifically, the function returns: KErrNotFound if the table does not exist in the database or a key column is not found in the table. KErrAlreadyExists if an index of the same name already exists on table or a duplicate key is present when building an index. Note that it is not possible to tell the difference between the possible causes of this error if index creation is not carried out incrementally. KErrBadName if an index or column name is invalid. KErrArgument if the key has no key columns or a fixed width column has a truncation length specified, or an invalid truncation length has been specified for a key column, or a LongText8 or LongText16 key column has no truncation length specified, or the key contains a Binary or LongBinary column. KErrNotSupported if a truncated key column is not the last one. KErrTooBig if the resulting key size is too big.

Description

Initiates an index discard operation on the database. This is the incremental form of RDbDatabase::DropIndex().

Parameters

`RDbDatabase& aDatabase`	The database from which to drop the index.
`const TDesC& aName`	The name of the index to drop.
`const TDesC& aTable`	The name of the table which has the index.
`TInt& aStep`	On return, contains the initial step count for the incremental operation. This value should be passed in to subsequent calls to `NextL()`.

Return value

TInt

KErrNone if successful, or one of the DBMS database error codes. Specifically, the function returns KErrNotFound if the table or index does not exist

Description

Initiates a table discard operation on a database. All indexes belonging to the table are also discarded as part of this operation.

This is the incremental version of RDbDatabase::DropTable().

Parameters

`RDbDatabase& aDatabase`	The database from which to drop the table.
`const TDesC& aTable`	The name of the table to drop.
`TInt& aStep`	On return, contains the initial step count for the incremental operation. This value should be passed in to subsequent calls to `NextL()`.

Return value

TInt

KErrNone if successful, or one of the DBMS database error codes. The Store database always returns KErrNotSupported for this function.

Description

Initiates the execution of a DDL (SQL schema update) statement on the database.

This is the incremental form of RDbDatabase::Execute().

Note that to begin executing a DML (SQL data update) statement incrementally, use the RDbUpdate class.

Parameters

`RDbDatabase& aDatabase`	The database on which the DDL (SQL schema update) statement is to execute.
`const TDesC& aSql`	The DDL SQL statement to be executed on the database.
`TInt& aStep`	On return, contains the initial step count for the incremental operation. This value should be passed in to subsequent calls to `Next()` to continue the operation.

Return value

TInt

KErrNone if successful, otherwise another of the system-wide error codes.

Description

Initiates the execution of a DDL (SQL schema update) statement on the database, specifing additional comparison operations for some SQL statements.

This is the incremental form of RDbDatabase::Execute().

Note that to begin executing a DML (SQL data update) statement incrementally, use the RDbUpdate class.

Parameters

`RDbDatabase& aDatabase`	The database on which the DDL (SQL schema update) statement is to execute.
`const TDesC& aSql`	The DDL SQL statement to be executed on the database.
`TDbTextComparison aComparison`	This argument is used in the execution of some SQL statements, and is ignored in all other SQL statements. Specifically: in CREATE INDEX statements, it specifies the comparison operation used for text columns in the index key. In UPDATE and DELETE statements, it specifies the comparison operation used to evaluate the WHERE clause.
`TInt& aStep`	On return, contains the initial step count for the incremental operation. This value should be passed in to subsequent calls to `Next()` to continue the operation.

Return value

TInt

KErrNone if successful, otherwise another of the system-wide error codes.

Description

Initiates a database recovery operation.

This is the incremental version of RDbDatabase::Recover().

Parameters

`RDbDatabase& aDatabase`	The database to recover.
`TInt& aStep`	On return, contains the initial step count for the incremental operation. This value should be passed in to subsequent calls to `NextL()`.

Return value

TInt

KErrNone if successful, or one of the DBMS database error codes. If recovery fails with either KErrNoMemory or KErrDiskFull, then recovery may be attempted again when more memory or disk space is available.

Description

Initiates the operation of calculating and updating database statistics.

This is the incremental form of RDbDatabase::UpdateStats()

Parameters

`RDbDatabase& aDatabase`	The database whose statistics are to be updated.
`TInt& aStep`	On return, contains the initial step count for the incremental operation. This value should be passed in to subsequent calls to `Next()` to continue the operation.

Return value

TInt

KErrNone if successful, otherwise another of the system-wide error codes.

Description

Performs the next step in the incremental operation, returning when the step is complete.

Parameters

TInt& aStep

Initially, contains the value returned from any of the initiating functions or the last call to perform an operational step. On return, contains a value which is less than or equal to the initial value. If it equals 0, then the operation has completed successfully and the incremental object should be closed.

Return value

TInt

KErrNone if successful, or one of the DBMS database error codes. If this indicates an error, then the incremental object should be closed and the operation aborted.

Description

Performs the next step in the incremental operation, returning immediately and signalling the request status when the step is complete.

This function is most effectively used when the incremental operation is packaged as an active object.

Note that the step parameter is packaged to enable this API to work for asynchronous calls in client/server implementations of DBMS.

Parameters

`TPckgBuf<TInt>& aStep`	Initially, contains the value returned from any of the initiating functions or the last call to perform an operational step. On return, contains a value which is less than or equal to the initial value. If it equals `0`, then the operation has completed successfully and the incremental object should be closed.
`TRequestStatus& aStatus`	The request status used to contain completion information for the function. On completion, contains the completion status or one of the DBMS database error codes. If this indicates an error, then the incremental object should be closed and the operation aborted.

Class RDbIncremental

Support

Description

Release resources

Close()

Description

Starting incremental operations

AlterTable()

Description

Parameters

Return value

See also:

Compact()

Description

Parameters

Return value

See also:

CreateIndex()

Description

Parameters

Return value

See also:

DropIndex()

Description

Parameters

Return value

See also:

DropTable()

Description

Parameters

Return value

See also:

Execute()

Description

Parameters

Return value

See also:

Execute()

Description

Parameters

Return value

See also:

Recover()

Description

Parameters

Return value

See also:

UpdateStats()

Description

Parameters

Return value

See also:

Continuing the operation

Next()

Description

Parameters

Return value

See also:

Next()

Description

Parameters

See also:

Class `RDbIncremental`

`Close()`

`AlterTable()`

`Compact()`

`CreateIndex()`

`DropIndex()`

`DropTable()`

`Execute()`

`Execute()`

`Recover()`

`UpdateStats()`

`Next()`

`Next()`