ODBC Driver for Teradata. User Guide

Transcription

1 ODBC Driver for Teradata User Guide Release B A July 2007

2 The product or products described in this book are licensed products of Teradata Corporation or its affiliates. Teradata, BYNET, DBC/1012, DecisionCast, DecisionFlow, DecisionPoint, Eye logo design, InfoWise, Meta Warehouse, MyCommerce, SeeChain, SeeCommerce, SeeRisk, Teradata Decision Experts, Teradata Source Experts, WebAnalyst, and You ve Never Seen Your Business Like This Before are trademarks or registered trademarks of Teradata Corporation or its affiliates. Adaptec and SCSISelect are trademarks or registered trademarks of Adaptec, Inc. AMD Opteron and Opteron are trademarks of Advanced Micro Devices, Inc. BakBone and NetVault are trademarks or registered trademarks of BakBone Software, Inc. EMC, PowerPath, SRDF, and Symmetrix are registered trademarks of EMC Corporation. GoldenGate is a trademark of GoldenGate Software, Inc. Hewlett-Packard and HP are registered trademarks of Hewlett-Packard Company. Intel, Pentium, and XEON are registered trademarks of Intel Corporation. IBM, CICS, DB2, MVS, RACF, Tivoli, and VM are registered trademarks of International Business Machines Corporation. Linux is a registered trademark of Linus Torvalds. LSI and Engenio are registered trademarks of LSI Corporation. Microsoft, Active Directory, Windows, Windows NT, and Windows Server are registered trademarks of Microsoft Corporation in the United States and other countries. Novell and SUSE are registered trademarks of Novell, Inc., in the United States and other countries. QLogic and SANbox trademarks or registered trademarks of QLogic Corporation. SAS and SAS/C are trademarks or registered trademarks of SAS Institute Inc. SPARC is a registered trademarks of SPARC International, Inc. Sun Microsystems, Solaris, Sun, and Sun Java are trademarks or registered trademarks of Sun Microsystems, Inc., in the United States and other countries. Symantec, NetBackup, and VERITAS are trademarks or registered trademarks of Symantec Corporation or its affiliates in the United States and other countries. Unicode is a collective membership mark and a service mark of Unicode, Inc. UNIX is a registered trademark of The Open Group in the United States and other countries. Other product and company names mentioned herein may be the trademarks of their respective owners. THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROVIDED ON AN AS-IS BASIS, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO THE ABOVE EXCLUSION MAY NOT APPLY TO YOU. IN NO EVENT WILL TERADATA CORPORATION BE LIABLE FOR ANY INDIRECT, DIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS OR LOST SAVINGS, EVEN IF EXPRESSLY ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. The information contained in this document may contain references or cross-references to features, functions, products, or services that are not announced or available in your country. Such references do not imply that Teradata Corporation intends to announce such features, functions, products, or services in your country. Please consult your local Teradata Corporation representative for those features, functions, products, or services available in your country. Information contained in this document may contain technical inaccuracies or typographical errors. Information may be changed or updated without notice. Teradata Corporation may also make improvements or changes in the products or services described in this information at any time without notice. To maintain the quality of our products and services, we would like your comments on the accuracy, clarity, organization, and value of this document. Please teradata-books@lists.teradata.com Any comments or materials (collectively referred to as Feedback ) sent to Teradata Corporation will be deemed non-confidential. Teradata Corporation will have no obligation of any kind with respect to Feedback and will be free to use, reproduce, disclose, exhibit, display, transform, create derivative works of, and distribute the Feedback and derivative works thereof without limitation on a royalty-free basis. Further, Teradata Corporation will be free to use any ideas, concepts, know-how, or techniques contained in such Feedback for any purpose whatsoever, including developing, manufacturing, or marketing products or services incorporating Feedback. Copyright by Teradata Corporation. All Rights Reserved.

3 Preface Purpose This book provides information about ODBC Driver for Teradata, which is a Teradata Tools and Utilities product. Teradata Tools and Utilities is a group of products designed to work with Teradata Database. The ODBC Driver for Teradata enables UNIX, Linux and Microsoft Windows operating systems to communicate with the Teradata Database across local area networks (LAN) using the open standards ODBC interface. With the ODBC Driver for Teradata, connect Microsoft Windows, Linux, and UNIX applications to the Teradata Database. Audience This book is intended for use by: System and application programmers System administrators Supported Releases This book supports the following releases: Teradata Database 12.0, V2R6.2, V2R6.1, V2R6.0 Teradata Tools and Utilities ODBC Driver for Teradata Note: See Determining the Current Version of the ODBC Driver for Teradata on page 20 to verify the ODBC Driver for Teradata version number. To locate detailed supported-release information: 1 Go to 2 Navigate to General Search>Publication Product ID. 3 Enter Open the version of the Teradata Tools and Utilities Supported Versions spreadsheet associated with this release. The spreadsheet includes supported Teradata Database versions, platforms, and product release numbers. ODBC Driver for Teradata User Guide 3

4 Preface Prerequisites Prerequisites The following prerequisite knowledge is required for this product: Microsoft Windows, Linux, or UNIX concepts and commands ANSI Structured Query Language (SQL) ODBC and Teradata SQL Changes to This Book The following changes were made to this book in support of the current release. Changes are marked with change bars. For a complete list of changes to the product, see the Teradata Tools and Utilities Release Definition associated with this release. Date and Release July Description The ODBC Driver for Teradata Version includes: Support for Teradata Database features: Improved metadata for parameters and result sets Retrieval of auto-generated keys from an Insert statement Stored procedure dynamic result sets Unicode Data Dictionary Multi-level partitioned primary index Table function dynamic results Mini-batch: INSERT-SELECT and MERGE-INTO error logging syntax ODBC support for SQLDescribeParam Support for 64-bit ODBC Driver for Teradata for Microsoft Windows XP and Microsoft Windows 2003 (64-bit EM64T) Support for 32-bit ODBC Driver for Teradata on Sun Solaris 10 Opteron Support for 64-bit ODBC Driver for Teradata on Sun Solaris 10 Opteron Support for Solaris 10 zones Support for 32-bit ODBC Driver for Teradata for Microsoft Windows Vista Enterprise (32-bit and 64-bit) Support for 64-bit ODBC Driver for Teradata for Microsoft Windows Vista Enterprise (64-bit) Support for new DSN option retryoneintr. Miscellaneous edits and updates, including updated GUI screen shots of ODBC Data Source Administrator, Teradata ODBC Driver Options, and Teradata ODBC Advanced Options. 4 ODBC Driver for Teradata User Guide

5 Preface Additional Information Additional Information Additional information that supports this product and Teradata Tools and Utilities is available at the web sites listed in the table that follows. Type of Information Description Access to Information Release overview Late information Additional product information CD-ROM images Ordering information for manuals Use the Release Definition for the following information: Overview of all of the products in the release Information received too late to be included in the manuals Operating systems and Teradata Database versions that are certified to work with each product Version numbers of each product and the documentation for each product Information about available training and the support center Use the Teradata Information Products Publishing Library site to view or download specific manuals that supply related or additional information to this manual. Access a link to a downloadable CD-ROM image of all customer documentation for this release. Customers are authorized to create CD-ROMs for their use from this image. Use the Teradata Information Products Publishing Library site to order printed versions of manuals. 1 Go to 2 Select the General Search check box. 3 In the Publication Product ID box, type Click Search. 5 Select the appropriate Release Definition from the search results. 1 Go to 2 Select the Teradata Data Warehousing check box. 3 Do one of the following: For a list of Teradata Tools and Utilities documents, click Teradata Tools and Utilities and then select a release or a specific title. Select a link to any of the data warehousing publications categories listed. 1 Go to 2 Select the General Search check box. 3 In the Title or Keyword box, type CD-ROM. 4 Click Search. 1 Go to 2 Select the How to Order check box under Print & CD Publications. 3 Follow the ordering instructions. ODBC Driver for Teradata User Guide 5

6 Preface Additional Information Type of Information Description Access to Information General information about Teradata The Teradata home page provides links to numerous sources of information about Teradata. Links include: Executive reports, case studies of customer experiences with Teradata, and thought leadership Technical information, solutions, and expert advice Press releases, mentions, and media resources 1 Go to Teradata.com. 2 Select a link. 6 ODBC Driver for Teradata User Guide

7 Table of Contents Preface Purpose Audience Supported Releases Prerequisites Changes to This Book Additional Information Chapter 1: Product Overview ODBC Driver for Teradata Background New Features Certification Determining the Current Version of the ODBC Driver for Teradata Microsoft Windows Hardware and Software Requirements Hardware Software UNIX Hardware and Software Requirements Chapter 2: ODBC Driver for Teradata Configuration for UNIX ODBC Directories Verification of the TCP/IP Connection Displaying the tdata man Page Configuring the UNIX and Linux Environment Setting SHLIB_PATH Setting LD_LIBRARY_PATH Setting LIBPATH Additional Environment Variables ODBC Driver for Teradata User Guide 7

