1.5 Current Position Movement with Retrieval Functions

Upon creation, the iterator's current position is set to the first entry in the list. Thereafter, the current position changes as object data is retrieved. The figure below shows a virtual list and the various positions that the retrieval functions move the iterator's current position.

Figure 1-2 Virtual List

The NWDSItrCreateList and NWDSItrCreateSearch functions position the iterator on the first object in the list. The NWDSItrGetCurrent function retrieves the data of the object in the current position; it does not move the iterator's position.

The current position moves with the other data retrieval functions. The NWDSItrGetNext function retrieves the information about the n number of entries specified, including the current entry. It then positions the iterator on the next available entry. Notice that the arrow in the figure points to an entry beyond the “Next Entries” box.

The NWDSItrGetPrev function retrieves the information about n number of entries specified, in reverse sort order (4, 3, 2, 1) from the current position. It does not retrieve information about the object in the current position when the function is called, and it positions the iterator on the entry last read. Notice that the arrow in the figure points to the last entry in the “Previous Entries” box.