company logo

PropertyHandle :: LocateKey - Locate instance according to key

The instance with the passed key value will be located in the currently selected index. In case of error or when no instance with the given key was found, the function returns an error (YES). Otherwise the instance is located and can be read with Get(CUR_INSTANCE). 

Passing NO for exact the function tries to locate the instance with the next higher key value.

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. When combining exact=true with a filter condition, both, the key value and the filter condition are checked.

When an instance is positioned, the leading part of the key is checked and the function does nor change the selection, when the selected instance matches the key value. In order to locate the first key with the passed key value, selected instance in the property handle should be unselected (ToTop()).
Return value:  Success ( logical  )

Implementation overview

Implementation details

  1. Locate key by key value
    logical PropertyHandle  :: LocateKey ( ::Key sort_key, logical exact_w=YES )

    This implementation locates the key by means of the key structure passed to the function. The key must be passed according to the structure of the key including trailing blanks.
    • sort_key - - internal feature (not documented)
    • exact_w - Exact option

      The exact option forces the function to locate the instance with the exact key.

      Default: YES
    2. to list
  2. Locate leading part of key by value
    logical PropertyHandle  :: LocateKey ( ::Key sort_key, int32 key_level, logical exact_w=YES )

    This implementation locates the key by means of the key structure passed to the function. The key must be passed according to the structure of the key including trailing blanks. The function checks the key components according to the key level passed to the function.

    When key_level greater than 0 is passed, the requested key components are checked, only. In combination with exact=true, the located key must match the requested key components. Otherwise, the passed key value is considered as offset, only.
    • sort_key - - internal feature (not documented)
    • key_level - Number of fixed key component
    • exact_w - Exact option

      The exact option forces the function to locate the instance with the exact key.

      Default: YES
    3. to list
  3. - internal feature (not documented)
    logical PropertyHandle  :: LocateKey ( NString &cnstring, int32 key_level, logical exact_w=YES )
    • cnstring - String containing the text
    • key_level - Number of fixed key component
    • exact_w - Exact option

      The exact option forces the function to locate the instance with the exact key.

      Default: YES
    4. to list
  4. Locate instance by property handle
    logical PropertyHandle  :: LocateKey ( PropertyHandle &cprop_hdl, logical exact_w=YES )

    When the property handle contains a string value, the string will be converted into a key for locating the instance. When the property handle refers to a complex instance of the same type or a base type of the current type in the property handle, the instance key in the passed property handle is used for locating the key.

    When the property handle contains a numeric value, no instance is located.
    • cprop_hdl - Property Handle
    • exact_w - Exact option

      The exact option forces the function to locate the instance with the exact key.

      Default: YES
    5. to list
  5. - internal feature (not documented)
    logical PropertyHandle  :: LocateKey ( PropertyHandle &cprop_hdl, int32 key_level, logical exact_w=YES )
    • cprop_hdl - Property Handle
    • key_level - Number of fixed key component
    • exact_w - Exact option

      The exact option forces the function to locate the instance with the exact key.

      Default: YES
    6. to list
to top previous next upper table of contents Comment