company logo

Property :: insert - Insert instance to collection

One may insert (add) instances to any type of collection (extent, relationship, reference) as soon as the property has been opened in update or write access mode and the parent property (when existing) is selected.

When inserting an instance to a collection, the cardinality for the collection is checked as well as unique access key constraints. When inserting an instance to an owning collection, a new database instance will be created.

Inserting an instance to a collection is possible by position, access key or by instance. When terminating successfully the instance added to the collection is selected in the property handle.

The position passed (iPosition) when inserting an instance to a collection has an effect only, when the collection is unordered. Otherwise the position depends on the order key value. For ordered instances one always has to pass a key value for the currently selected access key. When an __AUTOIDENT access key has been defined or the key value passed is 0, the new key value will be determined automatically.

When the instance could not be inserted (duplicate key, inverse reference error or others), the function throws an exception, which provides detailed explanations for the error reason.
Notes:

When a filter has been set for the collection, no instance will be selected in the property handle, when the instance created does not match the filter condition.

Collections with supersets

When inserting an instance to a collection with a defined superset (i.e. children as subset of Persons) the function checks whether an instance with the same key (primary key of the instance to be inserted) does already exist in the superset (base collection). In this case no new instance is created but the instance found in the superset is inserted to the current collection. The instance values are updated from the values of the instance found in the superset.

When no instance has been found the new instance (key) is inserted to the superset (or superset hierarchy) and than to the current collection. In any case the instance is shared between all supersets and the current collection, i.e. both (all) refer to the same instance.

In order to support supersets a unique access key must be provided when inserting an instance. The unique access key must be a unique access key for all supersets in the superset hierarchy.
Return value:  Property reference ( odaba::Property & )

A property handle refers to a (usually) opened property. Invalid properties may cause an exception.

Implementation overview

