Installing and Configuring the ODBC Driver

This topic describes how to install and configure the ODBC driver on Linux and Mac OSX platforms. The GemFire XD ODBC driver also provides command-line tools to simplify driver installation and configuration.

Note: This release of GemFire XD does not provide an ODBC driver for Windows Platforms.

The ODBC driver binaries are distributed for Linux-based platforms in a .zip or .tar.gz file. Binaries are available for 32-bit and 64-bit architectures and differ depending on the supported driver manager (either iODBC or unixODBC) that you are using. See ODBC Driver Supported Configurations for a list of supported platform architectures and driver managers.

If you are using an ODBC driver manager, you can configure the ODBC driver by manually modifying your odbcinst.ini and odbc.ini files or by using the odbc-installer or iodbc-installer tool.

You can also use a ODBC driver manager to map deprecated 2.0 to 3.5 ODBC function calls. See "Mapping Replacement Functions for Backward Compatibility of Applications" for more information.

If you are not using an ODBC driver manager, you can use the GemFire XD ODBC driver by directly linking to the driver library in your client application.

Installing and Configuring the ODBC Driver by Modifying .ini Files

To install the ODBC driver, you can manually create ODBC .ini files or add to the existing .ini file for the ODBC driver manager you are using. Use the following procedure:

Download and unzip the ODBC driver manager .tar.gz file from the Pivotal GemFire XD product page. For example:
```
tar -zxvf Pivotal_GemFireXD_XX_bNNNNN_ODBC.tar.gz -C path_to_install_location
```
where path_to_install_location is an already existing directory.
Download and install the ODBC driver manager you wish to use. See ODBC Driver Supported Configurations for a list of supported platform architectures and driver managers.
Create or modify your odbcinst.ini file to point to the path of the ODBC driver shared library. Use the following values depending on your driver configuration:
- unixODBC driver manager:
  - 32-bit: path_to_install_location/odbc/32/libgemfirexdodbc.so
  - 64-bit: path_to_install_location/odbc/64/libgemfirexdodbc.so
- iODBC driver manager:
  - 32-bit: path_to_install_location/odbc/32/libgemfirexdiodbc.so
  - 64-bit: path_to_install_location/odbc/64/libgemfirexdiodbc.so
The following is a sample odbcinst.ini file for the unixODBC driver manager:
```
[ODBC]
Trace = yes
TraceFile = dmtrace.log

[ODBC Drivers]
SQLFODBC = Installed

[SQLFODBC]
Driver = /usr/lib/gphd/gfxd/odbc/64/libgemfirexdodbc.so
Description = Driver for connecting to GemFire XD database server 
```

Create or modify your odbc.ini file to identify the GemFire XD data source name (DSN).

The following is a sample odbc.ini file for the unixODBC driver manager:

[ODBC Data Sources]
data_source_name = testdsn

[testdsn]
Driver = /usr/lib/gphd/gfxd/odbc/64/libgemfirexdodbc.so
DESCRIPTION = GemFire XD ODBC driver 
SERVER = localhost
PORT = 1527
UID = 
PASSWORD =
LogFile = gfxdodbc.log

Finally set the ODBCINI and ODBCSYSINI environment variables to the file location where odbc.ini and odbcinst.ini files for your driver manager are located. If you are using the iODBC driver manager, also set the ODBCINSTINI environment variable to the location of your odbcinst.ini file. For example:
```
export ODBCINI=/home/user/odbc.ini
export ODBCINSTINI=/home/user/odbcinst.ini
export ODBCSYSINI=/home/user/odbcinst.ini
```
If installing on Mac OSX, set the DYLD_LIBRARY_PATH environment variable to the location where you installed the driver files.
```
export DYLD_LIBRARY_PATH=path_to_install_location  
```

Installing and Configuring the ODBC Driver with the odbc-installer Tool

