Creating and Populating a DPB
Database attachments can optionally be tailored in many ways by creating a database parameter buffer (DPB), populating it with desired characteristics, and passing the address of the DPB to isc_attach_database().
For example, the DPB can contain a user name and password for attaching to a database on a remote server, and it might also contain a parameter that activates a database shadow file. For a list of all possible DPB parameters, see Table 4.2 DPB Parameters Grouped by Purpose.
Usually a separate DPB is created for each database attachment, but if different attachments use the same set of parameters, they can share a DPB. If a DPB is not created or is not passed to isc_attach_database(), the database attachment uses a default set of parameters.
Tip: Some of the DPB parameters correspond directly to gfix options. In fact, that’s how gfix is implemented: it sets certain DPB parameters and attaches to a database. The database then performs the requested operation on itself (sweep, set async writes, shutdown, and so on).
A DPB is a char array variable declared in an application, that consists of the following parts:
- A byte specifying the version of the parameter buffer, always the compile-time constant, isc_dpb_version1.
- A contiguous series of one or more clusters of bytes, each describing a single parameter.
Each cluster consists of the following parts:
- A one-byte parameter type. There are compile-time constants defined for all the parameter types (for example, isc_dpb_num_buffers).
- A one-byte number specifying the number of bytes that follow in the remainder of the cluster.
- A variable number of bytes, whose interpretation (for example, as a number or as a string of characters) depends on the parameter type.
For example, the following code creates a DPB with a single parameter that sets the number of cache buffers to use when connecting to a database:
- char dpb_buffer[256], *dpb, *p;
- short dpb_length;
- /* Construct the database parameter buffer. */
- dpb = dpb_buffer;
- *dpb++ = isc_dpb_version1;
- *dpb++ = isc_dpb_num_buffers;
- *dpb++ = 1;
- *dpb++ = 90;
- dpb_length = dpb - dpb_buffer
span style="color:blue">Important: All numbers in the database parameter buffer must be represented in a generic format, with the least significant byte first, and the most significant byte last. 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().