This is the Easysoft ODBC-ODBC Bridge FAQ.

List of Questions
-----------------

1. General Questions
 1.1 What is the Easysoft ODBC-ODBC Bridge.
 1.2 What does it do?
 1.3 What versions of ODBC are supported?
 1.4 Where can I get it?
 1.5 What else do I need?
 1.6 Do I need a Driver Manager?
 1.7 How much disk space do I need?
 1.8 What is a DSN?
 1.9 Where do I get information about the ODBC API?
 1.10 What platforms/OS is OOB available for?
 1.11 Where is the latest version of this FAQ?

2. OOB Specific.
 2.1 How do I build my ODBC application with the OOB?
 2.2 How to I set up a DSN?
 2.3 What attributes may be specified in a DSN?
 2.4 How does the OOB locate DSNs.
 2.5 I only want to retrieve data from the server, are there any tricks
     to speed it up in read-only mode?
 2.6 How can I get help on using the OOB?
 2.7 Where do I report bugs in the OOB?
 2.8 How much does a license for OOB cost?
 2.9 When will the final release of OOB be available?
 2.10 When does the beta version expire?
 2.11 What do I do when my beta version of the OOB expires?
 2.12 How do I license OOB?
 2.13 Are there any configurable options for the OOB?
 2.14 How much memory do I need for the OOB Server on NT?
 2.15 Why does it take so long to connect to the server?
 2.16 Why can I see more tables in MS SQLServer than normal?
 2.17 Are any usernames/passwords transmitted as plain text over the network
      connection?
 2.18 Can I strip(1) the shared objects and executables?
 2.19 Can I run the OOB Server on UNIX without the inetd SuperServer?
 2.20 Can I make the OOB statistics web page refresh more/less frequently?
 2.21 Why does the OOB HTTP Server statistics page show active threads
      when there are no connections?
 2.22 Why cannot I login to the HTTP Administrator when running the OOB
      server as a named user instead of in the system account?
 2.23 Is there any tracing in OOB I can use for debugging my application?
 2.24 How do I specify connection attributes for my DSN that are not
      configurable in the odbc.ini?
 2.25 Why does SQLDataSources list a datasource which returns the
      Datasource not found message when I connect to it?
 2.26 How can I encrypt the network connection between the client and server?
 2.27 Does the OOB install for UNIX support xinetd?
 2.28 Do you have to have DNS working for correct operation of OOB?
 2.29 Can multiple machines running the OOB client simultaneously use the
      same OOB Server?
 2.30 How does the OOB client handle refused connections?
 2.31 How does the OOB client support connection timeouts?
 2.32 What does the OOB do if an application terminates abnormally?
 2.33 I have no root access. How do I tell OOB/unixODBC to use odbc.ini
      and odbcinst.ini files not in /etc?
 2.34 Why do I get the error "Not enough attributes for connection" since
      upgrading OOB from a pre 1.0.0.27 release?

3. Trouble Shooting
 3.1 Why do I get connection refused errors from the client?
 3.2 Why do I get connection closed by foreign host messages when I try
     to telnet to the port the server is listening on?
 3.3 Why do my connections to the OOB server seem to be dropped after a while?
 3.4 Why do I get "Data source not found and no default driver" message when
     I am sure I have defined the DSN in my odbc.ini file?
 3.5 Why do I get authorization failures from the client?
 3.6 How do I find out why an ODBC call is failing?
 3.7 Why can't I connect to the data source?

4. Application/Driver-specific
 4.1 How do I use Perl with OOB?
 4.2 What versions of Perl modules can I use with OOB?
 4.3 How do I use Apache/PHP with OOB?
 4.4 What versions of PHP (and Apache) can I use with OOB?
 4.5 Why can't I use bound parameters with MS Access
 4.6 I don't like my odbc.ini in the same directory as my PHP/Perl script
     as people browsing my web site may see it and it contains passwords.
     What do I do?
 4.7 ld: cannot open -lesoobcclient: No such file or directory when
     attempting to link an application with the OOB.
 4.8 Apache/PHP can't seem to find my odbc.ini file or
     Datasource not found and no default driver error.
 4.9 undefined reference to xyz when making Apache/PHP
 4.10 Why do I get undefined symbols when running the Perl DBD::ODBC test?
 4.11 Why don't my PHP scripts appear to run on the web server?
 4.12 How can I put attributes other than the DSN in my Perl DBI->connect call?
 4.13 Why do I get parse errors when compiling PHP with OOB?
 4.14 How do I tell Apache to pass PHP scripts to the PHP interpreter?
 4.15 How can I find out why my PHP script is not working?
 4.16 How can I debug my Perl DBI, DBD::ODBC?
 4.17 Why do I keep getting data truncated errors in my Perl?
 4.18 Where can I find more information about Perl DBI and DBD:ODBC?
 4.19 Why does my second connection to MS Access hang?
 4.20 Why am I having intermittent problems with a particular ODBC driver?
 4.21 Can I use PHP with OOB and driver X?
 4.22 Why doesn't a query return recently inserted data?
 4.23 Why cannot I use multiple active statements?
 4.24 Why does Perl DBD::ODBC appear to open the DEFAULT datasource with OOB?
 4.25 Why do I get corrupted text columns back from MS SQLServer
 4.26 Why does a build of PHP4 RC1 and OOB fail?
 4.27 Why do I get Driver's SQLAllocHandle on SQL_HANDLE_ENV failed with the
      Microsoft Oracle ODBC driver?
 4.28 Why can't I run CGI programs using OOB under
      Netscape Enterprise Server?
 4.29 Why does a query on columns containing colons in the name fails from
      DBD::ODBC?
 4.30 Why do I not get a list of all the tables and columns in a database?
 4.31 Why do I get a transaction already started error calling a procedure?
 4.32 Why do I get ODBC driver authentication denied when using  unixODBC's
      isql and DataManager?
 4.33 Why do I get "IM004, Driver's SQLAllocHandle on SQL_HANDLE_HENV failed"
      connecting to DB2?
 4.34 In PHP, why can I only use/get column names up to 30 characters when
      my database supports much longer column names?
 4.35 Why do my Perl scripts complete but end in a segmentation violation?
 4.36 Why are my connections to MS SQLServer so slow?
 4.37 Why does test 13 of the simple test in Perl DBD::ODBC fail?
 4.38 Why do I get compile warnings in php_odbc.c with OOB 1.0.0.15
 4.39 Why do I get compile errors building Perl DBD::ODBC on AIX?
 4.40 Why is my column data truncated at 4096 bytes from PHP?
 4.41 Do I have to set DBI_DSN, DBI_USER and DBI_PASS  environment variables
      before running my Perl script?
 4.42 Why do I get "undefined symbol: SQLParamData" when testing DBD::ODBC?
 4.43 Why does phpinfo() display "Active Persistent Links" of 0/1 when I
      know there are more open connections to my database?
 4.44 Why don't my changes to PHP odbc settings in php.ini file get picked up?
 4.45 Why doesn't PHP's max_persistent setting limit the total number of
      ODBC connections to my database?
 4.46 I don't want to rebuild Apache for PHP/ODBC support, what can I do?
 4.47 Why does make test for Perl DBD::ODBC fail with "invalid object name"
      errors?
 4.48 Why is my NT OOB Server using alot of CPU, my ODBC connections go to
      MS SQLServer?
 4.49 How do I pass LD_LIBRARY_PATH down to CGI programs from Apache?
 4.50 Why cannot I insert timestamps with sub-millisecond fractions in to
      MS SQL Server datetime field?
 4.51 Why have connection times to MS SQL Server slowed down since upgrading
      to Windows 2000 Server?
 4.52 Why are my output bound parameters from a MS SQL Server procedure
      not retrieved?
 4.53 Why do I get "SQLSetConnectOption err=-2" errors in my Perl scripts

5. Operating System Specific - Linux
 5.1 Which version of OOB should I be using?
 5.2 What Linux kernels can I run?
 5.3 Linker errors building Apache/PHP with OOB
 5.4 Which is best, inetd or standalone startup for the OOB Server?
 5.5 Can I use a multi-threaded application with OOB on Linux and if so how?
 5.6 Why is inetd terminating the OOB Server service?

6. Operating System Specific - Windows
 6.1 What username/password do I need to specify for LogonUser
     and LogonAuth?
 6.2 What do I do if I get an Access Violation or Fault popup window?
 6.3 Does the OOB client support file DSNs?
 6.4 Why does the install hang?
 6.5 Why do I get "Invalid authorization specification" when the LogonUser
     and LogonAuth are set to a valid username and password?
 6.6 Why do I get connection refused/reset under heavy loads
     (Windows OOB server)?
 6.7 How can I check which version of MS MDAC I have?
 6.8 What version of MS MDAC do I need?
 6.9 Where do I get WinSock 2 for Windows 95?
 6.10 Why does OOB install fail with "Setup is unable to locate the layout file"?

7. Operating System Specific - Solaris
 7.1 Why do I get undefined symbol for h_errno?

8. Operating System Specific - OpenBSD
 8.1 Can I use the ODBC-ODBC Bridge for FreeBSD on OpenBSD?

9. Operating System Specific - FreeBSD
 9.1 When linking Perl DBD::ODBC with the OOB on FreeBSD I get errors
     regarding wchar.h what should I do?

10. Programming
 10.1 Can I fork child processes after SQLDriverConnect and use the connection
     handle in each one?
 10.2 Can I use a multi-threaded application with the OOB client?

1. General Questions
--------------------
1.1 What is the Easysoft ODBC-ODBC Bridge
-----------------------------------------

The Easysoft ODBC-ODBC Bridge is database middleware providing access
to a database driver on one machine from another machine on the same
network; e.g. access to MS SQL Server on NT from an application running
on Linux.

1.2 What does it do?
--------------------

The Easysoft ODBC-ODBC comes in two parts, a client and a server.  The
client is a shared object, archive, DLL or shared image containing the
full ODBC 3.5 API. You link your application to the ODBC-ODBC Bridge
client directly or through a driver manager and make ODBC calls. The
ODBC-ODBC Bridge server is installed on a remote machine where you
have a database and an ODBC driver. The ODBC-ODBC Bridge server makes
ODBC calls to the driver e.g. when your application calls
SQLDriverConnect(), the client contacts the server and instructs it to
call SQLDriverConnect() in the ODBC driver for your database (this is
a simplistic view). As far as your application is concerned it is
talking directly to the ODBC driver on the remote machine.

1.3 What versions of ODBC are supported?
----------------------------------------

ODBC 2.0, ODBC 2.5, ODBC 3.0 and ODBC 3.5.

The ODBC-ODBC Bridge has the full ODBC 3.5 API and most of the ODBC
2.0/2.5 API. All the ODBC 2.0 and 2.5 API required to run Perl
DBD:ODBC, PHP and mxODBC is present. However, Easysoft expects new
applications to be written using the ODBC 3.0/3.5 API so this is covered
100%.

1.4 Where can I get it?
-----------------------

http://www.easysoft.com
ftp://ftp.easysoft.com/pub/odbc-odbc-bridge

Beta and pre-release versions of the OOB can be found at:
ftp://ftp.easysoft.com/pub/beta/odbc-odbc-bridge

Please note http://beta.easysoft.com is nolonger actively maintained.

1.5 What else do I need?
------------------------

Presuming you already have a database set up and working on a machine
on your network all you need is an ODBC Driver for that database and
the Easysoft ODBC-ODBC Bridge.

The Windows distributions of OOB contain the Microsoft ODBC driver
manager and ODBC administration interface.

The UNIX distributions of OOB contain the unixODBC driver manager.

If you are using Windows 9x you will need to ensure you have Winsock 2
installed (see later question for where to obtain it).

1.6 Do I need a Driver Manager?
-------------------------------

Strictly speaking the answer to this question is no. However, if you
are accessing MS SQL Server, MS Access etc on a Windows machine the
server side of the ODBC-ODBC Bridge installs the Microsoft Driver
Manager. In part this is to make the configuration of data sources
easier and to allow the ODBC-ODBC Bridge server to pass concern for
which ODBC driver to load on to the driver manager.

The client side of the ODBC-ODBC does not need a driver manager as you
can link your application directly to it. The client contains much of
the driver manager functionality and this is how the ODBC-ODBC Bridge
can support multiple versions of the ODBC API. Typical
applications/interfaces which are already available on non-Windows
platforms are PHP, Perl DBI, DBD:ODBC, mxODBC and Rexx/SQL. When
building the ODBC-ODBC Bridge with any of these you do not need a
driver manager. A similar situation exists if you write your own
application.

Some applications come with a driver manager e.g. Applixware comes
with iODBC.  The ODBC-ODBC Bridge will work just as well with a driver
manager and it is only required if the application is written to
expect and need a driver manager.

If you have multiple ODBC drivers and you want to pick which one you
use at run time then you need a driver manager. Easysoft recommend the
driver manager incorporated in the unixODBC project which can be found
at http://www.unixodbc.org. The OOB distributions for UNIX contain the
unixODBC driver manager. Generally speaking it is a more flexible
configuration if you use a driver manager.

1.7 How much disk space do I need?
---------------------------------

The OOB requires a different amount of disk space for each platform.
As a rough guide:

Windows (2000, NT, 95/98):

  The InstallShield image is between 3-4Mb.  The fully installed OOB
  client, server, documentation and examples requires about 3Mb.

Unix 
  
  Four formats of the distribution are available, tar, gzipped tar,
  bzipped tar and compressed tar. These vary in size between 400K and
  8Mb. The fully installed client, server, documentation and examples
  requires about 1.5Mb and an additional 2Mb for unixODBC.

1.8 What is a DSN?
------------------

A data source name is a logical name for a data repository or
database.  Any attributes that define a data source are stored under
the DSN for retrieval by the driver.

In the case of the OOB, the data source name is the key to a set of
attributes in the odbc.ini or the system information (in
Windows). When the application calls SQLDriverConnect or SQLConnect
with a DSN, the OOB client can look up other attributes it needs for
the connection in the odbc.ini or system information.

1.9 Where do I get information about the ODBC API?
--------------------------------------------------

[1] The Microsoft Press (www.microsoft.com/mspress) books and CD
    Microsoft ODBC 3.0 Software Development Kit and Programmer's Reference.
[2] The Microsoft ODBC 3.0 Programmers Reference Volume 1 and 2
    ISBN 1-57231-516-4.
[3] http://www.microsoft.com/odbc - the Microsoft ODBC SDK.
[4] http://msdn.microsoft.com/library/sdkdoc/sdkstrt/aboutsdk.htm

1.10 What platforms/OS is OOB available for?
--------------------------------------------

OOB is currently available for the following operating systems and
architectures:

OS Name        Architecture OS Versions Variations Notes
-------        ------------ ----------- ---------- -----
Linux          Intel        1.2.n +     libc5      -
                                        glibc      -
                                        glibc-mt   -
Linux          Alpha        2.0.n +     glibc      -
Windows NT     Intel        3.51 +      -          -
Windows 95     Intel        -           -          WinSock 2 required
Windows 98     Intel        -           -          -
Windows 2000   Intel        -           -          -
Solaris        Sparc        2.4 +       -          -
Solaris        Intel        2.6 +       -          -
FreeBSD        Intel        3.3 +       mt/non-mt  -
AIX            RS6000       4.1.3 +     -          -
SCO OpenServer Intel        5 +         -          -
SCO Unixware   Intel        7 +         -          -
HP-UX          PA-RISC      10.10 +     -          -
Tru64          Alpha        5.0 +       -          -
Sinix          MIPS         5.43 +      -          -
OpenVMS        Alpha        7.1 +       -          Requires UCX 5.0/5.0A
                                                   or above

mt = multi-thread (i.e. built with thread support, thread-safe)

1.11 Where is the latest version of this FAQ?
---------------------------------------------

The most up to date copy of this FAQ is always held on the Easysoft
web site. There are links to a plain text and database driven version
of this FAQ on the OOB product page at http://www.easysoft.com.

Occassionally this FAQ may also be posted to the OOB news group at
news://news.easysoft.com/easysoft.public.da2k.odbc-odbc-bridge.

2. OOB Specific
---------------
2.1 How do I build my ODBC application with the OOB?
----------------------------------------------------

If you are using a Driver Manager then consult questions on driver
managers first as generally speaking if a driver manager is installed
your applications should build against the driver manager and the ODBC
driver is just installed. Otherwise, you must compile your ODBC
application (or interface) with the OOB client header files and link
with the OOB client shared object, image or DLL. There are examples
included with the OOB of applications building with the OOB
client. Other documentation is available on building Perl, PHP,
mxODBC, Rexx/SQL etc with the OOB.

2.2 How do I set up a DSN?
--------------------------

In Windows, you use the ODBC Data Source Administrator in the control
panel to define a new data source. Click on add, select the driver for
your database and fill in any dialogues presented to you. If you want
access to a DSN on a Windows machine through the OOB from another
machine you must define a System DSN for the ODBC driver you want
access to and not a User DSN as the latter can only be seen by the
user logged in to Windows.

On non-Windows platforms a DSN is defined in the odbc.ini (or
.odbc.ini) file in the current directory, your home directory or a
system directory like /etc/odbc.ini or SYS$ROOT:odbc.ini.  This file
is a simple text file of the form:

[DSN_name1]
attribute1 = value
attribute2 = value

attributeN = value

[DSN_name2]
attribute1 = value
attribute2 = value

