PropertyHandle :: NextKey - Locate next key

The function tries to locate the next key according to the selected order starting from the selected or located instance. When passing a key the instance with this key or the next lower (if not existing) is the starting point. The function locates the key next to the starting point. The function returns the next key located or an empty Key handle in case of an error. When calling the function for indexes allowing duplicate key values, NextKey() also returns duplicates.

When a filter or key filter has been set, the function locates the next key or instance fulfilling the filter condition. In case of instance filters, the instance will be positioned.

The instance is located but not selected in the property handle. It can be selected calling Get(CUR_INSTANCE) after calling NextKey(). Since the function is not reading instances but parsing the index only, it provides fast access to the keys of a collection. For PropertyHandle of type VOID the function always terminates with error.

Passing a key_level allows defining the last key components that must alter. This allows e.g. reading all instances for key duplicates when fixing the last key component. When passing a key and key_level, the next key for requested key components will be located.