11.3. Linking iODBC and ODBC Applications on Mac OS
11.3.1. Mac OS Classic
The package provided for this platform is a compressed Macintosh format (.sit.hqx). After uncompressing it on your hard drive, you will find below the tree of the iODBC SDK as installed on Mac OS Classic :
Figure 11.3. iODBC SDK Tree for Mac OS Classic
iODBC is cut down in three parts, and each one has its proper set of include files and libraries.
|The iODBC Driver Manager is the core of the ODBC driver manager. Its main task is to load run the right function with the right ODBC driver.|
|The iODBC Configuration Manager is the ODBC configuration manager. Its main task is to access and manage the DSN configuration files.|
|The iODBC GUI Manager is the GUI manager. Its main task is to give to the user the ability to access all the ODBC functionality through a GUI.|
Under the include directory, you will find all the iODBC header
files that can be used in your source. The following are the main
isqltypes.h, iodbcadm.h, iodbcinst.h
These are generally only a proxy for the other header files
provided in the same directory:
sqlext.h, sqltypes.h, odbcinst.h
To access all these include files, simply add to your compiler
an include path that points to
iODBC/include. This is compiler dependent,
so you may have to look into your compiler's documentation. For
Code Warrior, you can do this via the Project Preferences
Under the lib directory, you will find all the iODBC libraries needed to link against your application. All the parts explained before, are shipped through three different forms: CFM shared library, static object file, and static object file with debugging information.
Figure 11.4. iODBC SDK libraries on Mac
You will have to link your application with only one set of libraries. If you choose the CFM shared library set, ensure that at runtime these files are in the System-Extensions folder of your Mac Classic system.
To access the right set of library files, add a library path
that points to
is compiler dependent, consult your compiler documentation. For
Code Warrior, you can do this through the Project Preferences
11.3.2. Mac OS X
The package provided for this platform is a Macintosh Installer package (.mpkg) inside a disk-image (.dmg) file. After mounting the disk-image by double clicking on it, you will have to launch the Macintosh Installer package (.mpkg). You will be guided through the installation via the Macintosh Installer application.
iODBC follows the Programmer and System guidelines defined by Apple, this document can be found at: developer.apple.com
You will find the iODBC SDK installation in the following directory tree structure as installed on Mac OS X:
Figure 11.5. iODBC SDK tree on Mac OS X
In Mac OS X, "frameworks" are the central components of all SDKs. They provide everything needed by developers from include files to shared libraries with which you need to link your application. All frameworks support is well managed with Project Builder, shipped by Apple. Simply drag and drop via the provided GUI the corresponding framework you want use. If you want to use a framework through the command line compiler, see below.
The framework is basically a directory, structured as below:
Figure 11.6. iODBC SDK Frameworks on Mac OS X
When you need to include one of the framework header files, you have to prepend your header file name with the framework name as below :
iODBC is broken down into three frameworks, each having its own proper set of includes files and libraries.
|The iODBC.framework is the core of the ODBC driver manager. Its main task is to load run the right function with the right ODBC driver.|
|The iODBCinst.framework is the ODBC configuration manager. Its main task is to access and manage the DSN files.|
|The iODBCadm.framework is the GUI manager. Its main task is to give to the user the ability to access all the ODBC functionality through a GUI.|
First of all, you have to be sure that the compiler and linker you are using can manage frameworks correctly.
The iODBC SDK is shipped with the
Under Project Builder, you have to put all the frameworks that your application will use into your project. Implicitly, all these frameworks will be used. Also, you have to be sure that the machine where the application will be running includes all the frameworks with which you are linking. In certain cases, iODBC can be shipped with your application and all the frameworks.
This is the most straightforward way, but you can also directly
use the compiler and command line linker shipped with Project
Builder. In such case, you will have to add certain options to let
the compiler and linker know that you want to use a specific
framework. However, the sources do not require any changes. During
the compilation phase, you will have to use the "
F" option to add a path to let the
compiler search for frameworks under the designated path. The
correct syntax is "
dir is the path you want
to add. You have to put one path, and there is no limit on the
F options to pass on
the command line. For iODBC, you have to add only the following two
A complete cc compilation command line may look like:
cc c "F/Library/Frameworks" "F/System/Library/Frameworks" mysources.c
During the linkage phase, you will have to use the same option
as above, as well as specifying at the end of the command line all
the frameworks with which you are linking, preceded by the option
command line may look like:
cc o "myapplication" "F/Library/Frameworks" "F/System/Library/Frameworks" \ framework "iODBC" framework "iODBCinst" framework "iODBCadm"
11.3.4. Porting Mac OS Classic ODBC applications to Mac OS X
Carbon is a framework included with Apple's Mac OS X operating system that is derived from the original Macintosh Toolbox programming interface. Carbon on Mac OS X is an entirely new implementation, with a superset of the original Toolbox functionality, and many changes and additions to run under the Mac OS X operating system.
A subset of Carbon is also available on previous versions of the Mac OS, all the way back to Mac OS 8.1 or Mac OS 8.6 depending on the functionality required. This enables developers to create applications from one set of source code that will run on both the original Macintosh operating system as well as Mac OS X. Carbon applications can even take advantage of special Mac OS X features when running on Mac OS X, and continue to run as they have otherwise on earlier versions of the Mac OS.
Cocoa is a rich set of object-oriented frameworks that allow for the most rapid development of applications on Mac OS X. Using Cocoa, developers can create full-featured applications in a fraction of the time they would need for procedural languages. Applications from UNIX and other OS platforms can also be brought to Mac OS X quickly by using Cocoa to build state-of-the-art Aqua user interfaces while retaining most existing core code.
The Cocoa application environment is designed specifically for Mac OS X-only native applications. It is comprised of a set of object-oriented frameworks that support rapid development and high productivity. The Cocoa frameworks include a full featured set of classes designed to create robust and powerful Mac OS X applications. The object-oriented design simplifies application development and debugging.
Figure 11.7. iODBC SDK on Mac
Migration of iODBC applications to Carbon
The iODBC CFM Bridge is the library that Carbon applications must be linked against. This bridge is responsible for redirecting the ODBC API calls to the right iODBC version applicable to platform that the application is running on, beit Mac OS Classic or Mac OS X.
The iODBC CFM Bridge must be used exclusively. If you link against the iODBC CFM Bridge, ensure that no others iODBC libraries are linked in your project. The iODBC CFM Bridge linked applications require a valid iODBC installation on the target platform in order run successfully.
Any CFM libraries used must be included in your System-Extensions folder of your Mac Classic system in order to successfully support carbon applications at runtime.
Migration of iODBC applications to Cocoa
Under Project Builder, you have to put all the frameworks that your application will use in your project. Implicitly, all these frameworks will be used. Also, you have to be sure that the machine where you will run the application include all the frameworks you link with. In such cases, iODBC can be shipped with your application including all the frameworks.
This is the most straight forward way, but you can also directly use the compiler and linker command line shipped with Project Builder. In a such case, you will have to add some options to inform the compiler and linker that you want to use a specific framework. The sources sources do not have to change.
During the compilation phase, use the
-Fdir option on the compiler command line
to add a search path to the framework path, where dir is the path
you want to add. You may only specify one path per
-F option, but you not limited to the
-F options used.
iODBC compilations only require
command line may look like:
cc -c "-F/Library/Frameworks" "-F/System/Library/Frameworks" ... mysources.c
During the linkage phase, you will have to use the same option as above, and to specify at the end of the command line all the framework you want to link with, preceded with the option -framework . A complete cc linkage command line may look like:
cc -o "myapplication" "-F/Library/Frameworks" "-F/System/Library/Frameworks" ... \ -framework "iODBC" -framework "iODBCinst" -framework "iODBCadm"