ibec_BackupDatabase

Syntax 

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

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.

Options

DatabaseToBackupFull 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).
BackupFilesList 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!
OptionsA 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.
ExpectedDB|See Example 3 below.
BackupToClientThis option creates the backup file on the client side instead of the server side.
SkipDataSee Example 4 below.
StatisticsOptions 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).
ROLETo 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.
NoDBTriggersThis prevents database/transaction triggers from firing during a backup/restore.
WireCompressionTo enable compression it is necessary to specify 'WireCompression=TRUE' (or just 'WireCompression') in the options string. (Both client and server must support WireCompression.)
CallbackBlockA 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 multiple backup files with full output: 

    execute ibeblock
    as
    begin
      cbb = 'execute ibeblock (LogStr variant)
             as
             begin
               ibec_Progress(LogStr);
             end';

      res = ibec_BackupDatabase('LOCALHOST:D:\FB2_DATA\TESTDB.FDB',
 'E:\TESTDB_1.FBK=200M; E:\TESTDB_2.FBK=200M; E:\TESTDB_3.FBK=200M',
 'ClientLib=C:\Program Files\Firebird\Bin\fbclient.dll;
 Password=masterkey; User=SYSDBA; IGNORE; L; LogFile=E:\Backup.log',
                                cbb);
      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:

ItemArgumentData Reported
Total timeTTime elapsed since the gbak process started, in seconds and milliseconds.
Time deltaDTime elapsed since the previous line of output, in seconds and milliseconds.
Page readsRNumber of page reads since the previous line of output, integer.
Page writesWNumber 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);

See also:
ibec_RestoreDatabase

back to top of page
<< Specifying WHERE clauses in ibec_ExtractMetadata | IBEBlock | ibec_RestoreDatabase >>