ibec_RestoreDatabase

Description

The ibec_RestoreDatabase starts the restore process using the server Services Manager. It returns NULL if the restore process succeeded, otherwise it returns an error message.

ibec_RestoreDatabase also supports FIX_FSS_DATA and FIX_FSS_METADATA options which are equal to the corresponding gbak keys (see example 4 below).

Syntax

   function ibec_RestoreDatabase(BackupFiles : string; RestoreTo : string;
                                 Options : string; CallbackBlock : string) : variant;

Options

BackupFiles List of backup files delimited with semicolon.
RestoreTo List of database files delimited with semicolon. Each list item (in case of restore to multiple files) should be in format <db_file_name>=<file_size_in_pages>.
<db_file_name> 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).
<file_size_in_pages> Size of the database file in pages (!).
Options List of restore 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.
RestoreFromClient This specification used a local backup file while restoring a database.
PAGESIZE=<page_size> or PAGE_SIZE=<page_size> Page size of the restored database.
PAGEBUFFERS=<buffers> or BUFFERS=<buffers> or BU=<buffers> Overrides page buffers default.
ROLE To use an SQL role specify it in the option string: Role=SOMEROLE.
INACTIVE (or DEACTIVATEINDEXES, or I) Deactivate indexes during restore.
KILL (or NOSHADOWS, or K) Restore without creating shadows.
NO_VALIDITY (or NOVALIDITY, or N) Do not restore database validity conditions.
ONE_AT_A_TIME (or ONEATATIME, or O) Restore one table at a time (commit after each table).
REPLACE_DATABASE (or REPLACEDATABASE, or REP) Replace database from backup file.
CREATE_DATABASE (or CREATEDATABASE, or C) Create database from backup file.
USE_ALL_SPACE (or USEALLSPACE, or USE) Do not reserve space for record versions.
META_DATA (or METADATA, or M) Restore metadata only.
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 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 parameter.

Example 1

Restore database from single backup file with no output (silent mode):
  
  execute ibeblock
  as
  begin
    res = ibec_RestoreDatabase('E:\TESTDB.FBK',
                               'LOCALHOST:E:\TESTDB.FBK',
'ClientLib=C:\Program Files\Firebird\Bin\fbclient.dll;
Password=masterkey; User=SYSDBA;OneAtATime; PageSize=8192; C',
                               null);
    if (res is null) then
      ibec_ShowMessage('Restore completed successfully');
    else
      ibec_ShowMessage(res);
  end

Example 2

Restore database from multiple backup files to single database file with full output:

  execute ibeblock
  as
  begin
    cbb = 'execute ibeblock (LogStr variant)
           as
           begin
             ibec_Progress(LogStr);
           end';
 
res = ibec_RestoreDatabase('E:\TESTDB_1.FBK; E:\TESTDB_2.FBK; E:\TESTDB_3.FBK',
                               'LOCALHOST:E:\TESTDB.FBK',
'ClientLib=C:\Program Files\Firebird\Bin\fbclient.dll;
Password=masterkey; User=SYSDBA; C; REP; O; LogFile=E:\Restore.log',
                               cbb);
    if (res is null) then
      ibec_ShowMessage('Restore completed successfully');
    else
      ibec_ShowMessage(res);
  end

Example 3

  Restore database from multiple backup files to multiple database files with full output:

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

res = ibec_RestoreDatabase('E:\TESTDB_1.FBK; E:\TESTDB_2.FBK; E:\TESTDB_3.FBK',
                               'LOCALHOST:E:\TESTDB1.FBK=20000;
                                   LOCALHOST:E:\TESTDB2.FBK=20000;
                                   LOCALHOST:E:\TESTDB3.FBK',
'ClientLib=C:\Program Files\Firebird\Bin\fbclient.dll;
Password=masterkey; User=SYSDBA; C; REP; O; BU=3000;
                                   LogFile=E:\Restore.log',
                               cbb);
    if (res is null) then
      ibec_ShowMessage('Restore completed successfully');
    else
      ibec_ShowMessage(res);
  end

Example 4

res = ibec_RestoreDatabase('D:\NEWBLOCKDEMO.FBK', 

                          'localhost:D:\NEWBLOCKDEMO.FB2',
                          'ClientLib=C:\Program Files\Firebird\Bin\fbclient.dll;
                           password=masterkey; user=SYSDBA; OneAtATime; PageSize=8192;
                           fix_fss_data=WIN1251; fix_fss_metadata=WIN1251', null);