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 "xxkuzzzz.taz", where xx represents the operating system being used)
• "install.sh"

From within the OpenLink base installation directory run the "install.sh" script :

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.

Configuration

UDBC like ODBC is based on the notion of logical references to database backends through the use of Data Source Names, under UDBC these are described as Universal Data Source Names (UDSNs) due to the cross data access standard nature of these Data Source Names (they are usable by OpenLink Drivers for ODBC and JDBC™ ).

The OpenLink Data Access Driver Suite 1.5.5 requires you to manually create UDSNs by manually editing a designated file, and then creating your your UDSNs within this file (the OpenLink installer provides a template Universal Data Source Names file called "udbc.ini" - structured in exactly the same manner as a Windows "INI" configuration file). The OpenLink Data Access Driver Suite 3.2 on the other hand includes a HTML and HTTP based utility called the OpenLink "Web Configurator" that enables you create, configure, and manage UDSNs via any Web Browser.

You identify your UDSN file to UDBC Drivers via the Environment Variable "UDBCINI", if you do not set this variable OpenLink UDBC Drivers will use the template "udbc.ini" file that comes with your UDBC SDK installation. The UDBCINI environment variable is set using the command:

UDBCINI=/usr/openlink/bin/udbc.ini ; export UDBCINI

Note: The above presumes that your OpenLink installation's base directory is: /usr/openlink .

The example below depicts the structure of a UDSN 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 UDBC settings are configured within the "[UDBC]" section of your chosen UDSN file, an extract from this file 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 UDSN templates provided by your OpenLink UDBC SDK installation for your initial connection, as the OpenLink installer sets up the appropriate UDBC environment for you at installation time.

The table below describes each OpenLink UDBC attribute required for making a connection from your UDBC based application to your backend database engine.

UDBC Client to Server Mechanics

When connecting to a database, the application sends the UDBC engine a connect string that contains the necessary parameters to complete the database connection.

When the connect string is empty, or a null pointer, the [Default] section is used for the remaining connect parameters.

When the connect string contains a "DSN=<name>" setting, then the section [name] (case insensitive) will be picked from the "udbc.ini" file in use.

All other settings in the connect string overrule the values in the udbc.ini file when supplied.

Note: the OpenLink "Session Rules" Book will determine the ultimate database destination of your UDBC Driver.

Example UDBC Connect Strings:

"" (empty)

Use the values from the [Default] section. There must be at least a Host= definition in that section.

"DSN=dsn_Oracle7"

Use the values from the [dsn_Oracle7] section.

"DSN=dsn_Oracle7;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 UDBC Application "UDBCTEST"

Your OpenLink UDBC SDK installation contains a sample interactive dynamic SQL application called "udbctest", this application is situated within your OpenLink installation's "udbcsdk/examples" sub-directory.

Then run the application by typing the following command from the command line prompt:

      udbctest or ./udbctest

The application will prompt you for a connect string (assuming we are using the UDSN example depicted above):

         Enter UDBC connect string: DSN=generic_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

Compiling Sample Program

To compile the application type the following command from the command line :

      make -f udbctest.mk

Developing UDBC Applications

This UDBC SDK only implements an interface for the 'C' programming language.

To write an UDBC application,you must perform the following tasks::

a. include the file "libudbc.h" in your 'C' program(s)

b. link the application with the "libudbc.a" and the "librpc.a" libraries.

Note: Some UNIX systems also need -lsocket, -lnsl_s or both.

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