Database :: open - Open database handle

Implementation overview

• Open database handle copy
  Database :: open ( cDatabase )
• Open database handle
  Database :: open ( cDictionary, sFilePath, eStorageType, eResourceType, eAccessMode, bShared, sKeyString, bOnlineVersioning, iSchemaVersion, bEnableContext, bSystemUpgrade )
• Open database handle
  Database :: open ( cDictionary, sFilePath, eAccessMode, bShared, sKeyString )
• Open database handle
  Database :: open ( cDictionary, sFilePath, eAccessMode, bShared )
• Create database handle from dictionary handle
  Database :: open ( cDictionary, eAccessMode )
• Create new database
  Database :: open ( sFilePath, iDataAreaSize, bPlatformIndependent )
• Open database by path
  Database :: open ( cDictionary, sFilePath )

Implementation details

1. Open database handle copy
   Database  :: open ( odaba::Database &cDatabase )
   

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

   Handle copies for the same database access object must not be used in different threads. In order to provide thread-save database access, object space access copies should be used.

   If cDatabase is not opened, the calling database handle will be closed.

   • 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.

to list
2. Open database handle
   Database  :: open ( odaba::Dictionary &cDictionary, odaba::String &sFilePath, odaba::StorageTypes eStorageType, odaba::ResourceTypes eResourceType, odaba::AccessModes eAccessMode, bool bShared, odaba::String &sKeyString, bool bOnlineVersioning, int32 iSchemaVersion, bool bEnableContext, bool bSystemUpgrade )
   

   The function creates a database handle for an opened dictionary handle passed in rDictionary.

   The database path (sFilePath) passed to the function contains the database location (local or file server) or an option name (server). Local file paths may contain option names that are resolved before opening the database.

   The database storage type passed in eStorageType defines the type of data store. When passing UndefinedStorage, the storage type is determined from the file name extension. Usually, ODABA is used as storage type. The eResourceType parameter defines the way the database is opened, i.e. locally or in client/server mode.

   The database can be opened in read or write mode (eAccessMode). Passing Update in eAccessMode will open the database in write mode, too. When running the database in file server mode, bShared defines whether the database is running exclusive or can be shared with other users.

   In order to automatically upgrade instances to newer schema version, true has to be passed in bOnlineVersioning. An older schema version for the database can be opened by passing an appropriate schema version in iSchemaVersion.

   Usually, business rules (context classes) are enabled for the database. In order to disable business rules, false has to be passed in bEnableContext. When disabling business rules, the database has to be closed and reopened in order to activate business rules again.

   Database handles are not thread-save. In order to run a database within different threads, an access object copy for the database should be provided.

   In order to read an older version database entries, one may call Database::setVerion().

   // option might be defined in configuration file

   MyProject=Sample

   // path name will be resolved as follows

   %MyProject%/data/%MyProject%.dat --> Sample/data/Sample.dat

   • cDictionary - Dictionary handle

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

   • sFilePath - Complete file path
   • eStorageType - Database storage type

     The database storage type defines the type of database used for storing data. Usually, the storage type is ODABA.

   • eResourceType - Resource type

     Depending on the resource type the database or dictionary is opened on the client or server side.

   • eAccessMode - Access mode

     Access mode for a property handle or database.

   • bShared - Shared database access

     Passing true indicates that multi-user access is requested. False indicates exclusive use of database. Accessing a database in update or write mode, false guarantees absolute exclusive access.

   • sKeyString - String key forcoded database

     When a database is encoded, an access key is required (when not being defined in dictionary).

   • bOnlineVersioning - Enable online versioning

     When this option is set to true, the database will be enabled for on line versioning. When the option is set to false, the system option ONLINE_VERSION is checked instead.

   • iSchemaVersion - Scheme version

     Schema versions are numbered consecutively beginning with 0. In order to refer to the current schema version, the version value may be set to -1.

   • bEnableContext - Disable context

     When passing false for this option, this indicates that the application is running as system application. In this case context functions are disabled and will not be executed. This option should never be set in normal applications because this may lead to logical inconsistency of the database.

     When passing true, the option value is read from the current settings for the ENABLE_CONTEXT system option.

     
     

   • bSystemUpgrade - Automatic system upgrade

     When system version has been changed, i.e. structure for internal headers has been changed, usually an automatic upgrade to current system version will be done, when opening a database in write mode. In order to suppress system version upgrade, this property may be set to false. The default setting is true.

     After upgrading a database to a newer system version, the database cannot be accessed with older software versions.

     In order to disable automatic system upgrade for all databases opened in an application, the option may be set on global level to false (or NO):

     SYSTEM_UPGRADE=NO