attributeN = value

For a description of the attributes and values see the next question.
For a description of how the OOB locates DSNs see
"How does the OOB client locate DSNs?"

2.3 What attributes may be specified in a DSN?
----------------------------------------------

There are a number of attributes which may be specified in a DSN.
Here is a list with brief descriptions:

Attribute      Description
---------      -----------

Description    A description of this data source. Note that this is
               restricted to the text on a single line.

Driver         The name of the ODBC driver to use with this DSN.
               If your application is linked with a driver manager you
               will need a Driver attribute, generally set to the
               value OOB (but this will depend on what name the OOB
               was installed as).

Server 	       The name (or IP address) of the remote machine where
               the OOB server and ODBC driver for your database are
               located. Note that if you specify a server name
               your machine must be able to resolve this in to the IP
               address via your resolver libraries (e.g. DNS or
               hosts).

Port           The port where the OOB server is listening for incoming
               OOB client connections. This may be either the port
               number or on UNIX, the name of the service (which will
               be looked up with getservbyname() in the /etc/services
               file).

Transport      The network transport used between the OOB client and
               Server.  Currently only TCPIP is available so specify
               "tcpip".

LogonUser      The name of a user who exists on the Server
               machine. The OOB Server changes to this user when an
               incoming connection is made. This will be a user
               specified in your /etc/passwd file, a NT/Windows
               username or a user in your UAF (VMS).

LogonAuth      The password for the LogonUser.

TargetDSN      The name of the DSN to connect to on the remote
               machine.

TargetUser     The username used to identify the connector to the
               database engine. This is added to the connection string
               as UID=username by the OOB client. This may not be
               required by your database engine.

TargetAuth     The password/authentication_string for the user in
               TargetUser.

BlockFetchSize A flag and a value indicating whether the OOB client
               should do block fetches. A value of 0 indicates block
               fetches should not be performed by the OOB client. A
               value between 1 and 100 specifies the OOB client should
               attempt to use block-fetch-mode.  See question on
               speeding up the database reads.

MetaDataBlockFetch
               Takes a value of 0 (off) or 1 (on) and defaults to 1.
               This is used to enable/disable OOB's MetaData block fetch
               mode which speeds up the retrieval of columns in a meta
               data result set (e.g. SQLTables, SQLColumns etc). Some ODBC
               drivers do not have the necessary functionality to support
               MetaDataBlockFetch and need to have this facility turned
               off. Currently, only one private ODBC driver has been found
               to need MetaDataBlockFetch turning off.
               Introduced version 1.0.0.13.

Unquote_Catalog_Fns
               Applixware has the annoying habit of quoting strings in
               the calls to catalogue functions which can cause a
               failure to match. Specifying this attribute makes the
               OOB remove the quoting.

MetaData_ID_Identifier
               When set causes the OOB client to call SQLSetStmtAttr
               to set the SQL_ATTR_METADATA_ID attribute to
               SQL_TRUE. This means strings used in catalog functions
               are treated as literals.  This is sometimes required by
               old applications which do not realise that ODBC treats
               some characters as wildards.

DisguiseWide   Takes a value of 0 (off) and 1 (on), default is off.
               When set disguises the column types described by the ODBC
               driver as SQL_Wxyz for applications that do not understand
               wide characters.
               Introduced version 1.0.0.13.

UseOOBDBAuth   Takes a value of 0 (off) and 1 (on), default is off.
               Setting this value to on causes the OOB client to
               ignore the UID/PWD values passed to it via
               SQLDriverConnect in the connection string and use the
               TargetUser/TargetAuth in the registry/odbc.ini DSN
               instead. When UseOOBDBAuth is off the UID and PWD in the
               connection string always overides
               TargetUser/TargetAuth.

2.4 How does the OOB locate DSNs?
---------------------------------

In Windows, the OOB client uses the {Get|Set}PrivateProfileString
interface to save and retrieve DSN attributes. Therefore, all data
sources should be set up with the ODBC Data Source Administrator.

In non-Windows platforms the data sources are stored in a text file.
The OOB client searches for this text file using the following order:

ODBCINI (environment variable)
<cwd>odbc.ini
<cwd>.odbc.ini (UNIX only, not VMS)
<home>odbc.ini
<home>.odbc.ini (UNIX only, not VMS)
/etc/odbc.ini (SYS$ROOT:odbc.ini for VMS) - system DSNs only
<wherever unixODBC stores DSNs>

Where <cwd> is the current working directory and <home> is the current
users home directory.

If the OOB client cannot find the DSN in the fixed locations it will
attempt to load the unixODBC libodbcinst shared object and use
SQLGetPrivateProfileString(). In this way, if you built unixODBC
yourself with a different --sysconfdir, OOB can still find your DSNs.

The OOB server has no need to lookup DSNs or DSN attributes as it is
acting as an application talking to either a driver manager or an ODBC
driver directly (of course this changes when you are running the OOB
Server on non-Windows machines).

If you are running Apache/PHP built with the OOB, Easysoft recommend
you use /etc/odbc.ini because [1] this is more secure as it is out
of your htdocs directory [2] it avoids possible problems when starting
Apache in a directory other than where your odbc.ini file is located.
See later question.

2.5 I only want to retrieve data from the server, are there any tricks
----------------------------------------------------------------------
    to speed it up in read-only mode?
    ---------------------------------

If you have written the application yourselves then using bound
columns and large Array sizes is a great deal more efficient over a
network. The OOB client pulls all the bound columns over in one go
which is alot quicker than using repeated SQLFetchs and multiple
SQLGetData calls, one per column.

If you do not want to change your application (or cannot) and you are
only reading data from the database (and not using positioned updates,
deletes etc) then the OOB has a built in block-fetch-mode which may be
enabled with the DSN attribute, BlockFetchSize. Add "BlockFetchSize =
n" to the DSN entry you are using where (0 <= n < 100) n is the number
of rows to retrieve in one go. This shows significant speed increases
for the reasons in the paragraph above but may not be used with
certain types of cursors and when doing positioned updates/deletes.

Note that a value of 0 means block-fetch-mode is turned off and the
OOB works as a normal ODBC driver.

A value of 1 is safe to use even if you are doing positioned updates
and deletes and is often faster than with block-fetch-mode turned off.

2.6 How can I get help on using the OOB?
----------------------------------------

[1] Post a message to the
    news://news.easysoft.com/easysoft.public.da2k.odbc-odbc-bridge
    news group.
[2] Mail support@easysoft.com.
[3] Consult the http://www.easysoft.com web pages.

Please see the Easysoft Data Access support posting in the
news://news.easysoft.com/easysoft.public.da2k.odbc-odbc-bridge news
group and http://www.easysoft.com/support/main.phtml.

2.7 Where do I report bugs in the OOB?
--------------------------------------

You can report bugs by:

[1] mailing support@easysoft.com
[2] Post a message to the
    news://news.easysoft.com/easysoft.public.da2k.odbc-odbc-bridge
    news group.
[3] if you have a support contract you can contact Easysoft support.
    Contact information is available on our web site at
    http://www.easysoft.com.

If you just have a a query then see the previous question.

2.8 How much does a license for OOB cost?
----------------------------------------

The costs for the ODBC-ODBC Bridge may be found at:

http://www.easysoft.com/products/oob/pricing.phtml

2.9 When will the final release of OOB be available?
----------------------------------------------------

The final release date is 1st December 1999.

2.10 When does the beta version expire?
----------------------------------------

The first two beta versions (0.2.0.0 and 0.2.2.0) expire 1st July
1999. The third beta (0.2.4.0) expired 1st October 1999. Beta
versions generally expire within three months to ensure that beta
testers are using the latest version. The third and fourth betas,
0.4.0.0 and 0.6.0.0 expire 1st December 1999.

2.11 What do I do when my beta version of the OOB expires?
----------------------------------------------------------

If the OOB is still undergoing beta testing then all you have to do is
visit our web site or FTP site and download a newer beta version. If
the OOB has completed beta testing and moved into final release then
you should contact sales at sales@easysoft.com for purchasing
information.

You do not have to be concerned about continuity of supply of the OOB.
There will always be either a beta version or a purchasable version
available.

Please see the question on how do I license OOB?

2.12 How do I license OOB?
--------------------------

From version 0.8.0.0 of OOB you need a license to run the OOB Server.
The client side of OOB is license free.

The OOB Install for Windows includes a license administrator. A short
cut is added to:

Start Menu > Programs > Easysoft > Easysoft Data Access 2000 Licensing
or
Start Menu > Programs > Easysoft > Easysoft Data Access Licensing

called License Manager. You can use the License Administrator to
obtain new licenses either, automatically over the net via a direct
link or via email. You can also view any existing licenses.

The OOB install for UNIX includes a shell program called licshell
which may be used to obtain licenses.

Please also visit http://www.easysoft.com/support/faq.phtml where you
will find a list of online documents about licensing.

2.13 Are there any configurable options for the OOB?
----------------------------------------------------

There are a number of configurable options that affect the OOB client
or server. For Windows, these are specified in the registry and may be
changed via the HTTP interface. For UNIX, they are specified in the
{Settings} section of your odbc.ini (or its equivalent) or the
/usr/local/easysoft/oob/server/esoobserver.ini.

MaxBookmarkSize
               This attribute specifies the size of the largest
               bookmark the OOB can handle (it defaults to 32). ODBC
               2.0 uses fixed length bookmarks of 4 bytes. In ODBC 3.0
               bookmarks are all variable in size. If you find an ODBC
               driver that needs more than 32 bytes for a bookmark
               please let us know, otherwise the default should be
               fine.

               NOTE - this attribute is in version 0.4.0.0 onwards.

Timeout        This defines the inactivity timeout in seconds (the
               default is 7200 - 2 hours). This attribute is currently
               only meaningful for Windows platforms. The OOB server
               starts a new thread for each client that connects. If
               there has been no communication in timeout seconds the
               thread exits. This ensures clients which fail to
               closedown properly don't cause increasing resource
               usage on the server.

               NOTE - this attribute is in version 0.4.0.0 onwards.

HTTPPort       This option specifies the port on which the OOB Server
               will listen for HTTP requests (note that in UNIX, the
               HTTP Server is only available if the OOB Server is
               started standalone with the "standalone" command line
               argument and not when started from inetd). The default
               is port 8890 but it may be any port not in use on your
               machine. If the Flags configurable option bitmask has
               the second bit set (value 0x2) then the OOB Server
               starts listening on the specified port for HTTP
               requests in addition to acting in its normal role
               serving the OOB Client. You may use the URL
               http://machine_name:HTTPPort where machine_name is the
               name (or IP address) of the machine running the OOB
               Server and HTTPPort is the port number to communicate
               with the OOB Server from your browser. It can show
               statistics, DSNs and the current values of configurable
               parameters. You can also change configurable parameters
               and define access control.

               NOTE - this attribute is in version 0.4.0.0 onwards.

LogDir         This option specifies the directory where log files are
               created (see Logging).

Logging	       This is a bitmask telling the OOB Client or Server what
               sorts of event to log in the log file. This should only
               be used as directed by Easysoft support and will slow
               the OOB down considerably if set.

RetryCount     This is the number of attempts the OOB Server makes at
               creating a new thread/process to handle an incoming
               connection or obtain a license slot.

RetryPause     This is the time in seconds the server pauses between
               RetryCounts.