8 Table of Contents Setting ODBCINI Setting LANG The.odbc.ini File What are Data Sources? odbc.ini UNIX Compilation Options ODBC Options Section ODBC Data Sources Section Data Source Specification Section DSN Tracing Default Data Source Specification Section Adding a Data Source File Options Session Character Sets and Translation DLLs Chapter 3: ODBC Driver for Teradata Configuration for Microsoft Windows Microsoft Windows Options Configurable Through Setup Configuring a Data Source Reconfiguring a Data Source Resolving a Data Source Alias Name IP Addresses Alias Names Session Character Sets and Translation DLLs Chapter 4: ODBC Application Development Software Development Kits Microsoft Windows Application Development UNIX Application Development ODBC Conformance ODBC API SQLSetConnectOption() and SQLSetConnectAttr() Statement Options Set in SQLSetStmtAttr() Extension Level Functions SQLTablePrivileges ODBC Driver for Teradata User Guide

9 Table of Contents Attributes Supported Descriptor Fields ODBC SQL Grammar Core Compliance Subqueries ODBC Escape Clauses CREATE and DROP INDEX ODBC Named Indexes Scalar Functions ANSI SQL 1992 Syntax ANSI SQL with No Equivalent Teradata Simulation Interval Values Data Types for ANSI Compliance ODBC Connection Functions SQLConnect SQLDriverConnect SQLBrowseConnect Keywords for SQLDriverConnect() and SQLBrowseConnect() SQLGetInfo - Get User Name ODBC Pattern Escape Character Large Objects ODBC LOB Data Types Teradata LOB Data Types Teradata SQL and LOB Types LOB Limitations The Native LOB Support Option Option Setting Application Programming Considerations LOB Considerations for the ODBC API Sample ODBC Programs Accessing LOB Data User-Defined Functions Return Codes Parameter Markers Table Functions Restrictions User-Defined Types and User-Defined Methods Using User-Defined Types with ODBC User-Defined Methods Return Codes Catalog Functions Restrictions Parameter Arrays ODBC Driver for Teradata User Guide 9

10 Table of Contents Performance Using Parameter Arrays Restrictions Error Handling and Transaction Semantics Large Decimal and BIGINT Support bit Support Chapter 5: Network Security Password Encryption Single Sign On (Microsoft Windows only) Enabling SSO SSO Usage SSO Error Messages Data Encryption Connection Level Statement Level Backward Compatibility Gateway Dependency Performance Considerations Extensible Authentication, Authorization, and Encryption Authentication Authorization Confidentiality Integrity Authentication Mechanisms Determination of Authentication Mechanism Configuring Authentication Mechanisms Connecting to the Teradata Database Username and Password Requirements Enhancing Security Usage or Functionality Constraints Disconnect After Security Context Expiration Connection Pooling (Microsoft Windows) TDGSS Support for UTF ODBC Driver for Teradata User Guide

11 Table of Contents Chapter 6: ODBC for Teradata Application Development Teradata Extensions to the ODBC Standard SQL Column Attributes SQL Descriptor Fields SQLColumns SQLSetConnectAttr SQLSetStmtAttr Connection Pooling (Microsoft Windows only) Pooling Advantage Driver Manager Using Connection Pools Stored Procedures Stored Procedure Creation from ODBC Checking for Stored Procedure Support Print and SPL Options SPL Compilation Errors and Warnings Structure of Error and Warning Messages Executing Stored Procedures from ODBC Rules for Input and Output Arguments Stored Procedures Dynamic Result Sets External Stored Procedures Auto-Generated Key Retrieval Using Extended Statement Information SQL_DESC_UNSIGNED is set regardless of FORMAT SQL_DESC_BASE_COLUMN_NAME when there is an alias SQL_DESC_CASE_SENSITIVE International Character Set Support Introduction ODBC C Character Data Types ODBC SQL Character Data Types Conversion and Error Handling Parameter and Result Set Data Error Handling ANSI ODBC Applications Unicode ODBC Applications Application Considerations Length Arguments for Unicode ODBC Functions User-Defined Session Character Set Support Translation DLLs Application Code Page ODBC Driver for Teradata User Guide 11

12 Table of Contents UTF8 Pass Through Functionality Restrictions Atomic UPSERT Syntax ANSI Date/Time Restrictions ANSI Date/Time Feature Supporting Intervals Requirements to Use Intervals x ODBC Driver Custom Header byte Structure Member Alignment Restrictions Multi-Statement SQL Requests Teradata String Constants Teradata Column Limitation WITH Clause Asynchronous Operation ANSI Migration Issues Transaction Semantics Data Truncation Duplicate Rows Updateable Cursors Case Sensitivity Configuration Characteristics ACCESS Locks Database Password Expiration SQL Considerations Newname in SELECT Statement ANSI Comments in SQL Requests Index ODBC Driver for Teradata User Guide

13 List of Figures Figure 1: Parameters Figure 2: Programming Model for the ODBC Driver for Teradata When Used with ANSI Applications Figure 3: Programming Model for the ODBC Driver for Teradata When Used with Unicode Applications Figure 4: User-defined Session Character Set Figure 5: Translation.dll as the Translator ODBC Driver for Teradata User Guide 13

14 List of Figures 14 ODBC Driver for Teradata User Guide

15 List of Tables Table 1: Disk Space Requirements Table 2: Software Requirements (Microsoft Windows) Table 3: Hardware and Software Requirements (UNIX) Table 4: ODBC Directories Table 5: System-Dependent Environment Variables Table 6: Optional Environment Variables Table 7:.odbc.ini Sections Table 8: ODBC Options Section Keywords Table 9: ODBC Data Sources Section Keywords Table 10: Data Source Specification Section Keywords Table 11: Data Source Name Tracing Table 12: Options Configurable in the.odbc.ini File Table 13: Function of SQLDriverToDataSource Table 14: Function of the SQLDataSourceToDriver Table 15: ODBC Driver for Teradata for Windows Setup Table 16: ODBC Driver for Teradata Options Table 17: Advanced Options Dialog Box Options Table 18: Function of SQLDriverToDataSource Table 19: Function of the SQLDataSourceToDriver Table 20: Supported Compilers Windows Table 21: Supported Compilers UNIX Table 22: Core Level Functions Table 23: SQLSetConnectOption and the SQLSetConnectAttr Parameters Table 24: Statement Options Table 25: Extension Level Functions Table 26: SQL Privileges Table 27: Discontinued Functions Table 28: Unsupported Functions Table 29: Environment Attributes Table 30: Connection Attributes Table 31: Statement Attributes Table 32: Header Fields ODBC Driver for Teradata User Guide 15

16 List of Tables Table 33: Record Fields Table 34: ODBC Driver for Teradata Core Grammar Compliance Table 35: SQL Grammar Extensions Table 36: ODBC Escape Clauses Table 37: Scalar Functions Table 38: ANSI Syntax Table 39: Interval Values Table 40: ANSI Data Types Table 41: SQL Data Type Name Changes Table 42: SQL C-Type Identifier Changes Table 43: Columns Renamed for ODBC 3.x Table 44: Columns Added Table 45: SQLDriverConnect() and SQLBrowseConnect() Keywords Table 46: ODBC Pattern Escape Character Table 47: UseNativeLOB Support Option Table 48: UseNativeLOB Support=Yes Table 49: UseNativeLOB Support=No Table 50: SQLGetData Options Table 51: SQLGetTypeInfo Options Table 52: SQLColAttribute Options Table 53: SQLColumns LOB Information Table 54: SQLGetInfo LOB Information Table 55: UDF Return Codes Table 56: UDT and UDM Catalog Functions Table 57: Types of DML Statements with Array Support Table 58: Limiting Conditions for Array Requests Table 59: SSO Error Messages Table 60: Database Dependencies Table 61: Authentication Mechanisms Table 62: Username and Password Requirements Table 63: C Definitions Table 64: C Definitions for Extended fdesctype Values Table 65: Additional SQL Columns Table 66: SQLSetConnectAttr Defined Attributes Table 67: SQLSetStmtAttr Defined Attributes Table 68: Stored Procedure Support ODBC Driver for Teradata User Guide

17 List of Tables Table 69: Availability of Extended Statement Information Table 70: Supported Session Character Sets Table 71: SQL_C_CHAR and SQL_C_WCHAR C Data Types Table 72: ODBC SQL Character Data Types Table 73: Parameter and Result Set Data Table 74: IANAAppCodePage Values Table 75: Date Syntax Type Examples Table 76: Time/Timestamp Precision ODBC Driver for Teradata User Guide 17

18 List of Tables 18 ODBC Driver for Teradata User Guide

19 CHAPTER 1 Product Overview This user guide contains information for the Microsoft Windows, Linux, and UNIX versions of the ODBC Driver for Teradata. Unless a paragraph or section is specifically marked as (Microsoft Windows only) or (UNIX/Linux only), the information contained in the paragraph or section pertains to the drivers for all operating systems supported. This chapter provides general information about Open Database Connectivity (ODBC) compliance levels and the Microsoft ODBC release version implemented by the driver. It also discusses the network interfaces that the ODBC Driver for Teradata supports, and the hardware and software requirements for using the ODBC Driver for Teradata. This chapter is divided into the following sections: Section ODBC Driver for Teradata Microsoft Windows Hardware and Software Requirements UNIX Hardware and Software Requirements Description Description and purpose of the ODBC Driver for Teradata Hardware and software requirements for using the Microsoft Windows version of the ODBC Driver for Teradata Hardware and software requirements for using the UNIX version of the ODBC Driver for Teradata ODBC Driver for Teradata Background ODBC standards have been developed through the efforts of an industry consortium called the SQL-Access Group (SAG) consisting of vendors such as Teradata, Hewlett-Packard, Ingres, Oracle, Informix, Sybase, Microsoft, and Novell. These standards define common database access mechanisms to simplify the exchange of data between client and server. Use ODBC drivers to connect applications with databases. This book describes how to use the ODBC Driver for Teradata to interface with the Teradata Database. The ODBC Driver for Teradata conforms to standard ODBC 3.51 Core-Level specifications. ODBC Driver for Teradata User Guide 19

