Easysoft JDBC-ODBC Bridge User Guide - Configuring the Server

Configuring the Easysoft JDBC-ODBC Bridge Server

There are certain configurable parameters that affect the JOB Server, irrespective of the DSN to which you are connecting.

In Windows, these are stored in the registry.

In Unix they are held in the esjobserver.ini initialization file.

On either platform you can use the Web Administrator to modify these parameters.

Chapter Guide

Setting up the JOB Server on Windows

In Windows, data sources are made visible to applications through the Microsoft driver manager.

You set up a data source for the JOB Server in the same way as any ODBC application.

The JOB Server for Windows can connect to any System Data Source Name (System DSN) configured on your machine, given the necessary information.

If you do not already have a System DSN on your machine then now is the time to create one. You should use the ODBC driver suitable for your data source.

This section consists of a worked example where a System DSN is created for the Microsoft Northwind database, which is shipped with Microsoft Access.

The example is based around a 32-bit ODBC data source, as by default, the JOB installation program starts the 32-bit version of the JOB Server. (The JOB Server and ODBC driver architecture must be the same.) If you must use a 64-bit ODBC data source, for example, because your ODBC driver is 64-bit only, then you need to stop the 32-bit JOB Server in Windows Services, and start the 64-bit Server instead (Easysoft JDBC-ODBC Bridge Server x64).

You can follow the example as an exercise on your own computer, providing:

The first step is to open the Microsoft Data Source Administrator on the machine where the JOB Server is installed:

1.  In Control Panel, double-click Administrative Tools and then Data Sources ODBC Data Sources (32bit).

 The ODBC Data Source Administrator dialog box is displayed:

Figure 14: The ODBC Data Source Administrator User DSN Tab

2.  Select the System DSN tab:

Figure 15: The ODBC Data Source Administrator System DSN Tab

 It is important to create a system DSN rather than a user DSN, which is only visible to the desktop user who created it.

 Since the JOB Server runs as a service, User DSNs are not available to it.

3.  Click Add... to add a new DSN.

 The Create New Data Source dialog box is displayed, containing a list of drivers:

Figure 16: The Create New Data Source dialog box

4.  Select Microsoft Access Driver and click Finish.

 The ODBC driver for Microsoft Access displays a dialog box for configuring the Data Source (this step differs from one database to another).

5.  Enter a name for this data source in the Data Source Name box ("NorthwindDSN", for example).

 The text that is entered into the Description field may be displayed to a user if they choose to connect interactively.

 Enter a description, such as "JOB demonstration DSN":

Figure 17: The Microsoft Access ODBC driver configured

6.  Click Select... to browse for the target database, select your chosen database and click OK.

 This example uses the database in Microsoft Office\Office\Samples\Northwind.mdb, but this database may not exist or may be in a different location on your system. In this case, use any database you have to hand, preferably a small one.


Remember the Data Source Name, because it will be required when you come to connect through the Easysoft JDBC-ODBC Bridge.

7.  Click OK.

 You are returned to the ODBC Data Source Administrator window.

 Note that:

8.  Click OK.

You have now set up a system-wide Data Source Name on your machine to a local database, making it visible to the JOB Server (and all ODBC programs).

Starting the JOB Server on Windows

For your Java program to connect to the local DSN, the JOB Server must be running.

The installation program configures the JOB Server to start automatically as an Windows Service.

Alternatively, use the command-line interface and run server.bat, which stops any running JOB Server and Web Administrator and then starts them both again.

Go to Connecting from Java to connect a client.

Setting up the JOB Server on Unix

The Easysoft JDBC-ODBC Bridge is shipped as a binary executable linked with the unixODBC driver manager.

There are two ways to make your data source visible to the Easysoft JDBC-ODBC Bridge:

If you choose the second approach, then all Easysoft JDBC-ODBC Bridge connections will have to connect to your chosen ODBC driver.

If you use unixODBC you will be able to choose which ODBC driver to connect to at runtime.


unixODBC is a project creating free data access components for Unix platforms. It is not an Easysoft product, but its development and maintenance are sponsored by Easysoft and other industry bodies. For further information about using unixODBC, please visit http://www.unixodbc.org.

Using JOB with unixODBC

If it is supplied with the necessary information, the JOB Server can connect to any system data source configured on a Unix machine.

Easysoft recommend that you use the unixODBC driver manager supplied with the Easysoft JDBC-ODBC Bridge for setting up data sources on Unix


