Getting started

Overview

The Easysoft JDBC-ODBC Bridge allows Java applications to connect to any datastore for which an ODBC driver is available.

The Easysoft JDBC-ODBC Bridge is a client/server application. Use the Easysoft JDBC-ODBC Bridge client (EJOB.jar) in your Java application to connect to the Easysoft JDBC-ODBC Bridge server, which then connects to the target ODBC driver.

Installing the Easysoft JDBC-ODBC Bridge

The Easysoft JDBC-ODBC Bridge installer lets you install both the client and server components of the product.

Install the Easysoft JDBC-ODBC Bridge client on the same computer as your Java application. Install the Easysoft JDBC-ODBC Bridge server on the same computer as your target ODBC driver. If the Java application and ODBC driver are located on the same computer, install both the client and server on this computer.

Installing on Windows

The Windows installation can be done by anyone with local administrator privileges.

  1. Download the Easysoft JDBC-ODBC Bridge installer.

  2. Follow the onscreen instructions to progress through the installation wizard.

    If you installed the Easysoft JDBC-ODBC Bridge server, the Initial Server Configuration dialog box displays.

    JDBC Port defines the port where the Easysoft JDBC-ODBC Bridge server listens for Easysoft JDBC-ODBC Bridge client connections

    If you change the port, you’ll need to specify it in the JDBC URL used by your application.

    HTTP Port defines the port on which the Easysoft JDBC-ODBC Bridge web administrator listens for HTTP requests. Accept the default values unless you have a port conflict.

    In the User Name box, enter the login name of an existing Windows user account. This is the account that you’ll use to make changes in the Easysoft JDBC-ODBC Bridge web administrator.

    To allow anyone to have access to the web administrator, leave the User Name field blank. Alternatively, click to clear Enable Admin User, which remove the requirement to log in using the web administrator.

Updating files that are in use

To avoid rebooting your computer, the Easysoft JDBC-ODBC Bridge installer prompts you when files that it needs to update are in use by another application or service. This frees the locked files and allows the installation to complete without a system restart. The installer uses the Restart Manager to locate the applications that are using files that need updating. These applications are displayed in the Files in Use dialog box. To avoid a system restart, choose Automatically close applications and attempt to restart them after setup is complete. The Easysoft JDBC-ODBC Bridge installer then uses Restart Manager to try to stop and restart each application or service in the list. If possible, Restart Manager restores applications to the same state that they were in before it shut them down.

Licensing

By default, the installer starts the Easysoft License Manager, because you can’t use the Easysoft JDBC-ODBC Bridge until you have a license. If you choose not to run Easysoft License Manager as part of the installation process, run License Manager from the Easysoft group in the Windows Start menu when you’re ready to license the Easysoft JDBC-ODBC Bridge. These types of license are available:

  • A free time-limited trial license which gives you free and unrestricted use of the product for a limited period (usually 14 days).

  • A full license if you have purchased the product. On purchasing the product you are given an authorization code, which you use to obtain a license.

To license the Easysoft JDBC-ODBC Bridge:

  1. In License Manager, enter your contact details.

    You must complete the Name, E-Mail Address, and Company fields.

    The e-mail address must be the same as the one used to register at the Easysoft web site. Otherwise, you won’t be able to obtain a trial license.

  2. Choose Request License.

    You’re prompted to choose a license type.

  3. Do one of the following:

    • For a trial license, choose Time Limited Trial, and then choose Next.
      -Or-

    • For a purchased license, choose Non-expiring License, and then choose Next.

  4. Choose your product from the drop-down list when prompted, and then choose Next.

  5. For a purchased license, enter your authorization code when prompted, and then choose Next.

  6. Choose how to get your license when prompted.

  7. Do one of the following:

    • Choose On-line Request if your machine is connected to the internet and can make outgoing connections to port 8884.
      With this method, License Manager automatically requests and then applies your license.
      -Or-

    • Choose View Request. Then open a web browser and go to https://www.easysoft.com/support/licensing/trial_license.html or https://www.easysoft.com/support/licensing/full_license.html, as appropriate. In the web page, enter your machine number (labelled Number in the license request). For purchased licenses, you also need to enter your authorization code (labelled Ref in the license request).
      We’ll automatically email your license to the email address you supplied in License Manager.
      -Or-

    • Choose Email Request to email your license request to our licensing team.
      Once we’ve processed you request, we’ll email your license to the email address you supplied in License Manager.

  8. Close the License Manager windows and then choose Finish.

