company logo

Property :: appendKey - Append key to collection

The function creates a name reference in an unordered collection or appends an existing instance. The function can be called for unordered collections, only. A collection is considered as unordered, when the main index has no access key or when the collection is singular. Trying to append a key to an ordered collection will throw an exception.

Name references can be appended unordered collections, only. When the selected index is not an unordered index or when no primary key has been defined for the data type, the function throws an exception.

When the collection has got super sets, the function tries to locate an instance in the super set hierarchy of the collection with the passed primary key. The collections in the super set hierarchy must support access via primary key. When an instance with the key value passed could be located, the instance will be appended to the collection.

When no super set is defined or no instance could be found for the passed key value, a name reference with the primary key value is created for the collection (and all super sets).

When the primary key is an __AUTOIDENT key (automatic number), one may pass an empty key value or 0 in order to create the next auto-number.

When appending a key to a collection, the cardinality for the collection is checked. When the collection requires unique access key, the key value is checked for duplicate. When the key could not be appended (because of duplicate key or other reasons), the function throws an exception, which provides detailed explanations for the error reason.

When terminating successfully, an instance with properly set key attributes will be provided in the property handle. The instance is located but not positioned.
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.

Instead of appendKey(), insertKey() could be used passing the instance count as preferred position. Since appendKey() throws an exception when the collection is ordered, calling the function may fail when changing the object model (from unordered to ordered). Hence, it is suggested using insertKey() rather than appendKey().

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. Append key by instance
    odaba::Property & Property  :: appendKey ( odaba::Instance &cInstance )

    Appending a name reference by an instance creates name references for all indexes in the collection (and its super sets). Required keys are extracted from the instance passed in cInstance. Indexes except the currently selected access index may be ordered or not. In case of duplicate keys for unique indexes the function throws an exception.
    Notes:

    When adding name references to indexes that are nor unique, accessing instances in an overload object space may cause problems, since the system cannot distinguish between instances with same key value.

    • cInstance - Instance

      The instance is passed as String, which is structured as ESDF data (object interchange format).
    2. to list
  2. Append key to collection
    odaba::Property & Property  :: appendKey ( odaba::Key vPrimaryKey )

    The function appends a name reference for the key with the primary key value passed in vPrimaryKey to the collection. The function does not maintain indexes for other keys. In case of duplicate keys for a unique index the function throws an exception.
    • 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
    3. to list
  3. - internal feature (not documented)
    odaba::Property & Property  :: appendKey ( odaba::Key vSortKey, odaba::Key vPrimaryKey )
    • 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
    4. to list
to top previous next upper table of contents Comment