company logo

Database :: openReplicate - Open replication database

The function opens a replication database by passing server name and port or by referring to an opened connection in the passed client handle. In contrast to an object server, the dictionary need not to reside on the same server as the database. Hence, the database might refer to another connection than the dictionary, which is stored locally, usually.

Implementation overview

Implementation details

  1. Open replication database with connected client
    Database  :: openReplicate ( odaba::Client &cClient, odaba::Dictionary &cDictionary, odaba::String &sFilePath, odaba::String &sLocalPath, odaba::AccessModes eAccessMode, bool bShared, odaba::String &sKeyString, bool bOnlineVersioning, bool bEnableContext )

    The function creates a database handle for an opened dictionary handle passed in rDictionary. The server connection has to be provided in the client passed in rClient, which must already have been connected to the server.

    The database path (sFilePath) passed to the function contains an option name, which refers to the option defined on the server side for the database file location. The path passed in sLocalPath refers to the replicate in the local environment.The local file path may contain option names that are resolved before opening the database.

    The database can be opened in read or write mode (eAccessMode). When running the local 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.

    For opening an older version for the database one may pass a version number in iVersion.

    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.

    // option might be defined in configuration file

    MyProject=Sample

    // path name will be resolved as follows

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

    • cClient - Client handle

      The client handle refers to an (usually) opened ODABA client. Calling functions with invalid client handles may cause an exception. For checking the client handle, isValid() can be called.
    • 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
    • sLocalPath - Path to local database replicate

      The string contains the complete file path for the local database.
    • 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.
    • 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.
    2. to list
  2. Open replication database by server name and port
    Database  :: openReplicate ( odaba::String &sServerName, int32 iPort, odaba::Dictionary &cDictionary, odaba::String &sFilePath, odaba::String &sLocalPath, odaba::AccessModes eAccessMode, bool bShared, odaba::String &sKeyString, bool bOnlineVersioning, bool bEnableContext )

    The function creates a database handle for an opened dictionary handle passed in rDictionary. The replication client is connected to the server passed in sServerName using the port passed in iPort. When connecting to the server fails, the function throws an exception.

    The database path (sFilePath) passed to the function contains an option name, which refers to the option defined on the server side for the database file location. The path passed in sLocalPath refers to the replicate in the local environment.The local file path may contain option names that are resolved before opening the database.

    The database can be opened in read or write mode (eAccessMode). When running the local 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.

    For opening an older version for the database one may pass a version number in iVersion.

    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.

    // option might be defined in configuration file

    MyProject=Sample

    // path name will be resolved as follows

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

    • sServerName - Server name

      Valid server name or IP address referring to the server in a client server application.

    • iPort - Port number

      The port number must be the same the server has been started with (e.g. 6123). When no port number is passed, the client expects the port number being defined in a system variable SERVER_PORT or in a system environment ini-file on the ODABA installation folder.
    • 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
    • sLocalPath - Path to local database replicate

      The string contains the complete file path for the local database.
    • 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.
    • 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.
    3. to list
to top previous upper table of contents Comment