Creating and Populating a DPB
Go Up to Connecting to Databases
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 DPB Parameters.
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.
Some of the DPB parameters correspond directly to
gfix options. In fact, that is 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;
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().