| sioc:content
| - ---+ ODBC and Mac OS X a/k/a macOS
%TOC%
---+++ 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 | <nop>OpenLink's Darwin client installer provides the iODBC driver manager. Users may also encounter unixODBC, mac:ODBC, and other driver managers.|
| Mac Classic a/k/a Mac OS 9 | <nop>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 OS X | <nop>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.
<img src="%ATTACHURLPATH%/Macfig1.jpg" alt="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.
<img src="%ATTACHURLPATH%/Macfig2.jpg" alt="Macfig2.jpg">
---+++ <nop>OpenLink ODBC Driver Architecture
<nop>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* |
| <code>CLASSPATH</code> | Passes the full path to <nop>OpenLink's Java archive (.jar) files. These files comprise the <nop>OpenLink JDBC client. This variable is not required for ODBC connectivity.|
| <code><nowiki>LD_LIBRARY_PATH</nowiki></code> | Passes the full path to various library directories on Darwin computers. This variable must include the <nop>OpenLink /lib sub-directory.|
| <code>ODBCINI</code> | Passes the full path to the odbc.ini file, which resides in the <nop>OpenLink /bin sub-directory.|
| <code>ODBCINSTINI</code> | Passes the full path to the odbcinst.ini file, which resides in the <nop>OpenLink /bin sub-directory.|
| <code>OPENLINKINI</code> | Passes the full path to the openlink.ini file, which resides in the <nop>OpenLink /bin sub-directory.|
| <code>PATH</code> | Passes the full path to directories, which contain executables. This variable must include the <nop>OpenLink /bin sub-directory.|
---++++Setting Environment Variables on Darwin
<nop>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 <nop>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:
<verbatim>
export ODBCINI=/usr/openlink/bin/odbc.ini
</verbatim>
Users may also add the variables to their .profiles to insure that the
variables are set at login to their client systems.
---++++ Client Libraries
<nop>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 <code>/lib</code> sub-directory of the <nop>OpenLink client
installation. Click here to see a complete list of <nop>OpenLink libraries by
platform.
| *Filename* | *Description* |
| <code>libiodbc.la</code> | Static, iODBC driver manager library |
| <code>libiodbc.so</code> | Shared, iODBC driver manager library. Older, iODBC driver manager libraries are linked to the latest revision |
| <code>libiodbc.so.2</code> | Revised, iODBC driver manager library. Older, iODBC driver manager libraries are linked to the latest revision |
| <code>libiodbc.so.2.1.2</code> | Revised, iODBC driver manager library. Older, iODBC driver manager libraries are linked to the latest revision |
| <code>mys3_st_lt.la</code> | Static, single-threaded <nop>MySQL Single-Tier driver |
| <code>mys3_st_lt.so</code> | Shared, single-threaded <nop>MySQL Single-Tier driver |
| <code>oplodbc.la</code> | Static, Multi-Tier ODBC driver |
| <code>oplodbc.so</code> | Shared, Multi-Tier ODBC driver. Older, Multi-Tier ODBC driver library files are linked to the latest revision |
| <code>oplodbc.so.1</code> | Revised, Multi-Tier ODBC driver library. Older, Multi-Tier ODBC driver library files are linked to the latest revision |
| <code>oplodbc.so.1.0.0</code> | Revised, Multi-Tier ODBC driver library. Older, Multi-Tier ODBC driver library files are linked to the latest revision |
| <code>ora81_st_lt.la</code> | Static, single-threaded Oracle 8.1.x Single-Tier driver |
| <code>ora81_st_lt.so</code> | Shared, single-threaded Oracle 8.1.x Single-Tier driver |
| <code>pgr7_mt_lt.la</code> | Static, multi-threaded <nop>PostgreSQL Single-Tier driver |
| <code>pgr7_mt_lt.so</code> | Shared, multi-threaded <nop>PostgreSQL Single-Tier driver |
| <code>pgr7_st_lt.la</code> | Static, single-threaded <nop>PostgreSQL Single-Tier driver |
| <code>pgr7_st_lt.so</code> | Shared, single-threaded <nop>PostgreSQL Single-Tier driver |
| <code>sql_st_lt.la</code> | Static, single-threaded MS SQLServer Single-Tier driver |
| <code>sql_st_lt.so</code> | Shared, single-threaded MS SQLServer Single-Tier driver |
| <code>syb12_st_lt.la</code> | Static, single-threaded Sybase Single-Tier driver |
| <code>syb12_st_lt.so</code> | Shared, single-threaded Sybase Single-Tier driver |
---++++ Header Files
<nop>OpenLink Software provides a separate iODBC SDK product installer for Mac
Classic and Mac OS X platforms. These installers contain the <code>sql.h</code>,
<code>sqlext.h</code>, and <code>sqltypes.h</code> header files. Developers may use these files to
build ODBC-compliant applications.
---++++ Configuration Files
<nop>OpenLink's Darwin-based Single-Tier drivers use the <code>openlink.ini</code> file to
obtain database-specific environment variable settings. The <code>openlink.ini</code>
file resides in the <code>/bin</code> sub-directory of Single-Tier client installations.
<nop>OpenLink's Multi-Tier brokers read the <code>oplrqb.ini</code> file to resolve ODBC
connection requests and to enforce <nop>OpenLink's sophisticated, rule-based
security. The <code>oplrqb.ini</code> file resides in the <code>/bin</code> sub-directory of
<nop>OpenLink's server components installations.
---++++ Administrative Assistants
<nop>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.
<nop>OpenLink Software also produces the independent, HTTP-based iODBC Data
Sources Administrator. This web-based GUI enables users to create and
administer <nop>OpenLink and non-<nop>OpenLink ODBC data source names using one,
user-friendly interface.
---++++ Server Components
<nop>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 <nop>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 <nop>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 <code>odbc.ini</code> file using
<tt>vi</tt> 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 <nop>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:
<verbatim>
[ODBC Data Sources]
data_source_name=ODBC_client_driver_name
</verbatim>
Here is a sample ODBC Data Sources section with data source names:
<verbatim>
[ODBC Data Sources]
ora81_lite = OpenLink Oracle 8.1 Lite Driver (multi threaded)
pgr7_lite = OpenLink PostgreSQL Lite Driver (multi threaded)
</verbatim>
---++++ 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 <nop>OpenLink data
source specification format:
<verbatim>
[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
</verbatim>
Here is a sample data source specification:
<verbatim>
[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
</verbatim>
The following table explains the parameters that appear in the data source
specification sections.
| *Parameter* | *Description* |
| <code>[Data Source Name]</code> | Passes a descriptive data source title. This title must match the title passed under the <code>[ODBC Data Sources]</code> heading. |
| <code>Driver</code> | Passes the full path to the ODBC client driver. |
| <code><nop>ServerType</code> | Passes a valid <nop>OpenLink domain alias. This domain alias must match a valid domain alias in the Single-Tier <code>openlink.ini</code> file or Multi-Tier <code>oplrqb.ini</code> file. The drivers use these domain aliases as starting points from which to assess rules, environment variables, and agent binaries to instantiate for connections.|
| <code>Username</code> | Passes a valid database username. If the Multi-Tier <code>OPSYSLOGIN</code> parameter is enabled, this parameter passes a valid operating system username.|
| <code>Password</code> | Passes a valid database password. If the Multi-Tier <code>OPSYSLOGIN</code> parameter is enabled, this parameter passes a valid operating system password.|
| <code>Database</code> | Passes the name of a database or Oracle SID. Progress users should pass the full path to their databases. |
| <code>Options</code> | 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. |
| <code><nop>FetchBufferSize</code> | Passes an integer, which represents the number of rows that the driver will return during an individual fetch. |
| <code><nop>ReadOnly</code> | Passes a <code>Yes</code> or <code>No</code> value to enable or disable <code>READONLY</code> access to the data store. |
| <code><nop>DeferLongFetch</code> | Passes a <code>Yes</code> or <code>No</code> value to enable or disable deferred fetching. Deferred fetching causes large, binary objects to be fetched after other, smaller data. This enhances performance. |
| <code><nop>JetFix</code> | Passes a <code>Yes</code> or <code>No</code> value to enable or disable <nop>JetFix. <nop>JetFix facilitates translation of data types by Microsoft's Jet Engine. This feature is intended primarily for use with Microsoft client applications on Windows. |
| <code>Description</code> | 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* |
| <code>Protocol</code> | Passes a valid <nop>OpenLink network protocol. The default is TCP/IP.|
| <code>Hostname</code> | Passes the hostname or IP address of the machine, which contains the <nop>OpenLink request broker.|
| <code>Port</code> | Passes the TCP port on which the request broker listens. This TCP port is associated with the <code><nop>ListenPort</code> parameter, and it appears in the <code>[Protocol TCP]</code> section of the Multi-Tier Rules Book (<code>oplrqb.ini</code>).|
<nop>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 <nop>OpenLink and
non-<nop>OpenLink data source names.
Use the following instructions to create data source names with the iODBC
Data Sources Administrator.
* cd into the <code>/bin/w3config</code> sub-directory of the client's <nop>OpenLink installation.
* Use a text editor to open the <code>www_sv.ini</code> file.
* Locate the <code>[Startup]</code> section.
* Record the value passed to <code><nop>HttpPort</code>. For example:
<verbatim>
[Startup]
HttpPort = 8000
</verbatim>
* Exit the file.
* cd into the <code>/bin</code> sub-directory of the client's <nop>OpenLink installation.
* Run the following command:
<verbatim>
./iodbc-admin-httpd.sh start
</verbatim>
* Open a Web browser.
* Enter the following URL: <code><nowiki>http://localhost:HttpPort_from_www_sv.ini</nowiki></code>
* 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 <nop>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* |
| <code>Name</code> | Passes a descriptive data source title.|
| <code>Comment</code> | Passes a description of the use or nature of the data source name.|
| <code>Database Name</code> | Passes the name of a database or Oracle SID. Progress users should pass the full path to their databases.|
| <code>Server</code> | 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.|
| <code>Username</code> | Passes a valid database username. If the Multi-Tier OPSYSLOGIN parameter is enabled, this parameter passes a valid operating system username.|
| <code>Read-only connection</code> | Passes a Yes or No value to enable or disable READONLY access to the data store.|
| <code>No Login Dialog Box</code> | Enables or disables the login popup box.|
| <code>Defer Fetching of long data</code> | 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.|
| <code>Row buffer size</code> | Passes an integer, which represents the number of rows that the driver will return during an individual fetch operation.|
| <code>Jet Fix</code> | Passes a Yes or No value to enable or disable <nop>JetFix. <nop>JetFix facilitates translation of data types by Microsoft's Jet Engine. This feature is intended for use with MS Access client applications.|
| <code>Environment</code> | Passes a valid <nop>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 <nop>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 <nop>OpenLink request broker.|
| Port| Passes the TCP port, on which the request broker listens. This TCP port is associated with the <nop>ListenPort parameter, and it appears in the [Protocol TCP] section of the Multi-Tier Rules Book (oplrqb.ini).|
| Protocol| Passes a valid <nop>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
<nop>OpenLink produces the Multi-Tier Administrative Assistant for all server
operating systems, which it supports. This Web-based assistant is powered
by <nop>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 <nop>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 <nop>OpenLink installation.
* Use a text editor to open the www_sv.ini file.
* Locate the [Startup] section.
* Record the value passed to <nop>HttpPort. For example:
<verbatim>
[Startup]
HttpPort = 8000
</verbatim>
* Exit the file.
* cd into the /bin sub-directory of the server's <nop>OpenLink installation.
* Run the following command:
oplrqb
* Open a Web browser.
* Enter the following URL:
<verbatim>
http://localhost:HttpPort_from_www_sv.ini
</verbatim>
* 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 <nop>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 <nop>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 <nop>OpenLink request broker.|
| Port| Passes the TCP port, on which the request broker listens. This TCP port is associated with the <nop>ListenPort parameter, and it appears in the [Protocol TCP] section of the Multi-Tier Rules Book (oplrqb.ini).|
| Protocol| Passes a valid <nop>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
<nop>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 <nop>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 <nop>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 <nop>OpenLink request broker.|
| Port| Passes the TCP port, on which the request broker listens. This TCP port is associated with the <nop>ListenPort parameter, and it appears in the [Protocol TCP] section of the Multi-Tier Rules Book (oplrqb.ini).|
| Protocol| Passes a valid <nop>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
<nop>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 <nop>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:
<verbatim>
[ODBC Data Sources]
data_source_name=ODBC_client_driver_name
</verbatim>
Here is a sample ODBC Data Sources section with data source names:
<verbatim>
[ODBC Data Sources]
ora81_lite = OpenLink Oracle 8.1 Lite Driver (multi threaded)
pgr7_lite = OpenLink PostgreSQL Lite Driver (multi threaded)
</verbatim>
---++++ 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 <nop>OpenLink Multi-Tier
data source specification format:
<verbatim>
[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
</verbatim>
Here is a sample, Multi-Tier data source specification:
<verbatim>
[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
</verbatim>
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 <nop>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 <nop>OpenLink request broker.|
| Port| Passes the TCP port, on which the request broker listens. This TCP port is associated with the <nop>ListenPort parameter, and it appears in the [Protocol TCP] section of the Multi-Tier Rules Book (oplrqb.ini).|
| Protocol| Passes a valid <nop>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 <nop>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:
<verbatim>
[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
</verbatim>
Here is a sample, Single-Tier data source specification:
<verbatim>
[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
</verbatim>
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.|
| <nop>FetchBufferSize| Passes an integer, which represents the number of rows that the driver will return during individual fetch operations.|
| <nop>InitialSQL| Passes a path to a file containing SQL statements. These statements are issued against the database upon initial connection. <nop>InitialSQL scripts usually contain statements, which set ISOLATION levels.|
| Username| Passes a valid database username.|
| Password| Passes a valid database password|
| <nop>MaxRows| Passes an integer, which limits the maximum number of rows that may be returned.|
| <nop>NoAutoCommit| Passes a Yes or No value, which enables or disables the driver's autocommit behaviour.|
| <nop>NoLoginBox| Passes a Yes or No value to disable or enable the login pop-up box.|
| <nop>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.|
| <nop>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.|
| <nop>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 SQL Server 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.|
| <nop>SQLServerCatalog| Passes Yes to use Microsoft SQLServer implementation of catalog calls. Passes No to use Sybase implementation.|
--+++++ <nop>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* |
| <nop>OraCatalogs| Promotes efficient processing of Oracle catalog calls such as <nop>SQLForeignKey() and <nop>SQLPrimaryKeys(). The appropriate odbccat#.sql script must be run before <nop>OraCatalogs is enabled. There is one odbccat#.sql script for each Oracle database version.|
| <nop>ShowRemarks| Retrieves contents of SQLColumns REMARKS field.|
| <nop>UserTblsFirst| Causes user tables to appear at beginning of SQLTables() table name listing.|
| <nop>CountProcParms| Insures that number of parameters passed by stored procedures matches the number of parameters expected by SQLProcedures.|
| <nop>OCIPrefetchRows| Passes an integer value, which represents the number of rows to prefetch.|
| <nop>OCIPrefetchMemory| Passes an integer value, which represents the amount of memory to use for prefetch operations.|
| <nop>OracleDirectory| Passes the full path to the Oracle home directory.|
--+++++ <nop>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 <nop>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 <nop>OpenLink Software's driver installers.
Users will find the iODBC Administrator's icon in their /Applications
folder. This administrator is an <nop>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 <nop>OpenLink data
sources using any ODBC administrator.
* Open the appropriate administrator.
* Click on the System, User, or File tab.
* Click Add.
* Select the appropriate <nop>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.|
| <nop>Cursor_Sensitivity| Passes a Yes or No value to enable or disable the row version cache, which is used with dynamic cursors.|
| <nop>FetchBufferSize| Passes an integer, which represents the number of rows that the driver will return during individual fetch operations.|
| <nop>InitialSQL| Passes a path to a file containing SQL statements. These statements are issued against the database upon initial connection. <nop>InitialSQL scripts usually contain statements, which set ISOLATION levels.|
| Username| Passes a valid database username.|
| Password| Passes a valid database password|
| <nop>MaxRows| Passes an integer, which limits the maximum number of rows that may be returned.|
| <nop>NoAutoCommit| Passes a Yes or No value, which enables or disables the driver's autocommit behaviour.|
| <nop>NoLoginBox| Passes a Yes or No value to disable or enable the login pop-up box.|
| <nop>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.|
| <nop>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.|
| <nop>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 <nop>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. <nop>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 <nop>JetFix. <nop>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| <nop>MySQL/<nop>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 <nop>SQLForeignKey() and <nop>SQLPrimaryKeys(). The appropriate odbccat#.sql script must be run before <nop>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
<nop>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, <nop>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, <nop>OpenLink's SDK's enable developers to build Classic, Carbon, and
Cocoa native applications. Furthermore, <nop>OpenLink's SDK's assist developers
who need to migrate applications from the Classic API to Carbon. And,
<nop>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 <nop>OpenLink's iODBC libraries. The resulting binary
issues calls to the iODBC CFM Bridge. This bridge ships with <nop>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:
<img src="%ATTACHURLPATH%/macodbc1.jpg" alt="macodbc1.jpg">
---+++ <nop>OpenLink Driver Objectives
<nop>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.
<nop>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
---+++ <nop>OpenLink Driver Features
<nop>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, <nop>MySQL, Oracle, <nop>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. <nop>OpenLink's drivers for Microsoft SQL Server and Sybase are an exception. These drivers contain <nop>FreeTDS libraries, which enable <nop>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-<nop>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 <nop>OpenLink client components
* Enforcement of database engine ISOLATION LEVELS across all <nop>OpenLink client components.
|
![[cxml]](/fct/images/cxml_doc.png)
![[csv]](/fct/images/csv_doc.png)
RDF
![[text]](/fct/images/ntriples_doc.png)
![[turtle]](/fct/images/n3turtle_doc.png)
![[ld+json]](/fct/images/jsonld_doc.png)
![[rdf+json]](/fct/images/json_doc.png)
![[rdf+xml]](/fct/images/xml_doc.png)
ODATA
![[atom+xml]](/fct/images/atom_doc.png)
![[html]](/fct/images/html_doc.png)
About
![[RDF Data]](/fct/images/sw-rdf-blue.png)
