ibec_BackupDatabase

Description

The ibec_BackupDatabase starts the backup process using the server Services Manager. It returns NULL if the backup process is successful, otherwise it returns an error message.

Syntax

   function ibec_BackupDatabase(DatabaseToBackup : string; 
                                BackupFiles :string; Options : string; 
                                CallbackBlock : string) : variant;

Options

DatabaseToBackup Full connection string to the database including server name or IP address if the database is located on a remote server (for example, 123.123.123.123:D:\DATA\MyDB.fdb).
BackupFiles List of backup files delimited with semicolon. Each list item should be formatted as <file_name>=<file_size>.
<file_size> Specifies the length of the result backup file in bytes (no suffix), kilobytes (K), megabytes (M) or gigabytes (G). IMPORTANT: All backup files will be created on the server side because of the use of the Services Manager!
Options A list of backup options delimited with semicolon. Possible options are:
USER=<user_name> User name
PASSWORD=<password> or PAS=<password> Password.
CLIENTLIB=<client_lib_name> Name of clientlib dll; gds32.dll will be used if not specified.
ExpectedDBSee Example 3 below. ExpectedDBSee Example 3 below.
BackupToClient This option creates the backup file on the client side instead of the server side.
SkipData See Example 4 below.
Statistics Options are: this is equal to the -STATISTICS gbak switch and should contain any combination of T, D, R, W chars as described in the Firebird documentation (https://firebirdsql.org/file/documentation/release_notes/html/en/3_0/bk02ch11s03.html). (see Example 4 below).
ROLE To use an SQL role specify it in the option string: Role=SOMEROLE.
IGNORE (or IG) Ignore bad checksums.
LIMBO (or L) Ignore transactions in limbo.
METADATA (or META_DATA, or M) Backup metadata only.
GARBAGECOLLECT (or GARBAGE_COLLECT, or G) Inhibit garbage collection.
OLDDESCRIPTIONS (or OLD_DESCRIPTIONS, or OL) Save old style metadata descriptions.
NONTRANSPORTABLE (or NON_TRANSPORTABLE, or NT) Non-transportable backup file format.
CONVERT (or CO) Backup external files as tables.
LOGFILE=<log_file_name> Name of output log file.
NoDBTriggers This prevents database/transaction triggers from firing during a backup/restore.
WireCompression To enable compression it is necessary to specify 'WireCompression=TRUE' (or just 'WireCompression') in the options string. (Both client and server must support WireCompression.)
CallbackBlock A callback IBEBlock which will be executed for each output line. The callback IBEBlock must have at least one input parameter, which will be used to pass an output line within it. If there is no callback block use NULL or an empty string as a value of this.

Example 1

Backup a database to a single backup file with no output (silent mode): 

  execute ibeblock
  as
  begin
    res = ibec_BackupDatabase('LOCALHOST:D:\FB2_DATA\TESTDB.FDB',
                              'E:\TESTDB.FBK',

'ClientLib=C:\Program Files\Firebird\Bin\fbclient.dll; 

                                 Password=masterkey; User=SYSDBA; G;',
                              null);
    if (res is null) then
      ibec_ShowMessage('Backup completed successfully');
    else
      ibec_ShowMessage(res);
  end

Example 2

Backup a database to a single backup file with no output (silent mode): 

  execute ibeblock
  as
  begin
    res = ibec_BackupDatabase('LOCALHOST:D:\FB2_DATA\TESTDB.FDB',
                              'E:\TESTDB.FBK',

'ClientLib=C:\Program Files\Firebird\Bin\fbclient.dll; 

                                 Password=masterkey; User=SYSDBA; G;',
                              null);
    if (res is null) then
      ibec_ShowMessage('Backup completed successfully');
    else
      ibec_ShowMessage(res);
  end

Example 3

   Res = ibec_BackupDatabase('localhost:D:\FB3_DATA\SELFSECURITYDB.FB3',
                             'D:\BACKUPS\SELFSECURITYDB.FBK',
                             'ClientLib=C:\Program Files\Firebird\fbclient.dll;
                              Password=masterkey; User=SYSDBA; 
                              ExpectedDB=D:\FB3_DATA\SELFSECURITYDB.FB3',
                             null);

Example 4

Arguments for STATISTICS output:

Item Argument Data Reported
Total time T Time elapsed since the gbak process started, in seconds and milliseconds.
Time delta D Time elapsed since the previous line of output, in seconds and milliseconds.
Page reads R Number of page reads since the previous line of output, integer.
Page writes W Number of page writes since the previous line of output, integer. 
   Res = ibec_BackupDatabase('localhost:D:\FB3_DATA\SELFSECURITYDB.FB3',
                             'D:\BACKUPS\SELFSECURITYDB.FBK',
                             'ClientLib=C:\Program Files\Firebird\fbclient.dll;
                              Password=masterkey; User=SYSDBA; 
                              SkipData=(sales|customer); Statistics=TDRW',
                             null);