openDatabase

Database

Creates or opens a database and returns a new DatabaseShell object or DBError object in callback.

$m.openDatabase("mydb",function(r){

if(r.database){

// Successful database connection

}else{

// Database opening failed

}

})

Syntax

        $m.openDatabase(name,callback[,version,password,level])

Parameters

name

String (required)

Name of the database to be opened

callback

function (required)

Callback function when openDatabase finishes execution. Provided with the response object with the DatabaseShell object or DBError object

version

String (optional)

Version of the database

password

String (optional)

Password of the database.

                

level

Integer(optional)

The level specifies the storage level at which the database file is created.The are three possible levels:

    DB_PACK_LEVEL = 0 . Creates database file at pack level
    DB_PACK_LEVEL = 1 . Creates database file at application level
    DB_PACK_LEVEL = 3 . Creates database file at root level.This indicates the path to database file specified is the absolute path to the file in device.

By default, database file is created at the pack level.

Database

Database object provides methods to execute individual sqls and transactions.

executeSql

Queues a specified sql query for execution. Provides a DBResultset object in success callback or DBError

$m.executeSql("create table sample(id int primary key,description varchar(100))",select_callback,error_callback,null);

$m.executeSql("select * from sample,select_callback,error_callback");

$m.executeSql("insert into sample (id,description) values(1,'first')",insert_callback,error_callback);

$m.executeSql("insert into sample (id,description) values (?,?)",insert_callback,error_callback,[2,"second"]);

$m.executeSql("delete from sample where id = ?",delete_callback,error_callback,[2]);

function success_callback(resultSet){

        $m.logDebug("Num of rows:  " + resultSet.rows.length );

}

function insert_callback(resultSet){

        $m.logDebug("Last Insert Row Id:  " + resultSet.insertId );

}

function insert_callback(resultSet){

        $m.logDebug("Rows Affected:  " + resultSet.rowsAffected );

}

function error_callback(error){

        $m.logError("Query failed .Error code: " + error.code + " Message: " + error.message);

        

}

Syntax

db.executeSql(sql,success_callback,error_callback,params)

sql

String (Required)

Sql query string to be executed.Can include placeholders.

success_callback

Function (Required)

Callback function passing DBResultset object.

error_callback

Function (Required)

Callback function passing DBError object.

params

Array (Optional)

Array of values to be substituted in place of parameters/placeholders.

transaction

Provides a callback with DBTransaction object to build up sql queries which execute as transaction.

If all queries succeed ,transaction will be committed and success callback if any is invoked.

If any query fails,error callback if any,for the query is invoked with transaction object and DBError object instance as arguments.

Further queries are ignored and transaction is rolled back. In this case database state is rolled back to the point prior to the call of this transaction.

Syntax

db.transaction(process,success_callback,error_callback);

success_callback

Function (Required)

Callback function which receives DBTransaction object to build up queries to execute in the scope of transaction.

success_callback

Function (Required)

Callback function invoked when the transaction is successful.

error_callback

Function (Required)

Callback function invoked when the transaction is successful. It gets the following arguments:

    DBTransaction object in which the transaction is executed
    DBError object containing information about error. See Error Handling

DBTransaction

It contains method for executing a sql query in this scope of this transaction.The queries are queued up and executed as a transaction.As in a database transaction,either all queries execute and committed  or the database state is rolled back to its state prior to transaction.

executeSql

txn.executeSql("insert into sample (id,description) values (?,?)",success_callback,error_callback,[2,"second"]);

                        

function success_callback(dbTransaction,resultSet){

        $m.logDebug("Query successful");

        $m.logDebug("Result set : " + resultSet);

}

function error_callback(error){

        $m.logDebug("Error - Code : " + error.code + " Message: " + error.message);

}

Syntax 

txn.executeSql(sql,params,success_callback,error_callback)

                        

sql

String (Required)

SQL query to be executed

                

params

Array (Optional)

Array of values to be substituted for placeholders.

success_callback

Function (Required)

Callback function to execute when the query execution is successful.It gets a DBTransaction instance and DBResultset(See DBResultset) object with result details.

error_callback

Function (Required)

Callback function to execute when query fails.It gets DBError object instance as argument.

                        

Note: Transactions are not supported on Android and Blackberry.

DBResultset

Represents a resultset of query.It is provided in the success callback function of Database.executeSql method and transaction.executeSql methods.

db.executeSql("select field1,field2,time from sample_table",success_callback,error_callback);

function success_callback(resultset){

        $m.logDebug("Rows returned: " + resultset.rowsAffected);

        for(var i=0;i<rows.length;++i){

                var row = rows[i];

                $m.logDebug("Field1 : " + row.field1 + " Field 2: " + row.field2);

        }

}

Properties

insertId

String

Last insert row id for the database connection on which query executed.

rowsAffected

Integer

Number of rows affected by the sql query execution.

rows

Array

Array of objects. Usually,set when it is a result of select query. Each object in array is a mapping to the row returned from sql. The columns of the sql result set maps to the object properties.

Error Handling

Errors occurred during sql query execution or transaction are passed to the callbacks with DBError object.

The following are the applicable error codes:

Code      Code Name

100        DBError.SQL_ERR

1000      DBError.UNKNOWN_ERR

2000      DBError.DATABASE_ERR

3000      DBError.VERSION_ERR

4000      DBError.TOO_LARGE_ERR

5000      DBError.QUOTA_ERR

6000      DBError.SYNTAX_ERR

7000      DBError.CONSTRAINT_ERR

8000      DBError.TIMEOUT_ERR


DBError        

Represents an error containing information about failure in query or transaction execution.

Properties

code

Integer

Error code .Value can be one among error codes.

message

String

Description about the error occured when operating on database