PropertyHandle :: Locate - Locate object by identity
The function is searching for an instance with the given local identity (LOID) in the collection of the property handle. The function returns NO when the instance could be located. The function returns an error ( YES ) in case of an error or when the instance is not member of the collection.
When passing YES for read_opt the instance is selected in the property handle. Otherwise it is located, only and can be read with Get( CUR_INSTANCE ).
mit set_pos_w kann ein index übergeben werden, der zur optimierten Suche der Instanz genutzt werden soll.
Implementation details
- obident
- Instance identity
The identity refers to a persistent instance that can be referenced within the database. Embedded instances and exclusive base structure instances do not have an instance identity.
- set_pos_w
- Position in collection
The position of an instance in a collection depends on the selected index. if the collection is unsorted the position is the only way for accessing the instance.
For sorted collections the position is determined according to the instance key. If is a contradiction between position and key value the position will be ignored.
Special positions are
CUR_INSTANCE (-1) refers to the currently selected instance. If no instance is selected it refers to the first instance.
FIRST_INSTANCE (0) refers to the first instance in a collection according to the selected index (sort order).
FIRST_INSTANCE (0x7fffffff) refers to the last instance in a collection according to the selected index (sort order).
Default: AUTO
- read_opt
- Read option
The option forces the function to read the instance when it could be located.
Default: YES