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

Delete instance by position
PropertyHandle :: Delete ( set_pos0_w=AUTO, del_dep=YES, del_inst=NO )
Delete instance by key
PropertyHandle :: Delete ( sort_key )
- internal feature (not documented)
PropertyHandle :: Delete ( instance )
Delete by key or position
PropertyHandle :: Delete ( cprop_hdl )
- internal feature (not documented)
PropertyHandle :: Delete ( cnstring )

Implementation details

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

to list

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)

to list

- 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.

to list

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

to list

- internal feature (not documented)
logical PropertyHandle :: Delete ( NString &cnstring )
- cnstring - String containing the text

to list

to top Comment