Flags          This is a bitmask of operational flags. The bitmasks are:

               0x1 Authentication_Disabled
                   Disable OOB Server authentication
                   (default is clear, i.e. not set)
                   When set the values of LogonUser/LogonAuth
                   specified in the DSN at the client end are
                   irrelevant and the OOB server will NOT become the
                   LogonUser for the duration of the ODBC
                   connection. As a result, this flag should be used
                   with extreme caution as it means anyone with the
                   OOB client who is not denied access via OOB Server
                   access control can gain access to your SYSTEM data
                   sources.

               0x2 HTTP_Server
                   Start listening for HTTP connections when the server starts
	           (default is set, 0x2)

	       0x4 MultiProcess
                   OOB Server starts a new process for each incoming connection
                   instead of a new thread
		   (default is clear, ie. not set and therefore the Server
		   starts a new thread per connection). You might set this
                   if you had an ODBC driver which you know is not thread-safe.
	       0x8 MetaDataBlockFetch_Disabled
                   If set prevents the OOB client from automatically starting
                   block-fetch-mode for read-only metadata result-sets.
                   (default is clear, i.e. automatic metadata block-fetch-mode
		    enabled).

               0x10 HideSensitive
                   If set prevents the OOB Server administrators username
                   being displayed on the OOB HTTP Server web page for
                   configurable parameters (default is set i.e. no one browsing
                   the configurable parameters web page will see the name of
                   the administrator). Setting this flag also hides
                   whether you have disabled authentication or not.

               0x20 ReverseLookup
                   If set the OOB Server does a reverse lookup on the
                   client's IP address. Connections may be slighty
                   quicker if you clear this flag. The default is set i.e.
                   reverse lookups are performed).
                   If your machine is not configured to resolve IP
                   addresses in to machine names (i.e. not capable of
                   doing reverse lookups via the API gethostbyaddr()
                   this flag must be clear.

               0x40 AuditODBCAccess
                   If set audits connections to the OOB Server in an audit
                   trail file. This file is called esoob.access and will
                   be placed in the LOGDIR (see above) directory.
                   The default is clear, i.e. auditing does not take place.

               0x80 FreeStmstsOnDisconnect
                   If this flag is set then the OOB Server frees all
                   existing statements in the driver before calling
                   SQLDisconnect. By default this flag is clear as the ODBC
                   specification says that applications do not have to do this
                   and the driver should quietly do it for them. However, a
                   customer has seen Navision's ODBC driver crash when
                   SQLDisconnect is called from Perl when there are existing
                   statements so setting this flag works around this problem
                   in Navision's driver. The default is clear.

                0x100 ShowProcessTime
                   If set causes the OOB HTTP Server to display kernel
                   and user time used by the OOB Server. The default is
                   set.

                0x200 AutoUpdateConfiguration
                   If this flag is set then the OOB Server automatically
                   updates its copy of the configuration settings from the
                   registry or ini file. This affects the access control
                   lists, the flags listed here and MaxClientConnect/
                   MaxThreadCount. The values are only updated when 5 seconds
                   elapses with no incoming connections in that time.
                   Disabling this feature reduces accesses to the registry/ini
                   but means the server has to be restarted to pick up
                   configuration changes. The default is off.

	       You add these values together to produce the Flags value.
	       The Flags value may be changed using check boxes on the
               OOB HTTP Server configuration page.

You must add a "{settings}" section to your odbc.ini/esoobserver.ini
to define any of these configurable parameters. Here is an example:

{settings}
Logging = 0xffffff

[DSN_1]
attribute = value
.
.

2.14 How much memory do I need for the OOB Server on NT?
--------------------------------------------------------

How long is a piece of string?

The OOB Server for NT can run in 2 configurations.

The default is to create a new thread for every incoming ODBC
connection. The server under this configuration requires about 2Mb
and approximately 250K per thread but this latter number starts at 250Kb
and rises depending on what you do with the ODBC driver you are
connected to.

An alternative configuration for non-thread-safe ODBC drivers
instructs the OOB Server to start a new process per connection. This
requires approximately, 2Mb for the main server and 2Mb+ for each
connection.

2.15 Why does it take so long to connect to the server?
-------------------------------------------------------

In our experiments it takes less than 1/10 second to connect an
application linked directly with the OOB client on Linux to a
data source on NT over a 100Mb Ethernet link where both machines are on
the same LAN. This is a small fraction of a second slower for
interpreted languages like Perl or if there is a driver manager (like
unixODBC) between the application and the OOB client.

If you are experiencing connect times much slower than 1 second you
should check the following:

[a] Are the client and server machines on the same Local Area Network
    (LAN)?  Connection times can increase dramatically if they are
    not. Try pinging the server from the client and see what return
    times you get.

    e.g.

    ping www.easysoft.com
    PING pubmail.easysoft.com (194.131.236.4): 56 data bytes
    64 bytes from 194.131.236.4: icmp_seq=0 ttl=255 time=0.6 ms
    64 bytes from 194.131.236.4: icmp_seq=1 ttl=255 time=0.1 ms

    In this case less than 0.6ms - quick. Machines not on the same LAN
    can show a much greater time and this will be reflected in your
    ODBC connect times.

[b] Disable Reverse Lookups in the OOB Server. Performing a reverse
    lookup on an IP address can be quite slow depending on how the
    machine is configured to perform the reverse lookup. You can do
    this from the OOB HTTP Server configuration screen.  See question
    "Are there any configurable options for the OOB".

[c] Check that you do not have any tracing turned on. There are multiple
    places tracing and logging may be turned on:

    [1] Make sure that in your odbc.ini file any lines starting with
        "Logging = number_greater_than_0" are commented out with # or
        just delete them (this is OOB tracing).

    [2] If you are using the unixODBC Driver Manager then remove lines
        that look like "Trace = yes" and "TraceFile = file" or ensure
        Trace is set to no.

    [3] Make sure you have not turned on tracing at the server
        end. You can check this through a web browser to
        http://server_machine:8890 and then Configuration. Logging
        should be set to 0. Alternatively on UNIX examine the server
        odbc.ini/esoobserver.ini file or on Windows examine the
        registry for:

  	HKEY_LOCAL_MACHINE\
  	SOFTWARE\
  	Easysoft ODBC-ODBC Bridge\
  	Configuration\
  	System\
  	Settings\
  	Logging

     [4] If using Windows make sure tracing in the driver manager is
         not turned on. You can check this by going in to the ODBC
         Administrator and clicking on the tracing tab.

     All of the above default to tracing off or require positive
     action to turn tracing on.

[d] If you are using OOB version 0.4.0.n of greater for NT you can
    make the OOB Server start a new thread or a new process for each
    connection. By default, the OOB server starts a new thread but if
    bit 3 (value 0x4) of the configurable parameter "Flags" is set the
    server starts a new process - this is alot slower. You can check
    Flags as above for Logging.

[e] If using OOB 0.8.0.0 or above then obtaining a license slot adds a
    small amount of time to a connection (much less than 1/10s).
    However, if you are limited through your license to a set number
    of concurrent connections the OOB Server, by default, tries 5
    times at 3 second intervals to obtain a license slot before giving
    up. The retry attempts and pause between attempts is configurable
    via the RetryCount and RetryPause parameters.

[f] Check your application is not turning ODBC tracing on by calling
    SQLSetConnectAttr(SQL_ATTR_TRACE, SQL_OPT_TRACE_ON).

If after checking the above you are still want faster connections then
try using persistent ODBC connections (e.g. odbc_pconnect in PHP) as
these hold connections open for use by the call to an ODBC connect
function with the same DSN, username and password. If you are making
alot of repeated connections to the same DSN this can be alot faster.

Another alternative if you are in control of the ODBC application is
to connect then prepare statements before they are required. Then,
when you need to execute the SQL all you have to do is bind the
parameters in the prepared statement.

NOTE: If you are using persistent connections or connecting a long
time before you use the connection see the later question "Why do my
connections to the OOB server seem to be dropped after a while?

NOTE: If you are using MS SQL Server 7.0 then see the later question
"Why are my connections to SQL Server so slow?".

NOTE: If you are using Windows 2000 then see the later question "Why
have connection times to MS SQL Server slowed down since upgrading to
Windows 2000 Server?"

2.16 Why can I see more tables in MS SQLServer than normal?
-----------------------------------------------------------

When running the OOB client connected to the OOB Server and the MS
SQL Server ODBC driver you may find more tables are visible than when
connecting directly to the same MS SQL Server data source with the same
username and password. By default the OOB Server for Windows NT is
installed as a service running with administrator privileges. When the
OOB client connects to the server you pass a login username and
password which the OOB Server uses so it can become the specified
user. For MS SQL Server data sources using trusted connections the MS
SQL Server ODBC driver appears to notice you were an administrative
user and are now someone else (possibly noticing the real and
effective UIDs). Depending on how your database is set up it may then
show you tables you would not have otherwise seen.

If this causes you concern you can change the OOB Server service to
run as someone other than the administrative user. You do this by
starting the service manager administrative program in the control
panel and editing the startup options to specify a username and
password. You should then stop the OOB Server service and restart it.

2.17 Are any usernames/passwords transmitted as plain text over the network
---------------------------------------------------------------------------
     connection?
     -----------

No. Any usernames and passwords supplied in the connection string or
stored in the registry/odbc.ini are encrypted before sending them
across the network connection between the client and server.

In addition, usernames and passwords for OOB datasources in Windows
which are stored in the registry are encrypted.

All information in a connect string is encrypted before passing this
across a network connection.

2.18 Can I strip(1) the shared objects and executables?
-------------------------------------------------------

You can run strip on the shared objects and executables distributed
with the OOB to remove the symbols but this may affect any support
Easysoft can supply. Generally speaking we advise you not to strip the
shared objects and executables as the OOB is not large.

2.19 Can I run the OOB Server on UNIX without the inetd SuperServer?
--------------------------------------------------------------------

Yes. By default the OOB Server for UNIX is installed as a service with
entries in the /etc/services and /etc/inetd.conf files (inetd is
informed of the configuration file changes)(OOB also supports xinetd).
However, the OOB Server for UNIX will run standalone as well. To run the
OOB Server standalone you need to either:

[1] use a different port address from the entry in /etc/services for
    esoobserver. Edit
    <install_path>/easysoft/oob/server/esoobserver.ini and change the
    entry "Port = 8888" to specify a different port.

[2] comment out the esoobserver entries in /etc/services and
    /etc/inetd.conf and send a SIGHUP to inetd.

Once you have done the above you start the server by changing
directory to <install_path>/easysoft/oob/server and issuing the
following command:

./esoobserver standalone

The server will start listening for connections on the Port specified
in the esoobserver.ini file. You should really start the OOB Server as
root or it will be unable to change to the LogonUser specified in the
OOB client DSN. However, if you do not start the OOB Server as root
then no logon authentication will be performed and all clients will
run on the server as the user who started the OOB Server.

You can add a line to start the OOB Server standalone to one of your
rc scripts to have the OOB Server start up every time the machine
boots.  The file you need to change depends on your Operating System
so it is best to consult your system administrator. On RedHat for
Linux a good place is /etc/rc.d/rc.local.

When the OOB server is started standalone it will by default fork a
process to handle HTTP requests on port 8890 (this can be changed in
the esoobserver.ini file). You can then use your browser to contact
the OOB HTTP server using http://machine.domain:8890 and see
connection statistics, configurable parameters and access control.  If
you want to change configurable parameters or access control via the
HTTP interface you must define HTTPAdmin in the esoobserver.ini to an
existing user on your machine and you will need to enter the password
when viewing/making_changes on some protected pages. In this case the
OOB Server must be running as root on some machines to verify the
username/password.

2.20 Can I make the OOB statistics web page refresh more/less frequently?
-------------------------------------------------------------------------

Yes. The OOB HTTP Server uses a set of template files in to which the
dynamic data is inserted before sending it back to your browser. The
template file for the main page (the statistics page) is index.html.
You should find this file in the directory called templates wherever
you installed the OOB Server. Edit the index.html file and near the
top you will see 'meta http-equiv="refresh" content="60;
URL=/index.html'.  Change the 60 (the refresh time in seconds) to
whatever you would like.  You should note that setting this very low
will cause the OOB server thread handling HTTP requests to be kept
busy which might reduce the response time to the OOB ODBC server thread
so times much less than 60 seconds are not recommended.

2.21 Why does the OOB HTTP Server statistics page show active threads
---------------------------------------------------------------------
     when there are no connections?
     ------------------------------

The OOB HTTP Server statistics page is a guide to what is happening
and what has happened in the OOB ODBC server. The OOB Server registers
a new active connection when a client successfully connects and a thread
(or process) is started up to handle the ODBC connection. The server does
not deregister the connection (as far as the statistics are concerned)
immediately the client disconnects. The server looks for disconnected
threads/process when there has been no incoming connection for a period
of 5 seconds. This gives priority to incoming connections. This also
affects the peak concurrent connection count e.g. if you write a program
which connects and disconnects in one second but this is repeated every
3 seconds the active connections and peak concurrent connections will
appear to increase until your program stops.

There is one situation in which is this not the case. If you set
MaxClientConnect or MaxThreadCount to a value other than 1 to limit
the connections, the server checks for terminating threads/processes
every time a connection is made, so the active and concurrent counts
will always be up to date immediately after an ODBC connection from a
client.

This does not affect licensing in any way i.e. if you have a free
personal license which restricts the concurrent connections to 3 the
server does not use the active connections statistic to decide whether
you can connect or not.

2.22 Why cannot I login to the HTTP Administrator when running the OOB
----------------------------------------------------------------------
     server as a named user instead of in the system account?
     --------------------------------------------------------

By default the OOB Server is installed as a service which runs in the
system account - this is usual for NT system services. If you elect to
run the OOB Server under a named account that account may not have
privilege to become another user. Certain pages in the OOB HTTP
administrator are protected using HTTP authentication and when you
login, the HTTP server temporarily becomes the user you log in as.  If
the OOB Server does not have privilege to become that user you will
not be able to login to those pages.  A solution is to disable HTTP
authentication in the OOB HTTP Server by either:

[1] restart the OOB Server service in the system account, go to the
    configuration web page and change the HTTPAdmin username to
    disabled.
[2] Edit the registry key:

     HKEY_LOCAL_MACHINE/
     SOFTWARE/
     EASYSOFT ODBC-ODBC BRIDGE/
     CONFIGURATION/
     SYSTEM/
     SETTINGS/
     HTTPADMIN

    and change it to the text "disabled" (omit the quotes).

One imagines that the reason you want to run the OOB Server under a
named account is for added security but in fact you are opening up
security holes doing this. Firstly, anyone with the OOB client can now
connect to your data and secondly, to administer the OOB Server via
HTTP you will have to disable HTTP authentication. Disabling HTTP
authentication means anyone can change the OOB Server settings.

Easysoft recommend you run the OOB Server in the system account.

2.23 Is there any tracing in OOB I can use for debugging my application?
------------------------------------------------------------------------

The OOB client and server both have a mechanism for creating a trace
file.  How this is turned on depends on the platform and whether it is
the client or server. The types of tracing output may be selected by
use of a bitmask. Please treat this as an undocumented feature as the
mechanism for initiating tracing, the bit mask values and where the
trace file is written may change. Please also remember that the
tracing output was written to help us debug OOB problems so there is
no documentation on the format or contents of the trace file. Having
said this, the information is useful when debugging your application is
fairly obvious.

Some types of tracing generate a tremendous amount of output. Any kind
of tracing will slow the client or server down significantly as the
tracing output is flushed to the file every write.

On non-Windows platforms tracing is turned on by setting the Logging 
value in the Settings section of the odbc.ini file in the CURRENT WORKING
DIRECTORY to a non-zero value. e.g. your odbc.ini in the current working
directory would look something like this:

{Settings}
Logging = 0xnnnnnn

[DSN1]
attribute = value
.
.

with the DSNs are optional, as they may be in another odbc.ini file
(e.g. /etc).  Note, OOB only looks for the Logging value in the
odbc.ini in the current working directory. For UNIX, the output trace
file is normally named esoobclient.log_<PID> or esoobserver.log_<PID>
(where <PID> is the process ID) and will be placed in /tmp UNLESS the
file already exists and is a symbolic link.

In Windows you set the Logging value in the registry key:

HKEY_LOCAL_MACHINE\
SOFTWARE\
EASYSOFT ODBC-ODBC BRIDGE\
CONFIGURATION\
SYSTEM\
SETTINGS\

For Windows, the output files are esoobclient.log or esoobserver.log
and will be placed wherever the LogDir configuration option points.

In both cases the Logging value is a string value representing a bit
mask and may be specified in decimal or in hex (if a 0x is
prefixed). The bitmask values are listed below; you should just add up
all the ones you want.

0x1   Log entry points in to functions e.g. the function called and the
      arguments passed to it. Generally useful for ODBC application
      developers.

0x2   Log exit points from functions e.g. return status and sometimes
      other values returned. Generally useful for ODBC application
      developers.

0x8   Special logging not covered by other bit masks. It is unlikely
      much, if anything, of this will make a great deal of sense to
      anyone but Easysoft as it output OOB internal information.

0x10  OctetLengths, IndicatorPtrs, Row status values etc in bound
      parameters, bound columns or getdata.

0x20  Log internal (non-ODBC-API) OOB function entry/exit points
      depending on whether 0x1 and/or 0x2 set. Generally speaking
      little of this will be useful to anyone who does not knwo the
      internals of OOB.

0x40  Log calls to the OOB Server (client-side) or ODBC driver
      (server-side).

0x80  Log ODBC diagnostics. This may create an odbc_bridgec_diags.txt
      (client) or odbc_bridges_diags.txt (server) file in the LogDir
      directory.  This may be a useful logging option if the code that
      outputs diagnostics in your application is broken as the
      diagnostic will be logged when SQLError or SQLGetDiagRec is
      called.

0x100 Log query text in SQLPrepare/SQLExecDirect. Another useful one
      if you want to check what your application is asking the driver
      to do.

0x200 Log the connection process. This will show how OOB has retrieved
      the attributes for your DSN and what it is passing to the ODBC
      driver.

0x400 Log attribute retrievals or changes e.g. calls to
      SQLSetConnectAttr etc.

0x800 Start main OOB Server logging. There is no ODBC information in
      this output at all, it simply outputs what the main OOB Server
      is doing before the ODBC connection starts and will generate a
      huge amount of output over time. The log file is esoobstart.log.

0x1000 Log the actual data sent or retrieved.

0x2000 Output timing information e.g. how long an SQLPrepare,
       SQLExecDirect took.

2.24 How do I specify connection attributes for my DSN that are not
-------------------------------------------------------------------
     configurable in the odbc.ini?
     ----------------------------

My ODBC driver requires additional attributes that I have specified in
my odbc.ini file but they do not seem to get through to the driver.
The OOB only picks up from the odbc.ini file the attributes specified
in the answer to "What attributes may be specified in a DSN?". If you
need to specify additional attributes you must pass them in the
connection string to SQLDriverConnect().

For Perl, see the answer to the question "How can I put attributes
other than the DSN in my Perl DBI->connect call?".

For PHP and OOB there is a simple trick you can use.  Add the
attributes to string passed to odbc_connect() as the DSN name,
separating the attributes with semicolons.

e.g. if you were calling odbc_connect with

odbc_connect("mydsn","username", "password") and want to pass the ENG

attribute with a value of engine use:

odbc_connect("mydsn;ENG=engine","username","password")

This only works with OOB because calls made by applications to
SQLConnect in OOB are actually redirected to SQLDriverConnect once
"DSN=" is prefixed to the DSN name in SQLConnect's first argument.
However, the disadavantage of this method is that if you are using a
Driver Manager (e.g. unixODBC) the string passed must be less than 32
(SQL_MAX_DSN_NAME) characters so it is rather limiting (the same does
not apply to Perl as Perl calls SQLConnect and if that fails,
SQLDriverConnect).

For applications that you have the source code for you will need to
edit the code, find the call to SQLDriverConnect and add your
attributes to the string argument 3 (InConnectionString). If the
application uses SQLConnect instead of SQLDriverConnect (e.g. isql
that comes with unixODBC) you will need to change it to use
SQLDriverConnect (see the demo.c program in the OOB examples directory
for code using SQLDriverConnect).

2.25 Why does SQLDataSources list a datasource which returns the
----------------------------------------------------------------
     Datasource not found message when I connect to it?
     --------------------------------------------------

If you are using the unixODBC driver manager (included in the OOB
distribution) then SQLDataSources (or DBI->data_sources if you are
using Perl) will return the datasources found in the odbc.ini file (it
does not check the validity of each datasource). However, if any of
these datasources are missing the Driver attribute or have a Driver
attribute for which there is no corresponding driver in the
odbcinst.ini file then unixODBC will return:

IM002, Data source name not found, and no default driver specified.

If your application is linked directly with OOB (no driver manager)
then although the OOB client supports SQLDataSources it is limited
support and you are better using a driver manager.

2.26 How can I encrypt the network connection between the client and server?
----------------------------------------------------------------------------

Easysoft recommend Zebedee (http://www.winton.org.uk/zebedee).

Zebedee is a simple program to establish an encrypted, compressed
"tunnel" for TCP/IP or UDP data transfer between two systems.

zebedee is a neat little program which works on various unixes and
Windows and is distributed in source and binary form. It works with
two compression libraries (zlib and bzip2) and currently one
encryption library, blowfish.

zebedee is easy to build and works quite simply. You run zebedee on
your server where it listens on a predetermined port. You then run
zebedee on the client machine where you specify the server, server
port where zebedee is running and the port for the normal service you
want to use. The zebedee client then returns a port on your local
machine which your client software can use to communicate with the
remote service using encryption and compression. The client and server
application and service code do not need to be changed in any way.

The OOB performs a fair amount of compression of network data itself
so it is normally adisable to omit the compression from the zebedee
connection.

2.27 Does the OOB install for UNIX support xinetd?
--------------------------------------------------

xinetd (http://www.xinetd.org/) is an open source replacement for
inetd which combines inetd, tcpwrappers and a considerable amount of
other functionality. RedHat 7 (and perhaps other distributions) now
appears to use xinetd.

The install scripts for UNIX distributions up to 1.0.0.23 do not
support xinetd although it is relatively trivial to manually add the
OOB Server to the xinetd configuration post install.

To install the OOB Server under xinetd manually:

[1] Locate the xinetd.conf file. It is usually /etc/xinetd/conf.

[2] Examine the xinetd.conf file and look for a an includedir command.
    If you find an includedir command change to that directory and add
    a new file called esoobserver that looks like this:

    service esoobserver
    {
        socket_type             = stream
        protocol                = tcp
        wait                    = no
        user                    = root
        server                  = /bin/bash
        server_args             = /usr/local/easysoft/oob/server/server 
        disable                 = no
    }

    Make sure the server argument is a valid shell on your system.

[3] If in [2] you did not find an includedir command then the above
    entry can be added to the end of your xinetd.conf file.

[4] Once you have made your changes you need to tell xinetd to reread
    its configuration files. You usually do this by sending it a USR1
    signal e.g. kill -USR1 process_id_of_xinetd. However, as xinetd
    can be configured to use different signals you should check the
    signal your xinetd requires.

2.28 Do you have to have DNS working for correct operation of the OOB?
----------------------------------------------------------------------

The OOB Server does not need DNS working on your network. However, if
you enable the OOB configurable parameters "ReverseLookup" then the
OOB server will perform a reverse lookup on the client's IP address to
obtain the client machine name. In this case DNS must be working and
your resolver library must be able to do the reverse lookup or it can
result in long connection times.

The OOB client only needs to resolve a machine name into an IP address
if you set the Server attribute in your odbc.ini/registry to a machine
name. You can avoid this by referring to the server machine's IP
address instead.

2.29 Can multiple machines running the OOB client simultaneously use the
------------------------------------------------------------------------
     same OOB Server?
     ----------------

Yes. The OOB Server does not service one connection at a time. The OOB
server accepts a connection and hands it off to a thread or process to
deal with that connection and immediately goes back to accepting new
connections. As a result an OOB Server can be handling connections
from many different client machines at the same time.

2.30 How does the OOB client handle refused connections?
--------------------------------------------------------

The OOB client will retry connection attempts if the server operating
system returns ECONREFUSED (connection refused). The reason for this
is that on some platforms (notably NT workstation) the listen backlog
can only be set to a low level so if there is a sudden rush of
connections the operating system may turn some down before the OOB
Server sees them. When ECONREFUSED is received by the client it waits
connection_attempt * 0.1 seconds before trying again up to a maximum
of NetConnectRetryCount times.

Here is an example where NetConnectRetryCount is 5 (the default) and
the server always refuses the connection:

connect attempt 1 - refused by server
wait 0.1 seconds
connect attempt 2 - refused by server
wait 0.1*2 seconds
.
.
.
connect attempt 5 - refused by server
client gets error diagnostic:

08001:1:4:[Easysoft ODBC (Client)]
  Client unable to establish connection
HY000:2:4:[Easysoft ODBC (Client)]
  Connection refused, connect(), after 5 attempts

and here is an example where the first few attempts are refused due to
the listen backlog queue being full but by the third attempt the
backlog is cleared and the connection accepted:

connect attempt 1 - refused by server
wait 0.1 seconds
connect attempt 2 - refused by server
wait 0.1 * 2 seconds
connect attempt 3
 connection accepted by server operating system

The NetConnectRetryCount is 5 by default but it may be modified in the
OOB Settings off the DSN dialogue (Windows) or in the {Settings} section
of your odbc.ini file. e.g.

{Settings}
NetConnectRetryCount = 3

Please note NetConnectRetryCount is a global setting for all DSNs.

2.31 How does the OOB client support connection timeouts?
---------------------------------------------------------

Connection timeouts are set by an application calling
SQLSetConnectAttr with the attribute
SQL_ATTR_CONNECTION_TIMEOUT. Currently (OOB 1.0.0.23) only uses the
connection timeout when actually connecting to the server and not for
all ODBC calls. If you set the connection timeout and then the connect
does not succeed in the timeout period you will get a diagnostic like
this:

08001:1:4:[Easysoft ODBC (Client)]Client unable to establish connection
HY000:2:4:[Easysoft ODBC (Client)]Connection attempt timed out

However, there are a couple of important points:

[1] Connection timeouts are not currently supported in Windows or
    multi-threaded versions of the OOB client for UNIX.

[2] OOB classes the connection phase as obtaining the IP address of
    the server machine and connecting to it. This means that if you
    specify the Server attribute as a name rather than an IP address
    your system resolver library will be used (possibly examining
    /etc/hosts or performing a DNS query). On some operating systems,
    gethostbyname(), the call used to resolve a machine name into an
    IP address cannot be interrupted and the connection timeout will
    not work. If this is a problem for you then specify the Server
    attribute as an IP address or tell your resolver library to
    consult /etc/hosts before DSN and place an entry in /etc/hosts.

[3] Calls to SQLSetConnectAttr/SQLSetConnectOption for the
    SQL_ATTR_CONNECTION_TIMEOUT are passed on to the ODBC driver at
    the server end.

[4] Connection timeouts at the network level are not usuable since
    many operating systems hard-wire them.

[5] If you are writing your own application linked with the OOB client
    and are working in an environment where network cables may be
    pulled out (network connections lost) then you can put alarm() and
    SIGALRM handlers (or sigsetjmp) around your ODBC calls to
    implement connection timeouts.

2.32 What does the OOB do if an application terminates abnormally?
------------------------------------------------------------------

If an application using the OOB client terminates abnormally e.g. the
application seg faults or is interrupted with SIGINT, the socket
connection to the OOB server will be closed by the operating system.

The OOB server spots the closed socket connection and attempts to tidy
up the ODBC connection to the ODBC driver. It will loop through all
connections created by that client and call SQLDisconnect for each
one. If any fail to disconnect due to SQLSTATE 25000 (transaction in
progress) the server will call SQLEndTran(SQL_ROLLBACK) i.e. it will
attempt to roll back the transaction so the connection may be closed.
All handles in the ODBC driver are freed with SQLFreeHandle.

As an example, if you had some Perl which ran through OOB to MS
SQLServer and it turned off autocommit, updated a row in a table and
then the perl was stopped (say you hit ctrl/c or whatever your
interrupt key sequence is) before the transaction was committed the
OOB server would roll back the updates so the connection to the ODBC
driver could be closed.

2.33 I have no root access. How do I tell OOB/unixODBC to use odbc.ini
----------------------------------------------------------------------
     and odbcinst.ini files not in /etc?
     -----------------------------------

You do not need to be root to install the OOB client but certain parts
of the installation of the unixODBC driver manager are not usually
possible as a non-root user. Since unixODBC is built with the
sysconfdir configuration option set to /etc, the odbcinst.ini file
containing all the installed ODBC drivers resides in /etc by default
(as does the odbc.ini containing SYSTEM data sources). You can tell
unixODBC to look elsewhere for these files by setting and exporting
the ODBCSYSINI environment variable to point to another directory you
have write access to and creating the odbc.ini and odbcinst.ini files
there instead.

e.g.
Say you have installed OOB and unixODBC in your home account.
Create a etc directory in your home account, create odbcinst.ini and
odbc.ini files as below and set/export ODBCSYSINI.

cd $HOME
mkdir etc
cd etc
echo "[OOB]" > odbcinst.ini
echo "Description = Easysoft ODBC-ODBC Bridge" >> odbcinst.ini
echo "Driver = $HOMEeasysoft/oob/client/libesoobclient.so" >> odbcinst.ini
echo "Setup = $HOME/oob/client/libesoobsetup.so >> odbcinst.ini
echo "FileUsage = 1" >> odbcinst.ini
> odbc.ini
ODBCSYSINI=$HOME/etc
export ODBCSYSINI

2.34 Why do I get the error "Not enough attributes for connection" since
------------------------------------------------------------------------
     upgrading OOB from a pre 1.0.0.27 release?
     ------------------------------------------

OOB was changed in version 1.0.0.27 to require the LogonUser and
LogonAuth attributes (see the Changes.txt file entry for
4-Apr-2001). This change was made because a number of new OOB users
were getting confused by the authorisation error 87 (invalid
parameter) when LogonUser was not specified and authentication was
enabled in the OOB Server.

Prior to 1.0.0.27, if you had authentication turned off in the OOB
Server you did not have to specify LogonUser/LogonAuth. From 1.0.0.27,
if you have OOB Server authentication turned off you will have to
specify a value for LogonUser/LogonAuth although the actual value is
meaningless.

3. Trouble Shooting
------------------
3.1 I keep getting connection refused error from the client?
------------------------------------------------------------

If you get errors such as:

08001:1:4:[Easysoft ODBC (Client)]Client unable to establish connection
HY000:2:4:[Easysoft ODBC (Client)]Connection refused, <error text>

then the ODBC-ODBC Bridge server is not listening on the specified
port or the operating system refused the connection due to the listen
backlog queue filling (in this latter case see the question "Why do I
get connection refused under heavy loads?".  First check the DSN entry
you are using in the odbc.ini (or .odbc.ini or ODBC Administrator) is
correct. One of the attributes is PORT and another is SERVER. If the
server is up and running on the specified machine, listening on the
specified port you should be able to telnet to that port and see if
the server sends its startup protocol message. e.g. if PORT is 8888
and the SERVER is demo.easysoft.com you should be able to telnet to
port 8888 on demo.easysoft.com.

e.g. telnet demo.easysoft.com 8888

You should see something like this:

87FA9694x1:0:1998-1112-0000000001001:NT^02:4.0.1381^03:Intel^04:4^05:^06:p^07:1^

(Do not worry if it is not exactly the same as this depends on OOB
version, operating system and machine type).

If the telnet fails to connect then nothing is listening on that port
and you should check the port used on the server and make sure the
server is running. If you get connected but then see a connection
closed by foreign host message then you should see other questions in
this section.

If you are connecting to a non Windows server then check you
/etc/inetd.conf and /etc/services files or equivalent. These should be
similar to those below which are for the default installation:

/etc/services
esoobserver      8888/tcp                # Easysoft ODBC-ODBC Bridge

/etc/inetd.conf
esoobserver      stream  tcp     nowait  root    /bin/sh /bin/sh /usr/local/easysoft/server/server

This should have been done for you by the installation. The important
parts are:

[1] The name used in the /etc/services file should match the name used in
    the /etc/inetd.conf (esoobserver in the example).
[2] The 8888 is the port which inetd will listen to on the server's behalf.
    There must only be one 8888 in the /etc/services file. If 8888 is taken
    by another service simply replace it with an unused port number and
    change the PORT attribute in any odbc.ini files which reference this
    machine.
[3] The "/bin/sh bin/sh" columns in the /etc/inetd.conf file must be the
    path to a valid shell. If you suspect these trying running the named
    shell from the prompt e.g. /bin/sh. Sometimes, UNIX machines have a
    file called /etc/shells which lists valid shells.
[4] The last column in the inetd.conf file should be a path to a shell
    script which runs the esoobserver. The default installation is shown
    above where the shell script is:

    #!/bin/sh
    cd /usr/local/easysoft/server
    ./esoobserver inetd

    Check this script is executable and try running it. If esoobserver
    does not exist then you have not yet created a binary of the ODBC-ODBC
    Bridge linked with your ODBC driver. See BUILDING in the docs directory.

If you are connecting to a Windows server then you should look at the
following list for possible problems:

[1a] If on NT check that the NT service manager is running and the Easysoft
    ODBC-ODBC Bridge service is started. If the Easysoft service is not
    running start it.
[1b] If on Windows 95 then you have to start the esoobserver manually -
    see the Start Menu -> Programs -> Easysoft -> ODBC-ODBC Bridge
    program group and click on OOB Server.
[2] By default the service listens on port 8888. Run "netstat -a" from
    a DOS prompt to check that something is listening on port 8888.
[3] Check that the esoobserver.exe program runs by executing it from a
    DOS prompt. You should get a message saying the command line is
    missing a method followed by some help text.
[4] If on NT check the Application event log to see if there are any messages
    from the Easysoft service.
[5] The final checks all require examining the registry and are beyond
    the scope of this document. If you get to this stage please contact
    Easysoft Support for assistance.

3.2 I keep getting connection closed by foreign host messages when I try
------------------------------------------------------------------------
    to telnet to the port the server is listening on?
    -------------------------------------------------

First check all the points under the question above "I keep getting
connection refused error from the client?"

Connection closed by foreign host implies you got a connection then it
was prematurely disconnected.

If you are connecting to a non Windows server then you should check
the following:

[1] If you are running tcpwrappers make sure the client host is
    allowed to connect to the esoobserver service on the server
    machine. You will need to check your /etc/hosts.allow and
    /etc/hosts.deny files. See the man page on hosts_access and
    tcpwrappers. If your esoobserver entry in inetd.conf does not
    contain something like tcpd then you are probably not running
    tcpwrappers. Note that the default installation will not use
    tcpwrappers as this is a site consideration.

[2] Check that the script pointed to by the esoobserver entry in the
    inetd.conf file exists, is executable and runs the correct image.
    If you have not linked the Easysoft ODBC-ODBC Bridge server with an
    ODBC driver then this will be the problem. To access a remote database
    the server component of the ODBC-ODBC Bridge needs a local ODBC Driver.

[3] Check you system logs for other possible problems.

If you are connecting to a Windows server then we suggest calling
Easysoft Support once you've made the checks in the previous questions.

3.3 Why do my connections to the OOB server seem to be dropped after a while?
-----------------------------------------------------------------------------

The OOB Server has an inactivity timer which by default is set to 7200
seconds.  If a client connects to the server and does nothing for 7200
seconds (2 hours) the server will terminate that connection. This can
cause problems with applications using persistent connections
(e.g. PHP can do this) as if one of the connections is not used for 2
hours, it is terminated but PHP ( up to PHP 4 beta3) does not
recognise this and blindly attempts to continue with the connection.

The timeouts are there to stop unnecessary connections building up and
generally a useful feature. You can turn off the inactivity timeout by
setting it to 0 or just increase it to the period you desire.  See the
question "Are there any configurable options for the OOB" for
information on other OOB configurable parameters and how to set them.

3.4 Why do I get "Data source not found and no default driver" message when
---------------------------------------------------------------------------
    I am sure I have defined the DSN in my odbc.ini file?
    -----------------------------------------------------

Usually this message is returned when the DSN you specified in the
connection string cannot be found. However, the OOB client can also
return the error if insufficient attributes have been specified to
make a connection to the server. This does not usually arise in
Windows as when this happens the OOB client can throw up a dialogue
requesting you to define the missing attributes. In UNIX, there is no
standard way to do this and ODBC does not define any other way for the
OOB to communicate that you are missing attributes. The minimum set of
attributes defining a connection to an OOB Server is: Server, Port,
Transport and TargetDSN although in most cases you will have to define
LogonUser and LogonAuth as well. So, if you get this error and are
sure the DSN is defined, check the minimum attributes required for a
connection are all defined.

3.5 Why do I get authorisation failures from the client.
--------------------------------------------------------

There can be multiple reasons for this depending on which element of
the connection is turning down the connection. You have to look at the
ODBC error diagnostics from SQLError(), SQLGetDiagRec() or SQLGetDiagField()
to see where the connection is being turned down.

If the Easysoft ODBC-ODBC Bridge Client/Server has turned down the
connection then you will get a messages similar to this:

28000:1:1326:[Easysoft ODBC (Client)]Invalid authorization specification

Here you should check the LogonUser and LogonAuth attributes of your
client DSN. They should be a valid username and password for logging
on to the server machine. This has nothing to do with the database engine.

See the question "Why do I get "Invalid authorization specification"
when LogonUser and LogonAuth are set to a valid username and password"
where the error number (in the above case 1326) may be looked up.

If your database engine requires a username/password then these are
specified as UID and PWD in the connection string or alternatively
as the ODBC-ODBC Bridge attributes TargetUser and TargetAuth. Check your
odbc.ini (.odbc.ini or the ODBC Administrator) to make sure these are
valid for your database. Here is an example from MS SQLServer:

28000:1:18456:[Microsoft][ODBC SQL Server Driver][SQL Server]Login failed for user 'Fred'.

3.6 How do I find out why an ODBC call is failing?
--------------------------------------------------

The best why to discover the problem is to call SQLError or
SQLGetDiagRec with the same handle used in the ODBC SQL API
call. These functions return a status and error text which may used to
identify the problem.

A small C example is:

    ret = SQLDriverConnect(hdbc, NULL, in_connection_string, SQL_NTS,
    			   out_con_str, sizeof(out_con_str),
    			   &out_con_str_len, SQL_DRIVER_COMPLETE);
    if (!SQL_SUCCEEDED(ret))
    {
    	int		i=0;
	SQLRETURN	ret;
	char		state[7];
	SQLCHAR		text[1024];
	SQLSMALLINT	len;
	SQLINTEGER	native;
	char		cbuf[2048];

	while(SQL_SUCCEEDED(SQLGetDiagRec(SQL_HANDLE_DBC, hdbc, ++i, state,
    				          &native, text, sizeof(text), &len)))
    	{
            sprintf(cbuf, "error: %s:%d:%ld:%s\n",
	            state, i, native, text);
    	    fprintf(stderr, cbuf);
    	}
    	exit(1);
    }
    
This will print the error diagnostic for the last call using a
connection handle which may look like this:

error: IM002:1:0:[Easysoft ODBC (Client)]
 Data source not found and no default driver specified

The state value (IM002) may be looked up against the function to find
out why it failed.

You may retrieve error diagnostics from Perl DBI, PHP, mxODBC and
other ODBC interfaces in a similar way.

3.7 Why can't I connect to the data source?
-------------------------------------------

There can be many reasons for getting SQL_ERROR back from
SQLDriverConnect or SQLConnect.  See question "How do I find out why
an ODBC call is failing" first. The most likely reasons are:

IM002 - DSN or TargetDSN not found.  The DSN specified in the
        connection string could not be found by the OOB client in the
        odbc.ini file (or equivalent) (or the Driver Manager could not
        find the DSN) or the TargetDSN attribute was missing from the
        DSN or connection string. See also HY000 below.

28000 - Invalid authorization specification. Either the
        LogonUser/LogonAuth attribute pair or TargetUser/TargetAuth
        attribute pair were incorrect. The LogonUser/LogonAuth must be
        a valid username/password pair used by the OOB server to logon
        to the target machine. The TargetUser/TargetAuth are converted
        to UID=name,PWD=name and passed in to the remote
        SQLDriverConnect where the ODBC driver uses them for database
        logon (if they are required).

08001 - Client unable to establish connection. The machine specified
        in the Server attribute could not be found, it is not running
        the OOB server or one of many other possible networking
        issues.  Check the Server attribute in the specified DSN is a
        valid machine name (or IP address), check the name can be
        looked up via DNS (if you are using DNS or examine the hosts
        file), check you are on the same network by pinging the target
        server, check the Port attribute in the specified DSN is
        correct, try telnetting to the Server machine on port Port.

HY000 - A general error. A common mistake might be not specifying all
        the connection attributes required to connect to the
        server. e.g.  omitting the SERVER attribute from the DSN in
        the odbc.ini file in UNIX/VMS. In this case you will get IM002
        and a secondary error of HY000 explaining why.

4. Application/Driver-specific
------------------------------

4.1 How do I use Perl with OOB?
-------------------------------

You need to obtain the Perl modules, DBI and DBD::ODBC. These may be
obtained from your nearest CPAN archive. Instructions for building
Perl DBI, DBD::ODBC and OOB are contained in the Perl_DBI_DBD_ODBC
file contained in the docs directory of the OOB distribution.

4.2 What versions of Perl modules can I use with OOB?
-----------------------------------------------------

OOB has been tested with DBI 1.02 to 1.14 although it is likely to
work with more recent versions.

OOB has been tested with DBD::ODBC 0.20 to 0.28 although it is likely
to work with more recent versions.

You should check DBI and DBD to make sure you have the minimum Perl
requirements before attempting to install DBI, DBD::ODBC or OOB.

4.3 How do I use Apache/PHP with OOB?
-------------------------------------

You need to obtain the source distributions of Apache and PHP from
http://www.apache.org and http://www.php.net. Instructions for
building Apache and PHP with OOB can be found in the Apache_PHP file
contained in the docs directory of the OOB distribution.

Please make sure you carefully read the INSTALL files that come with
Apache and PHP as they contain valuable information that can save you
alot of headaches.

4.4 What versions of PHP (and Apache) can I use with OOB?
---------------------------------------------------------

OOB has been tested with Apache 1.3.n.

OOB has been tested with PHP 3.0.0 to 3.0.16, the first three betas
of PHP4 and should work with any version after 4.0.

4.5 Why can't I use bound parameters with MS Access
---------------------------------------------------

The MS Access ODBC Driver currently does not support SQLDescribeParam
which is often used by ODBC interfaces which use bound parameters (e.g
Perl DBD:ODBC). If the ODBC interface you are using requires
SQLDescribeParam to support bound parameters you must avoid binding
parameters when going to MS Access.

4.6 I don't like my odbc.ini in the same directory as my PHP/Perl script
------------------------------------------------------------------------
    as people browsing my web site may see it and it contains passwords.
    --------------------------------------------------------------------
    What do I do?
    -------------

As of the second beta of OOB (0.2.2.0) you can place your odbc.ini
file in the current users home directory or in the file pointed to by
the ODBCINI environment variable. From the third beta of OOB (0.2.4.0)
you can also put your DSNs in /etc/odbc.ini. You can also place the
sensitive information in the call to SQLDriverConnect by setting the
attributes in the in_connection_string parameter.

e.g. SQLDriverConnect(dbc,
                      "DSN=dsn_name;LOGONUSER=username;LOGONAUTH=password;",
		      ...);

Attributes set in the in_connection_string argument to
SQLDriverConnect override values in the odbc.ini file.

To set the ODBCINI environment variable from PHP use:
putenv ("<path>/odbc.ini");

To see what environment variables are set to from PHP use:
phpinfo();

4.7 ld: cannot open -lesoobcclient: No such file or directory
    ---------------------------------------------------------
    when attempting to link an application with the OOB
    ---------------------------------------------------

You need to tell the dynamic linker where to find the libesoobclient
shared object (there are some other required shared objects in the
easysoft/lib subdirectory of the installation path too).

For Linux:

In the beta releases, the installation script does not add entries to
the /etc/ld.so.conf file if the installing user is NOT root or if only
the client is installed. You need to add the paths to all the shared
objects in the OOB installation to /etc/ld.so.conf and rerun ldconfig
(usually in /sbin). e.g. if you installed OOB in the default location
you would add:

/usr/local/easysoft/lib
/usr/local/easysoft/oob/client

to /etc/ld.so.conf and then run /sbin/ldconfig. To be sure they are
picked up properly you can use /sbin/ldconfig -v where part of the
output for the default installation path would be:

/usr/local/easysoft/lib:
        libesrpc.so => libesrpc.so
        libsupport.so => libsupport.so
/usr/local/easysoft/oob/client:
        libesoobclient.so => libesoobclient.so

Note that you must be root to run ldconfig and probably, to edit
/etc/ld.so.conf.

For other UNIX platforms:

Read the above for Linux first. However, most platforms do not have
an equivalent of the /etc/ld.so.conf file and that usually means
you have to add the paths to the LD_RUN_PATH, LD_LIBRARY_PATH, SHLIB_PATH
or LIBPATH environment variables and then export them. e.g.

$ LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/easysoft/lib:/usr/local/easysoft/oob/client
$ export LD_LIBRARY_PATH

An alternative, although not one that Easysoft particularly recommends
is that you move the shared objects to a directory which is on your
linker's default search path (e.g. /usr/lib).

If you installed the unixODBC driver manager in the OOB distribution
you will want to add the path /usr/local/easysoft/unixODBC/lib to the
above.

4.8 Apache/PHP can't seem to find my odbc.ini file or
-----------------------------------------------------
     Datasource not found and no default driver error.
     -------------------------------------------------

When you start Apache with PHP built with ODBC support, PHP
immediately allocates an ODBC environment handle. Unfortunately, the
OOB searches for the odbc.ini file when an environment handle is
created and so your odbc.ini file needs to found at server
startup. This can be a nuisance since most people start Apache at
machine boot time from an rc script but locate their odbc.ini files in
the same directory as their PHP scripts. The best way around this is
to put all your DSN definitions in the /etc/odbc.ini (or
SYS$ROOT:odbc.ini for VMS) file.

4.9 undefined reference to xyz when making Apache/PHP
-----------------------------------------------------

e.g.

modules/php3/libphp3.a(unified_odbc.o): In function `_free_result':
/work/builds/php-3.0.11/functions/unified_odbc.c:192: undefined reference to `SQLFreeStmt'
modules/php3/libphp3.a(unified_odbc.o): In function `_results_cleanup':
/work/builds/php-3.0.11/functions/unified_odbc.c:208: undefined reference to `SQLFreeStmt'

Look at the linker line before the undefined reference messages start
and check that there is a -lesoobclient. If this is missing you have
probably misconfigured PHP as described below. You can usually check
this is what has happened by doing a grep for esoobclient in the top
level Makefile:

e.g.
/work/php-3.0.12-> grep esoobclient Makefile

which should show something like:

LIBS = -lgd pcrelib/libpcre.a regex/libregex.a -lgdbm
 -L/usr/local/easysoft/oob/client/lib -lesoobclient
 -lgd -lm -ldl -lcrypt -lnsl  -lresolv

The actual output will depend on the platform but should contain
"-lesoobclient".

The CUSTOM_ODBC_LIBS defines the name of the shared object which
provides the ODBC driver which in this case is the ODBC-ODBC Bridge
client shared object (libesoobclient.so, the .so depends on the
platform and may be .a or .sl). If the CUSTOM_ODBC_LIBS variable was
not set BEFORE making PHP Apache will not include a reference to the
shared object containing the SQL functions and hence the undefined
references.  See the Apache_PHP text file in the docs directory of the
distribution.

If you are not using a shell that allows variables to be assigned at
the same time as running a command then set CUSTOM_ODBC_LIBS to
"-lesoobclient" and then export the CUSTOM_ODBC_LIBS:

e.g.
> CUSTOM_ODBC_LIBS="-lesoobclient"
> export CUSTOM_ODBC_LIBS

4.10 Why do I get undefined symbols when running the Perl DBD::ODBC test?
------------------------------------------------------------------------

An example might look like this:

Can't load 'blib/arch/auto/DBD/ODBC/ODBC.so' for module DBD::ODBC: 
blib/arch/auto/DBD/ODBC/ODBC.so: undefined symbol: SQLDataSources
 at /usr/lib/perl5/5.00502/i686-linux/DynaLoader.pm line 168.

The problem depends on what symbol is undefined. If the symbol is
SQLDataSources or SQLDrivers then the likelihood is that you are
attempting to build a version of OOB prior to 0.4.0.0 with DBD::ODBC
0.21. Versions of the OOB prior to 0.4.0.0 are not compatible with
linking directly to DBD::ODBC 0.21. To use these older versions of OOB
with Perl DBD::ODBC 0.21 you must either:

[1] install a driver manager under Perl DBD::ODBC and then tell the
driver manager about OOB.

[2] download a newer version of OOB (0.4.0.0 or newer).

4.11 Why don't my PHP scripts appear to run on the web server?
-------------------------------------------------------------

Your first port of call should probably be the various PHP or Apache
(or whatever web server you are using) news groups, mailing lists and
FAQs. However, here are a few pointers specific to Apache/PHP.

[a] Did you build Apache with PHP?

[b] Make sure Apache knows what to do with a PHP script. You need to
    tell Apache in the httpd.conf (or one of the other config files)
    that files with the extension php3 or phtml should be passed to
    PHP. You do this with lines like this:

    AddType application/x-httpd-php3 .php3
    AddType application/x-httpd-php3 .phtml

    These tell Apache to pass files ending in .php3 and .phtml to PHP
    for processing.

[c] Check you can run a simple PHP script. Create a file called test.php3
    in the htdocs directory of your web server containing:

    <html>
    <head>
    <title>Test</title>
    </head>
    <body>
    <p>
    You should see PHP info below:
    <?
    	phpinfo();
    ?>
    </body>
    </html>

    Then use the URL http://my_web_server/test.php3 (replace
    my_webserver with the appropriate machine name and domain) from
    your browser to see if you get a page of PHP information back.  If
    you don't something far more serious is wrong with your Apache/PHP
    configuration than not being able to make ODBC connections from
    PHP through the OOB.

If all the above OK you might try:

[a] Examine your Apache error log. This file is named in your Apache
    configuration file(s) (e.g. httpd.conf) with the "ErrorLog"
    setting.

[b] Make sure you followed the PHP INSTALL file and copied the sample
    php ini file (php3.ini-dist) to the correct place. Some options in
    this file can prove useful for debugging:

    [1] "track_errors = On" stores the last error in the php_errormsg
        variable.
    [2] "error_reporting = 7" outputs Normal errors, Normal warnings,
        Parser errors.
    [3] "error_log = filename" defines the file errors/warnings will be
        sent to.

If PHP appears to be working but you do not get data back through OOB
then see the questions on turning logging in the OOB on.

4.12 How can I put attributes other than the DSN in my Perl DBI->connect call?
-----------------------------------------------------------------------------

From DBD::ODBC 0.21 you can put all of the connection attributes you
can specify in your odbc.ini in the connection string passed to
DBI->connect().

e.g.

Suppose your odbc.ini looked like this:

[dsn_name]
Server = demo.easysoft.com
Port = 8888;
Transport = tcpip
LogonUser = fred
LogonAuth = password
TargetDSN remotedsn

You can do away with the entire odbc.ini file and use the following
Perl instead:

my $DSN = 'Server=demo;Port=8888;Transport=tcpip';
$DSN = $DSN . 'LogonUser=fred;LogonAuth=password;TargetDSN=remotedsn';

my $dbh = DBI->connect("dbi:ODBC:$DSN",
		       "database_user,
		       "database_password)
          || die "Database connection failed: $DBI::errstr";

This can be particularly useful if you want to hide your usernames and
password for instance if you did not want them visible in the odbc.ini
file. You could retrieve the username and password from somewhere else
or even prompt for them.

4.13 Why do I get parse errors when compiling PHP with OOB?
----------------------------------------------------------

There are a number of reasons why you may get parse errors whilst
building PHP and OOB many of which are nothing to do with OOB. However
some that we have seen are:

In file included from /usr/local/easysoft/oob/client/include/odbc.h:2,
                 from functions/php3_unified_odbc.h:199,
                 from internal_functions.c:90:
/usr/local/easysoft/oob/client/include/sqlext.h:1652: parse error before `0'
/usr/local/easysoft/oob/client/include/sqlext.h:1756: parse error before `0'

In this case a beta tester was building PHP with informix
(--with-informix) and custom ODBC support. The problem with doing this
is that the both drivers define many of the same symbols. In this case
SQLCHAR was defined as '0' by Informix. If you want multiple ODBC
drivers available from PHP, Easysoft recommend that you install a
driver manager (e.g.  unixODBC http://www.unixodbc.org) and then tell
the driver manager about your multiple drivers.

4.14 How do I tell Apache to pass PHP scripts to the PHP interpreter?
----------------------------------------------------------------------

You should read the INSTALL file that comes with PHP very carefully
before using Apache and PHP. It has instructions which tell you how to
make Apache pass PHP scripts to the PHP interpreter. Briefly you must
add lines like:

AddType application/x-httpd-php3 .php3

or
 

AddType application/x-httpd-php3 .phtml

to your Apache srm.conf file. Note that this has changed for PHP4
where the type is now application/x-httpd-php4.

4.15 How can I find out why my PHP script is not working?
--------------------------------------------------------

There are general guidelines to help you in the PHP documentation and
via a number of PHP mailing lists, you should read those first. A
quick method is to turn on tracing in PHP. You can do this by editing
your /usr/local/lib/php3.ini file (if you don't have one then see the
INSTALL file that comes with PHP which documents a template ini file).

Ensure error_reporting is set to 7, log_errors is set to On and set
error_log to the name of a file (e.g. /tmp/php_errors). Once you have
made these changes restart Apache and all the normal errors and
warnings and parser errors will be logged to the file.

You can also set track_errors to On which makes the last error
available in the $php_errormsg variable.

4.16 How can I debug my Perl DBI, DBD::ODBC?
--------------------------------------------

Print out the contents of $DBI::errstr when an error occurs. This
often shows more detail, e.g. If the ODBC driver posts multiple errors
all of them can be seen.

You can enable Perl DBI tracing for all handles using DBI class method
with:

DBI->trace($trace_level)
DBI->trace($trace_level, $trace_filename)

To enable trace information for a specific handle use the similar
$h->trace.

Trace level is a number between 0 and 9 but usually 2 is sufficient.

More detailed information is included in the Perl documentation. Try
typing perldoc DBI. You might also like to look up the DBI_TRACE
environment in the Perl DBI documentation.

Recent versions of DBI include DBI::Shell which allows you to use DBI
to examine your database from a shell session. This can be a useful of
verifying that you driver is installed and working. Start dbish with
either:

perl -MDBI::Shell -e shell
or
dbish

You will be provided with a choice of drivers and then once a driver
is chosen, a choice of data sources. e.g.:

[martin@asegeir db]$ dbish
DBI::Shell 10.6 using DBI 1.13 

WARNING: The DBI::Shell interface and functionality are
=======  very likely to change in subsequent versions!

Available DBI drivers:
 1: dbi:ADO
 2: dbi:ExampleP
 3: dbi:ODBC
 4: dbi:Proxy
Enter driver name or number, or full 'dbi:...:...' DSN: 3

Enter data source to connect to: 
 1: DBI:ODBC:Postgres
 2: DBI:ODBC:test
Enter data source or number, or full 'dbi:...:...' DSN: 2
Connecting to 'DBI:ODBC:test' as ''...
@DBI:ODBC:test> 

You can now enter dbish commands and SQL to query/change your
database.  A good start is usually "/table_info" which lists all your
tables. See perldoc DBI::Shell for a list of the commands.

4.17 Why do I keep getting data truncated errors in my Perl?
------------------------------------------------------------

If you are getting truncation errors when retrieving data for a column
check what sort of column it is. Perl DBI needs to be told about long
columns or the data will be truncated. You can do this just after a
DBI->connect with:

$dbh->{LongReadLen} = 32768; # some big number

4.18 Where can I find more information about Perl DBI and DBD:ODBC?
-------------------------------------------------------------------

Perl DBI and DBD page:
http://dbi.perl.org/
http://www.symbolstone.org/technology/perl/DBI/index.html

DBI Users mailing list archive:
http://www.bitmechanic.com/mail-archives/dbi-users/

The Perl you need to know (for web authoring):
http://wdvl.com/Authoring/Languages/Perl/PerlfortheWeb/index.html

Recently (March 2000) the long awaited book by Alligator Descartes and
Tim Bunce, "Programming the Perl DBI" was released (ISBN
1-56592-699-4).  This is an excellent book for anyone writing Perl DBI
and DBD::ODBC.

4.19 Why does my second connection to MS Access hang?
----------------------------------------------------

You may notice if you try attaching a MS Access ODBC driver datasource
to the MS Access application in windows that it does not let you do
this.  Easysoft have seen problems making more than one simultaneous
connection from UNIX through the OOB to the MS Access ODBC driver (
specifically hanging). We think that the MS Access ODBC driver dll may
contain some shared data that is incompatible with our default
configuration of a multi-threaded OOB server. You can work around this
problem by changing the OOB Server to run multi-process instead of
multi-threaded.

According to Microsoft's web site 
(http://www.microsoft.com/data/mdac21info/MDAC21sp2manifest.htm)

==========
Known Issue: ODBC Jet driver in multithreaded environments 
Component: ODBC Jet driver 

When running in a multithreaded or stress environment such as IIS, it
is recommended not to use ODBC because of issues with threading in the
driver as well as the Jet engine. The recommendation for this
situation is to work with the OLE DB provider for Jet.
==========

To make the OOB Server run multi-process instead of multi-threaded use
the OOB Server administration interface by browsing
http://mywindowsmachine:8890. Select Configuration, Change
Configuration and then check the MultiProcess checkbox. Click on
submit. If the OOB Server configuration page had an
"AutoUpdateConfiguration" checkbox and it was not checked you will
need to restart the OOB Server Service. Versions of the OOB Server
administration interface without the "AutoUpdateConfiguration"
checkbox do not need the service restarting.

4.20 Why am I having intermittent problems with a particular ODBC driver?
-------------------------------------------------------------------------

Some ODBC drivers are not thread-safe and by default the OOB Server
for Windows runs multi-threaded. This can give rise to a whole host of
intermittent and peculiar errors. You should make the OOB server run
multi-process so that there is only ever one thread at a time in the
ODBC driver. See the question above for the method of making the OOB
server run multi-process.

Drivers we have encountered that it is best to set the OOB server to
run multi-process for are MS Access ODBC, Freedom Intelligence,
Navision and Margin Minder.

4.21 Can I use PHP with OOB and driver X?
-----------------------------------------

You cannot build PHP with multiple ODBC drivers or driver managers
e.g. you cannot use any two of the configure options from the list
below (current of PHP4b3):

--with-custom-odbc
--with-iodbc
--with-esoob
--with-unixODBC
--with-openlink

If you want to access multiple ODBC drivers from PHP the best method
is to install the unixODBC driver manager and then tell the unixODBC
driver manager about your ODBC drivers.

You can build PHP with an ODBC driver and other database drivers such
as Oracle or MySQL as these drivers do not provide the same ODBC API.

4.22 Why doesn't a query return recently inserted data?
-------------------------------------------------------

Insert statements seem to work okay and an immediate select with the
same cursor works to display the data, but when I retry the query the
data is gone.

Some ODBC enabled languages such as Perl and Python (mxODBC) have
autocommit set to off by default. (In PHP, however autocommit is set
to on by default)

There are two options to ensure that insert statements are committed
to the database.

1. Ensure that the relevant autocommit flag is switched on in your
   connection.

2. Use appropriate commit and rollback methods in your script.


See the following resources for detailed information on how to do this
in individual languages: -

Python - mxODBC
http://www.lemburg.com/files/python/mxODBC.html

Perl
perldoc DBI or http://www.perl.org

PHP 
http://www.php.net

4.23 Why cannot I use multiple active statements?
-------------------------------------------------

Multiple active statements is an ODBC driver facility.

The ODBC-ODBC Bridge will allow multiple statements on a connection if
the ODBC driver allows this.

The ODBC API defines a method of obtaining whether a driver handles
multiple active statements. 

In ODBC 2.0 you need to call SQLGetInfo() requesting
SQL_ACTIVE_STATEMENTS. This returns a 16 bit integer value specifying
the maximum number of active statements that the driver can support
for that connection. If there is no limit of the limit is unknown,
this value will be returned as zero.

In ODBC 3.0 you need to call SQLGetInfo() requesting
SQL_MAX_CONCURRENT_ACTIVITIES. This returns a SQLUSMALLINT value
specifying the maximum number of active statements that the driver
can support for that connection. A statement is defined as active if
it has results pending, with the term "results" meaning rows from a
SELECT operation, or rows affected by an INSERT, UPDATE or DELETE
operation (such as a row count), or if it is in a NEED_DATA
state. This value can reflect a limitation imposed by either the
driver or the data source. If there is no specified limit or the limit
is unknown, this value is set to zero.

With MS SQL Server, whilst you may allocate multiple statement handles
against a connection, you can only have one statement with a rowset
associated with it (using the default result sets). If you attempt to
use multiple active statements in MS SQLServer you will get an error
similar to the following:

[Microsoft][ODBC SQL Server Driver]Connection is busy with results for 
another hstmt (SQL-S1000)

There appear to be ways around this (at least in SQL server 6.5) but
they all involve clearing the remainder of the current resultset which
is generally not useful.

See http://msdn.microsoft.com/library/psdk/sql/6_030_2.htm for more
information on this.

If you need to keep things simple at the application end and have a
single connection then you can employ the Easysoft SQL Engine on the
server (i.e. the machine where the OOB server resides). This allows
you to have a single connection and open multiple statements against
SQL Server or any other ODBC datasource.

For information on the Easysoft SQL Engine see

http://www.easysoft.com/products/sql_engine/main.phtml

Failing that you have to employ multiple connections from your
application.

4.24 Why does Perl DBD::ODBC appear to open the DEFAULT datasource with OOB?
----------------------------------------------------------------------------

Since DBD::ODBC 0.21, Perl has required an ODBC driver manager (or at
least some of the functions a Driver Manager supplies). In addition,
since 0.21 the DBD::ODBC module connection code (dbdimp.c) started
calling SQLDriverConnect first with your DSN name and only if that
failed called SQLConnect with the same DSN name. The problem is that
SQLDriverConnect is supposed to take a list of attributes of the form:

attribute=name;

and a DSN should be specified as "DSN=name;". Perl DBD::ODBC does not
appear to append the "DSN=" to the DSN before calling SQLDriverConnect
and so the OOB follows ODBC and assumes a DSN=DEFAULT. If the DEFAULT
DSN is not found (likely), DBD::ODBC tries calling SQLConnect with the
same DSN name but SQLConnect only takes a DSN name and does not
require the "DSN=" so this tends to work.

If the time taken to go through this process bothers you change the
name on your calls to DBI->connect to "DBI:ODBC:DSN=dsnname".

4.25 Why do I get corrupted text columns back from MS SQLServer
---------------------------------------------------------------

We have had reported to us a problem accessing text fields in MS
SQLServer.  The reporter was attempting to retrieve multiple columns
defined as SQLServer "text" in PHP and always retrieved garbage in the
second text column. This problem only appears to happen when
retrieving multiple text fields from a table with SQLGetData and
occurs for the second text column retrieved. PHP sees that text fields
in SQLServer can be very long so instead of binding the column (as
usual) it uses SQLGetData. This problem could occur in any other ODBC
interface if SQLGetData is used for multiple text fields.

The specific report involved a table created as follows:

create table BENCH_TEXT (f1 integer, f2 text, f3 text)
insert into BENCH_TEXT values(1, 'some text', 'some text')
select f1, f2, f3 from BENCH_TEXT

The f1 and f2 columns are retrieved OK with SQLGetData but when the f2
column is requested with SQLGetData the returned StrLen_or_IndPtr
value is usually too short and the data is garbage.

After a search of the net we discovered a similar report by Chad
Slater-Scott which read:

Subject: BUG: Service Pack 1 on SQL7.0 (SQLExtendedFetch Returns
         metadata on SQLGetData)
Date: 09/27/1999
Author: Chad Slater-Scott <avacado@usa.net>

Just wanted to let you all know that SP1 For SQL Server has a new
bug. After using SQLExtendedFetch or SQLFetchScroll to retrieve
records using SQL_ABSOLUTE or SQL_RELATIVE positioning, a SQLGetData
call to a text field will return garbage.  This is not reproducible if
the text field is the only field selected or if you the text field is
the first field called.  In order to reproduce it, another field value
must be retrieved using SQLGetData.  I reported this to Microsoft and
a Bug has been filed.  If any of you are using this sequence of calls
and have installed SP1, check your stuff for garbage on the text
fields.  The Bug ID is 56509 is want to track its status.

We have been told that the problem is in the SQLServer driver included
in SP1 for SQLServer and SP6 for NT. The version with the problem
appears to be C:\winnt\system32\sqlsvr32.dll (3.70.06.90) and the
working version is 3.70.0623.

Our machines running SQLServer 7 and NT 4 sp4 appear OK.

4.26 Why does a build of PHP4 RC1 and OOB fail?
----------------------------------------------

If you are attempting to build PHP4 RC1 with OOB you will probably get
compilation errors such as:

php_odbc.c: In function `php_if_odbc_execute':
php_odbc.c:849: parse error before `FAR'
php_odbc.c:852: parse error before `FAR'

This problem is due to someone adding code to PHP4 which expects FAR
to be defined (FAR was an old Win16 macro). OOB header files do not
define FAR as OOB only runs on UNIX, VMS and WIN32. PHP4 has now be
changed to remove the use of FAR and this change is available in the
latest CVS tree. Until the next RC is released, if you do not have
access to the CVS tree the quickest solution is to define CFLAGS as
-DFAR="" before running configure.

e.g.
CFLAGS=-DFAR=""
export CFLAGS
./configure --enable-track-vars ... etc etc

4.27 Why do I get Driver's SQLAllocHandle on SQL_HANDLE_ENV failed with the
---------------------------------------------------------------------------
      Microsoft Oracle ODBC driver?
      -----------------------------

When connecting to a DSN using the Microsoft Oracle ODBC driver
SQLAllocHandle/SQLAllocEnv fails and SQLGetDiagRec or SQLError
returns:

IM004:1:0:[Microsoft][ODBC Driver Manager]
Driver's SQLAllocHandle on SQL_HANDLE_ENV failed

You need to install the NET 8 libraries which may be obtained by
installing the Oracle client. The Oracle ODBC driver includes them so
this problem does not occur when the Oracle ODBC driver is used.

4.28 Why can't I run CGI programs using OOB under
-------------------------------------------------
     Netscape Enterprise Server?
     ---------------------------

By default the Netscape Enterprise Server does not export environment
variables to the CGI program. We found this reference which explains
how to make it export environment variables:

http://help.netscape.com/kb/corporate/19960804-40.html

On most UNIX platforms you need to export LD_LIBRARY_PATH by adding
the following to your obj.conf file:

Init fn="init-cgi"
LD_LIBRARY_PATH="<path-to-easysoft>/oob/client:<path-to-easysoft>/lib"

4.29 Why does a query on columns containing colons in the name fails from
-------------------------------------------------------------------------
      DBD::ODBC?
      ----------

One of our customers were trying to issue a query like this:

select aa:bbbb from table where ccc like 'name%'

and received the following error:

DBD::ODBC::db prepare failed: [xxx][yyy] Column not found:
aa? (SQL-S0000)(DBD: st_prepare/SQLPrepare err=-1) at
file.cgi line nn.
Can't call method "execute" on an undefined value at
file.cgi line nn.

It appears that this problem is restricted to column names containing
colons and if there is a space between the colon and the next word it
works fine. Interestingly, Oracle uses the : syntax for parameters.
Investigation of the dbdimp.c showed code in dbd_preparse which
translates aa:bbbb to aa? and assumes bbbb is a bound parameter.

We currently do not know the work around for this but are currently
investigating.

4.30 Why do I not get a list of all the tables and columns in a database?
-------------------------------------------------------------------------

By default OOB uses metadata blockfetchmode which is an optimisation
speeding up the retrieval of metadata result sets. Some ODBC drivers
do not work properly with metadata blockfetchmode which binds the
columns in the result set and sets the row array size. The symptom is
usually that you see the first two tables/columns and then every 10th
table/column and all the others are missing. If you suspect you are
having this problem disable metadata blockfetchmode in your DSN by
either:

[1] In the Windows OOB DSN, uncheck metadatablockfetch.
[2] In UNIX, add MetaDataBlockFetch=0 to the affected DSNs in your odbc.ini
    file.
[3] Pass MetaDataBlockFetch=0 in the connection string.

At present we have only had this reported for the tickets.com ODBC
driver.

This attribute is only available in OOB 1.0.0.13 onwards.

In versions prior to 1.0.0.13 you can do one of the following:

[1] UNIX/OpenVMS
    Add

    {Settings}
    Flags = 0x8 

    to the top of an odbc.ini file in the current working directory of
    your application.
[2] In Windows add 8 to the registry key:

HKEY_LOCAL_MACHINE\
SOFTWARE\
EASYSOFT ODBC-ODBC BRIDGE\
CONFIGURATION\
SYSTEM\
SETTINGS\
FLAGS

4.31 Why do I get a transaction already started error calling a procedure?
--------------------------------------------------------------------------

This often happens if the procedure mixes insert/update and select
operations and auto-commit has been turned off. This is quite a common
question from people using Perl where the script connects with
autocommit turned off (as in one of the OOB examples):

my $dbh = DBI->>connect($ENV{DBI_DSN},
                        $ENV{DBI_USER},
                        $ENV{DBI_PASS},
                        {
                            RaiseError => 1,
                            AutoCommit => 0
                            }
                        ) || die "Database connection failed: $DBI::errstr";

4.32 Why do I get ODBC driver authentication denied when using  unixODBC's
--------------------------------------------------------------------------
     isql and DataManager?
     ---------------------

isql and DataManager (in unixODBC 1.8.8 and prior versions at least)
call SQLConnect passing a database username and password even if you
do not specify them. isql, takes two optional arguments after the DSN
which are the database username and database password. If you omit
them then isql passes empty strings to OOB which believes a
username and password were specified and hence does not pull the
TargetUser and TargetAuth out of the DSN.

If your ODBC driver requires a username and password and you are using
isql or DataManager you must specify them either on the command line
or in the dialogue DataManager pops up.

4.33 Why do I get "IM004, Driver's SQLAllocHandle on SQL_HANDLE_HENV failed"
----------------------------------------------------------------------------
      connecting to DB2?
      ------------------

This error generally occurs in UNIX because the environment variable
DB2INSTANCE is not set and exported before the OOB Server is started.
You need to either:

[1] edit /usr/local/easysoft/oob/server/server and add 
    DB2INSTANCE=xyz
    export DB2INSTANCE
    before the cd at the end of the file or
[2] defined DB2INSTANCE and export it before starting esoobserver
    standalone.

4.34 In PHP, why can I only use/get column names up to 30 characters when
-------------------------------------------------------------------------
     my database supports much longer column names?
     ----------------------------------------------

PHP, up to version 4.0 (final release) restricts column names to 30
characters. The OOB places no restrictions on column name lengths.

4.35 Why do my Perl scripts complete but end in a segmentation violation?
-------------------------------------------------------------------------

Did you build Perl DBD::ODBC with unixODBC?
If so, you should ensure unixODBC is built without threads (use the
configure option --enable-threads=no).

The unixODBC driver manager that comes pre-built with the standard OOB
is built without threads being enabled. OOB distributions containing
"mt" in the distribution name are thread-safe and currently will not
work with Perl.

4.36 Why are my connections to MS SQLServer so slow?
----------------------------------------------------

Microsoft introduced changes to MS SQLServer 7.0 which can cause
connections to an OOB Server and MS SQLServer and subsequent
operations to be very slow. These settings elevate the priority of
SQLServer to such an extent that other processes on the machine do not
get a look in. (e.g.  when someone is issuing a query, TaskManager
even stops displaying). If you are running MS SQLServer 7 and the OOB
Server is running on the same machine as SQLServer you should try the
following:

[1] The settings are available from the properties menu of the
    Enterprise Manager.  The settings are "Boost SQL Server Priority
    on Windows NT" and "Use NT fibres".  When these are set NT is so
    busy servicing SQLServer, the accept() in the OOB Server can take
    some time due to NT not scheduling any other process.

[2] Move your OOB Server to another machine where MS SQLServer is not
    running.

4.37 Why does test 13 of the simple test in Perl DBD::ODBC fail?
----------------------------------------------------------------

Test 13 in the simple test is testing SQLDataSources. If you have
built Perl DBD::ODBC directly with OOB (without a driver manager) then
SQLDataSources in OOB only lists data sources in the odbc.ini file in
the current working directory. If the odbc.ini file in the current
working directory does not contain any data sources then
SQLDataSOurces returns SQL_NO_DATA and the DBD::ODBC test classes this
as a fail.  Either add a data source to the odbc.ini file in the
current working directory, build with an ODBC driver manager or ignore
this failure.

4.38 Why do I get compile warnings in php_odbc.c with OOB 1.0.0.15
------------------------------------------------------------------

When compiling PHP 4.0.n with OOB 1.0.0.15 you may see compilation
warnings about implicit conversion of integer to pointer. There are
updated versions of the sqlext.h and sqltypes.h header files included
with OOB posted to the OOB news group. Alternatively, upgrade the OOB
client to 1.0.0.16 or above.

4.39 Why do I get compile errors building Perl DBD::ODBC on AIX?
----------------------------------------------------------------

The DBD::ODBC source code contains C++ comments which some AIX
compilers do not accept. You can either convert the c++ comments in
dbdimp.c to normal C comments (// text <end of line> becomes /* text
*/) or edit the generated makefile to add -qcpluscmt (add this to
CCFLAGS).

4.40 Why is my column data truncated at 4096 bytes from PHP?
------------------------------------------------------------

If you built PHP yourself make sure you copied the php.ini-dist file
from the PHP source tree to /usr/local/lib as documented in the PHP
INSTALL file. The php.ini file contains the default setting for
uodbc.defaultlrl (or odbc.defaultlrl) of 4096 which limits the amount
of data retrieved from a single column to 4096 bytes. You can increase
defaultlrl to get more data without changing your PHP or you can use
the PHP function called odbc_longreadlen.

4.41 Do I have to set DBI_DSN, DBI_USER and DBI_PASS  environment variables
---------------------------------------------------------------------------
     before running my Perl script?
     ------------------------------

Not unless your Perl script uses these environment variables.

The DBD::ODBC installation and test procedure requires these environment
variables to be set because it calls DBI->connect without any arguments.
From the DBI documentation:

=====
$dbh = DBI->connect($data_source, $username, $password, \%attr)

The $data_source value should begin with "dbi:driver_name:". The
driver_name specifies the driver that will be used to make the
connection. (Letter case is significant.)

As a convenience, if the $data_source parameter is undefined or empty,
the DBI will substitute the value of the environment variable DBI_DSN.
If just the driver_name part is empty (i.e., the $data_source prefix
is "dbi::"), the environment variable DBI_DRIVER is used. If neither
variable is set, then connect dies.

If $username or $password are undefined (rather than just empty), then
the DBI will substitute the values of the DBI_USER and DBI_PASS
environment variables, respectively.  The DBI will warn if the
environment variables are not defined.
=====

The documentation also suggests that using these environment variables
is not recommended for security reasons and that this mechanism is
intended to simplify testing. To avoid using the DBI_xyz environment
variables specify the values directly in the call to DBI->Connect:

DBI->Connect('dbi:ODBC:dsn_name', 'username', 'password')

Obviously you can prompt for the username/password.

4.42 Why do I get "undefined symbol: SQLParamData" when testing DBD::ODBC?
--------------------------------------------------------------------------

When building DBD::ODBC with unixODBC and running the make test you
see something like this:

PERL_DL_NONLAZY=1 /usr/bin/perl -Iblib/arch -Iblib/lib 
-I/usr/lib/perl5/5.00503/i386-linux -I/usr/lib/perl5/5.00503 -e 'use 
Test::Harness qw(&runtests $verbose); $verbose=0; runtests @ARGV;' t/*.t
t/01base............install_driver(ODBC) failed: Can't load 
'blib/arch/auto/DBD/ODBC/ODBC.so' for module DBD::ODBC: 
blib/arch/auto/DBD/ODBC/ODBC.so: undefined symbol: SQLParamData at 
/usr/lib/perl5/5.00503/i386-linux/DynaLoader.pm line 169.

The undefined symbol SQLParamData is reported by the dynamic linker as
the first symbol it looked for but could not find.

This happens when building DBD::ODBC with unixODBC because the
Makefile.PL is now incompatible with newer unixODBC releases. The
Makefile.PL searches ODBCHOME/lib for *odbc*.* and finds libodbc.so
AND libodbcinst.so. It then goes on to choose libodbcinst.so which is
the incorrect shared object.  You can check this by running ldd on
blib/arch/auto/DBD/ODBC/ODBC.so where you will probably see something
like:

libodbcinst.so1 (libc6) => /usr/local/easysoft/unixODBC/lib/libodbcinst.so1

To fix this edit the Makefile.PL and delete the second '*' in the line:

    elsif ($myodbc eq 'unixodbc') {
        my @ilibs = <$odbchome/lib/*odbc*.*>;

so it becomes:

    elsif ($myodbc eq 'unixodbc') {
        my @ilibs = <$odbchome/lib/*odbc.*>;

Now rerun perl Makefile.PL and it should pick up the correct libodbc
shared object.

4.43 Why does phpinfo() display "Active Persistent Links" of 0/1 when I
-----------------------------------------------------------------------
     know there are more open connections to my database?
     ----------------------------------------------------

Please read http://www.php.net/manual/features.persistent-connections.php.

Currently in UNIX, Apache and PHP is a single-threaded process where
the main web server creates children to deal with HTTP requests. When
you set allow_persistent to On in your php.ini file and use
odbc_pconnect a persistent connection will be created in one of the
HTTP child processes.  However, it is up to the main HTTP which child
will handle the request and the persistent connection only exists in
that httpd child.  Similarly when you browse a PHP page which calls
phpinfo(). You cannot control which HTTP child process will answer the
request so it may be one which has never connected to the database
(Active Persistent Links = 0) or one which has connected to the
database (Active Persistent Links = 1).  This is easy to confirm for
yourself:

[1] Stop http server and configure it so only you can connect (or
    arrange that no-one else connects to it whilst you are testing).
    Make sure allow_persistent = On in your php.ini file.
[2] Start http server.
[3] Browse a php page which calls phpinfo() - it will display 
    Active persistent Links = 0. No matter how many times you refresh
    this page it will show 0.
[4] Browse a php page which connects to your database with odbc_pconnect().
[5] Browse the page in [3] again and hit refresh a number of times.
    You will see "Active persistent Links" change between 0 and 1 even
    though there is no activity on your web server other than
    yourself. This is the main HTTP server farming out yout HTTP
    request to different children, one of which made the conenction in [4]
    and all the others which have never made a database connection.

The only way to get Active Persistent Links greater than 1 is to open
more than one persistent connection in a single PHP script.

4.44 Why don't my changes to PHP odbc settings in php.ini file get picked up?
-----------------------------------------------------------------------------

On some versions of php the distributed example php.ini-dest file
contains a section containing ODBC settings where the names are
uodbc.xyz but PHP looks for odbc.xyz. You need to edit the php.ini
file and change the uodbc to odbc for the settings you have changed
from the defaults.

4.45 Why doesn't PHP's max_persistent setting limit the total number of
-----------------------------------------------------------------------
     ODBC connections to my database?
     -------------------------------

Please see the question "Why does phpinfo() display Active Persistent
Links of 0/1 when I know there are more open connections to my
database".

The max_persistent limit is per HTTP server process. Setting
max_persisent to 1 does not limit the total number of ODBC connections
to 1. Eventually, all the HTTP server children will probably have 1
connection to the database.

4.46 I don't want to rebuild Apache for PHP/ODBC support, what can I do?
------------------------------------------------------------------------

If you already have Apache installed on your machine but it does not
have PHP support you may not want to rebuild Apache to include PHP.
If your Apache was built with DSO support then you can add PHP (or any
other module) to Apache afterwards without rebuilding Apache.  In
order to determine if your Apache has DSO support you need to run
Apache's -l option to list the included modules:

./httpd -l

You need to look for mod_so.c.

e.g. in a standard Linux/RedHat 6.1 distribution Apache is installed
in /usr/sbin:

> cd /usr/sbin/
> ./httpd -l
Compiled-in modules:
  http_core.c
  mod_so.c

Here Apache was built with DSO support so you can build PHP with ODBC
support separately and tell Apache to load it separately.

When building PHP with ODBC support for Apache with DSO support read
the php-x.y.z/INSTALL file in the PHP distribution and follow the
instructions under "INSTALL (DSO - Dynamic Shared Object)". Basically
you need to configure PHP with the --with-apxs and --with-esoob (or
--with-unixODBC) options.

Once PHP is built and installed you will need to add a LoadModule
command to your httpd.conf file to enable PHP in Apache (see the
Apache and PHP INSTALL files for details).

4.47 Why does make test for Perl DBD::ODBC fail with "invalid object name"
--------------------------------------------------------------------------
     errors?
     -------

The make test for Perl DBD::ODBC attempts to create tables in the
database, populate them and read the data back. If you use a DSN which
points to a database which is read-only (or for which you do not have
permission to create tables) the tests will fail. This will happen if
you use the demo DSN which is supplied with OOB as it points to our
database which is read-only as far as external users are concerned. A
typical failure when going to our demo datasource looks like:

t/02simple..........DBD::ODBC::db do failed: 
[unixODBC][Microsoft][ODBC SQL Server Driver][SQL Server]
CREATE TABLE permission denied, database 'pubs', owner 'dbo'. 
(SQL-37000)(DBD: st_execute/SQLExecute err=-1) at t/ODBCTEST.pm line 80.
DBD::ODBC::db prepare failed: 
[unixODBC][Microsoft][ODBC SQL Server Driver][SQL Server]
Invalid object name 'PERL_DBD_TEST'. (SQL-S0002)

4.48 Why is my NT OOB Server using alot of CPU, my ODBC connections go to
-------------------------------------------------------------------------
     MS SQLServer?
     -------------

Obviously, there could be many reasons for this. It should be
remembered that all the CPU used and showing in Task Manager for
esoobserver includes the CPU used by the driver manager and any ODBC
drivers you are using.  If the OOB Server is running threaded (the
default) then CPU usage SEEN in Task Manager will be greater than if
the OOB Server is running MultiProcess.  This is simply due to the
fact that when in MultiProcess mode a new process is created to handle
each incoming connection, when that connection is closed the OOB
Server process handling it will die and you cannot see the CPU usage
for a dead process.

The most common scenario where the OOB Server appears to be using alot
of CPU is when it is handling a connection MS SQLServer, a result-set
has been generated but not consumed/closed and an attempt to create a
new result-set is made. In this case, the MS SQL Server ODBC driver
appears to spin-wait, consuming alot of CPU. We have seen this
ourselves on our web site and a few customers have hit the same
problem - it is always down to not closing the result-set. The example
below is a real example which occurred in a PHP script, it is provided
in the hope it will help others avoid this problem.

The table in the MS SQL Server database contained a column defined as
TEXT. One row in the table contained one of these text columns with
over 7K in it but PHP's odbc.defaultlrl (default long read length) was
set to the default of 4K. A query was issued which retrieved all of
the columns from this table. PHP bound columns for most of the columns
in the table but used SQLGetData to retrieve the TEXT column as it was
defined as SQL_LONGVARCHAR. The problem arises because when PHP's
odbc_result() was called to retrieve the result-set data, PHP passed a
4K buffer which was insufficient, MS SQL Server returned 4K and
SQL_SUCCESS_WITH_INFO and hence the result-set is not consumed (ODBC
says you can call SQLGetData multiple times on the same column to
retrieve the data in chunks).  The PHP script then goes on to issue
another query which hangs. At this stage the OOB Server on the NT
machine showed alot of CPU usage which was tracked down to
spin-waiting in the ODBC driver. This problem can be avoided very
simply by closing any result-set you generate, in PHP that means
calling odbc_free_result(), in ODBC terms it is a call to
SQLFreeStmt(SQL_CLOSE).

In every case high CPU usage in the OOB Server has been reported to
us, the connection was always to MS SQL Server and always resulted
from the result-set not being closed.

4.49 How do I pass LD_LIBRARY_PATH down to CGI programs from Apache?
--------------------------------------------------------------------

If you are running an application using OOB under Apache as CGI
(e.g. a perl script) on a platform where the dynamic linker needs to
be told where to find all required shared objects using an environment
variable your CGI program will need this environment variable set
up. You need to add to your Apache configuration file (probably
httpd.conf) a SetEnv (or PassEnv if Apache 1.1 or later) command
similar to the one below:

SetEnv LD_LIBRARY_PATH /usr/local/easysoft/unixODBC/lib:/usr/local/easysoft/oob/client:/usr/local/easysoft/lib

Not all dynamic linkers use LD_LIBRARY_PATH, some use LIBPATH,
SHLIB_PATH etc. Check you dynamic linker documentation for the correct
environment variable.

The Apache group has full documentation for SetEnv at
http://httpd.apache.org/docs/mod/mod_env.html

The above assumes you are using straight CGI with your program running
external to your web server. If you are running something like
mod_perl where the Perl interpreter is built into Apache then you may
need to tell your dynamic linker where to find OOB shared objects
before Apache is started. For Apache you might set and export
LD_LIBRARY_PATH etc in the apachectl.

4.50 Why cannot I insert timestamps with sub-millisecond fractions in to
------------------------------------------------------------------------
     MS SQL Server datetime field?
     -----------------------------

Firstly, consult
http://support.microsoft.com/support/kb/articles/Q263/8/72.asp

MS SQL Server only does millisecond accuracy (precision of 3) on
datetime columns so anything sub-millisecond tends to generate an
error such as 22008 [Microsoft][ODBC SQL Server Driver]Datetime field
overflow. As the fraction part of a timestamp can range from 0 to
999,999,999 you need to specify the fraction in thousands of second.

If you are using column-wise bound parameters to insert a timestamp in
to a datetime field make sure the ColumnSize is set to 23.

4.51 Why have connection times to MS SQL Server slowed down since upgrading
---------------------------------------------------------------------------
     to Windows 2000 Server?
     -----------------------

We don't know but if you install Windows 2000 Service Pack 1
they come down again. We did notice this service pack appears to
include a WinSock update.

4.52 Why are my output bound parameters from a MS SQL Server procedure
----------------------------------------------------------------------
      not retrieved?
      --------------

Assuming your application was written correctly then the likelihood is
you are not calling SQLMoreResults() after each SQLExecute. A quote
from Microsoft's web site says:

"For SQL insert statements, ODBC 3.5 changed the behavior with respect
 to SQLMoreResults such that, output parameters aren't stored in the
 application's buffer until after the app calls SQLMoreResults and it
 returns SQL_NO_DATA_FOUND. The ODBC 2.65 driver would read-ahead and
 sometimes lump result sets together or skip over them. The ODBC 3.5
 driver was changed to provide result sets in a consistent fashion w/o
 the various problems that used to occur." 

So if you have procedures that return values and they contain insert
statements you must call SQLMoreResults() to fill your output bound
parameters.

You may also get a function sequence error if you attempt another
SQLExecute call before SQLMoreResults() has returned
SQL_NO_DATA_FOUND.

According to Microsoft, setting "SET NOCOUNT ON" in your SQL will also
work. However, if you do this you need to insert it into the first
line of your procedure (it is no good putting it in to the SQL that
calls your procedure in the SQLPrepare).

4.53 Why do I get "SQLSetConnectOption err=-2" errors in my Perl scripts
------------------------------------------------------------------------

When running a Perl script using DBD::ODBC linked with the unixODBC
driver manager you see something similar to this:

DBI->connect(test) failed:
(Unable to fetch information about the error)
(DBD: dbd_db_login/SQLSetConnectOption err=-2) at perl_e1.pl line 9

Did the make test when building DBD::ODBC work?

Try running your perl script again with the environment variable
PERL_DL_NOLAZY set to 1 (DBD::ODBC make test sets this). If this works
then the unixODBC driver manager was built with lazy linking and
RTLD_GLOBAL. If you are using the unixODBC driver manager distributed
with OOB please let us know the name of your OOB distribution file and
we will correct. If you built unixODBC yourself you need to stop
unixODBC using the RTLD_GLOBAL flag in libltdl/ltdl.c. Edit
libltdl/ltdl.c in the unixODBC source tree, look for a dlopen call
using RTLD_GLOBAL which is ORed with LT_LAZY_OR_NOW and delete the
"LT_GLOBAL |"

e.g.
  lt_module   module   = dlopen (filename, LT_GLOBAL | LT_LAZY_OR_NOW);

becomes

  lt_module   module   = dlopen (filename, LT_LAZY_OR_NOW);

5. Operating System Specific - Linux
------------------------------------
5.1 Which version of OOB should I be using?
-------------------------------------------

Linux systems can run with two different and incompatible C runtime
libraries. libc5 is the old C runtime library and glibc (aka libc6) is
the latest thread-safe version. The OOB version for libc5 will not
work with a glibc based system and vice versa. It is not always that
straight forward deciding whether your system, is libc5 based or glibc
based as many newer Linux distributions come with glibc as the default
but have the older libc library for backwards compatibility. If you
don't know whether you are libc5 or glibc based then try the
following:

ls  /lib/libc.*

On our glibc based machine at Easysoft that produces:

/lib/libc.so.4
/lib/libc.so.5
/lib/libc.so.6
/lib/libc.so.4.7.6
/lib/libc.so.5.4.46

Notice the libc.so.6 which is the tell tale sign that this machine is
running glibc. If you don't see a libc.so.6 then the chances are that
you have a libc5 based system.

The OOB install contains a small program called testlib (this will be
in the directory created when you unpack the OOB distribution). It is
a small C program which uses C runtime functions and maths library
functions and is built on the same machine as the OOB
distribution. When run it should output "hello4". The install runs
this to make sure you have the correct libraries and if you don't the
install will be aborted.

There are however further issues. Even if you have support for libc5
and glibc what version of the the C runtime library does your compiler
and linker use when you create new libraries and executables? This is
a key issue as if you have both libc5 and glibc but gcc/ld create
executables linked with glibc then you cannot use the libc version of
OOB with other programs which you build yourself (e.g. Perl/PHP).  The
testlib program referred to above is basically:

#include <stdio.h>
#include <math.h>

int main()
{
    double      j = 3.14;

    printf("hello%1.0f\n", ceil(j));
    return 0;
}

To be sure which version of OOB you should download compile the above
c program as follows:

[1] create testlib.c containg the above.
[2] compile with cc -o testlib testlib.c -lm
[3] run ldd on testlib - ldd ./testlib
[4] examine the output to see what versions of the C runtime library and
    maths library your system is using.
e.g.
> cc -o testlib testlib.c -lm
> ldd ./testlib
        libm.so.5 => /lib/libm.so.5 (0x4000b000)
        libc.so.5 => /lib/libc.so.5 (0x40013000)

This system is using libc5 and the version5 of the maths library so
download the lib5 distribution of OOB.

> cc -o testlib testlib.c -lm
> ldd ./testlib
        libm.so.6 => /lib/libm.so.6 (0x40018000)
        libc.so.6 => /lib/libc.so.6 (0x40035000)
        /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)

This system is using glibc and version 6 of the maths library so
download the glibc distribution of OOB.

There is one further distribution of OOB for glibc based systems and
that is the thread-safe version which is linked with -lpthread (Linux
Threads).  You should only use this version if your application
creates multiple threads and certainly do not attempt to use this with
Perl currently which is not threaded. The threaded (thread-safe) OOB
distributions have -mt in the distribution name. You should also be
aware that there have been a number of bugs reported in
glibc/linux_threads and you should check the glibc web pages and
mailing lists or the web page for your Linux distributor.

Once you have worked out which C run time library you are using
download the appropriate version from our FTP site.

Please make sure that you at least have the minimum version of libc
required for your kernel. If you are unsure, check the
Documentation/Changes file in the kernel sources.

5.2 What Linux kernels can I run?
---------------------------------

The Easysoft ODBC-ODBC Bridge is currently built on 2.0.36 with libc5
(5.4.33) and 2.2.14 with glibc 2.1. Easysoft will always endeavor to
support the latest stable kernel version and it is unlikely that the
OOB will not work with the latest development kernels.

It is unlikely that the OOB will work with 1.2.n kernels and perhaps
even 1.3.n kernels.

Please make sure that if you experience problems that you double check
the Documentation/Changes file in the kernel sources to make sure that
all the minimum requirements for the kernel you are running are
satisfied. This can be particularly important when it comes to the
run-time C library. We have seen people with libc5 based systems at
version 5.4.38 experiencing problems when used on a 2.2.n kernel but
the minimum requirement is 5.4.46.

5.3  Linker errors building Apache/PHP with OOB
-----------------------------------------------

There are generally 2 reasons for linker failures when building
Apache/PHP with OOB.

[1] You have installed a libc5 distribution of OOB on your glibc based
    Linux distribution or vice versa.

A typical result of this when building Apache is:

Creating Configuration.apaci in src
ld: warning: libm.so.5, needed by
    /usr/local/easysoft/oob/client/lib/libesoobclient.so,
    may conflict with libm.so.6
/usr/i486-linux-libc5/lib/libm.so.5: warning: erfcl is not implemented
    and will always fail
/usr/i486-linux-libc5/lib/libm.so.5: warning: erfl is not implemented
    and will always fail
/usr/i486-linux-libc5/lib/libm.so.5: undefined reference to `__getfpucw'
make: *** [dummy] Error 1

This output resulted from building Apache on a glibc based system with
the libc5 version of OOB.

[2] The linker does not know how to find the OOB client shared object.

Make sure you followed the Apache_PHP document in the docs directory
of the OOB distribution carefully. Pay particular attention to

[a] --with-custom-odbc setting for PHP configuration.

[b] CUSTOM_ODBC_LIBS setting for PHP configuration. The example log in
    the Apache_PHP file shows one actual command line split over multiple
    lines in the text file. Make sure you enter this all as one line.
    See question 4.5 above for additional help.

[c] LDFLAGS setting when configuring Apache. If you fail to set
    LDFLAGS as in the Apache_PHP document you will most likely get
    an error during configuration such as:

    /usr/bin/ld: cannot open -lesoobclient: No such file or directory
    collect2: ld returned 1 exit status
    make: *** [dummy] Error 1

[d] Check that the path to the libesoobclient.so shared object is in
    your /etc/ld.so.conf file and that ldconfig has been run to re-read
    this file.

5.4 Which is best, inetd or standalone startup for the OOB Server?
------------------------------------------------------------------

The standalone OOB Server is 10x faster at accepting connections than
the inetd started server. If you are making alot of small connections
to a UNIX OOB Server then starting it standalone (without inetd) is
preferable.  The OOB HTTP server is only available when the OOB Server
is running standalone.

However, the inetd solution has one advantage which is that if the
server crashes for any reason future connections will still work
without you having to restart the server.

5.5 Can I use a multi-threaded application with OOB on Linux and if so how?
---------------------------------------------------------------------------

Yes but make sure you download a thread-safe version of OOB. The
thread-safe distributions of OOB are identified by "-mt" in the
distribution name.

Do not use this OOB distribution unless your application is known to
be threaded and linked with Linux Threads.

When building your application add the -pthread switch to gcc and do
NOT use -lpthreads. Make sure you use thread-safe/reentrant versions
of library functions (e.g. gethostbyname_r etc) and define _REENTRANT
by adding -D_REENTRANT to your compile lines.

If you are using GNU PTH instead of Linux Threads please contact us
for availability.

5.6 Why is inetd terminating the OOB Server service?
----------------------------------------------------

inetd counts the number of server instances created in a 60 second
interval. If your OOB Server is very busy accepting alot of
connections in a short period of time, inetd may decide the OOB Server
is being flooded or looping and suspend the service for a while. A
typical message output by inetd looks like this:

/var/log/messages:Feb 16 14:35:41 machine inetd[52]: esoobserver/tcp
 failing (looping or being flooded), service terminated for 10 min

By default, most inetd servers count 40 instances in 60 seconds as too
many. If you need a higher threshold that this you need to edit your
inetd.conf file and amend the OOB Server line to add a maximum number
of server instances [see the inetd.conf(8) man page]. Usually, all
that is involved is placing a . and a number after the nowait.

e.g.

esoobserver stream tcp nowait.60 root /bin/sh /bin/sh
   /usr/local/easysoft/oob/server/server

Do not forget to tell inetd to reread its configuration files after
making changes to inetd.conf.

6. Operating System Specific - Windows
--------------------------------------
6.1 What username/password do I need to specify for LogonUser
-------------------------------------------------------------
    and LogonAuth?
    --------------

For Windows 95 and 98 you need to specify a username and password
defined for that machine.

For NT it is slightly more complex as NT machines are usually part of
an NT domain. You may specify either a local username and password on
that NT server or a NT domain username/password. The OOB Server,
passes either NULL or the specified domain name to the NT function
LogonUser(). You can specify a domain in the LogonUser attribute like
this:

Domain/username

If "Domain/" is not specified, the OOB Server passes NULL to LogonUser()
which means the local account database is searched first and then
trusted domains.

If Domain is "." (e.g. ./username), then the search is restricted to
the local account database on the NT Server.

6.2 What do I do if I get an Access Violation or Fault popup window?
--------------------------------------------------------------------

If an access violation or other fault occurs when running a program in
Windows a popup dialogue appears. This may occur on the client side
when running you application connected to the OOB client or at the
server side.

In general:

[1] you should note down any information in this popup.
[2] write down exactly what you were doing before this occurred.
[3] if you have a Dr Watson log take a copy of the log (see later)
[4] send all of the above along with the version of the OOB you are
    running to support@easysoft.com.

If you are writing your own ODBC compliant application then your first
port of call should be to thoroughly investigate your code and satisfy
yourself that nothing is wrong with it. Any application can generate
an access violation in an ODBC driver by passing invalid pointers to
ODBC APIs.

Dr Watson log files are created by drwtsn32.exe. After installing
Windows your machine is set up to run drwtsn32.exe when a program
fails (note that installing other software e.g. Microsoft Developer
Studio can change the spawned debugger). This program writes
information about your operating system and the program that failed
into a log file. It shows the threads, where each of them were when
the program failed and which thread caused the problem. This file can
be an invaluable aid in determining the source of the problem. The Dr
Watson log file is DRWTSN32.LOG and is created in the your Windows
directory.

If you have installed the WIN32 SDK then the debugger is changed to
WINDBG.  You can change the debugger back to Dr Watson by editing the
following key in your registry:

HKEY_LOCAL_MACHINE\
SOFTWARE\
Microsoft\
Windows NT\
CurrentVersion\
AeDebug

This key contains string values "Auto" and "Debugger". If you want to
temporarily change the spawned debugger to Dr Watson to generate a log
file then write down the current version of the "Debugger" entry and
change it to:

DRWTSN32 -p %ld -e %ld -g

Once you have generated a log file you can reset the debugger entry.

These entries are also available in Windows 95/98 but they are in the
win.ini file instead of the registry. The section [aedebug[ has
entries that correspond to the registry.

From OOB 1.0.0.3 (for Windows) the OOB Server traps exceptions and
reports them in the file LOGDIR\esoob.exception (where LOGDIR is a
server configurable parameter defaulting to c:\temp). Any exceptions
on NT will also be reported to the Event Log. If you have an
esoob.exception file, send that to us with a description of what you
were doing.

6.3 Does the OOB client support file DSNs?
------------------------------------------

Yes.

You can create File DSNs from the ODBC Administrator, just like user
or system DSNs. Simply click on File DSN, enter a name for the DSN and
then fill in all the OOB fields as usual.

6.4 Why does the install hang?
-----------------------------

On Windows NT we have seen (and had reported to us) the installation
hanging in two places. The course of action depends on where the hang
occurs.

[1] If the hang occurs whilst the Setup dialogue shows "Easysoft
    ODBC-ODBC Bridge is preparing the InstallShield(R) wizard which
    will guide you through the rest of the setup process. Please Wait"
    and the 100% progress bar is displayed:

    Be patient and wait (up to 5 minutes) and the installation will
    continue as normal. This appears to occur on other company's
    InstallShield installations too and so we do not think this is a
    problem specific to the OOB installation.

    Make sure you have closed all applications before installing.

[2] If the hang occurs after you have run through all the dialogue
    boxes and provided all the installation information requested:

    You are probably running a version of the OOB including and prior to
    version 1.0.0.3. These versions contained a bug in the InstallShield
    supplied service template that can cause it to loop forever waiting
    for the previously installed OOB Server Service to close down. The
    solution in this case is to either:

   [a] Get a more recent version of OOB which fixes this problem.
   
   [b] Abort the installation (use the Task Manager). Then go to
       control panel -> services and make sure the OOB Server Service
       is stopped (it probably will be). Then run the installation again
       and it should progress correctly.

6.5 Why do I get "Invalid authorization specification" when the LogonUser
-------------------------------------------------------------------------
    and LogonAuth are set to a valid username and password?
    -------------------------------------------------------

If you are sure the username and password are correct then you need to
call either SQLError or SQLGetDiagRec() or
SQLGetDiagField(SQL_DIAG_NATIVE).  The native error is actually the
error code returned by GetLastError (the WIN32 function) and it gives
an indication of why the OOB server failed to logon as your specified
user. Error codes we have seen and their solutions are:

1385
Logon Failure: the user has not been granted the requested logon type at this
computer. Check the user has the Logon Locally permission.

1314
A required privilege is not held by the client. The OOB Server needs
the "Act as part of the operating system" access right to authenticate
and become the LogonUser.

1326
Logon Failure: unknown username or bad password. The username is not a
valid user or the password is invalid. If you have checked these are
valid and the user is in an NT domain try prefixing the username with
DOMAIN/ e.g. NTDOMAIN/Username.

1328
Account logon time restriction violation.

1330
The specified account password has expired.

1331
Logon failure: account currently disabled. Re-enable the account.

1355
The specified domain did not exist. You are using the Domain/Username
syntax in LogonUser and Domain does not exist.

1909
Account locked out. Unlock the account.

87
Parameter incorrect. You have specified an invalid username for the
LogonUser attribute e.g. a zero length one. Check the LogonUser
attribute is spelt correctly in your registry or ini file
e.g. LoginUser is incorrect and results in the OOB client not finding
a username and passing a zero length one.

6.6 Why do I get connection refused/reset under heavy loads
-----------------------------------------------------------
(Windows OOB server)?
---------------------

The main OOB Server thread listens on the specified port (defaults to
8888) for incoming connections from OOB clients. Once a connection is
accepted the main OOB server thread creates a new thread/process which
handles the ODBC connection. Whilst the main server thread is starting
up a new connection thread/process it is not accepting other
connections. The time required to start a new connection handler is
usually very short but to avoid newly incoming connections being
dropped the server attempts to set the listen backlog queue to 20. The
listen backlog queue allows the TCPIP stack to queue the connection
until the server gets around to accepting the connection.

If the listen backlog queue fills the TCPIP stack will reject the
connection and the OOB Server never sees it.

Unfortunately, in Windows 9X and NT Workstation the maximum listen
backlog is 5. Since the OOB Server is usually pretty quick at
accepting connections this low backlog value is not usually a
problem. However, it does mean that concerted attempts to make lots of
connections in a short period of time can fill the backlog queue. This
makes Windows NT Workstation and Win9X in particular a bad choice for
a high-load server.

The OOB Server could use SOMAXCONN in Winsock2 to set the listen
backlog queue to its maximum value (this has no affect on NT
workstation and Win9x). However, large backlogs make SYN flood attacks
much more effective since the queue is non-pageable system memory.

You may find the following article useful:
http://support.microsoft.com/support/kb/articles/q142/6/41.asp

The OOB client can help with connection refused problems due to the
socket backlog filling in Win9x and NT workstation by making multiple
connection attempts. See the question "How does the OOB client handle
refused connections?"

6.7 How can I check which version of MS MDAC I have?
----------------------------------------------------

MDAC - Microsoft Data Access Components.

MDAC contains the ODBC driver manager and various ODBC drivers

You can download the ODBC component checker from Microsoft and run it.
The ODBC component checker is an extremely useful diagnostics tool
which checks the ODBC components such as the driver manager and ODBC
drivers on your machine to see what you are using and if they are
correctly installed. You can get it from:

http://www.microsoft.com/data

6.8 What version of MS MDAC do I need?
--------------------------------------

You are best using a recent MDAC (2.1 or above but preferably 2.5).
Some drivers we have tested do not work with older MDACs and OOB -
e.g. Centura SQLBase and MDAC 1.5b. To find out which version of MDAC
you have installed see the question "How can I check which version of
MS MDAC I have?".

6.9 Where do I get WinSock 2 for Windows 95?
--------------------------------------------

OOB for Windows 95 requires Winsock 2. You can get the WinSock 2
update for Windows 95 from:

http://www.microsoft.com/Windows95/downloads/contents/WUAdminTools/S_WUNetworkingTools/W95Sockets2/Default.asp

6.10 Why does OOB install fail with
-----------------------------------
     "Setup is unable to locate the layout file"?
     --------------------------------------------

When installing the ODBC-ODBC Bridge on windows I get the following
error:

Setup is unable to locate the layout file
'C:\Temp\pft2D~tmp\Layout.bin' which is needed to complete the
installation. Error 112.

This error indicates that environment variables that InstallShield
needs to unpack an ODBC-ODBC Bridge distribution are set incorrectly
and InstallShield cannot find the directory it needs. To correct this
problem reset the Environment Variables that point to the two
temporary directories. To do this enter Control Panel and double click
the System icon.  When the System Properties pane has loaded up select
the Advanced tab and click into Environment Variables. Select the
Environment Variables Temp & Tmp from the System Variables list and
change them to point to C:\temp and C:\tmp and make sure these
directories exist. Once these have been edited click ok and this will
save your new values.

7. Operating System Specific - Solaris
--------------------------------------

7.1 Why do I get undefined symbol for h_errno?
----------------------------------------------

Currently the OOB client for Solaris is not built against the Solaris
threads library. As a result, if you attempt to link a threaded
program with the libesoobclient shared object you will probably get an
undefined symbol for h_errno. When a program is built threaded,
h_errnop is defined instead of h_errno.

An example where you might see this is if you build unixODBC with
threads (the default configuration) and then try and use OOB with it.
The solution is to rebuild unixODBC without threads
(--enable-threads=no).

8. Operating System Specific - OpenBSD
--------------------------------------

8.1 Can I use the ODBC-ODBC Bridge for FreeBSD on OpenBSD?
----------------------------------------------------------

Although we have not tested this configuration according to the
OpenBSD web-site OpenBSD supports binary emulation "of most binaries
from SVR4 (Solaris), FreeBSD, Linux, BSDI, SunOS, and HPUX." To our
knowledge this has been successfully tested by a number of customers
with no reported problems.

9. Operating System Specific - FreeBSD
--------------------------------------
9.1 When linking Perl DBD::ODBC with the OOB on FreeBSD I get errors
--------------------------------------------------------------------
    regarding wchar.h what should I do?
    -----------------------------------

When linking the ODBC-ODBC bridge with Perl DBD::ODBC you may get the
following error:

/usr/local/easysoft/oob/client/include/sql.h:46,
                 from
/usr/local/easysoft/oob/client/include/sqlext.h:46,
                 from dbdodbc.h:9,
                 from ODBC.h:9,
                 from ODBC.xs:1:
/usr/local/easysoft/oob/client/include/sqltypes.h:14: wchar.h: No such
file or directory

To rectify this problem you need to comment out any references to
wchar.h in the following file:

/usr/local/easysoft/oob/client/include/sqlext.h

10. Programmming

---------------

10.1 Can I fork child processes after SQLDriverConnect and use the connection
----------------------------------------------------------------------------
    handle in each one?
    -------------------

No.

The OOB client connects to the OOB server during the call to
SQLDriverConnect.  After SQLDriverConnect returns, a socket is open
between the client and server. If you then fork children they inherit
the dbc and open socket.  If the children use the dbc in further calls
to SQL functions this will cause multiple processes to be sending data
down the same socket.  This just will not work. You need to make the
call to SQLDriverConnect in each child.

10.2 Can I use a multi-threaded application with the OOB client?
---------------------------------------------------------------

In Windows yes.

On most UNIX operating systems we support, a multi-thread-safe version
of the OOB client is not yet available. However, for Linux/glibc,
Solaris/Sparc/Intel and FreeBSD a MT-safe OOB distribution is
available.

