Symbian
Symbian OS Library

SYMBIAN OS V9.3

[Index] [Spacer] [Previous] [Next]

Location: D32DBMS.H
Link against: edbms.lib

Class RDbIncremental

class RDbIncremental;

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.

Members

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

Member functions

Close()

IMPORT_C 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.

Next()

IMPORT_C TInt Next(TInt &aStep);

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.

Next()

IMPORT_C void Next(TPckgBuf< TInt > &aStep, TRequestStatus &aStatus);

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.

See also:

Recover()

Capability: Security policy note: For a secure shared database, the caller must satisfy the schema access policy for the database.

IMPORT_C TInt Recover(RDbDatabase &aDatabase, TInt &aStep);

Description

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.

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.

See also:

Compact()

Capability: Security policy note: For a secure shared database, the caller must satisfy the schema access policy for the database.

IMPORT_C TInt Compact(RDbDatabase &aDatabase, TInt &aStep);

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.

See also:

DropTable()

Capability: Security policy note: For a secure shared database, the caller must satisfy the schema access policy for the database.

IMPORT_C TInt DropTable(RDbDatabase &aDatabase, const TDesC &aTable, TInt &aStep);

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.

See also:

AlterTable()

Capability: Security policy note: For a secure shared database, the caller must satisfy the schema access policy for the database.

IMPORT_C 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.

See also:

CreateIndex()

Capability: Security policy note: For a secure shared database, the caller must satisfy the schema access policy for the database.

IMPORT_C TInt CreateIndex(RDbDatabase &aDatabase, const TDesC &aName, const TDesC &aTable, const CDbKey &aKey, TInt &aStep);

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.

See also:

DropIndex()

Capability: Security policy note: For a secure shared database, the caller must satisfy the schema access policy for the database.

IMPORT_C TInt DropIndex(RDbDatabase &aDatabase, const TDesC &aName, const TDesC &aTable, TInt &aStep);

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

See also:

Execute()

Capability: Security policy note: For a secure shared database, the caller must satisfy:

inline TInt Execute(RDbDatabase &aDatabase, const TDesC &aSql, TInt &aStep);

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.

See also:

Execute()

Capability: Security policy note: For a secure shared database, the caller must satisfy:

IMPORT_C TInt Execute(RDbDatabase &aDatabase, const TDesC &aSql, TDbTextComparison aComparison, TInt &aStep);

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.

See also:

UpdateStats()

Capability: Security policy note: For a secure shared database, the caller must satisfy the schema access policy for the database.

IMPORT_C TInt UpdateStats(RDbDatabase &aDatabase, TInt &aStep);

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.

See also:

[Previous] [Top] [Next]