As an alternative to manually editing your system .ini files, you can use the command-line odbc-installer and iodbc-installer application that is provided with the GemFire XD ODBC driver to install and configure the driver.

The GemFire XD ODBC driver includes two different tools based on the driver manager that you are using. Use the odbc-installer tool if you are using the unixODBC driver manager. Use iodbc-installer if you are using the iODBC driver manager. The odbc-installer and iodbc-installer tools allow you to install and uninstall the driver, configure the DSN, and query driver and data source information.

Note: For additional usage information, see the README.txt file located in the top-level directory of the ODBC driver distribution or type 'odbc-installer' or 'iodbc-installer' on the command-line with no arguments.

For unixODBC users

Install the ODBC driver by performing the following steps:

Download and unzip the ODBC driver manager .tar.gz file from the Pivotal GemFire XD product page. For example:
```
tar -zxvf Pivotal_GemFireXD_XX_bNNNNN_ODBC.tar.gz -C path_to_install_location
```
where path_to_install_location is an already existing directory.
For Linux or Mac OSX platforms, install the unixODBC driver manager if you have not already done so.
For Linux or Mac OSX platforms, set LD_LIBRARY_PATH environment variable to the libodbcinst.so.2 shared library. For example:
```
export LD_LIBRARY_PATH=/unixODBC/lib:$LD_LIBRARY_PATH
```
For the unixODBC driver manager, odbc-installer should pick up libodbcinst.so.2. You can see the list of the shared libraries used by the odbc-installer by using ldd. For example:
```
ldd odbc-installer
```
Set ODBCINI and ODBCSYSINI to accessible paths where the .ini files will be written. For example:
```
export ODBCINI=/home/user/odbc.ini
export ODBCSYSINI=/home/user/odbcinst.ini
```
If installing on Mac OSX, set the DYLD_LIBRARY_PATH environment variable to the location where you installed the driver files.
```
export DYLD_LIBRARY_PATH=path_to_install_location  
```

Run the odbc-installer tool to install the driver and configure the DSN. For example:

odbc-installer -d -a -n"GemFire XD ODBC 1.0 Driver" -t"GemFire XD ODBC 1.0 Driver;Driver=libgemfirexdodbc.so;Setup=libgemfirexdodbc.so;APILevel=2;UID=;PWD="

For iODBC users

Install the ODBC driver by performing the following steps:

Download and unzip the ODBC driver manager .tar.gz file from the Pivotal GemFire XD product page. For example:
```
tar -zxvf Pivotal_GemFireXD_XX_bNNNNN_ODBC.tar.gz -C path_to_install_location
```
where path_to_install_location is an already existing directory.
Install the iODBC driver manager if you have not already done so.
Set LD_LIBRARY_PATH environment variable to the libiodbcinst.so.2 shared library. For example:
```
export LD_LIBRARY_PATH=/iODBC/lib:$LD_LIBRARY_PATH
```
For the iODBC driver manager, iodbc-installer should pick up libiodbcinst.so.2. You can see the list of the shared libraries used by the iodbc-installer by using ldd. For example:
```
ldd iodbc-installer
```

Set ODBCINI, ODBCINSTINI and ODBCSYSINI to accessible paths where the .ini files will be written. For example:

export ODBCINI=/home/user/odbc.ini
export ODBCINSTINI=/home/user/odbcinst.ini
export ODBCSYSINI=/home/user/odbcinst.ini

If installing on Mac OSX, set the DYLD_LIBRARY_PATH environment variable to the location where you installed the driver files.
```
export DYLD_LIBRARY_PATH=path_to_install_location  
```

Run the iodbc-installer tool to install the driver and configure the DSN. For example:

iodbc-installer -d -a -n"GemFire XD ODBC 1.0 Driver" -t"GemFire XD ODBC 1.0 Driver;Driver=libgemfirexdiodbc.so;Setup=libgemfirexdiodbc.so;APILevel=2;UID=;PWD="