company logo

Property :: insertGlobal - Add instance globally to collection

The function works the same way as insert(), except that global instances are created outside the transaction. When a local collection is not based on a global (extent) super set or when not running in a transactions the function works the same way as insert().

When a local collection is based on a global super set, global instances are created implicitly. Creating global instances in a transaction prevents all other users from creating global instances for the same extent until the transaction is closed, since the index for the global collection is locked until terminating the transaction. Especially when creating instances in local collections that are based on global collections (extents), uncomfortable locks may block the system. In this case insertGlobal() should be called instead of insert().

For more details see insert().
Notes:

Using insertGlobal() for creating a new instance the instance will remain in the global collection also when rolling back the transaction.

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. Insert instance to collection
    odaba::Property & Property  :: insertGlobal ( 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).
    2. to list
  2. Insert instance
    odaba::Property & Property  :: insertGlobal ( odaba::Instance &cInstance, int32 iPosition )

    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).
    • iPosition - Position in collection

      The position of an element in a collection is beginning with 0 for the first element.
    3. to list
  3. Insert instance by access key value
    odaba::Property & Property  :: insertGlobal ( 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
    4. to list
  4. Insert instance by key and position
    odaba::Property & Property  :: insertGlobal ( 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.
    5. to list
  5. Insert instance by key values
    odaba::Property & Property  :: insertGlobal ( 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
    6. to list
  6. Insert instance at position
    odaba::Property & Property  :: insertGlobal ( 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.

    7. to list
  7. Insert instance from selected instance
    odaba::Property & Property  :: insertGlobal ( odaba::Property &cProperty, int32 iPosition )

    This function is used to insert an instance at a certain position in an unordered collection. The instance data is passed as selected instance in 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, the iPosition value is ignored and the instance will be inserted in the collection according to the access key value extracted from the instance.

    When no instance is selected in the property handle passed in rProperty, the function throws an exception.
    • 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.
    8. to list
to top previous next upper table of contents Comment