This section explains how to set up data sources using unixODBC, as installed by Easysoft. If you choose to use a different driver manager, you should refer to the documentation with that driver manager for details of setting up data sources on Unix.


With unixODBC, you can create a data source by either:

Creating a DSN by editing a configuration file

With unixODBC, data sources are stored in a configuration file called odbc.ini. If you accepted the default Easysoft JDBC-ODBC Bridge installation, system data sources will be stored in /etc/odbc.ini. If you have built unixODBC yourself, the directory is specified in the --sysconfdir=directory configuration option.

You usually have to be logged in as root to edit the system odbc.ini.

Each section of the odbc.ini file starts with a data source name in square brackets [ ] followed by a number of attribute=value pairs.


Attribute names in odbc.ini are not case sensitive.

The attributes that you need to specify vary depending on which ODBC driver you are using to connect to the local database.

For example, a data source using the PostgreSQL driver will be in the format:


Description = Main data on Admin box

Driver = PostgreSQL

Trace = No

TraceFile = sql.log

Database = main

Servername = localhost

UserName =

Password =

Port = 5432

Protocol = 6.4

ReadOnly = No

RowVersioning = No

ShowSystemTables = No

ShowOidColumn = No

FakeOidIndex = No

ConnSettings =

unixODBC uses the DRIVER attibute to look up the driver in the odbcinst.ini file and locate the shared object to use as the ODBC driver.

Refer to the documentation with your ODBC driver for full details of the attributes it requires to define a data source.

Creating a DSN using the ODBC Data Source Administrator

To create a data source using the graphical ODBC Data Source Administrator supplied with unixODBC:

1.  Run an X session connecting to your Unix machine, ensuring that you log in as root.

2.  Change into the <InstallDir>/easysoft/unixODBC/bin directory.

3.  Type ./ODBCConfig <Enter>.

 The ODBC Data Source Administrator opens.

4.  Select the System DSN tab.

 This will create a data source which is available to any user or service that logs into this machine.

5.  Click Add to create a new data source.

 The Adding a New Data Source dialog box displays a list of the drivers which are available.

6.  Select the driver that you want to use to connect to the database.

7.  Click OK.

 A driver-specific New Data Source dialog box is displayed.

 The dialog box for setting up a PostgreSQL data source will be in the format:

Figure 18: The Configuration dialog box for a PostgreSQL data source

 Refer to the documentation with your ODBC driver for full details of the attributes you need to specify on this dialog box.

8.  Click OK when you have specified all the data source attributes and then close the ODBC Data Source Administrator.

Testing the Data Source

You now have a data source connecting to the database on your server.

Before attempting to connect via the Easysoft JDBC-ODBC Bridge, you should test that this data source is working so that you can be confident that the server side is functioning correctly.

You can do this using any ODBC application available on your Unix machine, or using the isql utility provided with unixODBC.

To use isql to test the data source:

1.  Change into the <InstallDir>/easysoft/unixODBC/bin directory

2.  Type:

 ./isql -v data_source_name

 For example, to connect to the PostgreSQL data source illustrated earlier in this section, you would type:

 ./isql -v main

 If the DBMS on your server requires authentication, you should type:

 ./isql -v data_source_name [user_name] [user_password]

3.  Once connected, type an SQL statement to query the data.


 select * from table;

 where table is a table in that database, or type help to get a list of tables in the database.

4.  To leave isql and return to the system prompt, press <Enter>.

Once you have established that the data source on your server machine is accessing data correctly, you can establish a connection to the data source across the Easysoft JDBC-ODBC Bridge.

Starting the server in Unix

For your Java program to connect to the local DSN, the JOB Server must be running.

Normally the JOB Server will be started at the end of the installation procedure, but if you need to start or stop it manually, change into the <InstallDir>/easysoft/job directory and then:



You should consider putting these scripts into your system's startup and shutdown scripts or into your path.

After using stopjob you may need to wait for the socket to time-out before trying to start the JOB Server using startjob.


To stop the JOB Server, you must be logged in as the user who started the JOB Server. Usually this will be root.

See Starting the JOB server for more details.

The Web Administrator

This section provides a tour of the Web Administrator interface and shows you how to change the configurable parameter settings in the JOB Server.

You can also edit these settings through:

In order to follow this section you will need:

¯ OR ¯

