 Kognitio Limited 2015
Kognitio JDBC/ODBC Bridge Installation and Configuration Guide
Kognitio JDBC/ODBC Bridge
Installation and Configuration Guide
Kognitio Document No
Authors
Reviewed By
Authorised By
V1.2
20th May 2015
Greg Loxton
Scott deVilliers
Stuart Watt
Document Version
V1.2
Date
20th May 2015
Page 1
 Kognitio Limited 2015
Kognitio JDBC/ODBC Bridge Installation and Configuration Guide
Table Of Contents
1.
Introduction .................................................................................................................. 3
2.
Pre-Requisites ............................................................................................................... 3
3.
Linux Installation .......................................................................................................... 4
3.1
3.1.1
3.1.2
3.2
3.3
4.
Linux Installation prerequisites ....................................................................................................... 4
Kognitio Client tools Installation ................................................................................................................ 4
unixODBC Installation ............................................................................................................................ 4
32-bit Linux Install........................................................................................................................ 6
64-bit Linux Install........................................................................................................................ 6
Windows Installation .................................................................................................... 8
4.1
4.1.1
4.2
4.3
Windows Installation prerequisites ................................................................................................... 8
Kognitio Client tools Installation ................................................................................................................ 8
32-bit Windows Install.................................................................................................................. 10
64-bit Windows Install.................................................................................................................. 11
5.
Client Configuration ................................................................................................... 12
6.
Running D2OServer as a deamon process ................................................................. 14
V1.2
20th May 2015
Page 2
 Kognitio Limited 2015
1.
Kognitio JDBC/ODBC Bridge Installation and Configuration Guide
Introduction
Kognitio provides a JDBC/ODBC bridge to allow any Java application to use the JDBC API to connect to and
query the Kognitio Analytical Platform via its ODBC driver through a standardised JDBC interface. Once
installed, this provides zero installation JDBC access from any Java platform to the defined Kognitio database.
The JDBC/ODBC bridge operates as the middle tier in a 3-tier architecture. The JDBC/ODBC bridge runs as a
standalone application where the application driver converts the JDBC method calls from the client Java
application into ODBC function calls that are then run against the Kognitio database.
Kognitio recommends the JDBC/ODBC bridge software is installed either on the Kognitio AP or another node
(either Windows or Linux) with good connectivity to the Kognitio database. Although the JDBC/ODBC bridge
software can be installed on a database node, this is not recommended.
2.
Pre-Requisites
The Kognitio ODBC driver must be installed in the environment running the JDBC/ODBC bridge.
Linux platforms must have an ODBC driver manager such as unixODBC installed.
Windows environments must have the Microsoft Visual C++ 2008 Redistributable installed.
V1.2
20th May 2015
Page 3
 Kognitio Limited 2015