If you chose either View Request or Email Request, apply your license by double-clicking the email attachment when you get the license email from us. Alternatively, start License Manager from the Easysoft folder in the Windows Start menu. Then choose Enter License and paste the license in the space provided.

Once you’ve licensed the Easysoft JDBC-ODBC Bridge, the installation is complete.

Repairing the installation

The installer can repair a broken Easysoft JDBC-ODBC Bridge installation. For example, you can use the installer to restore missing Easysoft JDBC-ODBC Bridge files or registry keys. To do this:

  1. In the Windows taskbar, enter Add or remove programs in the Windows search box.

  2. Select Easysoft JDBC-ODBC Bridge in the list, and then choose Repair.

Uninstalling on Windows

This section explains how to remove the Easysoft JDBC-ODBC Bridge from your system.

Removing the Easysoft JDBC-ODBC Bridge

  1. In the Windows taskbar, enter Add or remove programs in the Windows search box.

  2. Select Easysoft JDBC-ODBC Bridge in the list, and then choose Uninstall.

Easysoft product licenses are stored in the Windows registry. When you uninstall, your licenses are not removed, so you do not need to relicense the product if you reinstall or upgrade.

Installing on Linux or UNIX

The installation can be done by anyone with root access.

  1. Download the Easysoft JDBC-ODBC Bridge distribution for your client application platform.

    If your target ODBC driver is 64-bit, choose the 64-bit distribution from the Platforms list. If your target ODBC driver is 32-bit, choose the 32-bit distribution from the Platforms list.

  2. Copy the distribution to a temporary directory on the machine where the application you want to connect to JDBC-ODBC Bridge is installed.

  3. Unpack the distribution and cd into the resultant directory.

  4. As root, run:

    ./install

  5. Follow the onscreen instructions to progress through the installation.

Starting the Easysoft JDBC-ODBC Bridge server

As root:

  1. # cd installation_path/easysoft/job

  2. # ./startjob

    The output should be similar to:

Starting HTTP Server
The port is set to 8031 in this installation.

Stopping the Easysoft JDBC-ODBC Bridge server

As root:

  • # ./stopjob

Further information

Preinstallation requirements

To install the Easysoft JDBC-ODBC Bridge you need:

  • The Bourne shell in /bin/sh. If your Bourne shell is not located there, you may need to edit the first line of the installation script.

  • Various commonly used commands such as:

    grep, awk, test, cut, ps, sed, cat, wc, uname, tr, find, echo, sum, head, tee, id

If you do not have any of these commands, they can usually be obtained from the Free Software Foundation. As the tee command does not work correctly on some systems, the distribution includes a tee replacement.

  • Depending on the platform, you’ll need up to 10 MB of temporary space for the installation files and up to 10 MB of free disk space for the installed programs. If you also install the unixODBC Driver Manager, these numbers increase by approximately 1.5 MB.

  • For Easysoft licensing to work, you must do one of the following:

    • Install the Easysoft JDBC-ODBC Bridge in /usr/local/easysoft.

    • Install the Easysoft JDBC-ODBC Bridge elsewhere and symbolically link /usr/local/easysoft to wherever you chose to install the software.

The installation will do this automatically for you so long as you run the installation as someone with permission to create /usr/local/easysoft.

  • Install the Easysoft JDBC-ODBC Bridge elsewhere and set the EASYSOFT_ROOT environment variable. For more information about setting the EASYSOFT_ROOT environment variable, refer to Post installation steps for non-root installations.

    • An ODBC Driver Manager.

Easysoft JDBC-ODBC Bridge distributions include the unixODBC Driver Manager.

  • You do not have to be the root user to install, but you will need permission to create a directory in the chosen installation path. Also, if you are not the root user, it may not be possible for the installation to:

    1. Register the Easysoft JDBC-ODBC Bridge with unixODBC.

    2. Create the example data source in the SYSTEM odbc.ini file.

    3. Update the dynamic linker entries (some platforms only).

If you are not root, these tasks will have to be done manually later.

We recommend that you install all components as the root user.

What you can install

This distribution contains:

  • The Easysoft JDBC-ODBC Bridge.

  • The unixODBC Driver Manager.

You need an ODBC Driver Manager to use the Easysoft JDBC-ODBC Bridge from your applications. The distribution therefore contains the unixODBC Driver Manager. Most (if not all) UNIX and Linux applications support the unixODBC Driver Manager. For example, Perl DBD::ODBC, PHP, Python, and so on.

