Netezza Odbc JDBC Guide
Netezza Odbc JDBC Guide
IBM Netezza ODBC, JDBC, and OLE DB Installation and Configuration Guide
Revised: June 16, 2011
20751-12 Rev. 6
Note: Before using this information and the product that it supports, read the information in Notices and Trademarks on page C-1.
Copyright IBM Corporation 2011. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Table of Contents
Preface 1 Introduction
Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-1 Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 ODBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 JDBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-3 Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4 ODBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4 JDBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4 OLE DB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5 Installation Files Access. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-5
iii
ODBC Driver Manager Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3 Windows Driver Managers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3 Linux/UNIX Driver Managers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3 unixODBC Driver Manager Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-4 DataDirect Driver Manager Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-6
iv
ODBC Driver Search Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-1 ODBC Driver Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2 unixODBC Driver Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2 unixODBC Driver Manager Search Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2 Compatibility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2 DataDirect Driver Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3 DataDirect Driver Manager Search Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3 Incompatibilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3 Investigating Client System Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-4
Appendix B: Troubleshooting
ODBC Debug Logging and Driver Manager Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . B-1 ODBC Debug Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-1 ODBC Driver Manager Tracing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-2 JDBC Debug Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-2 loglevel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-3 loggertype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-3 logdirpath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-3 Connection String Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-3 OLE DB Debug Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-4
Index
vi
List of Tables
Table 2-1: Table 2-2: Table 2-3: Table 2-4: Table 2-5: Table 3-1: Table 3-2: Table 4-1: Table B-1: Netezza Supported Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1 OLE DB Windows Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2 Implementation, Netezza Driver/Provider, and Software Compatibility . 2-2 Netezza ODBC Driver Version Support . . . . . . . . . . . . . . . . . . . . . . . 2-3 Data Source Support Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4 Minimum Space Requirements for Clients . . . . . . . . . . . . . . . . . . . . 3-1 Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2 ODBC Driver Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2 Log Levels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . B-3
vii
viii
List of Figures
Figure 1-1: Figure 1-2: ODBC Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 JDBC Configuration.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4
ix
Preface
This document describes the IBM Netezza appliance implementations of International standards for a Structured Query Language Call Level Interface (SQL CLI). This IBM Netezza ODBC, JDBC and OLE DB Installation and Configuration Guide brings together all the information you need to install and configure the ODBC drivers, JDBC drivers, OLE DB, and IBM Netezza appliance data sources.
Topic Overview
The following provides a brief overview of the contents of each chapter in this guide.
Chapter 1. Introduction. Describes the changes to this manual version, provides background on ODBC, JDBC, and OLE DB, describes the architecture of ODBC and JDBC, and lists the process steps for installing ODBC, JDBC, and OLE DB. Chapter 2. Supported Platforms and Release Compatibility. Lists the platforms that the IBM Netezza appliance supports and which software releases are compatible. Chapter 3. Installing and Uninstalling Client Tools. Details the steps and procedures for installing and uninstalling the IBM Netezza appliance client tools. Chapter 4. ODBC Drivers and Driver Managers. Discusses the functions of IBM Netezza ODBC and JDBC drivers and ODBC driver managers. Chapter 5. Installing and Configuring ODBC. Describes procedures for installing and configuring ODBC and configuring IBM Netezza appliance data sources. Chapter 6. Installing and Configuring JDBC. Describes procedures for installing and configuring JDBC and configuring IBM Netezza appliance data sources. Chapter 7. Installing and Configuring OLE DB. Describes procedures for installing and configuring OLE DB and configuring IBM Netezza appliance data sources.
xi
Appendix A. ODBC Configuration Files. Describes advanced considerations concerning the names and locations of the ODBC configuration files. Appendix B. Troubleshooting. Describes the methods for enabling debug logging and tracing, ways of tracking activity to aid in troubleshooting. Appendix C. Notices and Trademarks. Describes the legal product and trademark information.
Italics for emphasis on terms and user-defined values such as user input Upper case for SQL commands; for example INSERT, DELETE Bold for command line input; for example, nzsystem stop
North American Toll-Free: +1.877.810.4441 United Kingdom Free-Phone: +0.800.032.8382 International Direct: +1.508.620.2281
Refer to your Netezza maintenance agreement for details about your support plan choices and coverage.
The name and version of the manual that you are using Any comments that you have about the manual Your name, address, and phone number
xii
Learning More
Find detailed specifications for the Microsoft ODBC implementation of the SQL CLI standards at the following:
http://msdn.microsoft.com/en-us/library
Find more information on the Oracle Sun Developer Network JDBC implementation of the SQL CLI at the following:
http://java.sun.com/reference/api/index.html
xiii
xiv
CHAPTER 1
Introduction
Whats in this chapter
Background Architecture Process Installation Files Access
This chapter provides general information about ODBC, JDBC, and OLE DB.
Background
The International standard for SQL defines a standard high-level language for accessing and manipulating the data stored in a relational database. The International standard for the SQL CLI defines an application programming interface (API) that programs use to issue SQL statements in a standardized manner through a series of well-defined API functions. The term Open Database Connectivity (ODBC) is a more commonly used term than SQL CLI, and in many contexts, the two terms are used synonymously. ODBC is actually a Microsoft specification for an API that constitutes an implementation of the International standards for the SQL CLI. ODBC is a superset of the SQL API, since it defines many functions that the International standards for the SQL API do not define. However, the SQL CLI and the Microsoft ODBC specification are closely aligned, and the two terms are used interchangeably especially in the C and C++ programming environments. Unless otherwise noted, the terms SQL CLI and ODBC mean the same thing in this document. Sun Microsystems developed a specification, called JDBC, that defines an API for the Java programming environment that Java programmers use to access relational databases and issue SQL statements. The JDBC specification defines many of the same types of functions for Java programmers that ODBC and the SQL CLI define for C and C++ programmers. It is possible for Java programs to directly invoke the API functions defined by ODBC and the SQL API. However, the nature of the Java programming environment makes this cumbersome. JDBC often provides a better solution than ODBC for the object-oriented Java programming environment. Like ODBC, JDBC is an implementation of the International standards for the SQL CLI. The JDBC implementation consists of a set of Java interfaces, classes, and methods that a Java programmer can use to do the same types of functions a C or C++ programmer uses when invoking ODBC function calls. Also like ODBC, JDBC constitutes a superset of the SQL CLI, since it defines many functions that the International standards for the SQL CLI do not define.
1-1
IBM Netezza ODBC, JDBC and OLE DB Installation and Configuration Guide
OLE DB was designed as a higher-level replacement for, and successor to, ODBC, to support a wider variety of non-relational databases that do not necessarily implement SQL (for example, object databases and spreadsheets). OLE has a client-provider model, where clients request access to data, and providers are the software component interface allowing access to the data.
Architecture
This section describes the architectural components of the various implementations.
ODBC
The ODBC implementation is a client-server architecture, with the following major components:
Application. The application is responsible for interacting with the user and for invoking ODBC API functions that submit SQL statements for processing by a file system or a database management system. Driver Manager. The Driver Manager accepts ODBC API functions from the application and passes them to an ODBC driver for processing. It also accepts results from the ODBC driver and passes them to the Application. ODBC Driver. The ODBC Driver processes the ODBC API functions it receives from the Driver Manager, interacts with the file system or database management system to access the required data, and returns results to the ODBC Driver Manager. Data Source. A Data Source contains the sets of data the ODBC Driver accesses, along with all the environments associated with the data. These environments might include file access or database access software, an operating system, and a networking platform.
To use ODBC to access a Netezza appliance, you need at least a two-tier client-server configuration, as shown in the example in Figure 1-1.
1-2
20751-12
Rev.6
Architecture
In a Netezza appliance two-tier client-server system, the data source is stored on the Netezza appliance, which handles all database access processing. The ODBC driver on the client system uses a network connection to a Postgres process running on the Netezza appliance host, which coordinates SQL statement processing functions.
JDBC
The JDBC architecture consists of four major components:
Java Application. The application, written in the Java programming language, is responsible for interacting with the user and for invoking JDBC API functions. These API functions submit SQL statements for processing by a file system or a database management system. The Java application uses interfaces, classes, and methods, defined by the Java API, to connect to and access a data source. Java Virtual Machine. When a Java application is compiled, the Java object program consists of byte codes. The Java virtual machine is responsible for converting the Java byte codes into instructions capable of being executed on the machine on which the application is running. The Java virtual machine functions as an intermediary between the Java object program and the machine on which the application is running. There is a different Java virtual machine implementation for each platform. The Java virtual machine makes it possible for the same Java program to be run, without changing or recompiling, on any machine for which a Java virtual machine has been implemented. JDBC Driver. The JDBC driver processes the JDBC API interfaces, classes, and methods in the Java application. The Java application uses the JDBC driver to interact with the file system or database management system to access the required data. It also returns results to the Java Virtual Machine, which, in turn, returns those results to the Java Application. There is a different JDBC driver for each vendors DBMS or data source type. Netezza provides a JDBC driver for Version 3.0 of the Oracle JDBC API specification. The driver is a Type 4, pure-Java driver that Netezza has tested for conformance with the Oracle JDBC specifications on Windows, Linux, and UNIX platforms. The Netezza JDBC driver supports all NZSQL data types, includes password encryption, and provides for connection options for host, port, and database. Starting with Netezza appliance Release 4.6, the JDBC driver requires Java release 1.5 and later. Data Source. A Data Source contains the sets of data the JDBC driver accesses, along with all the environments associated with the data. These environments might include file access or database access software, an operating system, and a networking platform.
To use JDBC to access a Netezza appliance, you need at least a two-tier client-server configuration, as shown in the example in Figure 1-2.
20751-12
Rev.6
1-3
IBM Netezza ODBC, JDBC and OLE DB Installation and Configuration Guide
Figure 1-2: JDBC Configuration. In a Netezza appliance two-tier client-server system, the data source is stored on the Netezza appliance, which handles all database access processing. The JDBC driver on the client system uses a network connection to a Postgres process running on the Netezza appliance host, which coordinates SQL statement processing functions.
Process
This section describes the process steps for ODBC, JDBC, and OLE DB, and where to go for more detail.
ODBC
The process for setting up ODBC on your system is as follows. 1. Install the appropriate Netezza appliance client tools. See the next section Installation Files Access and Chapter 3, Installing and Uninstalling Client Tools. 2. (UNIX only) Download an ODBC driver manager. See Chapter 4, ODBC Drivers and Driver Managers. 3. Select the ODBC driver to install. See Chapter 4, ODBC Drivers and Driver Managers. 4. Configure the data source. See Chapter 5, Installing and Configuring ODBC. 5. Test connectivity. See Chapter 5, Installing and Configuring ODBC.
JDBC
The process for setting up JDBC on your system is as follows. 1. Install the appropriate Netezza appliance client tools. See the next section Installation Files Access and Chapter 3, Installing and Uninstalling Client Tools. 2. Install the JDBC driver. See Chapter 6, Installing and Configuring JDBC. 3. Configure the data source. See Chapter 6, Installing and Configuring JDBC.
1-4
20751-12
Rev.6
OLE DB
The process for setting up OLE DB on your system is as follows. 1. Install the appropriate Netezza appliance client tools. See the next section Installation Files Access and Chapter 3, Installing and Uninstalling Client Tools. 2. Select the OLE DB provider to install. See Chapter 7, Installing and Configuring OLE DB. 3. Configure the data source. See Chapter 7, Installing and Configuring OLE DB.
Netezza FTP support site navigate here using either the command line method or through a Web browser.
Note: You must supply your Netezza FTP user account and password to access the server, where you will begin in your home directory location.
IBM Netezza Client CD Insert the CD in a system drive and use Windows Explorer to open the \admin folder on the CD.
To access the files, navigate to the Releases/version directory, where version is the Netezza software version with the tools that you want to download. For example, to navigate to the Netezza Release 6.0.3 software location, navigate to Releases/6.0.3. As a best practice, check for a patch subdirectory to see if there is a more recent set of client installation executables. Select the release whose client tools you want to install, and the page updates to display links to the files. The software version directory contains files such as the following:
*cli.package.tar Netezza client installation packages for the supported client operating systems. Note that there are different packages for the different clients. datadirect.package.tar.z DataDirect Driver Manager for ODBC support doc.package.tar.z Netezza documentation for the release nzjdbcsetup.exe JDBC driver for Netezza clients nzodbcsetup.exe ODBC driver for Netezza clients nzoledbsetup.exe and nzoledbsetup64.exe OLE DB provider for Netezza clients (32and 64-bit installers, respectively) nzsetup.exe NzAdmin client installation kit (Windows clients) package.tar.z Netezza software installation files
20751-12
Rev.6
1-5
IBM Netezza ODBC, JDBC and OLE DB Installation and Configuration Guide
If you need one of the .tar files, use the tar command to uncompress the package.tar.z file, for example:
tar cli.package.tar.z
You can download client kits such as ODBC, JDBC, OLE DB, or Netezza client CLIs for your Netezza client users to update to the latest software release. The downloads will vary depending upon the clients that you use, but you should ensure that you and your Netezza users upgrade to the latest clients for best performance.
1-6
20751-12
Rev.6
CHAPTER 2
Support and Release Compatibility
Whats in this chapter
Supported Platforms Release Compatibility Matrix ODBC Driver Version Support ODBC Standards Conformance and API Versions JDBC Driver Data Source Support
Supported Platforms
Netezza supplies the following platforms for ODBC and JDBC: Table 2-1: Netezza Supported Platforms Operating System Windows Windows 2000 Windows 2003 Windows 2008 Windows XP Windows Vista Windows 7 Linux Red Hat LAS Linux 4.0, 5.2, 5.3, 5.5 SUSE Linux Enterprise Server 8 and 9 Intel/AMD Intel/AMD Intel/AMD Intel/AMD X X X X X X X X X X X 32-bit 64-bit
2-1
IBM Netezza ODBC, JDBC and OLE DB Installation and Configuration Guide
Table 2-1: Netezza Supported Platforms (continued) Operating System UNIX Oracle Solaris 8, 9, 10 Oracle Solaris 10 HP-UX 11i versions 1.6 and 2 (B.11.22 and B.11.23) IBM AIX 5.1, 5.2, 5.3, 6.1 with 5.0.2.1 C++ runtime libraries SPARC x86 Itanium PA-RISC PowerPC SPARC x86 Itanium PA-RISC PowerPC 32-bit 64-bit
The OLE DB provider is supported on the Windows clients shown in Table 2-2: Table 2-2: OLE DB Windows Support Operating System Windows 2003 Server Windows 2008 Server Windows XP Windows Vista Business Windows 7 32-bit X X X X X 64-bit X X X X X
JDBC
2-2
20751-12
Rev.6
Table 2-3: Implementation, Netezza Driver/Provider, and Software Compatibility Implementation OLE DB Netezza Driver/ Provider 4.5.x 4.6.x 5.0.x 6.0.x Netezza Appliance Software 4.0.x, 4.0.x, 4.5.x, 4.6.x, 4.5.x, 4.5.x, 4.6.x, 5.0.x, 4.6.x, 5.0.x 4.6.x, 5.0.x, 6.0.x 5.0.x, 6.0.x 6.0.x
Note: Different driver/provider and software versions may have different available functions, so for full functionality, you may need to change your driver/provider or software version.
A distinguishing feature of the Microsoft ODBC Release 3.x specifications is that they are closely aligned with the X/Open and ANSI/ISO/IEC International standards for the SQL CLI. When you install an Netezza ODBC driver in a client computer system, you must choose one of the available drivers. You cannot install multiple Netezza ODBC drivers in the same client system.
The X/Open CAE Specification Data Management: SQL Call-Level Interface (CLI) ISO/IEC 9075-3:1995 (E) Call Level Interface (SQL CLI)
The X/Open and ISO/IEC standards for the SQL CLI are published in separate documents, but the two standards are closely aligned.
20751-12
Rev.6
2-3
IBM Netezza ODBC, JDBC and OLE DB Installation and Configuration Guide
javax.sql.ConnectionPoolData Source
org.netezza.jdbc2. optional.ConnectionPool
org.netezza.datasource.NzConnection PoolDatasource
2-4
20751-12
Rev.6
CHAPTER 3
Installing and Uninstalling Client Tools
Whats in this chapter
Windows Client Tools Installation UNIX/Linux Client Tools Installation Uninstalling Client Tools for Windows Uninstalling Client Tools for UNIX/Linux
This chapter provides information about installing the Netezza appliance client tools on your system. These tools help the ODBC drivers, JDBC drivers, and OLE DB Provider that Netezza supplies connect to an Netezza appliance from a client system. The first step in preparing a system for ODBC, JDBC, or OLE DB is to install the Netezza appliance client tools on your system. If these are already installed, skip this chapter. After the client tools have been installed, you can install the ODBC drivers, JDBC drivers, or OLE DB Provider.
Netezza administration application Console program executable files and libraries Console program string files Online help files Documentation files in PDF format
Table 3-1 lists the minimum disk space required to install each client. Table 3-1: Minimum Space Requirements for Clients Installing ODBC Disk Space Needed 100 MB
3-1
IBM Netezza ODBC, JDBC and OLE DB Installation and Configuration Guide
Table 3-1: Minimum Space Requirements for Clients Installing JDBC OLE DB Disk Space Needed 10 MB 100 MB
Table 3-2 describes the environment variables the installation program adds for the Netezza Performance Server console applications. Table 3-2: Environment Variables Variable NZ_DIR PATH Operation set append Setting Netezza Appliance Tools Installation directory (for example C:\Program Files\ Netezza) <installation directory>\bin
Created Subfolders
The installation program creates the following subfolders within the specified installation location. Do not change the names or locations of these installation subfolders.
Bin Executables and support files Doc Netezza product documentation Help Application help files Log Empty directory used for application logging Sys A Strings subfolder containing loader string files Tmp Empty directory used for temporary storage
3-2
20751-12
Rev.6
4. The Choose Install Set window is displayed. Select one of the following install set types from the drop-down box and click Next:
Typical (The default, recommended for most client systems) Installs the nzadmin program, the online help files, the documentation, and the console utilities, including the loader. Minimal Installs the nzadmin program and online help files. Custom Displays a screen that allows you to specify whether you want to install the administration application, the console application, or the documentation.
The installation program installs all the Netezza client software, help files, and documentation. 5. The Pre-Installation Summary window is displayed, summarizing your installation choices. To change any of your choices, page through the previous windows and reconfigure. When this window reflects your installation choices, click Install. After you click Install, the installation program installs the Netezza appliance tools software and places appropriate entries in the Windows registry. Windows displays a series of progress dialog boxes as the installation program does the various steps. The installation program adds an Netezza appliance tools folder in the Programs folder on your Start menu. From the Start menu, you can access the Netezza Server Administrator application (NzAdmin). 6. The Install Complete window is displayed, indicating that the installation process has completed successfully. Click Done to exit the installation procedure. On some systems, the installation program may prompt you to reboot your system. Note: To run the nz CLI commands, launch them from a Windows Command Prompt window.
Created Subdirectories
The client tools installation program for a UNIX/Linux system creates the following subdirectories in the nz directory:
bin Contains the Netezza CLI command software. doc Contains the user documentation. lib Contains ODBC, JDBC, and OLE DB software. license Contains the Netezza end-user software license agreement. sys/strings Contains strings for use by the Netezza CLI commands. tmp An empty directory used to contain the temporary files Netezza software creates.
20751-12
Rev.6
3-3
IBM Netezza ODBC, JDBC and OLE DB Installation and Configuration Guide
4. Run the setup command, which checks the client OS to identify the correct client files and launches the unpack command, or navigate to the correct OS directory and then run the unpack command as follows:
./unpack
5. The installation program allows you to make the following installation choices:
View the readme file (optional). Accept the default installation directory (recommended) or change it. Select to install the ODBC driver, the JDBC driver, or the OLE DB provider. For more information on each option, see the appropriate chapter.
6. If you accepted the default for the installation directory, the installation program creates the /usr/local/nz directory and copies the installation files into subdirectories within the nz directory. If you changed the default installation directory, the installation program creates the nz directory in the directory you specified. Note: If you direct the installation program to create the installation directory in a directory to which you do not have write access, the program fails and issues a message that it was unable to create the nz directory. This failure most often occurs if you log in as an ordinary user for the installation and do not change the installation directory appropriately.
3-4
20751-12
Rev.6
The above commands remove the nz directory and all of its subdirectories and files from the /usr/local directory.
20751-12
Rev.6
3-5
IBM Netezza ODBC, JDBC and OLE DB Installation and Configuration Guide
3-6
20751-12
Rev.6
CHAPTER 4
ODBC Drivers and Driver Managers
Whats in this chapter
ODBC Drivers ODBC Driver Managers
This chapter explains ODBC drivers and driver managers. You can have only one ODBC driver installed on your system at a time. If you need a different driver, remove the installed driver and install the different one. For more information on this procedure, see Chapter 3, Installing and Uninstalling Client Tools. For driver installation and configuration detail, see Chapter 5, Installing and Configuring ODBC.
ODBC Drivers
An ODBC driver uses a layer of code that translates the ODBC standard API calls the application issues into vendor-specific functions. Netezza supplies different versions of the ODBC driver for each supported platform, each vendors DBMS or data source type, each of the major ODBC versions, and for each major release level of the Netezza appliance. ODBC drivers expose the capabilities of the underlying data source, and each ODBC driver is designed for a particular database management system. For example, an ODBC driver designed to access a different vendor database cannot be used to access an Netezza database.
Connecting to and disconnecting from data sources. Performing error checking functions. Submitting SQL statements to the database management system software for execution against a particular data source. Converting ODBC-standard SQL statements, if necessary, to DBMS-specific SQL statements. Sending data to and retrieving data from a data source. Performing data conversion functions, as specified by the application. Returning information about the success or failure of an ODBC function.
4-1
IBM Netezza ODBC, JDBC and OLE DB Installation and Configuration Guide
Socket Buffer Size A numeric value that specifies the size of the communications buffer in bytes. The range is 1K to 32K. The default is 8192. Character Transla- The Netezza appliance uses the Latin9 character encoding for char tion Option and varchar types. The character encoding for many Windows systems is similar, but not identical. If your database includes characters that use only the basic subset of letters (a-z or A-Z), numbers (0-9), or punctuation characters, select the Optimize for ASCII character set option for the driver on Windows, which improves query performance. If your data includes special characters such as the Euro symbol or others, de-select the option so that the characters convert correctly. Unicode Translation Option For UNIX/Linux drivers, specifies the unicode encoding value. Valid values are utf8, utf16, and utf32. The default is utf8.
4-2
20751-12
Rev.6
For performance reasons, depending on the database management system software used, some API functions may bypass the driver manager and access the ODBC driver directly.
Loading into memory the ODBC driver required by the application and the data source it is accessing. Unloading from memory ODBC drivers when they are no longer needed. Passing ODBC API function calls from the application to an appropriate ODBC driver. Performing any required ODBC API function call conversions. For example, if an ODBC application issues ODBC 2.5 function calls and is using an ODBC 3.0 driver, the driver manager converts ODBC 2.5 function calls to their ODBC 3.0 equivalents when necessary. Performing error checking and validation functions on ODBC API function calls before passing them to the ODBC driver. Performing some character set conversions. For example, if the application uses an 8-bit ASCII character set, and the ODBC driver and DBMS work with character data in 16-bit Unicode format, the driver manager does the necessary character conversions.
Note: The driver manager component is used only with ODBC. There is no separate driver manager component in the JDBC architecture. With JDBC, all driver manager functions are performed in the Java application environment.
Open Source There are a number of driver managers available on the Web from open source software projects. Netezza supports the unixODBC driver manager component for Linux/UNIX platforms. You can find information about unixODBC at the following:
http://www.unixodbc.org
Commercial A number of commercial software vendors develop and market ODBC components, including driver managers. Netezza has licensed and provides support for the DataDirect driver manager from DataDirect Technologies. It is included with your system on it's own CD. The DataDirect driver manager component comes with some
20751-12
Rev.6
4-3
IBM Netezza ODBC, JDBC and OLE DB Installation and Configuration Guide
third-party ETL and BI software tools. It is not necessary to install the Netezza-licensed version of the DataDirect driver manager to access the Netezza ODBC drivers. You can find information on the DataDirect line of ODBC products at the following:
http://www.datadirect.com
The following procedure example is based on version 2.2.12, and assumes the name of the downloaded file is unixODBC-2.2.12.tar.gz. The file name might be different if you download a later release. Match the file and directory names in the procedure to correspond to the name of the file you download. Consult the README and INSTALL files contained in the downloaded package to determine whether the procedure needs to be modified.
4-4
20751-12
Rev.6
4. Run the following command to extract the contents of the unixODBC-2.2.12.tar file:
tar -xvf unixODBC-2.2.12.tar
5. Run the following command to change to the subdirectory created when the unixODBC-2.2.12.tar file was extracted:
cd unixODBC-2.2.12
6. Run the following command to configure the software and set the installation directory to /usr/local/unixODBC:
./configure --prefix=/usr/local/unixODBC
7. Run the following command to compile the package (note that this step may take a few minutes to complete):
make
8. Run the following command to install the programs, data files, and documentation:
make install
This step places the bin, etc, lib, and include subdirectories in the /usr/local/unixODBC directory. These subdirectories contain the programs, data files, and documentation for the unixODBC driver manager package. 9. Run the appropriate commands to add bin and lib subdirectories to the environment: For AIX:
export PATH=$PATH:/usr/local/unixodbc/bin export LIBPATH=$LIBPATH:/usr/local/unixodbc/lib
For HP-UX:
export PATH=$PATH:/usr/local/unixodbc/bin export SHLIB_PATH=$SHLIB_PATH:/usr/local/unixodbc/lib
Note: The above commands change the environment for the current session only. After you have verified that your environment modifications work correctly, edit your login script to set the environment variables when users log in. 10. If desired, delete the installation tar file from the file system:
rm unixODBC-2.2.12.tar
If preferred, you could move the installation tar file to somewhere else in the file system for safekeeping.
20751-12
Rev.6
4-5
IBM Netezza ODBC, JDBC and OLE DB Installation and Configuration Guide
Assumptions
The installation procedure for the DataDirect driver manager is the same for all supported Linux and UNIX systems. However, the exact file names for the manager are platform-specific.
The installation directory is /opt. If you choose another directory, modify the following files:
The odbc.ini and odbcinst.ini files are located in /opt/odbc32v51 (32 bit) and /opt/odbc64v51 (64 bit). If you choose another directory, modify the following files:
odbc.sh (if using sh or bash) odbc.csh (if using csh) odbc.ini odbcinst.ini
The Netezza ODBC driver is located in /usr/local/nz/lib. Verify that the driver entry points to the proper file name. If you choose another directory, modify the following files:
odbc.ini odbcinst.ini
4. Change to the extraction directory. For example, to change to the 32-bit extraction directory, enter the following:
cd odbc32v51
4-6
20751-12
Rev.6
6. Edit odbc.ini and specify the servername, database, login, and password. 7. Execute the appropriate environment file:
. ./odbc.sh
or
source odbc.csh
Note: The above commands change the environment for the current session only. After you have verified that your environment modifications work correctly, edit your login script to set the environment variables when users log in. 8. Change directory to example:
cd example
9. Run the example program (example), specifying a DSN (NZSQL is the default), login, and password. You should see the following output:
./example DataDirect Technologies, Inc. ODBC Example Application. Enter the data source name : NZSQL Enter the user name Enter the password : admin : password
20751-12
Rev.6
4-7
IBM Netezza ODBC, JDBC and OLE DB Installation and Configuration Guide
4-8
20751-12
Rev.6
CHAPTER 5
Installing and Configuring ODBC
Whats in this chapter
Installing and Configuring ODBC for Windows Configuring ODBC for UNIX/Linux
This chapter describes the procedures used to install and configure ODBC drivers and data sources for Windows or UNIX/Linux systems. You can have only one ODBC driver installed on your system at any given time. If you need a different driver, you will need to remove the installed driver and install the different one. For more information on removing the driver, see Chapter 3, Installing and Uninstalling Client Tools.
5-1
IBM Netezza ODBC, JDBC and OLE DB Installation and Configuration Guide
Silent install; Visual Studio 8 (VC8) libraries are not installed and Translation Options are set to the default value c:\>nzodbcsetup.exe -i silent Silent install; Visual Studio 8 (VC8) libraries are installed and Translation Options are set to the default value c:\>nzodbcsetup.exe -i silent -DVC8_LIB_INSTALL=1
Silent install; Visual Studio 8 (VC8) libraries are installed and Translation Options are set to Optimize for ASCII c:\>nzodbcsetup.exe -i silent -DVC8_LIB_INSTALL=1 -DTRANSLATION_OPTION_VALUE=1
5-2
20751-12
Rev.6
ters that are outside the basic set, do not select the optimize option. This causes the characters that you enter to be converted to the proper encodings so that they appear correctly in your query results. Click Next after selecting. 6. The ODBC driver requires the Visual Studio 8 (VC8) Libraries on the client system.
If the installation program finds the VC8 libraries, it uses the installed files and proceeds to the Pre-Installation Summary window. If the program cannot find the VC8 files on the system, it displays the Visual Studios 8 Libraries window. Select Install and click Next. If you can verify that the VC8 libraries are present on the system, even though the installer could not locate them, select Do not install and click Next. If the driver does not function properly because the libraries are missing or not found, run the driver installation program again and install the VC8 libraries.
7. The Pre-Installation Summary window is displayed, summarizing your installation choices. To page through the previous selections to review selections, use the Previous button. When finished, click Install. After you click Install, the installation program does the following processing:
Installs the Netezza ODBC Driver. A 32-bit driver on a 32-bit system and a 64-bit driver on a 64-bit system are installed in the \WINDOWS\system32 folder. If installing both 32- and 64-bit drivers on a 64-bit system, the 32-bit driver is installed in the \WINDOWS\SysWOW64 folder. Places entries in the Windows registry to add your selected ODBC driver to the driver list. Places entries in the Windows registry to add the NZSQL data source to the data source list.
8. The Install Complete window is displayed. This indicates that the installation process has completed successfully. Click Done to close the program. Before trying to access an ODBC data source, you must configure it. The next section describes the configuration procedure.
A System DSN defines a data source available to all users of the client system. A User DSN defines a data source available only to the user who defined it.
Get the following configuration information from your Netezza system administrator:
The name of the system or user database on the Netezza appliance. The server host name or IP address of your Netezza appliance. A valid user ID for accessing the system or user data source. A valid password for accessing the system or user data source.
20751-12
Rev.6
5-3
IBM Netezza ODBC, JDBC and OLE DB Installation and Configuration Guide
To configure an existing DSN, select the Configure button. To configure a new DSN, select the Add button.
2. Configure the DSN and Driver Options from the Driver Setup Window. 3. Test and verify the ODBC Connection. 4. Close any open configuration windows to finish the Data Source Configuration. ODBC Data Source Administrator Window The ODBC Data Source Administrator window allows you to make configuration selections. 1. Select Start > Settings > Control Panel > Administrative Tools > Data Sources (ODBC). The ODBC Data Source Administrator window is displayed. 2. Select either the System DSN tab or the User DSN tab and select either Configure or Add:
Selecting Add displays the Create New Data Source Window. Select NetezzaSQL as the driver and click Finish. The ODBC Driver Setup Window is displayed. Selecting the System DSN tab displays a list of System Data Sources. Selecting Configure displays the ODBC Driver Setup Window. The ODBC Driver Setup Window allows you to configure the
Select the DSN Options tab and enter appropriate values for the DSN Options. If your application supplies a user name and password, these can be left blank, since your applications user name and password take precedence over the ones specified here. If the application does not supply a user name and password, supply the values. For other options, you can accept the default values, or change the options as desired.
Data Source A name that identifies the database connection properties. Server The host name or IP address of the Netezza system to which the ODBC driver connects. Database The name of the database on the Netezza system. User Name The user ID of the account on the Netezza system used to access the data source. Description A description or comment about the data in the data source. Port The port number for the data source. The default is 5480. Password The assigned password for the user specified.
5-4
20751-12
Rev.6
The Advanced Options tab displays more options. You can change these or accept the default options.
Read Only A boolean value that controls whether the database allows read-only access (only SQL Select statements are allowed), or full access. The default is deselected, which allows full access. To modify data, do not select the checkbox. If you do, only SQL Select statements are allowed. Show System Tables When retrieving a list of tables, this boolean value controls whether the system tables are included in the list. The default is deselected to omit system tables. Legacy SQL Tables Behavior A boolean value that, when enabled, causes SQLTables to return a list of all the users that own a database. The default is deselected to omit the list of users. Treat Numeric as Char When selected, this boolean value causes the driver to treat SQL_C_NUMERIC buffers as SQL_C_CHAR buffers. By default, this is deselected, which means that SQL_C_NUMERIC are treated as Numeric Structures. Return SQL_BIT as 1/0 If enabled, when a return type is char or wchar, this boolean value returns the values 1 or 0 instead of t or f. The default is deselected to return t/f values. If you prefer that SQL_BIT return numeric boolean values (1/ 0), select the checkbox. Strip CR/LF If enabled, this removes the carriage return and line feed characters from the SQL statements. The default is deselected to not remove these characters. Selecting the checkbox strips control characters out of your data. Load Round Fraction If the value is true, it rounds the actual data for numeric columns whose precision exceeds the precision defined in the target table. The default is deselected, to not round. Login Timeout The number of seconds after which to terminate the login process. Valid values are 0 (no timeout) or any positive number. Query Timeout The number of seconds after which to terminate the query request. Valid values are 0 (no timeout) or any positive number. Load Max Errors Tells the system to abort after N bad input rows. Default is 1, and 0 means no limit, with a maximum of 2,147,483,647 (the largest signed 32bit integer). Date Format Specifies the desired date format as one of the following values:
Note that on Windows platforms, you specify the text value (such as YMD); on nonWindows platforms, specify the numeric value (such as 1). The SSL DSN Options tab shows Secure Socket Layer options. Select one of the following options for the Security Level, and enter a CA filename.
Only Unsecured Only connections that do not use SSL to encrypt data will be accepted. This provides increased performance but carries the risks that come with an unencrypted connection.
20751-12
Rev.6
5-5
IBM Netezza ODBC, JDBC and OLE DB Installation and Configuration Guide
Preferred Unsecured Connections that do not use SSL are preferred, but a connection will not be refused solely because it uses SSL encryption. Preferred Secured (Default) Connections that use SSL are preferred, but a connection will not be refused solely because it does not use SSL encryption. Only Secured Only connections that use SSL to encrypt data will be accepted. This provides increased security but reduces performance somewhat, due to the necessity of encrypting the data stream.
CA Certificate File Enter the name of the CA (Certificate Authority) file (including the path) that will be used to authenticate connections. If a CA is being used for authentication, the name of the CA file must match the name defined by the system administrator for the database to which you are attempting to connect. Refer to the IBM Netezza Administrators Guide for information on security and authentication. Enable Debug Logging Select this box if you want the system to log information about each ODBC connection. This information may be helpful in debugging connection problems. For more information, see Appendix B, Troubleshooting. Log File Path The location of the debug log files. The default is c:\ on Windows systems. Optimize for ASCII character set The Netezza appliance uses the Latin9 character encoding for char and varchar types. The character encoding for many Windows systems is similar, but not identical. If your database includes characters that use only the basic subset of letters (a-z or A-Z), numbers (0-9), or punctuation characters, select the Optimize for ASCII character set option for the driver on Windows, which will improve query performance. If your data includes special characters such as the Euro symbol or others, de-select the option to ensure that the characters convert correctly. Prefetch Count A numeric value that sets the number of rows the driver will fetch at a time from an Netezza database. The default is 256 rows. To tune your application, set a value that optimizes network use versus memory use. Realize that the higher this value, the more memory will be required to hold these rows. Socket Buffer Size A numeric value that specifies the size of the communications buffer in bytes. The range is 1K to 32K. The default is 8192.
The Driver Options tab allows you to configure global driver options.
Test the Connection When finished selecting DSN and Driver options, select the DSN Options tab and and click the Test Connection button to establish a connection to this data source on your Netezza appliance server. A message box displays, indicating that the connection attempt was either successful or failed. If the connection attempt fails, check for erroneous configuration information, correct it, and test the connection again. If you cannot establish a connection after checking for errors, contact your Netezza system administrator. Finish the Configuration A successful connection message indicates that you have successfully configured an entry for the system data source. To end the configuration process, close all the open dialog boxes.
5-6
20751-12
Rev.6
= = = = = =
DebugLogging = false LogPath = /tmp UnicodeTranslationOption = utf8 CharacterTranslationOption = all PreFetch = 256 Socket = 8192
[ODBC] Trace TraceAutoStop TraceFile
= 0 = 0 = /tmp/sql.log
20751-12
Rev.6
5-7
IBM Netezza ODBC, JDBC and OLE DB Installation and Configuration Guide
Note: The Netezza ODBC driver properties are explained in Table 4-1 on page 4-2. Use this table to select appropriate values for the configuration entries in your .odbcinst.ini file. The CharacterTranslationOption can be set to all or latin9.
For HP-UX:
export PATH=$PATH:/usr/local/nz/bin export SHLIB_PATH=$SHLIB_PATH:/opt/datanz/nz/bin
Note: The above commands change the environment for the current session only. After you have verified that your environment modifications work correctly, edit your login script to set the environment variables when users log in. 3. Configure Netezza ODBC drivers by using a text editor to modify the contents of the .odbcinst.ini configuration file. You normally place the .odbcinst.ini file in your home directory while logged in as an ordinary user. You may want to place the .odbcinst.ini file in a different location, and you may want to do the configuration as the superuser, rather than as an ordinary user. These issues are discussed in Appendix A, ODBC Configuration Files.
5-8
20751-12
Rev.6
This step assumes you are logged in as an ordinary user and are placing the .odbcinst.ini file in your home directory. What you do in this step depends on whether or not the .odbcinst.ini file already exists in your home directory.
The Configuration File Exists. Use a text editor, such as vi, to examine the .odbcinst.ini configuration file if it already exists in your home directory, which may occur for different reasons, including the following:
Your client system was previously configured for one or more ODBC drivers other than the Netezza ODBC driver. If you still want to use those ODBC drivers, do not modify existing entries in the .odbcinst.ini file. In this case, add the entry in the odbcinst.ini.sample file to the end of the existing contents of the .odbcinst.ini file. The Netezza client software and an Netezza ODBC driver were previously installed on your client system, and the Netezza ODBC driver has already been configured. If this is so, you may not have to add any entries to the .odbcinst.ini file. If your .odbcinst.ini file already contains an entry similar to that found in the odbcinst.ini.sample file, do nothing. If it does not, then add the entry in the odbcinst.ini.sample file to the end of the existing contents of the .odbcinst.ini file.
The Configuration File Does Not Exist. If the .odbinst.ini configuration file does not yet exist in your home directory, copy the entire odbcinst.ini.sample file into your home directory and rename it .odbcinst.ini.
4. The entry from the odbcinst.ini.sample file can usually be used without modification in your .odbcinst.ini file. Consult your Netezza system administrator to see if any configuration entries need to be changed for your installation.
Database The name of the system database on the Netezza appliance. Username A valid user ID for accessing the system data source. Servername The server host name or IP address of your Netezza appliance. Password A valid password for accessing the system data source.
20751-12
Rev.6
5-9
IBM Netezza ODBC, JDBC and OLE DB Installation and Configuration Guide
The following shows the contents of a file named odbc.ini.sample, which is in the nz/ lib directory after you have installed your ODBC drivers. The sample file describes a system data source found on every Netezza appliance, and includes comments explaining each parameter. Use the contents of this sample file, along with the administrator information you substituted, to configure your own .odbc.ini file.
; ; ; [ODBC Data Sources] NZSQL = NetezzaSQL odbc.ini
;A decription used to identify the database connection properties. Description = NetezzaSQL ODBC
;The name of a machine or IP address where the database is located. Servername = 127.0.0.1
;Only Select SQL statements will be allowed if this field is checked. ReadOnly = false
;When set to true, system tables will be included in the available table list. ShowSystemTables = false
;When set to true, use old (2.5) functionality for returning schemas in SQLTables.
5-10
20751-12
Rev.6
LegacySQLTables
= false
;When selected, driver treats SQL_C_NUMERIC buffers as SQL_C_CHAR buffers. NumericAsChar = false
;When enabled, replaces all occurences of CRLF, CR and LF with a single space. StripCRLF = false
;Specifies maximum errors allowed. 0 value means no limit on loadMaxErrors value. ;loadMaxErrors = 1
;If value is true, it rounds the data of numeric columns whose precision exceeds the precision defined. ;loadRoundFraction = 0
20751-12
Rev.6
5-11
IBM Netezza ODBC, JDBC and OLE DB Installation and Configuration Guide
Note: The data source properties are explained starting on page 5-4. Use this information to select appropriate values for the entries in your .odbc.ini file.
The Configuration File Exists. If the .odbc.ini configuration file already exists in your home directory, use a text editor to examine the contents of the .odbc.ini file to see if it already contains entries for the Netezza appliance data sources to access. If it does not, copy the contents of the odbc.ini.sample file to the end of your existing .odbc.ini file. Do not modify any existing entries in the file. The Configuration File Does Not Exist. If the .odbc.ini configuration file does not yet exist in your home directory, copy the entire odbc.ini.sample file into your home directory and rename it .odbc.ini.
2. Once you have initially set up the .odbc.ini configuration file, use a text editor to modify entries in the file to describe the Netezza appliance data sources to access, as described in the section Data Source Configuration File on page 5-9. To access additional Netezza appliance data sources, supply a set of configuration entries, similar to that found in the odbc.ini.sample file, for each data source to access.
5-12
20751-12
Rev.6
Note: If you are using a driver manager other than the unixODBC driver manager, consult your Netezza system administrator to see if there is an SQL query program installed on your client system that you can use instead of isql to validate ODBC connectivity and query Netezza appliance data sources. The following example uses the DataDirect driver manager, where you run the example program in the example directory, specifying the NZSQL DSN, login, and password, displaying output as in the following:
./example DataDirect Technologies, Inc. ODBC Example Application. Enter the data source name : NZSQL Enter the user name Enter the password : admin : password
Once connected, you can run the same queries as used in the following examples. The system should return the same results.
2. Start the isql interactive SQL application, and connect to the NZSQL system data source by entering the following command:
isql -v NZSQL
If your connection is successful, you will see a response similar to the following:
+---------------------------------------+ | Connected! | | | | sql-statement |
20751-12
Rev.6
5-13
IBM Netezza ODBC, JDBC and OLE DB Installation and Configuration Guide
3. The system database in the NZSQL data source contains a table named _t_dslice. Enter the following command to query the _t_dslice table:
select * from _t_dslice
4. If your ODBC driver is correctly installed, and your system data source is correctly configured, the isql program displays the contents of the _t_dslice table from the system database in the NZSQL data source. You will see a response similar to the following:
+------------+------------+------------+------------+ | ds_id | ds_pridskid| ds_priptid | ds_mirdskid| +------------+------------+------------+------------+ | 1 | 1002 | 0 | | +------------+------------+------------+------------+
5. Enter the quit command to end the connection to the NZSQL system data source and exit the isql program. Then restart isql and connect to the Test_User user data source by entering the following command:
isql -v Test_User
If your connection is successful, you will again see a response similar to the following:
+---------------------------------------+ | Connected! | | | | sql-statement | | help [tablename] | | quit | +---------------------------------------+
6. The example assumes the system database in the Test_User data source contains a table named a_inventory. Enter the following command to query the a_ inventory table:
select * from a_inventory
7. If the ODBC driver is correctly installed, and the user data source is correctly configured, the isql program displays the contents of the a_inventory table from the system database in the Test_User data source:
+------------+----------+------------+ | part_no | part_name| on_hand | +------------+----------+------------+ | 181 | Wheel | 449 | | 124 | Bolt | 900 | | 105 | Gear | 0 | | 134 | Nut | 743 | +------------+----------+------------+
5-14
20751-12
Rev.6
CHAPTER 6
Installing and Configuring JDBC
Whats in this chapter
Installing JDBC for Windows Installing JDBC for UNIX/Linux Configuring a JDBC Data Source (Windows Only)
This chapter describes the procedures to install and configure JDBC. You can have only one JDBC driver installed on your system at any given time. If you need a different driver, you will need to remove the installed driver and install the different one. For more information on removing the driver, see Chapter 3, Installing and Uninstalling Client Tools. Note: After installation, when you run an application trying to use JDBC, you are prompted for a value called Class Name. For the Netezza Driver, enter the following:
org.netezza.Driver
6-1
IBM Netezza ODBC, JDBC and OLE DB Installation and Configuration Guide
Complete the following steps to install the JDBC driver. 1. Start the installation program by double-clicking the nzjdbcsetup.exe program. For directions, see Installation Files Access on page 1-5. 2. A language option window is displayed, which controls the language for the installation program. Accept the default of English and click OK. 3. The Introduction window is displayed. Review the information and click Next. 4. The Choose Install Folder window is displayed. This allows you the option to change the installation folder from the Netezza default. When done, click Next. 5. The Pre-Installation Summary window is displayed, summarizing your installation choices. To page through the previous selections to review selections, use the Previous button. When finished, click Install. 6. The Installation Completed window indicates that the Netezza JDBC driver installation process has completed successfully. Click Done to exit.
Note: The above export commands change the environment for the current session only. Once you have verified that your environment modification works correctly, you can edit your login script to set the environment variable when users log in.
6-2
20751-12
Rev.6
2. Use the rcp or ftp command (using binary transfer mode) to copy the JDBC driver to your client machine. The following is a command example:
rcp nzjdbc3.jar <client machine>
3. Modify the CLASSPATH environment variable on the client machine to include the path of the directory in which you placed the JDBC driver.
2. The list of data sources screen is displayed. Select Add to add a new data source.
20751-12
Rev.6
6-3
IBM Netezza ODBC, JDBC and OLE DB Installation and Configuration Guide
3. The Datasource Configuration screen is displayed. Select the Connection Options tab and enter the information in the appropriate fields:
Data Source Name of the data source (Mandatory). Host Name of the host to connect to (Mandatory). Port Port number (Mandatory). Database Database (Catalog) name (Mandatory). Description Description for the data source. User Username to connect to the database. Password Password for authentication. Test Connection Tests the connection with the given parameters.
4. Select the Advanced Options tab and enter the information in the appropriate fields:
Batch Size Number of rows to be fetched in a cycle. Default - 256. Login Timeout Maximum wait time to make a connection. Default - infinite. Read Only Read Only property for the connection. Default - false. Auto Commit Auto Commit property for the connection. Default - true. Log Level Log Level for the connection. Default - OFF. Logger Type The type to be used for logging. Default - TEXT. Logger Directory Log directory where the log files will be dumped. Database Metadata When selected, you can get metadata information that is not restricted to the current catalog/schema. Not selecting this means your information will be restricted to the current catalog/schema. Default - not selected. Defaults Selects the defaults for these options.
5. Select the SSL Options tab and enter the security level information as appropriate:
Preferred Unsecured Connections that do not use SSL are preferred, but a connection will not be refused solely because it uses SSL encryption. Only Unsecured Only connections that do not use SSL to encrypt data will be accepted. This provides increased performance but carries the risks that come with an unencrypted connection. Preferred Secured Connections that use SSL are preferred, but a connection will not be refused solely because it does not use SSL encryption. Only Secured Only connections that use SSL to encrypt data will be accepted. This provides increased security but reduces performance somewhat, due to the necessity of encrypting the data stream. CA Certificate File Enter the name of the CA (Certificate Authority) file used to authenticate connections. If a CA is being used for authentication, the name of the CA file must match the name defined by the system administrator for the database to which you are attempting to connect. Refer to the IBM Netezza Administrators Guide for information on security and authentication.
6. When finished entering Datasource Configuration options, test the connection by selecting the Test Connection button on the Connection Options tab. When the connection is established, a confirmation screen displays. Select OK.
6-4
20751-12
Rev.6
7. When all your options have been entered and your connection has ben tested, select Ok on the Datasource Configuration screen. The Data Source and description appears in the List of Data Sources screen. 8. Select Exit when finished.
20751-12
Rev.6
6-5
IBM Netezza ODBC, JDBC and OLE DB Installation and Configuration Guide
6-6
20751-12
Rev.6
CHAPTER 7
Installing and Configuring OLE DB
Whats in this chapter
Installing OLE DB Provider Configuring an OLE DB Data Source
This chapter describes the procedure for installing the Netezza OLE DB provider on a Windows client system, configuring the provider and data sources, and testing for connectivity to Netezza appliance data sources.
c:\>nzoledbsetup.exe (full GUI install) c:\>nzoledbsetup.exe -i silent (silent install, VC8 Libraries not installed) c:\>nzoledbsetup.exe -i silent -DVC8_LIB_INSTALL=1 (silent install, VC8 Libraries installed)
c:\>nzoledbsetup64.exe (full GUI install) c:\>nzoledbsetup64.exe -i silent (silent install, VC8 Libraries not installed) c:\>nzoledbsetup64.exe -i silent -DVC8_LIBS_INSTALL=1 (silent install, VC8 Libraries installed)
7-1
IBM Netezza ODBC, JDBC and OLE DB Installation and Configuration Guide
4. Install the Visual Studio 8 libraries. 5. Review the installation options. 6. Finish the installation.
Installs the Netezza OLE DB provider. A 32-bit provider on a 32-bit system and a 64-bit provider on a 64-bit system are installed in the \WINDOWS\system32 folder. On a 64-bit system, both providers are installed, and the 32-bit provider is installed in the \WINDOWS\SysWOW64 folder. Places entries in the Windows registry to add the Netezza OLE DB Provider to the provider list.
6. The Install Complete window is displayed, which indicates that the installation process has completed successfully. Click Done to close the installation program. Before trying to access an OLE DB data source, you must configure it. The next section describes the configuration procedure.
7-2
20751-12
Rev.6
20751-12
Rev.6
7-3
IBM Netezza ODBC, JDBC and OLE DB Installation and Configuration Guide
7-4
20751-12
Rev.6
APPENDIX
ODBC Configuration Files
Whats in this appendix
Netezza ODBC Driver unixODBC Driver Manager DataDirect Driver Manager
This appendix introduces advanced considerations for configuring ODBC drivers and data sources on Linux/UNIX client systems, with respect to locating the .odbcinst.ini and .odbc.ini configuration files.
Hidden Files. When you place the two ODBC configuration files in the users home directory, the Netezza ODBC driver expects the files to have the hidden file names .odbcinst.ini and .odbc.ini. Non-Hidden Files. When you place the two ODBC configuration files in a directory other than the users home directory, the Netezza ODBC driver expects the files to have the non-hidden file names odbcinst.ini and odbc.ini.
A-1
IBM Netezza ODBC, JDBC and OLE DB Installation and Configuration Guide
3. If the driver does not find hidden configuration files in the current users home directory, it next looks in the /usr/local/etc directory for the two non-hidden files odbcinst.ini and odbc.ini. If the two configuration files exist as hidden files in the /usr/local/etc directory, the driver ignores them.
Compatibility
The methods the Netezza ODBC driver and the unixODBC driver manager use to locate the configuration files are compatible. It is relatively easy to ensure that the Netezza ODBC Driver and the unixODBC driver manager find the two ODBC configuration files in the same place. Their uses of hidden and non-hidden files are also compatible.
A-2
20751-12
Rev.6
Place hidden configuration files in each users home directory if each user needs to access different Netezza appliance data sources. Place non-hidden configuration files in the /usr/local/etc directory if all users will access the same Netezza appliance data sources. With the unixODBC driver manager, you do not need to use the NZ_ODBC_INI_PATH environment variable.
Incompatibilities
The following are incompatibilities between the Netezza ODBC drivers and the DataDirect driver manager: 1. The DataDirect driver manager looks first in the current users home directory for nonhidden configuration files instead of hidden ones. 2. The DataDirect driver manager looks next in the /etc directory instead of in the /usr/local/etc directory. 3. The DataDirect driver manager also looks at the value of the environment variable ODBCINI to determine the location of the odbc.ini file to use. To work around the DataDirect driver managers ODBC configuration file search incompatibilities, do one of the following: 1. Separate Configuration Files in Each Home Directory. Use this method if you would like each user of the Linux/UNIX client system to use a separate set of ODBC configuration files. Netezza ODBC drivers look for hidden configuration files, and the DataDirect driver manager looks for non-hidden files. To overcome this incompatibility, create two soft links in each users home directory so the DataDirect driver manager finds non-hidden files in the home directory and the Netezza ODBC driver finds hidden files:
A soft link so odbcinst.ini points to .odbcinst.ini A soft link so odbc.ini points to .odbc.ini
20751-12
Rev.6
A-3
IBM Netezza ODBC, JDBC and OLE DB Installation and Configuration Guide
2. Shared Configuration Files. Use this method if you would like all users of the Linux/ UNIX client system to use the same set of ODBC configuration files. Configure the NZ_ODBC_INI_PATH environment variable so it specifies the /etc directory, and place the two non-hidden configuration files odbcinst.ini and odbc.ini in the /etc directory. The DataDirect driver manager and the Netezza ODBC driver then both find the configuration files in the /etc directory. 3. Two environment variables. Use this method if you would like both the Netezza ODBC driver and DataDirect driver manager to find the configuration files no matter where they are on the filesystem. Use both NZ_ODBC_INI_PATH and ODBCINI together to point to the odbc.ini and odbcinst.ini files anywhere on the filesystem.
The information displayed by the above command tells you if there are any entries in the environment that contain the characters ODBC. You might see a result like the following:
ODBC_HOME=/opt/odbc
or
ODBCINI=/opt/odbc/odbc.ini
Results such as the above give you clues as to how the client system is presently configured. You can than look in the referenced directories for ODBC configuration files, and then configure the Netezza ODBC driver to look in those same directories for the ODBC configuration files.
A-4
20751-12
Rev.6
APPENDIX
Troubleshooting
Whats in this appendix
ODBC Debug Logging and Driver Manager Tracing JDBC Debug Logging OLE DB Debug Logging
This appendix introduces methods for tracking system activity, which can help in detecting problems and troubleshooting issues. A debug log provides you with a record of system activity, so you can take steps to correct problems.
B-1
IBM Netezza ODBC, JDBC and OLE DB Installation and Configuration Guide
B-2
20751-12
Rev.6
loglevel
You can set the following case-insensitive log levels: Table B-1: Log Levels Level off debug info entry_exit fatal Number 0 2 3 4 5 Result No messages will be logged (default). Logging is done at debug level. Every message will be logged. Only information messages, entry exit statements, and fatal messages will be logged. Only entry exit statements and fatal messages will be logged. Only fatal messages will be logged.
Enter the log level either by type or by number, as in the following examples: loglevel=entry_exit loglevel=4
loggertype
You can set the following case-insensitive log format types:
logdirpath
You can set the directory path for the log files, as in the following: logdirpath=<path on the local file system> The default values for logdirpath are as follows:
Windows:
C:\
UNIX/Linux: /tmp/
UNIX logdirpath:
jdbc:netezza://tom/will;user=admin;password=password;loglevel=2; logdirpath=/jdbc_log_file
Windows logdirpath:
jdbc:netezza://tom/will;user=admin;password=password;loglevel=2; logdirpath=C:\
20751-12
Rev.6
B-3
IBM Netezza ODBC, JDBC and OLE DB Installation and Configuration Guide
Provider Enter NZOLEDB User ID Enter your user ID Password Enter your password Data Source Enter the Netezza appliance hostname Initial Catalog Enter the database name Port Enter the port number (default is 5480) Logging Level Enter 1 to enable logging or 0 for no logging Log Path Enter the path for the log file (for example, c:\logs)
B-4
20751-12
Rev.6
APPENDIX
Notices and Trademarks
Whats in this appendix
Notices Trademarks Open Source Notifications Regulatory and Compliance
This information was developed for products and services offered in the U.S.A.
Notices
IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A. For license inquiries regarding double-byte character set (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to: Intellectual Property Licensing Legal and Intellectual Property Law IBM Japan Ltd. 1623-14, Shimotsuruma, Yamato-shi Kanagawa 242-8502 Japan The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
C-1
IBM Netezza ODBC, JDBC and OLE DB Installation and Configuration Guide
IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact: IBM Corporation 26 Forest Street Marlborough, MA 01752 U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee. The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us. Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment. Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products. All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only. This information is for planning purposes only. The information herein is subject to change before the products described become available. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.
C-2
20751-12
Rev.6
Trademarks
COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. The sample programs are provided "AS IS", without warranty of any kind. IBM shall not be liable for any damages arising out of your use of the sample programs. Each copy or any portion of these sample programs or any derivative work, must include a copyright notice as follows: (your company name) (year). Portions of this code are derived from IBM Corp. Sample Programs. Copyright IBM Corp. _enter the year or years_. All rights reserved. If you are viewing this information softcopy, the photographs and color illustrations may not appear.
Trademarks
IBM, the IBM logo, and ibm.com are trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at www.ibm.com/legal/copytrade.shtml. Netezza, the Netezza logo, the circle-N logo, TwinFin, Skimmer, Snippet Blades, S-Blades, NPS, Snippet, Snippet Processing Unit, SPU, Snippet Processing Array, SPA, Performance Server, Netezza Performance Server, Asymmetric Massively Parallel Processing, AMPP, Intelligent Query Streaming and other marks are trademarks or registered trademarks of Netezza Corporation, an IBM Company, in the United States and/or other countries. All rights reserved. The following terms are trademarks or registered trademarks of other companies: Adobe is a registered trademark of Adobe Systems Incorporated in the United States, and/ or other countries. Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both. Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corppration in the United States, other countries, or both. NEC is a registered trademark of NEC Corporation. UNIX is a registered trademark of The Open Group in the United States and other countries. Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Red Hat is a trademark or registered trademark of Red Hat, Inc. in the United States and/or other countries. D-CC, D-C++, Diab+, FastJ, pSOS+, SingleStep, Tornado, VxWorks, Wind River, and the Wind River logo are trademarks, registered trademarks, or service marks of Wind River Systems, Inc. Tornado patent pending.
20751-12
Rev.6
C-3
IBM Netezza ODBC, JDBC and OLE DB Installation and Configuration Guide
APC and the APC logo are trademarks or registered trademarks of American Power Conversion Corporation. All document files and software of the above named third-party suppliers are provided "as is" and may contain deficiencies. Netezza and its suppliers disclaim all warranties of any kind, express or implied, including, without limitation, those of merchantability, fitness for a particular purpose, and non infringement. In no event will Netezza or its suppliers be liable for indirect, incidental, consequential, special, or economic damages (including lost business profits, business interruption, loss or damage of data, and the like), or the use or inability to use the above-named third-party products, even if Netezza or its suppliers have been advised of the possibility of such damages. Other company, product or service names may be trademarks or service marks of others.
C-4
20751-12
Rev.6
to do so, provided that the above copyright notice(s) and this permission notice appear in all copies of the Software and that both the above copyright notice(s) and this permission notice appear in supporting documentation. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. Except as contained in this notice, the name of a copyright holder shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization of the copyright holder. ODBC Driver The Netezza implementation of the ODBC driver is an adaptation of an open source driver, Copyright 2000, 2001, Great Bridge LLC. The source code for this driver and the object code of any Netezza software that links with it are available upon request to [email protected] Botan License Copyright (C) 1999-2008 Jack Lloyd 2001 Peter J Jones 2004-2007 Justin Karneges 2005 Matthew Gregan 2005-2006 Matt Johnston 2006 Luca Piccarreta 2007 Yves Jerschow 2007-2008 FlexSecure GmbH 2007-2008 Technische Universitat Darmstadt 2007-2008 Falko Strenzke 2007-2008 Martin Doering 2007 Manuel Hartl 2007 Christoph Ludwig 2007 Patrick Sona All rights reserved. Redistribution and use in source and binary forms, for any use, with or without modification, of Botan (http://botan.randombit.net/license.html) is permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions, and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions, and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ARE DISCLAIMED.
20751-12
Rev.6
C-5
IBM Netezza ODBC, JDBC and OLE DB Installation and Configuration Guide
IN NO EVENT SHALL THE AUTHOR(S) OR CONTRIBUTOR(S) BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITYOF SUCH DAMAGE.
C-6
20751-12
Rev.6
Warning: This is a class A product. In a domestic environment this product may cause radio interference in which case the user may be required to take adequate measures. VCCI Statement
VCCI A
20751-12
Rev.6
C-7
IBM Netezza ODBC, JDBC and OLE DB Installation and Configuration Guide
C-8
20751-12
Rev.6
Index
Index
A
architecture 1-2 Windows 6-1 online documentation Oracle Sun Developer Network URL -xiii
C
Character Translation Option window 5-2 client tools uninstall Windows 3-5 configuration files. See ODBC driver or data source configuration files. configuration. See ODBC or JDBC driver or data source configuration.
M
MDAC 4-3 Microsoft Data Access Component (MDAC) 4-3
O
ODBC API 2-3 data source configuration Linux 5-9 Windows 5-3 data source configuration file, Linux 5-9 data source configuration procedure Linux 5-12 Windows 5-4 data source configuration steps Linux 5-12 debug logging B-1 driver configuration Linux 5-7 driver configuration file, Linux 5-7 driver configuration procedure, Linux 5-8 driver configuration steps, Linux 5-8 driver functions 4-1 driver installation procedure for Windows 5-2 Windows 5-1, 5-7 driver manager tracing B-2 driver manager. See driver manager driver properties 4-2 driver version support 2-3 IBM Netezza driver version support 2-3 IBM Netezza-supported platforms 2-1 installation Windows 5-1, 5-7 online documentation Microsoft URL -xiii standards conformance 2-3 validating connectivity Linux 5-12 validating connectivity procedure Linux 5-13 validating connectivity steps Linux 5-13 ODBC configuration files A-1 ODBC driver Visual Studio 8 libraries 5-3 OLE DB debug logging B-4 provider installation steps for Windows 7-1 provider installation for Windows 7-2 validating connectivity 7-3 Visual Studio 8 libraries 7-2
D
data source configuration. See ODBC or JDBC data source configuration. data sources. See ODBC or JDBC data sources. DataDirect driver manager A-3 driver configuration. See ODBC or JDBC driver configuration. driver installation. See ODBC or JDBC driver installation. driver manager absence in JDBC architecture 4-3 DataDirect configuration file search behavior A-3 IBM Netezza ODBC driver incompatibilities A-3 functions 4-2 in Linux/UNIX systems 4-3 in Windows systems 4-3 introduction 4-2 Recommendation for Linux/UNIX systems 4-3 unixODBC compatibility with IBM Netezza ODBC drivers A-2 configuration file search behavior A-2 installation procedure 4-4 installation steps 4-4
I
installation. See client tools, ODBC or JDBC installation.
J
JDBC configuration Linux 6-2 Windows 6-3 data source configuration Windows 6-3 debug logging B-2 driver configuration, Windows 6-3 driver data source 2-4 installation Linux 6-2 unsupported platforms 6-2
Index-1
Index
R
release compatibility 2-2
S
supported platforms 2-1
U
unixODBC driver manager A-2 installation procedure 4-4 installation steps 4-4
V
Visual Studio 8 (VC8) Libraries 5-3
Index-2