DatabaseHandle :: Open - Opening a database handle
The function allows opening a database handle. When the database handle is already opened it will be closed before reopening it.
A database can be opened in local, in client/server mode or in file server mode. Local mode usually implies exclusive access. When running several applications on a local machine the database should be opened in file server mode to provide concurrent access to the database. Client/server mode is suggested when running the database from different clients on a central server.
Passing RES_replication to this function for opening a replication database will cause an error. Opening a replication database requires an explicit call of OpenReplicate().
Implementation details
The function creates a database handle for an opened dictionary. The database path (cpath) passed to the function may contain system variable references that are resolved before opening the database.
The database can be opened in read or write mode (accept). When running the database in file server mode the net option defines whether the database is running exclusive or can be shared by other users. The local_resources parameter defines the way the database is opened.
For opening an older version for the database one may pass a version number in version_nr.
- dicthdl_refc - - internal feature (not documented)
- cpath - Complete file or directory path
- accopt - Access mode
- w_netopt
- Multi-user option
Passing this value as true (YES) indicates that multi-user access is requested. False (NO) indicates exclusive use of database. Accessing a database in update or write mode, NO guarantees absolute exclusive access.
- key_buffer
- - internal feature (not documented)
Default: NString::Null()
- online_version
- Online versioning option
When this option is set the database will be enabled for on line versioning. When the option is set to NO the system variable ONLINE_VERSION is checked instead.
Default: NO
- local_ressources
- Resource type
Depending on the resource type the database or dictionary is opened on the client or server side.
Default: RES_automatic
- sysenv
- System application
This option 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 running a replication client, this option contains the value 2. Running a replication client in a system application, the option contains the value 3.
For maintenance purposes, 4 might be passed in the variable. In this case, versions will not be upgraded automatically.
Default: NO
- schema_version_w
- 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.
Default: CUR_VERSION
- rb_type
- - internal feature (not documented)
Default: RBT_ODABA
- upgrade_opt
- 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
Default: YES
- opt_64bit
- 64 bit compiler version
Values have following meaning:
- 0 - automatically determine large file option
- 1 - large file requested
- 2 - large file not supported (file size limited to 2GB)