Connecting to TDV on Unix Using ODBC Data Direct Driver Manager

Connecting to TDV on Unix using Professional ODBC Data Direct Driver Manager Services Project Name

Release 2.0

Date March 2018

Primary Jean-Philippe Player Author

Document Deane Harding Owner

Client

Document Location

Purpose Provides guidance on how to connect to TDV through ODBC on Unix, using the Data Direct ODBC Driver Manager.

TIBCO Software empowers executives, developers, and business users with Fast Data solutions that make the right data available in real time for faster answers, better decisions, and smarter action. Over the past 15 years, thousands of businesses across the globe have relied on TIBCO technology to integrate their applications and ecosystems, analyze their data, and create real- time solutions. Learn how TIBCO turns data—big or small—into differentiation at www.tibco.com.

www.tibco.com Global Headquarters Tel: +1 650-846-1000 3303 Hillview +1 800-420-8450 Avenue Fax: +1 650-846-10051 Palo Alto, CA 94304 Connecting to TDV on Unix using ODBC Data Direct Driver Manager

Revision History Version Date Author Comments 1.0 August 2012 Jean-Philippe Initial revision Player 2.0 March 2018 Deane Harding Updated with TIBCO branding and relevance to TDV 7.0.x

Approvals This document requires the following approvals. Signed approval forms are filed in the project files.

Name Signature Title Company Date of Issue Version

Distribution This document has been distributed to:

Name Title Company Date of Issue Version

Related Documents This document is related to:

Document File Name Author TDV Client Interfaces TIB_tdv_7.0.6_ClientInterfacesGuide.pdf TIBCO DV Engineering Guide Establishing http://support.sas.com/documentation/cdl/ SAS Connectivity to a TDV en/bidsag/61236/HTML/default/viewer.ht Server m#a003279102.htm

Copyright Notice COPYRIGHT© TIBCO Software Inc. This document is unpublished and the foregoing notice is affixed to protect TIBCO Software Inc. in the event of inadvertent publication. All rights reserved. No part of this document may be reproduced in any form, including photocopying or transmission electronically to any computer, without prior written consent of TIBCO Software Inc. The information contained in this document is confidential and proprietary to TIBCO Software Inc. and may not be used or disclosed except as expressly authorized in writing by TIBCO Software Inc. Copyright protection includes material generated from our software programs displayed on the screen, such as icons, screen displays, and the like.

Trademarks All brand and product names are trademarks or registered trademarks of their respective holders and are hereby acknowledged. Technologies described herein are either covered by existing patents or patent applications are in progress.

Confidentiality The information in this document is subject to change without notice. This document contains information that is confidential and proprietary to TIBCO Software Inc. and its affiliates and may not be copied, published, or disclosed to others, or used for any purposes other than review, without written authorization of an officer of TIBCO Software Inc. Submission of this document does not represent a commitment to implement any portion of this specification in the products of the submitters.

Content Warranty The information in this document is subject to change without notice. THIS DOCUMENT IS PROVIDED "AS IS" AND TIBCO MAKES NO WARRANTY, EXPRESS, IMPLIED, OR STATUTORY, INCLUDING BUT NOT LIMITED TO ALL WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. TIBCO Software Inc. shall not be liable for errors contained herein or for incidental or consequential damages in connection with the furnishing, performance or use of this material.

Export This document and related technical data, are subject to U.S. export control laws, including without limitation the U.S. Export Administration Act and its associated regulations, and may be subject to export or import regulations of other countries. You agree not to export or re-export this document in any form in violation of the applicable export or import laws of the United States or any foreign jurisdiction.

For more information, please contact:

TIBCO Software Inc. 3303 Hillview Avenue Palo Alto, CA 94304 USA