the root user name and password on Unix.


The Web Administrator user name is displayed in the case sensitive HTTPAdmin field on the Configuration screen (see The Configuration Screen), which is hidden by default, but can be amended.

Update access will be denied if HTTPAdmin does not specify a valid user on the server system (setting it to "disabled" disallows HTTP Authentication).

Open the URL http://serverhost:8031/ (where serverhost is the name of the host running the JOB Server) from a web browser.

Depending on your server configuration, you may need to specify a port address different from the Easysoft default of 8031.

If you click on a link to a protected page you will be prompted by your browser for the Web Administrator user name and password for the ESJOBServer realm:

Figure 19: The Enter Network Password dialog box

The web page returned is generated by the server process.

The Statistics Screen displays runtime statistics for the latest run of the server and allows access to the following additional screens:

The Statistics Screen

The Web Administrator Statistics screen contains the following fields:

The time in days, hours, minutes and seconds since the JOB Server was started.

This field is only visible if the ShowProcessTime flag is set to on (see ShowProcessTime).

One or more values will be shown:

Note that:

The total number of connections (or attempted connections) to the JOB Server.

This will include connections dropped due to no license or insufficient license slots, port scanners or anyone using telnet to access the JOB Server port.

The total number of threads or processes that the JOB Server has created during its execution.

Connections denied access because of an access control rule or MaxThreadCount/MaxClientConnect being exceeded are not included, because the JOB Server does not start a thread or process for these.

The total number of active threads or processes the JOB Server has created to handle connections.

This number may exceed the actual active count as the JOB 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 then the JOB 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.

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

The time the last connection occured.

The time the last disconnection occured.

The number of different client machines which have connected to the JOB Server (where a client machine is identified by its IP address).

You can 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 directory wherever you installed the JOB Server.

Edit the index.html file and near the top you will see:

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

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


Note that setting the refresh time to a very low value will increase the workload on the JOB Server process which handles HTTP requests.

As this may reduce the reponse time to the JOB Server thread, times much less than 60 seconds are not recommended.

The Configuration Screen

This section explains the parameters that are configurable via the Web Administrator Configuration screen.

These parameters apply either to the JOB Server itself, or as a default value for all DSNs accessed via the server.

Brief reminder notes are available by scrolling the browser window. Make your changes and click Submit. At the confirmation screen, click another menu option or wait a few seconds to return to the Server Configuration screen and see the changes you have made.

These settings, and some additional settings, can also be edited via the registry in Windows (see The Windows Registry entry) or in the esjobserver.ini file in Unix (see The Unix initialization file).

The Web Administrator Configuration screen displays the configurable parameters of the server process. Some sensitive settings may not be displayed.

You can modify the server settings by clicking Change and then typing the Web Administrator user name and password when prompted.

The Web Administrator user name is the network user entered during the installation process and the password the one required for that user on the system where the JOB Server is running.


You are only asked for log in details if authentication has been enabled by entering a value other than "disabled" into the HTTPAdmin field on the Web Administrator Change Configuration screen.

The Configuration screen contains the following fields (click Submit to make your changes).

Values are case-dependent if the operating-system is, so it is best to match case where possible:

The port on which the JOB Server listens for incoming JOB Client connections.

The default port number is 8831, but it may be any port number not in use on your JOB Server machine.

The port on which the JOB Server listens for HTTP requests (i.e. runs the Web Administrator).

The default port number is 8031, but it may be any port number not in use on your JOB Server machine.

If the Flags option bitmask has the second bit set (see HTTP_Server) the JOB Server starts listening on the specified port for HTTP requests in addition to acting in its normal role serving the JOB Client.

You may use the URL http://machine_name:HTTPPort where machine_name is the name (or IP address) of the JOB Server machine, and HTTPPort is the port number to communicate with the JOB Server from your browser.

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

The JOB 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 which fail to closedown properly do not cause increasing resource usage on the server.

To disable the timeout, set it to 0.

The maximum number of threads or processes the Easysoft JDBC-ODBC Bridge Server will allow at any time.

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

You can use this parameter to prevent too many simultaneous connections swamping your server.

The number of times the JOB Server will attempt to create a thread or process to handle a connection, or the number of times the the server will attempt to obtain a license slot for a new connection.

The time in seconds between each retry attempt (see RetryCount).

