![]() |
![]() |
![]() |
![]() |
|||
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 fileEXAMPLES
. One of these isgetdata
, 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 thenmake
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.
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.
Apache can be found at http://www.apache.org, and PHP at http://www.php.net.
3. Refer to the instructions in theINSTALL
files in each distribution.
The PHP
INSTALL
file gives step-by-step instructions for building PHP with themysql
database.To build PHP with the Easysoft ODBC-ODBC Bridge you must define the environment variable
CUSTOM_ODBC_LIBS
:
#
CUSTOM_ODBC_LIBS="-lesoobclient"
4. When configuring Apache you need to define the environment variable
Next, follow the PHP installation instructions replacing
--with-mysql
with--with-custom-odbc=
InstallDir/easysoft/oob/client
.LDFLAGS
:
# LDFLAGS="-L/base_oob_install_dir/oob/easysoft/client"
...then follow the Apache installation instructions.
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.
If you are building DBD::ODBC version 0.20 then you must apply a patch (supplied with OOB in the extras
subdirectory) to the fileMakefile.PL
. If you do not have thepatch
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 inMakefile.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:
- We are able to provide better support for OOB running under unixODBC.
- If you find a problem in unixODBC it is much easier for us to get it fixed.
- At the time of writing, unixODBC supports ODBC 3.5 and is thread-safe whilst this is not true for iODBC.
DBD::ODBC prior to version 0.21 did not require a driver manager, but this changed in version 0.21. You still do not need a driver manager however to use DBD::ODBC with the Easysoft ODBC-ODBC Bridge: The bridge provides the necessary driver manager functionality.
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
5. Read the README accompanying the DBD:ODBC distribution. You must define and export the following environment variables to execute the test:
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.
ODBCHOME
The installation directory of the OOB client: /usr/local/easysoft/oob/client
or the directory where your driver manager was installedDBI_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
By default, the ODBC-ODBC Bridge is installed in /usr/local/easysoft
and the OOB client is in the subdirectoryoob/client
. For the default installation,ODBCHOME
=/usr/local/easysoft/oob/client
. The value forDBI_DSN
depends on the datasource you have set in theodbc.ini
file.
6. Type:
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
8. You can check the server is responding usinglibesoobclient.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 variablesLD_LIBRARY_PATH
orLD_RUN_PATH
. In linux you should normally add the path to the file/etc/ld.so.conf
and runldconfig
. Trymake test
again.telnet
.
... 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.
9. Once the tests succeed you can install Perl DBI:ODBC with:
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.
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.
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
to set up a local DSN.
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/.
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.
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
3. You need to pass
...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.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:
4. Once Rexx/SQL is configured type
$ ./configure --with-regina --with-easysoft-oob --with-dbincdir=/usr/local/easysoft/oob/client/include --with-dblibdir=/usr/local/easysoft/oob/client
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 (seeDSN_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
Rexx/SQL contains other test code such as
samples/tester.cmd
.You can run this by defining and exporting the following environment variables:
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. Thetester
program exercises Rexx/SQL and the OOB more thoroughly.
Easysoft - The Home of Data Access |
||