Overview of the Services API
Contents
This section describes general concepts of the Services API, usage of the services parameter buffer, and methods for attaching and detaching from a Services Manager.
General Information
The Services API is a group of functions in the InterBase client library (gds32.dll on Windows, libgds.a on UNIX/Linux). The features that you can exercise with the Services API include those of the command-line tools gbak, gfix, gsec, gstat, and iblicense. (See the Operations Guide for information on these tools.) The Services API can also perform other functions that are not provided by these tools.
All InterBase servers include a facility called the Services Manager. The Services API enables client applications to submit requests to the Services Manager of an InterBase server, and the Services Manager performs the tasks.
The server can be local (on the same host as your application), or remote (on another host on the network). The Services API offers the same features when connected to either local or remote InterBase servers. The Services API family consists of the following four functions:
For full details on the syntax and options of the Services API functions, see the reference entries for *isc_service_attach()
Using Services Parameter Buffers
You can specify options to tailor your attachment to a Services Manager by creating a services parameter buffer (SPB), populating it with desired properties, and passing the address of the SPB to isc_service_attach() or other functions in the Services API group. For example, the SPB can contain a user name and password for attaching to a remote server.
An SPB is a char array variable that you declare in your application. It contains the following elements:
- A byte that introduces the version of the SPB format, always the compile-time constant, isc_spb_version.
- A byte that specifies the version number. InterBase supplies a macro isc_spb_current_version, that is defined as the recommended SPB version for each given release of the InterBase product.
- A contiguous series of one or more clusters of bytes follow, each describing a single argument. Each cluster consists of the following parts:
- A byte that introduces the parameter type for each cluster. There are compiletime constants defined for all the parameter types (for example,isc_spb_user_name).
- A byte that specifies the number of bytes that follow in the remainder of the cluster argument; this is not needed for certain parameter types that have fixedlength arguments.
- A variable number of bytes that contain data, depending on the parameter type. Subsequent clusters follow immediately in the SPB array.
- For example, the following C/C++ code fills an SPB buffer with the SPB version and a cluster for the user name.
Example 12.1 Filling a services parameter buffer in C/C++
- char spb_buffer[128], *spb = spb_buffer;
- *spb++ = isc_spb_version;
- *spb++ = isc_spb_current_version;
- *spb++ = isc_spb_user_name;
- *spb++ = strlen("SYSDBA");
- strcpy(spb, "SYSDBA");
- spb += strlen("SYSDBA");
Line 1 declares an array of 128 bytes, and a pointer initialized to the first entry in the array.
Line 2 assigns the item specifier for the SPB version to the first element of the array. Every SPB must have this item at the start of the array. Since this SPB item is always one byte long, it doesn’t take a length specifier.
Line 3 assigns the value for the SPB version item.
Line 4 assigns the cluster identifier for the user name string to the next element of the array.
Line 5 provides the length of the following string. In this example, the string is “SYSDBA”, and the length is 6.
Line 6 copies the string “SYSDBA” into the array starting at the current element.
Line 7 increments the SPB pointer past the string “SYSDBA”, positioning it for additional clusters.
Important: All numbers in the database parameter buffer must be represented in a generic format, with the least significant byte first. Signed numbers should have the sign in the last byte. The API function isc_portable_integer() can be used to reverse the byte order of a number. For more information, see isc_portable_integer().
Attaching to the Services Manager with isc_service_attach( )
Use the Services API function isc_service_attach() to initiate a connection from your application to a remote InterBase Services Manager.
You must supply a local or remote service name to specify which host to attach. This string resembles InterBase database connection strings, in that the syntax determines the network protocol used to connect the client application to the Services Manager on the server host.
Table 12.1 Syntax of Services Manager Connect String, by Protocol
| Protocol | Syntax | Supported Server Platform |
|---|---|---|
| TCP/IP | serverhost:service_mgr | any |
| NetBEUI | \\serverhost\service_mgr | Windows server platforms |
| Local | service_mgr | any |
Replace serverhost with the hostname of your InterBase database server. In all cases, the string service_mgr is a literal string.
The user ID you use to attach to the Services Manager is the user ID the Services Manager uses to perform tasks by your request. Note that some service tasks can be performed only by the SYSDBA user ID.
Example 12.2 Attaching to a Services Manager in C/C++
- char *user = "SYSDBA",
- *password = "masterkey", /* see security tip below */
Example 12.3 *service_name = "jupiter:service_mgr";
- ISC_STATUS status[20];
- isc_svc_handle *service_handle = NULL;
- spb_buffer[128], *spb = spb_buffer;
- unsigned short spb_length;
- *spb++ = isc_spb_version;
- *spb++ = isc_spb_current_version;
- *spb++ = isc_spb_user_name;
- *spb++ = strlen(user);
- strcpy(spb, user);
- spb += strlen(user);
- *spb++ = isc_spb_password;
- *spb++ = strlen(password)
- strcpy(spb, password);
- spb += strlen(password);
- spb_length = spb - spb_buffer;
- if (isc_service_attach(status, 0, service_name, &service_handle,
- spb_length, spb_buffer)) {
- isc_print_status(status);
- exit(1);
- spb_length, spb_buffer)) {
- }
Detaching from a Services Manager with isc_service_detach( )
Use isc_service_detach( ) after you finish your tasks with the Services API, to end the connection with the Services Manager. Following is a C/C++ code example of terminating the connection, assuming you have acquired a valid service handle from isc_service_attach().
Example 12.4 Detaching from a Services Manager in C/C++
- isc_service_detach(status, &service_handle);