 |
Introduction
Installation
Configuration
Example connect strings
Further Reading
Welcome to the combined release of OpenLink ODBC for Unix
and the free iODBC driver manager. This kit will provide you with everything you need in
order to develop ODBC compliant applications under UNIX.
This kit consists of a number of parts:
- The free iODBC driver manager. This is a complete
implementation of an ODBC driver manager, released under the GNU Library General Public
License (LGPL). See http://www.iodbc.org
for additional information.
- Generic OpenLink ODBC Driver . The driver provided in the
form of a shared library file, with a system-dependent name.
- A sample ODBC application and source code. The sample
application is an Interactive Dynamic SQL Interpreter. You are free to use this
application and source code as you see fit.
Installation of Run-time Distribution
Move the following files to an installation directory of your choice (If such a directory does not exist, please create one):
- Client .taz archive (in the format "xxkozzzz.taz", where xx represents the operating system choice)
- "install.sh"
From within the OpenLink base installation directory run the "install.sh" script using the command:
sh install.sh
This will automatically extract the contents of the .taz file into the following sub-directory structure within your OpenLink base installation directory.
Files contained within the UNIX ODBC SDK
|
The next step is to ensure that your host operating system's shared library PATH variable is set correctly so that the ODBC Driver Manager and OpenLink ODBC Driver shared libraries are locatable by your UNIX based ODBC Application.
Under many UNIX flavors the environment variable
LD_LIBRARY_PATH is used to set the shared library PATH. Please note that older versions of
AIX use the environment variable LIBPATH, while HP-UX requires the environment variable
SHLIB_PATH.
If your system has a 'C' compiler, you can verify the development environment by
re-compiling the "odbctest.c" program. You can also simply run
"odbctest" to test the state of your ODBC under UNIX runtime environment.
Configuration of Run-time Distribution
The iODBC driver manager links iODBC clients to iODBC
Drivers via the iODBC configuration file. This file is typically the file
"~/.odbc.ini" (where the tilde stands for the user's home directory. Your
OpenLink iODBC SDK installation process will place this file in the $HOME directory of the
account user installing the SDK. It will also set the correct references to the Driver
Manager and OpenLink ODBC Driver shared libraries.
Your OpenLink UNIX based ODBC Drivers make use of iODBC Data Source Names (DSNs). These
DSNs are created, configured, and deleted through the OpenLink Admin Assistant. If you so
choose you can also do this manually by editing the ~/.odbc.ini file.
The example below depicts the structure of an iODBC DSN named "dsn_oracle7", used to facilitate connections with an Oracle Database residing on a machine named "mercury".
[dsn_oracle7]
Database = ORCL
UserName = scott
Password = tiger
Host = mercury
ServerType = Oracle 7
FetchBufferSize = 60
Description = Oracle Database Connections
Your general OpenLink ODBC Client for UNIX session settings are held within the
"[UDBC]" section of the file "udbc.ini", this file is situated in the
"bin" sub-directory of your OpenLink Server components installation. An
extract from this file that deals with these settings is depicted below:
[UDBC]
;DebugFile = /tmp/udbc.out ; Write client debugging output
[Communications]
ReceiveTimeout = 120 ; max. time to complete a request
BrokerTimeout = 30 ; max. time to wait for oplrqb
RetryTimeout = 5 ; Retry time for oplrqb locating
SendSize = 4096 ; RPC send buffer size
ReceiveSize = 16000 ; RPC receive buffer size
ShowErrors = Y ; Pass RPC errors to applications
DataEncryption = N ; Encrypt outgoing data
Note: It is highly recommended that you use the iODBC DSN templates provided by your OpenLink ODBC SDK installation for your initial connection, the iODBC SDK installer program sets up the appropriate iODBC environment for you at installation time.
The table below describes each OpenLink iODBC DSN attributes required for making a connection from your ODBC based application to your backend database engine.
| Section and Keys | Default Value | Corresponding Connect String option | Description |
| [UDBC Global] | Global UDBC client communications settings. | ||
| BrokerTimeout | 30 | The time (in secs) that the client application will wait for the request broker (oplrqb) to accept or reject a database connection. | |
| ReceiveTimeout | 60 | The time (in secs) that the client application will wait for a database agent to finish a request. | |
| PortMapTimeout | 30 | When using the ONC portmap or rpcbind name services, this is the time (in secs) that the client application will wait for a reply from the portmapper. | |
| SendSize | 4096 | RPC send buffer size. A value of 0 will cause the application to use the default value. | |
| ReceiveSize | 16000 | RPC receive buffer size. A value of 0 will cause the application to use the default value. | |
| DebugFile | no debugging | When this variable contains a valid filename, the client applications will write debugging information to that file. Do not use this in the systemwide ini file! (/etc/udbc.ini) This file will contain detailed UDBC call tracing. | |
| [DSN_name] | DSN=DSN_name | Name of the Data Source | |
| Host | HOST=name | Name of host to contact (hostname or network address) | |
| ServerType | SVT=type | Specify agent domain This is used by the broker to determine which agent section to connect the client request to using mapping rules. | |
| ServerOptions | Server startup options specific to agent/database. | ||
| Database | DATABASE=db | Database to use. Agent/database specific. | |
| Options | OPTIONS=opts | Database connect options. Agent/database specific. | |
| UserName | UID=username | Username to connect as. | |
| PWD=password | Password for user. | ||
| ReadOnly | READONLY=<y|n> | Specify Y(es) for read-only (ro) or N(o) for read-write (rw) connections. Read only connections are sometimes faster, but can never modify any database. | |
| FetchBufferSize | 5 | FBS=<value> | Number of rows (records) to be fetched per call from database agent. Values range from 1 to 99 |
Example ODBC Connect Strings:
"" (Empty Connect String)
This implies the use of values from the [Default] section of the iODBC configuration file. There must be at least a "Host=" definition in this section.
"DSN=dsn_oracle7"
Use the values from the [dsn_oracle7] section.
"DSN=MyOracle7dsn;UID=scott;PWD=tiger"
Use the values from the [dsn_oracle7] section, and overrides the value for UserName. Also use the password "tiger" to gain access to the database.
"HOST=mercury;SVT=Oracle 7;DATABASE=ORCL;UID=scott/tiger"
Connect to an Oracle 7 database on the machine "mercury" .
"READONLY=Y"
Make a read-only connection to the [Default] database.
The Sample ODBC Application "ODBCTEST"
Your OpenLink UDBC SDK installation contains a sample interactive dynamic SQL application called "odbctest", this application is situated within your OpenLink installation's "odbcsdk/examples" sub-directory.
Then run the application by typing the following command from the command line prompt:
odbctest
The application will prompt you for a connect string (assuming we are using the UDSN example depicted above):
Enter ODBC connect string: DSN=dsn_oracle7
If you connect to the database successfully you will get a SQL prompt:
SQL>
Type a valid SQL statement and then press <return> to send your request to your UDSN
SQL> select * from <table name>
or Use an OpenLink quick table list command:
SQL> tables
If the query returns data and was successful, the data will be scrolled down the screen.
Otherwise you will receive an error message.
Type in "exit" to quit the application
Further Reading:
"Data Management: SQL Call Level Interface (CLI)"
from X/Open in conjunction with SQL Access Group
ISBN: 1-872630-63-4
X/Open Document Number: S203
Microsoft ODBC API documentation
