Using Result Buffers

From InterBase
Jump to: navigation, search

Go Up to Querying the Services Manager

The Services API uses a buffer structured similarly to the SPB for isc_service_query() 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 supplies the data you requested by specifying these arguments.

isc_service_query() uses another structured buffer to return requested data. This is called the result buffer. The Services Manager stores data in this buffer. You write code in your application to scan the buffer after isc_service_query() returns, and interpret the data based on the single-byte cluster identifiers at the start of each cluster.

The cluster identifiers are used both for requesting data in the request buffer, and for identifying clusters of returned data in the result buffer. When you add these identifiers to the request buffer, you specify only the identifier name in the request buffer, not the identifiers for any arguments. The Services Manager returns argument identifiers and data in the result buffer.

When you interpret the identifiers in the result buffer, clusters include associated data. The data that follow the cluster identifier are specific to the cluster type. Some clusters have a fixed length value following the identifier, for example numeric values are always returned as 4-byte long integers. Other clusters identifiers are followed by a 2-byte short integer, which specifies the length of the subsequent string. Still other cluster identifiers are followed by a series of argument identifiers with fixed or variable length data.

If the data that the Server Manager returns exceed the size of the result buffer you supply, isc_service_query() fills the buffer as much as possible, and includes isc_info_truncated as the last cluster identifier. This indicates that the result buffer was too small to contain all the resulting output of the service query. To receive the entire buffer, you must call isc_service_query() again with a larger buffer. The Services Manager starts over from the beginning of the output; you must provide a buffer that is large enough to hold the entire output.

Services API queries: handling a truncated result

. . .
case isc_info_truncated:
printf ("Buffer Truncated\n");
/* you should increase the buffer size and retry the query */
. . .

For output that is typically very lengthy, such as the output of a database backup task, the Services Manager needs to return a volume of text data. You can use the request item isc_info_svc_line to request successive lines of the text result, or you can use isc_info_svc_to_eof to request the entire text output in one query. See Querying Service Tasks.

Advance To: