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?

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 Why do my connections to the OOB server seem to be dropped after a while?

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 I get authorization failures from the client?
 3.4 How do I find out why an ODBC call is failing?
 3.5 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?

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

7. Programmming
 7.1 Can I fork child processes after SQLDriverConnect and use the connection
     handle in each one?
 7.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 SQLServer 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.0 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 and ODBC 3.0.

The ODBC-ODBC Bridge has the full ODBC 3.0 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 API so this is covered
100%.

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

http://www.easysoft.com
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.

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

Strictly speaking the answer to this question is no. However, if you
are accessing MS SQLServer, 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 datasources
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.

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 (NT, 95/98):

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

Unix 
  
  Three formats of the distribution are available, tar, gzipped tar and
  compressed tar. These vary in size between 400K and 1.7Mb. The
  fully installed client, server, documentation and examples requires
  about 1.5Mb.

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.

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. 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 datasource. 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 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 DSN's see
"How does the OOB client locate DSNs?"

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

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

Server 	       The name (or IP address) of the remote machine where
               the OOB server and ODBC driver for your database are
               located.

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.

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.

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

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

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

If you are running a beta version of the OOB then you can do any of
the following:

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

Once the beta period is over you will have to pay for support although
the news server and web pages will always be available.

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

You can report bugs by:

[1] mailing support@easysoft.com
[2] Posting the bug to the Jitterbug web page at http://beta.easysoft.com/uda

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 us added to:

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

called License Administrator. 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 does not currently contain a License
Administrator program. If you need a server license for UNIX please
mail sales@easysoft.com.

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 is currently Windows specific and specifies
               the port on which the OOB Server will listen for HTTP
               requests. The default is port 8890 but it may be any
               port no 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.

               NOTE - this attribute is in version 0.4.0.0 onwards.

LogDir         This option specified 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 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 Reserved for Easysoft use
                   (default is clear, i.e. not set)
               0x2 Start listening for HTTP connections when the server starts
	           (default is set, 0x2)
	       0x4 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 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 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).

	       You add these values together to produce the Flags value.
	       The default Flags value is 0x2.

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 = 2047

[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 a second to connect an
application linked directly with the OOB client on Linux to a
datasource 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] 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 "Trace = 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.

[c] 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.

[d] 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.

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
SQLServer ODBC driver you may find more tables are visible than when
connecting directly to the same MS SQLServer 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 SQLServer data sources using trusted connections the MS
SQLServer 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 serivce and restart it.
However, if you do this you will not be able to change some configurable
parameters via the OOB HTTP Server.

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.

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 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 conenctions 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. Touble 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.  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 tpcd 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 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.

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.4 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.5 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.13 although it is likely to
work with more recent versions.

OOB has been tested with DBD::ODBC 0.20 and 0.21 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.12 and the first two betas
of PHP4.


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 yor 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
        libdate.so => libdate.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 or LD_LIBRARY_PATH
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).

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

[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 guildlines 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?
--------------------------------------------

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.

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

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

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.10 with glibc 2.1. Easysoft will always endevour 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.

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 accurs 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@eaysoft.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 correspnd to the registry.


7. Programmming
---------------

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

7.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 a
MT-safe OOB distribution is available.

