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.0-3.0 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 MS SQL Server, MySQL , Oracle 8i, 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 MS SQLServer and Sybase SQLServer drivers are an exception. These drivers contain FreeTDS libraries, which enable OpenLink's Single-Tier drivers to speak directly to MS SQLServer and Sybase databases without MS SQLServer'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.

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:

Platform Driver Manager
Darwin OpenLink's Darwin client installer provides the iODBC driver manager. Users may also encounter unixODBC, mac:ODBC, and other driver managers.
Mac Classic OpenLink's Mac Classic client installer provides its own driver manager for this platform. Users may also encounter another driver manager created by Visigenic and maintained by Intersolv, Merant, and Data Direct respectively.
Mac OSX OpenLink's default Mac OS X client installer provides an iODBC frameworks-based driver manager. Apple's Jaguar installer provides an iODBC dylibs-based driver manager. Users may also encounter unixODBC, mac:ODBC, and other driver managers.

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.

Macfig1.jpg

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.

Macfig2.jpg

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.

Environment Variable Description
CLASSPATH Passes the full path to OpenLink's JAVA archive (.jar) files. These files compose the OpenLink JDBC client. This variable is not required for ODBC connectivity.
LD LIBRARY_PATH Passes the full path to various library directories on Darwin computers. This variable must include the OpenLink /lib sub-directory.
ODBCINI Passes the full path to the odbc.ini file, which resides in the OpenLink /bin sub-directory.
ODBCINSTINI Passes the full path to the odbcinst.ini file, which resides in the OpenLink /bin sub-directory.
OPENLINKINI Passes the full path to the openlink.ini file, which resides in the OpenLink /bin sub-directory.
PATH Passes the full path to directories, which contain executables. This variable must include the OpenLink /bin sub-directory.

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 chart depicts 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.

Filename Description
libiodbc.la Static, iODBC driver manager library.
libiodbc.so Shared, iODBC driver manager library. Older, iODBC driver manager libraries are linked to the latest revision.
libiodbc.so.2 Revised, iODBC driver manager library. Older, iODBC driver manager libraries are linked to the latest revision.
libiodbc.so.2.1.2 Revised, iODBC driver manager library. Older, iODBC driver manager libraries are linked to the latest revision.
mys3 st_lt.la Static, single-threaded MySQL Single-Tier driver.
mys3_st_lt.so Shared, single-threaded MySQL Single-Tier driver.
oplodbc.la Static, Multi-Tier ODBC driver.
oplodbc.so Shared, Multi-Tier ODBC driver. Older, Multi-Tier ODBC driver library files are linked to the latest revision.
oplodbc.so.1 Revised, Multi-Tier ODBC driver library. Older, Multi-Tier ODBC driver library files are linked to the latest revision.
oplodbc.so.1.0.0 Revised, Multi-Tier ODBC driver library. Older, Multi-Tier ODBC driver library files are linked to the latest revision.
ora81_st_lt.la Static, single-threaded Oracle 8.1.x Single-Tier driver.
ora81_st_lt.so Shared, single-threaded Oracle 8.1.x Single-Tier driver.
pgr7_mt_lt.la Static, multi-threaded PostgreSQL Single-Tier driver.
pgr7_mt_lt.so Shared, multi-threaded PostgreSQL Single-Tier driver.
pgr7_st_lt.la Static, single-threaded PostgreSQL Single-Tier driver.
pgr7_st_lt.so Shared, single-threaded PostgreSQL Single-Tier driver.
sql_st_lt.la Static, single-threaded MS SQLServer Single-Tier driver.
sql_st_lt.so Shared, single-threaded MS SQLServer Single-Tier driver.
syb12_st_lt.la Static, single-threaded Sybase Single-Tier driver.
syb12_st_lt.so Shared, single-threaded Sybase Single-Tier driver

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, rules-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.

Section Description
ODBC Data Sources This section names each of the ODBC data sources that appear in the odbc.ini file. It also pairs the appropriate ODBC driver name with the data source name.
Data Source Specifications This section lists the actual data source names. Each data source name is composed of a formal name and a parameter list.

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 for use with MS Access client applications.
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.

Parameter Description
Protocol Passes a valid OpenLink network protocol. The default is TCP/IP.
Hostname Passes the hostname or IP address of the machine, which contains the OpenLink request broker.
Port Passes the TCP port, on which the request broker listens. This TCP port is associated with the ListenPort parameter, and it appears in the [Protocol TCP] section of the Multi-Tier Rules Book (oplrqb.ini).

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*
Parameter Description
Name Passes a descriptive data source title.
Comment Passes a description of the use or nature of the data source name.
Database Name Passes the name of a database or Oracle SID. Progress users should pass the full path to their databases.
Server 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.
Username Passes a valid database username. If the Multi-Tier OPSYSLOGIN parameter is enabled, this parameter passes a valid operating system username.
Read-only connection Passes a Yes or No value to enable or disable READONLY access to the data store.
No Login Dialog Box Enables or disables the login popup box.
Defer Fetching of long data 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.
Row buffer size Passes an integer, which represents the number of rows that the driver will return during an individual fetch operation.
Jet Fix 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 for use with MS Access client applications.
Environment Passes a valid OpenLink domain alias. This domain alias must match a valid domain alias in the Single-Tier openlink.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.
  • 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*
Parameter Description
Name Passes a descriptive data source title.
Comment Passes a description of the use or nature of the data source name.
Domain Passes a valid OpenLink domain alias. This domain alias must match a valid domain alias in the 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.
Hostname Passes the hostname or IP address of the machine, which contains the OpenLink request broker.
Port Passes the TCP port, on which the request broker listens. This TCP port is associated with the ListenPort parameter, and it appears in the [Protocol TCP] section of the Multi-Tier Rules Book (oplrqb.ini).
Protocol Passes a valid OpenLink network protocol. The default is TCP/IP.
Database Name Passes the name of a database or Oracle SID. Progress users should pass the full path to their databases.
Server 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.
Username Passes a valid database username. If the Multi-Tier OPSYSLOGIN parameter is enabled, this parameter passes a valid operating system username.
Read-only Connection Passes a Yes or No value to enable or disable READONLY access to the data store.
No Login Dialog Box Enables or disables login popup box.
Defer Fetching of long data 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.
Row buffer size Passes an integer, which represents the number of rows that the driver will return during an individual fetch.
  • 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*
Parameter Description
Name Passes a descriptive data source title.
Comment Passes a description of the use or nature of the data source name.
Domain Passes a valid OpenLink domain alias. This domain alias must match a valid domain alias in the 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.
Hostname Passes the hostname or IP address of the machine, which contains the OpenLink request broker.
Port Passes the TCP port, on which the request broker listens. This TCP port is associated with the ListenPort parameter, and it appears in the [Protocol TCP] section of the Multi-Tier Rules Book (oplrqb.ini).
Protocol Passes a valid OpenLink network protocol. The default is TCP/IP.
Database Name Passes the name of a database or Oracle SID. Progress users should pass the full path to their databases.
Server 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.
Username Passes a valid database username. If the Multi-Tier OPSYSLOGIN parameter is enabled, this parameter passes a valid operating system username.
Read-only Connection Passes a Yes or No value to enable or disable READONLY access to the data store.
No Login Dialog Box Enables or disables login popup box.
Defer Fetching of long data 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.
Row buffer size Passes an integer, which represents the number of rows that the driver will return during an individual fetch.
  • 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*
Parameter Description
Name Passes a descriptive data source title.
Comment Passes a description of the use or nature of the data source name.
Domain Passes a valid OpenLink domain alias. This domain alias must match a valid domain alias in the 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.
Hostname Passes the hostname or IP address of the machine, which contains the OpenLink request broker.
Port Passes the TCP port, on which the request broker listens. This TCP port is associated with the ListenPort parameter, and it appears in the [Protocol TCP] section of the Multi-Tier Rules Book (oplrqb.ini).
Protocol Passes a valid OpenLink network protocol. The default is TCP/IP.
Database Name Passes the name of a database or Oracle SID. Progress users should pass the full path to their databases.
Server 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.
Username Passes a valid database username. If the Multi-Tier OPSYSLOGIN parameter is enabled, this parameter passes a valid operating system username.
Read-only Connection Passes a Yes or No value to enable or disable READONLY access to the data store.
No Login Dialog Box Enables or disables login popup box.
Defer Fetching of long data 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.
Row buffer size Passes an integer, which represents the number of rows that the driver will return during an individual fetch.
  • 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.

