UDBC Client Components For UNIX

Introduction
Installation
Configuration

Wizard Based Data Source Management
Forms Based Data Source Management
UDBC Driver Session Settings

Sample Application

Introduction

UDBC stands for Universal Database Connectivity, it is a data access API implementation from OpenLink Software that conforms to the X/Open SQL CLI specification. Unlike the Open Database Connectivity (ODBC) specification UDBC does not include a separate Driver Manager Component, instead it provides you with direct connectivity to backend databases. In some quarters UDBC is actually seen as a Generic Native API to backend databases that adhere to the X/open SQL CLI specification.

ODBC and UDBC share identical APIs, thus applications that are written to either specification are guaranteed a high degree of compatibility.

The UDBC Client Components for UNIX comprise the following :

• Generic UDBC Driver - A shared library (the file "libudbc.so") that provides database connectivity and data access services to UDBC based clients (these are applications written using the UDBC SDK)
  
• Sample UDBC Application - A simple program that can be used to verify your UDBC installation and working environment.

Installation

The OpenLink UDBC Client Components for UNIX are contained within the compressed TAR archive file you downloaded. This file is automatically presented to you via the OpenLink Software Download wizard when you enter UNIX as your client operating system.

The steps that follow describe the installation process:

1. 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 "xxbrzzzz.taz", where xx represents the operating system choice)
• "install.sh"

Configuration

The main configuration activity involves setting up logical references to the actual backend database engines that you wish to access via your UNIX based UDBC Driver. These local references are called Universal Data Source Names (UDSNs) and they are responsible for linking UDBC clients with actual OpenLink Data Access Drivers.

The OpenLink Admin Assistant is a Server Based HTML utility that enables you to manage UDSNs via your Web Browser. This utility provides wizards and a forms based user interfaces for performing its tasks.

Setting Up UDBC Data Sources

In the sections that follow, a step-by guide and illustrative screen shots are used to demonstrate both approaches to setting up UDSNs.

In the examples below lets presume that we are trying to create a UNIX based UDSN that will connect us to a Microsoft SQL Database on a Windows 95/98/NT/2000 Server. The critical database connection and network information for this setup (aka connection attributes) are as follows:

Network alias of Windows 95/98/NT/2000 machine running your OpenLink Server components: ntappserver

Network Alias of Server machine running Microsoft SQL Server (also the machine on to which you have installed the OpenLink Server Components for Windows NT): pluto

Microsoft SQL Server Database Name: pubs

Wizard Based Data Source Name Management

1. Open up your Internet Browser and then enter the following URL: http://localhost:8000/ (note the OpenLink Web Assistant listens at port 8000 by default, this value is set at installation time). Click on the "Client Components Administration" hyperlink to expand this menu option further, then "Data Source Name Configuration" then click on the "Edit Data Sources by Wizard". Now Click the "Edit UDBC Data Sources" hyperlink.
   
   
   
   
   
   
2. You will be presented with the actual UDBC Data Source configuration wizard. Click the "Add" button.
   
   
   
   
   
3. Enter values into the "Name" and "Description" fields as follows:
   
   "Name" - enter values that uniquely identify the DSN being created, our example uses the name "SQL Server on NT" to indicate that this DSN will be connecting you to a SQL Server database on an NT server.
   
   "Description" - enter values that provide additional information that helps in describing the purpose of the DSN that you are creating.
   
   Once completed click on the "Next" button.
   
   
   
   
   
4. Enter values into the "Domain Type", "Hostname", and "Server Options" fields as follows:
   
   "Domain Type" - enter a value that identifies the type of OpenLink Agent that will serve your UDBC client.
   
   "Hostname" - enter a value that identifies the server machine running your OpenLink Server Components.
   
   "Server Options" field - This field is only relevant when connecting to a "Progress" agent, this holds Progress session startup parameters such as -TM, -TB, -e, -l etc... You rarely need to enter these values on the client as they are best managed on the server within the OpenLink Session Rules Book.
   
   
   
   
   
5. Enter values into the "Database Name", "Database Server", and "User ID" fields as follows:
   
   "Database Name" - enter the name of an actual SQL Server database, in this case our example uses the database "pubs"
   
   "Database Server"- enter database server connection values for the database that your are connecting to, in this case enter valid SQL Server database server connection values (where "-s pluto" represent an actual SQL Server instance currently available on your network).
   
   "User ID" - enter a valid username for the database that you are connecting to, you can leave this blank and be prompted for values at actual database connect time.
   
   Click on the "Next" button.
   
   
   
   
   
6. Enter values into the "Read-only connection" and "Fetch buffer size" fields as follows:
   
   "Read-only connection" - check this box if you require a read only session.
   
   "Fetch Buffer Size" - enter a value that represents the number of records that you would like your UDBC driver to retrieve during each network hop. A network hop represents the number of times your OpenLink UDBC sends a message across the network to retrieve records from your remote database server. The feature can be used to improve UDBC record retrieval performance.
   
   Once completed click on the "Next" button.
   
   
   
   
   
7. You have now completed entering all the values that make up your new UDBC DSN, these values are collectively known as your UDBC DSN Attributes. Click on the "Save" button in order to store these values permanently on your hard disk.
   
   
   
   
   
8. Click on the "Test this DSN" button, this enables you to test and verify usability of the new UDBC DSN that you have created.
   
   
   
   
   
   
9. Click the "Test" button to actually commence the UDBC DSN Test process, you will be presented with dialogs that indicate success or failure at the end of this process.
   
   
   
   
   
