Skip to main content

Visit Mozilla.org

mozIStorageStatement

From MDC

This article covers features introduced in Firefox 2

The mozIStorageStatement interface lets you create and execute SQL statements on a SQLite database.

For an introduction see Storage.

Contents

mozIStorageStatement is defined in storage/public/mozIStorageStatement.idl. It is scriptable and unfrozen (hasn't changed since Mozilla 1.8).

Inherits from: nsISupports

Note: If you are familiar with SQLite, you may know that prepared statements are invalidated when the schema of the database changes. Fortunately, mozIStorageStatement detects this error and will recompile the statement as needed. Therefore, once you create a statement, you don't need to worry about changing the schema; all statements will continue to transparently work. .

[edit] Method overview

void initialize(in mozIStorageConnection aDBConnection, in AUTF8String aSQLStatement);
void finalize();
mozIStorageStatement clone();
AUTF8String getParameterName(in unsigned long aParamIndex);
unsigned long getParameterIndex(in AUTF8String aName);
AUTF8String getColumnName(in unsigned long aColumnIndex);
unsigned long getColumnIndex(in AUTF8String aName);
void reset();
void bindUTF8StringParameter(in unsigned long aParamIndex, in AUTF8String aValue);
void bindStringParameter(in unsigned long aParamIndex, in AString aValue);
void bindDoubleParameter(in unsigned long aParamIndex, in double aValue);
void bindInt32Parameter(in unsigned long aParamIndex, in long aValue);
void bindInt64Parameter(in unsigned long aParamIndex, in long long aValue);
void bindNullParameter(in unsigned long aParamIndex);
void bindBlobParameter(in unsigned long aParamIndex, [array,const,size_is(aValueSize)] in octet aValue, in unsigned long aValueSize);
void execute();
boolean executeStep();
AString escapeStringForLIKE(in AString aValue, in wchar aEscapeChar);

[edit] Attributes

Attribute Type Description
parameterCount unsigned long Number of parameters.
columnCount unsigned long Number of columns returned.
state long The current state.

[edit] Constants

Constant Value Description
MOZ_STORAGE_STATEMENT_INVALID 0 The SQL statement is Invalid.
MOZ_STORAGE_STATEMENT_READY 1 The SQL statement is ready to be executed.
MOZ_STORAGE_STATEMENT_EXECUTING 2 The SQL statement is executing at the moment.

[edit] Methods

[edit] initialize()

Initialize this query with the given SQL statement. 

 void initialize(
   in mozIStorageConnection aDBConnection, 
   in AUTF8String aSQLStatement
 );
[edit] Parameters
aDBConnection
A mozIStorageConnection database connection.
aSQLStatement
String key representing the SQL statement.

[edit] finalize()

Finalizes a statement so you can successfully close a database connection. since Gecko 1.9 M9 

void finalize();
[edit] Parameters

None.

Note: This method does not need to be used from native callers since you can just set the statement to null, but is extremely useful to JS callers.

[edit] clone()

Creates a clone of the given statement, by initializing a new statement with the same connection and same SQL statement as specified one. It does not preserve statement state; that is, if a statement is being executed when it is cloned, the new statement will not be executing. 

mozIStorageStatement clone();
[edit] Parameters

None.

[edit] Return value

A mozIStorageConnection representing the clone of the SQL statement.

[edit] getParameterName()

Obtains the name of the parameter for the specified index. 

 AUTF8String getParameterName(
   in unsigned long aParamIndex
 );
[edit] Parameters
aParamIndex
Parameter's index.
[edit] Return value

An AUTF8String representing the parameter name for the specified index.

[edit] getParameterIndex()

Obtains the index of the parameter with the specified name. 

 unsigned long getParameterIndex(
   in AUTF8String aName
 );
[edit] Parameters
aName
Name of the parameter.
[edit] Return value

Returns the index of the parameter with the specified name.

[edit] getColumnName()

Obtains the name of the column for the specified index. 

 AUTF8String getColumnName(
   in unsigned long aColumnIndex
 );
[edit] Parameters
aColumnIndex
Column's index
[edit] Return value

An AUTF8String representing the column name for the specified index.

[edit] getColumnIndex()

Obtains the index of the column with the specified name. 

 unsigned long getColumnIndex(
   in AUTF8String aName
 );
[edit] Parameters
aName
Name of the column.
[edit] Return value

Returns the index of the column with the specified name.

[edit] reset()

Reset parameters and statement execution. 

void reset();
[edit] Parameters

None.

Note: JS callers should ensure that statements are reset. Be particularly careful about exceptions. You will want to make sure to reset your statements even if an exception is fired, or subsequent access to the database may not be possible. Whereas C++ callers know that all references will be destroyed when statement is freed, you don't have to explicitly reset the statement.


[edit] Binding functions

[edit] bindUTF8StringParameter()

Binds the UTF8String value to the parameter at aParamIndex. Index 0 denotes the first numbered argument or ?1. 

 void bindUTF8StringParameter(
   in unsigned long aParamIndex, 
   in AUTF8String aValue
 );
[edit] Parameters
aParamIndex
Parameter to be binded with the UTF8String value.
aValue
UTF8String value to be binded to the specified parameter.

[edit] bindStringParameter()

Binds the String value to the parameter at aParamIndex. Index 0 denotes the first numbered argument or ?1. 

 void bindStringParameter(
   in unsigned long aParamIndex, 
   in AString aValue
 );
[edit] Parameters
aParamIndex
Parameter to be binded with the String value.
aValue
String value to be binded to the specified parameter.

[edit] bindDoubleParameter()

Binds the Double value to the parameter at aParamIndex. Index 0 denotes the first numbered argument or ?1. 

 void bindDoubleParameter(
   in unsigned long aParamIndex, 
   in double aValue
 );
[edit] Parameters
aParamIndex
Parameter to be binded with the Double value.
aValue
Double value to be binded to the specified parameter.

[edit] bindInt32Parameter()

Binds the Int32 value to the parameter at aParamIndex. Index 0 denotes the first numbered argument or ?1. 

 void bindInt32Parameter(
   in unsigned long aParamIndex, 
   in long aValue
 );
[edit] Parameters
aParamIndex
Parameter to be binded with the Int32 value.
aValue
Int32 value to be binded to the specified parameter.

[edit] bindInt64Parameter()

Binds the Int64 value to the parameter at aParamIndex. Index 0 denotes the first numbered argument or ?1. 

 void bindInt64Parameter(
   in unsigned long aParamIndex, 
   in long long aValue
 );
[edit] Parameters
aParamIndex
Parameter to be binded with the Int64 value.
aValue
Int64 value to be binded to the specified parameter.

[edit] bindNullParameter()

Binds the NULL value to the parameter at aParamIndex. Index 0 denotes the first numbered argument or ?1. 

 void bindNullParameter(
   in unsigned long aParamIndex
 );
[edit] Parameters
aParamIndex
Parameter to be binded with the NULL value.

[edit] bindBlobParameter()

Binds the Blob value to the parameter at aParamIndex. Index 0 denotes the first numbered argument or ?1. 

 void bindBlobParameter(
   in unsigned long aParamIndex, 
   [array,const,size_is(aValueSize)] in octet aValue, 
   in unsigned long aValueSize
 );
[edit] Parameters
aParamIndex
Parameter to be binded with the Blob value.
aValue
Blob value to be binded to the specified parameter.
aValueSize
Size of the Blob value.

[edit] execute()

Execute the query, ignoring any results. This is accomplished by calling step() method once, and then calling reset() method. Error and last insert info, etc. are available from the mozIStorageConnection. 

 void execute();
[edit] Parameters

None.

[edit] executeStep()

The main way to execute a statement. This method executes a query, using any currently-bound parameters to enumerate all the result rows your statement produces, and will notify you when there are no more results available. The reset() method must be called on the statement after the last call of executeStep. 

 boolean executeStep();
[edit] Parameters

None.

[edit] Return value

Returns a boolean indicating whether there are more rows or not. Row data may be accessed using mozIStorageValueArray methods on the statement.

[edit] escapeStringForLIKE()

Escape a string for SQL LIKE search.

Note: Consumers will have to use same escape char when doing statements such as: ...LIKE '?1' ESCAPE '/'...
 AString escapeStringForLIKE(
   in AString aValue, 
   in wchar aEscapeChar
 );
[edit] Parameters
aValue
String to escape for SQL LIKE.
aEscapeChar
Escape character.
[edit] Return value

An AString of an escaped version of aValue (%, _ and the escape char are escaped with the escape char). For example, we will convert "foo/bar_baz%20cheese" into "foo//bar/_baz/%20cheese" (if the escape char is '/').

[edit] Example: Resetting a statement

[edit] JavaScript

var statement = connection.createStatement(...);
try {
  // use the statement...
} finally {
  statement.reset();
}

[edit] Example: Executing a statement

[edit] JavaScript

var statement = mDBConn.createStatement("INSERT INTO my_table VALUES (?1)");
statement.bindInt32Parameter(52);
statement.execute();


[edit] See also

Retrieved from "http://developer.mozilla.org/en/docs/mozIStorageStatement"