Section Description
ODBC Data Sources This section names each of the ODBC data sources that appear in the ODBC.preference file. It also pairs the appropriate ODBC driver name with the data source name.
Data Source Specifications This section lists the actual data source names. Each data source name is composed of a formal name and a parameter list.

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.

Parameter Description
Name Passes a descriptive data source title.
Comment Passes a description of the use or nature of the data source name.
Domain Passes a valid OpenLink domain alias. This domain alias must match a valid domain alias in the 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.
Hostname Passes the hostname or IP address of the machine, which contains the OpenLink request broker.
Port Passes the TCP port, on which the request broker listens. This TCP port is associated with the ListenPort parameter, and it appears in the [Protocol TCP] section of the Multi-Tier Rules Book (oplrqb.ini).
Protocol Passes a valid OpenLink network protocol. The default is TCP/IP.
Database Name Passes the name of a database or Oracle SID. Progress users should pass the full path to their databases.
Server 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.
Username Passes a valid database username. If the Multi-Tier OPSYSLOGIN parameter is enabled, this parameter passes a valid operating system username.
Read-only Connection Passes a Yes or No value to enable or disable READONLY access to the data store.
No Login Dialog Box Enables or disables login popup box.
Defer Fetching of long data 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.
Row buffer size Passes an integer, which represents the number of rows that the driver will return during an individual fetch.

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.

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.
Description Passes a description of the use or nature of the data source name.
Cursor_Sensitivity Passes a Yes or No value to enable or disable the row version cache, which is used with dynamic cursors.
FetchBufferSize Passes an integer, which represents the number of rows that the driver will return during individual fetch operations.
InitialSQL Passes a path to a file containing SQL statements. These statements are issued against the database upon initial connection. InitialSQL scripts usually contain statements, which set ISOLATION levels.
Username Passes a valid database username.
Password Passes a valid database password
MaxRows Passes an integer, which limits the maximum number of rows that may be returned.
NoAutoCommit Passes a Yes or No value, which enables or disables the driver's autocommit behaviour.
NoLoginBox Passes a Yes or No value to disable or enable the login pop-up box.
NoRowsetSizeLimit Passes a Yes or No value to enable or disable rowset size limits. Default rowset size limits are enforced by the cursor library. These limits prevent the driver from consuming all available memory in the event that rowsets are inordinately large.
ReadOnly Passes a Yes or No value to enable or disable READONLY access to the data store.
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.
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.
  • MS SQLServer Single-Tier drivers recognize these specialized parameters.*
Parameter Description
TDSHost Passes the hostname or IP address of the machine that hosts SQLServer.
TDSPort Passes the TCP port on which SQLServer listens.
TDSVersion Passes the TDS Version specification number. Do not alter this value.
SQLServerCatalog Passes Yes to use Microsoft SQLServer implementation of catalog calls. Passes No to use Sybase implementation.
  • MySQL Single-Tier drivers recognize these specialized parameters.*
Parameter Description
Disable ODBC transactions Disables transaction management. Enforces autocommit for all statements.
  • Oracle Single-Tier drivers recognize these specialized parameters.*
Parameter Description
OraCatalogs Promotes efficient processing of Oracle catalog calls such as SQLForeignKey () and SQLPrimaryKeys (). The appropriate odbccat#.sql script must be run before OraCatalogs is enabled. There is one odbccat#.sql script for each Oracle database version.
ShowRemarks Retrieves contents of SQLColumns REMARKS field.
UserTblsFirst Causes user tables to appear at beginning of SQLTables() table name listing.
CountProcParms Insures that number of parameters passed by stored procedures matches the number of parameters expected by SQLProcedures.
OCIPrefetchRows Passes an integer value, which represents the number of rows to prefetch.
OCIPrefetchMemory Passes an integer value, which represents the amount of memory to use for prefetch operations.
OracleDirectory Passes the full path to the Oracle home directory.
  • PostgreSQL Single-Tier drivers recognize these specialized parameters.*