20 Chapter 1: Product Overview ODBC Driver for Teradata New Features The ODBC Driver for Teradata Version includes: ODBC support for SQLDescribeParam Support for Teradata Database features: Improved metadata for parameters and result sets Retrieval of auto-generated keys from an Insert statement Stored procedure dynamic result sets Unicode Data Dictionary 4.0/4.1 Multi-level partitioned primary index Table function dynamic results Mini-batch: INSERT-SELECT and MERGE-INTO error logging syntax Support for the following platforms is included in asynchronous releases since the last edition of this user guide: 64-bit ODBC Driver for Microsoft Windows XP and Microsoft Windows 2003 (64-bit EM64T) 32-bit ODBC Driver for Teradata on Sun Solaris 10 Opteron 64-bit ODBC Driver for Teradata on Sun Solaris 10 Opteron Support for Solaris 10 zones 32-bit ODBC Driver for Microsoft Windows Vista Enterprise (32-bit and 64-bit) 64-bit ODBC Driver for Microsoft Windows Vista Enterprise (64-bit) Certification To find out on which platforms a given product is available and the compatible Teradata Database versions, refer to Teradata Tools and Utilities Supported and Certified Versions, B K. This spreadsheet shows version numbers and platform information for all Teradata Tools and Utilities release products and is available at Determining the Current Version of the ODBC Driver for Teradata Microsoft Windows To determine the currently installed version of the ODBC Driver for Teradata on Microsoft Windows, select Start->Control Panel->Add or Remove Programs and verify the driver version number. UNIX and Linux To determine the currently installed version of the ODBC Driver for Teradata on UNIX and Linux, use one of the following commands. On MP-RAS and Sun Solaris: pkginfo -l tdodbc 20 ODBC Driver for Teradata User Guide

21 Chapter 1: Product Overview Microsoft Windows Hardware and Software Requirements On IBM AIX: lslpp -l tdodbc On HP-UX: swlist tdodbc On Red Hat Linux: rpm - q <rpmname> On SUSE Linux: rpm -ql <rpmname> Microsoft Windows Hardware and Software Requirements Hardware Table 1 lists the disk space requirements for the available hardware platforms and Table 2 lists the Microsoft Windows operating system configurations. The minimum configuration required for the ODBC Driver for Teradata is an i386 -based PC (a 486-based PC, or higher is recommended): Table 1: Disk Space Requirements Component Disk space for the ODBC Driver for Teradata installation Additional disk space for the ODBC Driver for Teradata if Microsoft Data Access Components (MDAC) is installed Note: MDAC should not be installed on Microsoft Windows XP, Microsoft Windows Server 2003, or Microsoft Windows Vista Enterprise. Temporary disk space for ODBC Driver for Teradata installation Disk Space Required 1.2 MB 4.2 MB 11 MB Software The ODBC Driver for Teradata Release for Microsoft Windows is available in a 32-bit version on Microsoft Windows 2000, Microsoft Windows 2003, Microsoft Windows XP, and Microsoft Windows Vista Enterprise. The 32-bit ODBC Driver for Teradata is supported on 32-bit hardware with Microsoft Windows 2000, Microsoft Windows 2003, Microsoft Windows XP, and Microsoft Windows Vista Enterprise. The 32-bit ODBC Driver for Teradata is supported on EM64T with Microsoft Windows 2003 (32-bit and 64-bit), Microsoft Windows XP (32-bit and 64-bit), and Microsoft Windows Vista Enterprise (32-bit and 64-bit). ODBC Driver for Teradata User Guide 21

22 Chapter 1: Product Overview UNIX Hardware and Software Requirements The ODBC Driver for Teradata Release for Microsoft Windows is available in a native 64-bit version on Microsoft Windows 2003, Microsoft Windows XP, and Microsoft Windows Vista Enterprise. The 64-bit version of ODBC Driver for Teradata is available with Windows systems running on EM64T hardware. Table 2: Software Requirements (Microsoft Windows) Client Operating System Microsoft Windows 2000 original and up to SP4 Microsoft Windows 2003 original and up to SP1 (32-bit and 64-bit) Microsoft Windows XP original and up to SP2 (32-bit and 64-bit) Microsoft Windows Vista Enterprise (32-bit and 64-bit) Software Teradata Generic Security Services and Shared ICU Libraries are a dependency The server systems must be running Teradata Database V2R6.0 or later On Microsoft Windows, the MDAC Version 2.8 SP1 must be installed, unless installing on Microsoft Windows XP or Microsoft Windows Server 2003, or Microsoft Windows Vista Enterprise. To use the ODBC Driver for Teradata to develop custom Microsoft Windows applications, see Chapter 4: ODBC Application Development. UNIX Hardware and Software Requirements Table 3 depicts the range of requirements for the available hardware platforms and UNIX operating system configurations. Table 3: Hardware and Software Requirements (UNIX) Manufacturer Operating System Model NCR MP-RAS xx, 35xx, 3600AP, 43xx, 47xx, 48xx, 51xx, 52xx 32-bit ODBC X 64-bit ODBC MP-RAS xx, 35xx, 3600AP, 43xx, 47xx, 48xx, 51xx, 52xx X IBM AIX Version 5.3 PowerPC X X AIX Version 5.2 PowerPC X X AIX Version 5.1 PowerPC X X 22 ODBC Driver for Teradata User Guide

23 Chapter 1: Product Overview UNIX Hardware and Software Requirements Table 3: Hardware and Software Requirements (UNIX) (continued) Manufacturer Operating System Model 32-bit ODBC 64-bit ODBC HP HP-UX (11.11) PA-RISC X HP-UX (11.23) Itanium X HP-UX (11.31) Itanium X Sun Solaris SPARC Version 10 Solaris SPARC Version 9 Solaris SPARC Version 8 SPARC X X SPARC X X SPARC X X Solaris Version 10 Opteron X X Red Hat Red Hat Linux Advanced Server 4.0 (32-bit) Red Hat Linux Advanced Server 4.0 (64-bit) i386, EM64T X EM64T, Opteron X X Red Hat Linux Advanced Server 3.0 Red Hat Linux Advanced Server 2.1 i386 i386 X X Novell Novell SUSE Linux Enterprise 10.0 (32-bit) Novell SUSE Linux Enterprise 10.0 (64-bit) Novell SUSE Linux Enterprise 9.0 (32-bit) Novell SUSE Linux Enterprise 9.0 (64-bit) i386, EM64T X EM64T, Opteron X X i386, EM64T X EM64T, Opteron X X Software The following statements concern software: The server systems must be running Teradata Database V2R6.0 or later Teradata Generic Security Services and Shared ICU Libraries are a dependency On UNIX, the Data Direct ODBC Software Development Kit (SDK) is redistributed with the ODBC Driver for Teradata. The SDK contains libraries, header files, and samples. ODBC Driver for Teradata User Guide 23

24 Chapter 1: Product Overview UNIX Hardware and Software Requirements If you plan to use the ODBC Driver for Teradata to develop custom UNIX applications, see Chapter 4: ODBC Application Development. 24 ODBC Driver for Teradata User Guide

25 CHAPTER 2 ODBC Driver for Teradata Configuration for UNIX This chapter provides information on data sources and variables used with the UNIX version of the ODBC Driver for Teradata and how to configure the driver using the.odbc.ini file. For information on the Windows version of the ODBC Driver for Teradata, see Chapter 3: ODBC Driver for Teradata Configuration for Microsoft Windows. This chapter is divided into the following sections: Section ODBC Directories Configuring the UNIX and Linux Environment Additional Environment Variables The.odbc.ini File UNIX Compilation Options ODBC Options Section ODBC Data Sources Section Data Source Specification Section DSN Tracing Default Data Source Specification Section Adding a Data Source File Options Contents Application sub-directories, checks for TCP/IP connections, and the use of UNIX manual pages Variables that must be set for certain sub-functions such as libraries usage and to enable Kanji support features Additional optional environment variables Format of the.odbc.ini file and the options that can be inserted into each section in the file Compilation options for UNIX platforms ODBC Driver for Teradata installation directory and options for Driver Manager tracing Data Source Name (DSN) and ODBC Driver for Teradata name Path for the ODBC Driver for Teradata and the attributes that describe the DBCName, IP addresses, usernames, and passwords Options that control DSN tracing Default data source Formatting and definition of the various specifications, attributes, and options used.odbc.ini file options ODBC Driver for Teradata User Guide 25