Table of Contents 1 Introduction ...... 7 1.1 Purpose ...... 7 1.2 Audience ...... 7 2 Preparation...... 8 2.1 Choosing the Correct Driver ...... 8 2.2 Platforms ...... 8 2.3 Examples...... 9 2.4 Download ...... 9 3 ODBC Driver Components ...... 10 3.1 Where is the DSN Configuration Stored? ...... 10 3.2 Environment Variables ...... 10 3.2.1 COMPOSITE_HOME ...... 10 3.2.2 ODBCINI ...... 10 3.2.3 ODBCINSTINI ...... 10 3.2.4 Shared Libraries Variable ...... 10 3.3 Files...... 11 4 Installation ...... 12 4.1 Unpack the Archive ...... 12 4.1.1 Linux, Solaris, AIX (pre-TDV 7.0.6) ...... 12 4.1.2 HP-UX (pre-TDV 7.0.6) ...... 12 4.1.3 Unzip Package Containing All Drivers (TDV 7.0.6 onwards) ...... 12 4.2 Configure the Environment for driverConfig (optional but recommended) ...... 12 4.3 Configure the Environment for the Data Direct ODBC Driver Manager ...... 13 4.3.1 odbc.sh ...... 13 5 Create a DSN for Data Direct...... 14 5.1 Using the driverConfig Utility ...... 14 5.2 Manual DSN Creation ...... 14 6 Modifying a DSN ...... 16 6.1 Manually ...... 16 6.1.1 Renaming a DSN ...... 16 6.2 Using driverConfig ...... 16 7 Internals and Debugging ...... 17 7.1 How the ODBC System Works ...... 17 7.2 What can go Wrong ...... 17 7.3 Debugging Tools ...... 17 7.3.1 driverConfig ...... 17

7.3.2 ddtestlib (64 bit) or ivtestlib (32 bit) ...... 18 7.3.3 sample/example/example ...... 18

1 Introduction

1.1 Purpose Several vendors provide ODBC Driver Managers on Unix systems. The purpose of this document is to provide guidance on how to connect to TIBCO Data Virtualization (TDV) through ODBC on Unix, using the Data Direct ODBC Driver Manager. This driver manager is used by many enterprise software including

• IBM Cognos

• SAP Business Objects

• Microstrategy

• IBM SPSS

• SAS

• Informatica PowerCenter

Additional information can be found in the TDV Client Interfaces Guide, which is part of the official documentation.

This document provides:

1. Installation – How to choose and install the appropriate TDV ODBC driver

2. Set up a DSN – How to create a DSN to access your TIBCO Data Virtualization Server

3. Modify a DSN – How to modify an existing DSN

4. Security and Authentication – Authentication mechanisms available and other security considerations

5. Internals – How the driver works under the covers and how to debug connectivity issues

1.2 Audience This document is intended to provide guidance to the following users:

• TIBCO Professional Services

• Operations personnel

• Administrators

2 Preparation

2.1 Choosing the Correct Driver It is important to select the driver that matches the operating system and platform that the client application is running on. More specifically, you must select the driver that will work with Driver Manager that the application ships with. It is possible that the Driver Manager is 32 bit while the application is 64 bit. In that case, choose the 32 bit ODBC driver.

The system on which the TIBCO Data Virtualization Server (TDV) is running is not relevant in the choice of ODBC driver. However, try to select the driver version that matches TDV, such as a 7.0 ODBC driver for TDV 7.0.

Figure 1: SAS Server example

2.2 Platforms • Linux on Intel x86 – 32 bit and 64 bit

• Solaris on SPARC – 32 bit and 64 bit

• Solaris on Intel x86 – Not supported

• IBM AIX – 32 bit and 64 bit

• HP-UX on Itanium – 32 bit and 64 bit

• HP-UX on PA RISC – 32 bit only

2.3 Examples • Cognos 9.2 running on Solaris 64 bit

Select the 32 bit ODBC driver for Solaris. You need to choose the 32 bit driver because although the Operating System and Cognos 9.2 are both 64 bit systems, the Data Direct Driver Manager that ships with Cognos is 32 bit only.

• Microstrategy 9.2 running on Linux 64 bit

Select the 32 bit ODBC driver for Solaris. You need to choose the 32 bit driver because although the Operating System and Microstrategy 9.2 are both 64 bit systems, the Data Direct Driver Manager that ships with Microstrategy is 32 bit only.

• SAS Server running on Itanium 64 bit

Select the ODBC driver for Itanium 64 bit.

2.4 Download You can download the drivers from the TIBCO eDelivery site, simply search for TIBCO Data Virtualization: http://edelivery.tibco.com/storefront

The full TDV installers also come with ODBC drivers appropriate for the platform.

3 ODBC Driver Components

3.1 Where is the DSN Configuration Stored? The TDVODBC Driver follows the usual convention of storing connection information in an odbc.ini file.

