2. Constructing a Simple ODBC Application

After you install the ODBC software (refer to the Microsoft ODBC Programmer's Reference) and DBMaker's ODBC driver, you can begin constructing a simple ODBC application using DBMaker. In this chapter, we will teach you how to compile and link an ODBC program with DBMaker's ODBC driver.

2.1 Choosing an ODBC Library Model

You create an ODBC application using the DBMaker function library or the ODBC function library. If your application program needs to make low-level system calls to the operating system, file system, or hardware-specific drivers, you may also need to use your own function libraries. Figure 2-1 and Figure 2-2 show the models for interfacing to these libraries.

Figure 2-1 is the model for using the ODBC Driver Manager, and Figure 2-2 is the model for using the DBMaker Driver directly without using the ODBC Driver Manager. When using the ODBC Driver Manager you may connect to data sources other than DBMaker. Without Driver Manager, your application links to the DBMaker function library directly and gains the benefit of better performance, but loses the ability to connect to other data sources.

Figure 2-1: ODBC library model when using the ODBC Driver Manager

Figure 2-2: ODBC library model when using the DBMaker driver directly

2.2 Header Files and Link Libraries to Include

To construct an ODBC program using the DBMaker ODBC driver, you need to specify the include header files and linking libraries in your makefile. In the following description, we use the C language as an example.

Header Files

When creating an ODBC application, the following header files are required: sql.h, sqlext.h, sqlopt.h and sqlunix.h (sqlunix.h is required for UNIX only).

sql.h and sqlext.h are the standard ODBC include files, and sqlopt.h and sqlunix.h are provided by DBMaker for some driver-specific options and for UNIX applications, respectively. Since sqlext.h also includes sql.h, you only need to include sqlext.h in your program.

The header files are same on all platforms, except sqlunix.h is used only for programs running on the UNIX platform.

On Microsoft Windows, these files can be found in the c:\dbmaker35\include\c directory after DBMaker is installed on drive C. This assumes that DBMaker was installed in the default installation directory. Otherwise, they can be found under d:\install_directory\include, where d: is the drive DBMaker was installed on, and install_directory is the directory it was installed to.

On UNIX environment, these files are under the ~dbmaker/3.5/include directory.

Link Libraries

Link libraries are also required when creating ODBC applications for use with DBMaker. The link libraries to use depend on the platform the application will be running on.

Windows 95/98/NT

For Windows ODBC applications, use the link library dmapi35.lib. On these Windows platforms, you can link the library:

With Driver Manager. Use the library odbc.lib in the ODBC SDK, often put in c:\odbcsdk\lib\odbc.lib. But you must register DBMaker in odbc.ini first so that the Driver Manager can load the DBMaker driver correctly. In this case, you don't have to specify dmapi35.lib in your makefile. The Driver Manager will load the necessary DLL automatically.

Without Driver Manager. Use the library dmapi35.lib provided by DBMaker. This library is normally found in c:\dbmaker35\lib.

If DBMaker is installed successfully, there is one dynamic link library in the c:\windows\system directory that is used with ODBC programs: dmapi35.dll. However, programmers only need to link the libraries odbc.lib (with Driver Manager) or dmapi35.lib (without Driver Manager). After these libraries are linked, the application will call this DLL automatically.

UNIX

On UNIX platforms, you must link the libdmapic.a file when creating a client/server ODBC application.

2.3 An Example of a Simple ODBC Application

Consider the following example program in the UNIX environment. The program illustrates how to connect to a data source and then use SQLGetInfo to get the DBMS version.

#include <stdio.h>
#include "sqlext.h"
#include "sqlopt.h"
#include "sqlunix.h"
#define  STR_LEN 30

HENV     henv;                            /* environment handle */
HDBC     hdbc;                            /* connection handle */
HSTMT    hstmt;                           /* statement handle */
SDWORD   retcode;                         /* return code */
UCHAR    info[STR_LEN];                   /* info string for SQLGetInfo */

retcode = SQLAllocEnv(&henv);
retcode = SQLAllocConnect(&hdbc);
retcode = SQLConnect(hdbc, "TEST", SQL_NTS, "SYSADM", SQL_NTS, "",
                     SQL_NTS);

if (rc != SQL_SUCCESS)
    goto EXIT;

rc = SQLGetInfo(hdbc,SQL_DBMS_VER, &info, STR_LEN,&cbInfoValue);

if (rc != SQL_SUCCESS)
    goto EXIT;

printf("Current DBMS version is %s\n", info);

EXIT:
    SQLDisconnect(hdbc);
    SQLFreeConnect(hdbc);
    SQLFreeEnv(henv);
    return;

2.4 Compiling and Linking the Sample Program

You can compile this example program (example.c) by typing the following command on the UNIX command line as shown below (this example assumes you use the compiler acc and $dir is the directory where you installed DBMaker):

sh> acc -c example.c -I$dir/dbmaker/include

Now you can link example.o with DBMaker's library libdmapis.a to produce an executable file called example:

sh> acc -o example example.o -L$dir/dbmaker/lib -ldmapis

2.5 Other DBMaker Sample Programs

Additional sample programs are provided with DBMaker in the samples directory. You can use the makefile in this directory to build these samples and execute them. First change to the dbmaker/samples directory, then type "make ex1" to build the executable ex1 for the sample program ex1.c.

On the Windows platform, there are several different C language development tools, such as Microsoft Visual C++, Borland C++ and Watcom C++. You may need to edit your own makefile to set the directories for include files and linking libraries in different ways for different development tools. For example, in Visual C++ you have to open a new project and edit the .mak and .def file.

DBMaker provides an example makefile for Visual C++ in the c:/dbmaker/samples/c directory.