Creating Database Handles
Go Up to Connecting to Databases
Every database that an application accesses must be associated with its own database handle, a pointer to a FILE
structure that is used by all API database functions. The ibase.h
header file contains the following C typedef declaration for database handles:
typedef void ISC_FAR *isc_db_handle;
To use this typedef for declaring database handles in an application, include ibase.h
in each source file module:
#include <ibase.h>
Declaring Database Handles
To establish database handles for use, declare a variable of type isc_db_handle
for each database that will be accessed at the same time. The following code declares two handles:
#include <ibase.h>
. . .
isc_db_handle db1;
isc_db_handle db2;
Once a database is no longer attached, its handle can be assigned to a different database in a subsequent attachment. If an application accesses several databases, but only accesses a subset of databases at the same time, it is only necessary to declare as many handles as there will be simultaneous database accesses. For example, if an application accesses a total of three databases, but only attaches to two of them at a time, only two database handles need be declared.
Initializing Database Handles
Before a database handle can be used to attach to a database, it must be set to zero. The following code illustrates how two database handles are set to zero:
#include <ibase.h>
. . .
isc_db_handle db1;
isc_db_handle db2;
. . .
/* Set database handles to zero before attaching to a database. */
db1 = 0L;
db2 = 0L;
Once a database handle is initialized to zero, it can be used in a call to isc_attach_database
() to establish a database connection. If a nonzero database handle is passed to isc_attach_database()
, the connection fails and an error code is returned. For more information about establishing a database connection with isc_attach_database
(), see