Backing Up and Restoring Databases Using isc_action_svc_backup

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 `gbak` ‑`no_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:

Dumping Databases