3.2 Environment Variables

3.2.1 COMPOSITE_HOME The TDV ODBC Driver relies on the COMPOSITE_HOME variable to locate the driverConfig executable. This is should be set to the path of the TDV installation root folder (which is usually referred to as ), e.g. /opt/TIBCO/TDV_Server_7.0 . If this configuration is not set you can run driverConfig with an absolute or relative path, e.g.

./opt/TIBCO/TDV_Server_7.0/apps/odbc/linux64/bin/driverConfig ./odbc/linux64/bin/driverConfig ./bin/driverConfig

The driver will not load if it cannot find this file.

3.2.2 ODBCINI This variable should be set to the full path to the configuration file odbc.ini. If this file doesn’t exist it is generated during creation of DSN configuration with driverConfig. An example of this variable’s value would be /odbc.ini , e.g:

/opt/TIBCO/TDV_Server_7.0/odbc.ini

3.2.3 ODBCINSTINI This variable should be set to the full path to the configuration file odbcinst.ini. If this file doesn’t exist it is generated during creation of DSN configuration with driverConfig. An example of this variable’s value would be /odbcinst.ini , e.g:

/opt/TIBCO/TDV_Server_7.0/odbcinst.ini

3.2.4 Shared Libraries Variable At runtime, the Data Direct ODBC Driver Manager must be able to locate the TDV ODBC Driver libraries. The shared library environment variable must point to /apps/odbc//lib/ . The driver will fail to load if they cannot be found.

• Linux : LD_LIBRARY_PATH

• Solaris : LD_LIBRARY_PATH

• HP-UX : SHLIB_PATH

• AIX : LIBPATH

3.3 Files • $ODBCINI – odbc.ini file containing details of which driver is being used to access the particular named TDV ODBC DSN as well as the connection configuration details.

• $ODBCINSTINI – odbcinst.ini file containing details of where to find the various library files that the TDV ODBC Driver requires.

• /apps/odbc//lib – Shared libraries for the 32 bit driver

• /apps/odbc/64/lib – Share libraries for the 64 bit driver

• /apps/odbc//bin/driverConfig – Utility to manage the contents of the odbc.ini and odbcinst.ini files and test DSNs.

4 Installation

At a high-level, the three steps that need to be carried out are as follows:

1. Unpack the archive

2. Configure the environment for driverConfig (optional)

3. Configure the Data Direct ODBC Driver Manager

The following sections describe each of these steps in more detail.

4.1 Unpack the Archive These instructions assume that the TDV ODBC Driver archive file for the relevant platform has been placed into e.g. /opt/TIBCO/TDV_Server_7.0

Prior to the release of TIBCO Data Virtualization 7.0.6, TIBCO shipped separate tar.gz files for each different platform type that TDV supports, therefore the following sections 4.1.1 and 4.1.2 provide examples of unpacking the older versions of the TDV ODBC Driver.

Since the release of TDV 7.0.6, TIBCO ships the TDV ODBC Driver for all supported platforms in the same zip file, therefore you have the option of unpacking the entire zip file into your folder (see section 4.1.3) and then deleting the unwanted versions afterwards, or creating your own .zip or .tar.gz files specifically containing the TDV ODBC Driver for your operating system.

4.1.1 Linux, Solaris, AIX (pre-TDV 7.0.6) cd /opt/TIBCO/TDV_Server_7.0 tar xfz odbc_solaris64.tar.gz

4.1.2 HP-UX (pre-TDV 7.0.6) cd /opt/TIBCO/TDV_Server_7.0 zcat odbc_hpuxia64.Z | tar xf -

4.1.3 Unzip Package Containing All Drivers (TDV 7.0.6 onwards) cd /opt/TIBCO/TDV_Server_7.0 unzip TIB_tdv_drivers_7.0.6_all.zip –d .

4.2 Configure the Environment for driverConfig (optional but recommended) Create this script to setup the environment for driverConfig, call it odbcenv.sh. Place it under apps/odbc64 .

#!/bin/sh

#Assuming this script is run from apps/odbc/linux64/lib export COMPOSITE_HOME="$(dirname $(dirname `pwd`))" #Alternatively state the explicit path

#export COMPOSITE_HOME=/opt/TIBCO/TDV_Server_7.0

#Shared libraries export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$COMPOSITE_HOME/apps/odbc/linux64/lib

