storage/public/mozIStorageStatement.idlScriptable
This interface lets you create and execute SQL statements on a mozIStorageConnection.
Inherits from: mozIStorageValueArray Last changed in Gecko 1.9.2 (Firefox 3.6 / Thunderbird 3.1 / Fennec 1.0)

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

Method overview

void initialize(in mozIStorageConnection aDBConnection, in AUTF8String aSQLStatement); Obsolete since Gecko 1.9.1
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();
AString escapeStringForLIKE(in AString aValue, in wchar aEscapeChar);
void bindParameters(in mozIStorageBindingParamsArray aParameters);
mozIStorageBindingParamsArray newBindingParamsArray();
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);
mozIStoragePendingStatement executeAsync(mozIStorageStatementCallback aCallback);
boolean executeStep();
boolean step();
void execute();

Attributes

Attribute Type Description
columnCount unsigned long Number of columns returned. Read only.
parameterCount unsigned long Number of parameters. Read only.
params mozIStorageStatementParams The current list of named parameters, which may be set. Only available to JavaScript code. Read only.
row mozIStorageStatementRow The current row, with access to all data members by name. Available only to JavaScript code. Read only.
state long The current state defined by mozIStorageStatement.MOZ_STORAGE_STATEMENT_INVALID, mozIStorageStatement.MOZ_STORAGE_STATEMENT_READY, or mozIStorageStatement.MOZ_STORAGE_STATEMENT_EXECUTING. Read only.

Statement status 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.

Methods

initialize()

Obsolete since Gecko 1.9.1 (Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.0)

Note: This method has been removed for Gecko 1.9.1. To initialize a statement, consumers should call mozIStorageConnection.createStatement(). This method exists back to Gecko 1.8.0.

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();

Note: This method does not need to be used from native callers because you have to release the statement in order to not leak. Finalize will be called for you when the reference count on the statement goes to zero.

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.

Note: JavaScript callers should always wrap their execution in a try block, and have a reset statement in a finally block.

See the overview document on storage for more details.

void reset()

escapeStringForLIKE()

Escapes a string for SQL LIKE search.

Note: Consumers will have to use same escape char when doing statements such as: ...LIKE '?1' ESCAPE '/'.... See the sample code for more details.

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().

Note: Starting in Gecko 2.0, this method returns NS_ERROR_UNEXPECTED if the specified mozIStorageBindingParamsArray is empty.
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.

Note: The statement does not have to be reset before being reused.

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.

Note: The statement must be reset before being reused.

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.

Note: This method may only be called from JavaScript code.
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