1.4 Positions of an Iterator Object

When the iterator object is created, its current position is set to the first object in the list that matches the search criteria. The figure below illustrates a virtual list and some of the possible positions for the iterator object.

Figure 1-1 Virtual List with Iterator Object Possible Positions

The numbers (0, ~500, 1000, and 1001) on the left side of the list represent logical positions in the list, not actual entry numbers. A logical position is a scaled number from 0 to 1000 and not an exact index number into the list. For example, 500 represents the approximate middle of the list, whether there are actually 50 or 5,000 entries in the list.

Three positions are exact:

The position can be set to any entry in the list, or to EOF (end of file). EOF is an imaginary position after the end of the last entry. The following functions set the position or return information about the current position.

Function

Purpose

NWDSItrAtEOF

Indicates whether the iterator object is positioned at the end of the list. Works on all iterators.

NWDSItrAtFirst

Indicates whether the iterator object is at the first entry of the list. Works on all iterators.

NWDSItrGetPosition

Returns the current position of the iterator object. Works on positionable iterators.

NWDSItrSetPosition

Moves the current position to the specified position. Logical values specify the location: 0, the top of the list; 1000, the end of the list; and 1001, the EOF position. Other values move the current position to an approximate location. Works on positionable iterators.

NWDSItrSkip

Allows the current position to be moved forward or backward “n” entries. Skipping beyond the top of the list leaves the current position at the first entry in the list (DS_ITR_FIRST). Skipping beyond the end of the list leaves the position at the end of the list (DS_ITR_EOF). Works on all iterators.

NWDSItrSetPositionFromIterator

Moves the current position of the iterator to the object that comes the closest to matching the current object of the source iterator object.

For NDS 8 iterators, the iterators do not need to be identical. For emulation mode, the iterators need to be clones.

NWDSItrTypeDown

Moves the current position to the object with the attribute that matches the input string. For example, a typedown using attribute “Surname” and string “St” positions the iterator to the first entry with surname “St”. If no entries starting with “St” are present, the iterator is positioned on the first entry after “St” in sorted order. Works on all iterators.