HTML5 Database - BlackBerry WebWorks

Supported Platform(s)

- BlackBerry OS 5.0+

- BlackBerry PlayBook 1.0+

- BlackBerry 10

- Ripple Emulator

View Supported Platform Table

API	BB5.0	BB6.0	BB7.0	PB1.0	PB2.0	BB10	Ripple
window.openDatabase	Y	Y	Y	Y	Y	Y	Y
changeVersion	Y	Y	Y	Y	Y	Y	Y
readTransaction	Y	Y	Y	Y	Y	Y	Y
transaction	Y	Y	Y	Y	Y	Y	Y
version	Y	Y	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 and BlackBerry 10+)
This API does not require a <permission> element to be declared in the configuration document of your BlackBerry WebWorks Application.

Constructors

window.openDatabase (name : String, version : String, displayName : String, estimatedSize : Number, creationCallback : function)

Creates a new database object. If the database already exists, the existing database will be returned and the creation callback will not be invoked.

Note: A SD card is the required method of storage for databases for 5.x devices

Supported Platforms
	- BlackBerry OS 5.0+
	- BlackBerry PlayBook 1.0+
	- BlackBerry 10
	- Ripple Emulator

Parameters
name	The name of the database to be created
version	The version of the database to be created
displayName	The display name of the database to be created
estimatedSize	The estimated size in bytes of the database
creationCallback	The callback will be invoked when the database is first created. database: The newly created database

Code Example:

Database db = window.openDatabase('documents', '1.0', 'Offline document storage', 5*1024*1024);

/**

//Create a namespace to hold our database variable
if (typeof mynamespace === 'undefined') {
    mynamespace = {};
}

(function () {

    //This method is only called once (the first time the database is created)
    function onDBCreate(database) {
        //Attach the database because "window.openDatabase" would not have returned it
        mynamespace.db = database;
        database.transaction(
            function (tx) {tx.executeSql('CREATE TABLE tbl_name (key int unique, name text)',
                [],
                function (tx, res) {
                    alert("Table Created Successfully");
                },
                function (tx, err) {
                    alert("ERROR - Table creation failed - code: " + err.code + ", message: " + err.message);
                });
            }
        );
    }

    if (window.openDatabase) {
        //Will either return the existing database or null and call our creation callback onDBCreate
        mynamespace.db = window.openDatabase('awesome', '1.0', 'The most awesome database ever', 5 * 1024 * 1024, onDBCreate);
    } else {
        alert("This device does not have HTML5 Database support");
    }
}());

Functions

void changeVersion (oldVersion : String, newVersion : String, callback: function(transaction : SQLTransaction), [errorCallback: function(error : SQLError)], [successCallback: function()])

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.

Supported Platforms
	- BlackBerry OS 5.0+
	- BlackBerry PlayBook 1.0+
	- BlackBerry 10
	- Ripple Emulator

Parameters
oldVersion	database's current version.
newVersion	database's new version.
callback	Function to be called when executing SQL statements. transaction: The transaction to be executed.
errorCallback	Function to be called when an SQL error occurs. error: The SQLError object describing the SQL error that occurred.
successCallback	Function to be called when SQL statement is executed successfully.

Code Example:

db.changeVersion('', '1.0', function (t) {...});

void readTransaction (callback: function(transaction : SQLTransaction), [errorCallback: function(error : SQLError)], [successCallback: function()])

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.

Supported Platforms
	- BlackBerry OS 5.0+
	- BlackBerry PlayBook 1.0+
	- BlackBerry 10
	- Ripple Emulator

Parameters
callback	Function to be called when executing SQL statements. transaction: The transaction to be executed.
errorCallback	Function to be called when an SQL error occurs. error: The SQLError object describing the SQL error that occurred.
successCallback	Function to be called when SQL statement is executed successfully.

Code Example:

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 + ')';
				}
			);
		}
	);
}

void transaction (callback: function(transaction : SQLTransaction), [errorCallback: function(error : SQLError)], [successCallback: function()])

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.

Supported Platforms
	- BlackBerry OS 5.0+
	- BlackBerry PlayBook 1.0+
	- BlackBerry 10
	- Ripple Emulator

Parameters
callback	Function to be called when executing SQL statements. transaction: The transaction to be executed.
errorCallback	Function to be called when an SQL error occurs. error: The SQLError object describing the SQL error that occurred.
successCallback	Function to be called when SQL statement is executed successfully.

Properties

readonly String version

The current version of the database.

Supported Platforms
	- BlackBerry OS 5.0+
	- BlackBerry PlayBook 1.0+
	- BlackBerry 10
	- Ripple Emulator