Invoking Service Tasks with isc service start()

You can use the function isc_service_start() to request that the Services Manager perform specified tasks. These tasks execute on the server host as a thread in the ibserver process. This section describes the types of tasks you can request.

You can execute only one task at a time in a given attachment to a Services Manager. While the task is running, you can retrieve any output of the task using isc_service_query(). You can maintain multiple attachments to a Services Manager and execute a task in each attachment.

Using Request Buffers

The Services API uses a buffer structured similarly to the SPB for isc_service_start() to specify tasks and options for the Services Manager. This is called the request buffer. You supply clusters of parameters and arguments in the request buffer. The Services Manager performs tasks you specify.

Overview of Task Identifiers

The following table lists by request buffer cluster identifier the tasks that you can request with isc_service_start().

Table 12.2 Services API Tasks

Task Item	Purpose
isc_action_svc_backup	Back up a database to a file or tape device; equivalent to gbak -b
isc_action_svc_restore	Restore a database backup file and recreate a database; equivalent to gbak -c
isc_action_svc_dump	Dump a database to a file; equivalent to gbak -d
isc_action_svc_properties	Set database properties; equivalent to gfix with various options
isc_action_svc_repair	Initiate database consistency check and correction; equivalent to gfix with -validate, -full, and -mend options
isc_action_svc_db_stats	Report database statistics; equivalent to the output of gstat
isc_action_svc_get_ib_log	Report contents of the InterBase.log file on the server
isc_action_svc_display_user	Display a user entry to the security database on the server; equivalent to gsec -display
isc_action_svc_add_user	Add a user entry to the security database on the server; equivalent to gsec -add
isc_action_svc_delete_user	Delete a user entry to the security database on the server; equivalent to gsec -delete
isc_action_svc_modify_user	Modify a user entry to the security database on the server; equivalent to gsec -modify
isc_action_svc_add_license	Add a software activation certificate to ib_license.dat;only SYSDBA can invoke this task
isc_action_svc_remove_license	Remove a software activation certificate from ib_license.dat; only SYSDBA can invoke this task
isc_action_svc_add_db_alias	Add an alias for the database to the server; only SYSDBA can invoke this task
isc_action_svc_delete_db_alias	Delete the database alias from the server; only SYSDBA can invoke this task.
isc_action_svc_display_db_alias	Display the database alias; only SYSDBA can invoke this task

Sample Code for isc_action_svc_delete_db_alias

/*

* db_alias_del: delete database alias from the server

*

* Copyright 1986-2010 Embarcadero Technologies, Inc.

* All rights reserved.

*/

#include <stdio.h>

#include <string.h>

#include <stdlib.h>

#include <ibase.h>

#include "example.h"

#define RESPBUF2048

void main (argc, argv)

int argc;

char*argv[];

{

char *user = "sysdba", *pass = "masterkey";

charalias_name[64];

ISC_STATUSstatus [20];

isc_svc_handle *svc_handle = NULL;

charsvc_name[RESPBUF], spb_buff[RESPBUF], thd_buff[RESPBUF];

charrespbuf[RESPBUF], *p = respbuf, *spb = spb_buff, *thd = thd_buff,*x;

shortspblen, thdlen;

int i = 0, cnt=0;

short finished = ISC_FALSE;

if (argc > 1)

sprintf (alias_name, "%s", argv[1]);

else

strcpy (alias_name, "empdb");

*spb++ = isc_spb_version;

*spb++ = isc_spb_current_version;

*spb++ = isc_spb_user_name;

*spb++ = strlen (user);

for (x = user; *x;)

*spb++ = *x++;

*spb++ = isc_spb_password;

*spb++ = strlen (pass);

for (x = pass; *x;)

*spb++ = *x++;

sprintf (svc_name, "service_mgr");

spblen = spb - spb_buff;

if (isc_service_attach (status, 0, svc_name, &svc_handle, spblen, spb_buff))

{

isc_print_status (status);

exit (1);

}

*thd++ = isc_action_svc_delete_db_alias;

*thd++ = isc_spb_sec_db_alias_name;

ADD_SPB_LENGTH (thd, strlen(alias_name));

for (x = alias_name; *x;)

*thd++ = *x++;

thdlen = thd - thd_buff;

printf ("Attach succeed\n");

if (isc_service_start(status, &svc_handle, NULL, thdlen, thd_buff))

{

ISC_STATUS *vector = status;

printf ("Unable to start service:\n");

while (isc_interprete (respbuf, &vector))

printf ("ERROR: %s\n", respbuf);

printf ("End of errors\n");

isc_service_detach (status, &svc_handle);

exit(1);

}

printf ("Start succeed\n");

do

{

char sendbuf[] = {isc_info_svc_line};

ISC_STATUS loc_status[20], *stat = loc_status;

if (isc_service_query (status, &svc_handle, NULL, 0, NULL, sizeof (sendbuf), sendbuf,

RESPBUF, respbuf))

{

isc_print_status (status);

isc_service_detach (status, &svc_handle);

exit(1);

}

x = p = respbuf;

if (*p++ == isc_info_svc_line)

ISC_USHORT len = 0, chTmp = 0;

len = (ISC_USHORT)isc_vax_integer(p, sizeof(ISC_USHORT));

p += sizeof (ISC_USHORT);

if (!len)

if (*p == isc_info_data_not_ready)

{

printf ("no data available at this moment\n");

continue;

}

else

{

if (*p != isc_info_end)

printf ("Format error ... <%d>\n", *p);

break;

}

for (chTmp = 0; chTmp < len; chTmp++)

printf("%c",p[chTmp]);

p += len;

if (*p != isc_info_truncated && *p != isc_info_end)

{

printf ("Format error ... encountered <%d>\n", *p);

break;

}

else

{

// printf ("\nisc_info_truncated || isc_info_end\n");

}

}

else

printf ("not a isc_info_svc_line, but %d\n", *x);

}

