company logo

Database :: open - Open database handle

The function allows opening a database handle. When the database is already opened, it will be closed before being opened again.

A database can be opened in local or file server mode, or in server mode (object or replication server). Local mode usually implies exclusive access. When running several applications on a local machine the database should be opened in file server mode in order to provide concurrent access to the database. Server mode is suggested when running the database from different clients on a central server. When opening the same database (same file location) in server mode, there will be only one database access object created on the server.

Usually, opening a object server database requires that database and dictionary refer to the same server. Thus, connection information are taken from the dictionary handle passed to the open() function.

Notes:

In order to guarantee scalability, one should never open a database twice in the same application, since this my cause problems, when running the application in client/server environment. In order to run multi-thread applications, copies for object space access objects should be created.

When opening more than one database for the same dictionary, all databases have to be opened with the same schema version (usually the current version). After opening the first database, the schema version must not be changed.

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 object copies should be used.

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

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

  2. to list
  3. 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 for encoded database

      When a database is encoded, a string 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 - - internal feature (not documented)
  4. to list
  5. 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 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.

    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.

    • sKeyString - String key for encoded database

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

  6. to list
  7. - internal feature (not documented)
    Database  :: open ( odaba::Dictionary &cDictionary, odaba::String &sFilePath, odaba::AccessModes eAccessMode, bool bShared )
    • 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.

  8. to list
  9. 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.

  10. to list
  11. 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.

  12. to list
  13. 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
  14. to list