Implementation details

  1. Create and insert new instance
    odaba::Property & Property  :: insert (  )

    The function creates a new instance in a collection. When an instance has been located in the property handle, the new instance is inserted in front of the selected instance. Otherwise, the instance is appended to the end of collection.

    When the collection is ordered, the new instance is inserted according to the initialized key value. Key values for new instances might be initialized by event handlers provided in appropriate context classes. In case of an __AUTOIDENT access key the next higher number is set by the system.
    2. to list
  2. Insert instance
    odaba::Property & Property  :: insert ( odaba::Instance &cInstance )

    This function is used to insert an instance in a collection. The instance data is passed as OIF string in vInstance. When the collection is ordered, the instance is inserted at position according to the access key. When the collection is unordered, the instance is inserted in front of the currently selected instance or at the end when no instance is selected.

    • cInstance - Instance

      The instance is passed as String, which is structured as ESDF data (object interchange format).
    3. to list
  3. Insert instance
    odaba::Property & Property  :: insert ( odaba::Instance &cInstance, int32 iPosition )

    This function is used to insert an instance at a certain position in an unordered collection. The instance data is passed as OIF string in vInstance. The function inserts the instance passed at the passed position (iPosition). When -1 is passed in iPosition, the new instance is appended to the end of the collection.

    When the collection is ordered by an access key, the function throws an exception.
    • cInstance - Instance

      The instance is passed as String, which is structured as ESDF data (object interchange format).
    • iPosition - Position in collection

      The position of an element in a collection is beginning with 0 for the first element.
    4. to list
  4. Insert instance by access key value
    odaba::Property & Property  :: insert ( odaba::Key vSortKey )

    The function is usually called for collections, where the selected access key is the primary key or contains all primary key components. In order to insert an instance by access key value, the key value for the currently selected access key must be passed in vSortKey.

    When the collection is unordered, the instance will be inserted in front of the currently selected instance. When no instance is selected, the instance is appended.

    When a super set has been defined for the collection, the function tries to locate an instance with the passed access key value in the super set hierarchy of the collection. When no super set is defined or no instance could be found, a new instance with the passed access key will be created.

    The function inserts the instance at position determined by access key. When the collection is unordered, the access key is the primary key.

    • vSortKey - Access key

      The sort or access key value is provided as typed string in ESDF or CSV format. Key components can be separated by '|' or ';'.

      // key: name;first_name

      Miller;Paul          // simple positioned CSV key

      "Miller";"Paul Mary" // special characters must be quoted
    5. to list
  5. Insert instance by key and position
    odaba::Property & Property  :: insert ( odaba::Key vPrimaryKey, int32 iPosition )

    The function should be called for unordered collections, only. A collection is considered as unordered, when the currently selected index has no access key or the collection is singular. When the collection is ordered, the function throws an exception.

    When -1 is passed in iPosition, the instance is appended to the end of the collection.

    When the collection has got defined super sets, the function tries to locate an instance in the supe rset hierarchy of the collection with the primary key value passed in vPrimaryKey. The collections in the super set hierarchy must support access key for the primary key.

    When no super set is defined or no instance could be found, a new instance with the given primary key value (vPrimaryKey) will be created.

    When no primary key has been defined for the data type, the key value in vPrimaryKey will be ignored.
    • vPrimaryKey - Primary key value

      The key value for a primary key is provided as typed string in ESDF or CSV format. Key components can be separated by '|' or ';'.

      In order to pass no key value, an empty string ( String() ) can be passed.

      // key: name;first_name

      Miller;Paul          // simple positioned CSV key

      "Miller";"Paul Mary" // special characters must be quoted
    • iPosition - Position in collection

      The position of an element in a collection is beginning with 0 for the first element.
    6. to list
  6. Insert instance by key values
    odaba::Property & Property  :: insert ( odaba::Key vSortKey, odaba::Key vPrimaryKey )

    In order to insert an instance by access key value, the key value for the currently selected access key must be passed. When the currently selected access key is not the primary key, the primary key value should be passed in addition in order to support instance look-up on super sets.

    When the collection has got defined super sets, the function tries to locate an instance in the super set hierarchy of the collection with the primary key value passed in vPrimaryKey. The collections in the super set hierarchy must support access key for the primary key.

    When no super set is defined or no instance could be found, a new instance with the key values passed will be created.

    The function inserts the instance at position determined by access key.

    • vSortKey - Access key

      The sort or access key value is provided as typed string in ESDF or CSV format. Key components can be separated by '|' or ';'.

      // key: name;first_name

      Miller;Paul          // simple positioned CSV key

      "Miller";"Paul Mary" // special characters must be quoted
    • vPrimaryKey - Primary key value

      The key value for a primary key is provided as typed string in ESDF or CSV format. Key components can be separated by '|' or ';'.

      In order to pass no key value, an empty string ( String() ) can be passed.

      // key: name;first_name

      Miller;Paul          // simple positioned CSV key

      "Miller";"Paul Mary" // special characters must be quoted
    7. to list
  7. Insert instance at position
    odaba::Property & Property  :: insert ( int32 iPosition, bool bInstance )

    The function is called for unordered collections in order to insert an instance at a certain position in the collection. A collection is considered as unordered, when the currently selected index has no access key or the collection is singular. The function should not be called, when a super set has been defined for the collection, in which case a key value is required, unless a database context function is implemented to evaluate the required key value.

    When the collection is ordered, the function throws an exception.

    The function creates an instance at position passed in iPosition. When -1 is passed, the new instance is appended at the end of the collection.

    The instance in the property handle can be initialized before calling add() by calling initializeInstance() and setting initial property values. In order to avoid reinitializing the instance, the bInstance option must be set to true. In order to initialize the instance, the application may also overload the doBeforeInitialize() database event handler.

    In order to insert an initialized instance (initializeInstance()) by key values stored in the instance, save() should be called, instead.

      initializeInstance();

      //... initialize values

      save();

    • iPosition - Position in collection

      The position of an element in a collection is beginning with 0 for the first element.
    • bInstance - Use internal instance

      The option forces the function to use the internal instance area without reinitializing is. When not being set, the internal instance is reinitialized before the operation is executed.

    8. to list
  8. Create property from selected instance
    odaba::Property & Property  :: insert ( odaba::Property &cProperty, int32 iPosition )

    This function is used to insert an instance at a certain position in an ordered or unordered collection.

    In an unordered collection the instance data is passed as selected instance in the property rProperty. The function inserts the instance passed at the passed position (iPosition). When -1 is passed in iPosition, 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 by an access key, iPosition value will be ignored and the instance will be inserted in the collection according to the access key value extracted from the instance.
    • cProperty - Property reference

      A property handle refers to a (usually) opened property. Invalid properties may cause an exception.
    • iPosition - Position in collection

      The position of an element in a collection is beginning with 0 for the first element.
    9. to list
to top previous next upper table of contents Comment