TOC Previous Next Index   Easysoft Homepage
       

Interfacing


Preparing to write applications for the Easysoft ODBC-ODBC Bridge

This chapter shows you how to begin utilising the Easysoft ODBC-ODBC bridge in your own applications. The distribution comes with several example programs which can be found in the examples directory. These can serve as a tutorial to get you started writing OOB client applications. The C examples can be compiled and run like any C program, but for the others you need to rebuild the interpreter or compiler with the OOB. Examples shown were executed under Linux, and serve as a guide for all unix platforms. Windows developers should refer to the manual for their chosen development platform.


Chapter Guide

· A Simple OOB Client in C
· Apache/PHP
· Perl DBI DBD::ODBC
· mxODBC
· Rexx/SQL

A Simple OOB Client in C

In The Demo Client, you compiled and/or ran a simple C program that connected through the OOB. Other small programs are provided in the examples directory, and documented in the file EXAMPLES. One of these is getdata, a simple C program that reads stdin for some SQL and passes it to a datasource for execution.

Before you can use the program you must edit the call to SQLDriverConnect() to indicate a valid DSN. You can then make the program, following the instructions on This Link.

This program, the source to the demo program, and the Makefile are enough to show you how to create C programs that connect through the OOB. If you need to know more, you should refer to an ODBC Programmer's Manual.


Apache/PHP

Building Apache with PHP and the OOB allows your web content to be closely integrated with a database running on a separate machine to your web server. This is particularly useful because many offices have MS Access databases that would benefit from up-to-date information from the webserver, but the web server will typically be a linux box running Apache.

NB
Please read the INSTALL files in the PHP and Apache distributions before following these instructions as they may provide more up-to-date information specific to Apache and PHP.

Building PHP with Apache and OOB approximately follows this sequence (subject to changes due to the PHP or Apache distributions).

1. Download Apache.
2. Dowload PHP.

NB
Apache can be found at http://www.apache.org, and PHP at http://www.php.net.


3. Refer to the instructions in the INSTALL files in each distribution.

The PHP INSTALL file gives step-by-step instructions for building PHP with the mysql database.

To build PHP with the Easysoft ODBC-ODBC Bridge you must define the environment variable CUSTOM_ODBC_LIBS:

# CUSTOM_ODBC_LIBS="-lesoobclient"

# export CUSTOM_ODBC_LIBS

Next, follow the PHP installation instructions replacing --with-mysql with --with-custom-odbc=InstallDir/easysoft/oob/client.

