company logo

PropertyHandle :: Get - Get property instance

The Get() function allows selecting an instance in a property handle collection by key or position. The function can also be used to locate an instance in an array attribute or to get a single attribute instance. Before a new instance is selected the current selection in the property handle is canceled. in case of instance modifications on the previously selected instance those are saved automatically. Selecting an instance will also cancel the selection of all subordinated property handles.

The function returns the instance that has been selected in the property handle when is has been executed successfully. Otherwise it returns an empty instance.
Return value:  Instance area ( ::Instance  )

Instances do have the type of the referenced property handle (collection type). The instance contains a pointer to a properly structured instance area.

You can use the !-operator or the GetData() function to check whether the instance refers to data or not.

Implementation overview

Implementation details

  1. Get Instance by index position
    ::Instance PropertyHandle  :: Get ( int32 set_pos0_w=AUTO )

    Reading an instance by position is locating the instance on the given location in the selected index (sort order). Thus, the result will change usually when changing the selected index for the collection. Using index positions for reading is also a weak point when indexes are updated simultaneously, since the index position might change when other users insert or remove entries from the index. To avoid this one may use the LockSet() function, that locks the complete collection. Access by position, however, is a comfortable way browsing through a collection. Access by position cannot be used for LOID or GUID property handles. Passing a number to an LOID handle interprets the number as local object identity.

    For a path property Get() by position automatically changes the selection for higher properties in the path when the end of collection is signaled an a level that is not the top level for the path property.

    Passing AUTO as position the function returns the instance currently selected in the property handle. When no instance is selected the function returns the first instance in the collection. When an instance is selected in the property handle and the current access mode does not correspond to the required access mode, the function will reread the instance. Thus, the function can be used to update the access mode when the selected instance was write protected. Selections in subordinated property handles are canceled when rereading the instance.
    • set_pos0_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
    2. to list
  2. Get instance by key value
    ::Instance PropertyHandle  :: Get ( ::Key sort_key )

    When reading an instance by key, this is considered as key in the currently selected index (SetOrder()). When the key cannot be found in the index the function returns an empty instance. It is also possible to locate an instance by key in an unordered collection, when it has been marked as unique (no duplicate instances). In this case the key must be passed according to the structure of the identifying key. The key must be passed according to the internal key structure.

    The key can also be an LOID or a GUID string when the property handle has been opened for reading by local object identities (__LOID) or by global unique identifiers (__GUID).

    When positioning the instance for a path property the key must consist of all sort keys along the path.
    • sort_key - - internal feature (not documented)
    3. to list
  3. Get instance by value in the property handle
    ::Instance PropertyHandle  :: Get ( PropertyHandle &cprop_hdl )

    When passing the value for locating an instance in a collection via property handle, Get() is called as get by key or index depending on the data type defined in the property handle.

    When the value property handle passes a structured instance of the same or a specialized type as the instance to be selected, the key value is extracted from the instance passed in the property handle and get by key is used.

    When passing a text value (STRING, MEMO or CHAR), the text data is considered as string key where key components are separated by |. You cannot pass a structured key (Key) my means of property handles.

    If no key or instance version is used, the "get by position" version is called. Non integer numerical values are rounded to the next lower integer number.
    • cprop_hdl - Property Handle
    4. to list
  4. - internal feature (not documented)
    ::Instance PropertyHandle  :: Get ( OperEnvironment *operenv, int32 set_pos0_w=AUTO )
    • operenv - Pointer to operation environment
    • set_pos0_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
    5. to list
  5. Get instance by LOID
    ::Instance PropertyHandle  :: Get ( int64 vLOID )

    The function tries to locate in instance by local object identifier (LOID). When the property handle handles a collection, the function tries to locate an instance with the LOID passed within the collection. When the property handle handles all instances in the database (VOID handle, see example below), the function tries to locate an instance in the database with the LOID passed in vLOID.

    // open database instance hande for all instances

    Property   all(database,"VOID",Read);

    • vLOID - Local object identifier

      The LOID is passed as 64-bit integer. 0 is considered as empty LOID. -1 is also considered as empty, but it is used often for indicating automatic value or no result.
    6. to list
to top previous next upper table of contents Comment