You do not have to install the unixODBC Driver Manager included with this distribution. You can use an existing copy of unixODBC. For example, a version of unixODBC installed by another Easysoft product, a version obtained from your operating system vendor or one that you built yourself. However, as Easysoft ensure that the unixODBC distributed with the Easysoft JDBC-ODBC Bridge has been tested with that driver, we recommend you use it.

If you choose to use an existing unixODBC Driver Manager, the installation script will attempt to locate it. The installation script looks for the ODBC Driver Manager in the standard places. If you have installed it in a non-standard location, the installation script prompts you for the location. The installation primarily needs unixODBC’s odbcinst command to install drivers and data sources.

Where to install

This installation needs a location for the installed files. The default location is /usr/local.

At the start of the installation, you’re prompted for an installation path. All files are installed in a subdirectory of your specified path called easysoft. For example, if you accept the default location /usr/local, the product will be installed in /usr/local/easysoft and below.

If you choose a different installation path, the installation script tries to symbolically link /usr/local/easysoft to the easysoft subdirectory in your chosen location. This allows us to distribute binaries with built in dynamic linker run paths. If you are not root or the path /usr/local/easysoft already exists and is not a symbolic link, the installation will be unable to create the symbolic link. For information about how to correct this manually, refer to Post installation steps for non-root installations.

Note that you cannot license Easysoft products until either of the following is true:

  • /usr/local/easysoft exists either as a symbolic link to your chosen installation path or as the installation path itself.

  • You have set EASYSOFT_ROOT to installation_path/easysoft.

Changes made to your system

The installation script installs files in subdirectories of the path requested at the start of the installation, Depending on what is installed, a few changes may be made to your system:

  1. If you choose to install the Easysoft JDBC-ODBC Bridge into unixODBC, unixODBC’s odbcinst command will be run to add an entry to your odbcinst.ini file. You can locate this file with odbcinst -j. (odbcinst is in installation_path/easysoft/unixODBC/bin, if you are using the unixODBC included with this distribution.)

  2. The installation script installs an example data source into unixODBC. This data source will be added to your SYSTEM odbc.ini file. You can locate your SYSTEM odbc.ini file by using odbcinst -j. The data source will look similar to this:

  3. Dynamic linker. On operating systems where the dynamic linker has a file listing locations for shared objects (Linux and FreeBSD), the installation script will attempt to add paths under the path you provided at the start of the installation to the end of this list.

    • On Linux, this is usually the file /etc/ld.so.conf.

    • On FreeBSD this is usually the file /etc/defaults/rc.conf.

Installing alongside other existing Easysoft product installations

Each Easysoft distribution contains common files shared between Easysoft products. These shared objects are placed in installation_path/easysoft/lib. When you run the installation script, the dates and versions of these files are compared with the same files in the distribution. The files are only updated if the files being installed are newer or have a later version number.

You should ensure that nothing on your system is using Easysoft software before starting an installation. This is because on some platforms, files in use cannot be replaced. If a file cannot be updated, you get a warning during the installation. All warnings are written to a file called warnings in the directory you unpacked the distribution into.

If the installer detects you’re upgrading a product, the installer will suggest you delete the product directory to avoid having problems with files in use. An alternative is to rename the specified directory.

If you are upgrading, you will need a new license from Easysoft to use the new driver.

Gathering information required during the installation

During the installation, you’re prompted for various pieces of information. Before installing, you need to find out whether you have unixODBC already installed and where it is installed. The installation script searches standard places like /usr and /usr/local.

However, if you installed the Driver Manager in a non-standard place and you do not install the included unixODBC, you will need to know the location.

Unpacking the distribution The distribution for UNIX and Linux platforms is a tar file. To extract the installation files from the tar file, use:

tar -xvf jdbc-odbc-bridge-1.7.0-linux-x86-64.tar

This creates a directory with the same name as the tar file (without the .tar postfix) containing further archives, checksum files, an installation script and various other installation files.

Change into the directory created by unpacking the tar file to run the installation script. For example:

# cd jdbc-odbc-bridge-1.7.0-linux-x86-64

License to use

The end-user license agreement (EULA) is in the file license.txt. Be sure to understand the terms of the agreement before continuing, as you’re required to accept the license terms at the start of the installation.

Answering questions during the installation

Throughout the installation, you’re prompted to answer some questions. In each case, the default choice displays in square brackets and you need only press Enter to accept the default. If there are alternative responses, these are shown in round brackets; to choose one of these, type the response and press Enter.

