Property :: get - Get property instance

Implementation overview

• Select located instance
  Property :: get (  )
• Select instance by instance
  Property :: get ( cInstance )
• Get instance by key value
  Property :: get ( cKey )
• Get instance by LOID
  Property :: get ( vLOID )
• Get Instance by index position
  Property :: get ( iPosition )
• Select instance by property instance
  Property :: get ( cProperty )

Implementation details

1. Select located instance
   odaba::Property & Property  :: get (  )
   

   The function returns true, when an instance has been located in the property handle. When no instance is located the function returns false.

   When the instance is located but not selected, the function reads the instance.

   When an instance is already selected in the property handle and the current access mode does not correspond to the required access mode, the function will reread the instance. Thus, the function can be used to update the access mode when the selected instance was write protected. Selections in subordinated property handles are reset when rereading the instance.

to list
2. Select instance by instance
   odaba::Property & Property  :: get ( odaba::Instance &cInstance )
   

   The function tries to locate an instance by an instance passed in vInstance. The instance type for the instance has to be the same or has to inherit from the instance type in the current property handle.

   In order to locate the instance in the property handle, an appropriate access key will be extracted from the instance.

   When no access key is available for the property handle, when types differ or when the instance does not contain data, the function throws an exception.

   • cInstance - Instance

     The instance is passed as String, which is structured as ESDF data (object interchange format).

to list
3. Get instance by key value
   odaba::Property & Property  :: get ( odaba::Key &cKey )
   

   When reading an instance by key, the key value passed in cKey is considered as key value for the currently selected access key (changeAccessKey()).

   For unordered collections, a key value for the primary key might be passed.

   When accessing instances in the VOID extent, The key can also be an LOID or a GUID string when the property handle has been opened for reading by local object identities (__LOID) or by global unique identifiers (__GUID).

   When positioning the instance for a path property the key is composed by all access keys along the path.

   • cKey - Key value

     A key value is the key definition and a value for the key. The key value is typically provided in ESDF format. Other formats might be set (OIF, XML)

to list
4. Get instance by LOID
   odaba::Property & Property  :: get ( int64 vLOID )
   

   The function tries to locate in instance by local object identifier (LOID). When the property handle handles a collection, the function tries to locate an instance with the LOID passed within the collection. When the property handle handles all instances in the database (VOID handle, see example below), the function tries to locate an instance in the database with the LOID passed in vLOID.

   // open database instance hande for all instances

   Property   all(database,"VOID",Read);

   • vLOID - Local object identifier

     The LOID is passed as 64-bit integer. 0 is considered as empty LOID. -1 is also considered as empty, but it is used often for indicating automatic value or no result.

to list
5. Get Instance by index position
   odaba::Property & Property  :: get ( int32 iPosition )
   

   Reading an instance by position selects the instance at requested position (iPosition) for the selected access key. The value passed in iPosition must be a value greater or equal to 0. In case of an invalid position value, the function throws an exception. The selected instance for a certain position depends on the selected access key.

   Using index positions for reading is also a weak point when collections are updated simultaneously, since the instance position might change when other users insert or remove entries from the collection. To avoid this one may use the lockSet() function in order to prevent other applications from updating the collection.

   Access by position cannot be used for LOID or GUID property handles. Passing a number to an LOID handle interprets the number as local object identity.

   For a path property get() by position automatically changes the selection for higher properties in the path when the end of collection is signaled for a level that is not the top level for the path property.

   • iPosition - Position in collection

     The position of an element in a collection is beginning with 0 for the first element.

to list
6. Select instance by property instance
   odaba::Property & Property  :: get ( odaba::Property &cProperty )
   

   The function tries to locate an instance by an instance selected in another property handle (rProperty). The instance type for the instance selected in rProperty has to be the same or has to inherit from the instance type in the current property handle.

   In order to locate the instance in the property handle, an appropriate access key will be extracted from the instance selected in rProperty.

   When no access key is available for the property handle, when no instance is selected in rProperty or when types differ, the function throws an exception.

   • cProperty - Property reference

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

to list