26 Chapter 2: ODBC Driver for Teradata Configuration for UNIX ODBC Directories ODBC Directories After installation, the directories listed in Table 4 can be found under the ODBC installation directory. If not specified during the installation, the default installation directory is /usr/odbc on platforms other than Solaris SPARC and Opteron. If not specified during the installation, there are three default directories per installation from Solaris SPARC and Opteron platforms: Default 1: /opt/teradata/client/odbc Default 2: /opt/teradata/client/lib (32-bit Solaris SPARC) /opt/teradata/client/lib/64 (64-bit Solaris SPARC) /opt/teradata/client/lib/amd64 (64-bit Solaris Opteron) Default 3: /usr/share/man Table 4: ODBC Directories Directory include/ lib/ drivers/ messages/ samples/ /usr/lib/odbc Contents ODBC include files ODBC Driver Manager and other shared libraries Libraries for the ODBC Driver for Teradata Error message files Sample C and C++ applications Message catalog file Verification of the TCP/IP Connection Verify that the client system can connect over TCP/IP to the server using a domain name server (DNS) or through a local hosts file. The local hosts file contains the names and IP addresses of system nodes that support the Teradata network communication interface. Note: The adhoc program in the <InstallDir>/samples/C or <InstallDir>/samples/C++ directory can be used to verify the connection. Displaying the tdata man Page Included with the UNIX version of the ODBC Driver for Teradata package is a manual page called tdata. This man page provides useful general reference information. Access this page in the normal way by entering the command at the UNIX shell prompt, as follows: 26 ODBC Driver for Teradata User Guide

27 Chapter 2: ODBC Driver for Teradata Configuration for UNIX Configuring the UNIX and Linux Environment man tdata MANPATH environment variable needs to be set if man pages are placed in a location other than the system default. NLSPATH environment variable needs to be set since the odbc.cat file is no longer guaranteed to be in the /usr/lib/odbc directory. Configuring the UNIX and Linux Environment One of the following system-dependent environment variables must be set to the location of the ODBC Driver for Teradata libraries before using the UNIX or Linux version of the ODBC Driver for Teradata. Table 5 shows the environment variables and the operating systems in which they are used. Table 5: System-Dependent Environment Variables Variable Name SHLIB_PATH LD_LIBRARY_PATH LIBPATH Operating System HP-UX PA RISC MP-RAS, Linux, Sun Solaris, and 64-bit HP-UX Itanium IBM AIX Setting SHLIB_PATH If the ODBC Driver for Teradata is installed on an HP-UX PA RISC operating system in: /usr/odbc then set SHLIB_PATH to: /usr/odbc/lib:/usr/odbc/drivers Setting LD_LIBRARY_PATH If the ODBC Driver for Teradata is installed on an MP-RAS, Linux, or HP_UX Itanium in: /usr/odbc then set LD_LIBRARY_PATH to: /usr/odbc/lib:/usr/odbc/drivers If the ODBC Driver for Teradata is installed on a Sun Solaris system, then the LD_LIBRARY_PATH needs to be set to the user-entered input. The following example represents the default input: /opt/teradata/client/odbc /opt/teradata/client/lib /opt/teradata/client/lib/64 /opt/teradata/client/lib/amd64 ODBC Driver for Teradata User Guide 27

28 Chapter 2: ODBC Driver for Teradata Configuration for UNIX Additional Environment Variables then set LD_LIBRARY_PATH to: /opt/teradata/client/odbc/drivers: /opt/teradata/client/odbc/lib: /opt/teradata/client/lib:/opt/tdicu/ Note: The tdicu package also supports Solaris Zones and a user can select a different install directory for the tdicu product. Therefore, the /opt/tdicu path may not be absolute. Setting LIBPATH The LIBPATH needs to point to the TeraGSS library installation and to the ODBC driver installation: /usr/teragss/aix-power.32/client/lib If the ODBC Driver for Teradata is installed on an IBM AIX operating system in: /usr/odbc then set LIBPATH to: /usr/teragss/aix-power.32/client/lib:/usr/odbc/drivers Note: If using a 64-bit system, remove the.32 from the path. Additional Environment Variables Table 6 lists two additional optional environment variables that might need to be set. Table 6: Optional Environment Variables Variable Name ODBCINI LANG Function Specifies a different pathname for the.odbc.ini file Enables a supported character set to work with the ODBC Driver for Teradata Setting ODBCINI The installation directory where the ODBC Driver for Teradata software is installed contains an odbc.ini file. Copy this file into your home directory and rename it (with a leading dot) to odbc.ini before using the driver. Although the system expects the.odbc.ini file to be in your home directory, the ODBCINI environment variable may be used to specify a different pathname of the.odbc.ini file. The.odbc.ini file is a hidden file. The following expression is an example of the command for copying the.ini file: cp /usr/odbc/odbc.ini $HOME/.odbc.ini ODBCINI is an optional environment variable on any of the UNIX operating systems. The variable allows the use of an alternate.odbc.ini file. When specifying an alternate filepath, the full path must be used. 28 ODBC Driver for Teradata User Guide

29 Chapter 2: ODBC Driver for Teradata Configuration for UNIX The.odbc.ini File Setting LANG In the Korn shell: ODBCINI=filepath; export ODBCINI Or, in the C shell: setenv ODBCINI filepath where filepath is the filename of the odbc.ini file. For example: /usr/odbc/odbc.ini To enable Kanji, Chinese, or Korean support with the ODBC Driver for Teradata, the LANG environment variable must be set to the appropriate character setting. For example, on MP-RAS, set LANG=japan. In the Korn shell, LANG=japan; export LANG Or, in the C shell, setenv LANG japan For additional information on international language support, see International Character Set Support on page 158. The.odbc.ini File What are Data Sources? The.odbc.ini file contains the names and descriptions of the Data Sources available to the UNIX user. UNIX users must edit this file to add, delete, or change ODBC Data Sources. Through a DSN, the ODBC Driver for Teradata maps a logical name to the necessary software components and any additional information required for accessing data in a Database Management System (DBMS). The end user chooses the DSN. Ensure that the DSN is a name that reflects the type of data or system it represents..odbc.ini Table 7 lists the sections that make up the.odbc.ini file: Table 7:.odbc.ini Sections Section ODBC Options [ODBC] Description Specifies the ODBC Driver for Teradata installation directory and ODBC Driver for Teradata options ODBC Driver for Teradata User Guide 29

30 Chapter 2: ODBC Driver for Teradata Configuration for UNIX The.odbc.ini File Table 7:.odbc.ini Sections (continued) Section ODBC Data Sources [ODBC Data Sources] Data Source Specification [<data source>] Default Data Source Specification [default] Description Lists the name of each data source and describes its associated driver Provides a corresponding entry for each data source listed in the ODBC Data Sources section, containing additional details about that data source [Optional] Specifies the default data source to use when an application does not specify a data source at connect time Example of an.odbc.ini File The following is an example of a typical.odbc.ini file: [ODBC] InstallDir=/usr/odbc Trace=0 TraceDll=/usr/odbc/lib/odbctrac.so TraceFile=/usr/odbcusr/joe/trace.log TraceAutoStop=1 [ODBC Data Sources] financial=tdata.so dual_db=tdata.so [financial] Driver=/usr/odbc/drivers/tdata.so Description=NCR 5500 running Teradata DBCName= DBCName2= DBCName3= Username=odbcadm Password= Database= DefaultDatabase=sales [dual_db] Driver=/usr/odbc/drivers/tdata.so Description=NCR 5500 running Teradata DBCName= DBCName2= Username=dualdb Password= DefaultDatabase=dualdb MaxRespSize=32000 [default] Driver=/usr/odbc/drivers/tdata.so Description=Default DSN is Teradata 5100 DBCName= DBCName2= Username=dualdb Password= Database= DefaultDatabase=dualdb AccountString=dbc 30 ODBC Driver for Teradata User Guide

31 Chapter 2: ODBC Driver for Teradata Configuration for UNIX UNIX Compilation Options UNIX Compilation Options The standard ODBC installation directory that the Driver Manager provides must be used when developing ODBC applications on UNIX. These files are located in: <InstallDir>/include The ODBC Driver for Teradata includes the Data Direct Driver Manager, Version 5.2. The inclusion of this version of the Driver Manager requires some changes to compilation options for your applications. As an example, look at: <InstallDir>/samples/C/Makefile or <InstallDir>/samples/C++/Makefile and corresponding platform.include files for the compilation options used for each UNIX platform. If compiling for C++ applications on any UNIX platform that uses the ODBC Driver for Teradata, use the following compile time options: -DODBCVER=0x0352 If compiling for C applications on an IBM AIX platform, use the following compile time options: -DODBCVER=0x0352 -qlanglvl=extended ODBC Options Section The ODBC Options section [ODBC] specifies the ODBC installation directory and indicates whether Driver Manager tracing is enabled or disabled. When tracing is enabled, all ODBC function calls made from an application can be logged to a specified trace file. This section format is: [ODBC] InstallDir=<filepath> trace-keyword=<attribute> Note: This section of the.odbc.ini file is required so the Driver Manager can find the message files. The Driver Manager also uses this section to load the Cursor Library and the Connection Dialog Library. At a minimum, the [ODBC] section must contain the InstallDir keyword with the value set to the path in which the ODBC SDK is installed. Table 8 lists the ODBC Options Section keywords. ODBC Driver for Teradata User Guide 31

