HTML5 Database
This object provides functions to manipulate client-side databases using SQL.
Supported Platform(s)
- BlackBerry OS 5.0+
- BlackBerry PlayBook
- Ripple Emulator
| API | OS 5.0 | OS 6.0 | OS 7.0 | PlayBook | Ripple |
|---|---|---|---|---|---|
| window.openDatabase | Y | Y | Y | Y | Y |
| changeVersion | Y | Y | Y | Y | Y |
| readTransaction | Y | Y | Y | Y | Y |
| transaction | Y | Y | Y | Y | Y |
| version | Y | Y | Y | Y | Y |
Configuration Document Settings
To use all of the API described for this object, you must ensure the following settings are in your configuration document:
This API does not require a <feature> element to be declared in the configuration document of your BlackBerry WebWorks Application.| Permission Elements (PlayBook Only) |
|---|
| This API does not require a <permission> element to be declared in the configuration document of your BlackBerry WebWorks Application. |
API Summary
Constructors
Functions
Properties
window.openDatabase
| window.openDatabase (name : String, version : String, displayName : String, estimatedSize : Number, creationCallback : function) |
Supported Platform(s)
- BlackBerry OS 5.0+- BlackBerry PlayBook
- Ripple Emulator
Description
Creates a new databse object. If the database already exists, the existing database will be returned and the creation callback will not be invoked.
| Parameter | Type | Description |
|---|---|---|
| name | String | The name of the database to be created |
| version | String | The version of the database to be created |
| displayName | String | The display name of the database to be created |
| estimatedSize | Number | The estimated size in bytes of the database |
| creationCallback | function(database : Database) |
The callback will be invoked when the database is first created.
database: The newly created database |
Code Example(s)
Database db=window.openDatabase('documents', '1.0', 'Offline document storage', 5*1024*1024, null);
changeVersion
| void changeVersion(oldVersion : String, newVersion : String, callback : function, [errorCallback: function], [successCallback: function]) |
Supported Platform(s)
- BlackBerry OS 5.0+- BlackBerry PlayBook
- Ripple Emulator
Description
This method allows scripts to atomically verify the version number and change it at the same time as doing a schema update. When the method is invoked, it immediately returns, and then asynchronously runs the transaction steps with the transaction callback being the third argument, the error callback being the fourth argument, the success callback being the fifth argument. If any of the optional arguments are omitted, then they are treated as if they were null.
| Parameter | Type | Description |
|---|---|---|
| oldVersion | String | database's current version. |
| newVersion | String | database's new version. |
| callback | function(transaction : SQLTransaction) |
Function to be called when executing SQL statements.
transaction: The transaction to be executed. |
| errorCallback |
function(error : SQLError)
Optional |
Function to be called when an SQL error occurs.
error: The SQLError object describing the SQL error that occurred. |
| successCallback |
function()
Optional |
Function to be called when SQL statement is executed successfully. |
Code Example(s)
db.changeVersion('', '1.0', function (t) {...});
readTransaction
| void readTransaction(callback : function, [errorCallback: function], [successCallback: function]) |
Supported Platform(s)
- BlackBerry OS 5.0+- BlackBerry PlayBook
- Ripple Emulator
Description
When called, this method immediately returns and then asynchronously runs the transaction steps with the transaction callback being the first argument, the error callback being the second argument, if any, the success callback being the third argument, if any, and with no preflight operation or postflight operation. The mode is read-only.
| Parameter | Type | Description |
|---|---|---|
| callback | function(transaction : SQLTransaction) |
Function to be called when executing SQL statements.
transaction: The transaction to be executed. |
| errorCallback |
function(error : SQLError)
Optional |
Function to be called when an SQL error occurs.
error: The SQLError object describing the SQL error that occurred. |
| successCallback |
function()
Optional |
Function to be called when SQL statement is executed successfully. |
Code Example(s)
function showDocCount(db, span) {
db.readTransaction(
function (t) {
t.executeSql('SELECT COUNT(*) AS c FROM docids', [],
function (t, r) {
span.textContent = r.rows[0].c;
},
function (t, e) {
// couldn't read database
span.textContent = '(unknown: ' + e.message + ')';
}
);
}
);
}
transaction
| void transaction(callback : function, [errorCallback: function], [successCallback: function]) |
Supported Platform(s)
- BlackBerry OS 5.0+- BlackBerry PlayBook
- Ripple Emulator
Description
When called, this method immediately returns and then asynchronously runs the transaction steps with the transaction callback being the first argument, the error callback being the second argument, if any, the success callback being the third argument, if any, and with no preflight operation or postflight operation. The mode is read/write.
| Parameter | Type | Description |
|---|---|---|
| callback | function(transaction : SQLTransaction) |
Function to be called when executing SQL statements.
transaction: The transaction to be executed. |
| errorCallback |
function(error : SQLError)
Optional |
Function to be called when an SQL error occurs.
error: The SQLError object describing the SQL error that occurred. |
| successCallback |
function()
Optional |
Function to be called when SQL statement is executed successfully. |
Properties:
| Property | Type | Description | Supported Platform(s) |
|---|---|---|---|
| version |
String
readonly |
The current version of the database.
|
- BlackBerry OS 5.0+
- BlackBerry PlayBook - Ripple Emulator |