to list
3. Open database handle
   Database  :: open ( odaba::Dictionary &cDictionary, odaba::String &sFilePath, odaba::AccessModes eAccessMode, bool bShared, odaba::String &sKeyString )
   

   The function creates a database handle for an opened dictionary handle passed in cDictionary.

   The database path (sFilePath) passed to the function contains the database location (local or file server) or an option name (server). Local file paths may contain option names that are resolved before opening the database.

   The database storage type is determined from the file name extension. Usually, ODABA is used as storage type. Depending on the way, the dictionary has been opened, the data base is opened as server client (when the dictionary is a server client) or as local or file server database.

   The database can be opened in read or write mode (eAccessMode). Passing Update in eAccessMode will open the database in write mode, too. When running the database in file server mode, bShared defines whether the database is running exclusive or can be shared with other users.

   In order to access a coded database, the database key may be passed in sKeyString (usually 64-bit encoded binary key).

   // option might be defined in configuration file

   MyProject=Sample

   // path name will be resolved as follows

   %MyProject%/data/%MyProject%.dat --> Sample/data/Sample.dat

   • cDictionary - Dictionary handle

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

   • sFilePath - Complete file path
   • eAccessMode - Access mode

     Access mode for a property handle or database.

   • bShared - Shared database access

     Passing true indicates that multi-user access is requested. False indicates exclusive use of database. Accessing a database in update or write mode, false guarantees absolute exclusive access.

   • sKeyString - String key forcoded database

     When a database is encoded, an access key is required (when not being defined in dictionary).

to list
4. Open database handle
   Database  :: open ( odaba::Dictionary &cDictionary, odaba::String &sFilePath, odaba::AccessModes eAccessMode, bool bShared )
   

   The function creates a database handle for an opened dictionary handle passed in cDictionary.

   The database path (sFilePath) passed to the function contains the database location (local or file server) or an option name (server). Local file paths may contain option names that are resolved before opening the database.

   The database storage type is determined from the file name extension. Usually, ODABA is used as storage type. Depending on the way, the dictionary has been opened, the data base is opened as server client (when the dictionary is a server client) or as local or file server database.

   The database can be opened in read or write mode (eAccessMode). Passing Update in eAccessMode will open the database in write mode, too. When running the database in file server mode, bShared defines whether the database is running exclusive or can be shared with other users.

   // option might be defined in configuration file

   MyProject=Sample

   // path name will be resolved as follows

   %MyProject%/data/%MyProject%.dat --> Sample/data/Sample.dat

   • cDictionary - Dictionary handle

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

   • sFilePath - Complete file path
   • eAccessMode - Access mode

     Access mode for a property handle or database.

   • bShared - Shared database access

     Passing true indicates that multi-user access is requested. False indicates exclusive use of database. Accessing a database in update or write mode, false guarantees absolute exclusive access.

to list
5. Create database handle from dictionary handle
   Database  :: open ( odaba::Dictionary &cDictionary, odaba::AccessModes eAccessMode )
   

   The function creates a database handle from the dictionary handle. Usually, all database handle functions are available for the dictionary as well. Since a dictionary database may contain additional database resources, it might be useful in special cases to refer to the dictionary as database, in which case the dictionary handle passed cDictionary in could be transformed into a database handle by calling this function.

   The function allows also creating a write access database handle for a read-only dictionary handle by passing Write in eAccessMode. Passing Update in eAccessMode will open the database in write mode, too.

   • cDictionary - Dictionary handle

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

   • eAccessMode - Access mode

     Access mode for a property handle or database.

to list
6. Create new database
   Database  :: open ( odaba::String &sFilePath, int64 iDataAreaSize, bool bPlatformIndependent )
   

   This function allows explicitly creating a new database. Usually creating a database explicitly is not necessary. When, however, special options are required, this function can be used.

   In order to create a platform independent database, which can be copied easily between different hardware platforms, true has to be passed in bPlatformDependent.

   In order to limit the data area size for the database, an appropriate value has to be passed in iDataAreaSize. In this case, the data area is preallocated, but will not expand automatically.

   Notes:

   The errorneous implementation of

   Database db;

   db.open("my.db",Read,true);

   results in calling this implementation (because enums autocast to int).

   The programmer should use the simple open() implementation, instead.

   • sFilePath - Complete file path
   • iDataAreaSize - Size for data area

     When no data area size had been defined (0), the data area expands whenever more space is needed.

     The maximum size for data areas in a 32-bit versions is 4,026,531,840 (0xF0000000) bytes or nearly 4GB. For 64-bit versions, the maximum size is 281,474,976,710,656 or 256 TB.

   • bPlatformIndependent - Platform independence option

     The platform independence option indicates that integer numbers are to be stored in platform independent format. This information is stored in the database header after creating the database.

to list
7. Open database by path
   Database  :: open ( odaba::Dictionary &cDictionary, odaba::String &sFilePath )
   

   The function provides a simple way of opening a database handle for read access and for shared use. The function creates a database handle for an opened dictionary handle passed in rDictionary.

   The database path (sFilePath) passed to the function contains the database location (local or file server) or an option name (server). Local file paths may contain option names that are resolved before opening the database.

   The database storage type is determined from the file name extension. Usually, ODABA is used as storage type. Depending on the way, the dictionary has been opened, the data base is opened as server client (when the dictionary is a server client) or as local or file server database.

   // option might be defined in configuration file

   MyProject=Sample

   // path name will be resolved as follows

   %MyProject%/data/%MyProject%.dat --> Sample/data/Sample.dat

   • cDictionary - Dictionary handle

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

   • sFilePath - Complete file path
to list