#for driverConfig – location of generated odbc.ini export ODBCINI=$COMPOSITE_HOME/odbc.ini

#for driverConfig – location of generated odbcinst.ini export ODBCINSTINI=$COMPOSITE_HOME/odbcinst.ini

Run it using: chmod +x odbcenv.sh . ./odbcenv

(the front dot is required to alter the current shell variables)

Now run driverConfig

./driverconfig

Use driverConfig to validate the environment, create and validate a DSN.

Note : the odbcenv.sh script created above could be converted into a wrapper script that launches driverConfig directly.

4.3 Configure the Environment for the Data Direct ODBC Driver Manager The Data Direct ODBC Driver loads the TDV ODBC driver at runtime.

Important: The TDV driver must be able to locate its libraries and the odbc.ini and odbcinst.ini files. For that purpose, edit the script that sets the environment for the Data Direct Driver Manager, such as /odbc.sh.

4.3.1 odbc.sh Locate the odbc.sh startup script (varies based on vendor), and modify it to configure the needed environment variables: COMPOSITE_HOME and LD_LIRBARY_PATH (AIX: LIBPATH, HP-UX: SHLIB_PATH)

Example: odbc.sh used by Data Direct for Microstrategy on Linux

Microstrategy places the file under env/odbc.sh.

# # ODBC Driver for TDV # COMPOSITE_PATH=’’ if [ “${COMPOSITE_PATH}” != ‘’ ]; then COMPOSITE_PATH=’/opt/TIBCO/TDV_Server_7.0/apps/odbc/linux64/lib’ COMPOSITE_HOME=’/opt/TIBCO/TDV_Server_7.0’ mstr_append_path LD_LIBRARY_PATH “${COMPOSITE_PATH:?}” export COMPOSITE_HOME export COMPOSITE_PATH export LD_LIBRARY_PATH fi

5 Create a DSN for Data Direct

A DSN can be created either manually or through the driverConfig utility.

5.1 Using the driverConfig Utility You can use driverConfig utility to generate the odbc.ini file. Once odbc.ini is created, copy-paste the relevant DSN sections into the odbc.ini used by Data Direct.

Notes

• We recommend copying the line relating to your DSN under the [ODBC Data Sources] section of the odbc.ini file, as well as the entire section containing the configuration settings for your chosen DSN name.

• The TDV odbc.ini file generated by driverConfig in this case is a sample only since Data Direct uses its own odbc.ini file. Relevant information should be manually copy-pasted into the odbc.ini used by Data Direct

• See Internals section for more information.

5.2 Manual DSN Creation A DSN can be created manually, without the assistance of driverConfig. Understanding the manual process will make it easier to make changes later.

Let’s assume we want to create a DSN for the following configuration:

• DSN name TDVDEV • Host = hawaii • Port = 9401 • Domain = composite • DataSource = enterprise

1. Edit /odbc.ini

a. Create a new line in the file, at the bottom of the initial [ODBC Data Sources] section:

TDVDEV = composite70_x64

b. Create a new section at the end of the entire file:

[TDVDEV] Driver = /opt/TIBCO/TDV_Server_7.0/apps/odbc/linux64/lib/libcomposite70_x64.so host = hawaii port = 9401 uid = admin password =

domain = composite datasource = enterprise 2. Edit /odbcinst.ini.

a. Create a new line in the [ODBC Drivers] section of the file, ensure there is an entry indicating the data source has been installed, for example

Composite70_x64 = Installed

b. Create a new section at the end of the entire file, the name of this section should reflect the name of the data source associated with the DSN, as entered into the [ODBC Data Sources] section of the odbc.ini file (e.g. composite70_x64 ). Specify the Driver and Setup parameters and leave the rest of the values empty:

[composite70_x64] Driver = /opt/TIBCO/TDV_Server_7.0/apps/odbc/linux64/lib/libcomposite70_x64.so Setup = /opt/TIBCO/TDV_Server_7.0/apps/odbc/linux64/lib/libcomposite70_x64.so host = port = uid = password = datasource = catalog = domain =

6 Modifying a DSN

6.1 Manually To make changes to your DSN manually, simply make the appropriate changes to your named DSN section in the odbc.ini file.

