The Wayback Machine - https://web.archive.org/web/20081019234906/http://developer.mozilla.org:80/en/mozIStorageStatement
Register | Log in

Mozilla.com

  1. MDC
  2. Main Page
  3. mozIStorageStatement
Table of contents
  1. 1. Method overview
  2. 2. Attributes
  3. 3. Constants
  4. 4. Methods
    1. 4.1. initialize()
          1. 4.1.1.1.1. Parameters
    2. 4.2. finalize()
          1. 4.2.1.1.1. Parameters
    3. 4.3. clone()
          1. 4.3.1.1.1. Parameters
          2. 4.3.1.1.2. Return value
    4. 4.4. getParameterName()
          1. 4.4.1.1.1. Parameters
          2. 4.4.1.1.2. Return value
    5. 4.5. getParameterIndex()
          1. 4.5.1.1.1. Parameters
          2. 4.5.1.1.2. Return value
    6. 4.6. getColumnName()
          1. 4.6.1.1.1. Parameters
          2. 4.6.1.1.2. Return value
    7. 4.7. getColumnIndex()
          1. 4.7.1.1.1. Parameters
          2. 4.7.1.1.2. Return value
    8. 4.8. reset()
          1. 4.8.1.1.1. Parameters
    9. 4.9. Binding functions
      1. 4.9.1. bindUTF8StringParameter()
          1. 4.9.1.1.1. Parameters
      2. 4.9.2. bindStringParameter()
          1. 4.9.2.1.1. Parameters
      3. 4.9.3. bindDoubleParameter()
          1. 4.9.3.1.1. Parameters
      4. 4.9.4. bindInt32Parameter()
          1. 4.9.4.1.1. Parameters
      5. 4.9.5. bindInt64Parameter()
          1. 4.9.5.1.1. Parameters
      6. 4.9.6. bindNullParameter()
          1. 4.9.6.1.1. Parameters
      7. 4.9.7. bindBlobParameter()
          1. 4.9.7.1.1. Parameters
    10. 4.10. execute()
          1. 4.10.1.1.1. Parameters
    11. 4.11. executeStep()
          1. 4.11.1.1.1. Parameters
          2. 4.11.1.1.2. Return value
    12. 4.12. escapeStringForLIKE()
          1. 4.12.1.1.1. Parameters
          2. 4.12.1.1.2. Return value
    13. 4.13. Example: Resetting a statement
      1. 4.13.1. JavaScript
    14. 4.14. Example: Executing a statement
      1. 4.14.1. JavaScript
  5. 5. See also

mozIStorageStatement

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.


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

Method overview

void initialize(in mozIStorageConnection aDBConnection, in AUTF8String aSQLStatement); Obsolete
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);

Attributes

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

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

Initialize this query with the given SQL statement.

Firefox 3.1 note

This method has been removed for Firefox 3.1. To initialize a statement, simply call the mozIStorageConnection method createStatement() ; this works in Firefox 3.0 as well.

 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 so you can successfully close a database connection. since Gecko 1.9 M9 

void finalize();
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 JavaScript callers.

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

None.

Return value

A mozIStorageConnection representing the clone of the SQL statement.

getParameterName()

Obtains the name of the parameter for the specified index. 

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

An AUTF8String representing the parameter name for the specified index.

getParameterIndex()

Obtains the index of the parameter with the specified name. 

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

Returns the index of the parameter with the specified name.

getColumnName()

Obtains the name of the column for the specified index. 

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

An AUTF8String representing 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

Returns the index of the column with the specified name.

reset()

Reset parameters and statement execution. 

void reset();
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.


Binding functions

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
 );
Parameters
aParamIndex
Parameter to be binded with the UTF8String value.
aValue
UTF8String value to be binded to the specified parameter.

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
 );
Parameters
aParamIndex
Parameter to be binded with the String value.
aValue
String value to be binded to the specified parameter.

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
 );
Parameters
aParamIndex
Parameter to be binded with the Double value.
aValue
Double value to be binded to the specified parameter.

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
 );
Parameters
aParamIndex
Parameter to be binded with the Int32 value.
aValue
Int32 value to be binded to the specified parameter.

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
 );
Parameters
aParamIndex
Parameter to be binded with the Int64 value.
aValue
Int64 value to be binded to the specified parameter.

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
 );
Parameters
aParamIndex
Parameter to be binded with the NULL value.

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

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

None.

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

None.

Return value

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

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
 );
Parameters
aValue
String to escape for SQL LIKE.
aEscapeChar
Escape character.
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 '/').

Example: Resetting a statement

JavaScript

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

Example: Executing a statement

JavaScript

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


See also

Page last modified 16:07, 11 Jun 2008 by Sheppy

Tags:

Files (0)