mozilla
Your Search Results

    mozIStorageStatement

    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

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

    initialize()

    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 (?1 maps to 0, 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 (?1 maps to 0, 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.

    Requires Gecko 1.9.2 (Firefox 3.6 / Thunderbird 3.1 / Fennec 1.0)

    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.

    Requires Gecko 1.9.2 (Firefox 3.6 / Thunderbird 3.1 / Fennec 1.0)

    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 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 (?1 maps to 0, and so on).

    aValue

    to be bound to the specified index.

    bindStringParameter()

    Binds a 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 (?1 maps to 0, and so on).

    aValue

    to be bound to the specified index.

    bindDoubleParameter()

    Binds a 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 (?1 maps to 0, and so on).

    aValue

    to be bound to the specified index.

    bindInt32Parameter()

    Binds a 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 (?1 maps to 0, and so on).

    aValue

    to be bound to the specified index.

    bindInt64Parameter()

    Binds a 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 (?1 maps to 0, and so on).

    aValue

    to be bound to the specified index.

    bindNullParameter()

    Binds a 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 (?1 maps to 0, and so on).

    bindBlobParameter()

    Binds a 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 (?1 maps to 0, 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.

    Requires Gecko 1.9.1 (Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.0)

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

    Warning: Performing synchronous IO on the main thread can cause serious performance problems. As a result, using this method on the main thread is strongly discouraged!

    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.

    Requires Gecko 1.9.1 (Firefox 3.5 / Thunderbird 3.0 / SeaMonkey 2.0)

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

    Warning: Performing synchronous IO on the main thread can cause serious performance problems. As a result, using this method on the main thread is strongly discouraged!

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

     void execute();
    

    See also

    Document Tags and Contributors

    Last updated by: Zorbing,