openCursor method

Returns a cursor object positioned at the first record object in a data source, optionally filtered by a key range and ordered by a direction.

Syntax

object.openCursor(range, direction, retVal)

Parameters

range [in, optional]

Type: any

A key range limiting the cursor to a specific set of values.

direction [in, optional]

Type: DOMString

Indicates the direction of traversal and whether duplicate values are included.

ValueMeaning
"next"

The cursor contains duplicate values and is traversing key values in ascending order.

"nextunique"

The cursor contains only unique values and is traversing key values in ascending order.

"prev"

The cursor contains duplicate values and is traversing key values in descending order.

"prevunique"

The cursor contains only unique values and is traversing key values in descending order.

 

Exceptions

This method can throw the following DOMException exceptions:

Note  As of a Windows Store app using JavaScript, the code property is deprecated in favor of the name property, which is preferred for standards compliance and future compatibility.

Exception propertiesCondition
name: DataError

The values range parameter are not valid for the data source.

name: InvalidStateError
code: DOMException.INVALID_STATE_ERR (11)

The data source has been deleted or is otherwise not available.

name: TransactionInactiveError

The associated transaction is not active.

Standards information

Examples

The following example illustrates a function designed to return a record object from an object store; the function supports an optional parameter (sIndexName) that specifies the name of an index. If the sIndexName parameter specifies a value, the function uses that value to open a cursor using an index. If the parameter isn't specified, the function opens the cursor directly.


function getCard( aValue, fnCallback, sIndexName ) {

  if ( hIxHandle == null ) {
     handleError( "Can't open database (invalid handle)." );
  } else
       try {

          sObjectStore = getCardStoreName();        
          var hTransaction = hDBHandle.transaction( sObjectStore, "readonly" );
          var hObjectStore = hTransaction.objectStore( sObjectStore );
          var hRequest = null;
          
          if ( sIndexName == null ) {
             hRequest = hObjectStore.openCursor( aValue );
          } else {
             var hIndex = hObjectStore.index( sIndexName ); 
             hRequest = hIndex.openCursor( aValue );
          }
          hRequest.onerror = handleRequestEvent;
          hRequest.onsuccess = function( evt ) {
             handleRequestEvent( evt );
             if ( fnCallback != null ) {
                var oResult = null; // assume no result.
                if ( evt.target.result != null ) {
                   oResult = evt.target.result.value; 
                }
                fnCallback( oResult );          
             }
          }
       } catch( ex ) {
         handleError( ex.message );
       }   
}


See also

IDBCursor
IDBIndex
IDBObjectStore

 

 

Show:
© 2014 Microsoft