Building Applications
This section discusses compilers and libraries that are needed to build InterBase applications.
Help with linking and compiling: On each platform, there is a makefile in the examples directory that contains detailed platform-specific information about linking and compiling. Open the makefile in a text editor to access the information. The section includes the following topics:
- Compilers
- Linking
- Include Files
- Using Microsoft C++
- Using C/C++ Builder
- Setting up the Integrated Development Environment (IDE)
- The Module Definition File
- Using Dynamic Link Libraries
- Example Programs
Contents
Compilers
The import libraries included with InterBase have been tested with the following compilers:
Windows platforms
- C++ Builder 5.0
- Microsoft Visual C++ 2.0
- Microsoft Visual C++ 4.0
Solaris
- C SPARCWorks SC4.2 C compiler
- C++ SPARCWorks SC3.0.1 C++ compiler
- COBOLMicroFocus Cobol 4.0
- ADA SPARCWorks SC4.0 Ada compiler
- FORTRAN SPARCWorks SC4.0 Fortran compiler
Linux
- GCC G++
Linking
The InterBase library files reside in the lib subdirectory of the installation directory. Applications must link with the InterBase client library. This library name varies depending on the platform and the compiler.
Table 3.2 Interbase library file names
| Platform/Compiler | InterBase Library File | |
|---|---|---|
| Windows/C++ Builder | gds32/lib | |
| Windows/Microsoft Visual C++ 2.0 and 4.0 | gds32_ms.lib | |
| Solaris/all | gdsmt | |
| HPUX/all | gds |
Compilers earlier than 5.0 do not work with gds32.lib
Include Files
Applications must include the ibase.h header file to pick up the InterBase type definitions and function prototypes. This file is in the include subdirectory of the InterBase install directory.
On UNIX platforms, the gds.h file is available in the installation directory for backward compatibility.
Using Microsoft C++
Use the following options when compiling applicatins with Microsoft C++
Table 3.3 Microsoft C compiler options
| Option | Action | |
|---|---|---|
| c | Compile without linking (DLLs only) | |
| Zi | Generate complete debugging information | |
| DWN32 | Defines "WIN32" to be the null string | |
| D_MT | Use a multi-thread, statically-linked library |
For example, these commands use the Microsoft compiler to build a DLL that uses InterBase:
- cl -c -Zi -DWIN32 -D_MT -LD udf.c
- lib -out:udf.lib -def:funclib.def -machine:i586 -subsystem:console
- link -DLL -out:funclib.dll -DEBUG:full,mapped -DEBUGTYPE:CV
- -machine:i586 -entry:_DllMainCRTStartup@12 -subsystem:console
- -verbose udf.obj udf.exp gds32.lib ib_util_ms.lib crtdll.lib
This command builds an InterBase executable using the Microsoft compiler:
- cl -Zi -DWIN32 -D_MT -MD udftest.c udf.lib gds32.lib
- ib_util_ms.lib crtdll.lib
Note: See “Working with UDFs” in the Developer’s Guide for more about compiling and linking user-defined libraries. Using the Dynamic Runtime Library If you are
- using a Microsoft Visual C++ 2.0 or Microsoft Visual C++ 4.0
- compiling and linking separately, and
- using the Dynamic Runtime Library (msvcrt20.dll or msvcrt40.dll)
You need to use the /MD compiler flag to compile with the run time library (RTL), as well as linking with the correct import library.
Using C/C++ Builder
Use the following options when compiling applications with C++ Builder:
Table 3.4 C++ Builder compiler options
| Option | Action | |
|---|---|---|
| v | Turns on source debugging | |
| a4 | Structure padding/byte alignment | |
| DWIN32 |
| |
| tWM | Makes target multi-threaded | |
| tWC |
| |
| tWCD | Makes the target a console .DLL with all functions exportable; cannot be used with the -tWC option |
The following command creates a DLL named funclib.dll from a source file named udf.c:
- implib mygds32.lib \interbas\bin\gds32.dll
- bcc32 -v -a4 -DWIN32 -tWM -tWCD -efunclib.dll udf.c mygds32.lib
The following commands create an InterBase executable named udftest.exe (which calls into funclib.dll) from a source file named udftest.e containing embedded SQL commands.
- implib udf.lib funclib.dll
- gpre -e udftest.e
- bcc32 -v -a4 -DWIN32 -tWM -tWC udftest.c udf.lib mygds32.lib
When linking applications with the C command line linker, use the /c option (case sensitive link).
Note: There are equivalent general linker options within the Integrated Development Environment (IDE). The default in the IDE is case-sensitive link (/c option) alone, which causes unresolved linker errors for all of the InterBase entry points.
Setting up the Integrated Development Environment (IDE)
The Embarcadero Integrated Development Environment (IDE) offers options that are equivalent to the command line options.
IDE Default
The case-sensitive link (/c option) is the default in the IDE.
IDE Project Options Dialog Box
Choose the following options from the IDE Project Options dialog box. The corresponding command-line option is also listed.
- Directories
- Include directory: <InterBase_home>\SDK\include
- Library directory: <InterBase_home>\SDK\lib
Note: The default InterBase home directory is C:\Embarcadero\InterBase.
- Compiler
- Source language compliance: Embarcadero extensions
- 32-bit Compiler
- Data alignment: Byte (-a4 option for 4 byte alignment)
- Linker
- Choose Case-sensitive link ON (/c option).
The Module Definition File
Creating a module definition file can solve certain issues that arise during linking and compiling with the C++ Builder:
- Set the STACKSIZE parameter to at least 10 kilobytes (10,240 bytes); 16 kilobytes (16,384 bytes) is recommended. A sample .def file is included in the examples subdirectory of the InterBase installation directory.
- Because the C++Builder prepends an underscore to some API functions that gds32.dll exports without the underscore, you may need to add aliases for these functions to your module definition file, as in the following example:
- IMPORTS
- _isc_start_transaction = GDS32.isc_start_transaction
Using Dynamic Link Libraries (DLLs)
InterBase applications use the gds32.dll dynamic link library, which in turn loads the appropriate network DLLs. These DLLs unload automatically when the last calling application terminates. If the calling application exits abnormally (for example, from a protection fault), it is possible that DLLs will not be unloaded from memory. If this occurs, exit and restart Windows to free the resources.
Example Programs
Example programs demonstrating how to use the InterBase API are included in the examples subdirectory of the InterBase installation directory. There is also a sample .def file.
On NT, there are two make files, makefile.bc for the compiler and linker, and makefile.msc for the Microsoft compiler and linker. In both files, you must modify the IBASE environment variable to point to an absolute path. In the .bc make file, modify the BCDIR variable to point to the absolute path to the compiler and linker. In the .msc make file, modify the MSCDIR variable to point to the absolute path to the Microsoft compiler and linker. To build the example applications on NT using C++, use the following command:
- make -B -f makefile.bc all
To build the example applications using Microsoft C++, use this command:
- nmake -B -f makefile.msc all
On UNIX systems, the command to build the example applications is as follows:
- make all