6.1.1 Renaming a DSN To rename a DSN, rename the entry for your DSN in the [ODBC Data Sources] section of the odbc.ini file as well as renaming the section with your DSN name towards the end of in odbc.ini.

Using the example shown in section 5.2 above as a guide, in odbc.ini change this entry under the [ODBC Data Sources] section:

TDVDEV = composite70_x64

To this:

RENAMED_TDVDEV = composite70_x64

And change this section in the file:

[TDVDEV ] Driver = /opt/TIBCO/TDV_Server_7.0/apps/odbc/linux64/lib/libcomposite70_x64.so host = hawaii port = 9401 uid = admin password = domain = composite datasource = enterprise to this:

[RENAMED_TDVDEV ] Driver = /opt/TIBCO/TDV_Server_7.0/apps/odbc/linux64/lib/libcomposite70_x64.so host = hawaii port = 9401 uid = admin password = domain = composite datasource = enterprise

6.2 Using driverConfig You can of course use driverConfig to change your DSN setup.

. ./odbcenv ./driverConfig

Be aware you will again need to copy the relevant pieces into the Data Direct odbc.ini file as discussed in section 5.1 of this document.

7 Internals and Debugging

7.1 How the ODBC System Works What happens when a client requests a connection to a DSN:

1. Driver Manager parses its odbc.ini looking for the requested DSN

2. Driver Manager parses its odbc.ini looking for a driver file associated with the DSN

3. Driver Manager invokes ODBC driver listed in #2

4. ODBC driver is dynamically linked to its libraries. The Driver Manager finds them through the Shared Library environment variable

5. ODBC driver parses odbc.ini for the connection information for the named DSN.

6. Connection is established

7.2 What can go Wrong • shared libraries can’t be located (or the path to the TDV ODBC driver in odbc.ini is invalid) o SQLSTATE = IM003 o NATIVE ERROR = 0 o MSG = [DataDirect][ODBC lib] Specified driver could not be loaded • wrong library platform (eg 64 bit driver instead of 32 bit driver) • DSN not found in Data Direct’s odbc.ini o SQLSTATE = IM002 o NATIVE ERROR = 0 o MSG = [DataDirect][ODBC lib] Data source name not found and no default driver specified

Use the /samples/example/example application provided by Data Direct to debug connectivity issues.

7.3 Debugging Tools

7.3.1 driverConfig The driverConfig utility is provided by TIBCO, and is located in the apps/odbc//bin or apps/odbc/64/bin folder. Using this utility is optional, however using it will ensure that the format of the odbc.ini file is correct. driverConfig is a good place to start testing the configuration. Do note however that the Data Direct ODBC Driver Manager is independent, and has its own set of environment variables. You may have configured the environment correctly for driverConfig, but not for Data Direct. driverConfig expects the following variables:

• COMPOSITE_HOME – Set to the TDV installation folder

• LD_LIBRARY_PATH (to find /apps/odbc//lib/*)

• ODBCINI (where the generated odbc.ini file will be located)

• ODBCINSTINI (where the generated odbcinst.ini file will be located)

7.3.2 ddtestlib (64 bit) or ivtestlib (32 bit) The ddtestlib utility is provided by Data Direct. It is located under /bin. Use this utility to verify that the TDV ODBC driver can be loaded. This step can be used to detect platform mismatches (32 bit vs 64 bit).

Syntax: ddtestlib

Example: ddtestlib /opt/TIBCO/TDV_Server_7.0/apps/odbc/linux64/lib/libcomposite70_x64.so

7.3.2.1 Possible Errors When using ddtestlib, you might find that the shared libraries cannot be found: qa@qa-regress bin]$ ./ddtestlib /opt/TIBCO/TDV_Server_7.0/apps/odbc/linux64/lib/libcomposite70_x64.so

/usr/lib/linux64/dld.so: Unable to find library 'libiconv.so.6'.

Load of /opt/TIBCO/TDV_Server_7.0/apps/odbc/linux64/lib/libcomposite70_x64.so failed, errno(2)=No such file or directory

The solution is to set LD_LIBRARY_PATH or equivalent in env/odbc.sh (for this session only). In odbc.sh: export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/TIBCO/TDV_Server_7.0/apps/odbc/linux64/lib/ . ./odbc.sh

7.3.3 sample/example/example The example utility provided by Data Direct is a good final test. Run the command with no arguments. A prompt denotes success.