32 Chapter 2: ODBC Driver for Teradata Configuration for UNIX ODBC Options Section Table 8: ODBC Options Section Keywords Keyword InstallDir=<filepath> Description Enter the directory where the ODBC Driver for Teradata was installed. The default directory, if not specified during installation, is /usr/odbc A common error encountered while running an application is the inability to load the ODBC Driver for Teradata. The cause is usually that the exact location of the ODBC Driver for Teradata was not specified in the.odbc.ini file. The.odbc.ini file must reference the exact location of the ODBC Driver for Teradata to be used. Trace=[0] or [1] Default = 0 When Trace is 0 Driver Manager tracing is disabled When Trace is 1 Driver Manager tracing is enabled TraceDll=<tracedll pathname> TraceFile=<filepath> Default = <InstallDir>/lib/odbctrac.so (on MP-RAS, IBM AIX, and Sun Solaris) Default =<InstallDir>/lib/odbctrac.sl (on HP-UX PA RISC) Enter the complete pathname of the trace DLL. The DLL is located in the Driver Manager library. Enter the complete pathname of the file where trace information will be logged TraceAutoStop=[0] or [1] Default = 0 When TraceAutoStop is 0 tracing is not disabled when SQLFreehandle for ENV is called When TraceAutoStop is 1 tracing is disabled when SQLFreehandle for ENV is called Example of the ODBC Options Section The following is an example of how to enable tracing in the ODBC Driver for Teradata Options section of the.odbc.ini file on MP-RAS, IBM AIX, and Sun Solaris: [ODBC] InstallDir=/usr/odbc Trace=1 TraceDll=/usr/odbc/lib/odbctrac.so TraceFile=/usr/odbcusr/joe/trace.log TraceAutoStop=1 The following is an example of how to enable tracing in the ODBC Driver for Teradata Options section of the.odbc.ini file on HP-UX PA-RISC: [ODBC] InstallDir=/usr/odbc Trace=1 TraceDll=/usr/odbc/lib/odbctrac.sl 32 ODBC Driver for Teradata User Guide

33 Chapter 2: ODBC Driver for Teradata Configuration for UNIX ODBC Data Sources Section TraceFile=/usr/odbcusr/joe/trace.log TraceAutoStop=1 ODBC Data Sources Section Each entry in the ODBC Data Source sections [ODBC Data Sources] of the.odbc.ini file lists a DSN and the associated ODBC Driver for Teradata. Table 9 lists the ODBC Data Sources section keywords. The section format is: [ODBC Data Sources] data-source-name=<driver> Table 9: ODBC Data Sources Section Keywords Keyword data-source-name=<driver> Description Enter the name of the ODBC Driver for Teradata into the.odbc.ini file [ODBC Data Sources] section. This is a required keyword. The driver file extensions for MP-RAS, Sun Solaris, IBM AIX, Linux, and HP-UX are different for shared object libraries. For MP-RAS, Sun Solaris, Linux, and IBM AIX, the.so extension is used; for HP-UX PA RISC, the.sl extension is used. [Optional] Configure multiple data sources for the same system so that different default databases or keywords can be associated with each data source. Example ODBC Data Sources Section on MP-RAS, Sun Solaris, Linux, and IBM AIX The following is an example of the ODBC Data Sources section on an MP-RAS, Sun Solaris, or IBM AIX UNIX operating system. Notice the.so file extension for the ODBC Driver for Teradata. [ODBC Data Sources] Inventory=tdata.so Example ODBC Data Sources Section on HP-UX PA RISC The following is an example of the ODBC Data Sources section on an HP-UX PA RISC UNIX operating system. Notice the.sl file extension for the ODBC Driver for Teradata. The HP-UX IA64 has an.so extension. [ODBC Data Sources] Inventory=tdata.sl ODBC Driver for Teradata User Guide 33

34 Chapter 2: ODBC Driver for Teradata Configuration for UNIX Data Source Specification Section Data Source Specification Section Each data source listed in the ODBC Data Sources section, [<data-source-name>], of the.odbc.ini file includes its own data source specification section. This section has the following format: [<data-source-name>] Driver=<driver-path> Keyword=<attribute> The lines following the data source name define the required and optional attributes. Table 10 contains the available options that can be entered into the Data Source Specification section. Table 10: Data Source Specification Section Keywords Keyword Driver=<driver-path> Description=<data-source-desc> DBCName=<IP-addr-or-alias> DBCName2=<IP-addr-or-alias> DBCNamen=<IP-addr-or-alias> Username=<name> Password=<password> Database=<database-name> Description [Required] entry, provides the full path to the ODBC Driver for Teradata shared object (tdata.so on MP-RAS, Sun Solaris, Linux, and IBM AIX; tdata.sl on HP-UX PA RISC). [Optional] entry, provides descriptive text about the data source [Required] entry (DBCName), provides an IP address of the Teradata server or its alias When an alias name is specified, it is resolved at connect time. DBCNames are constrained by a maximum of 1024 nodes and a buffer size of 30,002 bytes. The number of DBCNames equals 30,002 bytes, divided by the length of the DBCName. Additional DBCNames can be specified. [Optional] entry, provides a default username for logon to a Teradata server system [Optional] entry, provides the password required for the default Username Caution: [Optional] entry Not currently used There is no password security in the file. The password is retained in un-encrypted plain text and can be viewed by any user with read-access to the file 34 ODBC Driver for Teradata User Guide

35 Chapter 2: ODBC Driver for Teradata Configuration for UNIX DSN Tracing Table 10: Data Source Specification Section Keywords (continued) Keyword DefaultDatabase=<database-name> Description Default=none When none, the database is the user name. [Optional] entry, provides the name of the default database associated with this data source. The entry may be overridden when specifying a new connection. All catalog functions assume the default database if a table owner is not specified. Example of a Data Source Specification Section The following is an example showing option entries in the Data Source Specification section named [financial]: [financial] Driver=/usr/odbc/drivers/tdata.so Description=NCR 5500 running Teradata DBCName= DBCName2= DBCName3= Username=odbcadm Password= Database= DefaultDatabase=sales DSN Tracing To control tracing for a DSN, the.odbc.ini file might contain the additional entries listed in Table 11 within a Data Source Specification or Default Data Source Specification section. Table 11: Data Source Name Tracing Keyword DSNTraceEnable=[Yes No] DSNTraceFileFlushThreshold= <size> Description Default = No When DSNTraceEnable is Yes this option turns on tracing for the DSN When DSNTraceEnable is No, or if the DSNTraceEnable entry is missing tracing is not activated for any connection using the DSN Default= (2,000,000,000 bytes) When the size of ODBC.Trace.xxxxx reaches the DSNTraceFileFlushThreshold, the contents of the file are deleted ODBC Driver for Teradata User Guide 35

36 Chapter 2: ODBC Driver for Teradata Configuration for UNIX DSN Tracing Table 11: Data Source Name Tracing (continued) Keyword DSNTraceFilePath=<path> DSNTraceFileMaxSize=<size> DSNTraceOverwrite=[Yes No] DSNTraceLineNumbers=[Yes No] Description Default = /tmp/odbc.trace.xxxxx Enter the relative or absolute pathname, path, of the trace file. If this entry is missing, a default pathname of /tmp/ ODBC.Trace.xxxxx is used, where xxxxx is the pid of the creating process. Default = (1,000,000 bytes) This option specifies the maximum size in bytes, size, allowed for the trace file. If this entry is missing, a default size of 1,000,000 bytes is assumed. Size must be between 10,000 and 1,000,000,000. Default = No When DSNTraceOverwrite is Yes the trace file is overwritten when it is first opened. The file is effectively deleted and opened as a new file. When DSNTraceOverwrite is No the trace is started, and the trace file is opened for append mode Default = Yes When DSNTraceLineNumbers is Yes the filename and line number is appended to each trace entry When DSNTraceLineNumbers is No produces a trace file without the filenames and line numbers Example of DSN Tracing Important: Using any of the tracing options can significantly degrade performance. The following is an example of a Data Source Specification Section with DSN tracing entries included: [financial] Driver=/usr/odbc/drivers/tdata.so Description=NCR 5500 running Teradata DBCName= DBCName2= DBCName3= Username=odbcadm Password= Database= DefaultDatabase=sales DSNTraceEnable=YES DSNTraceFilePath=/tmp/ODBC.Trace.log DSNTraceFileMaxSize= DSNTraceOverwrite=NO DSNTraceLineNumbers=YES 36 ODBC Driver for Teradata User Guide

