ObjectSpace :: open - Open database object space handle

Implementation overview

• Create object space handle copy
  ObjectSpace :: open ( cObjectSpace )
• Open different version for object space
  ObjectSpace :: open ( cDatabase, eAccessMode )
• Create object space handle for data source
  ObjectSpace :: open ( sDataSourceName, eAccessMode )
• Open subordinated object handle by identity
  ObjectSpace :: open ( cObjectSpace, iObjectID, eAccessMode )
• Open subordinated object handle by object name
  ObjectSpace :: open ( cObjectSpace, sObjectSpaceName, eAccessMode )

Implementation details

1. Create object space handle copy
   ObjectSpace  :: open ( odaba::ObjectSpace &cObjectSpace )
   

   This function creates a copy of the object space handle passed in cObjectSpace. Both, the copy and the origin are referring to the same access object. The access object will be closed when closing the last object space handle referring to it, regardless on the sequence the handles have been opened.

   If cObjectSpace is not opened the function does not throw an exception and the calling ObjectSpace handle is closed, too.

   • cObjectSpace - Object space reference

     The reference refers to an opened or not opened object space handle.

to list
2. Open different version for object space
   ObjectSpace  :: open ( odaba::Database &cDatabase, odaba::AccessModes eAccessMode )
   

   Especially when working in multi-thread applications, each thread requires a separate object space handle, i.e. a separate access object. In order to create different access objects referring to the same database resource, necessary object space handles can be created from a database passed in cDatabase.

   Depending on the database resource type (local or server), the object space handle is created as local or server client access object.

   In order to change the access mode, the new access mode can be passed in eAccessMode. In order to use the access mode set for the passed database, UndefinedMode should be passed in eAccessMode. Passing Update in eAccessMode will open the database in write mode, too. For opening the object space for write access, the database must not be opened in read mode.

   
   

   • cDatabase - Database handle

     The database handle refers to an (usually) opened database. Calling functions with invalid database handles may cause an exception. For checking the database handle, isValid() can be called.

   • eAccessMode - Access mode

     Access mode for a property handle or database.

to list
3. Create object space handle for data source
   ObjectSpace  :: open ( odaba::String &sDataSourceName, odaba::AccessModes eAccessMode )
   

   This function opens an object space handle according to the specification in a data source passed in sDataSourceName

   The data source has to be defined as section in the configuration or ini-file used when initializing the application (odaba::initializeApplication()) or as data source in the data catalog referenced in the configuration file.

   The access mode passed in eAccessMode allows overwriting the access mode defined in the data source.

   // create object space from data source: ObjectSpace osh;

     osh.open("Sample",Write);

   • sDataSourceName - Data source name

     The name of the data source refers to a section in a configuration or ini-file or to a data source defined in the data catalog defined for the application. Other data source variables are set from the data source definition referred to by the data source name.

   • eAccessMode - Access mode

     Access mode for a property handle or database.

to list
4. Open subordinated object handle by identity
   ObjectSpace  :: open ( odaba::ObjectSpace &cObjectSpace, int64 iObjectID, odaba::AccessModes eAccessMode )
   

   The function opens a subordinated object space handle by locating the object space using the local object identity (LOID) passed in iObjectID. The object identity has to refer to a valid object space. In order to check object identity validity, the SDB_NamedObject extent can be opened and read.

   In order to change the access mode, the new access mode can be passed in eAccessMode. Passing Update in eAccessMode will open the database in write mode, too. In order to use the access mode set for the passed database, UndefinedMode should be passed in eAccessMode.

   ... fragment ( ObjectSpace &osh) {

     Property    ph(osh,"SDB_NamedObject",Read);

     ObjectSpace sub_osh;

     while ( ph.next(true) ) {

       // open OS by identity

       sub_osh.Open(osh,ph.value("object_ref.ebsnum").toBig(),Read);

       // do something

       sub_osh.close();

     }

   }

   • cObjectSpace - Object space reference

     The reference refers to an opened or not opened object space handle.

   • iObjectID - Local instance identity

     The object or instance identity is a unique identity within a database.

   • eAccessMode - Access mode

     Access mode for a property handle or database.

to list
5. Open subordinated object handle by object name
   ObjectSpace  :: open ( odaba::ObjectSpace &cObjectSpace, odaba::String &sObjectSpaceName, odaba::AccessModes eAccessMode )
   

   The function opens a subordinated object space handle by locating the object space using the object space name passed in sObjectSpaceName. The object name need not to refer to an existing object space name. When not yet existing, an object space with the name passed to the function will be created and added to the object name list. In order to check object space names, the SDB_NamedObject extent may be opened and read. In order to create a new subordinated object space, Write has to be passed in eAccessMode.

   In order to change the access mode, the new access mode can be passed in eAccessMode. In order to use the access mode set for the passed database, UndefinedMode should be passed in eAccessMode.

   ... fragment ( ObjectSpace &osh) {

     Property    ph(osh,"SDB_NamedObject",Read);

     ObjectSpace sub_osh;

     while ( ph.next(true) ) {

       sub_osh.Open(osh,ph.value("sys_ident").toString(),Read); // open OS by name

       // do something

       sub_osh.close();

     }

   }

   • cObjectSpace - Object space reference

     The reference refers to an opened or not opened object space handle.

   • sObjectSpaceName - Object space name

     Names can be assigned to object spaces in order to access an object space via name.

     Usually, however, no names are assigned to object spaces. In order to pass no object space name, an empty string ( String() ) has to be passed.

   • eAccessMode - Access mode

     Access mode for a property handle or database.

to list