Backing Up and Restoring Databases Using isc_action_svc_backup

From InterBase
Jump to: navigation, search

Go Up to Invoking Service Tasks with isc_service_start( )


Use the cluster identifier isc_action_svc_backup to request that the Services Manager perform a backup operation. This is a programmatic method to invoke the gbak tool as a thread in the ibserver process. You must specify the path of the database primary file, and the path of the backup output file or files.

Note: Paths of backup files are relative to the server. Because the Services Manager executes backup and restore tasks on the server host, the Services Manager reads and writes backup files on the server host. The Services Manager also creates files in the context of the server. If, on a UNIX system, you run your server as root, restoring a backup may fail because of the protection put on the backup file when the server created it.

You can specify additional options as needed. Some options require arguments, while other options are bits in an option bitmask.

The following table lists arguments to isc_action_svc_backup:

Services API Database Backup Arguments
Argument Purpose Argument length Argument value

isc_spb_dbname

Path of the primary file of the database, from the server’s point of view

2 bytes + string

String

isc_spb_verbose

If specified, the Services Manager prepares output to return via isc_service_query(); corresponds to gbak -verbose

isc_spb_bkp_file

Path of a backup output file; you can specify multiple output files; corresponds to gsplit functionality

2 bytes + string

String

isc_spb_bkp_length

Length in bytes of the backup output file; you must specify one length value for each output file except the last; corresponds to gsplit functionality

2 bytes + string

String

isc_spb_bkp_factor

Tape device blocking factor; corresponds to gbak -factor

4 bytes

Unsigned long

isc_spb_options

The following value is a bitmask of isc_spb_bkp_xxxx options below

4 bytes

Bitmask

isc_spb_bkp_ignore_checksums

Ignore checksums during backup; corresponds to gbak -ignore

Bit

isc_spb_bkp_ignore_limbo

Ignore limbo transactions during backup; corresponds to gbak -limbo

Bit

isc_spb_bkp_metadata_only

Output backup file for metadata only with empty tables; corresponds to gbak -metadata

Bit

isc_spb_bkp_no_garbage_collect

Suppress normal garbage collection during backup; improves performance on some databases; corresponds to gbak -garbage_collect

Bit

isc_spb_bkp_old_descriptions

Output metadata in pre-4.0 format; corresponds to gbak -old_descriptions

Bit

isc_spb_bkp_non_transportable

Output backup file format with non-XDR data format; improves space and performance by a negligible amount; corresponds to gbak -nt

Bit

isc_spb_bkp_convert

Convert external table data to internal tables; corresponds to gbak -convert

Bit

isc_spb_bkp_preallocate

Database pages to be preallocated; corresponds to gbak -preallocate. Set to 0 to disable preallocation

4 byptes

Unsigned long

Starting a database backup service in C/C++

char request[100], *x, *p = request;
/* Identify cluster */
*p++ = isc_action_svc_backup;

/* Argument for database filename */
*p++ = isc_spb_dbname;
ADD_SPB_LENGTH(p, strlen(argv[1]));
for (x = argv[1]; *x; ) *p++ = *x++;

/* Argument for backup output filename */
*p++ = isc_spb_bkp_file;
ADD_SPB_LENGTH(p, strlen(argv[2]));
for (x = argv[2]; *x; ) *p++ = *x++;

/* Argument to request verbose output */
*p++ = isc_spb_verbose;

if (isc_service_start(status, &service_handle, NULL, p - request, request)) {
isc_print_status(status);
isc_service_detach(status, service_handle);
exit(1);
}

You can also restore a database backup file to create a new database file. The following table lists arguments to the cluster identifier isc_action_svc_restore:

Services API Database Restore Arguments
Argument Purpose Argument length Argument value

isc_spb_bkp_file

The path of the backup file name

2 bytes + string

String

isc_spb_dbname

Path of the primary file of the database, from the server’s point of view; you can specify multiple database files

2 bytes + string

String

isc_spb_res_length

The length in pages of the restored database file; must not exceed 2 gigabytes; you must supply a length for each database file except the last

4 bytes

Unsigned long;
pages in database file

isc_spb_verbose

If specified, the Services Manager prepares output to return via isc_service_query(); corresponds to gbak -verbose

isc_spb_res_buffers

The number of default cache buffers to configure for attachments to the restored database; corresponds to gbak -buffers

4 bytes

Unsigned long; number of buffers

isc_spb_res_page_size

The page size for the restored database; corresponds to gbak -page_size

isc_spb_res_access_mode

Set the access mode of the database; the next byte must be one of:

  • isc_spb_prp_am_readonly
  • isc_spb_prp_am_readwrite

Corresponds to gbak -mode

1 byte

Byte

isc_spb_res_eua_user_name

User name to authenticate with EUA user accounts in backup file

2 bytes + string

String

isc_spb_res_eua_password

Password to authenticate with EUA user accounts in backup file

2 bytes + string

String

isc_spb_options

The following value is a bitmask of isc_spb_res_xxxx options below

4 bytes

Bitmask

isc_spb_res_deactivate_idx

Do not build user indexes during restore; corresponds to gbak -inactive

Bit

isc_spb_res_no_shadow

Do not recreate shadow files during restore; corresponds to gbak -kill

Bit

isc_spb_res_no_validity

Do not enforce validity conditions (for example, NOT NULL) during restore; corresponds to gbakno_validity

Bit

isc_spb_res_one_at_a_time

Commit after completing restore of each table; corresponds to gbak -one_at_a_time

Bit

isc_spb_res_replace

Replace database, if one exists; corresponds to gbak -replace. For a restore you must supply either isc_spb_res_replace or isc_spb_res_create

Bit

isc_spb_res_create

Restore but do not overwrite an existing database; corresponds to gbak -create. For a restore you must supply either isc_spb_res_replace or isc_spb_res_create

Bit

isc_spb_res_validate

Enables validation during a database restore.

isc_spb_res_use_all_space

Do not reserve 20 percent of each data page for future record versions; useful for read-only databases; corresponds to gbak -use_all_space

Bit

isc_spb_res_write_mode

Set the write mode of the database; the next byte must be one of:

- isc_spb_res_wm_async
- isc_spb_res_wm_sync
- isc_spb_res_wm_direct

Corresponds to gbak -write

1 byte

Byte

isc_spb_res_preallocate

Database pages to be preallocated; corresponds to gbak -preallocate. Set to 0 to disable preallocation

4 bytes

Unsigned long

isc_spb_res_ods_version_major

Restore database with specified major ODS version as the target version

4-byte ISC_ULONG integer

Unsigned long;
major ODS version of restored database

Starting a Database Restore Service in C/C++

char request[100], *x, *p = request;
unsigned long options;

/* Identify cluster */
*p++ = isc_action_svc_restore;

/* Arguments for backup filenames */
for (i = 1; argc > 1; --argc; ++i) {
*p++ = isc_spb_bkp_file;
ADD_SPB_LENGTH(p, strlen(argv[i]));
for (x = argv[i]; *x; ) *p++ = *x++;
}

/* Argument for database filename */
*p++ = isc_spb_db_name;
ADD_SPB_LENGTH(p, strlen(argv[i]));
for (x = argv[i]; *x; ) *p++ = *x++;

/* Argument to request verbose output */
*p++ = isc_spb_verbose;

/* Argument to specify restore options */
*p++ = isc_spb_options;
options = isc_spb_res_ create;
ADD_SPB_NUMERIC(p, options);

if (isc_service_start(status, &service_handle, NULL, p - request, request)) {
isc_print_status(status);
isc_service_detach(status, service_handle);
exit(1);
}

Advance To: