iODBC.org

Standard ODBC Architecture

ODBC data access comprises the following, four components:

Application

Most end users use ODBC-compliant applications to access their data stores. ODBC-compliant applications are executables, which issue ODBC API calls. These API calls are implemented by ODBC drivers that are customized for use with the data store. These calls enable the application to connect to the data store and query the data store via the ODBC driver.

Driver Manager

The driver manager is a library, which manages communications between applications and ODBC drivers. It responds to all ODBC connection requests made by applications, and it loads the ODBC drivers that are associated with the requests. Once the drivers are loaded, the driver manager translates applications' function calls into the corresponding ODBC API calls, and it issues these calls to the drivers. When the applications complete their requests, the driver manager terminates the connections and unloads the drivers.

Users may encounter the following driver managers on Mac client systems:

ODBC Drivers

ODBC drivers are libraries. These libraries implement ODBC API functions, which enable applications to speak to databases. Typically, applications are linked against driver managers, which load the appropriate driver libraries. However, applications may be linked directly to drivers. In this instance, driver libraries perform driver manager library functions.

Data sources

The term data source has two, distinct meanings. First, data source refers to the actual flat files, spreadsheets, or database management systems, which store data. Second, data source refers to the collection of parameters that applications use to establish connections to data stores. This data source passes a driver name, database name, server hostname, and other parameters, which are necessary to identify a database or similar storage entity.

ODBC Driver Architecture with Driver Manager

Figure 1-1 illustrates the default architecture for ODBC connectivity. The default architecture employs both a driver manager and ODBC drivers.

ODBC Driver Architecture without Driver Manager

Figure 1-2 illustrates ODBC connectivity without a driver manager component. ODBC connectivity is possible, in the absence of a driver manager, if the client application is linked directly to the ODBC driver. In some instances, a symbolic link is created, which uses a driver manager library name to point to an ODBC driver library.

OpenLink ODBC Driver Architecture

OpenLink Software provides two ODBC driver formats. Use of these drivers requires knowledge of the following items:

• Environment Variables
• Client Libraries
• Header Files
• Configuration Files
• Administrative Assistants
• Server Components

Environment Variables

Environment variables pass the locations of files and directories, which the operating system or applications need to accomplish tasks. Users do not need to set environment variables on Mac Classic and Mac OS X operating systems. Users do need to set environment variables on Darwin.

The following table lists environment variables, which must be set on Darwin clients.

Setting Environment Variables on Darwin

OpenLink's Darwin installers create openlink.sh and openlink.csh files in the root of the installation. These files contain all the environment variables, which need to be set for OpenLink client connectivity. Users must execute these files in the appropriate shell. C shell users may execute openlink.csh. Bash and Bourne shell users may execute openlink.sh. Users with different shells are encouraged to switch to C, Bash, or Bourne before executing the files.

Expert users may set and export the appropriate variables using the Darwin command line. For example:

export ODBCINI=/usr/openlink/bin/odbc.ini

Users may also add the variables to their .profiles to insure that the variables are set at login to their client systems.

Client Libraries

OpenLink's drivers and iODBC driver manager are library files. Users will encounter a variety of library file formats and installation locals on different, client operating systems.

The following table holds a list of common Darwin libraries. Each of these files appears in the /lib sub-directory of the OpenLink client installation. Click here to see a complete list of OpenLink libraries by platform.

Header Files

OpenLink Software provides a separate iODBC SDK product installer for Mac Classic and Mac OS X platforms. These installers contain the sql.h, sqlext.h, and sqltypes.h header files. Developers may use these files to build ODBC-compliant applications.

Configuration Files

OpenLink's Darwin-based Single-Tier drivers use the openlink.ini file to obtain database-specific environment variable settings. The openlink.ini file resides in the /bin sub-directory of Single-Tier client installations.

OpenLink's Multi-Tier brokers read the oplrqb.ini file to resolve ODBC connection requests and to enforce OpenLink's sophisticated, rule-based security. The oplrqb.ini file resides in the /bin sub-directory of OpenLink's server components installations.

Administrative Assistants

OpenLink Software produces two, graphical Administrative Assistants. The Multi-Tier Administrative Assistant is a web-based GUI, which allows users to configure all aspects of Multi-Tier connectivity. This assistant allows users to create Multi-Tier data source names, configure Multi-Tier Server components, configure rules-based security, and debug ODBC connectivity problems.

OpenLink Software also produces the independent, HTTP-based iODBC Data Sources Administrator. This web-based GUI enables users to create and administer OpenLink and non-OpenLink ODBC data source names using one, user-friendly interface.

Server Components

OpenLink's Multi-Tier drivers implement a client/server connectivity model. The Multi-Tier client comprises a driver manager and client-side ODBC driver. The Multi-Tier server component comprises a request broker and one or more database agents.

The request broker is a generic, listening process. It responds to ODBC requests made by the Multi-Tier client driver. The broker reviews these requests and spawns the appropriate database agent. The database agent is the only portion of the Multi-Tier product portfolio that is written to a specific CLI. Specifically, the database agent speaks the CLI of the database to which it is meant to connect. Hence, the agent is able to submit the SQL request to the database, retrieve its results, and convey those results to the client application.

Configuring OpenLink Data Source Names

Users must create ODBC data source names to establish connectivity between client applications and SQL data stores. ODBC data source names are collections of parameters, which enable the OpenLink driver to identify and connect to the data store. There are several means, which users may employ to create ODBC data source names.

Configuring Darwin Data Source Names

There are three methods, which users may employ to configure Darwin data source names. Expert users may configure the odbc.ini file using vi or a similar text editor. Novice users may use the HTTP-Based iODBC Data Sources Administrator, or they may use the Multi-Tier Administrative Assistant.

The odbc.ini File

The odbc.ini file appears in the /bin sub-directory of the OpenLink client installation. Users may open this file with vi or a similar text editor. The following table describes sections, which users will encounter in odbc.ini.

ODBC Data Sources

The ODBC Data Sources section lists the names of the individual data sources and pairs the names with the appropriate ODBC client driver. These data sources names are associated with formal data source specifications, which appear later in the file.

Here is the ODBC Data Sources format:

[ODBC Data Sources] 
data_source_name=ODBC_client_driver_name

Here is a sample ODBC Data Sources section with data source names:

[ODBC Data Sources]
ora81_lite = OpenLink Oracle 8.1 Lite Driver (multi threaded)
pgr7_lite = OpenLink PostgreSQL Lite Driver (multi threaded)

Data Source Specification

Each [ODBC Data Sources] data source name has a corresponding data source specification. The data source specification lists parameters, which are necessary to establish the ODBC connection. Here is the OpenLink data source specification format:

[data_source_name]
Driver = driver_path
ServerType = openlink_domain_alias
Username = database_username
Password = database_password
Database = database_name_or_oracle_sid
Options = three_tier_or_sockets_connection_parameters
FetchBufferSize = buffer_size
ReadOnly = enable_disable_readonly_access_to_database
DeferLongFetch = enable_disable_deferlongfetch_option
JetFix = enable_disable_jetfix_option
Description = data_source_description

Here is a sample data source specification:

[Oracle]
Driver = /usr/openlink/lib/ora81_st_lt.sl
ServerType = Oracle 8.1.x
Username = scott
Password = tiger
Database = ORCL
Options = 
FetchBufferSize = 99
ReadOnly = Yes
DeferLongFetch = No
JetFix = No
Description = Oracle DSN

The following table explains the parameters that appear in the data source specification sections.

Parameter	Description
[Data Source Name]	Passes a descriptive data source title. This title must match the title passed under the [ODBC Data Sources] heading.
Driver	Passes the full path to the ODBC client driver.
ServerType	Passes a valid OpenLink domain alias. This domain alias must match a valid domain alias in the Single-Tier openlink.ini file or Multi-Tier oplrqb.ini file. The drivers use these domain aliases as starting points from which to assess rules, environment variables, and agent binaries to instantiate for connections.
Username	Passes a valid database username. If the Multi-Tier OPSYSLOGIN parameter is enabled, this parameter passes a valid operating system username.
Password	Passes a valid database password. If the Multi-Tier OPSYSLOGIN parameter is enabled, this parameter passes a valid operating system password.
Database	Passes the name of a database or Oracle SID. Progress users should pass the full path to their databases.
Options	Passes Progress SHN sockets parameters. Users may also use the field to pass database native communications parameters to establish three-tier connections. For instance, users may pass Sybase instance names, Oracle aliases, or Ingres vnodes to connect database agents--through local database native clients--to remote databases.
FetchBufferSize	Passes an integer, which represents the number of rows that the driver will return during an individual fetch.
ReadOnly	Passes a Yes or No value to enable or disable READONLY access to the data store.
DeferLongFetch	Passes a Yes or No value to enable or disable deferred fetching. Deferred fetching causes large, binary objects to be fetched after other, smaller data. This enhances performance.
JetFix	Passes a Yes or No value to enable or disable JetFix. JetFix facilitates translation of data types by Microsoft's Jet Engine. This feature is intended primarily for use with Microsoft client applications on Windows.
Description	Passes a description of the use or nature of the data source name.

The following table explains additional values, which may be added to Multi-Tier data source name specifications.

OpenLink produces the HTTP-Based iODBC Data Sources Administrator for Darwin and other platforms. This Web-based administrator is a stand-alone GUI interface to the iODBC driver manager. It is similar to the Microsoft ODBC Data Sources Administrator, and it allows users to create OpenLink and non-OpenLink data source names.

Use the following instructions to create data source names with the iODBC Data Sources Administrator.

• cd into the /bin/w3config sub-directory of the client's OpenLink installation.
• Use a text editor to open the www_sv.ini file.
• Locate the [Startup] section.
• Record the value passed to HttpPort. For example:
  

                
  [Startup]
  HttpPort          = 8000
  

  
  
• Exit the file.
• cd into the /bin sub-directory of the client's OpenLink installation.
• Run the following command:
  

                
  ./iodbc-admin-httpd.sh start
  

  
  
• Open a Web browser.
• Enter the following URL: http://localhost:HttpPort_from_www_sv.ini
• Expand the following menu items: Client Components Administration -> Data Source Name Configuration -> Edit Data Sources by Wizard -> Edit ODBC Data Sources.
• Provide the administrator username and password. Both fields default to admin.
• Click Add.
• Select the appropriate OpenLink ODBC driver.
• Click Next.
• Use setup screens 1 to 5 to provide connection parameters and to disable or enable optional features. Figures 1-3 describes Single-Tier parameters and options. Figure 1-4 describes Multi-Tier parameters and options.

• Figure 1-3 - Single-Tier Parameters & Options*

• Note:* The Server parameter name changes to reflect the database to which you are trying to connect. For instance, the setup routine will replace Server with Net 8 Service Name, if you choose an Oracle Single-Tier driver.

• Figure 1-4 - Multi-Tier Parameters & Options*

• Note:* The Server parameter name changes to reflect the database to which you are trying to connect. For instance, the setup routine will replace Server with Net 8 Service Name, if you choose an Oracle domain.

• Click the Save button, which appears on the sixth setup screen.
• Click the Finish button, which appears on the last setup screen.

The Multi-Tier Administrative Assistant

OpenLink produces the Multi-Tier Administrative Assistant for all server operating systems, which it supports. This Web-based assistant is powered by OpenLink's server components, and it provides utilities to configure these components. However, the assistant also provides a GUI interface to the iODBC driver manager. This interface is similar to the Microsoft ODBC Data Sources Administrator, and it allows users to create OpenLink data source names.

Use the following instructions to create data source names with the Multi-Tier Administrative Assistant.

• cd into the /bin/w3config sub-directory of the server's OpenLink installation.
• Use a text editor to open the www_sv.ini file.
• Locate the [Startup] section.
• Record the value passed to HttpPort. For example:
  

                
  [Startup]
  HttpPort          = 8000
  

  
  
• Exit the file.
• cd into the /bin sub-directory of the server's OpenLink installation.
• Run the following command: oplrqb
• Open a Web browser.
• Enter the following URL:
  

                
  http://localhost:HttpPort_from_www_sv.ini
  

  
  
• Expand the following menu items: Client Components Administration -> Data Source Name Configuration -> Edit Data Sources by Wizard -> Edit ODBC Data Sources.
• Provide the administrator username and password. Both fields default to admin.
• Click Add.
• Select the OpenLink Generic ODBC driver.
• Click Next.
• Use setup screens 1 to 5 to provide connection parameters and to disable or enable optional features.

Figure 1-5 describes Multi-Tier parameters and options

• Figure 1-5 - Multi-Tier Parameters & Options*

• Note:* The Server parameter name changes to reflect the database to which you are trying to connect. For instance, the setup routine will replace Server with Net 8 Service Name, if you choose an Oracle domain.

• Click the Save button, which appears on the sixth setup screen.
• Click the Finish button, which appears on the last setup screen.

Configuring Mac Classic Data Source Names

OpenLink Software provides Multi-Tier client software for the Mac Classic operating system. The following instructions will enable users to create Multi-Tier data source names on Mac Classic.

• Expand the Apple menu.
• Expand the Control Panels menu.
• Select the ODBC Setup PPC menu item.
• Click on the System DSN, User DSN, or File DSN tab.
• Click Add.
• Select the OpenLink Generic ODBC driver.
• Click Finish.
• Use the Generic ODBC Setup dialog to provide connection parameters and to disable or enable optional features. Figure 1-6 describes Multi-Tier parameters and options

• Figure 1-6 - Multi-Tier Parameters & Options*

• Note:* The Optional Server parameter name changes to reflect the database to which you are trying to connect. For instance, the setup routine will replace Server with Net 8 Service Name, if you choose an Oracle domain.

• Click OK to save your data source name.

Configuring Mac OS X Data Source Names

There are two methods, which users may employ to configure Mac OS X data source names. Expert users may configure the ODBC.preference file with TextEdit or a similar text editor. Novice users may use an Aqua GUI ODBC Administrator.

• The ODBC.preference File*

The ODBC.preference file appears in the /Library/Preferences directory. Users may open this file with TextEdit or a similar text editor. The following table describes sections, which users will encounter in ODBC.preference.

ODBC Data Sources

The ODBC Data Sources section lists the names of the individual data sources and pairs the names with the appropriate ODBC client driver. These data sources names are associated with formal data source specifications, which appear later in the file.

Here is the ODBC Data Sources format:

[ODBC Data Sources]
data_source_name=ODBC_client_driver_name

Here is a sample ODBC Data Sources section with data source names:

[ODBC Data Sources]
ora81_lite = OpenLink Oracle 8.1 Lite Driver (multi threaded)
pgr7_lite  = OpenLink PostgreSQL Lite Driver (multi threaded)

Data Source Specification

Each [ODBC Data Sources] data source name has a corresponding data source specification. The data source specification lists parameters, which are necessary to establish the ODBC connection. Here is the OpenLink Multi-Tier data source specification format:

[data_source_name]
Driver = driver_path
Description = data_source_description
ServerType = openlink_domain_alias
FetchBufferSize = buffer_size
Host = hostname_of_machine_which_hosts_OpenLink_server_components
Port = port_on_which_openlink_broker_listens
Database = database_name_or_oracle_sid
Protocol = network_communications_protocol
Options = three_tier_or_sockets_connection_parameters
ReadOnly = read_only_flag
Username = database_username
Password = database_password
NoLoginBox = enable_disable_login_dialog_box
DeferLongFetch = enable_disable_deferlongfetch_option

Here is a sample, Multi-Tier data source specification:

[Oracle]
Driver = /usr/openlink/lib/oplodbc.so.1
Description = Oracle DSN
ServerType = Oracle 8.1.x
FetchBufferSize = 99
Host = localhost
Port = 5000
Database = ORCL
Protocol = TCP/IP
Options = 
ReadOnly = Yes
Username = scott
Password = tiger
NoLoginBox = No
DeferLongFetch = No

The following table explains the parameters that appear in the Multi-Tier data source specification sections.

All OpenLink Single-Tier drivers recognize a common subset of specifications parameters. Individual Single-Tier drivers recognize an additional set of parameters, which are specialized for the database to which they connect.

