Using Services Parameter Buffers
Go Up to Overview of the Services API
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 compile-time 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 fixed-length 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.
Filling A Services Parameter Buffer in C/C++
1 char spb_buffer[128], *spb = spb_buffer;
2 *spb++ = isc_spb_version;
3 *spb++ = isc_spb_current_version;
4 *spb++ = isc_spb_user_name;
5 *spb++ = strlen("SYSDBA");
6 strcpy(spb, "SYSDBA");
7 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 does not 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.
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().