Client :: backupDatabase - Database backup

The function creates a backup from a database. The function may run locally but also on a server client (client connected to a server).

When running backupDatabase() on a server client, the backup request is passed to the server in order to backup the server database. In this case, symbolic file names defined in the servers file catalog have to be passed for the file location passed in sDatabasePath (e.g. sDatabasePath="%MyDatabase%") and in sTargetPath.

When running backup on a server, the server will pause all active clients as long as backup is running (which may take a few minutes). When pausing client, this might access the database read-only. When trying to start a write request (transaction), the client waits until the backup has terminated.

The function throws an exception, when the client handle passed is not valid or when the database backup could not be created successfully.

Implementation overview

Create backup
Client :: backupDatabase ( sDatabasePath )
Store backup file to selected target
Client :: backupDatabase ( sDatabasePath, sTargetPath )
Backup database on server
Client :: backupDatabase ( sDatabasePath, sTargetPath, iWait )

Implementation details

Create backup
Client :: backupDatabase ( odaba::String &sDatabasePath )

The function creates a backup file from the database locates at sDatabasePath at the same location as for the source with the extension .ozi.
- sDatabasePath - File path to database location
  The database path refers to the location of the main database file (root base).
  
  In order to pass no database path, an empty string ( String() ) has to be passed.

to list

Store backup file to selected target
Client :: backupDatabase ( odaba::String &sDatabasePath, odaba::String &sTargetPath )

In order to store the backup in an other folder or with another name, the target file and location name have to be passed in sTargetPath. Active clients are killed immediately without warning.

The function is usually called for local restore. In order to restore a database on server, a timeout interval for pausing clients should be passed. When calling this function for a server client, the function will fail, when at least one client transaction has been started.
- sDatabasePath - File path to database location
  The database path refers to the location of the main database file (root base).
  
  In order to pass no database path, an empty string ( String() ) has to be passed.
- sTargetPath - Target path
  The target path refers to a file location for the target file. The complete path includes file name and directory. It might, however, be defined as absolute path starting with the root device or folder or a relative path.
  
  In order to pass no file path, an empty string ( String() ) may be passed.

to list

Backup database on server
Client :: backupDatabase ( odaba::String &sDatabasePath, odaba::String &sTargetPath, int32 iWait )

When running backupDatabase() on a server, a symbolic file name defined in the servers file catalog has to be passed for the database location (e.g. sDatabasePath="%MyDatabase%"). The file name for the target location (sTargetPath) should be passed as symbolic name as well, which also has to be defined in the servers file catalog.

In order to guarantee a consistent database state while backing up, the server will pause, i.e. read access is still possible but updating data is prohibited. In order to pause the server, all running transactions have to be finished. The timeout for finishing all running transactions can be limited to the number of seconds passed in iWait (e.g. 300). When pausing is not possible during that time interval, the function throws an exception.

Notes:
iWait should be passed as 0 only, when the application is read only. Otherwise, the function fails, when at least one client transaction has been started.
- sDatabasePath - File path to database location
  The database path refers to the location of the main database file (root base).
  
  In order to pass no database path, an empty string ( String() ) has to be passed.
- sTargetPath - Target path
  The target path refers to a file location for the target file. The complete path includes file name and directory. It might, however, be defined as absolute path starting with the root device or folder or a relative path.
  
  In order to pass no file path, an empty string ( String() ) may be passed.
- iWait - Number of seconds to wait
  The system waits the given number of seconds before executing the request.

to list

to top Comment