10. Click on the "exit" button to exit the UDBC DSN configuration     wizard
    
    

Forms Based Data Source Name Management

The OpenLink Admin assistant also allows the more experienced OpenLink UDBC user to manage UDBC DSNs via a forms based interface. Like the wizard based approach this is done entirely from within your browser. In the sections that follow, a step by guide and illustrative screen shots are used to demonstrate the process of creating the same UDBC DSN created in the prior section using the Wizard approach.

1. Enter the following URL into your Web Browser (if the Admin Assistant isn't already initialized): http://localhost:8000 You will be presented with a screen similar to the one below. Notice that the "Data Source Names(s) Settings" and "Edit Data Sources By Form" hyperlinks have been expanded.
   
   On the right side of the Admin Assistant pane is your start page for configuring UDBC DSNs using the Forms approach. This page presents to you a list of currently configured UDBC DSNs on the machine "localhost" (your UNIX client for this exercise). Click on the "Add" hyperlink to commence the process of creating a new UDBC DSN.
   
   
   
   
   
2. Enter values into the fields presented on the UDBC DSN form as follows:
   
   "Name" - enter values that uniquely identify the DSN being created, our example uses the name "SQL Server on NT" to indicate that this DSN will be connecting you to a SQL Server database on an NT server.
   
   "Description" - enter values that provide additional information that helps in describing the purpose of the DSN that you are creating.
   
   "Read-only connection" - check this box if you require a read only session.
   
   "No Login Dialog Box" - check this box if you do not want to be prompted by your UDBC Driver for username and password dialog box at connect time.
   
   "Type" - enter a value that identifies the type of OpenLink Agent that will serve your UDBC client.
   
   "Hostname" - enter a value that identifies the server machine running your OpenLink Server Components.
   
   "Server Options" field - This field is only relevant when connecting to a "Progress" agent, this holds Progress session startup parameters such as -TM, -TB, -e, -l etc... You rarely need to enter these values on the client as they are best managed on the server within the OpenLink Session Rules Book.
   
   "Database" - enter the name of an actual SQL Server database, in this case our example uses the database "pubs"
   
   "Connect Options" - enter database server connection values for the database that your are connecting to, in this case enter valid SQL Server database server connection values (where "-s pluto" represent an actual SQL Server instance currently available on your network).
   
   "UserName" - enter a valid username for the database that you are connecting to, you can leave this blank and be prompted for values at actual database connect time.
   
   "Fetch Buffer Size" - enter a value that represents the number of records that you would like your UDBC driver to retrieve during each network hop. A network hop represents the number of times your OpenLink UDBC driver sends a message across the network to retrieve records from your remote database server. The feature can be used to improve UDBC record retrieval performance.
   
   Note: The screen shot below is a snapshot of the UDBC DSN for, click on the right-hand scroll bar to see all the fields described above.
   
   
   
   
   
3. Click on the "Add" button at the foot of the page to complete the creation of your new UDBC DSN
   

UDBC Driver Session Settings

A number of configuration session parameters are available to adminstrators of OpenLink UDBC Drivers. These parameters can be managed via the Web Browser based Admin Assistant or by manually editing the file "udbc.ini" situated in the "bin" sub-directory of your OpenLink installation directory. These parameters enable you to tailor the behaviour of your UDBC Drivers for UNIX in line with the requirements of your UDBC based soultions and any general infrastructural requirements that you may have.

The list of configurable session parameters and their descriptions are as follows:

Sample Application

OpenLink also provides a sample UDBC based dynamic SQL application that enables you verify usability of your UDBC installation.The sample application is situated within the "samples" sub-directory below your OpenLink installation directory. The UDBC sample application is called "udbctest".

Using Sample UDBC Application

The following steps guide you through the process of successfully utilising this sample application. This exercise presumes that we are connecting to a UDSN called "SQL Server on NT", which connects us to a remote SQL Server Database hosted on a machine called "pluto" via the OpenLink Server components on an Windows 95/98/NT/2000 application server called "ntappserver"..

1. Ensure that your OpenLink Request Broker is up and running on the machine "ntappserver" (you can quickly confirm this by opening up your browser and entering the following URL:
   
   http://ntappserver:8000/ )
   
   
2. At your UNIX command prompt type in the following command:
   
   udbctest
   
   
3. Enter a full or partial UDBC connect string at the UDBC applications command prompt, some examples are listed below:
   
   - for a list of UDSNs on your system enter "?"
   
   - to connect to the UDSN called "SQL Server on NT" type (this is a partial connect string): 
   
   DSN=SQL Server On NT
   
   - to enter a username and a blank password combination along with the UDSN type (this is a partial connect string only becuase we have a seperate server hosting the OpenLink Server and Microsoft SQL Server components):
   
   DSN=SQL Server on NT;UID=sa;PWD=
   
   - to enter a directive that instructs the OpenLink Server components to connect to the remote SQL Server hosted on the machine called "pluto", type the following (this is a full connect string for this particular scenario):
   
   DSN=SQL Server on NT;UID=sa;PWD=;OPTIONS=-s pluto
   
   
4. If step 4 is successful you are now ready to execute SQL interactively against your remote database, to do this enter the following SQL command:
   
   select * from authors
   
   
5. To quit this application type in "exit" at the SQL command line prompt.