> # 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:

> - 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.

>   NB | 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 –

> 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:
> - an interpreter option (e.g. `--with-regina`)
> - `--with-easysoft-oob`
> - `--with-dblibdir=`clientpath
> (where clientpath is the location of the OOB library and header files,) and
> - `--with-dbincdir=`clientpath`/include`

> 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 - The Home of Data Access |