Additional Requirements
The following sections outline possible additional requirements for API applications developed on certain system platforms, such as Microsoft Windows, and for general classes of API functions, such as those that process DSQL statements. This section covers:
- Microsoft Windows Requirements
- DSQL Requirements
- Blob Requirements
- Array Requirements
- Event Requirements
- Error-handling Requirements
- Services Requirements
Contents
Microsoft Windows Requirements
InterBase client applications for Microsoft Windows have programming requirements specific to that environment and the C/C++ compilers available there.
The InterBase header file, ibase.h, provides prototypes of all API functions. For Windows applications, these prototypes make use of the following declarations:
#define ISC_FAR __far
#define ISC_EXPORT ISC_FAR __cdecl __loadds __export
For example, the isc_attach_database() prototype in ibase.h is:
ISC_STATUS ISC_EXPORT isc_attach_database(ISC_STATUS ISC_FAR *,
short,
char ISC_FAR, isc_db_handle ISC FAR *, short, char ISC_FAR *);
When Windows client applications make calls and cast C datatypes, they should make explicit use of the ISC_FAR declaration.
Note: The ISC_EXPORT keyword is omitted from the API function reference because on all non-Windows platforms it is undefined.
For more information about Windows requirements, see Chapter 3: Programming with the InterBase API
DSQL Requirements
API applications that build or prompt for DSQL queries at run time require careful declaration, initialization, and population of extended SQL descriptor area (XSQLDA) structures for data transfer to and from the database. In addition, many API functions, such as isc_dsql_allocate_statement() and isc_dsql_describe(), also make use of statement handles for DSQL processing.
ibase.h</> provides typedefs for the XSQLDA structure, and its underlying structure, the XSQLVAR. It also provides a #define for the statement handle, a macro for allocating the appropriate amount of space for an instance of an XSQLDA in an application, and #defines for DSQL information parameters passed to
isc_dsql_sql_info().
The following code illustrates how to declare an XSQLDA structure for use in an
application, and how to declare a statement handle:
#include <ibase.h>
. . .
XSQLDA *insqlda;
isc_stmt_handle sql_stmt;
. . .
For more information about DSQL programming with the API, see Chapter 6: Working with Dynamic SQL.
Blob Requirements
To work with Blob data that must be filtered, an API application must set up a Blob parameter buffer (BPB) for each Blob. A BPB is a variable-length byte vector declared in an application to store control information that dictates Blob access. The BPB can contain a number of constants, defined in ibase.h, that describe the Blob and the Blob subtypes that specify Blob filtering.
Applications that work with Blob data in an international environment must also declare and populate a Blob descriptor that contains character set information for the Blob. The Blob descriptor structure is defined in ibase.h. To declare a Blob descriptor, an application must provide code like this:
#include <ibase.h>- . . .
ISC_BLOB_DESC_V2 descriptor_name;
Blob filters enable a Blob to be translated from one format to another, such as from a compressed state to an decompressed state or vice versa. If Blob filters are desired, separate filter functions must be created and defined to the database to ensure their use when Blob data is accessed.
Finally, to access Blob data, applications must make extensive use of API DSQL functions.
For more information about working with Blob data and Blob filters, see "Working with Blob Data". For more information about DSQL, see "Working with Dynamic SQL"