37 Chapter 2: ODBC Driver for Teradata Configuration for UNIX Default Data Source Specification Section Default Data Source Specification Section The.odbc.ini file optionally contains a default data source specification section. The data source must be named [default] and is not listed in the ODBC Data Sources section. The structure and options entered into default data source specification section are the same as those entered into the Data Source Specification section. See the Data Source Specification Section for a list of options that can be entered in the Default Data Source Specification section. At connect time, if an application specifies a DSN that is not in the.odbc.ini file, or if the application does not specify a DSN, the ODBC Driver Manager looks for the default DSN in the.odbc.ini file, and uses that DSN for connection. Example of the Default Data Source Specification Section The following is an example of a Default Data Source section: [default] Driver=/usr/odbc/drivers/tdata.so Description=Default DSN is Teradata 5100 DBCName= DBCName2= Username=dualdb Password= Database= DefaultDatabase=dualdb AccountString=dbc Adding a Data Source To configure a data source When adding or configuring a data source, the.odbc.ini file must be edited using a text editor. Each Data Source listed in the ODBC Data Sources Section has its own Data Source Specification section. The examples provided here display the file extension convention for MP-RAS, Sun Solaris, Linux, and IBM AIX (.so). Remember that the file extension for HP-UX PA RISC is.sl. 1 Open the.odbc.ini file using a text editor 2 Add an entry for the new data source and its corresponding driver in the [ODBC Data Sources] section Example: In this example, the data source called [financial] is associated with the ODBC Driver for Teradata for UNIX called tdata.so: financial=tdata.so ODBC Driver for Teradata User Guide 37

38 Chapter 2: ODBC Driver for Teradata Configuration for UNIX File Options 3 Add a descriptive entry for each data source listed in the [ODBC Data Sources] section after the [ODBC Data Sources] section. This is called a Data Source Specification. Example: In this example, a Data Source Specification section called [financial] is added to the.odbc.ini file. The location of the ODBC Driver for Teradata is specified and a description of the driver is added. Other options might also be added: [financial] Driver=/usr/odbc/drivers/tdata.so Description=NCR 5500 running Teradata Include additional options in the section File Options The following keyword options may be added to the Data Source Specification and Default Data Source Specification sections of the.odbc.ini file. The options can only be configured through the.odbc.ini file. The options presented in Table 12 are in alphabetical order, although this is not a requirement in the.odbc.ini file. Table 12: Options Configurable in the.odbc.ini File Keyword AccountString=<account> AppCatalogDB=<database name> Description Default = None The AccountString information is used during the creation of a user in Teradata Database, instead of providing account information during configuration of ODBC. AccountString also helps to isolate users, to determine what application users are running, or to restrict users from logging on. Default = None This option is provided for applications, such as PowerBuilder, that require a database for their system catalog tables. If a database name is specified for AppCatalogDB, and SQLTables is called with null parameters, SQLTables will include this database in its search of tables, along with the default tables. 38 ODBC Driver for Teradata User Guide

39 Chapter 2: ODBC Driver for Teradata Configuration for UNIX File Options Table 12: Options Configurable in the.odbc.ini File (continued) Keyword CharacterSet=<charset name> DateTimeFormat=[[I A] [I A][I A]] Description Enter the charset name to override the Teradata character set. Do not change the default character set unless instructed to do so by Technical Support. charset name The character set name could be a userdefined character set or one of the following defined by Teradata: ASCII UTF8 UTF16 LATIN1252_0A LATIN9_0A LATIN1_0A KANJISJIS_0S KANJIEUC_0U TCHBIG5_1R0 SCHGB2312_1T0 HANGULKSC5601_2R4 Note: These character sets have to be installed on the database. See International Character Set Support. Default = III This option determines whether to use ANSI format or Integer format for DATE, TIME, and TIMESTAMP data types. When a DateTimeFormat value is set to an A the format used is ANSI When a DateTimeFormat value is set to an I the format used is Integer The format is a three-character combination. Each character can be either A or I, where: A = ANSI I = Integer The three-character combination represents: First character = DATE format Second character = TIME format Third character = TIMESTAMP format The default action is to use the integer DATEs, TIMEs, or TIMESTAMPs. To use ANSI DATEs, TIMEs, or TIMESTAMPs instead, specify the appropriate value through the setup. Note: The last character representing TIMESTAMP data type has no significance. It is always equivalent to A. ODBC Driver for Teradata User Guide 39

40 Chapter 2: ODBC Driver for Teradata Configuration for UNIX File Options Table 12: Options Configurable in the.odbc.ini File (continued) Keyword Disable CALLToEXECConversion=[Yes No] DisableAsync=[Yes No] Description Default = Yes This option implements the CALL statement with an escape clause, {CALL <name>(..)}. When DisableCALLToEXECConversion is No the ODBC Driver for Teradata considers the {CALL <name>(..)} statement as the SQL for MACRO execution, and converts the above statement to an EXEC <name>(..). When DisableCALLToEXECConversion is Yes the ODBC Driver for Teradata does not convert {CALL <name>(..)} statements to EXEC, and considers the statements as CALL statements for Stored Procedure Execution. Parsing the SQL is mandatory for this CALL statement with escape clauses to work. On Windows, do not select the Disable Parsing option. On UNIX, do not select the NoScan option. Default = No This option determines whether the ODBC Driver for Teradata operates in synchronous or asynchronous mode. When DisableAsync is Yes the ODBC Driver for Teradata ignores any attempt to enable asynchronous mode by setting SQL_ATTR_ASYNC_ENABLE to SQL_ASYNC_ENABLE_OFF. The driver then ignores the values passed. When DisableAsync is No the ODBC Driver for Teradata operates synchronously; that is, the driver does not return control to the application until a function call completes by setting SQL_ATTR_ASYNC_ENABLE to SQL_ASYNC_ENABLE_ON. Although tracing is easier, there is a wait for host responses to queries or commands. In asynchronous mode, control is returned to the application before the function call completes. The driver mode can be set to asynchronous through SQLSetStmtOption() or SQLSetConnectionOption(). 40 ODBC Driver for Teradata User Guide

41 Chapter 2: ODBC Driver for Teradata Configuration for UNIX File Options Table 12: Options Configurable in the.odbc.ini File (continued) Keyword DisablePREPARE=[Yes No] DontUseHelpDatabase=[Yes No] DontUseTitles=[Yes No] Description Default = No When DisablePREPARE is Yes this option reduces processing time; however, the ODBC Driver for Teradata will not get complete column information from the Teradata Database for a result set returned from SQLExecDirect. The ODBC Driver for Teradata is therefore not able to provide Column Name information from SQLDescribeCol or SQLColAttribute, and DATE, TIME, and TIMESTAMP data might not be returned in the proper data type or format. When DisablePREPARE is No The ODBC Driver for Teradata instructs Teradata to prepare the statement and then execute. Default = No This option determines whether the Help Database is used. When DontUseHelpDatabase is Yes SQLTables() uses a SELECT statement instead of the HELP DATABASE command when no wildcard characters are used in SQLTables(). SQLTables() uses either dbc.tables or dbc.tablesx depending upon the UseXViews selection. When DontUseHelpDatabase is No The driver uses the HELP DATABASE command. Default = Yes This option determines whether the ODBC Driver for Teradata returns column names or column titles. When DontUseTitles is Yes the ODBC Driver for Teradata returns column names rather than column titles, as required by some applications, such as Crystal Reports. Column titles for SQLColumns() are shown in the LABEL column. When DontUseTitles is No the ODBC Driver for Teradata returns column titles, if titles are defined; otherwise, it returns column names. ODBC Driver for Teradata User Guide 41

42 Chapter 2: ODBC Driver for Teradata Configuration for UNIX File Options Table 12: Options Configurable in the.odbc.ini File (continued) Keyword EnableExtendedStmtInfo=[ Yes No ] EnableReconnect=[Yes No] IANAAppCodePage=<application code page> Description Default = Yes This option determines whether extended statement information is used or not used by the ODBC Driver for Teradata, provided that it is available from the database. Teradata Database versions from V2R6.2 and up support extended statement information. The extended statement information includes additional metadata information for parameters used in SQL requests and for columns in result sets. When EnableExtendedStmtInfo is Yes the ODBC Driver for Teradata requests and uses extended statement information from the database if the database supports it. If extended statement information is available, then the ODBC API function SQLDescribeParam is supported and SQLGetFunctions returns SQL_TRUE (supported) for SQL_API_SQLDESCRIBEPARAM. When EnableExtendedStmtInfo is No the ODBC Driver for Teradata does not request or use extended statement information from the database, even if the database supports it. If extended statement information is not available, then the ODBC 12.0 driver behaves as in previous releases: SQLDescribeParam is not supported and SQLGetFunctions returns SQL_FALSE (not supported) for SQL_API_SQLDESCRIBEPARAM. Default = No This option causes the ODBC Driver for Teradata to determine if sessions on Teradata are to be reconnected after a system crash or reset is detected. When EnableReconnect is Yes the ODBC Driver for Teradata attempts to reconnect the saved sessions; however, sessions cannot be reconnected until the Teradata system is available. After a session is reconnected, applications can expect to receive error messages describing why the ODBC function failed and a status report describing the post-recovery state. When EnableReconnect is No the ODBC Driver for Teradata does not attempt to reconnect the saved sessions On UNIX, the current application code page is defined as IANAAppCodePage. See Table 74 on page 166 for a list of IANAAppCodePage values and cautionary information. 42 ODBC Driver for Teradata User Guide

