company logo

PropertyHandle :: Add - Add instance to collection

You can add instances to any type of collection or reference. When adding an instance to a collection the cardinality for the collection is checked as well as unique key requirements. When adding an instance to an owning collection or reference a new database instance will be created. Adding an instance to a collection or reference is possible by position, key (when sort orders are defined for the collection) or with an initializing instance. When terminating successfully the instance added to the collection is selected in the property handle.

The position passed (set_pos0) when adding an instance to a collection has an effect only, when the collection is unordered. Otherwise the position is determined by the key value. For ordered instances you must always pass a sort or identifying key value. When passing a sort key this must correspond to the active order (index) set for the property handle. When an __AUTOIDENT key has been defined the next instance number is determined in the collection or in its most top super set (based collections).

Collection based references

When adding an instance to a collection based reference or collection (i.e. a subset of another collection) the function checks whether an instance with the same key (identifying key of the instance to be added) does already exist in the base collection (super set). In this case no new instance is created but the instance found in the base collection is added to the current collection or reference. The instance values are updated from the values of the instance found in the base collection. When no instance has been found the new instance (key) is added to the base collection and than to the current collection. In any case the instance is shared between the base and the current collection, i.e. both refer to the same instance.

For base collections you must always provide an identifying key. The function will store the passed keys in an initial instance (which can also be passed by the application). From this initial instance the function extracts the identifying key for searching the instance in the basic collections, i.e. the identifying key is the minimum information an instance should have.

Using shared base structure instances

When the collection refers to an instance which has one or more shared base instances the instance must contain identifying key values for all shared base instances. Add by key you can use in this case only, when the key provides information for all base instance identifying keys.

Events

When adding an instance to a collection the function fires an insert event and an inserted event. You can use the insert event for checking the operation and deny it. When creating a new instance, an initialize event is generated when initializing the instance. Moreover, a create and created event will be generated.
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. Add instance
    ::Instance PropertyHandle  :: Add ( ::Instance newinst, int32 set_pos0_w=AUTO )

    This function is used to insert an instance at a certain position in an unordered collection. The function inserts the instance passed at the passed position (set_pos_w). When no position or AUTO is passed as position the instance is inserted in front of the selected instance. When no instance is selected the new instance is appended to the end of the collection.

    When the collection is ordered the position passed will be ignored and the instance will be inserted in the collection according to the key passed within the instance.
    • newinst - New instance

      The new instance refers to the data area of the instance to be added to a collection. The instance contains a reference to a properly structured area.

      You can pass the instance as (void *) which will be automatically converted into an instance handle. Only attributes of the new instance are added to the database. References or relationships in the new instance will be ignored (if there are any).
    • 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. Add instance by key value
    ::Instance PropertyHandle  :: Add ( ::Key sortkey, ::Key identkey_w=Key() )

    The function tries to locate an instance with the passed key in the super set of the collection. When no super set is defined or no instance could be found, a new instance with the given key will be created.

    The function adds an instance by key (sort-key). When the collection is unordered the sort key will be interpreted as identifying key (when no extra identifying key is passed). When a sort order has been selected for the collection that is not the identifying key and that does not contain the identifying key, both, sort key and identifying key must be passed to the function.

    • sortkey - Sort key value

      The key is provided in the internal key format. When necessary the key value can be converted from a string into the internal format using the ({.r pib.StringToKey}()) function. Regardless on the type key values are passed as (char *) areas.
    • identkey_w - Ident key value

      The key is provided in the internal key format. When necessary the key value can be converted from a string into the internal format using the ({.r pib.StringToKey}()) function. Regardless on the type key values are passed as (char *) areas. NULL indicates that no key value has passed.

             Default: Key()
    3. to list
  3. Add instance by key and position
    ::Instance PropertyHandle  :: Add ( int32 set_pos0, ::Key sortkey, ::Key identkey_w=Key() )

    The function tries to locate an instance with the passed key in the super set of the collection. When no super set is defined or no instance could be found, a new instance with the given key will be created.

    The function adds an instance by key (sort-key). When the collection is unordered, the instance is inserted at the position passed in set_pos0. When a sort order has been selected for the collection that is not the identifying key and that does not contain the identifying key, both, sort key and identifying key must be passed to the function.

    • set_pos0 - 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).
    • sortkey - Sort key value

      The key is provided in the internal key format. When necessary the key value can be converted from a string into the internal format using the ({.r pib.StringToKey}()) function. Regardless on the type key values are passed as (char *) areas.
    • identkey_w - Ident key value

      The key is provided in the internal key format. When necessary the key value can be converted from a string into the internal format using the ({.r pib.StringToKey}()) function. Regardless on the type key values are passed as (char *) areas. NULL indicates that no key value has passed.

             Default: Key()
    4. to list
  4. Create instance at position
    ::Instance PropertyHandle  :: Add ( int32 set_pos0_w=AUTO, logical init_inst=YES )

    This function is used to create an instance at a certain position in an unordered collection. The function creates the instance at the passed position (set_pos_w). When AUTO is passed the instance is created in front of the selected instance. When no instance is selected the new instance is appended to the end of the collection.

    The instance in the property handle can be initialized before calling the Add function calling GetInitInstance() and setting initial property values. In this case the init_inst option must be set to NO when calling the function (otherwise, the instance will be initialized by the system) and the function operates similar to the "Add instance at position" function. The instance can be also initialized before adding to the collection using the DBInitialized() event in the structure context.

    When the collection is ordered the position passed will be ignored and the instance will be inserted in the collection according to the key passed within the initialized instance. When the instance is not initialized, the instance is created with the default values defined in the data model (structure definition).
    • 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
    • init_inst - Add initialized instance

      The option forces the function to use the internal instance area for creating a new instance in the collection. This instance has been provided using the GetInitInstance() function and has to be filled by the application before calling the Add() function.

             Default: YES
    5. to list
  5. Add instance by property value
    ::Instance PropertyHandle  :: Add ( PropertyHandle &cprop_hdl )

    The function checks whether the property handle passes a numerical value or not. When passing a numerical value the function creates an instance at the position according to the number passed in the property handle (-> "Create instance at position"). Otherwise the value in the property handle is interpreted as string key, which will be converted into key and adds an instance by key value to the collection (-> "Add instance by key value")..
    • cprop_hdl - Property Handle
    6. to list
  6. - internal feature (not documented)
    ::Instance PropertyHandle  :: Add ( NString &cnkey )
    • cnkey - - Title unknown
    7. to list
  7. - internal feature (not documented)
    ::Instance PropertyHandle  :: Add ( int32 set_pos0, NString &cnstring )
    • set_pos0 - 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).
    • cnstring - String containing the text
    8. to list
to top next upper table of contents Comment