mozIStorageStatement

For an introduction on how to use this interface, see the Storage overview document.

Method overview

Attributes

Statement status constants

Methods

Initialize this query with the given SQL statement.

void initialize(
  in mozIStorageConnection aDBConnection, 
  in AUTF8String aSQLStatement
);

Parameters

aDBConnection

A mozIStorageConnection database connection.

aSQLStatement

String key representing the SQL statement.

finalize()

Finalizes a statement which releases all resources that were allocated for it. You must call this method on every active statement before you try to call mozIStorageConnection.close().

void finalize();

clone()

Creates a copy of the statement whose state will be mozIStorageStatement.MOZ_STORAGE_STATEMENT_READY.

mozIStorageStatement clone();

Return value

A mozIStorageStatement that is a copy of the current statement.

getParameterName()

Obtains the name of the parameter for the specified index.

AUTF8String getParameterName(
  in unsigned long aParamIndex
);

Parameters

aParamIndex

The zero-based numerical index for the parameter to be bound. This will be one less than the number used in the SQL (<code>?1</code> maps to <code>0</code>, and so on).

Return value

An AUTF8String representing the parameter name for the specified index.

getParameterIndex()

Obtains the index of the parameter with the specified name. This method was added in 1.9.0. In 1.8.1 you had to use getParameterIndexes(). See bug 388048 for details.

unsigned long getParameterIndex(
  in AUTF8String aName
);

Parameters

aName

Name of the parameter to get the index for. For parameter 'foo', name's format is ':foo' in 1.9.0 and 1.9.1. In 1.9.2 the ':' was dropped and name's value should be just 'foo'. See bug 528166 for details.

Return value

The zero-based numerical index for the parameter to be bound. This will be one less than the number used in the SQL (<code>?1</code> maps to <code>0</code>, and so on).

getColumnName()

Obtains the name of the column for the specified index.

AUTF8String getColumnName(
  in unsigned long aColumnIndex
);

Parameters

aColumnIndex

The zero-based numerical index for the column to get data from.

Return value

An AUTF8String with the of the column name for the specified index.

getColumnIndex()

Obtains the index of the column with the specified name.

unsigned long getColumnIndex(
  in AUTF8String aName
);

Parameters

aName

Name of the column.

Return value

The zero-based numerical index for the column to get data from.

reset()

Resets the bound parameters and statement execution state. This must be called before reusing the statement.

See the overview document on storage for more details.

void reset()

escapeStringForLIKE()

Escapes a string for SQL LIKE search.

AString escapeStringForLIKE(
  in AString aValue, 
  in wchar aEscapeChar
);

Parameters

aValue

String to escape for SQL LIKE.

aEscapeChar

The escape character to use. Generally, / will be sufficient.

Return value

An UTF-16 encoded string that has characters that have special meaning escaped from aValue.

Sample Code

var statement = dbConn.createStatement(
  "SELECT * " +
  "FROM table_name " +
  "WHERE column_name LIKE :userInput ESCAPE '/'"
);
statement.params.userInput = statement.escapeStringForLIKE(someUserInput, "/");

Binding Functions

These functions are discussed in more detail with sample code in the overview document.

newBindingParamsArray()

Creates and returns a new mozIStorageBindingParamsArray object that can be used to bind multiple values to parameters in preparation for calling executeAsync().

mozIStorageBindingParamsArray newBindingParamsArray();

Parameters

None.

bindParameters()

Binds all the parameters in the specified array to the statement in preparation for calling executeAsync().

void bindParameters(
  in mozIStorageBindingParamsArray aParameters
); 

Parameters

aParameters

The mozIStorageBindingParamsArray object containing one or more mozIStorageBindingParams objects with the parameters to be bound to the statement prior to execution.

bindUTF8StringParameter()

Binds a UTF8String to the specified index.

void bindUTF8StringParameter(
  in unsigned long aParamIndex, 
  in AUTF8String aValue
);

Parameters

aParamIndex