By default, the Easysoft JDBC-ODBC Bridge will attempt to pool statement handles in the ODBC driver and open new connections to support multiple concurrent statements, even if the backend ODBC driver does not.

If you know that you do not need this feature (i.e. you ensure that there is only a single result set open at any one time) set this to "Y".

The user name of the person allowed to make changes to the JOB Server via the Web Administrator.

This must be a valid user name in the operating system the server is running on. If set to the string "disabled" (omit the quotes) then authentication is not required (this does not mean the JOB Server stops authenticating incoming connections).

The value is case-sensitive.


The "eye" symbol displayed against the HTTPAdmin parameter is used to denote that the value of the field is hidden from the user unless they gain access to the corresponding screen by clicking Change and entering user name and password details.

The installation path of the Easysoft JDBC-ODBC Bridge.

This is a read-only parameter for information only.

A bitmask telling the JOB Server what sorts of event to record in the log file.

This should only be used as directed by Easysoft support and will slow the Easysoft JDBC-ODBC Bridge down considerably if set. You may specify the number as decimal or hexadecimal (e.g. 2047 or 0x7ff).

The directory where log files are created (see Logging).

It defaults to drive:\Program Files\Easysoft\Easysoft JDBC-ODBC Bridge\Logs\ on Windows and /tmp on Unix.

A bitmask of operational flags.

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

The Security Screen

The Web Administrator Security screen displays and allows the user to view or change the set of hosts that are allowed to connect to the Easysoft JDBC-ODBC Bridge.

The Web Administrator user name and password are required if they have not yet been entered:

In addition to the user names and passwords of your system and of the database management system, the Easysoft JDBC-ODBC Bridge provides another layer of security with access control lists.

To add an IP address to a list, type the address or address-stem into either the Allowed Access or Denied Access boxes and click Add.

Unix administrators will recognize this mechanism from the hosts.allow and hosts.deny files.


Although the approach is similar, the rules for determining whether or not a host should be allowed to connect are different from those for hosts.allow and hosts.deny.

Security for the Easysoft JDBC-ODBC Bridge takes the form of two lists of IP addresses.

When a host attempts to connect to the JOB Server, access is only granted if:

The lists can be edited either in the registry (Windows), their relevant flat files (Unix), or via the Web Administrator (Windows and Unix when run standalone.)

Addresses must be entered using the IP `dot' notation.

Entries which consist of fewer than four fields represent all the addresses that match the fields which are defined.


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


Direct editing is not supported by Easysoft and will not allow access to changed values until the server has been rebooted.

The Information Screen

The Web Administrator Information screen displays a list of links to Easysoft support resources:

The Client Hosts Screen

The Web Administrator Client Hosts screen displays a list of individual clients which have connected to the JOB Server. These connection attempts may not have been fully successful (e.g. not authenticated or denied access).

The screen contains the following fields:

The Windows Registry entry

If you cannot remember the user name or you do not know the corresponding password, then you will not be able to modify the configuration of the JOB Server via the Web Administrator.

In this case you need to log in directly to the server host and edit the registry.

The registry key for the Easysoft JDBC-ODBC-Bridge is:

HKEY_LOCAL_MACHINE/SOFTWARE/Easysoft JDBC-ODBC Bridge/Configuration/System/settings

Note that the registry key contains a string value for each of the Server Configurable Parameters (numeric parameters are stored in strings):

Figure 20: The Windows Registry entry

See The Configuration Screen for full details of each of these settings.

The Unix initialization file

If you do not know the password then you will not be able to modify the JOB Server configuration via the Web Administrator.

In this case, for the you need to log in directly to the server host and edit <InstallDir>/easysoft/job/server/esjobserver.ini.

If <Installir> is anything other than /usr/local/ then there will be a symbolic link /usr/local/easysoft to the real Easysoft directory.

An example esjobserver.ini file follows:


Port = 8831

HTTPPort = 8031

Timeout = 3600

LogDir = /tmp

Logging = 0

Flags = 38

RetryCount = 5

RetryPause = 3

AllowList =

DenyList =

MaxThreadCount = 0

MaxClientConnect = 0

HTTPAdmin = John Smith

See The Configuration Screen for full details of each of these settings.


Lines beginning with # are comments. The first non-comment line should be {Settings} and the rest of the file should be Key=Value pairs. Bitmask values are given either in decimal or in hexadecimal. The Flags attribute must be included, and must be given a value of 38, unless you are advised otherwise by Easysoft.