3.
Kognitio JDBC/ODBC Bridge Installation and Configuration Guide
Linux Installation
3.1 Linux Installation prerequisites
In a Linux environment, the Kognitio ODBC drivers must be installed and operational before the
JDBC/ODBC bridge can be configured. An existing Kognitio AP will already have an appropriate environment
setup, so the JDBC/ODBC bridge can be installed on an AP to use the existing ODBC DSNs. The
JDBC/ODBC bridge can be successfully installed and run under the wxadmin user on a Kognitio AP.
If the JDBC/ODBC bridge is to be installed in a Linux environment other than an existing Kognitio AP, then
the Kognitio ODBC drivers and an ODBC Driver Manager such as unixODBC must be installed. Kognitio
recommends using unixODBC and the installation guidelines for this can be found in section 3.1.2 below.
3.1.1 Kognitio Client tools Installation
For an non-AP install, the Kognitio ODBC drivers should be downloaded from the Kognitio support portal
(http://support.kognitio.com). The file 'wx2-linux-clients-nnnnna.tar.gz' contains the Kognitio client tools and
ODBC drivers for Linux. Full installation details can be found on the Kognitio support portal, but for a
JDBC/ODBC bridge environment this should be installed as follows:
1. Create the directory structure for the install e.g. '/opt/kognitio';
2. Unzip the file 'wx2-linux-clients-nnnnna.tar.gz' and copy the tar file (wx2-linux-clients-nnnnna.tar) to
/opt/kognitio;
3. Execute 'tar -xvf wx2-linux-clients-nnnnna.tar'.
This will install the Kognitio ODBC drivers that will be used by unixODBC.
3.1.2 unixODBC Installation
Kognitio recommends that unixODBC version 2.3.1 is used. If an earlier version of unixODBC is to be
used, please contact Kognitio support for further details.
It is recommended that an appropriate user is created on the linux server to run both unixODBC and the
JDBC/ODBC bridge. This user will require appropriate privileges to create directories and create/amend files in
the following directories:
/etc
/usr/local/bin
/usr/local/lib
/usr/local/etc
/usr/local/include
The server should have the linux development tools packages installed to allow the compilation of the
unixODBC code during its installation.
unixODBC is available as source code only. To install, this means that once the source code is downloaded (via
a zipped tar file from http://www.unixODBC.org) , it must be extracted, compiled and installed before it can be
used.
Once downloaded and unzipped, create an appropriate installation directory and copy the tar file to this
directory:
1. Create a directory for the install e.g. '/opt/unixODBC';
2. Unzip and copy the tar file (unixODBC-2.3.1.tar) to /opt/unixODBC;
3. Execute ‘tar –xvf unixODBC-2.3.1.tar’
V1.2
20th May 2015
Page 4
 Kognitio Limited 2015
Kognitio JDBC/ODBC Bridge Installation and Configuration Guide
4. cd to the sub directory created (e.g. ‘cd unixODBC-2.3.1’)
5. Execute ‘./configure’ – and check the output for any error messages. If there are any error messages,
investigate these before proceeding.
6. Execute ‘make’. Again check the output for any error messages. If there are any error messages,
investigate these before proceeding.
7. Execute ‘make install’ – this should be run as root, but can be run as the installation user if they have
write privileges to the directories listed above. Again check the output for any error messages. If there
are any error messages, investigate these before proceeding.
This process will install the unixODBC executables into /usr/local/bin
Alternatively on RedHat/Fedora environments this could be installed via “yum” if the system is connected to
the internet. If this is possible then ignore steps above.
Once unixODBC and the Kognitio client tools and ODBC drivers have been successfully installed, an ODBC
DSN (Data Source Name) should be created. The ODBC DSN for unixODBC is separate to an ODBC DSN
created for Kognitio, although the file name used is the same, odbc.ini. A local DSN file can be created as detailed
below, but this can also be exported as a system DSN file. ODBC distinguishes between two types of ini files.
System ini files are designed to be accessible but not modifiable by any user; user files are private to a particular
user and may be modified by that user. The system files are odbcinst.ini and odbc.ini (note no leading dot), and
the user file is ~/.odbc.ini in each user's home directory (note leading dot). The system file odbcinst.ini contains
information about ODBC drivers available to all users, and the odbc.ini file contains information about DSN's
available to all users. The System DSN's are useful to allow all users to share a common DSN without requiring
their own local .odbc.ini.
The odbcinst.ini should be created first. This contains a section heading that provides a name for the driver,
with the following lines containing a description and driver paths. The Driver and Setup paths point to the
ODBC driver and the ODBC setup libraries. An example odbcinst.ini for Kognitio is as follows as should be
created in the users home directory as .odbcinst.ini:
[WX2]
Description
Driver
Setup
= WX2 ODBC driver for Linux
= /opt/kognitio/lib/libwcsodbc_utf16.so
= /opt/kognitio/lib/libwcsodbcS.so
Please note 64bit environments should use the lib64 directory, e.g. /opt/kognitio/lib64. Also, as detailed
above, the utf16 driver needs to be used (libwcsodbc_utf16.so) rather than the default driver for the
Kognitio JDBC/ODBC bridge to operate.
The following command then publishes this odbcinst.ini file to the /usr/local/etc directory:
‘/usr/local/bin/odbcinst -i -d -f .odbcinst.ini’
The odbc.ini file contains the DSN that is needed to connect to the server. An example odbc.ini for a DSN
named wx2_vm is as follows and should be created in the user’s home directory as .odbc.ini:
[ODBC Data Sources]
wx2_vm=wx2_vm
[wx2_vm]
Driver=/opt/kognitio/lib/libwcsodbc_utf16.so
Description=WX2 Driver on VM server
ServerAddress1=<your 1st WX node IP address here>
ServerPort1=6550
ServerAddress2=<your 2nd WX node IP address here>
ServerPort2=6550
Timeout=15
ForceConnect=N
SslEnabled=N
[ODBC]
Trace=0
V1.2
20th May 2015
Page 5
 Kognitio Limited 2015
Kognitio JDBC/ODBC Bridge Installation and Configuration Guide
TraceFile=/tmp/odbctrace.log
Debug=0
DebugFile=/tmp/odbcdebug.log
WX2ODBCDbg=0
WX2ODBCDbgFilename=/tmp/wx2odbc.log
ServerAddresses 2 to n can be specified for multiple IP addresses of the Kognitio nodes in your system. If there
is only one Kognitio node then just comment out or remove these lines.
The section starting [ODBC] sets up the environment for tracing, but all values are set to 0 (disabled). Amending
the values to 1 enables tracing.
The following command then publishes this file to the /usr/local/etc directory:
‘/usr/local/bin/odbcinst -i -s -f .odbc.ini’
Alternately the .odbc.ini file can simply be copied to the /usr/local/etc directory
Finally the path to the unixODBC libraries should be added to LD_LIBRARY_PATH:
‘export LD_LIBRARY_PATH=$LD_LIBRARY_PATH: /usr/local/lib’
Connectivity via unixODBC can then be tested using the command:
‘/usr/local/bin/isql –v odbc_dsn username password’
3.2 32-bit Linux Install
The Kognitio JDBC/ODBC Bridge installation can be downloaded from the Kognitio support portal
(http://support.kognitio.com). The file ‘jdbc_odbc_bridge_installer_1.n.n.n.sh’ is a self-extracting shell script
install the Kognitio JDBC/ODBC bridge on Linux. The extracted file set contains a command line interactive
installer. Installation is as follows:
1. Run the executable:
jdbc_odbc_bridge_installer_1.n.n.n.sh (you may have to provide execute permission on this file via
chmod +x jdbc_odbc_bridge_installer_n.n.n.n.sh
2. Follow the prompts:
a. Specify the desired installation directory, or accept the default [enter]
b. Provide the data source name (DSN) from your active odbc.ini file for the jdbc to odbc bridge to
use
c. Specify the port number that the jdbc to odbc bridge should listen on, or accept the default
3. Add the full path of the "Lib/32" directory to the "LD_LIBRARY_PATH" environment variable
(e.g. ‘export LD_LIBRARY_PATH=$LD_LIBRARY_PATH: /opt/JDBC/Kognitio/Lib/32’
4. Execute D2OServerLauncher.sh in the ‘Bin/32’ directory as follows:
nohup ./D2OServerLauncher.sh &
This will persist a process named D2OServer that will survive the session end. There is a section
below that describes launching the D2OServerLauncher.sh using the /etc/init.d technique, such that
it will launch automatically at system boot.
3.3 64-bit Linux Install
The Kognitio JDBC/ODBC Bridge installation can be downloaded from the Kognitio support portal
(http://support.kognitio.com). The file ‘jdbc_odbc_bridge_installer_1.n.n.n.sh’ is a self-extracting shell script
V1.2
20th May 2015
Page 6
 Kognitio Limited 2015
Kognitio JDBC/ODBC Bridge Installation and Configuration Guide
install the Kognitio JDBC/ODBC bridge on Linux. The extracted file set contains a command line interactive
installer. Installation is as follows:
1. Run the executable:
jdbc_odbc_bridge_installer_1.n.n.n.sh (you may have to provide execute permission on this file via
chmod +x jdbc_odbc_bridge_installer_n.n.n.n.sh
2. Follow the prompts:
a. Specify the desired installation directory, or accept the default [enter]
b. Provide the data source name (DSN) from your active odbc.ini file for the jdbc to odbc bridge to
use
c. Specify the port number that the jdbc to odbc bridge should listen on, or accept the default
3. Add the full path of the "Lib/32" directory to the "LD_LIBRARY_PATH" environment variable
(e.g. ‘export LD_LIBRARY_PATH=$LD_LIBRARY_PATH: /opt/JDBC/Kognitio/Lib/32’
4. Execute D2OServerLauncher.sh in the ‘Bin/32’ directory as follows:
nohup ./D2OServerLauncher.sh &
This will persist a process named D2OServer that will survive the session end. There is a section
below that describes launching the D2OServerLauncher.sh using the /etc/init.d technique, such that
it will launch automatically at system boot.
V1.2
20th May 2015
Page 7
 Kognitio Limited 2015
4.
Kognitio JDBC/ODBC Bridge Installation and Configuration Guide
Windows Installation
4.1 Windows Installation prerequisites
In a Windows environment, the Kognitio ODBC drivers must be installed and operational before the
JDBC/ODBC bridge can be configured.
In order to run the Kognitio JDBC/ODBC Bridge server, the windows server must have the Microsoft Visual
C++ 2008 Redistributable installed. The package can be downloaded from the Microsoft Download Center:
32-bit (x86) - http://www.microsoft.com/download/en/details.aspx?displaylang=en&id=29
64-bit (x64) - http://www.microsoft.com/download/en/details.aspx?displaylang=en&id=15336
4.1.1 Kognitio Client tools Installation
The Kognitio ODBC drivers can be downloaded from the Kognitio support portal
(http://support.kognitio.com). Full installation details can be found on the Kognitio support portal, but for a
JDBC/ODBC bridge environment the downloaded Kognitio client tools package (‘wx2clients-bbnnnnna.exe’ [where bb is 32 or 64]) needs to be installed on the PC by running the executable. This will
display the following screen:
Note: You should not install the ‘Legacy ODBC driver’ unless instructed to do so by Kognitio
Support.
Once the client tools have been successfully installed, an ODBC entry needs to be created on the
client server to allow it to communicate with the back-end Kognitio server.
To set up an ODBC entry, open the Microsoft ODBC Administrator program from the
Windows Start menu via:
V1.2
20th May 2015
Page 8
 Kognitio Limited 2015
Kognitio JDBC/ODBC Bridge Installation and Configuration Guide
Start->Settings->Control Panel->Administrative Tools->Data Sources (ODBC),
which should
result in a window similar to the following:
Click on the System DSN tab, click on ‘Add…’ button, then select the ‘Kognitio WX2’ ODBC driver and
click on ‘Finish’ as follows:
This will open the Kognitio ODBC Driver Setup window:
Enter the following basic details:
V1.2
20th May 2015
Page 9
 Kognitio Limited 2015
Kognitio JDBC/ODBC Bridge Installation and Configuration Guide
 Data Source Name (DSN) – The ODBC name of the Kognitio server;
 Description – Optional description of the data source;
 Network Address – (entries 2-8 can be left blank).
Once the IP address has been entered, click ‘OK’ to close the Kognitio driver setup screen. The Kognitio
ODBC entry has now been set up and the ODBC Administrator program can now be closed.
4.2 32-bit Windows Install
The Kognitio JDBC/ODBC Bridge installation can be downloaded from the Kognitio support portal
(http://support.kognitio.com). The zipped file ‘JDBC-ODBC-bridge-win-1. n.n.n.zip’ contains the all files
required to install the Kognitio JDBC/ODBC bridge on Windows. This should be installed as follows:
1. Create a directory for the install e.g. 'C:\Program Files\Kognitio\JDBC’
2. Unzip the file (JDBC-ODBC-bridge-win-1. n.n.n.zip’) to this directory;
3. Edit the D2OServer.reg in the Setup directory:
- “ErrorMessagesPath” – replace <INSTALL_DIR> with the path where the Kognitio folder
resides (e.g. C:\Program Files\Kognitio\JDBC).
- “ServerDSN” – replace <SERVER_DSN> with the ODBC data source name that refers to the
Kognitio server to be used by the bridge (e.g. wx2_vm).
- “ListenPort” – set to the value of the port on which you want your server to listen (The default
port is 12345).
- “SslCertfile” – replace <INSTALL_DIR> with the path where the Kognitio folder resides (e.g.
C:\Program Files\Kognitio\JDBC).
- “SslKeyFile” – replace <INSTALL_DIR> with the path where the Kognitio folder resides (e.g.
C:\Program Files\Kognitio\JDBC).
4. Save the .reg file once you have finished editing it.
5. Double-click on the .reg file to import it into your registry
V1.2
20th May 2015
Page 10
 Kognitio Limited 2015
Kognitio JDBC/ODBC Bridge Installation and Configuration Guide
At this point the executable simply be run from the Binaries\Win32 directory (e.g. C:\Program
Files\Kognitio\JDBC\Kognitio\Binaries\Win32), or it can be installed as a Windows service. To install this as
a Windows service:
6. From a command line with administrative privileges, execute
C:\Program Files\Kognitio\JDBC\Kognitio\Binaries\Win32\D2OServer.exe -Install
7. This installs the service as ‘D2OService’, and it is set up to start automatically when Windows starts.
You can reconfigure it or manually start it immediately from the Services Administrative Control
Panel. Alternatively, you can also start and stop the service from a command line by executing ‘net
start D2OService’ to start, and ‘net stop D2OService’ to stop the service.
The D20Service can be uninstalled if required by executing the following from a command line:
C:\Program Files\Kognitio\JDBC\Binaries\Win32\D2OServer.exe -Uninstall
4.3 64-bit Windows Install
The Kognitio JDBC/ODBC Bridge installation can be downloaded from the Kognitio support portal
(http://support.kognitio.com). The zipped file ‘JDBC-ODBC-bridge-win-1. n.n.n.zip’ contains the all files
required to install the Kognitio JDBC/ODBC bridge on Windows. Installation notes can be found in this
zipped file, but this should be installed as follows:
1. Create a directory for the install e.g. 'C:\Program Files\Kognitio\JDBC’
2. Unzip the file (‘JDBC-ODBC-bridge-win-1. n.n.n.zip’) to this directory;
3. Edit the D2OServer.reg in the Setup directory:
- “ErrorMessagesPath” – replace <INSTALL_DIR> with the path where the Kognitio folder
resides (e.g. C:\Program Files\Kognitio\JDBC).
- “ServerDSN” – replace <SERVER_DSN> with the ODBC data source name that refers to the
Kognitio server to be used by the bridge (e.g. wx2_vm).
- “ListenPort” – set to the value of the port on which you want your server to listen (The default
port is 12345).
- “SslCertfile” – replace <INSTALL_DIR> with the path where the Kognitio folder resides (e.g.
C:\Program Files\Kognitio\JDBC).
- “SslKeyFile” – replace <INSTALL_DIR> with the path where the Kognitio folder resides (e.g.
C:\Program Files\Kognitio\JDBC).
4. Save the .reg file once you have finished editing it.
5. Double-click on the .reg file to import it into your registry
At this point the executable simply be run from the Binaries\x64 directory (e.g. C:\Program
Files\Kognitio\JDBC\Binaries\x64), or it can be installed as a Windows service. To install this as a Windows
service:
6. From a command line with administrative privileges, execute
C:\Program Files\Kognitio\JDBC\Binaries\x64\D2OServer.exe -Install
7. This installs the service as ‘D2OService’, and it is set up to start automatically when Windows starts.
You can reconfigure it or manually start it immediately from the Services Administrative Control
Panel. Alternatively, you can also start and stop the service from a command line by executing ‘net
start D2OService’ to start, and ‘net stop D2OService’ to stop the service.
The D20Service can be uninstalled if required by executing the following from a command line:
C:\Program Files\Kognitio\JDBC\Binaries\x64\D2OServer.exe -Uninstall
V1.2
20th May 2015
Page 11
 Kognitio Limited 2015
5.
Kognitio JDBC/ODBC Bridge Installation and Configuration Guide
Client Configuration
Once the JDBC/ODBC bridge server installation is complete, the JDBC connection configuration can be
performed on the client.
The Kognitio.jar file from the Java directory (e.g. /opt/JDBC/Kognitio/Java on Linux or C:\Program
Files\Kognitio\JDBC\Java on Windows) should be copied to the client machine. Once this is in place the
JDBC driver in the Java application should be configured according to the application’s driver installation
instructions:
The Driver class is named: com.kognitio.jdbc.Driver
The JDBC Driver URL will be in the form: jdbc:kognitio://<hostname>:<port>
Below is a sample configuration using SQuirreLSQL:
1. Configure the driver class name to:
com.kognitio.jdbc.Driver
This will point to the Kognitio.jar downloaded from the installed server and saved into an appropriate
directory (e.g. C:\Program Files\Kognitio\JDBC). This directory may need to be specified in the
application class path and/or saved in an application specific location - depending upon application.
In SQuirreLSQL, goto Drivers->New Driver. Enter Name and Example URLs as shown. Add the "Extra
Class Path" for the driver, choosing the path where the Kognitio.jar file is located. Enter the "Class
Name" as shown.
2. Add the Alias to Squirrel for your connection.
V1.2
20th May 2015
Page 12
 Kognitio Limited 2015
Kognitio JDBC/ODBC Bridge Installation and Configuration Guide
Aliases->New Alias. Enter parameters as shown to connect to the Kognitio DSN specified in the installed
server:
The application is now configured to connect to the Kognitio instance.
V1.2
20th May 2015
Page 13
 Kognitio Limited 2015
6.
Kognitio JDBC/ODBC Bridge Installation and Configuration Guide
Running D2OServer as a deamon process
The D2OServer can be run as a startup service if it is run behind a simple application which calls the daemon()
function. A script named D2OServerLauncher.sh has been provided in the Bin/32 or Bin/64 directory. Below
is a chkconfig script (named simba) that can be used as a system service that can start automatically at system
boot.
#!/bin/sh
#
# Startup script for program
#
# chkconfig: 345 99 15
- start or stop process definition within the boot process
# description: Simba JDBC Bridge Daemon
# processname: /disks/simba/Kognitio/Bin/64/D2OServer
# pidfile: /var/run/D2OServer.pid
#include <stdlib.h>
#include <unistd.h>
# Source function library.
to be started
. /etc/rc.d/init.d/functions
This creates the operating environment for the process
export
LD_LIBRARY_PATH=/usr/lib:/opt/kognitio/wx2/current/lib:/disks/simba/Kognitio/Lib/32/
case "$1" in
start)
echo -e -n "\t\t\r Starting process-name: "
daemon /disks/simba/Kognitio/Bin/32/D2OServer &
#
int main(void)
#
{
#
daemon(0,1);
#
return system("/disks/simba/Kognitio/Bin/32/D2OServer");
#
}
echo
;;
stop)
echo -e -n "\t\t\r Shutting down Simba JDBC Bridge: "
killproc D2OServer
;;
status)
status D2OServer
;;
*)
echo "Usage: $0 {start|stop|status}"
exit 1
esac
exit 0

As root, save/copy simba script to /etc/init.d

Chmod the simba script to make executable
chmod +x simba
V1.2
20th May 2015
Page 14
 Kognitio Limited 2015

Kognitio JDBC/ODBC Bridge Installation and Configuration Guide
As root, add simba to the appropriate runlevels, as defined in the script above:
chkconfig --add simba

Check status of last command:
chkconfig --list simba

Use linux “service” command to start the newly added service:
service simba start
If an error occurs, double check your environment variables in the startsimba script.
Notes: The “simba” script above is using paths present on a VM used to create this section of this document when
following the above listed steps.
V1.2
20th May 2015
Page 15