Here is a representative Single-Tier data source specification format:

[data_source_name]
Driver = driver_path
Description = data_source_description
Database =  database_name_or_oracle_sid
Cursor_Sensitivity = enable_disable_dynamic_cursor_row_version_cache
FetchBufferSize = buffer_size
InitialSQL = path_to_script_containing_sql_statements
UserName = database_username
Password = database_password
MaxRows = maximum_number_of_rows_to_return_per_resultset
NoAutoCommit = enable_disable_autocommit
NoLoginBox = enable_disable_login_dialog_box
NoRowsetSizeLimit = enable_disable_norowsetsizelimit
ReadOnly = enable_disable_read_only_access_to_database
Options = three_tier_or_sockets_connection_parameters
DeferLongFetch = enable_disable_deferlongfetch_option

Here is a sample, Single-Tier data source specification:

[Oracle]
Driver = /usr/openlink/lib/ora81_st_lt.sl
Description = Oracle DSN
Database = ORCL
Cursor_Sensitivity = Yes
FetchBufferSize = 99
InitialSQL = 
UserName = scott
Password = tiger
MaxRows = 
NoAutoCommit = Yes
NoLoginBox = No
NoRowsetSizeLimit = Yes
ReadOnly = Yes
Options = 
DeferLongFetch = No

The following table explains the parameters, which all Single-Tier drivers recognize.

MS SQL Server Single-Tier drivers recognize these specialized parameters.

MySQL Single-Tier drivers recognize these specialized parameters.

Oracle Single-Tier drivers recognize these specialized parameters.

PostgreSQL Single-Tier drivers recognize these specialized parameters.

Aqua GUI ODBC Administrators

Users may encounter one of three, Aqua GUI ODBC administrators on Mac OS X. Users may encounter the ODBC Administrator, the iODBC Administrator, or Data Direct's ODBC Configure. Different driver managers are installed by different OpenLink install bundles and client applications.

The ODBC Administrator ships with Apple's Jaguar installers. Users will find the ODBC Administrator's icon in their /Applications/Utilities folder. This administrator is an Apple-native interface to the iODBC dylibs driver manager. Apple dylibs are dynamic shared libraries. One copy of a .dylib or dynamic library may be shared by multiple applications simultaneously. These libraries are similar in theory to Unix dynamic libraries. However, their use and implementation are different.

The iODBC Administrator ships with OpenLink Software's driver installers. Users will find the iODBC Administrator's icon in their /Applications folder. This administrator is an OpenLink-native interface to the iODBC frameworks driver manager. Apple frameworks are special bundles or packages, which contain dynamic shared libraries, header files, documentation, and other resources that are necessary to use the library.

The ODBC Configure administrator ships with Filemaker 6. Users will find the ODBC Configure icon in /Applications/Data Direct ODBC Folder. This administrator is a Data Direct-native interface to the Data Direct's Carbon-based, CFM driver manager. Carbon is an older, Mac OS application environment and API, which Apple modified for use with Mac OS X operating systems. The CFM driver manager is based on Apple's CFM technology. CFM is an abbreviation for Code Fragment Manager. The Code Fragment Manager loads code fragments (libraries, applications, code, etc.) and prepares them for execution.

The following instructions will enable users to create OpenLink data sources using any ODBC administrator.

• Open the appropriate administrator.
• Click on the System, User, or File tab.
• Click Add.
• Select the appropriate OpenLink Single-Tier or Multi-Tier driver.
• Click Finish.
• Use the ODBC Setup dialog to provide connection parameters and to disable or enable optional features.

Figure 1-7 describes Multi-Tier parameters and options*

• Figure 1-7 - Multi-Tier Parameters & Options*

*Note:* The optional Server parameter name changes to reflect the database to which you are trying to connect. For instance, the setup routine will replace Server with Net 8 Service Name, if you choose an Oracle domain.

Figure 1-8 describes common Single-Tier parameters and options

*Figure 1-8 - Common Single-Tier Parameters & Options*

Figure 1-9 describes additional, database specific Single-Tier parameters and options.

• Figure 1-9 - Database-Specific Single-Tier Parameters & Options*