For example:

Do you want to continue? (y/n) [n]:

The possible answers to this question are y or n. The default answer when you type nothing and press Enter is n.

Running the installer

If you are considering running the installation as a non root user, we suggest you review this carefully as you will have to get a root user to manually complete some parts of the installation afterwards. We recommend installing as the root user. (If you’re concerned about the changes that will be made to your system, refer to Changes made to your system.)

To start the installation, run:

./install

You need to:

  • Confirm your acceptance of the license agreement by typing "yes" or "no". For more information about the license agreement, refer to License to use.

  • Supply the location where the software is to be installed.

We recommend accepting the default installation path.

For more information, refer to Where to install.

Locating or installing unixODBC

We strongly recommend you use the unixODBC Driver Manager because:

  • The installation script is designed to work with unixODBC and can automatically add Easysoft JDBC-ODBC Bridge and data sources during the installation.

  • Most applications and interfaces that support ODBC are compatible with unixODBC. The Easysoft JDBC-ODBC Bridge and any data sources that you add during the installation are automatically available to your applications and interfaces therefore.

  • The unixODBC project is currently led by Easysoft developer Nick Gorham. This means that there is a great deal of experience at Easysoft of unixODBC in general and of supporting the Easysoft JDBC-ODBC Bridge running under unixODBC. It also means that if you find a problem in unixODBC, it’s much easier for us to facilitate a fix.

The installation starts by searching for unixODBC. There are two possible outcomes here:

  1. If the installation script finds unixODBC, the following message displays:

    Found unixODBC under path and it is version n.n.n

  2. If the installation script can’t find unixODBC in the standard places, you will be asked whether you have it installed.

If unixODBC is installed, you need to provide the unixODBC installation path. Usually, the path required is the directory above where odbcinst is installed. For example, if odbcinst is in /opt/unixODBC/bin/odbcinst, the required path is /opt/unixODBC.

If unixODBC is not installed, you should install the unixODBC included with this distribution.

If you already have unixODBC installed, you do not have to install the unixODBC included with the distribution, but you might consider doing so if your version is older than the one we provide.

The unixODBC in the Easysoft JDBC-ODBC Bridge distribution is not built with the default options in unixODBC’s configure line.

Option Description

--prefix=/etc

This means the default SYSTEM odbc.ini file where SYSTEM data sources are located is /etc/odbc.ini.

--enable-drivers=no

This means other ODBC drivers that come with unixODBC are not installed.

--enable-iconv=no

This means unixODBC does not look for libiconv. Warnings about not finding an iconv library were confusing our customers.

--enable-stats=no

Turns off unixODBC statistics, which use system semaphores to keep track of used handles. Many systems do not have sufficient semaphore resources to keep track of used handles.

--enable-readline=no

This turns off readline support in isql. We did this because it ties isql to the version of libreadline on the system we build on. We build on as old a version of the operating system as we can for forward compatibility. Many newer Linux systems no longer include the older readline libraries and so turning on readline support makes isql unusable on these systems.

--prefix=/usr/local/easysoft/unixODBC

This installs unixODBC into /usr/local/easysoft/unixODBC.

Installing the Easysoft ODBC driver

The Easysoft JDBC-ODBC Bridge installation script:

  • Installs the driver.

  • Registers the driver with the unixODBC Driver Manager.

    If the Easysoft JDBC-ODBC Bridge is already registered with unixODBC, a warning displays that lists the drivers unixODBC knows about. If you’re installing the Easysoft JDBC-ODBC Bridge into a different directory than it was installed before, you need to edit your odbcinst.ini file after the installation and correct the Driver and Setup paths. unixODBC’s odbcinst doesn’t update these paths if a driver is already registered.

  • Creates an example Easysoft JDBC-ODBC Bridge data source. If unixODBC is installed and you registered the Easysoft JDBC-ODBC Bridge with unixODBC, the installation script adds example data source to your odbc.ini file.

Licensing

The installation_path/easysoft/license/licshell program lets you obtain or list licenses.

Licenses are stored in installation_path/easysoft/license/licenses.

After obtaining a license, you should make a backup copy of this file.

The installation script asks you if you want to request an Easysoft JDBC-ODBC Bridge license:

Would you like to request a Easysoft JDBC-ODBC Bridge license now (y/n) [y]:

