#include <d32dbms.h>
| class RDbIncremental |
| Public Member Functions | |
|---|---|
| IMPORT_C TInt | AlterTable(RDbDatabase &, const TDesC &, const CDbColSet &, TInt &) |
| IMPORT_C void | Close() |
| IMPORT_C TInt | Compact(RDbDatabase &, TInt &) |
| IMPORT_C TInt | CreateIndex(RDbDatabase &, const TDesC &, const TDesC &, const CDbKey &, TInt &) |
| IMPORT_C TInt | DropIndex(RDbDatabase &, const TDesC &, const TDesC &, TInt &) |
| IMPORT_C TInt | DropTable(RDbDatabase &, const TDesC &, TInt &) |
| TInt | Execute(RDbDatabase &, const TDesC &, TInt &) |
| IMPORT_C TInt | Execute(RDbDatabase &, const TDesC &, TDbTextComparison, TInt &) |
| IMPORT_C TInt | Next(TInt &) |
| IMPORT_C void | Next(TPckgBuf< TInt > &, TRequestStatus &) |
| IMPORT_C TInt | Recover(RDbDatabase &, TInt &) |
| IMPORT_C TInt | UpdateStats(RDbDatabase &, TInt &) |
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.
| IMPORT_C TInt | AlterTable | ( | RDbDatabase & | aDatabase, |
| const TDesC & | aTable, | |||
| const CDbColSet & | aNewDef, | |||
| TInt & | aStep | |||
| ) | ||||
Initiates a table alteration operation on a database. This is the incremental form of RDbDatabase::AlterTable().
See also: RDbDatabase::AlterTable()
| Parameter | Description |
|---|---|
| aDatabase | The database which has the table to be altered. |
| aTable | The name of the table which is to be altered. |
| aNewDef | A column set describing the new definition for the table. |
| aStep | On return, contains the initial step count for the incremental operation. This value should be passed in to subsequent calls to NextL(). |
Returns: 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.
| IMPORT_C void | Close | ( | ) |
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.
| IMPORT_C TInt | Compact | ( | RDbDatabase & | aDatabase, |
| TInt & | aStep | |||
| ) | ||||
Initiates the operation of compacting a database. This is the incremental form of RDbDatabase::Compact().
See also: RDbDatabase::Compact()
| Parameter | Description |
|---|---|
| aDatabase | The database to compact. |
| 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. |
Returns: KErrNone if successful, otherwise another of the system-wide error codes.
| IMPORT_C TInt | CreateIndex | ( | RDbDatabase & | aDatabase, |
| const TDesC & | aName, | |||
| const TDesC & | aTable, | |||
| const CDbKey & | aKey, | |||
| TInt & | aStep | |||
| ) | ||||
Initiates an index creation operation on a database. This is the incremental form of RDbDatabase::CreateIndex().
See also: RDbDatabase::CreateIndex()
| Parameter | Description |
|---|---|
| aDatabase | The database on which to create the index. |
| aName | A name for the created index. |
| aTable | The name of the table on which to create the index. |
| aKey | The key for the new index. |
| aStep | On return, contains the initial step count for the incremental operation. This value should be passed in to subsequent calls to NextL(). |
Returns: 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.
| IMPORT_C TInt | DropIndex | ( | RDbDatabase & | aDatabase, |
| const TDesC & | aName, | |||
| const TDesC & | aTable, | |||
| TInt & | aStep | |||
| ) | ||||
Initiates an index discard operation on the database. This is the incremental form of RDbDatabase::DropIndex().
See also: RDbDatabase::DropIndex()
| Parameter | Description |
|---|---|
| aDatabase | The database from which to drop the index. |
| aName | The name of the index to drop. |
| aTable | The name of the table which has the index. |
| aStep | On return, contains the initial step count for the incremental operation. This value should be passed in to subsequent calls to NextL(). |
Returns: KErrNone if successful, or one of the DBMS database error codes. Specifically, the function returns KErrNotFound if the table or index does not exist
| IMPORT_C TInt | DropTable | ( | RDbDatabase & | aDatabase, |
| const TDesC & | aTable, | |||
| TInt & | aStep | |||
| ) | ||||
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().
See also: RDbDatabase::DropTable()
| Parameter | Description |
|---|---|
| aDatabase | The database from which to drop the table. |
| aTable | The name of the table to drop. |
| aStep | On return, contains the initial step count for the incremental operation. This value should be passed in to subsequent calls to NextL(). |
Returns: KErrNone if successful, or one of the DBMS database error codes. The Store database always returns KErrNotSupported for this function.
| TInt | Execute | ( | RDbDatabase & | aDatabase, |
| const TDesC & | aSql, | |||
| TInt & | aStep | |||
| ) | [inline] | |||
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.
See also: RDbDatabase::Execute() RDbUpdate
the schema access policy for the database, if the SQL statement is CREATE/DROP/ALTER;
the write access policy for the table in the SQL, if the SQL statement is INSERT/UPDATE/DELETE;
| Parameter | Description |
|---|---|
| aDatabase | The database on which the DDL (SQL schema update) statement is to execute. |
| aSql | The DDL SQL statement to be executed on the database. |
| 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. |
Returns: KErrNone if successful, otherwise another of the system-wide error codes.
| IMPORT_C TInt | Execute | ( | RDbDatabase & | aDatabase, |
| const TDesC & | aSql, | |||
| TDbTextComparison | aComparison, | |||
| TInt & | aStep | |||
| ) | ||||
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.
See also: RDbDatabase::Execute() RDbUpdate
the schema access policy for the database, if the SQL statement is CREATE/DROP/ALTER;
the write access policy for the table in the SQL, if the SQL statement is INSERT/UPDATE/DELETE;
| Parameter | Description |
|---|---|
| aDatabase | The database on which the DDL (SQL schema update) statement is to execute. |
| aSql | The DDL SQL statement to be executed on the database. |
| 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. |
| 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. |
Returns: KErrNone if successful, otherwise another of the system-wide error codes.
Performs the next step in the incremental operation, returning when the step is complete.
| Parameter | Description |
|---|---|
| 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. |
Returns: 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.
| IMPORT_C void | Next | ( | TPckgBuf< TInt > & | aStep, |
| TRequestStatus & | aStatus | |||
| ) | ||||
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.
See also: TPckgBuf
| Parameter | Description |
|---|---|
| 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. |
| 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. |
| IMPORT_C TInt | Recover | ( | RDbDatabase & | aDatabase, |
| TInt & | aStep | |||
| ) | ||||
Initiates a database recovery operation.
This is the incremental version of RDbDatabase::Recover(). Recover() will try to rebuild database indexes if they are broken. If the database data is corrupted, it cannot be recovered.
See also: RDbDatabase::Recover()
| Parameter | Description |
|---|---|
| aDatabase | The database to recover. |
| aStep | On return, contains the initial step count for the incremental operation. This value should be passed in to subsequent calls to NextL(). |
Returns: 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.
| IMPORT_C TInt | UpdateStats | ( | RDbDatabase & | aDatabase, |
| TInt & | aStep | |||
| ) | ||||
Initiates the operation of calculating and updating database statistics.
This is the incremental form of RDbDatabase::UpdateStats()
See also: RDbDatabase::UpdateStats()
| Parameter | Description |
|---|---|
| aDatabase | The database whose statistics are to be updated. |
| 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. |
Returns: KErrNone if successful, otherwise another of the system-wide error codes.