company logo

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.

Return value:  Sort key ( char * )

The sort key is passed in the internal key structure format.

Notes:

Must be a C string

Implementation details

  1. - Title unknown
    ::Key PropertyHandle  :: NextKey ( ::Key sort_key_w=Key(), int16 kc_level=AUTO )
    • sort_key_w - Sort key value

      The key is provided in the internal key format. When necessary the key value can be converted from a string into the internal format using the StringToKey() function.

      Default: Key()
    • kc_level - Number of fixed key component Default: AUTO
  2. to list
  3. - internal feature (not documented)
    ::Key PropertyHandle  :: NextKey ( NString &cnstring, int16 kc_level=AUTO )
    • cnstring - String containing the text
    • kc_level - Number of fixed key component Default: AUTO
  4. to list