Requirements for all Applications
The following sections outline these requirements for all API applications:
Contents
Including ibase.h
The InterBase subdirectory, include, contains the ibase.h header file, which should be included in all source code modules for API applications. ibase.h contains API function prototypes. It also contains structure typedefs, parameter definitions, and macros required by various API functions.
To include ibase.h in a source code module, insert the following #include near the start of the source code:
#include <ibase.h>
If ibase.h is not on your compiler’s search path, you may need to provide a full path specification and enclose the file name in quotation marks.
Important: Failure to include ibase.h prevents the successful compilation and linking of an application.
DataBase Requirements
All applications that work with databases must provide one database handle for each database to be accessed. A database handle is a long pointer that is used in API functions to attach to a database and to reference it in subsequent API calls. The InterBase header file, ibase.h, contains a #define useful for declaring database handles.
When establishing a connection to a database, optional database attachment characteristics, such as a user name and password combination, can be passed to the attachment through a database parameter buffer (DPB). Usually, one DPB is set up for each database attachment, although database attachments can also share a DPB.
Declaring Database Handles
The following code illustrates how to declare and initialize a database handle:
#include <ibase.h>
. . .
/* Declare a database handle. */
isc_db_handle db1;
. . .
/* Initialize the handle. */
db1 = 0L;
For more information about declaring, initializing, and using database handles, see Chapter 4: Working with Databases.
Setting up a DBP
A DPB is a byte array describing optional database attachment characteristics. A DPB must be set up and populated before attaching to a database. Parameters that can be passed to the DPB are defined in ibase.h.
For more information about setting up, populating, and using a DPB, see Chapter 4: Working with Databases.
Transaction Requirements
All applications must provide one transaction handle for each transaction to be accessed. A transaction handle is a long pointer that is used in API functions to start a transaction and to reference it in subsequent API calls. The InterBase header file, ibase.h, contains a #define useful for declaring transaction handles. When starting a transaction, optional transaction characteristics, such as access method and isolation level, can be passed to the start-up call through a transaction parameter buffer (TPB). Usually, one TPB is set up for each transaction, although transactions with the same operating characteristics can also share a TPB.
Declaring Transaction Handles
A transaction handle must be declared and initialized to zero before use. The following code illustrates how to declare and initialize a transaction handle:
#include <ibase.h>
. . .
/* Declare a transaction handle. */
isc_tr_handle tr1;
. . .
/* Initialize the handle. */
tr1 = 0L;
For more information about declaring, initializing, and using transaction handles, see see Chapter 5: Working with Transactions.
Setting up a TPB
A TPB is a byte array containing parameters that describe optional transaction characteristics. In these cases, the TPB must be set up and populated before starting a transaction. Parameters that can be passed to the TPB are defined in ibase.h.
For more information about setting up, populating, and using a TPB, see Chapter 5: Working with Transactions