Administration API (isc_service_attach) - Functional Specification

Description

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)

returns:

value of ISC_STATUS[1]:

0 if no error
>0 if there is an error

*status_vector

pointer to a 20 element array of ISC_STATUS

service_length

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

Specify 0 if the service is a null terminated string.

*service

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

*svc_handle

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

Note

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

spb_length

length in bytes of the service parameter buffer

*spb

pointer to a buffer containing the service parameter

example:

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;
10.
11.  *spb++ = isc_spb_version;
12.  *spb++ = isc_spb_current_version;
13.
14.  *spb++ = isc_spb_user_name;
15.  *spb++ = strlen (user);
16.  for (x = user; *x;)
17.  *spb++ = *x++;
18.
19.  *spb++ = isc_spb_password;
20.  *spb++ = strlen (pass);
21.  for (x = pass; *x;)
22.  *spb++ = *x++;
23.
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 */
28.
29.  spblen = spb - spb_buff;
30.
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.

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.