Attaching to a Database

Go Up to Connecting to Databases

After creating and initializing a database handle, and optionally setting up a DPB to specify connection parameters, use isc_attach_database() to establish a connection to an existing database. Besides allocating system resources for the database connection, ­isc_attach_database() also associates a specific database with a database handle for use in subsequent API calls that require a handle.

isc_attach_database() expects six parameters:

• A pointer to an error status array, where attachment errors can be reported should they occur.
• The length, in bytes, of the database name for the database to open. If the database name includes a node name and path, these elements must be counted in the length argument.
• A string containing the name of the database to attach. The name can include a node name and path specification.
• A pointer to a previously declared and initialized database handle with which to associate the database to attach. All subsequent API calls use the handle to specify access to this database.
• The length, in bytes, of the DPB. If no DPB is passed, set this value to zero.
• A pointer to the DPB. If no DPB is passed, set this to NULL.

Each database attachment requires a separate call to isc_attach_database().

The following code establishes an attachment to the InterBase example database, employee.ib, and specifies a DPB to use for the attachment:

#include <ibase.h>
. . .
isc_db_handle db1;
char dpb_buffer[256], *dpb, *p;
short dpb_length;
char *str = "employee.ib";
ISC_STATUS status_vector[20];
. . .
/* Set database handle to zero before attaching to a database. */
db1 = 0L;
/* Initialize the DPB. */
dpb = dpb_buffer;
*dpb++ = isc_dpb_version1;
*dpb++ = isc_dpb_num_buffers;
*dpb++ = 1;
*dpb++ = 90;
dpb_length = dpb - dpb_buffer;
/* Attach to the database. */
isc_attach_database(status_vector, strlen(str), str, &db1,
dpb_length,  dbp_buffer);
if (status_vector[0] == 1 && status_vector[1]){
error_exit();
}
. . .

The following code illustrates how to attach to a database without passing a DPB:

#include <ibase.h>
. . .
isc_db_handle db1;
char *str = "employee.ib";
ISC_STATUS status_vector[20];
. . .
/* Set database handle to zero before attaching to a database. */
db1 = 0L;
/* Attach to the database. */
isc_attach_database(status_vector, strlen(str), str, &db1, 0, NULL);
if (status_vector[0] == 1 && status_vector[1]){
error_exit();
}
. . .