43 Chapter 2: ODBC Driver for Teradata Configuration for UNIX File Options Table 12: Options Configurable in the.odbc.ini File (continued) Keyword IgnoreODBCSearchPattern=[Yes No] IndexName[0-9]=<indexname (column identifiers) dbn.tablename> Description Default = No (except for Microsoft Access) Normally, the characters _ and % work like wildcard characters for the values given to table names, schema names, and so forth when passed to catalog functions such as SQL Tables. This option is useful for applications, such as Microsoft Access, that do not support search patterns. When IgnoreODBCSearchPattern is Yes the following commands cause the ODBC Driver for Teradata to treat the normal search pattern characters _ and % as regular characters: SQLTables SQLColumns SQLTablePrivileges SQLProcedures SQLProcedureColumns SQLGetInfo SQL_SEARCH_PATTERN_ESCAPE returns an empty string. When IgnoreODBCSearchPattern is No the data source section of the.odbc.ini file used by Microsoft Access, and the ODBC Driver for Teradata will again process search patterns. This is true for all applications except Microsoft Access. Default = None The ODBC Driver for Teradata creates this UNIX option to support user-defined ODBC-style named indexes. IndexName(s) are defined independently for each data source entry, and are only defined when the index is created. IndexName entries are generated when an application CREATEs a named index. IndexName entries are removed when a DROP INDEX command is issued that affects the named index or when a DROP TABLE command is issued that destroys the table where an index exists. IndexName entries are re-used on a first in/first out basis when all other entries have been used. indexname (column identifiers) indicates the index name, followed by name(s) of one or more table columns that might be used as an index dbn.tablename indicates the database.table where the index is used ODBC Driver for Teradata User Guide 43

44 Chapter 2: ODBC Driver for Teradata Configuration for UNIX File Options Table 12: Options Configurable in the.odbc.ini File (continued) Keyword Integrated Security=[Yes No] Description Default = No When Integrated Security is Yes enables the user to connect to the database through Single Sign On (SSO) using one of the authentication mechanisms that support SSO. When Integrated Security is No does not allow SSO. LoginTimeout=<integer 0> Default = 20 This option defines a value corresponding to the number of seconds to wait when establishing a virtual circuit with Teradata for login. Enter an integer value greater than or equal to 0. MaxRespSize=<integer > Default = 8192 The MaxRespSize value is used to limit the Teradata response buffer size for SQL requests. This value may be adjusted dynamically if Teradata cannot send a result within the limited packet size defined. The maximum integer value is If a slow TCP/IP interface is used, such as PPP or SLIP, enter a smaller value. If large result sets in a LAN environment are expected, set a larger value. MechanismName=<MechanismName> Default = determined by a configuration option that is set in an xml file by the TeraGSS program, tdgssconfigure Identifies the authentication mechanism used for connections to the data source. KRB5, KRB5C, NTLM, and NTLMC are for Windows only, and are not available on UNIX or Linux. Valid values are: Empty is the same as omitting the keyword. TD1 selects Teradata 1 as the Authentication Mechanism. Username and password are required. TD2 selects Teradata 2 as the Authentication Mechanism. Username and password are required. LDAP selects LDAP as the Authentication Mechanism. The application provides the username and password. See Chapter 5: Network Security for complete descriptions of Authentication Mechanisms. 44 ODBC Driver for Teradata User Guide

45 Chapter 2: ODBC Driver for Teradata Configuration for UNIX File Options Table 12: Options Configurable in the.odbc.ini File (continued) Keyword MechanismKey=<Value> NoScan=[ Yes No ] Order=[< >] OutputAsResultSet=[Yes No] Description Value = string A string of characters regarded as a parameter to the authentication mechanism. It is opaque for the ODBC Driver for Teradata and is passed on to the Teradata authentication software that is called to set the mechanism used. Default = No Use this option to enable or disable parsing of SQL statements by the ODBC Driver for Teradata. In Windows, this option is called DisableParsing. When NoScan is Yes the parser in the ODBC Driver for Teradata is bypassed and the SQL statement is sent directly to Teradata When the SQL statement contains ODBC-specific syntax, do not set this option. Setting this option while using ODBC-specific syntax in the SQL statement results in Teradata Database reporting errors. When NoScan is No the parser in the ODBC Driver for Teradata is not bypassed and SQL statements are sent to the parser Default = None The ODBC Driver for Teradata creates this UNIX option entry to support ODBC-style named indexes. The ODBC Driver for Teradata writes back to the.odbc.ini file with the SQLWritePrivateProfileString API. The entry indicates the order of creation for IndexName entries and determines which indexes are reused first when all IndexName entries have been exhausted. A maximum 10 index names are kept. Default = No The setting of this option determines how stored procedure output parameters are retrieved by the ODBC Driver for Teradata. When OutputAsResultSet is Yes the values of INOUT and OUT parameters are returned the same way as the result set. They need to be retrieved from the response by SQLFetch() or by an SQLBindCol() ODBC SDK API call followed SQLFetch(). When OutputAsResultSet is No the values of INOUT and OUT parameters are directly updated after the procedure call. Because of this, all parameter makers need to be bound to a variable before the procedure call. This is the default option. ODBC Driver for Teradata User Guide 45

46 Chapter 2: ODBC Driver for Teradata Configuration for UNIX File Options Table 12: Options Configurable in the.odbc.ini File (continued) Keyword PrintOption=[N P] Description Default = N This option specifies the PrintOption option when creating stored procedures. When PrintOption is N the Procedure is created with the no print option When PrintOption is P the print option is enabled ReconnectWait=<integer> Default = 10 This is a user-defined option that manages the display of reconnect messages during session recovery. A message box displays for the duration of the session recovery. The message box is removed automatically when a connection is re-established with the database. Otherwise, a user cannot cancel the session recovery effort. The EnableReconnect option must be set to Yes before the ReconnectWait option is valid. The range of values expected is 0,1,2,...,59,60. When ReconnectWait is 0 displays the reconnect message only once. Specify whether to continue with the session recovery or cancel the recovery. When ReconnectWait is an integer from 1 to 60 (1 <= n <= 60) it specifies the number of minutes the ODBC Driver for Teradata waits before re-displaying the reconnect message. This allows cancellation of a session recovery. retryoneintr Default=True/Yes (ON) This option allows the user to control whether the ODBC Driver for Teradata should retry the socket system calls on an EINTR or return an SQL_ERROR. The socket system calls affected are: connect() select() recv() send() 46 ODBC Driver for Teradata User Guide

47 Chapter 2: ODBC Driver for Teradata Configuration for UNIX File Options Table 12: Options Configurable in the.odbc.ini File (continued) Keyword ReturnGeneratedKeys=<value> RunInQuietMode=[Yes No] SessionMode=[Teradata ANSI ] Description Default = N Determines the result from requests that insert into identity columns (INSERT, INSERT-SELECT, UPSERT, MERGE-INTO). These requests may optionally return a result set containing identity column values (also known as auto-generated keys) for the inserted rows. Auto-generated key retrieval is not supported in Teradata Database versions prior to V2R6.2 and the setting of ReturnGeneratedKeys has no effect when using a pre- V2R6.2 database server. Valid values are N, C, and R: N = No auto-generated key retrieval (default) C = Retrieve identity column only R = Retrieve entire row(s) When ReturnGeneratedKeys is set to C or R, a request that inserts into tables containing identity columns returns two results: a row count with the number of inserted rows and a result set containing either the auto-generated keys as a single column (C) or the complete rows inserted (R). In other words, the insert request becomes similar to a macro that first inserts and then selects the identity column (C) or all columns (R) of the rows just inserted. When ReturnGeneratedKeys is set to N or is not set, the behavior of requests that insert into identity columns is not changed. Default = No When RunInQuietMode is Yes the ODBC Driver for Teradata does not display standard messages on the screen When RunInQuietMode is No the ODBC Driver for Teradata displays standard messages on the screen Default = System defined This option allows the user to select the mode (Teradata or ANSI) for sessions on a Teradata Database. The selected mode applies for the duration of the session. Note: An application cannot set SessionMode programatically. SessionMode may be set only while connecting. ODBC Driver for Teradata User Guide 47

48 Chapter 2: ODBC Driver for Teradata Configuration for UNIX File Options Table 12: Options Configurable in the.odbc.ini File (continued) Keyword SplOption=[Y N] SQLWithCommentsOrParenthesis=[Yes No] Description Default = Y This option specifies the SPL option when creating stored procedures. When SplOption is Y the Procedure is created with SPL text When SplOption is N the Procedure is created without SPL text Default = Yes When this option is Yes the ODBC Driver for Teradata prepares SQL statements enclosed in parenthesis or preceded by comments When this option is No these statements are prepared by Teradata prior to execution with SQLExecDirect 48 ODBC Driver for Teradata User Guide

49 Chapter 2: ODBC Driver for Teradata Configuration for UNIX File Options Table 12: Options Configurable in the.odbc.ini File (continued) Keyword Description StCheckLevel=[0 1 2] Default = 0 This user-defined option provides enhanced ODBC state checking that detects SQLState according to the requirements in the ODBC SDK. When StCheckLevel is 0 no check is made on cursor state when calling functions, backward compatibility is provided. The ODBC Driver for Teradata will not return SQL State when an ODBC function such as SQLExecute, SQLExecDirect, or an ODBC catalog function generates a result set and another function that generates a result set is called before the first results were fetched or freed. When StCheckLevel is 1 the application must not be in an open cursor state when calling a function that generates a result set The ODBC Driver for Teradata generates an SQL State error if an application is in an open cursor state and one of the following functions is called: SQLColumns, SQLColumnPrivileges, SQLExecDirect, SQLExecute, SQLTables, SQLForeignKeys, SQLPrimaryKeys, SQLGetTypeInfo, SQLPrepare, SQLProcedureColumns, SQLProcedures, SQLSpecialColumns, SQLStatistics, or SQLTablePrivileges. When StCheckLevel is 2 the application must not be in an open cursor state when calling a function that generates a result set, or when calling functions that require an open cursor state, the application must be in this state The ODBC Driver for Teradata generates an SQL State error if an application is not in an open cursor state and SQLColAttributes, SQLDescribeCol, or SQLFetch is called ODBC Driver for Teradata User Guide 49

