Using managed versions
In order to define major versions for a database, managed versioning has to be enabled by running the DBVersion utility. or by calling Database::versioningMode(). In order to combine managed versions with any kind of versioning scope, one may also request managed in combination with synchronized and/or any versioning scope (e.g. managedSynchronizedOwner).
New major versions can be created or updated (begin/end), as long as the end of a major version is still in future. Major versions defined in the past cannot be updated. The first major version has an open start point. The last major version always has an open end until the end point is set by the start point of the next major version.
One may reset a complete major version, which will remove all changes made in this major version and recreates the database state for the previous version.
// DBVersion Utility: set version mode
DBVersion.exe c:\Sample\sample.dat -M:M
// set version mode from within a program: Database dbh;
... fragment ( ObjectSpace &dbh ) {
dbh.versioningMode(managed);
}
In order to create major versions, the managed versioning feature has to be enabled. For creating newmajor versions, theDBVersion utility might be called. From within an application, one may also call Database::createMajorVersion(). Versioning mode is set to managedDatabase automatically, whencalling Database::createMajorVersion().
When creating a new major version, the current version will be terminated at the starting time point for the new major version. By default, starting point for a new version is the current time. The starting point for the first version (version 0) is always open. The last defined version is always an open version, which is valid, until the next version will be created defining the end of the last version.
Major versions are timestamped. Thus, one may define the starting points of new versions in advance (DBVersion,Database::createMajorVersion()). When opening an object space, the current access version is set automatically to the major version containing the current time point. i.e. the access version automatically changes, when the time for the new version has been reached.
// DBVersion Utility: Create new version slice
DBVersion.exe c:\Sample\sample.dat create -M:md -T(2010-01-01 00:00:00,00)
// create new version from within a program: ObjectSpace osh;
... fragment ( Database &dbh ) {
dbh.createMajorVersion(); // now (2013/11/17 12:46,45)
dbh.createMajorVersion(DateTime("2014-01-01 00:00:00,00"); // starts at 1. january 2014
}
Versions are not automatically changed, when the object space has been opened, i.e. in order to adjust the version currently active for an object space, one has to close the object space (database) and reopen it again or call ObjectSpace::setMajorVersion().
In order to change major version's borders, version intervals might be updated. Updating version termination date is possible via the DBVersion utility or by calling Database::updateMajorVersion(). As long as the version end is defined in future, the version end (which is also the begin of the next version) might be updated.
Changing version borders is possible for active and future versions, but not for versions, which had already been closed, i.e. where the termination date has already exceeded. When updating the starting point for a major version, the timestamp value has to be greater than the beginning of the previous and less than the staring pint of the next major version (when already being defined) . The starting point for the first major version (version 0) is always open.
// DBVersion Utility: Update version slice
DBVersion.exe c:\Sample\sample.dat update -V:5 -T(2013-12-01)
// Update version slice from within a program: ObjectSpace osh;
... fragment ( Database &dbh ) {
dbh.updateMajorVersion(5,DateTime("2014-02-01"));
}
When versioning mode is set to any of the managed versioning modes (managed, ManagedConsistent, managedSynchronized..., managedInstance or managedOwner) database versions can be reset. Resetting major versions for the database to an earlier version (roll back) is possible either by calling the DBVersion utility or by calling Database::resetMajorVersion(). Resetting a version will remove all database version entries from the database with a version number greater than or equal to the version number to be reset. Deleted entries will be reactivated.
When versioning mode is managedDatabase or managedSynchronized..., the last versioning scope version number for the previous major version will be restored.
// DBVersion Utility: Update version slice
DBVersion.exe c:\Sample\sample.dat reset -V:5
// Update version slice from within a program: Database dbh;
... fragment ( Database &dbh ) {
dbh.resetDataVersion(5);
}
In order to browse data for an older major version, one may set the access version for an object space by calling ObjectSpace::setMajorVersion(). Older versions should be used in read mode, only.
Database entries, which have already been updated in a higher major version cannot be updated at all. Database entries, which have not been changed in higher versions, might be updated, but this may lead to conflicts (e.g. when indexes needs to be maintained, which already got a higher version). Thus, browsing data only is suggested, when activating older versions.
In order to obtain the access version currently used by the object space, one may call ObjectSpace::majorVersion().
In order to retrieve information about start and stop time for major versions, one may call the list operation of the DBVersion utility or Database::majorVersionBegin()and/or Database::majorVersionEnd().
// DBVersion Utility: List version slices
DBVersion.exe c:\Sample\sample.dat list
// Update version slice from within a program: ObjectSpace osh;
... fragment ( Database &dbh ) {
int i = 0;
int count = dbh.majorVersionCount();
DateTime start, stop;
while ( i < count ) {
start = odb.majorVersionBegin(i);
stop = odb.majorVersionEnd(i);
// print i, start, stop
}
}