while (*x == isc_info_svc_line);

isc_service_detach (status, &svc_handle);

}

See the following sections for descriptions of tasks and examples of starting them.

Generic Services API Parameters

The following parameters enable IBX support for InterBase XE.

Table 12.3 Generic Services API Parameters

Argument	Purpose	Argument Length	Argument Value
isc_spb_user_name	User name to authenticate with user accounts in administration database.	2 bytes + string	String
isc_spb_sys_user_name	Internal only: automatically built and used as system user name if database username is not provided.	2 bytes + string	String
isc_spb_sys_user_name_enc	Reserved for future use.
isc_spb_password	Password to authenticate with user accounts in administration database.	2 bytes length + string
isc_spb_password_enc	Encrypted password string; similar to isc_dpb_password_enc.	2 bytes length + string	String
isc_spb_command_line	For internal use only.
isc_spb_connect_timeout	Optional: Connection timeout in seconds specified by the client.	4 bytes	Unsigned 32-bit integer
isc_spb_dummy_packet_interval	Optional: Keep alive dummy packet interval in seconds.	4 bytes	Unsigned 32-bit integer
isc_spb_sql_role_name	Login SQL Role name.	2 bytes length + string	String
isc_spb_instance_name	Instance name (multi-instance related) of server you are trying to connect with. This is a client side setting.	2 bytes length + string	String
isc_spb_user_dbname	Name of user database file where user accounts are administered.	2 bytes length + string	String
isc_spb_auth_dbname	For internal use only.

Backing Up and Restoring Databases

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:

Table 12.4 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	Output backup file for metadata only with empty tables; corresponds to gbak -metadata		Bit
isc_spb_bkp_metadata_only	Ignore limbo transactions during backup; corresponds to gbak -limbo		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 bytes	Unsigned long

=Example 12.5 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:

Table 12.5 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; pages in database file
isc_spb_res_page_size	The page size for the restored database; corresponds to gbak -page_size
sc_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
sc_spb_res_preallocate	Database pages to be preallocated; corresponds to gbak -preallocate. Set to 0 to disable preallocation	4 bytes	Unsigned long

Example 12.6 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);

}

Dumping Databases

Use the cluster identifier isc_action_svc_dump to request that the ServicesManager perform a dump 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 dump output file or files.

Note: Paths of dump files are relative to the server. Because the Services Manager executes dump tasks on the server host, the Services Manager reads and writes dump files on the server host. The Services Manager also creates files in the context of the server.

Table 12.6 Services API Database Dump 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_dmp_file	Path of a dump output file; you can specify multiple output files.	2 bytes + string	String
isc_spb_dmp_length	Length in bytes of the dump output file; you must specify one length value for each output file except the last	2 bytes + string	String
isc_spb_dmp_overwrite	Overwrite existing dump file; absence connotes incremental update of existing dump file	1 byte	Bit