(InstallDir is the OOB installation directory, not PHP's!)

4. When configuring Apache you need to define the environment variable LDFLAGS:

# LDFLAGS="-L/base_oob_install_dir/oob/easysoft/client"

# export LDFLAGS

...then follow the Apache installation instructions.

Caution!
Currently, OOB shared objects are not built with a dynamic linker run path so if you are on a Unix machine (except linux) you need to set
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:InstallDir/easysoft/oob/client:InstallDir/easysoft/lib
...and export it before building or running Apache. InstallDir refers to the OOB installation directory (usually /usr/local/).

More information can be foud in the file InstallDir/doc/Apache_PHP.


Perl DBI DBD::ODBC

This section shows how to build Perl DBI with the DBD::ODBC module and connect to the Easysoft ODBC-ODBC Bridge client. It assumes that you have Perl and the Perl modules DBI and DBD::ODBC. These may be obtained from your nearest CPAN archive.

NB
If you are building DBD::ODBC version 0.20 then you must apply a patch (supplied with OOB in the extras subdirectory) to the file Makefile.PL. If you do not have the patch command then you need to apply the changes by hand. To do this, look for lines in the patch file beginning with +. Insert these lines in Makefile.PL.

Driver Managers

The DBD::ODBC 0.21 distribution contains the iODBC driver manager and the OOB will work with this driver manager. However, if you wish to use a driver manager then Easysoft recommend the unixODBC driver manager. Easysoft have close links with the unixODBC project -- the project is now maintained by an Easysoft developer. This brings the following benefits:

Building Perl DBI, DBD:ODBC with OOB

1. Unpack DBI and build as per the instructions in the README file in the Perl DBI distribution.
2. Install DBI.
3. Unpack DBD-ODBC version 2.1 or later. Earlier versions can be made to work, with a patch. Consult the files in the easysoft/oob/docs directory for more information.
4. If you are using a driver manager, refer to the documentation for that driver manager and set up a Data Source Name (DSN) for the OOB client.
– OR –

If you are not using a driver manager, you must create an odbc.ini file for the client. In this file go all the DSN attributes for the OOB Bridge DSN.

5. Read the README accompanying the DBD:ODBC distribution. You must define and export the following environment variables to execute the test:
Name
Description
ODBCHOME The installation directory of the OOB client: /usr/local/easysoft/oob/client or the directory where your driver manager was installed
DBI_DSN The DBI data source, e.g. dbi:ODBC:MYDSN
DBI_USER The username to use to connect to the database, if required
DBI_PASS The password to use to connect to the database, if required

NB
By default, the ODBC-ODBC Bridge is installed in /usr/local/easysoft and the OOB client is in the subdirectory oob/client. For the default installation, ODBCHOME=/usr/local/easysoft/oob/client. The value for DBI_DSN depends on the datasource you have set in the odbc.ini file.


6. Type:

$ perl Makefile.PL

You may get some warnings of the form:

Warning: LD_LIBRARY_PATH

... which you should ignore for now.

$ make

...

$ make test

7. You may get errors like:

install_driver(ODBC) failed: Can't load 'blib/arch/auto/DBD/ODBC/ODBC.so

This generally means that the Easysoft ODBC-ODBC Bridge client shared object cannot be found by the dynamic linker.

If you get errors like this you should ensure the path to libesoobclient.so is on the dynamic linker search path. The method for doing this depends on the OS you are running but often means adding a path to the environment variables LD_LIBRARY_PATH or LD_RUN_PATH. In linux you should normally add the path to the file /etc/ld.so.conf and run ldconfig. Try make test again.

8. You can check the server is responding using telnet.

$ telnet server port

... where server and port are as specified in the odbc.ini file (or driver manager DSN). You should receive a string like the following (though it will differ from server to server):

87FA9694x1:0:1998-1112-0000000001+01:NT^02:4.0.1381^03:Intel^04:4^05:^06:<99> p^

Once any problems with the server or the connection are resolved, any further problems should be easily identified by the ODBC error message output.

NB
The Perl tests are somewhat dependent on the ODBC database and driver you are using on the remote machine, for example, the MS Access ODBC driver does not have SQLDescribeParam().
This also impacts upon attempting to use perl bound parameters across the OOB to MS Access.

9. Once the tests succeed you can install Perl DBI:ODBC with:

$ make install

Once Perl DBI:ODBC is installed, you can try the example files in the examples directory of the OOB install tree. There are also examples given in the Perl DBD::ODBC distribution but beware that at the time of writing, some of these were quite out of date, so they are liable to fail when there is nothing really wrong with your installation or build.


mxODBC

mxODBC is a database API for the Python scripting language which provides an interface to ODBC datasources. The Easysoft ODBC-ODBC Bridge (OOB) has been tested with mxODBC-1.0.1 and mxODBC-pre1.0.2 with Python-1.5.1.

When building mxODBC, there is a configuration section specifically for OOB which makes the build very straightforward. You should refer to the web page below and follow the installation instructions.

REF
mxODBC and instructions for building it are available at http://starship.skyport.net/~lemburg/mxODBC.html.


Rexx/SQL

Rexx/SQL provides Rexx programmers with a consistent, simple and powerful interface to SQL databases. This section explains how to build Rexx/SQL with ODBC support provided by the Easysoft ODBC-ODBC Bridge and shows you how to connect a small test program.

This section assumes that you have an OOB service running with a test database on a remote machine, and that you have a local DSN set up for an OOB connection to a test database. Refer to Connecting to the Bridge Client in Unix

REF
The Rexx/SQL home page contains download links, documentation, mailing list instructions and links to other Rexx resources.
The URL for Rexx/SQL's World Wide Web home page is http://www.lightlink.com/hessling/.
The Rexx/SQL anonymous ftp site is mirrored in the US at ftp://ftp.lightlink.com/pub/hessling/REXXSQL.
Easysoft used the Rexx interpreter `Regina' to test the ODBC-ODBC Bridge with Rexx/SQL. Regina is available at ftp://ftp.lightlink.com/pub/hessling/Regina/.

to set up a local DSN.

Building Rexx/SQL with OOB

You will need a Rexx interpreter (such as Regina -- see above reference) to run the Rexx/SQL test code and your Rexx programs using Rexx/SQL. You may use ./configure --help in Rexx/SQL to see which Rexx interpreters are supported.

These instructions assume you are building from a source distribution of Rexx/SQL. You must have already installed the ODBC-ODBC Bridge before building Rexx/SQL. This is essential as Rexx/SQL needs an ODBC driver to compile and link with. Make a note of the installation path used when OOB was installed as you will need it when building Rexx/SQL.

1. Unpack the Rexx/SQL distribution.

NB
Read the INSTALL files in Rexx/SQL and OOB distributions. There is also a FAQ distributed with the OOB if you need further assistance.


2. Unpack Rexx/SQL and run

$ ./configure --help

...to locate the option required for your Rexx interpreter. For instance, with Regina you would use --with-regina. Depending on your interpreter you may need to add extra configure options.

3. You need to pass configure a minimum of:
(where clientpath is the location of the OOB library and header files,) and

If you installed the OOB in the default directory and are using Regina as the Rexx interpreter you might configure Rexx/SQL with:

$ ./configure --with-regina --with-easysoft-oob --with-dbincdir=/usr/local/easysoft/oob/client/include --with-dblibdir=/usr/local/easysoft/oob/client

4. Once Rexx/SQL is configured type

$ make all

...to build it.

5. You should then consult the section of the Rexx/SQL INSTALL file entitled "Testing the Installation".

To perform the tests in this section you need to define an OOB Data Source local to the machine where the OOB client and Rexx/SQL are installed.

To do this you must create an odbc.ini file containing the datasource (see DSN_definition.txt in the OOB distribution).

Once you have defined the local datasource you can try the Rexx/SQL tests, e.g:

$ ./rexxsql user=db_user pass=db_passwd data=rexx_sql_test

Running this against MS SQLServer you should see something like this:

Rexx/SQL Version: rexxsql 2.4 21 Jul 1999 UNIX ESOOB

Database Name: Microsoft_SQL_Server

Database Version: 07.00.0255

Disconnect succeeded!

Rexx/SQL contains other test code such as samples/tester.cmd.

You can run this by defining and exporting the following environment variables:

Name

Description

REXXSQL_DATABASE The ODBC data source name
REXXSQL_USERNAME The username to use to connect to the database, if required
REXXSQL_PASSWORD The password to use to connect to the database, if required

$ ./rexxsql samples/tester.cmd setup

$ ./rexxsql samples/tester.cmd

The setup argument creates the necessary tables for the test routine. Then run the same command without the setup argument. The tester program exercises Rexx/SQL and the OOB more thoroughly.

[Top] | [Contents] | [Previous] | [Next] | [Index]

Easysoft Ltd. Easysoft - The Home of Data Access
Easysoft Ltd.