You do not need to obtain a license during the installation, you can run licshell after the installation to obtain or view licenses.

If you answer y, the installation runs the licshell script.

To obtain a license automatically, you need to be connected to the Internet and allow outgoing connections to license.easysoft.com on port 8884. If you’re not connected to the Internet or don’t allow outgoing connections on port 8884, the License Client can create a license request file that you can email to us.

When you start the License Client, the following menu displays:

[0] exit
[1] view existing license
[n] obtain a license for the desired product.

To obtain a license, select one of the options from [2] onwards for the product you’re installing. The License Client then runs a program that generates a key that’s used to identify the product and operating system (we need this key to license you).

After you have chosen the product to license (Easysoft JDBC-ODBC Bridge), you need to supply:

  • Your full name.

  • Your company name.

  • An email contact address. This must be the email address that you used when you registered on the Easysoft web site.

  • A reference number (also referred to as an authorization code). When applying for a trial license, press Enter when prompted for a reference number. This field only applies to full (paid) licenses.

You’re then asked to choose how you want to obtain the license.

The choices are:

  • [1] Automatically by contacting the Easysoft License Daemon

    This requires a connection to the Internet and the ability to support an outgoing TCP/IP connection to license.easysoft.com on port 8884.

  • [2] Write information to file

    The license request is output to license_request.txt.

  • [3] Cancel this operation

If you choose to obtain the license automatically, the License Client true to open a TCP/IP connection to license.easysoft.com on port 8884 and send the details you supplied along with your machine number. No other data is sent. The data sent is transmitted as plain text, so if you want to avoid the possibility of this information being intercepted by someone else on the Internet, you should choose [2] and send the the request to us. The License daemon returns the license key, print it to the screen and make it available to the installation script in the file licenses.out.

If you choose option [2], the license request is written to the file license_request.txt. You should then exit the License Client by choosing option [0] and complete the installation. After you have sent the license request to us, we’ll return a license key. Add this to the end of the file installation_path/easysoft/license/licenses.

Post installation steps for non-root installations

If you installed the Easysoft JDBC-ODBC Bridge as a non-root user (not recommended), there may be some additional steps you to do manually:

  1. If you attempt to install the Easysoft JDBC-ODBC Bridge under the unixODBC Driver Manager and you do not have write permission to unixODBC’s odbcinst.ini file, the driver can’t be added.

    You can manually install the driver under unixODBC by adding an entry to the odbcinst.ini file. Run odbcinst -j to find out the location of the DRIVERS file then append the lines from drv_template file to odbcinst.ini. (drv_template is in the directory where the Easysoft distribution was untarred to.)

  2. No example data sources can be added into unixODBC if you do not have write permission to the SYSTEM odbc.ini file. Run odbcinst -j to find out the location of the SYSTEM DATA SOURCES file then add your data sources to this file.

  3. On systems where the dynamic linker has a configuration file defining the locations where it looks for shared objects (Linux and FreeBSD), you need to add:

    installation_path/easysoft/lib
installation_path/easysoft/unixODBC/lib

    The latter entry is only required if you installed the unixODBC included with this distribution. Sometimes, after changing the dynamic linker configuration file, you need to run a program to update the dynamic linker cache. (For example, /sbin/ldconfig on Linux.)

  4. If you didn’t install the Easysoft JDBC-ODBC Bridge in the default location, you need to do one of the following:

    • Link /usr/local/easysoft to the easysoft directory in your chosen installation path.

      For example, if you installed in /home/user, the installation creates /home/user/easysoft and you need to symbolically link /usr/local/easysoft to /home/user/easysoft:

      ln -s /home/user/easysoft /usr/local/easysoft

    • Set and export the EASYSOFT_ROOT environment variable to installation_path/easysoft.

  5. If your system doesn’t have a dynamic linker configuration file, you need to add the paths listed in step 3 to whatever environment path the dynamic linker uses to locate shared objects. You may want to add these paths to a system file run whenever someone logs. For example, /etc/profile.

    The environment variable depends on the dynamic linker. Refer to your ld or ld.so man page. It is usually:

    LD_LIBRARY_PATH, LIBPATH, LD_RUN_PATH, or SHLIB_PATH.

Uninstalling on Linux or UNIX