Parameter Description
Disable ODBC transactions Disables transaction management. Enforces autocommit for all statements.

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*
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.
Description Passes a description of the use or nature of the data source name.
Cursor_Sensitivity Passes a Yes or No value to enable or disable the row version cache, which is used with dynamic cursors.
FetchBufferSize Passes an integer, which represents the number of rows that the driver will return during individual fetch operations.
InitialSQL Passes a path to a file containing SQL statements. These statements are issued against the database upon initial connection. InitialSQL scripts usually contain statements, which set ISOLATION levels.
Username Passes a valid database username.
Password Passes a valid database password
MaxRows Passes an integer, which limits the maximum number of rows that may be returned.
NoAutoCommit Passes a Yes or No value, which enables or disables the driver's autocommit behaviour.
NoLoginBox Passes a Yes or No value to disable or enable the login pop-up box.
NoRowsetSizeLimit Passes a Yes or No value to enable or disable rowset size limits. Default rowset size limits are enforced by the cursor library. These limits prevent the driver from consuming all available memory in the event that rowsets are inordinately large.
ReadOnly Passes a Yes or No value to enable or disable READONLY access to the data store.
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.
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.
  • 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*
Parameter Description
DSN Passes a descriptive data source title.
Description Passes a description of the use or nature of the data source name.
Hostname Passes the hostname or IP address of the machine, which contains the database server.
Port Passes the TCP port, on which the database server or PostgreSQL postmaster listens.
Username Passes a valid database username.
Password Passes a valid database password.
Row buffer size Passes an integer, which represents the number of rows that the driver will return during an individual fetch.
Hide login dialog Enables or disables the login popup box.
Read only connection Enables or disables READONLY access to the data store.
Database Passes the name of a database or Oracle SID. Progress users should pass the full path to their databases.
Initialization SQL Passes a path to a file containing SQL statements. These statements are issued against the database upon initial connection. InitialSQL scripts usually contain statements, which set ISOLATION levels.
Max rows override Passes an integer, which represents the number of rows that the driver will return during individual fetch operations.
Disable autocommit Enables or disables the driver's autocommit behavior.
Disable rowset size limit Enables or disables rowset size limits. Default rowset size limits are enforced by the cursor library. These limits prevent the driver from consuming all available memory in the event that rowsets are inordinately large.
High cursor sensitivity Enables or disables the row version cache, which is used with dynamic cursors.
Defer Fetching of long data Enables or disables deferred fetching. Deferred fetching causes large, binary objects to be fetched after other data. This enhances performance.

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

  • Figure 1-9 - Database-Specific Single-Tier Parameters & Options*
Parameter Description
Character Set MS SQLServer/Sybase Passes the name of a valid character set.
Enable Microsoft Jet Engine options MS SQLServer/Sybase 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 for use with MS Access client applications.
Language MS SQLServer/Sybase Passes the name of a supported, national language.
Server Type MS SQLServer/Sybase Passes a Database Management System (DBMS) name and version. Choose the closest possible match to your DBMS.
Disable ODBC transactions MySQL /PostgreSQL Disables transaction management. Enforces autocommit for all statements.
Count stored procedures parameters Oracle Insures that number of parameters passed by stored procedures matches the number of parameters expected by SQLProcedures.
Custom catalog views Oracle Promotes efficient processing of Oracle catalog calls such as SQLForeignKey () and SQLPrimaryKeys (). The appropriate odbccat#.sql script must be run before OraCatalogs is enabled. There is one odbccat#.sql script for each Oracle database version.
Net Service Oracle Passes the name of a valid Oracle Net Service.
Net Service name Oracle Passes the name of a valid Oracle Net Service.
OCIPrefetch Memory Oracle Passes an integer value, which represents the amount of memory to use for prefetch operations.
OCIPrefetch Rows Oracle Passes an integer value, which represents the number of rows to prefetch.
Oracle directory Oracle Passes the full path to the Oracle home directory.
Service name/SID Oracle Passes the name of a valid Oracle SID.
Show remarks Oracle Retrieves content of SQLColumns REMARKS field.
Use Oracle 8i release 8.0 Compatible Identification Oracle
User's own tables first in SQLTables Oracle Causes user tables to appear at beginning of SQLTables() table name listing.
  • 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:
macodbc1.jpg