Administration API (isc_service_query) - Functional Specification

Description

Once a client has attached to the services mananger using isc_service_attach, the client uses this API call to retrieve information about the server, such as the installed licenses. This is accomplished by specifying the correct parameters in the receive buffer specified in the API call.

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_query
  (ISC_STATUS *status_vector,
   isc_svc_handle *svc_handle,
   ISC_USHORT send_spb_length,
   char *send_spb,
   ISC_USHORT recv_spb_length,
   char *recv_spb,
   ISC_USHORT buffer_length,
   char *buffer);

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

*svc_handle

pointer to a long value used to store the handle of the service structure on the server.This must point to a handle previously allocated in isc_service_attach.

*reserved

this parameter is being reserved for future use

send_spb_length

length in characters of the send buffer

*send_spb

pointer to a buffer containing flags instructing the service manager to process information

recv_spb_length

length in characters of the receive buffer

*recv_spb

pointer to a buffer containing flags instructing the service manager to return information

buffer_length

length in characters of the return buffer

*buffer

pointer to a buffer containing information received from the services manager

example (after isc_service_attach has been completed):

1. ISC_STATUS status [20];
2. char respbuf[SVC_RESPBUF],
3. recvbuf[] = { isc_info_svc_get_licensed_users, isc_info_svc_get_env_msg };
4. char *p = respbuf;
5. ISC_ULONG path_length;
6.
7. /* service attach happens here */
8. if (isc_service_query (status, &svc_handle, NULL, 0, NULL, sizeof (recvbuf),
9. recvbuf, SVC_RESPBUF, respbuf))
10. {
11. isc_print_status (status);
12. isc_service_detach (status, &svc_handle);
13. return;
14. }
15.
16. do {
17. switch (*p++)
18.  {
19.  case isc_info_svc_get_licensed_users:
20.   {
21.   ISC_ULONG nUsers;
22.   nUsers = (ISC_ULONG)isc_vax_integer(p, sizeof (ISC_ULONG));
23.   printf ("Number of licensed users: %dn", nUsers);
24.   p += sizeof(ISC_ULONG);
25.   break;
26.   }
27.
28.    case isc_info_svc_get_env_msg:
29.    {
30.    ISC_USHORT path_length;
31.    char *buffer;
32.    path_length = (ISC_USHORT) isc_vax_integer (p, sizeof(ISC_USHORT));
33.    p += sizeof (ISC_USHORT);
34.    buffer = (char*) malloc (path_length);
35.    strncpy (buffer, p, path_length);
36.    buffer [path_length] = '0';
37.    printf ("Path to INTERBASE.MSG: %sn", buffer);
38.    p += path_length;
39.    break;
40.    }
41.   }
42.  } while (*p);

As with all parameter buffers (i.e. dpb) that get sent to the server for processing information, service buffers can also be used to send multiple parameters to be processed. This can be seen in line 3 where the sendbuf is being initalized to hold parameters. Once the call to isc_service_query is made, the response buffer (respbuf) contains the information that was requested. Lines 15-42 show how to process the response buffer once the call to isc_service_query returns. Some important things to note about this API call are:

1. isc_service_query will not return unless either the request has completed or the response buffer is full. In the case of the buffer being full, it will return isc_info_truncated. You will need to increase the size of the buffer before calling into the services manager again with your request. If there is no data to return and you have started a service (using isc_service_start), this call will not return until the service has completed. This removes the need for polling to determine if a service has finished.
2. The format of the response buffer is: <isc_info_svc_xxx><length><data>. All lengths returned by this call will be 2 bytes long (line 32) and all numeric data returned will be 4 bytes long (line 21). This helps keep all formatting consistent so that there is no worry about what is actually being passed around. Parameters that specify numeric values (line 21) do not have a length associated with it.
3. isc_service_query can only process isc_info_svc requests. Any request that isc_service_query can not process will not produce an error and will not return any information. A complete list of isc_info_svc parameters follows.

Requirements and Constraints

General InterBase Requirements

isc_service_query only accepts isc_info_svc parameters

data lengths in the response buffer are always 2 bytes long (use ISC_USHORT)

numeric data returned in the response buffer is always 4 bytes long (use ISC_ULONG)

Migration Issues

There are no migration issues with this feature as the call was never documented or distributed for public use.