The zero-based numerical index for the parameter to be bound. This will be one less than the number used in the SQL (<code>?1</code> maps to <code>0</code>, and so on).

aValue

to be bound to the specified index.

bindStringParameter()

Binds a string parameter to the specified index.

void bindStringParameter(
  in unsigned long aParamIndex, 
  in AString aValue
);

Parameters

aParamIndex

The zero-based numerical index for the parameter to be bound. This will be one less than the number used in the SQL (<code>?1</code> maps to <code>0</code>, and so on).

aValue

to be bound to the specified index.

bindDoubleParameter()

Binds a double parameter to the specified index.

void bindDoubleParameter(
  in unsigned long aParamIndex, 
  in double aValue
);

Parameters

aParamIndex

The zero-based numerical index for the parameter to be bound. This will be one less than the number used in the SQL (<code>?1</code> maps to <code>0</code>, and so on).

aValue

to be bound to the specified index.

bindInt32Parameter()

Binds an Int32 parameter to the specified index.

void bindInt32Parameter(
  in unsigned long aParamIndex, 
  in long aValue
);

Parameters

aParamIndex

The zero-based numerical index for the parameter to be bound. This will be one less than the number used in the SQL (<code>?1</code> maps to <code>0</code>, and so on).

aValue

to be bound to the specified index.

bindInt64Parameter()

Binds an Int64 parameter to the specified index.

void bindInt64Parameter(
  in unsigned long aParamIndex, 
  in long long aValue
);

Parameters

aParamIndex

The zero-based numerical index for the parameter to be bound. This will be one less than the number used in the SQL (<code>?1</code> maps to <code>0</code>, and so on).

aValue

to be bound to the specified index.

bindNullParameter()

Binds a null parameter to the specified index.

void bindNullParameter(
  in unsigned long aParamIndex
);

Parameters

aParamIndex

The zero-based numerical index for the parameter to be bound. This will be one less than the number used in the SQL (<code>?1</code> maps to <code>0</code>, and so on).

bindBlobParameter()

Binds a blob parameter to the specified index.

void bindBlobParameter(
  in unsigned long aParamIndex, 
  [array,const,size_is(aValueSize)] in octet aValue, 
  in unsigned long aValueSize
);

Parameters

aParamIndex

The zero-based numerical index for the parameter to be bound. This will be one less than the number used in the SQL (<code>?1</code> maps to <code>0</code>, and so on).

aValue

to be bound to the specified index.

aValueSize

Size of aValue.

Execution Functions

These functions are discussed in more detail with sample code in the overview document.

executeAsync()

Starts the execution of a query asynchronously using the currently bound parameters. The optional callback routine receives notifications about the progress of the query. For sample code and more details, see the overview document.

mozIStoragePendingStatement executeAsync(
  [optional] mozIStorageStatementCallback aCallback
);

Parameters

aCallback

A callback object that will be notified of progress, errors, and query completion. This parameter is optional.

Return value

A mozIStoragePendingStatement object that can be used to cancel the execution of the statement.

executeStep()

Executes a query with the currently bound parameters, and steps through the results one row at a time. For sample code and more details, see the overview document.

boolean executeStep();

Return value

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

step()

Identical to calling executeStep(), and then calling reset() when no more rows are returned.

boolean step()

Return value

true if there are more rows left in the results, otherwise false.

execute()

Execute the query, ignoring any results. This is accomplished by calling executeStep(), and then calling reset().

 void execute();

See also

• Storage introduction and how-to article
• mozIStorageConnection Database connection to a specific file or in-memory data storage
• mozIStorageValueArray Wraps an array of SQL values, such as a result row.
• mozIStorageFunction Create a new SQLite function.
• mozIStorageAggregateFunction Create a new SQLite aggregate function.
• mozIStorageProgressHandler Monitor progress during the execution of a statement.
• mozIStorageAsyncStatement
• mozIStorageStatementWrapper Storage statement wrapper
• mozIStorageBindingParams
• mozIStorageBindingParamsArray