Use the navigateByMaster property to flag a detail rowset to move when its master rowset is moved. The navigateByMaster property allows detail rowsets and a linked master rowset to be navigated as though they were part of a single, combined rowset (similar to the xDML SET SKIP command).

Property of

Rowset

Description

When set to true in a detail rowset, navigateByMaster signals the linked master rowset to navigate through any matching detail rows before moving to a new master row.

More specifically, navigateByMaster :

Flags a detail rowset so its row cursor is moved when its master rowset’s next( ), first( ), or last( ) methods are called

Flags a detail rowset so its atFirst( ) or atLast( ) methods are called when its master rowset’s atFirst( ) or atLast( ) methods are called.

When a master rowset has one or more detail rowset’s with navigateByMaster set to true, the behavior of the following rowset methods is modified as follows:

first( ) Ensures that linked detail rowsets are positioned to the first row matching the first master row. After positioning a master rowset to its first row, the masters first( ) method positions any linked detail rowsets to their first matching row, which in turn position any linked grandchild rowsets to their first row matching their master rowsets. This process continues recursively through the entire tree of linked rowsets.

next( ) Attempts to move detail and master rowsets such that they appear to have moved one or more rows relative to their starting positions, as if they were a single combined rowset. next( ) can be called with an optional numeric parameter specifying the direction (positive to move forward, negative to move backward) and number of rows to move. If no parameter is specified, next( ) defaults to moving one row forward. next( ) will return true if it is able to move the number of rows specified, otherwise it returns false.

next( ) moves the row cursors according to the following rules: 

next( ) will only move linked detail rowsets that have their navigateByMaster property set to true.

next( ) will attempt to move these linked detail rowsets before moving the master rowset.

If a rowset has more than one linked detail rowset, next( ) will attempt to move them in the order in which they were linked to the master rowset. In addition, only detail rows matching the current master row will be moved (i.e. navigation occurs as if the master-detail link is constrained)

When moving in a detail rowset, next( ) will continue moving in the same detail rowset until it moves the number of rows requested, or it reaches end-of-set (i.e. no more detail rows are found matching the current master row). If the detail rowset has reached end-of-set, and there are still more rows to be moved, next( ) will continue with the next linked detail rowset or, if there are no other linked detail rowsets, next( ) will move the master rowset one row and synchronize the linked detail rowsets to:

their first matching row (if moving forward)

their last matching row (if moving backward)

end-of-set (if no matching row is found).

If there are still more rows to be moved to, next( ) will repeat this process starting once again with the first linked detail rowset.

If a linked detail rowset , for example d1, is itself a master rowset and has its own detail rowset , d2, (with navigateByMaster set to true), it will act as a master rowset and follow the same sequence of events described above. The net result of this sequence is that the lowest detail rowset (d2 in this example) will be moved first. When d2 reaches end-of-set, its master rowset, d1, will be moved. When d1 reaches end-of-set, its master rowset will be moved.

last( ) Ensures that linked detail rowsets are positioned to the last row matching the last master row. After positioning a master rowset to its last row, the master’s last( ) method positions any linked detail rowsets to their last matching row, which in turn position any linked grandchild rowsets to their last row matching their master rowsets. This process continues recursively through the entire tree of linked rowsets.

atFirst( ) Returns true when a master rowset is at the first row and all linked detail rowsets, whose navigateByMaster properties are set to true, are at their first matching rows. Otherwise returns false.

atLast( ) Returns true when a master rowset is at the last row and all linked detail rowsets, whose navigateByMaster properties are set to true, are at their last matching rows. Otherwise returns false.

The navigateByMaster property’s default is false.

To use this property:

In the detail rowset, set navigateByMaster to true

Specify the master rowset for the form.rowset (using the standard toolbar’s navigation buttons).

Specify the master rowset as the grid's datalink if you want to setup a grid containing columns from both the master and linked detail rowsets.

Set the grandchild rowset's navigateByMaster to true to add additional master detail levels (such as parent, child, grandchild):

Grid and Browse classes

dBASE Plus's Grid class now provides correct rowset navigation when datalinked to a master rowset with at least one detail rowset whose navigateByMaster is set to true.

Similarly, dBASE Plus’s Browse class provides correct navigation when controlled by a table using xDML SET RELATION and SET SKIP commands.