Administration API (isc_service_attach) - Functional Specification


This API allows the client to connect to the InterBase Services Manager before attempting to use any of the defined InterBase services such as backup and restore.

User Interface/Usability

This feature will only be available to the end user via a call into the InterBase API.

ISC_STATUS ISC_EXPORT isc_service_attach (ISC_STATUS *status_vector,
                                          ISC_USHORT service_length,
                                          char *service,
                                          isc_svc_handle *svc_handle,
                                          ISC_USHORT spb_length,
                                          char *spb)

value of ISC_STATUS[1]:

0 if no error
>0 if there is an error
pointer to a 20 element array of ISC_STATUS

length in characters of the name of the service and host to connect to.

Specify 0 if the service is a null terminated string.

pointer to a character buffer containing the name of the host to connect to.

pointer to a long value used to store the handle of the service structure on the server.


This value MUST be 0L when attaching to a service.

length in bytes of the service parameter buffer
pointer to a buffer containing the service parameter


1.   char            *user = "SYSDBA",
2.                   *pass = "masterkey";
3.   char             *x;
4.   ISC_STATUS      status [20];
5.   isc_svc_handle  *svc_handle = NULL;
6.   char            svc_name[32],
7.                   spb_buff[128],
8.                   *spb = spb_buff;
9.   ISC_USHORT      spblen;
11.  *spb++ = isc_spb_version;
12.  *spb++ = isc_spb_current_version;
14.  *spb++ = isc_spb_user_name;
15.  *spb++ = strlen (user);
16.  for (x = user; *x;)
17.  *spb++ = *x++;
19.  *spb++ = isc_spb_password;
20.  *spb++ = strlen (pass);
21.  for (x = pass; *x;)
22.  *spb++ = *x++;
24.  sprintf (svc_name, "hostname:service_mgr");     /* TCP/IP */
25.  sprintf (svc_name, "//hostname/service_mgr");   /* Named Pipes */
26.  sprintf (svc_name, "@hostname:service_mgr");    /* SPX */
27.  sprintf (svc_name, "service_mgr");              /* Local */
29.  spblen = spb - spb_buff;
31.  if (isc_service_attach (status, 0, svc_name, &svc_handle, spblen, spb_buff))
32.      {
33.      isc_print_status (status);
34.      exit (1);
35.      }

Lines 24-27 show the four different connection strings that can be used to attach to the services manager. When using this API call, you must specify one of these connection strings.

As shown above (lines 11 and 12), this call uses 2 bytes to specify the spb version being used by the services manager. This new method is defined as follows:

isc_spb_version (line 11)
This parameter is used to differentiate verion 1 calls from other versions. The next byte that follows will be the actual version of the spb.
isc_spb_current_version (line 12)
This parameter contians the value of the current version of the spb. Doing this allows the versions to be updated without adding additional version definitions to the header files.
user parameters accepted in the spb for isc_service_attach
Parameter Length Data Meaning
isc_spb_current_version 1 isc_spb_version 2 bytes which specify the version of the spb. These must always be the first two bytes in the spb.
isc_spb_user_name length of username the username the username to connect to the service manager with. This username will be used for all services that require a username to be specified.
isc_spb_password length of password the password the password to connect to the service manager with. This password will be used for all services that require a password to be specified.

Requirements and Constraints

This feature will be available on all platforms and all architectures. There are no additional requirements that need to be taken in consideration when using this feature.

Migration Issues

Older clients will no longer be able to connect to the InterBase V6.0 services manager because of changes that need to be made to header file defines. This affects only ibmgr32 as these entrypoints were never documented or defined for public use.