50 Chapter 2: ODBC Driver for Teradata Configuration for UNIX File Options Table 12: Options Configurable in the.odbc.ini File (continued) Keyword TCPNoDelay=[Yes No] Translation DLL=<path> Translation Option=<option> Description Default = Yes This option is valid for the Teradata Data Source Entry in ODBC Driver for Teradata. Transmission Control Protocol (TCP) provides an option called TCP_NODELAY to control the transmission of data. When TCPNoDelay is Yes TCP sends small amounts of output immediately rather than gathering into a single packet. This avoids delays in packet transmission, but a larger number of small packets, including acknowledgements, may be sent over the network. When TCPNoDelay is No TCP may delay sending small packets so they can be gathered and sent as a single packet. This may reduce network traffic, but it may also delay packet transmission. Refer to the TCP documentation for complete information. By default the ODBC Driver for Teradata runs with the TCP option TCP_NODELAY enabled so TCP sends small amounts of output immediately. Use of the TCPNoDelay option in the ODBC Driver for Teradata allows users to specify whether TCP is to send small packets immediately or gather packets. This option specifies the translation DLL path. Translation DLL is used to convert between Unicode and the session character set. User-defined session character sets may be used without a translation DLL. The conversion is based on the current application code page. See Session Character Sets and Translation DLLs on page 53. This option specifies the translation DLL option. The option is used by translation DLL. See Session Character Sets and Translation DLLs on page 53. TDMSTPortNumber=<integer> Default = 1025 This option is the port number to use to access the Teradata Database. Enter the port number the ODBC Driver for Teradata is to use to access the Teradata Database. Always use the default of 1025, and do not change this value unless you are instructed to do so by technical support. 50 ODBC Driver for Teradata User Guide

51 Chapter 2: ODBC Driver for Teradata Configuration for UNIX File Options Table 12: Options Configurable in the.odbc.ini File (continued) Keyword USE2XAPPCUSTOMCATALOGMODE =[Yes No] UseDataEncryption=[Yes No] UseNativeLOBSupport=[Yes No] Description Default = No When USE2XAPPCUSTOMCATALOGMODE is Yes this option provides backwards compatibility for ODBC 2.x Applications that have taken advantage of a defect in the ODBC Driver where the functionality of the Catalog APIs are noncompliant with the ODBC Programmers Reference Specification. The behavior when a NULL value is passed to the SQLTables API for the SchemaName argument results in a search for tables belonging to the userid, DBC, and default database schema names, rather than a % search pattern as per the ODBC Programmers Reference Specification. Default = No When UseDataEncryption is Yes the ODBC Driver for Teradata encrypts data and thus the Teradata gateway and ODBC Driver for Teradata communicate with each other in encrypted manner When UseDataEncryption is No the ODBC Driver for Teradata does not encrypt data, except for logon information Default = No The setting of this option impacts data type mapping that takes place internally in the ODBC driver. When UseNativeLOBSupport is Yes this option enforces native Large Object (LOB) data type mapping. This mapping is the default mapping if the Teradata Database has LOB support: ODBC data type SQL_LONGVARBINARY is mapped to the Teradata Binary Large Object (BLOB) feature ODBC data type SQL_LONGVARCHAR is mapped to the Teradata Character Large Object (CLOB) feature When UseNativeLOBSupport is No this option retains backward compatibility. It is intended for use by applications without LOB support that are using a version of Teradata Database without LOB support: ODBC data type SQL_LONGVARBINARY is mapped to the Teradata VARBYTE(32000) feature ODBC data type SQL_LONGVARCHAR is mapped to the Teradata LONG VARCHAR feature See The Native LOB Support Option on page 112. ODBC Driver for Teradata User Guide 51

52 Chapter 2: ODBC Driver for Teradata Configuration for UNIX File Options Table 12: Options Configurable in the.odbc.ini File (continued) Keyword UseXViews=[Yes No] Description Default = No When UseXViews is Yes SQLTables() and SQLProcedures() use dbc.tablesvx and dbc.databasesvx instead of dbc.tablesv and dbc.databasesv. Also, SQLColumns() and SQLProcedureColumns() use dbc.columnsvx instead of dbc.columnsv. SqlStatistics() uses dbc.tablesizevx instead of dbc.tablesizev. The X tables only contain information that the user has permission to access. These tables are optional for Teradata, so check to ensure they exist. When UseXViews is No SQLTables() and SQLProcedures() use dbc.tablesv and dbc.databasesv. Also, SQLColumns() and SQLProcedureColumns() use dbc.columnsv. SqlStatistics() uses dbc.tablesizev. Note: If using a version of Teradata Database earlier than 12.0, the above information will vary. The UNIX version of the ODBC Driver for Teradata recognizes the following options when the LANG environment variable contains a value recognized by the ODBC Driver for Teradata for Japanese, Chinese, or Korean locales. ClientKanjiFormat={SJIS EUC Big5 Network Korean GB} DisplayKanjiConversionErrors= [Yes No] Default = Set by User Specifies to the ODBC Driver for Teradata which character set to use for the user's choice of character set format: SJIS EUC Big5 Network Korean GB The data returned to the user will be translated from the KanjiFormat to the ClientKanjiFormat for SJIS and EUC only. For Big5, NetworkKorean, and GB, this value should match the KanjiFormat. Default = No Selecting a Kanji format other than SJIS causes the ODBC Driver for Teradata to convert between different Kanji formats. When the option is Yes if a character is encountered that is not included in SJIS, an error is generated When the option is No if a character is encountered that is not included in SJIS, no error is generated 52 ODBC Driver for Teradata User Guide

53 Chapter 2: ODBC Driver for Teradata Configuration for UNIX File Options Session Character Sets and Translation DLLs Starting with the ODBC Driver for Teradata Release , Teradata UTF8 and UTF16 session character sets on UNIX work with the Translation DLL that the Translation DLL=<option> keyword selects. Table 13 indicates the conversions performed by SQLDriverToDataSource. Table 14 indicates the conversions performed by SQLDataSourceToDriver. Table 13: Function of SQLDriverToDataSource Condition UTF16 session character set on UNIX Other session character set on UNIX Function of SQLDriverToDataSource Convert IANAAppCodePage to UTF16 Convert UTF8 to session character set Table 14: Function of the SQLDataSourceToDriver Condition UTF16 session character set on UNIX Other session character set on UNIX Function of SQLDriverToDataSource Convert UTF16 to IANAAppCodePage Convert session character set to UTF8 ODBC Driver for Teradata User Guide 53

54 Chapter 2: ODBC Driver for Teradata Configuration for UNIX File Options 54 ODBC Driver for Teradata User Guide

55 CHAPTER 3 ODBC Driver for Teradata Configuration for Microsoft Windows This chapter provides instructions for configuring the Microsoft Windows version of the ODBC Driver for Teradata. For information on the UNIX version of the ODBC Driver for Teradata, see Chapter 2: ODBC Driver for Teradata Configuration for UNIX. Microsoft Windows Options Configurable Through Setup All options for the Microsoft Windows version of the ODBC Driver for Teradata are configurable through the ODBC Driver Setup for Teradata Database dialog box. The chapter is divided into the following sections: Section "Configuring a Data Source" "Reconfiguring a Data Source" "Resolving a Data Source Alias Name" Contents How to configure data sources for each Teradata system planned to be accessed How to modify the existing configuration of a data source How to use the setup library to resolve problems with alias names to avoid delaying the connect process Configuring a Data Source Use the ODBC Data Source Administrator dialog box to configure data sources for each Teradata system to be accessed. One or more data sources must be configured. To configure a data source: ODBC Driver for Teradata User Guide 55

56 Chapter 3: ODBC Driver for Teradata Configuration for Microsoft Windows Configuring a Data Source 1 From the Microsoft Windows desktop task bar, click Start, move the mouse pointer up to Settings. Then select Control Panel to open the Control Panel window. 2 In the Control Panel window, double-click the icon for ODBC Data Sources to open the ODBC Data Source Administrator dialog box. 3 The User DSN and System DSN tabs list the names of existing data sources for the user and for all users of the system. To edit an existing data source, select it and click the Configure button. To create a new data source for the Teradata Database, click the Add button and continue with the following steps. 56 ODBC Driver for Teradata User Guide

57 Chapter 3: ODBC Driver for Teradata Configuration for Microsoft Windows Configuring a Data Source 4 In the Data Source Name pane of the Create New Data Source dialog box, select Teradata. Click the Finish button and the ODBC Driver Setup for Teradata dialog box displays. ODBC Driver for Teradata User Guide 57