There is no automated way to remove the Easysoft JDBC-ODBC Bridge in this release. However, removal is quite simple. To do this:

  1. Change directory to installation_path/easysoft and delete the product directory. installation_path is the Easysoft JDBC-ODBC Bridge installation directory, by default /usr/local.

  2. If you had to add this path to the dynamic linker search paths (for example, /etc/ld.so.conf on Linux), remove it. You may have to run a linker command such as /sbin/ldconfig to get the dynamic linker to reread its configuration file. Usually, this step can only be done by the root user.

  3. If you were using unixODBC, the Easysoft JDBC-ODBC Bridge entry needs to be removed from the odbcinst.ini file. To check whether the Easysoft JDBC-ODBC Bridge is configured under unixODBC, use odbcinst -q -d. If the command output contains [], uninstall the driver from unixODBC by using:

    odbcinst -u -d -n

If a reduced usage count message is displayed, repeat this command until odbcinst reports that the driver has been removed.

  1. If you created any Easysoft JDBC-ODBC Bridge data sources under unixODBC, you may want to delete these. To do this, first use odbcinst -j to locate USER and SYSTEM odbc.ini files. Then check those files for data sources that have the driver attribute set to .

  2. Remove the install.info for the Easysoft JDBC-ODBC Bridge from the /usr/local/easysoft directory.

Configuring the Easysoft JDBC-ODBC Bridge

Use the web administator to configure the Easysoft JDBC-ODBC Bridge.

To access the web administrator, got to:

http://serverhost:8031/

where serverhost is the host name computer on which the Easysoft JDBC-ODBC Bridge server is running.

The web administrator contains these pages:

The Statistics page

The Statistics page displays runtime statistics for the latest run of the server and lets you access other pages.

This page contains the following fields:

Field Description

Server up time

The time in days, hours, minutes, and seconds since the Easysoft JDBC-ODBC Bridge server was started.

Server CPU time (s)

This field is only visible if the ShowProcessTime flag is turned on

One or more values will be shown:

  • If only one value is shown, it is the total CPU time consumed by the Easysoft JDBC-ODBC Bridge server.

  • If two times are shown, the first is user time and the second is kernel time.

When the Easysoft JDBC-ODBC Bridge server is running multi-threaded, any of the CPU times shown include CPU time consumed by the ODBC driver manager, any ODBC drivers loaded and any child processes or threads. The process time is only updated when the Easysoft JDBC-ODBC Bridge server is idle. If the Easysoft JDBC-ODBC Bridge server is extremely busy servicing incoming connections, the process time will not be updated.

Total Connections

The total number of connections (or attempted connections) to the Easysoft JDBC-ODBC Bridge server.

This includes connections dropped due to no license or insufficient license slots, port scanners, or anyone using telnet to access the Easysoft JDBC-ODBC Bridge server port.

Total Threads/Processes

The total number of threads or processes that the Easysoft JDBC-ODBC Bridge server has created during its execution.

Connections denied access because of an access control rule or MaxThreadCount or MaxClientConnect being exceeded are not included, because the Easysoft JDBC-ODBC Bridge server does not start a thread or process for these.

Active Threads/Processes

The total number of active threads or processes the Easysoft JDBC-ODBC Bridge server has created to handle connections.

This number may exceed the actual active count as the Easysoft JDBC-ODBC Bridge server only looks for exited threads and processes when five seconds has elapsed without any connections. (This is done to give preference to incoming connections.)

Note that if MaxThreadCount or MaxClientConnect is set to anything other than 0, the Easysoft JDBC-ODBC Bridge server has to reap exited threads and processes every time a new connection arrives.

Also note that this is not a limit and may therefore exceed your maximum licensed connection slots.

Peak concurrent Threads/Processes

The highest value ever seen in the Active Threads/Processes count.

Last Connection time

The time the last connection occured.

Last Disconnect time

The time the last disconnection occured.

Number of different client hosts

The number of different client machines that have connected to the Easysoft JDBC-ODBC Bridge server (where a client machine is identified by its IP address).

Click on this link to get a list of IP addresses or machine names. Machine names are only displayed if you have ReverseLookup enabled.

Changing the refresh frequency

The Web Administrator uses a set of template files into which the dynamic data is inserted before sending it back to your browser.

The template file for the Statistics screen is index.html, which is located in the admin subdirectory under wherever you installed the Easysoft JDBC-ODBC Bridge server.

Open index.html in a text editor, and near the top you’ll find:

meta http-equiv="refresh" content="60"; URL=/index.html

Change 60 (the refresh time in seconds) to your new refresh time.

