next( )

Topic group Related topics

Moves the row cursor to another row relative to the current position.

Syntax

<oRef>.next([<rows expN>])

<oRef>

The rowset in which you want to move the row cursor.

<rows expN>

The number of rows you want to move. By default, the next row forward.

Property of

Rowset

Description

next( ) takes an optional numeric parameter that specifies in which direction, forward or backward, to move and how many rows to move through, relative to the current row position. A negative number indicates a search backward, toward the first row; a positive number indicates a search forward, toward the last row. For example, a parameter of 2 means to move forward two rows.

If a filter is active, it is honored.

If the row cursor encounters the end-of-set while moving, the movement stops, leaving the row cursor at the end-of-set, and next( ) returns false. Otherwise next( ) returns true.

Navigation methods such as next( ) will cause the rowset to attempt an implicit save if the rowset’s modified property is true. The order of events when calling next( ) is as follows:

1. If the rowset has a canNavigate event handler, it is called. If not, it’s as if canNavigate returns true.

1. • If the canNavigate event handler returns false, nothing else happens and next( ) returns false.

   • If the canNavigate event handler returns true, the rowset’s modified property is checked.

   • If modified is true:

1. • • The rowset’scanSave event is fired. If there is no canSave event, it’s as if canSave returns true.

     • If canSave returns false, nothing else happens and next( ) returns false.

     • If canSave returns true, dBASE Plus tries to save the row. If the row is not saved, perhaps because it fails some database engine-level validation, a DbException occurs—next( ) does not return.

     • If the row is saved, the modified property is set to false, and the onSave event is fired.

1. • After the current row is saved (if necessary):

1. • • The row cursor moves to the designated row.

     • The onNavigate event fires.

     • next( ) returns true (if the navigation did not end up at the end-of-set).

Other navigation methods go through a similar chain of events.

Note

Using the rowset's navigateByMaster property to synchronize movement in master-detail rowsets, modifies the behavior of the next( ) method. See navigateByMaster for more information.