• Click OK to save your data source name.

Developing ODBC Compliant Applications

OpenLink Software's Software Development Kits (SDK's) provide powerful tools for Apple applications developers. While Apple SDK's provide only the dylibs format driver manager, OpenLink's SDK's provide both the dylibs and frameworks format driver managers. This distinction is critical. The frameworks format driver manager provides the applications developer with versatility that is not available with dylibs.

Frameworks bundles contain multiple revisions of the iODBC driver manager. Moreover, the driver manager library name points to the latest revision of the component. Therefore, developers do not need to set environment variables to point to the appropriate file. However, applications developers can choose to instantiate legacy revisions. In other words, developers can hard link applications to older driver managers to access functionality that is not present in recent revisions.

Finally, OpenLink's SDK's enable developers to build Classic, Carbon, and Cocoa native applications. Furthermore, OpenLink's SDK's assist developers who need to migrate applications from the Classic API to Carbon. And, OpenLink aids developers who need to compile applications, which run on both Classic and Mac OS X. To proceed, developers simply link their applications against OpenLink's iODBC libraries. The resulting binary issues calls to the iODBC CFM Bridge. This bridge ships with OpenLink's iODBC bundles, and it exists in Classic and OS X formats. It identifies the correct driver manager format, which to load.

• macodbc1.jpg:

OpenLink Driver Objectives

OpenLink Software's ODBC data access technologies simplify client and server computing. These technologies are based on the principle of interoperability. This principle dictates that one client application can access diverse, back-end database management systems, without knowledge of proprietary database protocols. Thereby, this powerful technology allows application developers to develop, compile, and ship applications, which speak to any, ODBC-compliant data source. The application developer does not need to cater to any specific vendor's DBMS. Moreover, application developers do not need to attend to any specific client/server architecture. The application and DBMS may reside on one or more machines. These machines may comprise similar or dissimilar operating systems and hardware.

OpenLink Software's ODBC data access technologies meet their objectives, because they are based on Microsoft's ODBC specification. The specification defines the ability to:

• Connect and disconnect to ODBC-compliant data sources.
• Retrieve SQL data from ODBC data sources.
• Obtain an ODBC driver's capabilities and characteristics.
• Obtain and manipulate ODBC driver options.
• Prepare and execute SQL statements.
• Retrieve SQL result sets and process results dynamically.
• Retrieve result metadata and process metadata dynamically

OpenLink Driver Features

OpenLink's Single-Tier and Multi-Tier Data Access Drivers provide ODBC 1.x-3.x compliance. The two driver formats also provide the following features:

Single-Tier Drivers

• Blistering performance
• ODBC core, level 1, level 2, and extensions support
• Client-based scrollable cursor support
• Mac OS X client access to Microsoft SQL Server, MySQL, Oracle, PostgreSQL, and Sybase
• Support for all network protocols and server operating environments, which are supported by the database vendors' communications products.

• Note:* Single-Tier data access is dependent upon client installation of the database native communications software. For example, Oracle users require a client side installation of Net8. Progress users require a client side installation of Progress Client Networking. OpenLink's drivers for Microsoft SQL Server and Sybase are an exception. These drivers contain FreeTDS libraries, which enable OpenLink's Single-Tier drivers to speak directly to Microsoft SQL Server and Sybase databases without Microsoft SQL Server's NETLIB or Sybase's Open Client product.

Multi-Tier Drivers

• Blistering performance
• ODBC core, level 1, level 2, and extensions support
• Built-in, database-independent communications layer
• Sophisticated data encryption
• Concurrent access to heterogeneous ODBC drivers
• Intelligent metadata information handling
• Array fetching
• Network-centric result set management
• Scrollable cursor support
• Implementation of scrollable cursors across non-OpenLink ODBC drivers
• Support for all native backend functionality
• Support for distributed database capabilities of relevant backend database engines
• Implementation of all inter-process communications mechanisms supported by relevant database engines. (Sockets, Shared Memory, Pipes etc.)
• Enforcement of query optimizer configurations across all OpenLink client components
• Enforcement of database engine ISOLATION LEVELS across all OpenLink client components.