Note that setting the refresh time to a very low value will increase the workload on the Easysoft JDBC-ODBC Bridge server process which handles HTTP requests. As this may reduce the reponse time to the Easysoft JDBC-ODBC Bridge server thread, times much less than 60 seconds are not recommended.

The Configuration page

To change settings in this page, use the user name that you specified for this purpose during Easysoft JDBC-ODBC Bridge setup. (Unless you chose to turn off web administrator authentication, in which case no user name is needed.)

This page contains the following fields:

Field Description

Port

The port on which the Easysoft JDBC-ODBC Bridge server listens for incoming client connections.

The default port number is 8831, but it may be any port number not in use on your Easysoft JDBC-ODBC Bridge server machine.

HTTPPort

The port on which the Easysoft JDBC-ODBC Bridge server listens for HTTP (web administrator) requests.

The default port number is 8031, but it may be any port number not in use on your Easysoft JDBC-ODBC Bridge server machine.

If the Flags bitmask has the second bit set (HTTP_Server), the Easysoft JDBC-ODBC Bridge server starts listening on the specified port for HTTP requests in addition to acting in its normal role, serving client requests.

Timeout

The inactivity timeout in seconds (the default is 7200, two hours).

The Easysoft JDBC-ODBC Bridge server starts a new thread (or process) for each client that connects and if there has been no communication in Timeout seconds, the thread or process exits.

This ensures clients that fail to close down properly don’t cause increasing resource usage on the server.

To turn off the timeout, set it to 0.

MaxThreadCount

The maximum number of threads or processes the Easysoft JDBC-ODBC Bridge server allows at any one time.

One thread or process is created for every ODBC connection. If MaxThreadCount is set to 0, there is no limit. The default is 100.

Use this parameter to prevent too many simultaneous connections swamping your server.

RetryCount

The number of times the Easysoft JDBC-ODBC Bridge server attempts to create a thread or process to handle a connection, or the number of times the server attempts to obtain a license slot for a new connection.

RetryPause

The time in seconds between each retry attempt.

SingleStatement

By default, the Easysoft JDBC-ODBC Bridge attempts to pool statement handles in the ODBC driver and opens new connections to support multiple concurrent statements, even if the ODBC driver does not support this behaviour.

If you don’t need this feature (that is, you ensure that there is only a single result set open at any one time) set this to Y.

HTTPAdmin

The user name of the person allowed to make changes to the Easysoft JDBC-ODBC Bridge server by using the web administrator.

This must be a valid user name in the operating system the server is running on. If set to the disabled, web server authentication is not required.

The value is case-sensitive.

Path

The installation path of the Easysoft JDBC-ODBC Bridge.

This is a read-only parameter for information only.

Logging

A bitmask telling the Easysoft JDBC-ODBC Bridge server what sorts of event to record in the log file.

This should only be used as directed by Easysoft support and slows the Easysoft JDBC-ODBC Bridge down considerably if set. You may specify the number as decimal or hexadecimal. For example, 2047 or 0x7ff.

LogDir

The directory where Easysoft JDBC-ODBC Bridge log files are created.

It defaults to drive:\Program Files\Easysoft{PRODUCT}\Logs\ on Windows and /tmp on Linux and UNIX.

Flags

A bitmask of operational flags.

The bitmasks are split into check boxes, one for each bit:

  • Authentication_Disabled (0x1) If set, Easysoft JDBC-ODBC Bridge server authentication is turned off . Setting this parameter should be considered as a security risk. However, in controlled environments where you do not need to authenticate the connections this can save a considerable amount of time during connections. The default is off.

  • HTTP_Server (0x2) If set, the Easysoft JDBC-ODBC Bridge server listens for HTTP connections to the web administrator. The default is on.

  • MultiProcess (0x4) If set, the Easysoft JDBC-ODBC Bridge server starts a new process rather than a new thread for each incoming connection. Use this setting for an ODBC driver that’s not thread-safe or is leaking memory. On Linux and UNIX, The MultiProcess flag can’t be updated, as the server is not multi-threaded and therefore always starts new processes. The default is off.

  • HideSensitive (0x10) If set, the web administrator hides sensitive parameters on the Configuration page. The HTTPAdmin and Authentication_Disabled parameters are hidden when HideSensitive is set. All parameters are always shown in full on the Change Configurable Parameters page as this page is password protected. The default is off.

  • ReverseLookup (0x20) If set the Easysoft JDBC-ODBC Bridge server calls gethostbyaddr() on the connecting client’s IP address to obtain the client’s machine name. On machines where DNS is not set up properly, this can cause problems and in any case adds time to the connection. ReverseLookup currently only affects the number of different clients shown on the Statistics page, where "unknown" will be displayed instead of the machine name for the machine names of connecting clients if ReverseLookup is off. The default is off.

  • AuditODBCAccess (0x40) If set the Easysoft JDBC-ODBC Bridge server audits all connections to a log file, which can be examined in the web administrator. The audit file is written to the LogDir directory as esjob_access.log. The default is off.

  • ShowProcessTime (0x100) If set user and kernel CPU times for the main Easysoft JDBC-ODBC Bridge server process are displayed on the Statistics page Values are updated every five seconds. The default is off.

