company logo

PropertyHandle :: Delete - Delete/remove instance from collection

The function removes the selected instance from the collection. When passing a key or a position the function selects the instance with the passed key or the given position before removing it from the collection. Deleting by key is possible only when a sort order with a unique key has been selected. For removing an instance from a collection the property handle must be opened in write mode. For deleting the instance the selected instance must be available in write mode as well.

Removing an instance from a collection will delete the instance as well, when the collection is owning the instance or when the instances in the collection do depend on the collection. You may also request deleting the instance by passing YES for the del_inst parameter (Delete at position, only).

Removing an instance from a collection it will maintain automatically inverse references. Moreover, the instance is removed from all derived collections (subsets). This means the instances might be deleted also, when being dependent on one of the derived collections.

When deleting the instance derived instances are deleted as well. All inverse relationships and subset relationships are maintained.

Return value:  Success ( logical  )

Implementation overview

Implementation details

  1. Delete instance by position
    logical PropertyHandle  :: Delete ( int32 set_pos0_w=AUTO, logical del_dep=YES, logical del_inst=NO )

    The function deletes the instance at the position passed to the function ( set_pos0_w ). When AUTO is passed the current instance is deleted. Dependent instances are usually deleted as well ( del_dep = YES ). When passing NO , depending instances are not deleted, as long as they are not owned by the current instance.

    When the current collection is not owner of instances and instances do not depend on the collection, del_inst = true can be passed in order to delete the instance anyway. Otherwise, the instance will be removed from the collection, only.

    Notes:

    Deleting an instance by position may fail (without generating a database error) when a filter condition is set for the collection, which is not fulfilled for the instance to be deleted.

    • 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
    • del_dep - Delete dependent instances

      Usually this option is set to YES , i.e. all dependent instances are deleted when being removed from the collection. Passing NO dependent instances are not deleted but removed from the collection, only.

      Instances owned by the collection, however, will be deleted always.

      When deleting a collection ( DeleteSet() ) with a filter condition, only instances that are filtered will be selected. In order to delete the complete collection, the option should be set to 2 (not deleting depending instances ) or 3 (delete all and depending instances).

      Default: YES
    • del_inst - Delete instance requested

      The parameter must be set to true ( YES ) in order to delete the instance instead of removing the instance from the collection. Passing AUTO indicates, that instance will be deleted by caller. This causes fast delete, since instance's relationships will not be maintained.

      Default: NO
  2. to list
  3. Delete instance by key
    logical PropertyHandle  :: Delete ( ::Key sort_key )

    The function deletes an instance by key. When no instance with the passed key can be located, the function terminates with error.

    • sort_key - - internal feature (not documented)
  4. to list
  5. - internal feature (not documented)
    logical PropertyHandle  :: Delete ( ::Instance instance )
    • instance - Instance area

      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.

  6. to list
  7. Delete by key or position
    logical PropertyHandle  :: Delete ( PropertyHandle &cprop_hdl )

    Depending on the data type of the passed property handle, the instance at the passed position (number) will be deleted or the instance with the given key (text) will be deleted. When passing a key value (text), key components must be separated by '|'.

    • cprop_hdl - Property Handle
  8. to list
  9. - internal feature (not documented)
    logical PropertyHandle  :: Delete ( NString &cnstring )
    • cnstring - String containing the text
  10. to list