The Security page

This page lets you view or change the computers that are allowed to connect to the Easysoft JDBC-ODBC Bridge.

Easysoft JDBC-ODBC Bridge security splits IP addresses up into two lists: allowed and denied. When a computer attempts to connect to the Easysoft JDBC-ODBC Bridge server, access is only granted if:

  • The allowed list is empty and the IP address is not in the denied list. -Or-

  • The IP address is in the allowed list.

Addresses must be entered using the IP dot notation. Entries that consist of fewer than four fields represent all addresses that match the defined fields. For example:

163.141.23. (note the trailing dot) matches all IP addresses from:

163.141.23.0

to

163.141.23.255

The Information page

The page contains:

  • A list of links to Easysoft support resources

The Client Hosts page

The page lists the clients that have connected to the Easysoft JDBC-ODBC Bridge server. These connection attempts may not have been fully successful (for example, not authenticated or denied access).

The page contains the following fields:

Field Description

IP Address

The IP addresses of connecting clients.

FQDN

The fully qualified domain name of connecting clients, which are displayed as "unknown", unless ReverseLookup is turned on.

Connecting to your ODBC data source

Configure an ODBC data source

If you have not done so already, create a system ODBC data source that connects to the datastore you want to access from your Java application. Create the ODBC data source on the same computer as the one on which you installed the Easysoft JDBC-ODBC Bridge server.

You create system data sources in the System DSN tab in ODBC Data Source Administrator (Windows) or /etc/odbc.ini (Linux and UNIX).

Registering the Easysoft JDBC-ODBC Bridge

To register the Easysoft JDBC-ODBC Bridge JDBC driver, your Java application must specify the class easysoft.sql.jobDriver. For example:

Class.forName("easysoft.sql.jobDriver");

To make this class available, add the Easysoft JDBC-ODBC Bridge client (EJOB.jar) to the system-wide classpath or copy the client to a directory that’s already on the system-wide classpath or your application’s internal classpath.

The connection URL

When the Easysoft JDBC-ODBC Bridge JDBC driver is registered, you can establish a connection by using a connection URL and the getConnection method of the DriverManagerclass. For example:

String connectionUrl = "jdbc:easysoft:my_host/my_system_dsn_name";
Connection con = DriverManager.getConnection(connectionUrl);

Further information

Tracing

From the Easysoft JDBC-ODBC Bridge client

Use these Driver Manager methods:

// JDBC 1.x
DriverManager.setLogStream(java.io.PrintStream(java.io.PrintStream out))

-Or-

// JDBC 2.x+
DriverManager(java.io.PrintWriter out)

in your JAVA code to direct tracing output to a specified file.

It’s also possible to direct tracing to the standard output (Java console) by adding :trace=on to the Easysoft JDBC-ODBC Bridge JDBC URL.

Set the clearText=on to turn off encrypted transmission of connection information, which makes some tracing output unreadable.

For multi-threaded applications, set the :multi=on attribute, so that each trace line is prefixed with an indication of the thread that produced that line.

For example:

jdbc:easysoft://myhost/mydsn:trace=on:multi=on

From the Easysoft JDBC-ODBC Bridge server

Use ODBC tracing on the computer where the JDBC-ODBC Bridge server is installed.

To do this on Windows, in ODBC Data Source Administrator, click the Tracing tab. Enter a trace file name in the space provided. Choose Machine-wide tracing for all user identities, and then choose Start tracing now.

To do this on Linux and UNIX:, add this section to the start of odbcinst.ini (usually located in /etc/odbcinst.ini):

[ODBC]
Trace = Yes
TraceFile = /path/filename

For example:

[ODBC]
Trace = Yes
TraceFile = /tmp/sql.log

The user who is running the application to be traced must have write permission to TraceFile (and to the directory containing it).