Survey
* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project
Download Teradata Driver for the JDBC Interface User Guide
Document related concepts
Oracle Database wikipedia , lookup
Entity–attribute–value model wikipedia , lookup
Concurrency control wikipedia , lookup
Functional Database Model wikipedia , lookup
Microsoft Jet Database Engine wikipedia , lookup
Microsoft SQL Server wikipedia , lookup
Extensible Storage Engine wikipedia , lookup
Clusterpoint wikipedia , lookup
Database model wikipedia , lookup
Transcript
Teradata Driver for the JDBC Interface User Guide Release 12.00.00 B035-2403-067A July 2007 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 e-mail: [email protected] 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 © 1997-2007 by Teradata Corporation. All Rights Reserved. Preface Purpose This book provides information about Teradata Driver for the JDBC Interface, which is a Teradata® Tools and Utilities product. Teradata Tools and Utilities is a group of products designed to work with Teradata Database. The Teradata® Driver for the JDBC® Interface provides access to the Teradata Database using Java® applications. Audience This book is intended for use by: • Java programmers • Users who will be writing Java code to access the Teradata Database Supported Releases This book supports the following releases: • Teradata Database 12.00.00 • Teradata Tools and Utilities 12.00.00 • Teradata Driver for the JDBC Interface Release 12.00.00 Note: See “Determining the Current Version of the JDBC Driver” on page 24 to verify the Teradata Driver for the JDBC Interface version number. To locate detailed supported-release information: 1 Go to www.info.teradata.com. 2 Navigate to General Search>Publication Product ID. 3 Enter 3119. 4 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. Teradata Driver for the JDBC Interface User Guide 3 Preface Prerequisites Prerequisites The following prerequisite knowledge is required for this product: • Familiar with computer technology, database management systems, Java Database Connectivity (JDBC) concepts, and utilities that load and retrieve data. 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 Release Definition associated with this release. 4 Date and Release Description July 2007 Teradata Driver for the JDBC Interface Release 12.00.00: 12.00.00 • Supports updatable result sets; includes changes to several methods • Implements the BLOB and CLOB update methods • Adds a Connection parameter NEW_PASSWORD to support the handling of database password expiration • Adds a Connection parameter USEXVIEWS that controls whether X views or non-X views are used for retrieving metadata • Provides getMoreResults(KEEP_CURRENT_RESULT) for multistatement request cursor positioning • Enables UDFs, XSPs, and UDMs to be created from resources that reside on the client • Supports the default connection URL (jdbc:default:connection) used in a Java Stored Procedure. A new Appendix E lists SQL Data Types Mapping. • Supports Connection parameter CHARSET for jdbc:default:connection for Java Stored Procedures • Supports stored procedure dynamic result sets, which extend the capabilities of Teradata Database stored procedures. This feature enables a stored procedure to return zero or more dynamic result sets, in addition to the output parameters already returned. • Supports the Teradata Database SET QUERY_BAND feature • Adds the GOVERN parameter information. Use of this parameter enables JDBC load and export sessions to be identifiable by TASM. • JDBC FastLoad • Removes references to IBM OS/390 • Updates the getDatabaseProductVersion() information; two additional methods are included: getDatabaseMajorVersion() and getDatabaseMinorVersion() Teradata Driver for the JDBC Interface User Guide Preface Additional Information Date and Release Description • Updates Appendix D non-support of setAsciiStream/ setCharacterStream for binding data to BYTE or VARBYTE destinations • Corrects the UNIX classpath information listed in “Running a Sample Application” • Supports fractional seconds of TIME values returned from the Teradata Database • Cautions regarding a possible hang with some occurrences of multithreading on IBM AIX 5.1 using 64-bit JDK application • Updates the ACCOUNT connection parameter information • JDBC Monitor 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. In the table, mmyx represents the publication date of a manual, where mm is the month, y is the last digit of the year, and x is an internal publication code. Match the mmy of a related publication to the date on the cover of this book. This ensures that the publication selected supports the same release. Type of Information Description Access to Information Release overview Use the Release Definition for the following information: 1 Go to http://www.info.teradata.com/. • 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 3 In the Publication Product ID box, type 2029. Late information Teradata Driver for the JDBC Interface User Guide 2 Select the General Search check box. 4 Click Search. 5 Select the appropriate Release Definition from the search results. 5 Preface Additional Information Type of Information Description Access to Information Additional product information Use the Teradata Information Products Publishing Library site to view or download specific manuals that supply related or additional information to this manual. 1 Go to http://www.info.teradata.com/. 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. Specific books related to Teradata Driver for the JDBC Interface are as follows: • Teradata Manager Installation Guide B035-2402-mmyA • Teradata Driver for the JDBC Interface User Guide B035-2403-mmyA • Teradata MultiLoad Reference B035-2409-mmyA • Teradata FastExport Reference B035-2410-mmyA • Basic Teradata Query Reference B035-2414-mmyA • Teradata Tools and Utilities Access Module Programmer Guide B035-2424-mmyA • Teradata Tools and Utilities Access Module Reference B035-2425-mmyA • Teradata FastLoad Reference B035-2411-mmyA • Teradata Archive/Recovery Utility Reference B035-2412-mmyA 6 Teradata Driver for the JDBC Interface User Guide Preface Additional Information Type of Information Description Access to Information • (Continued from the bulleted list above) in the Publication Product ID field, enter one of the following book numbers: • Teradata Manager User Guide B035-2428-mmyA • Teradata System Emulation Tool User Guide B035-2492-mmyA • OLE DB Provider for Teradata Installation and User Guide B035-2498-mmyA • Teradata Administrator User Guide B035-2502-mmyA • Teradata Statistics Wizard User Guide B035-2503-mmyA • Teradata SQL Assistant/Web Edition User Guide B035-2505-mmyA • Teradata Index Wizard User Guide B035-2506-mmyA • Teradata SQL Assistant for Microsoft Windows User Guide B035-2430-mmyA • Teradata Access Module for Tivoli Installation and User Guide B035-2444-mmyA • Teradata Tools and Utilities Installation Guide for UNIX and Linux B035-2459-mmyA • Teradata Dynamic Workload Manager User Guide B035-2513-mmyA • Teradata Workload Analyzer User Guide B035-2514-mmyA • Teradata Parallel Data Pump Reference B035-3021-mmyA • ODBC Driver for Teradata User Guide B035-2509-mmyA • Teradata Director Program Reference B035-2510-mmyA • Teradata Query Scheduler Administrator Guide B035-2511-mmyA • Teradata Query Scheduler User Guide B035-2512-mmyA CD-ROM images 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. Teradata Driver for the JDBC Interface User Guide 1 Go to http://www.info.teradata.com/. 2 Select the General Search check box. 3 In the Title or Keyword box, type CD-ROM. 4 Click Search. 7 Preface Additional Information Type of Information Description Access to Information Ordering information for manuals Use the Teradata Information Products Publishing Library site to order printed versions of manuals. 1 Go to http://www.info.teradata.com/. 2 Select the How to Order check box under Print & CD Publications. 3 Follow the ordering instructions. General information about Teradata The Teradata home page provides links to numerous sources of information about Teradata. Links include: 1 Go to Teradata.com. 2 Select a link. • Executive reports, case studies of customer experiences with Teradata, and thought leadership • Technical information, solutions, and expert advice • Press releases, mentions, and media resources 8 Teradata Driver for the JDBC Interface User Guide Table of Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 Supported Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4 Changes to This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4 Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5 Chapter 1: Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 What’s New . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Planning for Software Upgrades . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Application Server Compatibility Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Driver Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Downloading the Java Development Kit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Determining the Current Version of the JDBC Driver. . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 JDBC Interface Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Teradata Driver for the JDBC Interface Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Type 4 JDBC Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 The JDBC Type 4 Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . How It Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Benefits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 27 28 28 Support for Internationalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Java Virtual Machine Locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Flow From a Java Application to Teradata Driver for the JDBC Interface . . . . . . . Data Flow Between the Teradata Driver for the JDBC Interface and Teradata Database Character Mapping Differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Flow From the Teradata JDBC Driver to a Java Application . . . . . . . . . . . . . . . . . . 28 28 28 30 31 32 Modifying SQL Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Null Expressions Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Correcting the SQL Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Teradata Driver for the JDBC Interface User Guide 9 Table of Contents Chapter 2: Using the Teradata Driver for the JDBC Interface . . . . . . . . . . . . . .35 JDBC Escape Clauses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35 Date and Time Literals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36 JDBC Scalar Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36 LIKE Predicate Escape Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38 Outer Joins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38 Calls to Stored Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38 Query Banding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39 Why is Query Banding Needed? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39 Use Case Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40 Recommended QueryBand Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41 Uses for the QueryBand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42 Importing the SQL Package and Loading the Teradata Driver for the JDBC Interface . . . . . .42 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42 Making a Teradata Database Connection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43 JDBC Type 3 Driver to Type 4 Driver Migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43 The Type 4 Connection URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43 Data Source Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54 Type 4 COP Discovery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55 LogonSource Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56 Example LogonSource value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57 Field 4 - TDPID (target Teradata Database hostname) Field . . . . . . . . . . . . . . . . . . . . . . .58 Field 5 - Client Process ID/Thread ID Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58 Field 6 - Client Process User Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59 Field 7 - Client Program Name Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59 Field 8 - LogonSource string version 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59 Program Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59 Converting Sample files from Java to EBCDIC for z/OS USS . . . . . . . . . . . . . . . . . . . . . . .59 Running a Sample Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60 Running on Sun Solaris SPARC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60 Source File Locations for JDBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61 Updatable LOBs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61 Temporary Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61 Connection Parameter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61 Update LOB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62 SQL Literals and SQL Injection Attacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62 Multi-Threading Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63 Multi-threading on IBM AIX 5.1 and Using 64-bit JDK on Microsoft Windows . . . . . . .64 10 Teradata Driver for the JDBC Interface User Guide Table of Contents Using Type 4 Driver with ResultSetMetaData Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Using Type 4 Driver with Sun JDK 5.0 Implementation of JDBC RowSet Interface . . . . . . . 65 Encryption, Authentication, and Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . URL and DataSource Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Meeting Kerberos Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Server-Side Default Authentication Mechanism. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . C and Java Application Sharing of XML Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . 66 67 67 68 71 72 Generated Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Multi-Statement Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PreparedStatement Batch Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Insert-Select Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Exceptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Upsert Statements are not Supported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 73 73 73 73 74 Parameter MetaData and Ambiguous Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Java External Stored Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JAR Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Transferring Java XSP From the Client to the DBS Server. . . . . . . . . . . . . . . . . . . . . . . . . Defining the SQL Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parameter Usage Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Default Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Invoking a Java XSP from JDBC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Transaction Semantics and Java XSPs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 77 77 78 78 79 79 80 Updatable Result Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Making a Result Set Updatable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Non-updatable Result Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Inner Joins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Outer Joins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Updatable Result Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Result Set Type and Concurrency Upgrading and Downgrading . . . . . . . . . . . . . . . . . . . Exceptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 80 81 81 81 82 83 84 Stored Procedure Dynamic Result Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 JDBC FastLoad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enabling JDBC FastLoad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Considerations When Using JDBC FastLoad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JDBC Data Types Supported by JDBC FastLoad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JDBC Escape Functions in Support of JDBC FastLoad . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 85 86 86 86 JDBC Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enabling JDBC Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Considerations When Using JDBC Monitor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JDBC Data Types Supported by JDBC Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Teradata Database PM/API Statements Supported by JDBC Monitor. . . . . . . . . . . . . . . 87 87 87 88 88 Teradata Driver for the JDBC Interface User Guide 11 Table of Contents Chapter 3: JDBC Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93 BLOB Interface Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94 CLOB Interface Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96 CallableStatement Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99 Connection Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107 ConnectionEvent Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119 ConnectionEventListener Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120 ConnectionPoolDataSource Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121 DatabaseMetaData Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123 DataSource Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .180 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .180 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .180 DriverManager Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .182 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .182 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .182 ParameterMetaData Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .186 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .186 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .186 PooledConnection Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .190 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .190 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .190 PreparedStatement Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .191 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .191 12 Teradata Driver for the JDBC Interface User Guide Table of Contents Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 ResultSet Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 ResultSetMetaData Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249 Statement Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 TeraDataSource Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264 Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265 Appendix A: Supported JDBC Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 Supported Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JDBC BLOB Interface Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JDBC CLOB Interface Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JDBC CallableStatement Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JDBC Connection Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JDBC ConnectionEvent Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JDBC ConnectionEventListener Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JDBC ConnectionPoolDataSource Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JDBC DatabaseMetaData Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JDBC DataSource Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JDBC DriverManager Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JDBC ParameterMetaData Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JDBC PooledConnection Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JDBC PreparedStatement Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JDBC ResultSetMetadata Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JDBC ResultSet Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . JDBC Statement Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TeraDataSource Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 286 286 287 288 289 289 289 289 295 295 296 297 297 298 299 304 305 Appendix B: Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309 Invalid UserID, Password, or Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309 Teradata Driver for the JDBC Interface User Guide 13 Table of Contents Numeric Data Truncation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .310 Character Export Width. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .310 BigDecimal Behavior for toString When Running on J2SE 5.0 . . . . . . . . . . . . . . . . . . . . . . . .311 Transaction Isolation, Concurrency, and Deadlock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .311 Create and Drop. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .311 JDBC FastLoad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .311 Transaction Isolation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .311 Large Object Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .312 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .312 Number of LOB Columns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .312 LOB Size Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .312 Response Limit Exceeded Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .312 1 MB SQL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .314 Using the Type 4 Driver on IBM AIX 5.2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .314 Additional Arguments Needed for IBM AIX platform. . . . . . . . . . . . . . . . . . . . . . . . . . . .314 Submitting Application Using addBatch() and executeBatch() . . . . . . . . . . . . . . . . . . . .314 Database Response Buffer Size Limit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .315 Multiple Sessions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .315 Multiple Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .315 Application Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .316 Close Not Done . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .316 UTF16 Character Set Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .316 Checking the Environment Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .317 CLASSPATH. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .317 Troubleshooting COP Discovery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .317 DNS and Hosts File Entries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .317 Improving Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .318 Java HotSpot Server Virtual Machine Error on Linux Platform . . . . . . . . . . . . . . . . . . . . . . .320 Troubleshooting Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .321 Troubleshooting Kerberos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .321 LDAP Authentication Not Supported on MVS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .323 UserId, Password, or Account is Invalid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .323 Troubleshooting JDBC FastLoad. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .323 Troubleshooting JDBC Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .324 Appendix C: Metadata Features and Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .327 Issues and Answers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .327 14 Teradata Driver for the JDBC Interface User Guide Table of Contents Appendix D: Data Type Conversions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 Data Type Conversions Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 Appendix E: SQL Data Types Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341 SQL Data Types Mapping Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347 Teradata Driver for the JDBC Interface User Guide 15 Table of Contents 16 Teradata Driver for the JDBC Interface User Guide List of Figures Figure 1: JDBC Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Figure 2: JDBC Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Figure 3: JDBC Type 4 Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Figure 4: Registry Editor Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315 Figure 5: Changing the Windows SharedSection Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316 Teradata Driver for the JDBC Interface User Guide 17 List of Figures 18 Teradata Driver for the JDBC Interface User Guide List of Tables Table 1: Java Development Kit (JDK) Version. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Table 2: JDBC Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Table 3: Character Set Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Table 4: Internal Unicode Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Table 5: Date and Time Literals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 Table 6: Numeric, String, and Time and Date Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 Table 7: System Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Table 8: Conversion Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Table 9: URL String. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Table 10: Database Connection Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 Table 11: JDBC Object Thread Safety . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Table 12: URL and DataSource Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Table 13: Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Table 14: Data Type AmbiguousUnknown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Table 15: Data Type Ambiguous Unknown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Table 16: IDENTIFY Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Table 17: MONITOR PHYSICAL CONFIG Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Table 18: MONITOR PHYSICAL RESOURCE Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Table 19: MONITOR PHYSICAL SUMMARY Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Table 20: MONITOR SESSION Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Table 21: MONITOR SQL Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 Table 22: MONITOR VERSION Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 Table 23: MONITOR VIRTUAL CONFIG Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Table 24: MONITOR VIRTUAL RESOURCE Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Table 25: MONITOR VIRTUAL SUMMARY Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Table 26: SET SESSION RATE Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Table 27: TDWM STATISTICS Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Table 28: TDWM SUMMARY Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 Table 29: JDBC BLOB Interface Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 Table 30: JDBC CLOB Interface Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 Table 31: JDBC CallableStatement Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287 Table 32: JDBC Connection Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288 Teradata Driver for the JDBC Interface User Guide 19 List of Tables Table 33: JDBC ConnectionEvent Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .289 Table 34: JDBC ConnectionEventListener Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .289 Table 35: JDBC ConnectionPoolDataSource Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .289 Table 36: JDBC DatabaseMetaData Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .289 Table 37: JDBC DataSource Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .295 Table 38: JDBC DriverManager Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .295 Table 39: JDBC ParameterMetadata Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .296 Table 40: JDBC PooledConnection Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .297 Table 41: JDBC PreparedStatement Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .297 Table 42: JDBC ResultSetMetadata Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .298 Table 43: JDBC ResultSet Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .299 Table 44: JDBC Statement Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .304 Table 45: TeraDataSource Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .305 Table 46: Metadata Features and Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .327 Table 47: Data Type Conversions Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .335 20 Teradata Driver for the JDBC Interface User Guide CHAPTER 1 Overview This chapter describes Java Database Connectivity (JDBC), the Teradata Driver for the JDBC Interface, and the three-tier architecture that connects client system Java programs to the Teradata Database. The section titles include: • What’s New • Driver Requirements • JDBC Interface Description • Teradata Driver for the JDBC Interface Description • The JDBC Type 4 Architecture • Support for Internationalization • Modifying SQL Statements What’s New • Support for Java Stored Procedures with Teradata Database 12.0 • User Defined Functions (UDFs), User Defined Methods (UDMs), Java Stored Procedures, and other External Stored Procedures (XSPs) can now be created from resources on the client classpath • Support for Dynamic Result Sets returned from Structured Query Language (SQL) Stored Procedures with Teradata Database 12.0 • Support for Updatable Result Sets with Teradata Database 12.0 and V2R6.2 • Support for the JDBC 3.0 Specification Blob update methods: • • public int setBytes(long pos, byte[] bytes) • public int setBytes(long pos, byte[] bytes, int offset, int len) • public OutputStream setBinaryStream(long pos) • public void truncate(long len) Support for JDBC 3.0 Specification Clob update methods: • public int setString(long pos, String str) • public int setString(long pos, String str, int offset, int len) • public OutputStream setAsciiStream(long pos) • public Writer setCharacterStream(long pos) • public void truncate(long len) Teradata Driver for the JDBC Interface User Guide 21 Chapter 1: Overview What’s New • JDBC FastLoad enables efficient loading of large amounts of data into an empty destination table • JDBC Monitor provides a method for accessing and using standard performance monitoring and production control functions contained within the Teradata Database • Teradata Database TIME values may be defined with as many as six fractional digits, but java.sql.Time objects are capable of millisecond precision (three fractional digits at most). Previously, fractional seconds of TIME values were not returned. Now, fractional seconds of TIME values are returned from the database by the following methods, with truncation to millisecond precision, if necessary: • ResultSet.getTime • ResultSet.getObject • CallableStatement.getTime • CallableStatement.getObject • Support for DatabaseMetaData queries against the Teradata Database Data Dictionary X views with the USEXVIEWS connection parameter • Support for Teradata Database password expiration with the NEW_PASSWORD connection parameter • Support for the Teradata Database 12.0 SET QUERY_BAND statement and Query Banding feature • Support method getMoreResults(KEEP_CURRENT_RESULT) for multi-statement request cursor positioning with Teradata Database 12.0 • DatabaseMetaData getDatabaseProductVersion returns a string that begins with Teradata Database and that includes V2R for supported database releases prior to 12.0, but does not include V2R for 12.0 • DatabaseMetaData getDatabaseMajorVersion returns 12 for Teradata Database 12.0 and returns 2 for supported V2R6.x releases prior to 12.0 • DatabaseMetaData getDatabaseMinorVersion returns 0 for Teradata Database 12.0 and returns 6 for supported V2R6.x releases prior to 12.0 Planning for Software Upgrades Change applications to expect the JDBC specification features and behavior listed, in anticipation of support for these JDBC specification features and behavior. The JDBC 3.0 specification requires JDBC drivers and data sources to validate the SQL requests that are passed to the executeQuery, executeUpdate, and executeBatch APIs; and requires an SQLException to be thrown from the executeQuery, executeUpdate, and executeBatch APIs if the SQL request is inappropriate for the API. 22 • If executeQuery is used on an SQL statement that does not return a result set or returns multiple result sets then an SQLException is thrown. • If executeUpdate is used on an SQL statement that returns a result set or returns multiple update counts then an SQLException is thrown. Teradata Driver for the JDBC Interface User Guide Chapter 1: Overview Application Server Compatibility Documentation • If executeBatch is used where one or more of the SQL statements return a result set, then an SQLException is thrown. Application Server Compatibility Documentation Application server compatibility documentation is included in the Teradata Driver for the JDBC Interface download package. The application server compatibility documentation lists the application server versions supported by this release of the Teradata Driver for the JDBC Interface, and includes detailed instructions for how to configure Data Source and Connection Pools within each supported application server. The Teradata Driver for the JDBC Interface download package includes a jar file named appserver-howto.jar. This jar file contains an HTML document for each supported application server version, explaining how to use the Teradata Driver for the JDBC Interface with that application server version. As support is added for more application server versions, the Teradata Driver for the JDBC Interface download package will be updated to include more application server compatibility documentation. Be sure to check the http://www.teradata.com Download Center at Teradata regularly for updates to the Teradata Driver for the JDBC Interface download package. Driver Requirements To find out on which platforms a given product is available and the compatible Teradata Database versions, refer to Teradata Tools and Utilities 12.00.00 Supported and Certified Versions, B035-3119-067K. This spreadsheet shows version numbers and platform information for all Teradata Tools and Utilities release 12.00.00 products and is available at www.info.teradata.com. Downloading the Java Development Kit To start Java development after the Teradata Driver for the JDBC Interface is installed, download the Java Development Kit (JDK). Table 1 includes the supported versions of JDK: Table 1: Java Development Kit (JDK) Version System Version Microsoft Windows (2000, Server 2003, and XP) JDK 1.4 or JDK 5.0 from Sun JDK 5.0 is certified for Windows 32-bit. JDK 5.0 is certified for Windows XP Professional x64 using EM64T Sun Solaris Teradata Driver for the JDBC Interface User Guide JDK 1.4 or JDK 5.0 from Sun JDK 5.0 is certified for Solaris 10 32-bit and 64-bit. 23 Chapter 1: Overview Driver Requirements Table 1: Java Development Kit (JDK) Version (continued) System Version HP-UX JDK 1.4 or JDK 5.0 from HP® Note: Download this JDK from HP for the HP-UX operating system from the following location: http://www.hp.com/products1/unix/java IBM AIX JDK 1.4 or JDK 5.0 from IBM Note: Download this JDK from IBM for the AIX operating system from the following location: http://www-106.ibm.com/developerworks/java/jdk/?dwzone=java IBM z/OS 1.3 USS JDK 1.4 or JDK 5.0 from IBM Note: Download this JDK from IBM for z/OS USS operating system from the following location: http://www-106.ibm.com/developerworks/java/jdk/?dwzone=java Linux JDK 1.4 or JDK 5.0 from Sun, or JDK 1.4 or JDK 5.0 from IBM Note: Download this JDK from IBM for z/OS USS operating system from the following location: http://www-106.ibm.com/developerworks/java/jdk/?dwzone=java JDK 5.0 is certified for Linux 32-bit. Note: Unless otherwise specified in Table 1, download the JDK from Sun Microsystems from the following location: http://www.java.sun.com/products Determining the Current Version of the JDBC Driver Windows To determine the currently installed version of the Teradata Driver for the JDBC Interface on Windows open a Command Prompt window, change to the directory containing the Teradata JDBC Driver, and use the following commands: jar xvf terajdbc4.jar META-INF/MANIFEST.MF type META-INF/MANIFEST.MF UNIX and Linux To determine the currently installed version of the Teradata Driver for the JDBC Interface on UNIX and Linux, change to the directory containing the Teradata JDBC Driver, and use the following commands. jar xvf terajdbc4.jar META-INF/MANIFEST.MF cat META-INF/MANIFEST.MF 24 Teradata Driver for the JDBC Interface User Guide Chapter 1: Overview JDBC Interface Description JDBC Interface Description JDBC is a specification for an application programming interface (API). This API allows platform-independent Java applications to access database management systems using SQL. The JDBC API provides a standard set of interfaces for: • Opening connections to databases • Executing SQL statements • Processing results These interfaces are shown Figure 1 and listed in Table 2. Figure 1: JDBC Interfaces Driver Manager or DataSource Connection Connection Connection Connection Connection Callable Statement Prepared Statement Prepared Statement Statement Statement ResultSet ResultSet Parameter MetaData ResultSet ResultSet Database MetaData ResultSet MetaData 2403B003 Table 2: JDBC Interfaces Interface Name Description java.sql.Blob Provides support for Binary Large Objects (BLOB) java.sql.Clob Provides support for Character Large Objects (CLOB) java.sql.Connection Represents a connection to a database java.sql.DatabaseMetaData Accesses a variety of information for the selected Database javax.sql.DataSource Provides support for creating/obtaining database connections java.sql.DriverManager Handles driver loading and supports creating new database connections java.sql.ParameterMetaData Accesses the metadata information for the parameters Teradata Driver for the JDBC Interface User Guide 25 Chapter 1: Overview JDBC Interface Description Table 2: JDBC Interfaces (continued) 26 Interface Name Description java.sql.PreparedStatement Acts as a container for executing a prepared SQL statement on a given connection java.sql.ResultSet Controls access to the row results of a given statement java.sql.ResultSetMetaData Accesses the metadata information for the result set java.sql.Statement Acts as a container for executing an SQL statement on a given connection Java.sql.CallableStatement Acts as a container for executing a stored procedure on the database for a given connection javax.sql.ConnectionEventListener Acts as an object that registers to receive events generated by a PooledConnection javax.sql.ConnectionPoolDataSource Is a factory for PooledConnection objects. An object that implements this interface typically is registered with a Java Naming and Directory Interface (JNDI) service. javax.sql.PooledConnection Is a connection object that provides hooks for connection pool management. A PooledConnection object represents a physical connection to a data source. Teradata Driver for the JDBC Interface User Guide Chapter 1: Overview Teradata Driver for the JDBC Interface Description Teradata Driver for the JDBC Interface Description The Teradata Driver for the JDBC Interface is a set of Java classes that work with the JDBC interface, enabling access to the Teradata Database using the Java language. As illustrated in Figure 2, Teradata currently supports the Type 4 JDBC driver. Figure 2: JDBC Interface Java Application JDBC API JDBC Driver Manager JDBC Driver API Type 4 Driver Teradata Database 2403B001 Type 4 JDBC Driver The Type 4 JDBC driver communicates directly with the Teradata Database. The JDBC Type 4 Architecture Description The Teradata Driver for the JDBC Interface uses a two-tier architecture to access the Teradata Database as shown in Figure 3. Figure 3: JDBC Type 4 Architecture Client Computer Java Program Teradata Database Teradata JDBC Driver 2403A004 Teradata Driver for the JDBC Interface User Guide 27 Chapter 1: Overview Support for Internationalization How It Works The Teradata Driver for the JDBC Interface is platform-independent and can be used on any system that has a supported Java Virtual Machine (JVM) installed. Java classes of the Teradata Driver for the JDBC Interface connect directly to the Teradata Database using a TCP socket. The supported JDBC methods are listed in Appendix A. Benefits The two-tier access architecture offers the following benefits: • Improved performance over the JDBC Type 3 driver • All-Java driver allows it to run anywhere Support for Internationalization Java Virtual Machine Locale The Teradata Driver for the JDBC Interface provides support for the Japanese locale, such that the message text of Teradata Driver for the JDBC Interface exceptions is provided in Japanese, when the Japanese locale is used for the JVM. This applies only to Teradata Driver for the JDBC Interface exception conditions. Exception message text for Teradata Database error conditions is provided by the Teradata Database, and is not controlled by the JVM locale. The message text of Teradata Driver for the JDBC Interface exceptions is provided in English for all locales other than the Japanese locale. Data Flow From a Java Application to Teradata Driver for the JDBC Interface Almost all Java APIs, including the JDBC APIs, assume the use of java.lang.String objects, which contain Unicode characters. Character data is typically passed from a Java application into the Teradata Driver for the JDBC Interface as java.lang.String objects. This occurs when an application: • Includes character data as SQL string literals in an SQL statement, and uses one of the JDBC APIs such as Statement.execute, Statement.executeUpdate, Statement.executeQuery, or Connection.prepareStatement • Uses a prepared statement, and binds character data to a ? parameter marker using the JDBC API method PreparedStatement.setString or PreparedStatement.setObject(String) Once data passes into the Teradata Driver for the JDBC Interface as java.lang.String objects, the Teradata Driver for the JDBC Interface does not convert from non-Unicode to Unicode characters, because java.lang.String objects always contain Unicode characters. 28 Teradata Driver for the JDBC Interface User Guide Chapter 1: Overview Support for Internationalization There are two unusual scenarios in which a Java application might obtain non-Unicode characters, and subsequently need to store those characters in the Teradata Database. These are not normal application development scenarios, since normal Java application development is entirely Unicode-based: • Scenario 1: The Java application obtains non-Unicode character data in some way; for example, by reading from a TCP socket, and stores the non-Unicode character data as bytes in a Java byte array • Scenario 2: The Java application must read non-Unicode character data from a file on the file system For Scenario 1, with the non-Unicode character data stored as bytes in a Java byte array, the Java application uses the following java.lang.String constructor: String(byte[] bytes, String charsetName) This constructs a new String by decoding the specified array of bytes using the specified charset. After constructing the java.lang.String object, the Java application can manipulate this object like any other Java String object, and pass it into the Teradata Driver for the JDBC Interface. For Scenario 2, with the non-Unicode character data stored in a file on the file system, the Java application uses a PreparedStatement object with a ? parameter marker to represent the input data from the file, and the Java application uses one of the following JDBC APIs: • PreparedStatement.setCharacterStream–can be used for data stored in a file, in any character set. The JDBC API PreparedStatement.setCharacterStream requires the Java application to provide a Reader object as one of the arguments. With PreparedStatement.setCharacterStream, it is the Java application's responsibility to use the appropriate Java I/O APIs to convert non-Unicode input data to Unicode and ensure that the conversion does not result in any loss of any data. The Java application constructs an InputStreamReader object on a FileInputStream object, and then supplies the InputStreamReader object as an argument to the JDBC API PreparedStatement.setCharacterStream. When constructing the InputStreamReader object, the Java application uses one of the InputStreamReader constructors that have a charset parameter, and the Java application specifies the correct character set of the data stored in the file. For example: prepstmt.setCharacterStream(columnIndex, new InputStreamReader(new FileInputStream("myfile.dat"),"ISO-8859-8")) • PreparedStatement.setAsciiStream–can be used for data stored in a file, only in the American Standard Code for Information (ASCII) character set. The JDBC API PreparedStatement.setAsciiStream requires the Java application to provide an InputStream object as one of the arguments. The Java application constructs a FileInputStream object to read from the ASCII file, and then supplies that FileInputStream object as an argument to the JDBC API PreparedStatement.setAsciiStream. For example: Teradata Driver for the JDBC Interface User Guide 29 Chapter 1: Overview Support for Internationalization prepstmt.setAsciiStream(columnIndex, new FileInputStream("ascii.txt")) Data Flow Between the Teradata Driver for the JDBC Interface and Teradata Database The Teradata Driver for the JDBC Interface provides a CHARSET connection parameter for the Java application to specify the session character set for the Teradata Database session. The CHARSET connection parameter's description is located in the Database Connection Parameters table in Chapter 2. If the Java application does not specify a CHARSET connection parameter, then the default setting is CHARSET=ASCII. It is strongly recommended that Java applications store character data in Unicode columns in the Teradata Database, and use the UTF8 session character set (connection parameter CHARSET=UTF8). This avoids conversions between character sets, and ensures end-to-end fidelity of character data. The Teradata Driver for the JDBC Interface provides a fixed mapping of Teradata session character sets to Java character sets, shown in Table 3. For a given Teradata session character set, the corresponding Java character set is used to encode bytes sent to the database, and to decode bytes received from the database. Table 3: Character Set Mapping 30 Teradata Session Character Set Java Character Set ASCII ASCII UTF8 UTF8 UTF16 UnicodeBigUnmarked EBCDIC037_0E Cp037 EBCDIC273_0E Cp273 EBCDIC277_0E Cp277 HANGULEBCDIC933_1II Cp933 HANGULKSC5601_2R4 MS949 KANJIEBCDIC5026_0I Cp930 KANJIEBCDIC5035_0I Cp939 KANJIEUC_0U EUC_JP KANJISJIS_0S MS932 KATAKANAEBCDIC CP930 LATIN1_0A ISO8859_1 LATIN1252_0A Cp1252 LATIN9_0A ISO8859_15_FDIS Teradata Driver for the JDBC Interface User Guide Chapter 1: Overview Support for Internationalization Table 3: Character Set Mapping (continued) Teradata Session Character Set Java Character Set SCHEBCDIC935_2IJ Cp935 SCHGB2312_1T0 EUC_CN TCHBIG5_1R0 BIG5 TCHEBCDIC937_3IB Cp937 Although the CLIENT_CHARSET connection parameter can be used to override the Teradata Driver for the JDBC Interface fixed mapping of Teradata session character sets to Java character sets, the CLIENT_CHARSET connection parameter is not intended for use in new Teradata deployments. It is a legacy support feature intended to assist transition away from the unsupported use of the Teradata Database in terms of storing non-Latin characters in a Latin column, and the subsequent unsupported access of those non-ASCII characters using an ASCII session character set. Character Mapping Differences Table 4 shows how certain character sets differ in specific character code points. • The Java application avoids using characters that cannot be represented in the Java character set corresponding to the Teradata session character set • When the Java application uses the PreparedStatement.setCharacterStream technique described above, the Java application ensures that the Java character set specified as an argument to the InputStreamReader constructor provides a mapping to Unicode for the non-Unicode characters stored in the file Table 4: Internal Unicode Mapping Encoding Character Name SJIS MS932 Cp943 Cp943C Teradata Internal Unicode REVERSE SOLIDUS 0x5C U+005C – U+005C – YEN SIGN 0x5C – U+00A5 – U+00A5 WAVE DASH 0x8160 U+FF5E U+301C U+301C U+301C DOUBLE VERTICAL LINE 0x8161 U+2225 U+2016 U+2016 U+2016 MINUS SIGN 0x817C U+FF0D U+2212 U+2212 U+2212 If the Java application attempts to store WAVE DASH or MINUS SIGN characters in a CHAR or VARCHAR column, the Teradata Database might not be able to process the request Teradata Driver for the JDBC Interface User Guide 31 Chapter 1: Overview Modifying SQL Statements correctly, since there are multiple Unicode character translations for the SJIS, EUC, and EBCDIC code points for the WAVE DASH and MINUS SIGN characters. Teradata Database maps U+FF5E to the following external code points for each session character set. A Teradata Database map file is required for the following mappings. • KANJIEBCDIC 0x43A1 • KANJIEUC 0xA1C1 • KANJISJIS 0x8160 1- • in mapeuc: UNICODE_2_UPC_CS123 0xFF5E 0xA1C1 # FULLWIDTH TILDE 2- • in mapsjis: UNICODE_2_SJIS_MBC 0xFF5E 0x8160 # FULLWIDTH TILDE 3- • in mapsosi: UNICODE_2_SOSI 0xFF5E 0x43A1 # FULLWIDTH TILDE Data Flow From the Teradata JDBC Driver to a Java Application After executing a query, the Java application typically gets character data from the Teradata Driver for the JDBC Interface as java.lang.String objects by using one of the following JDBC APIs: • ResultSet.getString • ResultSet.getObject for a CHAR or VARCHAR column returns a String object Alternatively, the Java application can get character data from the Teradata Driver for the JDBC Interface by using one the following JDBC APIs: • ResultSet.getCharacterStream–returns a Reader object that provides Unicode characters • ResultSet.getAsciiStream–returns an InputStream object that can only provide ASCII characters. The Java application should not attempt to use this JDBC API to get nonASCII character data. Modifying SQL Statements Teradata Driver for the JDBC Interface Release 3.1 and earlier modified SQL statements, replacing all occurrences of ? with IS NULL whenever the application called setNull() for the ? in a where clause. For example, if the SQL statement was: SELECT * from table1 where colid = ? and the application called setNull(1), the Teradata Driver for the JDBC Interface changed the SQL statement to SELECT * from table1 where colid is null This was an incorrect procedure to use, since the SQL statement returned all rows where colid was null. The correct SQL statement is: SELECT * from table1 where colid = null 32 Teradata Driver for the JDBC Interface User Guide Chapter 1: Overview Modifying SQL Statements Note that this statement never returns any rows because null is never equal to anything including itself. The problem was fixed in the Teradata Driver for the JDBC Interface Release 3.2, but the fix might potentially change the output of some applications. Null Expressions Policy In SQL Reference: Functions and Operators, the following policy is stated for the result of a comparison (including the = equality operator) involving null values. If any expression in a comparison is null, the result of the comparison is unknown. For a comparison to provide a TRUE result when comparing fields that might result in nulls, the statement must include the IS [NOT] NULL operator. Correcting the SQL Statements To modify an SQL statement that is incorrect and stops working with the Release 3.3 driver, use the following information as an example: If the application uses an SQL statement such as: SELECT * from table1 where colid = ? and the application may bind either a null value argument, or bind a non-null value argument to the ? parameter, then the application may have expected the = comparison operator to return true in either case, since the Teradata Driver for the JDBC Interface Release 3.1 and earlier modified the SQL statement to provide that behavior. If the application expected that behavior, then change the SQL statement as follows: SELECT * from table1 where colid = ? or ? is null and colid is null and change the application to bind the argument twice to both ? parameters. Teradata Driver for the JDBC Interface User Guide 33 Chapter 1: Overview Modifying SQL Statements 34 Teradata Driver for the JDBC Interface User Guide CHAPTER 2 Using the Teradata Driver for the JDBC Interface This chapter describes using the Teradata Driver for the JDBC Interface software in Java programs, and guides you through the process of getting the Teradata Driver for the JDBC Interface running on site: • JDBC Escape Clauses • Query Banding • Importing the SQL Package and Loading the Teradata Driver for the JDBC Interface • Making a Teradata Database Connection • LogonSource Format • Program Examples • Running a Sample Application • Source File Locations for JDBC • Encryption, Authentication, and Authorization • Generated Keys • Parameter MetaData and Ambiguous Types • Java External Stored Procedures • Updatable Result Set • Stored Procedure Dynamic Result Set • JDBC FastLoad • JDBC Monitor JDBC Escape Clauses When JDBC escape clause processing is enabled, the Teradata Driver for the JDBC Interface looks for any escape syntax and translates it into native code for the type of database being used. This makes escape syntax independent of any database. The default for JDBC escape clause processing is ENABLED. Escape clause processing can be disabled for the Classes Statement and RowSet by calling the methods: • Statement.setEscapeProcessing(false) • RowSet.setEscapeProcessing(false) The following is the generic syntax for escape clauses: Teradata Driver for the JDBC Interface User Guide 35 Chapter 2: Using the Teradata Driver for the JDBC Interface JDBC Escape Clauses {keyword . . . parameters . . . } Teradata Driver for the JDBC Interface supports the following types of escape clauses: • Date, time, timestamp • Scalar functions • LIKE predicate escape characters • Outer joins • Calls to stored procedures Date and Time Literals Escape clauses for date and time literals use the following syntax: {literal-type 'value'} where literal-type is one of the types listed in Table 5: Table 5: Date and Time Literals Literal Type Meaning Format d Date yyy-mm-dd t Time hh:mm:ss ts Timestamp yyy-mm-dd hh:mm:ss[.f...] JDBC Scalar Functions The syntax for JDBC scalar functions is the following: { fn scalar_function() } Numeric, String, and Time and Date Functions Table 6 is the list of scalar functions which are supported by both the X/Open Call-Level Interface (CLI) for JDBC and the Teradata Driver for the JDBC Interface: Table 6: Numeric, String, and Time and Date Functions 36 Numeric Functions String Functions Time and Date Functions ABS(number) REPEAT(string, count) WEEK(date) ACOS(float) REPLACE(string1,string2, string3) YEAR(date) ASIN(float) SOUNDEX(string) CURDATE() ATAN(float) UCASE(string) CURTIME() Arctangent, in radians, of float ATAN2(float1, float2) Length(String) HOUR(time) Teradata Driver for the JDBC Interface User Guide Chapter 2: Using the Teradata Driver for the JDBC Interface JDBC Escape Clauses Table 6: Numeric, String, and Time and Date Functions (continued) Numeric Functions String Functions Time and Date Functions COS(float) LOCATE(string1,string2[, start]) MINUTE(time) COT(float) LTRIM(string) MONTH(date) EXP(float) RTRIM(string) NOW() LOG(float) LCASE(string) SECOND(time) MOD(integer1, integer2) SUBSTRING(string, start, length) TIMESTAMPADD(interval, count, timestamp) The Teradata Database only supports the following JDBC intervals: • SQL_TSI_YEAR, SQL_TSI_MONTH • SQL_TSI_DAY, SQL_TSI_MINUTE • SQL_TSI_SECOND SIN(float) UCASE(string) TIMESTAMPDIFF(interval, timestamp1, timestamp2) Teradata Database will only support the following JDBC intervals: • SQL_TSI_YEAR, SQL_TSI_MONTH • SQL_TSI_DAY, SQL_TSI_MINUTE • SQL_TSI_SECOND SQRT(float) CONCAT(string1,string2) TAN(float) WEEK(date) YEAR(date) System Functions Table 7 lists the system functions available. Table 7: System Functions System Functions DATABASE() IFNULL(expression, value) USER() Conversion Functions CONVERT(value, Teradata Driver for the JDBC Interface User Guide SQLtype) 37 Chapter 2: Using the Teradata Driver for the JDBC Interface JDBC Escape Clauses where SQLtype is one of the types listed in Table 8: Table 8: Conversion Functions Conversion Functions DATE DECIMAL DOUBLE INTEGER FLOAT LONGVARCHAR SMALLINT TIME TIMESTAMP TINYINT VARBINARY VARCHAR CHAR BINARY LIKE Predicate Escape Characters Teradata Driver for the JDBC Interface supports ESCAPE characters for LIKE SQL statements with the following syntax: {escape 'escape-character'} This escape clause specifies the escape character so wildcards such as %, _ can be interpreted literally in an SQL LIKE statement. Outer Joins The Teradata Driver for the JDBC Interface supports escape clauses for outer joins. The following is the syntax for an outer join: {oj outer-join} In this language rule, outer-join structure is: table {LEFT|RIGHT|FULL} OUTER JOIN {table | outer-join} ON search-condition Calls to Stored Procedures The escape clause syntax for a call to a stored procedure is the following: 38 Teradata Driver for the JDBC Interface User Guide Chapter 2: Using the Teradata Driver for the JDBC Interface Query Banding {call procedure_name(?, ?, . . .)} The following are true in Escape clauses: • A missing parenthesis () is only added when calling a stored procedure with a JDBC escape clause • It is invalid to execute a macro inside of a JDBC escape clause Effective with Teradata Tools and Utilities 08.01.00 and the Teradata Driver for the JDBC Interface Release 03.03.00, parentheses are no longer added to an SQL CALL statement that doesn’t use JDBC escape syntax. This behavior change allows an application’s SQL statements to be passed to the Teradata Database unmodified when JDBC escape syntax is not used. It is strongly recommended that applications always use standard vendor-independent JDBC Escape Syntax to call stored procedures. When JDBC Escape Syntax is used to call a stored procedure, as in: {call storedproc} then the Teradata Driver for the JDBC Interface modifies the SQL statement as needed to satisfy the Teradata Database's precise syntax requirements. JDBC Escape Syntax functionality for calling stored procedures has not changed with this release of the Teradata Driver for the JDBC Interface. Applications that inadvertently relied on the behavior of previous Teradata Driver for the JDBC Interface releases to modify SQL CALL statements that did not use JDBC Escape Syntax may need to be modified either: • To use standard JDBC Escape Syntax for calling a stored procedure (recommended) • To provide the empty parentheses after the stored procedure name Query Banding Teradata Database 12.0 introduces Query Banding. A QueryBand is a set of name-value pairs that can be set on a session or a transaction to identify an SQL request’s originating source. Why is Query Banding Needed? • Many J2EE applications that access a database make use of connection pooling mechanisms that consolidate the activity of several end-users onto database connections using the same database userID. Especially with a multi-tiered application, there may be no straightforward way on the database tier to identify the end-user, application, and so forth, that originated the SQL request. • J2EE applications may desire to identify or group together all the SQL requests submitted on behalf of a particular HTTP request for rendering a web page • For chargeback, accounting, troubleshooting, and other types of system management, administrators need to know what end-user, application, report, or part of an application issued a request Teradata Driver for the JDBC Interface User Guide 39 Chapter 2: Using the Teradata Driver for the JDBC Interface Query Banding Use Case Scenario In a web-based Java application, connection pools exist on the web servers. All the connections in the pools are for the same Teradata user; for example, appuser. This is commonly known as a robot user. The application uses browser cookies to identify the endusers who are using the web browsers. Every time the user clicks a link on a web page, the user’s web browser sends a request to the web server and transmits the browser cookie as part of the request. The web server invokes the application to process the request. The application does something; for example, submits a query to Teradata. Immediately before submitting the query to Teradata, the application first submits the following statements: PreparedStatement pstmt = conn.prepareStatement(“Set QUERY_BAND=? FOR TRANSACTION”); pstmt.setString (1, “custIdFromCookie=46734832”); pstmt.executeUpdate (); Then, the application can submit its query: SELECT col1, col2 FROM TableName WHERE condition1 = ? AND condition2 = ? After the query returns a result set, the application outputs an HTML page to the web browser. Use Case Scenario • A web service, implemented in Java, responds to an HTTP/SOAP request • A web service uses the Java Transaction API (JTA) to begin a User-Managed Transaction • A web service obtains a JDBC connection from a connection pool managed by the application server • A web service invokes multiple Enterprise Java Beans (EJB) to do some useful work. For example, the first EJB inserts a row into Table A and the second EJB updates some rows in Table B. All calls to the EJBs participate in the same transaction and therefore are identified with the same QueryBand. • A web service commits the transaction. The transaction’s QueryBand value is cleared automatically, so any subsequent SQL requests submitted on the pooled connections have a different QueryBand value. Syntax The QueryBand is passed to the Teradata Database as a list of name=value pairs in a string. The application defines both the names and the values. The QueryBand can be specified as an SQL string literal enclosed within single quotes. However, it is strongly recommended that a question mark parameter marker and the PreparedStatement.setString () method be used instead. A QueryBand can be set for the transaction and/or for the session. The following rules are required: 40 • Each name-value pair, including the last one, must terminate with a semicolon • Each QueryBand name must be 1-128 characters in length • Each QueryBand value must be 0-256 characters in length • QueryBand names and values cannot contain the following characters: equal sign, semicolon, or null character (\u0000) Teradata Driver for the JDBC Interface User Guide Chapter 2: Using the Teradata Driver for the JDBC Interface Query Banding • Each QueryBand name must be specified only once in a QueryBand string. (If QueryBand name is specified more than once in a QueryBand string, then the Teradata Database returns an error.) • The maximum length of the entire QueryBand string is limited to 2048 characters. All characters, including white-space characters, are counted when determining the length. White-space characters are permitted at (and removed from) the beginning and ending of the QueryBand string, before and after each equal sign, and before and after each semicolon. Example To set a QueryBand value in a transaction using an SQL string literal with a non-PreparedStatement: stmt = conn.createStatement(); stmt.executeUpdate(“SET QUERY_BAND = ‘Org = Finance; report = EndOfYear; universe=west;’ for TRANSACTION”); Example To set a QueryBand value in a transaction using a PreparedStatement: pstmt=conn.prepareStatement(“SET QUERY_BAND=? FOR TRANSACTION”); pstmt.setString (1, “Org = Finance; report = EndOfYear; universe=west;); pstmt.executeUpdate (); Example To clear a QueryBand value in a transaction: stmt = conn.CreateStatement(); stmt.executeUpdate(“SET QUERY_BAND = NONE for TRANSACTION”); Recommended QueryBand Names The following are standard Client Info property names defined by the JDBC 4.0 specification: • ApplicationName–the name of the application currently utilizing the connection • ClientUser–the name of the user for which the application using the connection is performing work. (This might not be the same as the user name that was used in establishing the connection.) • ClientHostname–the hostname of the computer on which the application using the connection is running For applications that need to use QueryBand name-value pairs that correspond to the standard Client Info properties, Teradata recommends using standard Client Info property names as QueryBand names. An application is not limited to using only standard Client Info properties. For QueryBand name-value pairs that do not correspond to the standard Client Info properties, the application is free to use any legal QueryBand name that is supported by the Teradata Database. Teradata Driver for the JDBC Interface User Guide 41 Chapter 2: Using the Teradata Driver for the JDBC Interface Importing the SQL Package and Loading the Teradata Driver for the JDBC Interface Uses for the QueryBand • The QueryBand is logged as a field in the Database Query Log (DBQL) detail logging table. DBQL reports can be created using the QueryBand name-value pairs to provide additional refinement for accounting and resource allocation purposes. For more information about DBQL, go to www.info.teradata.com, then click Teradata Data Warehousing, Teradata Database, Database Administration. • The QueryBand name-value pairs can be associated with Teradata Dynamic Workload Manager (TDWM) filter and throttle rules. For directory-based connections and applications that utilize a web-based application server that all connect to Teradata with a single logon, the originating source of requests can be distinguished using the QueryBand to permit resource control using the TDWM rules. For more information about TDWM, go to www.info.teradata.com, then click Teradata Data Warehousing, Teradata Tools and Utilities, and Teradata Dynamic Workload Manager document. • The QueryBand name-value pairs can be defined in TDWM workload classification criteria. This enables requests all coming from a single logon to be classified into different workloads based on the QueryBand set by the originating application. It also enables an application to set different priorities for different requests. For example, a GUI application may have dialogs that require quick responses and other dialogs that submit long-running reports that run in the background. The application can set a different QueryBand for each type of job, causing the requests to be classified into different workloads and thus running at different priorities. Importing the SQL Package and Loading the Teradata Driver for the JDBC Interface Introduction The JDBC application must have the SQL Interface package imported and the Teradata Driver for the JDBC Interface loaded. Note: The information in this section applies primarily to standalone Java applications. This information does not apply to a J2EE application deployed to an application server environment such as WebSphere or WebLogic. Application servers provide their own mechanisms for defining the classpath, and application servers are responsible for loading the JDBC driver classes. To import the SQL Interface package and load the Teradata Driver for the JDBC Interface 1 2 42 Verify that the following Teradata files are on the Java development platform: • terajdbc4.jar • tdgssjava.jar • tdgssconfig.jar Check CLASSPATH to see if it includes the following java archive files: Teradata Driver for the JDBC Interface User Guide Chapter 2: Using the Teradata Driver for the JDBC Interface Making a Teradata Database Connection 3 • terajdbc4.jar • tdgssjava.jar • tdgssconfig.jar Place the following line near the top of the program: import java.sql.*; 4 Use the following statement to load and register the Teradata Driver for the JDBC Interface: Class.forName(“com.ncr.teradata.TeraDriver”); Making a Teradata Database Connection JDBC Type 3 Driver to Type 4 Driver Migration The Type 3 Teradata Driver for the JDBC Interface is no longer included on the Installation CDs and tapes for Teradata Tools and Utilities. Related software, such as the JDBC Gateway and its administration GUI, is also no longer included. To run applications previously written for the Type 3 driver it is necessary to move applications to the Type 4 Teradata Driver for the JDBC Interface. To do this, change the application’s connection Universal Resource Locator (URL) as follows: JDBC Type 3: JDBC Type 4: jdbc:teradata://gwhost:port/dbshost jdbc:teradata://dbshost Applets The applet security model only permits applets to connect to the system from which the applet was downloaded. The following three-tier application architecture is no longer supported: • Client tier, consisting of an applet using the JDBC Type 3 driver • Middle tier, consisting of a web server and JDBC Gateway • Back-end tier, consisting of the Teradata Database This release of the Teradata Driver for the JDBC Interface supports the following application architecture. • Client tier, consisting of a browser-based - HTML/DHTML and/or J2EE client applet • Middle tier, consisting of a J2EE application server – servlets and/or EJBs using the JDBC Type 4 driver • Back-end tier, consisting of the Teradata Database The Type 4 Connection URL To access a Teradata Database from a Java program, use the java.sql.DriverManager.getConnection method to obtain a new java.sql.Connection object from the DriverManager. Teradata Driver for the JDBC Interface User Guide 43 Chapter 2: Using the Teradata Driver for the JDBC Interface Making a Teradata Database Connection The java.sql.DriverManager.getConnection method takes a URL string as an argument. The URL string represents a Teradata Database, and the DriverManager uses it to locate a driver that can connect to the represented Teradata Database. To select the Type 4 Teradata Driver for the JDBC Interface connection to a Teradata Database, enter the following URL: jdbc:teradata://DatabaseServerName/Param1,Param2,... where: Table 9: URL String Syntax Element Description DatabaseServerName Name of the server running the Teradata Database Param1, Param2... [Optional] list of connection parameters, as described in Table 10. • ACCOUNT=account_id • CHARSET={ASCII/LATIN1_0A/KANJISJIS_0S/KANJIEUC_0U/ LATIN9_0A/LATIN1252_0A/HANGULKSC5601_2R4/ SCHGB2312_1T0/TCHBIG5_1R0/UTF8/UTF16} The EBCDIC character sets are only supported on MVS®. • • • • COMPAT_DBS=true/false COMPAT_ISAUTOINC=true/false COMPAT_ISCURRENCY=true/false COMPAT_ISSIGNED=true/false • COMPAT_ISSEARCH=true/false • • • • • • • 44 COMPAT_ISREADONLY=true/false COMPAT_ISWRITABLE=true/false COMPAT_ISDEFWRIT=true/false COMPAT_GETSCHEMA=ReturnValue COMPAT_GETTABLE=ReturnValue DATABASE=default database name DBS_PORT=number Teradata Driver for the JDBC Interface User Guide Chapter 2: Using the Teradata Driver for the JDBC Interface Making a Teradata Database Connection Table 9: URL String (continued) Syntax Element Description • • • • • • • • • • • • • • • ENCRYPTDATA={ON/OFF} GOVERN={ON/OFF} LOB_SUPPORT={ON/OFF} LOB_TEMP_TABLE=tableName or databaseName.tableName LOG={ERROR/INFO/DEBUG} LOGDATA=varies according to the LOGMECH selection LOGMECH={TD1/TD2/KRB5/LDAP} NEW_PASSWORD=new password string PARTITION= {DBC/SQL,MONITOR} SESSIONS=n, where 1 <= n <= number of AMPs SP_SPL={SPL/NOSPL} TMODE={ANSI/TERA/DEFAULT} TSNANO={0...6} TYPE={DEFAULT/FASTLOAD} USEXVIEWS={ON/OFF} Table 10 lists the Database Connection parameters. Table 10: Database Connection Parameters Parameter Description ACCOUNT The account to be charged on network-attached clients. Maximum length of account id is 30 characters. ACCOUNTID This connection parameter is deprecated. Use the ACCOUNT parameter instead. Teradata Driver for the JDBC Interface User Guide 45 Chapter 2: Using the Teradata Driver for the JDBC Interface Making a Teradata Database Connection Table 10: Database Connection Parameters (continued) Parameter Description CHARSET Character set for a particular session to the Teradata Database. The supported character sets include: • • • • • • • • • • • ASCII LATIN1_0A KANJISJIS_0S KANJIEUC_0U LATIN9_0A LATIN1252_0A HANGULKSC5601_2R4 SCHGB2312_1T0 TCHBIG5_1R0 UTF8 UTF16 (To use UTF16 with Kerberos or Lightweight Directory Access Protocol (LDAP) authentication, the Teradata Driver for the JDBC Interface must be Version 3.3 or later, and the Teradata Database must be V2R6.1 or later.) This parameter is supported for the Default Connection for Java External Stored Procedures. Only three character sets are supported for Java Stored procedures: ASCII, UTF16, and UTF8. Note: The Extended Binary-Coded Decimal Interchange Code (EBCDIC) character sets are only supported on MVS. The default value is set to ASCII. COMPAT_DBS This parameter is only needed for Teradata Database V2R6.1 and earlier. (Type 4 driver only) This option is required if the following options are specified: COMPAT_ISAUTOINC COMPAT_ISCURRENCY COMPAT_ISSIGNED COMPAT_ISSEARCH COMPAT_ISREADONLY COMPAT_ISWRITABLE COMPAT_ISDEFWRIT COMPAT_GETSCHEMA COMPAT_GETTABLE to call the following ResultSetMetaData methods: isAutoIncrement() isCurrency() isSigned() isSearchable() isReadOnly() isWritable() isDefinitelyWritable() getSchemaName() getTableName(). Otherwise, DriverManager.getConnection() throws an SQLException. 46 Teradata Driver for the JDBC Interface User Guide Chapter 2: Using the Teradata Driver for the JDBC Interface Making a Teradata Database Connection Table 10: Database Connection Parameters (continued) Parameter Description COMPAT_ISAUTOINC This parameter is only needed for Teradata Database V2R6.1 and earlier. This option provides the default return value for the method call: resultSetMetaData.isAutoIncrement(). When COMPAT_DBS=true, the values from the Teradata Database are used if provided by the database; the COMPAT_ISAUTOINC value is used only when the database does not provide the value. When COMPAT_DBS=false, this default COMPAT_ISAUTOINC value is always used, regardless of whether the database returns the data. COMPAT_ISCURRENCY This parameter is only needed for Teradata Database V2R6.1 and earlier. This option provides the default return value for the method call: resultSetMetaData.isCurrency(). When COMPAT_DBS=true, the values from the Teradata Database are used if provided by the database; the COMPAT_ISCURRENCY value is used only when the database does not provide the value. When COMPAT_DBS=false, this default COMPAT_ISCURRENCY value is always used, regardless of whether the database returns the data. COMPAT_ISSIGNED This parameter is only needed for Teradata Database V2R6.1 and earlier. This option provides the default return value for the method call: resultSetMetaData.isSigned(). When COMPAT_DBS=true, the values from the Teradata Database are used if provided by the database; the COMPAT_ISSIGNED value is used only when the database does not provide the value. When COMPAT_DBS=false, this default COMPAT_ISSIGNED value is always used, regardless of whether the database returns the data. COMPAT_ISSEARCH This parameter is only needed for Teradata Database V2R6.1 and earlier. This option provides the default return value for the method call: resultSetMetaData.isSearchable(). When COMPAT_DBS=true, the values from the Teradata Database are used if provided by the database; the COMPAT_ISSEARCH value is used only when the database does not provide the value. When COMPAT_DBS=false, this default COMPAT_ISSEARCH value is always used, regardless of whether the database returns the data. COMPAT_ISREADONLY This parameter is only needed for Teradata Database V2R6.1 and earlier. This option provides the default return value for the method call: resultSetMetaData.isReadOnly() When COMPAT_DBS=true, the values from the Teradata Database are used if provided by the database; the COMPAT_ISREADONLY value is used only when the database does not provide the value. When COMPAT_DBS=false, this default COMPAT_ISREADONLY value is always used, regardless of whether the database returns the data. Teradata Driver for the JDBC Interface User Guide 47 Chapter 2: Using the Teradata Driver for the JDBC Interface Making a Teradata Database Connection Table 10: Database Connection Parameters (continued) Parameter Description COMPAT_ISWRITABLE This parameter is only needed for Teradata Database V2R6.1 and earlier. This option provides the default return value for the method call: resultSetMetaData.isWritable(). When COMPAT_DBS=true, the values from the Teradata Database are used if provided by the database; the COMPAT_ISWRITABLE value is used only when the database does not provide the value. When COMPAT_DBS=false, this default COMPAT_ISWRITABLE value is always used, regardless of whether the database returns the data. COMPAT_ISDEFWRIT This parameter is only needed for Teradata Database V2R6.1 and earlier. This option provides the default return value for the method call: resultSetMetaData.isDefinitelyWritable() When COMPAT_DBS=true, the values from the Teradata Database are used if provided by the database; the COMPAT_ISDEFWRIT value is used only when the database does not provide the value. When COMPAT_DBS=false, this default COMPAT_ISDEFWRIT value is always used, regardless of whether the database returns the data. COMPAT_GETSCHEMA This parameter is only needed for Teradata Database V2R6.1 and earlier. This option provides the default return value for the method call: resultSetMetaData.getSchemaName() When COMPAT_DBS=true, the values from the Teradata Database are used if provided by the database; the COMPAT_GETSCHEMA value is used only when the database does not provide the value. When COMPAT_DBS=false, this default COMPAT_GETSCHEMA value is always used, regardless of whether the database returns the data. COMPAT_GETTABLE This parameter is only needed for Teradata Database V2R6.1 and earlier. This option provides the default return value for the method call: resultSetMetaData.getTableName(). When COMPAT_DBS=true, the values from the Teradata Database are used if provided by the database; the COMPAT_GETTABLE value is used only when the database does not provide the value. When COMPAT_DBS=false, this default COMPAT_GETTABLE value is always used, regardless of whether the database returns the data. DATABASE DATABASE=default database name This parameter is used when the application requires that a default database is set at logon time. 48 DBS_PORT Connects to the Teradata Database on the Transmission Control Protocol/Internet Protocol (TCP/IP) port specified. The default Teradata Database port is 1025. DEBUG This Database Connection Parameter has been removed from the driver. Teradata Driver for the JDBC Interface User Guide Chapter 2: Using the Teradata Driver for the JDBC Interface Making a Teradata Database Connection Table 10: Database Connection Parameters (continued) Parameter Description ENCRYPTDATA ENCRYPTDATA values are ON or OFF: • When set to ON, data sent between the JDBC driver and Teradata is encrypted. This provides greater security, though performance is impacted. • Encryption algorithms are associated with Logon Mechanisms, so the LOGMECH parameter determines which encryption method is available. The ENCRYPTDATA parameter then determines whether or not it is used. featureProps This Database Connection Parameter has been removed from the driver. GOVERN GOVERN values are ON (default) or OFF: • When set to ON (the default), permits Teradata Active System Management (TASM) to delay a JDBC FastLoad operation. When TASM is enabled in the Teradata Database, FastLoad operations are controlled by TASM, which may delay or reject a FastLoad operation according to the TASM rules. If TASM is disabled, a FastLoad operation will not be delayed, although it may still be rejected if it exceeds the maximum permitted number of concurrent FastLoad operations. The limit is configured in the Teradata Database. • When set to OFF, prevents TASM from delaying a JDBC FastLoad operation. A JDBC FastLoad operation will be rejected, but never delayed, if the FastLoad operation exceeds a TASM limit or system limit, and an SQLException will be thrown with error code 2633. This behavior will occur regardless of whether TASM is enabled or disabled. LOB_SUPPORT LOB_SUPPORT=ON enables Large Object (LOB) support when connecting to a Teradata Database. The default is ON. This switch must be turned ON if the application: • Selects or inserts LOB data • Uses Scrollable Result Sets • Uses Updatable Result Sets Turning LOB_SUPPORT ON forces the application to have no more than 16 open requests at one time, including any SQL request – insert, delete, and update. This parameter is supported for the Default Connection for Java External Stored procedures. See “Large Object Interface” on page 312 if you receive “Response limit exceeded” errors. LOB_TEMP_TABLE The name of a table with the following columns: id integer, bval blob, cval clob The user or the application must have previously created the table. The Teradata Driver for the JDBC Interface will not automatically create the table. See Updatable LOBs for more information. Teradata Driver for the JDBC Interface User Guide 49 Chapter 2: Using the Teradata Driver for the JDBC Interface Making a Teradata Database Connection Table 10: Database Connection Parameters (continued) Parameter Description LOG Sets a connection’s log level. Logging is always enabled: • LOG=ERROR causes error messages for that connection to be printed to System.out. This is the default value. • LOG=INFO causes error and informational messages for that connection to be printed to System.out. • LOG=DEBUG causes error, informational, and debug messages for that connection to be printed to System.out This parameter is supported for the Default Connection for Java External Stored procedures. LOGDATA This represents additional data needed by a mechanism. This is where information such as a secure token, Distinguished Name, or a domain/ realm name can be passed for processing. LOGDATA use varies with the mechanism selected. • TD1 – not used • TD2 – not used • KRB5 – Can contain Kerberos username, instance, realm and password. Use is optional, the current user can logon without supplying this information. The sequence @@ always precedes the password. For example: [email protected]@@mypassword • LDAP – A Lightweight Directory Access Protocol (LDAP) LOGDATA can contain spaces, commas, and single quotes. When using this parameter with a DriverManager getConnection method, the LDAP LOGDATA parameter is always enclosed in single quotes. Within that string, a double-single quote can be used to represent an instance of a single quote. When setting this parameter with a DataSource, no special processing is required. For example: LOGDATA='dn:cn=John Smith,cn=users,dc=corp,dc=ncr,dc=com password=secret' 50 Teradata Driver for the JDBC Interface User Guide Chapter 2: Using the Teradata Driver for the JDBC Interface Making a Teradata Database Connection Table 10: Database Connection Parameters (continued) Parameter Description LOGMECH This is the Logon Mechanism. It determines both the sort of authentication used and the type of encryption to support on the connection. More detail on the mechanisms supported is available in Security Administration. • TD1 – Teradata Method 1 • TD2 – Teradata Method 2 (stronger encryption than method 1) • KRB5 – Kerberos V5 (Kerberos is only supported when both the Teradata Driver for the JDBC Interface and the Teradata Database are running on Windows platforms.) • LDAP Use a user-defined name in cases where the user-defined methods have been created. In the case where no LOGMECH is specified, the Teradata Driver for the JDBC Interface uses the local default mechanism. If this default doesn't exist, the default mechanism, as specified by the Teradata Database, is used. In the case where a LOGMECH value is requested that cannot be supported, an SQL exception is thrown. Teradata Driver for the JDBC Interface User Guide 51 Chapter 2: Using the Teradata Driver for the JDBC Interface Making a Teradata Database Connection Table 10: Database Connection Parameters (continued) Parameter Description NEW_PASSWORD This connection parameter enables an application to change an expired password automatically. When a connection is established for a user with an expired password, it is a conditional connection. The only SQL request that can be submitted on a conditional connection is a MODIFY USER statement that assigns a new password to the user. Each Teradata Database user is allowed only one conditional connection at a time. To submit a new password for the user, all previously established connections for the user need to be ended, across all Teradata client products and interfaces such as Basic Teradata Query (BTEQ), SQL Assistant (SQLA), the Teradata Driver for the JDBC Interface, and so forth. When a conditional connection is established for a user with an expired password and the NEW_PASSWORD parameter: • Is specified and set to a non-empty password value–the Teradata Driver for the JDBC Interface automatically submits a MODIFY USER statement to the Teradata Database to update the user’s password. The Connection.getWarnings method returns null. • Is not specified–the Connection.getWarnings method returns an SQLWarning with Teradata Database error code 3032 to indicate an expired password. The application can submit a MODIFY USER statement to assign a new password to the user. After the MODIFY USER statement successfully changes the expired password, the connection is no longer conditional—the connection can be used normally. Note that when the NEW_PASSWORD connection property is specified for an application server DataSource and the Teradata Driver for the JDBC Interface automatically changes the expired password, the original password defined in the application server DataSource is not updated. The application can either: • Make the original password and the NEW_PASSWORD value the same, which allows a single DataSource to be used, or • Define multiple DataSources in a cycle whose passwords chain to each other so that each DataSource’s NEW_PASSWORD value matches the next DataSource’s password. The application needs to keep track of which DataSource is the current DataSource. This technique is complex, but it offers the security of being able to specify the set of passwords in DataSource definitions separate from the application and to control centrally from the Teradata Database when the password should change. PARTITION Specifies the protocol to be used with the Teradata Database for SQL statements. The default is DBC/SQL. • DBC/SQL – directs the Teradata Driver for the JDBC Interface to use the standard protocol for all SQL statements • MONITOR – directs the Teradata Driver for the JDBC Interface to use the Monitor protocol for all SQL statements 52 Teradata Driver for the JDBC Interface User Guide Chapter 2: Using the Teradata Driver for the JDBC Interface Making a Teradata Database Connection Table 10: Database Connection Parameters (continued) Parameter Description SESSIONS Specifies the number of FastLoad connections to be created, where 1 <= number of FastLoad connections <= number of AMPs. The default value is 8 or the number of AMPs if the number of AMPs is less than 8. Note: It is generally recommended to select the default value; that is, let the Teradata Driver for the JDBC Interface create the appropriate number of FastLoad connections. SP_SPL This parameter is only used when creating or replacing Teradata stored procedures. This parameter is supported for the Default Connection for Java External Stored procedures. When this flag is set to NOSPL, it indicates to the Teradata Database server not to store Stored Procedure Language (SPL) source text. For such stored procedures, the SHOW PROCEDURE SQL statement returns an error/failure. The default value is SPL. TMODE Allows the selection of the database transaction mode. There are two transaction modes: • American National Standards Institute (ANSI) • Teradata Teradata mode provides compatibility with existing applications. New users use ANSI mode. This parameter overrides the default transaction mode of the Teradata Database. Refer to SQL Reference: Statement and Transaction Processing for more information regarding the Teradata transaction modes. TNANO TSNANO TNANO is the fractional seconds precision for the time datatype. If this value is set, then a preparedStatement.setTime() results in a time with the specified precision. For example, if TNANO is set to 3, then 10:02:30 is sent to the database as 10:02:30.000. This the same with TSNANO, except that it is used for timestamps. TNANO and TSNANO parameters support the Default Connection for Java External Stored procedures. If using stored procedures with time or timestamp parameters, then these URL parameters are to match the fractional second precision of the stored procedure parameters. Example URL jdbc:teradata: //cs4300s1/TSNANO=6,TNANO=3 Teradata Driver for the JDBC Interface User Guide 53 Chapter 2: Using the Teradata Driver for the JDBC Interface Making a Teradata Database Connection Table 10: Database Connection Parameters (continued) Parameter Description TYPE Specifies the type of protocol to be used with the Teradata Database for SQL statements. Options are: • DEFAULT–directs the Teradata Driver for the JDBC Interface to use the standard protocol for all SQL statements • FASTLOAD–directs the Teradata Driver for the JDBC Interface to use the FastLoad protocol for FastLoad-capable SQL INSERT statements and the standard protocol for all other SQL statements The default is DEFAULT. USEXVIEWS The USEXVIEWS parameter instructs the Teradata Driver for the JDBC Interface to use X views for retrieval of DatabaseMetaData instead of non-X views (USEXVIEWS=ON). The X views of various tables used to obtain metadata provide extra security checks and generally return less data than a corresponding selection of a non-X view. These security checks do have a performance penalty and, as a result, the use of X views is slower than non-X views. Refer to Teradata Database Data Dictionary for additional information on X views. The default is USEXVIEWS=OFF. Data Source Interface When using an application server, the preferred way to obtain a java.sql.Connection is to use the java.sql.DataSource interface. Each application server provides its own way to configure JDBC Data Sources. Refer to the application server how-to documentation included in the Teradata Driver for the JDBC Interface download package for information on using the Teradata Driver for the JDBC Interface with supported application servers. DataSource allows the encapsulation all of the parameters associated with obtaining a database connection in one object that has a logical name. You can then just ask for a connection to that name (for example, Teradata1) and not have to be aware of the numerous parameters that are required to fulfill this request. A DataSource must be created before it can be used. This job is normally done by a system administrator. The work involved amounts to setting the parameters associated with a Driver Manager URL into the DataSource object and saving it as a file or network-addressable resource. The names of these parameters must be identical to their names used in the URL, including capitalization. For example, if CHARSET is used to set the character set property, then CharSet, CHARSet or CHARSEt would not set it. Additional properties dataSourceName, description, user and password are only available at the DataSource level. Refer to “TeraDataSource Methods” on page 264 for additional information. DataSources are accessed with the JNDI. For more information, check: http://java.sun.com/products/jndi/ 54 Teradata Driver for the JDBC Interface User Guide Chapter 2: Using the Teradata Driver for the JDBC Interface Making a Teradata Database Connection With pooled connections, it is very important that the connection be closed when the user no longer needs it. Otherwise, it is not returned to the connection pool. When using pooled connections, it is advisable to have a finally block after try/catch blocks to ensure that connections are closed. Session Defaults Warning Teradata does not provide any means to reset a connection. Therefore, the user of a connection pool data source, must be aware that any commands that affect session defaults must not be used. Any changes to session defaults continue to be in effect for the next unsuspecting user of that connection. Session Parameters That Must Not be Changed Session parameters that MUST NOT BE CHANGED include: • Database (SET SESSION DATABASE command) • Collation (SET SESSION COLLATION command) • Character Set • Transaction Semantics • Dateform (SET SESSION DATEFORM command) • Timezone (SET TIME ZONE command) • Default date format • QueryBand (SET QUERY_BAND … FOR SESSION command, introduced with Teradata Database 12.00.00) Note: The SET QUERY_BAND … FOR TRANSACTION command is recommended as an alternative to SET QUERY_BAND … FOR SESSION because SET QUERY_BAND … FOR TRANSACTION is limited in scope to the current transaction. Type 4 COP Discovery The Type 4 Teradata Driver for the JDBC Interface mimics the Communications Processor (COP) discovery behavior of CLI. The Type 4 driver first finds all defined COPs. The driver starts with COP1, which is appended to the database hostname, and then proceeds with COP2, COP3, ..., COPn until an undefined name is reached. For the first access to that database, the Type 4 driver generates a random number to index into the list of COPs. For each subsequent access, the Type 4 driver increments the saved index until it wraps around to the first position. This behavior provides load distribution across all defined COPs. The Type 4 driver masks connection failures to downed COPs, thereby hiding most connection failures from the client application. The client application recognize a database connection failure if all the COPs are down for that database. If a COP is down, the next COP in the sequence (including a wrap-around to the first COP) receives extra connections that were originally destined for the down COP. Teradata Driver for the JDBC Interface User Guide 55 Chapter 2: Using the Teradata Driver for the JDBC Interface LogonSource Format If no HostNameCOPnnn names are defined in the Domain Name System (DNS), the Type 4 driver connects directly to the database hostname provided in the connection URL. This permits load distribution schemes other than the COP discovery approach. For example, a round-robin DNS or a TCP/IP load distribution product can be used. Because COP discovery takes precedence over simple database hostname lookup, ensure that no HostNameCOPnnn names are defined in DNS if an alternative load distribution scheme is in use. JVM caches DNS lookups, and the Teradata Driver for the JDBC Interface does not maintain its own cache of DNS name resolutions. The administrator can use the standard JVM system properties for cache control as defined in the javadoc for the InetAddress class: InetAddress Caching The InetAddress class caches to store successful as well as unsuccessful host name resolutions. The positive caching is there to guard against DNS spoofing attacks; while the negative caching is used to improve performance. By default, the result of positive host name resolutions are cached forever, because there is no general rule to decide when it is safe to remove cache entries. The result of unsuccessful host name resolution is cached for a very short period of time (10 seconds) to improve performance. Under certain circumstances where it can be determined that DNS spoofing attacks are not possible, a Java security property can be set to a different Time-to-live (TTL) value for positive caching. Likewise, a system administrator can configure a different negative caching TTL value when needed. Two Java security properties control the TTL values used for positive and negative host name resolution caching: networkaddress.cache.ttl (default: -1) indicates the caching policy for successful name lookups from the name service. The value is specified as an integer to indicate the number of seconds to cache the successful lookup. A value of -1 indicates cache forever. networkaddress.cache.negative.ttl (default: 10) indicates the caching policy for unsuccessful name lookups from the name service. The value is specified as an integer to indicate the number of seconds to cache the failure for unsuccessful lookups. A value of 0 indicates never cache. A value of -1 indicates cache forever. LogonSource Format When the Teradata Driver for the JDBC Interface establishes a connection to the Teradata Database, the Teradata Driver for the JDBC Interface composes a string value that is stored in 56 Teradata Driver for the JDBC Interface User Guide Chapter 2: Using the Teradata Driver for the JDBC Interface LogonSource Format the Data Dictionary System Views LogonSource column, which is included in system views such as DBC.SessionInfo and DBC.LogOnOff. Note: All LogonSource values provided by Teradata Driver for the JDBC Interface and other clients are entered into the database in uppercase. The Teradata Driver for the JDBC Interface follows the format documented in the Teradata Data Dictionary, section “System Views Columns Reference”, for network-attached LogonSource values. Network-attached LogonSource values have eight fields, separated by whitespace. Teradata Database composes fields 1 through 3; the Teradata Driver for the JDBC Interface composes fields 4 through 8. 1 The literal “(TCP/IP)”, to indicate the connection type 2 TCP port number on the client system, in hexadecimal 3 IP address of the client system 4 Teradata Database hostname, known as the Teradata Directory Program Identifier “TDPID” 5 Client process/thread identifier 6 Client system user ID 7 Program used on the client system 8 The literal “01 LSS”, to indicate LogonSource string version 01 Fields 4 through 8 are described in detail in the following sections. Warning: The information in this section is subject to change in future releases of the Teradata Driver for the JDBC Interface. Teradata strongly recommends that applications do not parse LogonSource values. Any applications that parse LogonSource values will have to be changed if the LogonSource format is changed in the future. All client information refers to the system running JVM containing the Teradata Driver for the JDBC Interface. Typically, this is an application server. Client information does not refer to any other clients, such as a web browser, that may be communicating with the application server. Example LogonSource value 1 2 3 4 5 6 7 12345678901234567890123456789012345678901234567890123456789012345678901 <--set by Teradata Database--><--------------set by client-------------> (TCP/IP) 11AB 153.64.135.140 CHARON;CHARONCOP1/153.64.116.144:1025 (TCP/IP) 11AB 153.64.135.140 CHARON.SANDIEGOCA.NCR.COM;CHARONCOP1.SAND ----------------------------- ----------------------------------------1 2 3 4 12345678901234567890123456789012345678901 Truncated to the space remaining in the 97 chars, after the subsequent fields are composed Teradata Driver for the JDBC Interface User Guide c o n t i n u e d b e l o w 57 Chapter 2: Using the Teradata Driver for the JDBC Interface LogonSource Format c o n t i n u e d f r o m a b o v e 7 8 9 10 11 12 234567890123456789012345678901234567890123456789012345678 <------------------set by client-------------------------> CID=C2A132 ROOTUSER JDBC03.02.00.00;1.4.2_01 01 LSS CID=C2A132 ROOTUSER JDBC03.02.00.00;1.4.2_01 01 LSS ------------ -------- -------------------------- -----1 1 2 123456789012 12345678 12345678901234567890123456 123456 Will be 12 chars or less Trunc'ed Trunc'ed to 26 chars to 20 chars (may be less) (may be less) Hardcoded 6 chars Fields are separated from each other by exactly one space character. Field 4 - TDPID (target Teradata Database hostname) Field The TDPID field is composed of: • Original Teradata Database hostname specified by application (without a COPnnn suffix). For example, cs4300sl. • followed by a semicolon: “;” • and the Hostname or IP address of Teradata Database node that was connected. For example, CS4300S1COP1/153.64.116.95. • followed by a colon: “:” • and the Port of the Teradata Database node that was connected. For example, 1025. This TPID field is truncated to the space remaining in the 97 chars, after all the other fields are composed. An example value for this field when an application specifies the Teradata Database hostname “cs4300s1” is: CS4300S1;CS4300S1COP1/153.64.116.95:1025 An example truncated value for this field when an application specifies a Teradata Database hostname of “cs4300s1.sandiegoca.ncr.com” is: CS4300S1.SANDIEGOCA.NCR.COM;CS4300S1COP1.SAN Field 5 - Client Process ID/Thread ID Field Note: The Teradata Driver for the JDBC Interface does not provide the Java Thread ID for this field. In an application server environment, threads are not tied to particular database connections, so any particular thread can execute requests on a connection originally created by a different thread. To avoid potential confusion, the Teradata Driver for the JDBC Interface provides a connection ID for field 5 containing the LogonSource value. The connection ID is also provided in exception and log messages, which enable connection ID values to be correlated between LogonSource values and exception and log messages. The Teradata Driver for the JDBC Interface always prefixes connection ID values with the prefix “cid=”, to make it easy to distinguish connection ID values from other values. 58 Teradata Driver for the JDBC Interface User Guide Chapter 2: Using the Teradata Driver for the JDBC Interface Program Examples The connection ID is the hash code of the connection object. It provides a simple unique identifier for a particular connection to the Teradata Database. The Client Process/Thread ID field is composed of: • CID= • followed by the Connection ID An example value for this field is: CID=1E51060 Field 6 - Client Process User Field The Client Process User field is composed of System.getProperty("user.name") This field is truncated to 20 chars, but can be shorter. An example value for this field is: ROOTUSER Field 7 - Client Program Name Field The Client Program Name field is composed of: • JDBC • followed by the JDBC driver version, for example, 03.02.00.00 • followed by a semicolon “;” • then the System.getProperty(“java.version”), for example, 1.4.2_04 This field is truncated to 26 chars, but can be shorter. An example value for this field is: JDBC03.02.00.00;1.4.2_04 Field 8 - LogonSource string version 1 This field is composed of 01 LSS. Program Examples Example programs that demonstrate the use of the Teradata Driver for the JDBC Interface are available from the Download Center at http://www.teradata.com. The example programs are distributed in a platform-independent jar file, samples.jar, which contains the source code and the compiled class files for the example programs. Converting Sample files from Java to EBCDIC for z/OS USS Users on the z/OS USS must convert the .java files in samples.jar once they are extracted from the jar file to use them with the operating system. The .java source files in samples.jar are in ASCII but z/OS USS expects EBCDIC files. To get around this, the user needs to convert the .java source files to EBCDIC files using the “iconv” tool. Teradata Driver for the JDBC Interface User Guide 59 Chapter 2: Using the Teradata Driver for the JDBC Interface Running a Sample Application An example that shows how to use this tool to convert sample1.java from ASCII to EBCDIC would be: iconv -f ISO8859-1 -t IBM-1047 sample1.java > sample1-ebcdic.java Running a Sample Application To run a sample application Use the following procedure to run a sample application. 1 Download a supported JDK to the development platform 2 Download and copy samples.jar, terajdbc4.jar, tdgssjava.jar, and tdgssconfig.jar to the development platform. The following commands assume that all four files are copied to the same directory on the development platform. 3 Go to the directory where samples.jar is located and unjar the sample applications: jar xvf samples.jar 4 5 Modify the sample application sample1.java with Teradata Database information. Change the following: • Name of the Teradata Database • User id and password for the Teradata Database Compile the modified sample application by entering the following: javac sample1.java 6 [Windows only]Run the application on Windows by entering the following: java -classpath .;terajdbc4.jar;tdgssjava.jar;tdgssconfig.jar sample1 7 [UNIX only]Run the application on UNIX by entering the following: java -classpath .:terajdbc4.jar:tdgssjava.jar:tdgssconfig.jar sample1 Note: The . entry, representing the current directory on the classpath in the preceding commands is what enables Java to locate the sample1.class file. Running on Sun Solaris SPARC This section describes the options to use when compiling and running an application on Sun Solaris SPARC 32-bit and 64-bit operating systems. Sun Solaris SPARC To run an application on Sun Solaris SPARC, use one of the following commands: java -classpath .:terajdbc4.jar:tdgssjava.jar:tdgssconfig.jar sample1 java -d32 -classpath .:terajdbc4.jar:tdgssjava.jar:tdgssconfig.jar sample1 java -d64 -classpath .:terajdbc4.jar:tdgssjava.jar:tdgssconfig.jar sample1 The first and second examples run the application sample in 32-bit mode, the default. The third example with the -d64 option runs the application sample in the 64-bit mode. The -d64 option may only be used on 64-bit Solaris systems. 60 Teradata Driver for the JDBC Interface User Guide Chapter 2: Using the Teradata Driver for the JDBC Interface Source File Locations for JDBC Currently only the Java HotSpot Server VM supports 64-bit operation, and the -server option is implicit with the use of -d64. If neither -d32 nor -d64 is specified, the default is to run in a 32-bit environment. Source File Locations for JDBC The Teradata Driver for the JDBC Interface can create UDFs, UDMs, or XSPs from source files that are stored on the server or the client. Source files stored on the client must be transferred from the client node to the server node. For security purposes, the Teradata Driver for the JDBC Interface uses the classpath to load all resources. This requires the source file on the client to be on the classpath. Once the classpath is set, the Teradata Driver for the JDBC Interface can transfer the source file to the server node. Updatable LOBs Temporary Table Before LOB updates can be used with the Teradata Driver for the JDBC Interface, a table must be created with the following columns: • • • id integer bval blob cval clob For normal application usage, the Teradata Database Administrator creates the table as a Global Temporary Table (GTT). However, the table could be a regular table for special usage cases, such as for debugging. The id integer column is intended to be the primary index. If desired, it could be specified as a unique primary index. When the GTT is created with CREATE TABLE, the ON COMMIT PRESERVE ROWS clause must be specified, so that the Teradata Driver for the JDBC Interface can manipulate LOBs across transactions. In the example that follows, the table name JdbcLobUpdate is just a suggestion; any name can be chosen for the table: create global temporary table JdbcLobUpdate( id integer not null, bval blob, cval clob character set unicode) unique primary index upi_JdbcLobUpdate(id) on commit preserve rows Connection Parameter The Connection parameter LOB_TEMP_TABLE must be set to the name chosen for the temporary table. Teradata Driver for the JDBC Interface User Guide 61 Chapter 2: Using the Teradata Driver for the JDBC Interface SQL Literals and SQL Injection Attacks LOB_TEMP_TABLE=tableName [Optional]Specify a database name: LOB_TEMP_TABLE=databaseName.tableName See Table 10 on page 45 for more information on Database Connection parameters. Update LOB If an application wants to update an existing LOB value in a table, then after calling any LOB update methods, the application must also execute an UPDATE statement to put the modified LOB value back into the original row. The Teradata Driver for the JDBC Interface returns true from DatabaseMetaData locatorsUpdateCopy to indicate that the implementation updates a copy of the LOB. ResultSet rs = stmt.executeQuery(“SELECT id,data FROM datatab”); rs.next(); int id = rs.getInt(1); Blob data = rs.getBlob(2); int numWritten = data.setBytes(1, val); if (dbmd.locatorsUpdateCopy() == true){ PreparedStatement ps = conn.prepareStatement( “UPDATE datatab SET data = ? WHERE id = ?”); try { ps.setBlob(1, data); ps.setInt(2, id); ps.executeUpdate(); } finally { ps.close(); } } SQL Literals and SQL Injection Attacks Applications that compose SQL requests containing SQL string literals must take care to properly escape single-quote characters. An SQL string literal is enclosed by single-quotes, for example: 'New York'. To use a single-quote character in an SQL string literal, the single-quote character must be repeated, for example: 'Joe”s Diner'. Applications that compose SQL requests based on user input, such that the user input is directly substituted into the SQL text string, may be vulnerable to an SQL Injection attack. For example, an application prompts the user to enter a person's last name, and then composes a query to search for all people with that last name: String sql = "SELECT * FROM customer WHERE lastname = '" + lastname + "'" In this example, notice that the hardcoded part of the SQL text includes the single-quote characters to be used on each side of the SQL string literal. This technique works only if the user's input value never includes any single quotes. 62 Teradata Driver for the JDBC Interface User Guide Chapter 2: Using the Teradata Driver for the JDBC Interface Multi-Threading Issues However, if the user specifies “O'Malley” as a last name, then the application will erroneously compose the following query, which is then rejected by the database as a syntax error: SELECT * FROM customer WHERE lastname = 'O'Malley' An SQL Injection attack takes advantage of this kind of defect in the application code to do something malicious. For example, the malicious input value would be: x';delete from important_table;select 'x which would cause the application to compose the SQL text string: SELECT * FROM customer WHERE lastname = 'x';delete from important_table;select 'x' In this example, the malicious user carefully chose a value that works with the hardcoded single-quote characters on each side of the input value. The database would successfully execute the SQL string and, assuming that the malicious user had write-access to the important table, would delete all the rows from the important table, with a result being a denial of service. Applications must be coded to handle single-quote characters, and to correctly compose SQL requests. The most common recommendation to protect against SQL Injection attack is to use prepared statements so that users cannot modify the SQL text; the user's input values are only used as bind parameter values for prepared statements. If it is not possible for the application to use prepared statements, such as for composing Data Definition Language (DDL) commands, then another common recommendation is to validate and escape the user's input values. For example: • If the user's input is a number, then the application must verify that the user's input value consists of numeric digits only, before the user's input value is concatenated into the SQL text string • If the user's input value is used inside an SQL string literal, then the user's input value must be scanned for any single-quote characters, and each single-quote character must be repeated, before the user's input value is concatenated into the SQL text string. On the database side, the database unescapes each pair of single-quote characters in the SQL string literal, to be one single-quote character. Multi-Threading Issues Using multi-threading can improve the applications performance. Determine which requests can run at the same time and then using multiple concurrent sessions, submit a request on each session. It is strongly discouraged to try and submit more than one concurrent request per session. Note: The Teradata Database does not support more than one active request per session. If the user attempts to do this, then the Teradata Driver for the JDBC Interface blocks until the previous request has returned. This may negatively impact performance. Teradata Driver for the JDBC Interface User Guide 63 Chapter 2: Using the Teradata Driver for the JDBC Interface Using Type 4 Driver with ResultSetMetaData Methods Table 11 contains JDBC Object Thread safety information. Table 11: JDBC Object Thread Safety JDBC Object Thread Safety Connection Connection objects are fully thread-safe, and can be used by multiple threads. However, only one request is executed at a time. Subsequent requests block until the previous request completes executing. Statement, PreparedStatement, CallableStatement Statement and its subclass objects are generally not thread-safe. One specific case is supported. A second thread can call the cancel() method to interrupt an executing request. ResultSet ResultSet objects are not thread-safe. A ResultSet object should only be used by a single thread. A ResultSet object contains state information that is not thread-safe, such as the wasNull state to indicate whether the most recently called getter method returned a NULL. Blob, Clob Blob and Clob objects are not thread-safe. A Blob or Clob object should only be used by a single thread. A Blob/Clob object should be retrieved from a ResultSet by the thread that owns the ResultSet using the ResultSet.getBlob/getClob method. After the Blob/Clob object has been retrieved from a ResultSet, it can be used by a different thread. Thus, multiple threads can be used to access LOB data; however, each Blob/Clob object itself should only be used by one thread. Multi-threading on IBM AIX 5.1 and Using 64-bit JDK on Microsoft Windows When using the Type 4 Teradata Driver for the JDBC Interface Release 03.02.00 with the JDK Version 1.4 on IBM AIX 5.1 and 64-bit JDK on Microsoft Windows, some occurrences of multi-threaded applications hang and do not return a prompt to the screen. This occurs only with the JDK 1.4 version. A workaround exists. Run the Java application by turning off the JIT with the following command: java -Djava.compiler=NONE <Java application name> Using Type 4 Driver with ResultSetMetaData Methods All ResultSetMetaData methods are supported with Teradata Database V2R6.2 and later. With Teradata Database V2R6.1 and earlier releases, the Type 4 Teradata Driver for the JDBC Interface throws an SQL Exception when the following nine ResultSetMetaData methods are invoked: • 64 isAutoIncrement() Teradata Driver for the JDBC Interface User Guide Chapter 2: Using the Teradata Driver for the JDBC Interface Using Type 4 Driver with Sun JDK 5.0 Implementation of JDBC RowSet Interface • isCurrency() • isSigned() • isSearchable() • isReadOnly() • isWritable() • isDefinitelyWritable() • getSchemaName() • getTableName() These nine methods are supported in the Type 4 driver when connected to Teradata Database V2R6.2 and later, but are not supported with Teradata Database V2R6.1 and earlier releases. To use these methods in your applications with Teradata Database V2R6.1 and earlier releases, supply the following URL options: COMPAT_DBS=true/false COMPAT_ISAUTOINC=true/false COMPAT_ISCURRENCY=true/false COMPAT_ISSIGNED=true/false COMPAT_ISSEARCH=true/false COMPAT_ISREADONLY=true/false COMPAT_ISWRITABLE=true/false COMPAT_ISDEFWRIT=true/false COMPAT_GETSCHEMA=ReturnValue COMPAT_GETTABLE=ReturnValue Refer to the tables in “Making a Teradata Database Connection” on page 43 for more details about how to specify these URL options in the driver connection URL string. The URL option COMPAT_DBS is always required to use any of these nine methods; the corresponding COMPAT_xxx is also needed. For example, to use resultSetMetaData.isAutoIncrement() method, the URL options COMPAT_DBS and COMPAT_ISAUTOINC are required. COMPAT_DBS=true specifies that the values from the Teradata Database are used if provided by the database; the COMPAT_xxx values are used only when the database does not provide the values. COMPAT_DBS=false specifies that the other COMPAT_xxx values are always used, regardless of whether the database returns the data. Note: During connection time, if URL options COMPAT_xxx values are used but COMPAT_DBS is not being used, JDBC driver throws an SQLException. When invoking these methods, both COMPAT_DBS and the corresponding COMPAT_xxx URL options are required; otherwise, an SQLException is thrown. Using Type 4 Driver with Sun JDK 5.0 Implementation of JDBC RowSet Interface The Type 4 Teradata Driver for the JDBC Interface works with the Sun JDK 5.0 implementation of JDBC RowSet Interface. When using Teradata Driver for the JDBC Interface User Guide 65 Chapter 2: Using the Teradata Driver for the JDBC Interface Encryption, Authentication, and Authorization com.sun.rowset.JdbcRowSetImpl(java.sql.ResultSet resultSet), various ResultMetaData methods are called by this constructor. All ResultSetMetaData methods are supported with Teradata Database V2R6.2 and later. With Teradata Database V2R6.1 and earlier releases, the Teradata Driver for the JDBC Interface will throw SQLException when the following six ResultSetMetaData methods are invoked through JdbcRowSetImpl(java.sql.ResultSet resultSet): • isAutoIncrement() • isCurrency() • isSigned() • isSearchable() • getSchemaName() • getTableName() To use the constructor, JdbcRowSetImpl(java.sql.ResultSet resultSet), supply the following URL options: COMPAT_DBS=true/false COMPAT_ISAUTOINC=true/false COMPAT_ISCURRENCY=true/false COMPAT_ISSIGNED=true/false COMPAT_ISSEARCH=true/false COMPAT_GETSCHEMA=ReturnValue COMPAT_GETTABLE=ReturnValue Refer to the section “Using Type 4 Driver with ResultSetMetaData Methods” on page 64 for more details about how to specify these URL options in the driver connection URL string. When using com.sun.rowset.JdbcRowSetImpl(java.sql.Connection connection) and com.sun.rowset.JdbcRowSetImpl(String url, String user, String password), it calls Connection.prepareStatement(String sql, ResultSet.TYPE_SCROLL_INSENSITIVE, ResultSet.CONCUR_UPDATABLE). However, for database versions prior to 12.0, CONCUR_UPDATABLE is not supported. The Type 4 Teradata Driver for the JDBC Interface downgrades the unsupported ResultSet concurrency (CONCUR_UPDATABLE) to the supported concurrency (CONCUR_READ_ONLY) for database versions prior to 12.0 or when the fetched result set is not updatable for Teradata Database 12.0 and newer versions. Refer to “Making a Result Set Updatable” for more details about how to use updatable result set. Encryption, Authentication, and Authorization Teradata Driver for the JDBC Interface password encryption was released with Teradata Tools and Utilities 7.1. The functionality was then extended in Teradata Tools and Utilities 8.0 using Logon Mechanisms to support: 66 • Authentication • Authorization Teradata Driver for the JDBC Interface User Guide Chapter 2: Using the Teradata Driver for the JDBC Interface Encryption, Authentication, and Authorization • Encryption The Logon Mechanisms supported are: • Teradata Method 1 • Teradata Method 2 • Kerberos • LDAP The Teradata Driver for the JDBC Interface provides methods that allow selection of the mechanism, and allow data encryption to be turned on or off at the connection level. The selected mechanism determines the level of encryption that is used on the connection. See Security Administration for details on these mechanisms. Single Sign On (SSO) is only supported when Kerberos is selected, while data encryption is supported for all connections. This allows the JDBC client to access the Teradata Database over an unsecured channel without exposing the contents of messages. URL and DataSource Parameters URL and DataSource parameters in Teradata Tools and Utilities 8.0 or later and Teradata Database V2R6.0 or later support this feature using the following parameters: • LOGMECH • LOGDATA • ENCRYPTDATA Parameter Descriptions Table 12 provides URL and data source parameters information. Descriptions of methods that allow the getting and setting of the parameters are in “TeraDataSource Methods” in Chapter 3. Table 12: URL and DataSource Parameters URL and Data Source Parameter Description LOGMECH The LOGMECH parameter specifies the mechanism selected. LOGDATA The LOGDATA parameter carries information used by those mechanisms that require information beyond the normal Teradata username and password. ENCRYPTDATA The ENCRYPTDATA parameter controls the encryption of traffic to and from the Teradata Database. ENABLED indicates encryption is enabled. Prerequisites Logons with any mechanism other than TD1 and TD2 using the UTF16 session character set are not accepted if either the Teradata Driver for the JDBC Interface release is prior to 3.3 or the Teradata Database release is prior to V2R6.1. If such a logon is attempted, one of the following SQLExceptions is thrown: Teradata Driver for the JDBC Interface User Guide 67 Chapter 2: Using the Teradata Driver for the JDBC Interface Encryption, Authentication, and Authorization • Parcel kind or ordering is invalid (Error code 3748) • UserID, Password, or Account is invalid (Error code 8017) Table 13 lists the prerequisites for each of the methods. Table 13: Prerequisites Method Description Teradata Method 1 Does not require any special setup, and can be used immediately Teradata Method 2 Does not require any special setup, and can be used immediately Kerberos Requires a significant number of administration tasks on the machine that is running the Teradata Driver for the JDBC Interface. See “Meeting Kerberos Prerequisites” for more detail. To use UTF16 with Kerberos authentication, the Teradata Driver for the JDBC Interface must be version 3.3 or later, and the Teradata Database must be V2R6.1 or later. LDAP Requires a significant amount of administration effort to set up the LDAP environment. These tasks are covered in Security Administration. Once they are complete, LDAP can be used without any additional work required on the machine that is running the Teradata Driver for the JDBC Interface. To use UTF16 with LDAP authentication, the Teradata Driver for the JDBC Interface must be version 3.3 or later, and the Teradata Database must be V2R6.1 or later. Meeting Kerberos Prerequisites Prior to operating with Kerberos, the system administrator must perform the following prerequisites: • Set up a Kerberos Domain and Realm • Define users within the Active Directory • Ensure that each user has a krb5.ini file in the c:\winnt directory • Ensure that each user can run the kinit program • Verify that the login configuration file is correct • Specify the Java VM option • Enable Kerberos SSO Set up a Kerberos Domain and Realm A Kerberos domain and realm must be set up for the machines that are to be in the domain. A system administrator must perform this work. See Security Administration. Define Users within Active Directory All Kerberos users must be defined within the Active Directory in the Windows domain. It is important that users log on to the their machines EXACTLY as they are defined within Active 68 Teradata Driver for the JDBC Interface User Guide Chapter 2: Using the Teradata Driver for the JDBC Interface Encryption, Authentication, and Authorization Directory. Although a user defined in an Active Directory as DR818999 could successfully log onto the domain as dr818999 (notice the case change), for Kerberos to work, the user must log in to the domain as DR818999. Note: Ensure that the definition of the user within the Active Directory has the “Do not require Kerberos preauthenication” checked. Ensure krb5.ini File Exists in C:\winnt Directory The system administrator must set up a krb5.ini file in the c:\winnt directory for each user. It is the equivalent of the krb5.conf file that is the standard for both MIT and Heimdal Kerberos. The details of the various settings can be found in the MIT Kerberos documentation. An example of this file follows. This file is an example and must be modified to reflect the actual domain, realm, and KDC: ======================================= [libdefaults] ticket_lifetime = 6000 default_realm = ESROOTDOM.ESDEV.TDAT clockskew = 13000 default_tkt_enctypes = des-cbc-md5 default_tgs_enctypes = des-cbc-md5 checksum_type=2 [realms] ESROOTDOM.ESDEV.TDAT = { kdc = esroot.esrootdom.esdev.tdat:88 default_domain = esrootdom } [domain_realm] esrootdom = { .esrootdom = ESROOTDOM.ESDEV.TDAT esrootdom = ESROOTDOM.ESDEV.TDAT } ========================================== Run kinit For SSO, users must be able to run the kinit program, which obtains and caches a Kerberos Ticket-Granting-Ticket. This program can be found in the jre/bin directory of the Java JDK. An example follows: ================================ C:\j2sdk1.4.2_04\jre\bin>kinit Password for [email protected]:Mypassword New ticket is stored in cache file C:\Documents and Settings\DR818999\krb5cc_DR818999 ================================= Credential Delegation and Teradata Query Director When using Kerberos and Teradata Query Director (TQD), Credential Delegation must be enabled. To use Credential Delegation, obtain a Ticket-Granting-Ticket that is forwardable. This is done using the forwardable option of kinit, for example: kinit -f Teradata Driver for the JDBC Interface User Guide 69 Chapter 2: Using the Teradata Driver for the JDBC Interface Encryption, Authentication, and Authorization This option must be used in order for TQD to route authentication requests to the Teradata Database. Set the forwardable=true option in the C:\winnt\krb5.ini file under the [libdefaults] section. The previous krb5.ini file modified to use credential delegation is similar to: [libdefaults] forwardable = true ticket_lifetime = 6000 default_realm = ESROOTDOM.ESDEV.TDAT clockskew = 13000 default_tkt_enctypes = des-cbc-md5 default_tgs_enctypes = des-cbc-md5 checksum_type=2 [realms] ESROOTDOM.ESDEV.TDAT = { kdc = esroot.esrootdom.esdev.tdat:88 default_domain = esrootdom } [domain_realm] esrootdom = { .esrootdom = ESROOTDOM.ESDEV.TDAT esrootdom = ESROOTDOM.ESDEV.TDAT } Verify Login Configuration Information Kerberos requires the following Login Configuration information: =========================== com.sun.security.jgss.initiate { com.sun.security.auth.module.Krb5LoginModule sufficient useTicketCache=true; }; other { com.sun.security.auth.module.Krb5LoginModule required ; }; ========================= The information can reside in a file (to be used selectively) or be set for all users by modifying the java.security file. To put the information in a file, specify the location of that file with the JVM directive: “-Djava.security.auth.login.config” For example, if the Login Configuration file resided in a file called TeraJDBC.config in the working directory, specify: “-Djava.security.auth.login.config=TeraJDBC.config” as a JVM directive to use this file. To make it a system-wide setting, do the following: • 70 Edit the java.security file located in the lib/security directory of J2RE Teradata Driver for the JDBC Interface User Guide Chapter 2: Using the Teradata Driver for the JDBC Interface Encryption, Authentication, and Authorization • Add the login.config.url.n property to this file Search for login.config.url to see where this property is to reside. The value specifies where the file holding the configuration settings can be found. The values of n in login.cfg.url.n must be consecutively numbered. The following example shows only one login.config.url value. In this example, the configuration file is located at C:\dmr\TeraJDBC.config. “login.config.url.1=file:C:/dmr/TeraJDBC.config” This URL always uses forward slashes. Specify the JVM Option To enable SSO, the JVM option must be supplied: -Djavax.security.auth.useSubjectCredsOnly=false Enable Kerberos SSO To enable the Kerberos SSO logon, the user defined in the Teradata Database must have the same password as the user’s logon password and support SSO. To support SSO, the DDL statement grant logon with null password is required. For example, to provide the needed permission for user dr818999, use the following grant logon: grant logon on all to dr818999 with null password; More detail on this statement can be found in the Teradata Database SQL Reference: Data Definition Statements. Server-Side Default Authentication Mechanism The Teradata Security Administrator can change the default authentication mechanism from TD2 to a different mechanism on the server side (Teradata Database). However, the Administrator must be aware that certain mechanisms are only supported on certain platforms; for example, Kerberos is only supported on Windows platforms. The Administrator must also be aware of all the client platforms that are in use at the site; for example, Windows, UNIX, Linux. Before changing the server-side default mechanism to a mechanism that is not supported on all the client platforms in use at the site, the Administrator must first verify that all Java clients on platforms that don’t support the planned server-side default mechanism explicitly specify a supported authentication mechanism using the LOGMECH= connection parameter. For example, at a site consisting of Java applications deployed to both Windows and Linux platforms, if the Administrator decides to change the server-side default mechanism from TD2 to Kerberos, the Administrator must first verify that the Java applications deployed on Linux specify the LOGMECH=TD2 connection parameter, because the Kerberos authentication mechanism is not supported on Linux. Teradata Driver for the JDBC Interface User Guide 71 Chapter 2: Using the Teradata Driver for the JDBC Interface Generated Keys C and Java Application Sharing of XML Configuration C/C++ applications that communicate with the Teradata Database use the TeraGSS security library. If C/C++ and Java applications are deployed to the same physical machine, then Java applications can be configured to use the TeraGSS security library's XML security configuration file. In this deployment scenario, Java applications do not use the tdgssconfig.jar file that is included in the Teradata Driver for the JDBC Interface download package. Instead, the classpath for Java applications is set to include the TeraGSS directory that contains TdgssUserConfigFile.xml. The classpath must be set to include the following: • terajdbc4.jar • tdgssjava.jar • The directory containing TdgssUserConfigFile.xml Not all classloaders support the specification of a directory on the classpath. This deployment technique can only be used with classloaders that support the specification of a directory on the classpath. If the application server or environment does not support the specification of a directory on the classpath, then C/C++ and Java applications cannot directly share the same TeraGSS User Configuration File. Refer to the application server compatibility documentation included in the Teradata Driver for the JDBC Interface download package for complete instructions on how to use the Teradata Driver for the JDBC Interface with each supported application server. For application servers or environments that do not support the specification of a directory on the classpath, the TeraGSS User Configuration File can only be shared indirectly, and an extra step must be performed to enable this indirect sharing. A jar update command must be executed to take the TeraGSS User Configuration File from the TeraGSS directory and to put the TeraGSS User Configuration File into the tdgssconfig.jar file from the Teradata Driver for the JDBC Interface download package: jar uvf tdgssconfig.jar TdgssUserConfigFile.xml Each time the TeraGSS User Configuration File is modified, the jar update command must be executed again. The application server or environment must be restarted so that the modified tdgssconfig.jar is used. Generated Keys In version 3.4 of the Teradata Driver for the JDBC Interface, the following methods were added or enabled to support generated keys: 72 • Statement.getGeneratedKeys() • Statement.executeUpdate(String sql, int autoGeneratedKeys) • Statement.executeUpdate(String sql, int[] columnIndexes) Teradata Driver for the JDBC Interface User Guide Chapter 2: Using the Teradata Driver for the JDBC Interface Generated Keys • Statement.executeUpdate(String sql, String[] columnNames) • Statement.execute(String sql, int autoGeneratedKeys) • Statement.execute(String sql, int[] columnIndexes) • Statement.execute(String sql, String[] columnNames) • Connection.prepareStatement(String sql, int autoGeneratedKeys) • Connection.prepareStatement(String sql, int[] columnIndexes) • Connection.prepareStatement(String sql, String[] columnNames) Multi-Statement Requests If generated keys are being requested for a multi-statement request, then the application can retrieve the generated keys for the first statement by calling getGeneratedKeys(). It is then necessary to call getMoreResults() before each additional call to getGeneratedKeys(). If the statement is not an INSERT statement, then an empty result set is returned. The JDBC spec does not state how an application would obtain multiple generated key result sets from a multi-statement request. The JDBC spec does not mandate or prohibit using getMoreResults() to advance to the next generated key result set. This is a design choice for the Teradata Driver for the JDBC Interface that seemed to be the most obvious and intuitive choice. PreparedStatement Batch Requests If generated keys are being retrieved for a PreparedStatement batch request, then the rows are coalesced into a single auto-generated key result set, which is returned from getGeneratedKeys(). The maximum number of inserts in a batch request is limited to 1024. Insert-Select Statement If the request is an INSERT SELECT statement, then multiple rows are returned in the result set. The rows are not in any specific order. Exceptions Error 1125 One or more of the generated keys specified do not match a column name in the table. Change the list of column names to match the column names in the table where the row is being inserted may be returned for: • Statement.executeUpdate(String sql, String[] columnNames) • Statement.execute(String sql, String[] columnNames) • Connection.prepareStatement(String sql, String[] columnNames) Teradata Driver for the JDBC Interface User Guide 73 Chapter 2: Using the Teradata Driver for the JDBC Interface Parameter MetaData and Ambiguous Types Error 1126 One or more of the generated key indexes are invalid. Change the indexes so that they are greater than 0 and less than or equal to the number of columns in the table where the row is being inserted may be returned for: • Statement.executeUpdate(String sql, int[] columnIndexes) • Statement.execute(String sql, int[] columnIndexes) • Connection.prepareStatement(String sql, int[] columnIndexes) Error 1127 Column names array or column index array cannot be null may be returned if any of the methods are called that contain a null value for the column names array or the column index array. Error 1128 AutoGenerated Keys are not supported with this release of database software. The database must be running V2R6.2 or higher may be returned if any of the methods are called that request Auto Generated Keys. Statement.executeUpdate() The following exceptions are currently being used for PreparedStatement.executeUpdate(), but are now used for Statement.executeUpdate() where auto-generated keys are being requested. • executeUpdate() cannot be used when a result set is expected; use executeQuery() or execute() • executeUpdate() cannot be used when the request contains multiple statements; use execute() Upsert Statements are not Supported UPSERT statements are not supported with getGenerated Keys. If generatedKeys are requested after an UPSERT statement, an empty result set is returned. Parameter MetaData and Ambiguous Types When using ParameterMetaData, there are cases where the data type of a parameter may be ambiguous. This can happen when a ? parameter is used in certain expressions or used in the invocation of an overloaded UDF or UDM. Consider the following examples: Simple INSERT Operation: INSERT INTO T1 VALUES (?, ?, ?); This is a straightforward operation in which the three parameters, indicated by (?, ?, ?), are inserted into the table T1. In this instance, there is a simple assignment of each of the 74 Teradata Driver for the JDBC Interface User Guide Chapter 2: Using the Teradata Driver for the JDBC Interface Parameter MetaData and Ambiguous Types parameters to a column or field in the table.The parameter metadata returned is clear; it is the metadata describing each of the columns that the parameter data populates. INSERT Operation with Expressions: INSERT INTO T1 VALUES (? * 3, ? + 1, ? MOD 3); In this example, each of the columns of the target table is to be assigned the results of expressions: ? * 3, ? + 1, and ? MOD 3. The metadata associated with the three parameters has become ambiguous. since it could map to more than one SQL type. In this case, the data type of the parameter is considered unknown, and the method java.sql.ParameterMetaData.getParameterType() returns java.sql.Types.NULL. Table 14 outlines what is returned in cases where the data type of a parameter is ambiguous, and is considered an unknown data type. Table 14: Data Type AmbiguousUnknown java.sql.ParameterMetaData Method Value Returned for an Unknown Data Type String getParameterClassName(int param) null int getParameterType(int param) java.sql.Types.NULL String getParameterTypeName(int param) null int getPrecision(int param) 0 int getScale(int param) 0 int isNullable(int param) ParameterMetaData.parameterNullableUnknown boolean isSigned(int param) false int getParameterMode(int param) ParameterMetaData.parameterModeUnknown When a ? parameter is specified in the select list of a SELECT statement, the ResultSetMetaData may be ambiguous, in addition to the ParameterMetaData. Example SELECT ? Note: Question-mark parameter markers may be used in a select-list within a SELECT statement with Teradata Database. Versions of Teradata Database earlier than V2R6.2.0.19 do not support question-mark parameter markers. Table 15 outlines what is returned in cases where the data type of a parameter is ambiguous, and is considered an unknown data type. Table 15: Data Type Ambiguous Unknown java.sql.ResultSetMetaData Method Value Returned for an Unknown Data Type getCatalogName "" (a zero-length string) Teradata Driver for the JDBC Interface User Guide 75 Chapter 2: Using the Teradata Driver for the JDBC Interface Java External Stored Procedures Table 15: Data Type Ambiguous Unknown (continued) java.sql.ResultSetMetaData Method Value Returned for an Unknown Data Type getColumnClassName null getColumnDisplaySize 0 getColumnType java.sql.Types.NULL getColumnTypeName null getPrecision 0 getScale 0 getSchemaName ""(a zero-length string) getTableName ""(a zero-length string) isAutoIncrement false isCaseSensitive false isCurrency false isDefinitelyWritable false isNullable ResultSetMetaData.columnNullableUnknown isReadOnly false isSearchable false isSigned false isWritable false Java External Stored Procedures The Teradata Driver for the JDBC Interface implements the Java External Stored Procedure (XSP) portion of the java ANSI SQL:2003 standard. This includes the SQLJ database and tables, jar file installation, Java XSP definition, and Java XSP access to the JDBC default connection. This feature does not implement the entire standard. Specifically, support of Java User Defined Functions is postponed for a later release. Refer to Teradata Java External Stored Procedures User’s Guide for more details. Use Java XSPs in the following manner: 76 • Compile the Java source outside of the database and place the resulting class or classes (the byte code) in a jar file • Register the resulting jar file with the database by calling an XSP named SQLJ.INSTALL_JAR Teradata Driver for the JDBC Interface User Guide Chapter 2: Using the Teradata Driver for the JDBC Interface Java External Stored Procedures • Create the JAVA XSP with its EXTERNAL NAME clause specifying the jar file and associated Java class Once created, access the Java routine in the same manner as any XSP. Java XSPs can execute SQL code using the standard JDBC driver interface. Since the stored procedure is running on the database and is invoked from within a logged-on session, a connection URL of jdbc:default:connection should be used. JAR Files A jar file contains a collection of Java classes. The classes (compiled Java bytecodes) are referenced when an external Java routine is created using the EXTERNAL NAME clause. The jar files are created outside of the database. Before the classes can be referenced, they must be registered and copied into the SQL environment. Once a jar is installed onto the database, its content can’t be changed in any way—it can only be deleted or replaced in its entirety. A jar file is not global but is only available to the user that installed it using a call to SQLJ.INSTALL_JAR(). Like the infrastructure for C/C++ UDFs and XSPs, a directory is created on the server for each database that contains a jar. A C/C++ DLL created for one or more UDFs or XSPs in a given database is not accessible to other users or databases; the same is true for jar files. In connection with this, no new access rights are created for jar files. Therefore, user-database A cannot create an XSP that references a jar installed in user-database B. However, user-database A can be granted access to a Java XSP that has been created in user-database B by using the same access rights designed for C/C++ UDFs/XSPs. A model that could optionally be followed for Java XSPs is to install all jars and create all Java XSPs in the same database, and then grant access to these Java XSPs to all users who will need to execute them. The jar files are installed, replaced, deleted, or path-specified by the following XSPs: • SQLJ.INSTALL_JAR • SQLJ.REPLACE_JAR • SQLJ.REMOVE_JAR • SQLJ.ALTER_JAVA_PATH Refer to Teradata Java External Stored Procedure User’s Guide for more details. Transferring Java XSP From the Client to the DBS Server If using JDBC, use jar files for XSPs that are stored on the server or the client. A jar file for a Java XSP that is on the client must be transferred from the client node to the server node. For security purposes, the Teradata Driver for the JDBC Interface uses the classpath to load all resources. The jar file that contains Java XSPs must not be on the classpath itself. Instead, the container of the jar file must be on the classpath. For example, if the jar file is located in a directory on the file system, then the directory name must be present in the classpath. As another example, the jar file may be located inside a war file or an ear file, because the application server will automatically make the contents of the war file or ear file available on the classpath. Once the class path is set, the Teradata Driver for the JDBC Interface can transfer the source file to the server node. Teradata Driver for the JDBC Interface User Guide 77 Chapter 2: Using the Teradata Driver for the JDBC Interface Java External Stored Procedures The following is code from a JDBC sample class using SQLJ to install and transfer a jar file from the client to the DBS server: String sInstallJar = “call sqlj.install_jar(‘cj!SampleXJSP.jar’, ‘SampleXJSP’,0);”; stmt.executeUpdate(sInstallJar); This example gives the location of the jar file using the locspec parameter. The <locspec> specifies where the originating jar file is located. If the <location designator> specifies ‘CJ!’ then the jar is located on the client in the client-interpreted location specified by the class path for the Teradata Driver for the JDBC Interface. If the <location designator> specifies ‘SJ!’ then the jar is located on the database server using the <server jar path>. Refer to Teradata Java External Stored Procedure User’s Guide for more details. Defining the SQL Routines After the jar file is installed, the next step is to create the Java class procedure DeptJobInfo. For example: REPLACE PROCEDURE getDeptJobInfo (IN name VARCHAR(30), OUT dept VARCHAR(50), OUT job VARCHAR(300)) LANGUAGE JAVA MODIFIES SQL DATA PARAMETER STYLE JAVA EXTERNAL NAME ‘SampleXJSP:DeptJobInfo.getDeptJobInfo’; Parameter Usage Example The following example shows a procedure definition for various parameter types. SQL statement: REPLACE PROCEDURE getEmpInfo (IN name VARCHAR(30), OUT id INTEGER, OUT dept VARCHAR(50), OUT job VARCHAR(300), OUT res CLOB) LANGUAGE JAVA MODIFIES SQL DATA PARAMETER STYLE JAVA EXTERNAL NAME ‘SampleXJSP:EmpInfo.getEmpInfo( java.lang.String, java.lang.Integer[], java.lang.String[], java.lang.String[], java.sql.Clob[])’; Source code for the Java stored procedure defined above: public class EmpInfo { public static void getEmpInfo(String name, java.lang.Integer[] id, String[] dept, String[] job, java.sql.Clob[] res) throws SQLException { /* Establish default connection.*/ Connection con = DriverManager.getConnection(“jdbc:default:connection”); String query = “SELECT empID, empDept, empJob, empResume” + “FROM employee 2” + 78 Teradata Driver for the JDBC Interface User Guide Chapter 2: Using the Teradata Driver for the JDBC Interface Java External Stored Procedures “WHERE empName = ?;”; /* Executing the command */ PreparedStatement pStmt = con.prepareStatement(query); try { pStmt.setString(1, name); ResultSet rs = pStmt.executeQuery(); boolean more = rs.next(); if(more) { id[0] = new java.lang.Integer(rs.getInt(1)); dept[0] = rs.getString(2); job[0] = rs.getString(3); res[0] = rs.getClob(4); } } finally { pStmt.close(); } } The parameters in the Java XSP provided here are explicitly mapped from the SQL types to the Java types. These mappings also can be implicit. The mappings for external Java XSP parameters from SQL types to Java types are defined in Appendix E. Default Connection The Java XSP in the previous example is running on the database and is invoked from within a logged-on session. As a result, the connection URL being used is jdbc:default:connection. This creates a default connection that participates in the caller’s session and current transaction. No logoff occurs when the connection’s close method is called since the default connection uses the same session as the caller. The default connection is only accessible from one thread– the thread that invoked the Java XSP. Java XSPs support the following URL parameters with the jdbc:default:connection URL: • *LOG • *LOB_SUPPORT • *SP_SPL • *TNANO • *TSNANO Invoking a Java XSP from JDBC Calling a Java XSP from a JDBC client is the same as invoking any stored procedure. The following example uses a CallableStatement: String sCall = “CALL getEmpInfo(?,?,?,?,?);”; String sName = “Brian Lee”; // Creating a CallableStatement object, representing // a precompiled SQL statement and preparing the callable // statement for execution. CallableStatement cStmt = con.prepareCall(sCall); Teradata Driver for the JDBC Interface User Guide 79 Chapter 2: Using the Teradata Driver for the JDBC Interface Updatable Result Set // Setting up input parameter value cStmt.setString(1, sName); // Setting up output parameters for data retrieval by // declaring parameter types. cStmt.registerOutParameter(2, Types.INTEGER); cStmt.registerOutParameter(3, Types.VARCHAR); cStmt.registerOutParameter(4, Types.VARCHAR); cStmt.registerOutParameter(5, Types.CLOB); System.out.printIn(“\n Calling the procedure with ’” + sName + ’”…”); // Making a procedure call cStmt.executeUpdate(); // Displaying procedure call result System.out.printIn(“ Call successful.”); System.out.printIn(“\n Displaying output of the call to” + “getEmpInfo(…):”); System.outprintIn(“\n” + sName); System.out.printIn(“---------------”); int id = cStmt.getInt(2); System.out.printIn(“ Employee ID : “ + id); System.out.printIn(“ Department : “ + cStmt.getString(3)); System.out.printIn(“ Job Description : “ + cStmt.getString(4)); System.out.print(“ Resume: ”); // Writing CLOB data out to a file for review createClobFile(cStmt.getClob(5),(id + “resumeT20604.txt”)); Transaction Semantics and Java XSPs Transaction semantics (ANSI or Teradata) are set when a session is logged on, and cannot be subsequently changed. When using the Teradata Driver for the JDBC Interface, the transaction semantics are specified using the TMODE connection parameter. The default connection used by a Java XSP always inherits the transaction semantics used to establish the caller’s session. If the caller’s session has ANSI transaction semantics, then the Java XSP’s default connection Auto-Commit setting will be true. If the caller’s session has Teradata transaction semantics, then the Java XSP’s default connection Auto-Commit setting will depend on whether the caller’s session is within an existing transaction (for example, BT was executed). In this case, the Auto-Commit setting will be false if BT was executed, and the Auto-Commit setting will be true if BT was not executed. Updatable Result Set Making a Result Set Updatable A default ResultSet object is returned when calling the following methods: • Connection.createStatement() • Connection.prepareStatement(String query) • Connection.prepareCall(String query) This default ResultSet object is not updatable and has a cursor that moves forward only. 80 Teradata Driver for the JDBC Interface User Guide Chapter 2: Using the Teradata Driver for the JDBC Interface Updatable Result Set It is possible to produce ResultSet objects that are scrollable and updatable by calling the following methods: • Connection.createStatement(int type, ResultSet.CONCUR_UPDATABLE) • Connection.prepareStatement(String sql, int type, ResultSet.CONCUR_UPDATABLE) • Connection.prepareCall(String sql, int type, ResultSet.CONCUR_UPDATABLE) To make the ResultSet objects from the above methods updatable, the following requirements need to be satisfied: • Teradata Database version requirement: Teradata Database V2R6.2 or 12.0 • Connection parameter LOB_SUPPORT must be ON or omitted (the default is ON) • Unique index requirement: The fetched result set must contain a column that is the only member of a unique index, or a column that is a member of one or more unique indexes on the table, and all the columns of at least one unique index have been selected in the result set. Non-updatable Result Set The Teradata Driver for the JDBC Interface attempts to satisfy updating, inserting, and deleting requests from the result set fetched from the single table or multiple joined tables. However, there are several cases where the returned result set from Teradata Database is not updatable, including: • When the result set is fetched from self-joined tables, the columns in the result set fetched from self-joined tables have the same original table name and column names, so the UPDATE, INSERT, and DELETE queries applied to this result set might be ambiguous. • When ResultSet.insertRow() is used with the result set fetched from either a single table or multiple joined tables, all the columns with NOT NULL constraints from the single table or all the joined tables must be contained in the fetched result set. Otherwise, method insertRow fails and the Teradata Database returns an error message. Inner Joins There are no issues with using updatable result set with inner joins since only matched rows are selected from the inner-joined tables without NULL values padded for unmatched rows. However, if the result set fetched from multiple inner-joined tables doesn’t meet the following unique index requirement for all tables with columns contained in the result set, the methods updateRow and deleteRow fail and the Teradata Driver for the JDBC Interface throws an SQLException, and method insertRow returns an error message from Teradata Database. The fetched result set must contain a column that is the only member of a unique index or a column that is a member of one or more unique indexes on the table, and all the columns of at least one unique index have been selected in the result set. Outer Joins If the result set fetched from multiple outer-joined tables doesn’t meet the following unique index requirement for all tables with columns contained in the result set, the methods Teradata Driver for the JDBC Interface User Guide 81 Chapter 2: Using the Teradata Driver for the JDBC Interface Updatable Result Set updateRow and deleteRow fail and the Teradata Driver for the JDBC Interface throws an SQLException, and method insertRow returns an error message from Teradata Database. The fetched result set must contain a column that is the only member of a unique index, or a column that is a member of one or more unique indexes on the table, and all the columns of at least one unique index have been selected in the result set. Also, the Teradata Driver for the JDBC Interface is only able to permit a result set row from a join to be updated if the unique index column(s) selected from the above unique index requirement is(are) not NULL. However, outer joins could involve NULL values for these unique index columns for one or more joined table(s). In this case, updateRow() and deleteRow() operations fail and the Teradata Driver for the JDBC Interface throws an SQLException. Using Updatable Result Set The following are some common scenarios for using updatable result set with the Teradata Driver for the JDBC Interface: • Update column values in the current row in the database The following code fragment updates the STATE column in the third row of the ResultSet object rs and then uses the method updateRow to update the data source table from which rs was derived. rs.absolute(3); // moves the cursor to the third row of rs rs.updateString(“STATE”, “CALIFORNIA”); // updates the // STATE column of row 3 to be CALIFORNIA rs.updateRow(); // updates the row in the data source • Insert a new row in the database An updatable ResultSet object has a special row associated with it that serves as a staging area for building a row to be inserted. The following code fragment moves the cursor to the insert row, builds a three-column row, and inserts it into rs and into the data source table, using the method insertRow. rs.moveToInsertRow(); // moves cursor to the insert row rs.updateString(1, “Michael”); // updates the // first column of the insert row to be Michael rs.updateInt(2, 35); // updates the second column to be 35 rs.updateBoolean(3, true); // updates the third column to true rs.insertRow(); // inserts the row in the data source rs.moveToCurrentRow(); // moves back to current row • Delete the current row in the database An updatable ResultSet object has a special row associated with it that serves as a staging area for building a row to be inserted. The following code fragment moves the cursor to the insert row, builds a three-column row, and inserts it into rs and into the data source table using the method insertRow. rs.absolute(3); // moves the cursor to the third row of rs rs.deleteRow(); // deletes the current row 3 in the data source • Refresh the current row in the database The Teradata Driver for the JDBC Interface implements the method refreshRow to clear up the column values updated by a set of updater methods for the current row in the result 82 Teradata Driver for the JDBC Interface User Guide Chapter 2: Using the Teradata Driver for the JDBC Interface Updatable Result Set set. If refreshRow is called after calling the updater methods, but before calling the method updateRow, then the updates made to the row are lost. However, the Teradata Driver for the JDBC Interface doesn’t refetch the latest value of the current row from the database to refresh the current row. The following code fragment updates the STATE and AMOUNT columns in the third row of the ResultSet object rs and then uses the method refreshRow to clear up the column values updated by the updater methods for the current row in the result set. The method updateRow does not update the data source table from which rs was derived since the update column values are lost. rs.absolute(3); // moves the cursor to the third row of rs rs.updateString(“STATE”, “CALIFORNIA”); // updates the // STATE column of row 3 to be CALIFORNIA rs.updateInt(“AMOUNT”, 58); // updates the second column to be 35 rs.refreshRow(); // clears up the update column // values for the current row rs.updateRow(); // no UPDATE in the data source since // update values are lost Result Set Type and Concurrency Upgrading and Downgrading There are some scenarios where the result set type and concurrency need to be either upgraded or downgraded. Scenario 1: Type Upgrading The Teradata Driver for the JDBC Interface implements updatable result set as result set type ResultSet.TYPE_SCROLL_INSENSITIVE. When users attempt to use result set type ResultSet.TYPE_FORWARD_ONLY and concurrency mode ResultSet.CONCUR_UPDATABLE in the following methods: • Connection.createStatement(ResultSet.TYPE_FORWARD_ONLY, ResultSet.CONCUR_UPDATABLE) • Connection.prepareStatement(String sql, ResultSet.TYPE_FORWARD_ONLY, ResultSet.CONCUR_UPDATABLE) • Connection.prepareCall(String sql, ResultSet.TYPE_FORWARD_ONLY, ResultSet.CONCUR_UPDATABLE) and the following requirements are satisfied: • Teradata Database version requirement: Teradata Database V2R6.2 or 12.0 • Connection parameter LOB_SUPPORT is ON or omitted (the default is ON) the fetched result set type is upgraded to ResultSet.TYPE_SCROLL_INSENSITIVE, and an SQLWarning is added to the connection object. Scenario 2: Concurrency Downgrading When users attempt to use result set concurrency ResultSet.CONCUR_UPDATABLE in the following methods: Teradata Driver for the JDBC Interface User Guide 83 Chapter 2: Using the Teradata Driver for the JDBC Interface Updatable Result Set • Connection.createStatement(int type, ResultSet.CONCUR_UPDATABLE) • Connection.prepareStatement(String sql, int type, ResultSet.CONCUR_UPDATABLE) • Connection.prepareCall(String sql, int type, ResultSet.CONCUR_UPDATABLE) and the following requirements are not satisfied: • Teradata Database version requirement: Teradata Database V2R6.2 or 12.0 • Connection parameter LOB_SUPPORT is ON or omitted (the default is ON) • Unique index requirement: the fetched result set contains a column that is the only member of a unique index, or a column that is a member of one or more unique indexes on the table, and all the columns of at least one unique index have been selected in the result set. the fetched result set concurrent mode is downgraded to ResultSet.READ_ONLY, and an SQLWarning is added to the connection object. Exceptions The following are Teradata Driver for the JDBC Interface exception scenarios when using updatable result set: • It is ambiguous and unpredictable to apply methods updateRow, insertRow, and deleteRow to the result set fetched from self-joined tables • If the result set fetched from single- or multiple-joined tables doesn’t meet the above unique index requirement for the table(s) with columns contained in the result set: • Methods updateRow and deleteRow: The Teradata Driver for the JDBC Interface throws an SQLException. Error 1197: No unique primary index (UPI) or key columns are fetched in this result set from the table • Method insertRow: The Teradata Driver for the JDBC Interface throws an SQLException if not all of non-nullable columns in the fetched result set have not been given a non-null value when calling method insertRow. Error 1198: Not all of non-nullable columns in the insert row have been given a value for the table Error 1199: Not all of non-nullable columns in the insert row have been given a nonnull value for the table • The Teradata Driver for the JDBC Interface throws an SQLException if the unique index column(s) selected from the above unique index requirement contain(s) NULL values from outer-joined tables when calling methods updateRow and deleteRow. Error 1195: Unique Primary Index (UPI) columns are NULL for the table Error 1196: Primary key columns are NULL for the table • The Teradata Driver for the JDBC Interface throws an SQLException if methods updateArray, updateBoolean, and updateRef are called since Teradata Database doesn’t support data type Array, Boolean, and Ref. Error 1190: Data type Array(Boolean/Ref) is not supported by the Teradata Database 84 Teradata Driver for the JDBC Interface User Guide Chapter 2: Using the Teradata Driver for the JDBC Interface Stored Procedure Dynamic Result Set • The Teradata Driver for the JDBC Interface throws an SQLException if methods cancelRowUpdates, updateRow, deleteRow, and refreshRow are called when the cursor is on the insert row. Error 1191: Function should not be called since the cursor is on the insert row Stored Procedure Dynamic Result Set A stored procedure that returns dynamic result sets is similar to any multi-statement request: • CallableStatement.execute()—use if more than one result set is expected or if it is unknown whether a stored procedure will return any dynamic result set(s) • CallableStatement.executeQuery()—use if a single result set is expected The result sets are dynamic; therefore, it is not possible to look at the metadata for the results until after the statement is executed. JDBC FastLoad JDBC FastLoad provides a method for quickly loading large amounts of data into an empty destination table in a Teradata Database. The actual performance of JDBC FastLoad varies, depending on the application and database configuration. For example, given an unconstrained network, JDBC FastLoad is about five to 10 times faster than a single-statement batched insert (that is, it takes JDBC FastLoad 10 to 20 percent of the time it takes a single-statement batched insert). Enabling JDBC FastLoad JDBC FastLoad is enabled with TYPE=FASTLOAD in the URL connection string. When enabled, the FastLoad protocol is used with the Teradata Database for FastLoad-capable SQL INSERT statements. For all other SQL statements, including SQL INSERT statements not FastLoad capable, the standard protocol is used with the Teradata Database. In order to qualify for JDBC FastLoad, the SQL INSERT statement must meet the following criteria: • JDBC FastLoad must be used with a PreparedStatement • The PreparedStatement must be a single SQL INSERT statement • The PreparedStatement must be used without returning auto-generated keys • The Teradata session character set must be ASCII, UTF8, or UTF16 • If TNANO or TSNANO is specified, the given precision of fractional seconds must be less than or equal to the precision of fractional seconds declared for any TIME or TIMESTAMP column in the destination table • All Teradata data types declared in the destination table must be supported by JDBC FastLoad Teradata Driver for the JDBC Interface User Guide 85 Chapter 2: Using the Teradata Driver for the JDBC Interface JDBC FastLoad Considerations When Using JDBC FastLoad Keep in mind the following considerations. JDBC FastLoad: • Requires that the destination table in a Teradata Database must be empty before it can be used to insert data rows • Locks the destination table in a Teradata Database. Thus, the Java application will not have any access permission to the destination table while JDBC FastLoad is active. The lock is released when transactions are committed or rolled back. • Supports batch inserts only • Potentially sets an SQL Warning. It is recommended to always check that no SQLWarning has been set after transactions are committed or rolled back • Creates two temporary error tables with the following naming convention: <database name>.<table name>_ERR_1 and <database name>.<table name>_ERR_2. For example, if the destination <database name> is guest and the destination <table name> is FastLoad Example, then the two temporary error tables will be named guest.FastLoadExample_ERR_1 and guest.FastLoadExample_ERR_2. For more details on the purpose of the two temporary error tables, see the section on Error Recording in the Teradata FastLoad Reference. Note that the two temporary error tables must never be accessed by a Java application because the naming convention may change without prior notice and any access may cause a deadlock while JDBC FastLoad is active. • The name of the destination table in the Teradata Database that is to be used by JDBC FastLoad must not exceed 24 characters because of the name of the two temporary error tables created by JDBC FastLoad (discussed above) • The use of concurrent JDBC FastLoad Prepared Statement objects is permitted, but is subject to limitations imposed by the Teradata Database. For details on the imposed limitations, see the section on Concurrent Load Utility Tasks in the Teradata FastLoad Reference. JDBC Data Types Supported by JDBC FastLoad Not all of the JDBC data types supported by the Teradata Driver for the JDBC Interface are supported by JDBC FastLoad; for example, BLOB and CLOB. Likewise, not all of the JDBC data type conversions supported by the Teradata Driver for the JDBC Interface are supported by JDBC FastLoad. JDBC Escape Functions in Support of JDBC FastLoad Connection.nativeSQL(“{fn teradata_amp_count()}”) Returns the number of AMPs configured for a Teradata Database. The information helps in determining the maximum number of JDBC FastLoad connections that can be created. Connection.nativeSQL(“{fn teradata_logon_sequence_number()}”) Returns comma-separated pairs of a JDBC FastLoad-capable PreparedStatement.hashCode() and the associated Logon Sequence Number (LSN) of any JDBC FastLoad PreparedStatement created by this Connection. 86 Teradata Driver for the JDBC Interface User Guide Chapter 2: Using the Teradata Driver for the JDBC Interface JDBC Monitor For example, a string of “6166383,1850,22323092,1851” indicates that 6166383 and 22323092 are hash codes of a JDBC FastLoad PreparedStatement and 1850 and 1851 are the respective LSNs. The information helps in finding the DBC.SessionInfo.SessionNo of JDBC FastLoad connections, as is shown in Program Examples. However, note than an LSN can only be observed when auto-commit mode is false and at least one column value is bound beforehand using the JDBC FastLoad-capable PreparedStatement. JDBC Monitor JDBC Monitor provides a method for accessing and using standard performance monitoring and production control functions contained within the Teradata Database. Enabling JDBC Monitor JDBC Monitor is enabled with PARTITION=MONITOR in the URL connection string. When enabled, the Monitor protocol is used with the Teradata Database for all SQL statements. To qualify for JDBC Monitor, the SQL statement must meet the following criteria: • Before connecting with the JDBC Monitor, it is necessary that the user be granted access rights for executing Monitor statements; for example, execute “GRANT MONITOR TO guest” before connecting as user “guest” and executing any Monitor statement • The Teradata session character set must be ASCII • JDBC Monitor must be used with a PreparedStatement • The PreparedStatement must be a single SQL statement Considerations When Using JDBC Monitor • All bound Teradata data types must be supported by JDBC Monitor • The Monitor protocol expects all String values to be of data type CHAR with a fixed length. Therefore, the Teradata Driver for the JDBC Interface imposes the following rules: • LONGVARCHAR and VARCHAR data types are automatically converted to a CHAR data type • When binding a null String value, call PreparedStatement.setObject variant with scale, where the scale tells the Teradata Driver for the JDBC Interface the CHAR column size expected by the Monitor statement to be executed • The PreparedStatement.setObject variant with scale will pad spaces to the end of any String that has a length less than the given scale • If a String value is bound with PreparedStatement.setString or PreparedStatement.setObject without scale, the application assumes responsibility for making sure that the String value has the exact length expected by the Monitor statement Teradata Driver for the JDBC Interface User Guide 87 Chapter 2: Using the Teradata Driver for the JDBC Interface JDBC Monitor • The method PreparedStatement.setString cannot be called with a null String value • The method PreparedStatement.setNull cannot be called with a CHAR, LONGVARCHAR, or VARCHAR data type • The method PreparedStatement.setObject without scale cannot be called to bind a null String value • Use only PreparedStatement.execute to execute a Monitor statement • JDBC Monitor may set an SQLWarning. So it is recommended to always check that no SQLWarning has been set after statements are executed • The use of concurrent JDBC Monitor PreparedStatement objects is permitted, but is subject to limitations imposed by the Teradata Database. For details on the imposed limitations, see Workload Management API: PM/API and Open API. JDBC Data Types Supported by JDBC Monitor Not all of the JDBC data types supported by the Teradata Driver for the JDBC Interface are supported by JDBC Monitor; for example, BLOB and CLOB. Likewise, not all of the JDBC data type conversions supported by the Teradata Driver for the JDBC Interface are supported by JDBC Monitor. Teradata Database PM/API Statements Supported by JDBC Monitor The Teradata Database PM/API statements supported by JDBC Monitor are given in the tables that follow. Refer to Workload Management API: PM/API and Open API for details of each Monitor statement. PM/API Statements Table 16 describes the IDENTIFY statement. Table 16: IDENTIFY Statement Parameter PreparedStatement Description 1 (mon_ver_id) setShort Monitor software version id 2 (host_id) setShort The logical ID of a host (or client) Note: Nullable 3 (session_no) setInt Session number. A combination of host_id and session_no identifies a user causing a block. Note: Nullable 4 (database_id) setInt ID of the database for this session Note: Nullable 5 (user_id) setInt ID of the user for this session Note: Nullable 88 Teradata Driver for the JDBC Interface User Guide Chapter 2: Using the Teradata Driver for the JDBC Interface JDBC Monitor Table 16: IDENTIFY Statement (continued) Parameter PreparedStatement Description 6 (table_id) setInt Unique ID of a table Note: Nullable Table 17 describes the MONITOR PHYSICAL CONFIG statement. Table 17: MONITOR PHYSICAL CONFIG Statement Parameter PreparedStatement Description 1 (mon_ver_id) setShort Monitor software version id Table 18 describes the MONITOR PHYSICAL RESOURCE statement. Table 18: MONITOR PHYSICAL RESOURCE Statement Parameter PreparedStatement Description 1 (mon_ver_id) setShort Monitor software version id Table 19 describes the MONITOR PHYSICAL SUMMARY statement. Table 19: MONITOR PHYSICAL SUMMARY Statement Parameter PreparedStatement Descriptiona 1 (mon_ver_id) setShort Monitor software version id a. If MONITOR PHYSICAL SUMMARY is executed on MP-RAS platforms, the JDBC Driver may throw chained SQL exceptions with error codes 1214 and 1178. This is due to a Teradata Database defect that has been fixed in the following releases: 6.0.2.54, 6.1.1.58. Table 20 describes the MONITOR SESSION statement. Table 20: MONITOR SESSION Statement Parameter PreparedStatement Descriptiona 1 (mon_ver_id) setShort Monitor software version id 2 (host_id) setShort The logical ID of a host (or client) Note: Nullable 3 (session_no) setInt Session number. A combination of host_id and session_no identifies a user causing a block. Note: Nullable Teradata Driver for the JDBC Interface User Guide 89 Chapter 2: Using the Teradata Driver for the JDBC Interface JDBC Monitor Table 20: MONITOR SESSION Statement (continued) Parameter PreparedStatement Descriptiona 4 (user_name) setString Name of the user or database that is running this session Note: Nullable a. SET SESSION RATE must have been executed to set a valid session rate before MONITOR SESSION can succeed. Table 21 describes the MONITOR SQL statement. Table 21: MONITOR SQL Statement Parameter PreparedStatement Descriptiona 1 (mon_ver_id) setShort Monitor software version id Note: A version id of “2” MUST NEVER be bound when running MONITOR SQL or the JDBC Driver will throw chained SQL exceptions with error codes 1214 and 1178. This is due to a Teradata Database defect. Version id “2” is an old version that shouldn’t be used. 2 (host_id) setShort The logical ID of a host (or client) Note: Nullable 3 (session_no) setInt Session number. A combination of host_id and session_no identifies a user causing a block. Note: Nullable 4 (RunPEVprocNo) setShort The PE vproc number where the session runs Note: Nullable Note: The argument “RunPEVprocNo” was added after Teradata Database V2R5.1 and is not available in older versions. a. If MONITOR SQL is executed to “monitor” SQL statements longer than 64000 bytes, the result set may be corrupted with non-printable characters when printable characters are expected. This is due to a Teradata Database defect that has been fixed in the following releases: 6.0.2.51, 6.1.1.54, and 6.2.1.5. Table 22 describes the MONITOR VERSION statement. Table 22: MONITOR VERSION Statement 90 Parameter PreparedStatement Description 1 (mon_ver_id) setShort Monitor software version id Teradata Driver for the JDBC Interface User Guide Chapter 2: Using the Teradata Driver for the JDBC Interface JDBC Monitor Table 23 describes the MONITOR VIRTUAL CONFIG statement. Table 23: MONITOR VIRTUAL CONFIG Statement Parameter PreparedStatement Description 1 (mon_ver_id) setShort Monitor software version id Table 24 describes the MONITOR VIRTUAL RESOURCE statement. Table 24: MONITOR VIRTUAL RESOURCE Statement Parameter PreparedStatement Description 1 (mon_ver_id) setShort Monitor software version id Table 25 describes the MONITOR VIRTUAL SUMMARY statement. Table 25: MONITOR VIRTUAL SUMMARY Statement Parameter PreparedStatement Description 1 (mon_ver_id) setShort Monitor software version id Table 26 describe the SET SESSION RATE statement. Table 26: SET SESSION RATE Statement Parameter PreparedStatement Description 1 (mon_ver_id) setShort Monitor software version id 2 (sample_rate) setShort Value of the sample interval 3 (local_change) setString Types of session to which this rate change applies Note: Nullable Table 27 describes the TDWM STATISTICS statement. Table 27: TDWM STATISTICS Statement Parameter PreparedStatement Description 1 (mon_ver_id) setShort Monitor software version id 2 (request_flag) setShort Indicates the type of request Table 28 describes the TDWM SUMMARY statement. Teradata Driver for the JDBC Interface User Guide 91 Chapter 2: Using the Teradata Driver for the JDBC Interface JDBC Monitor Table 28: TDWM SUMMARY Statement 92 Parameter PreparedStatement Description 1 (mon_ver_id) setShort Monitor software version id Teradata Driver for the JDBC Interface User Guide CHAPTER 3 JDBC Methods This chapter describes the JDBC methods supported by the Teradata Driver for the JDBC Interface and Teradata extension methods. The JDBC methods are listed by class in the following order: • BLOB Interface Methods • CLOB Interface Methods • CallableStatement Methods • Connection Methods • ConnectionEvent Methods • ConnectionEventListener Methods • ConnectionPoolDataSource Methods • DatabaseMetaData Methods • DataSource Methods • DriverManager Methods • ParameterMetaData Methods • PooledConnection Methods • PreparedStatement Methods • ResultSet Methods • ResultSetMetaData Methods • Statement Methods • TeraDataSource Methods Teradata Driver for the JDBC Interface User Guide 93 Chapter 3: JDBC Methods BLOB Interface Methods BLOB Interface Methods Description This section describes the BLOB interface methods. Methods getBinaryStream( ) Function: Materializes the BLOB value designated by this BLOB object as a stream of uninterpreted bytes. Characteristic Description Syntax public InputStream getBinaryStream() throws SQLException Return A stream containing the BLOB data is returned. getBytes(long pos, integer length) Function: Materializes the BLOB value designated by this BLOB object as an array of bytes. Characteristic Description Syntax public byte[] getBytes(long pos, integer length) throws SQLException where • pos is the ordinal position of the first byte in the BLOB value that is extracted. The first byte is position 1. • length is the number of consecutive bytes that are copied Return A byte of size length containing consecutive bytes from the BLOB value is returned. length( ) Function: Returns the number of bytes in the BLOB value that the BLOB object designates. 94 Characteristic Description Syntax public long length() throws SQLException Return The length of the BLOB in bytes is returned. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods BLOB Interface Methods setBytes(long pos, byte[] bytes) Function: Writes the given array of bytes to the BLOB value that this BLOB object represents, starting at position pos, and returns the number of bytes written. Characteristic Description Syntax public int setBytes(long pos, byte[] bytes) throws SQLException where the parameter: • pos is the position in the BLOB object at which to start writing • bytes is the array of bytes to be written to the BLOB value that this BLOB object represents Return The number of bytes written is returned. Note: The maximum length of bytes that can be set is 64000. setBytes(long pos, byte[] bytes, int offset, int len) Function: Writes all or part of a given byte array to the BLOB value that this BLOB object represents and returns the number of bytes written. Writing starts at position pos in the BLOB value; len bytes from the given byte array are written. Characteristic Description Syntax public int setBytes(long pos, byte[] bytes, int offset, int len) throws SQLException where the parameter: • pos is the position in the BLOB object at which to start writing • bytes is the array of bytes to be written to this BLOB object • offset is the offset into the array bytes at which to start reading the bytes to be set • len is the number of bytes to be written to the BLOB value from the array of bytes bytes Return The number of bytes written is returned. Note: The maximum length of bytes that can be set is 64000. setBinaryStream(long pos) Function: Retrieves a stream that can be used to write the BLOB value that this BLOB object represents. The stream begins at position pos. Teradata Driver for the JDBC Interface User Guide 95 Chapter 3: JDBC Methods CLOB Interface Methods Characteristic Description Syntax public OutputStream setBinaryStream(long pos) throws SQLException where the parameter pos is the position in the BLOB value at which to start writing. Return A java.io.OutputStream object to which data can be written is returned. truncate(long len) Function: Truncates the BLOB value that this BLOB object represents to be len bytes in length. Characteristic Description Syntax public void truncate(long len) throws SQLException where the parameter len is the length, in bytes, to truncate the BLOB value that this BLOB object represents. CLOB Interface Methods Description This section describes the CLOB interface methods. Methods getAsciiStream( ) Function: Gets the CLOB value designated by this CLOB object as a stream of Ascii characters. Characteristic Description Syntax public InputStream getAsciiStream() throws SQLException Return A java.io InputStream object containing the data in the CLOB is returned. getCharacterStream( ) Function: Gets the CLOB value designated by this CLOB object as a Unicode stream. 96 Characteristic Description Syntax public Reader getCharacterStream() throws SQLException Return A java.io Reader object containing the data in the CLOB is returned. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods CLOB Interface Methods getSubString(long pos, int length) Function: Returns a copy of the specified substring in the CLOB value designated by this CLOB object. Characteristic Description Syntax public String getSubString(long pos, int length) throws SQLException where the parameter: • pos is the first character of the substring to be extracted. The first character is located at position 1. • length is the number of consecutive characters copied Return The specified substring in the CLOB as a String is returned. length() Function: Returns the number of bytes in the CLOB value designated by this CLOB object. Characteristic Description Syntax public long length() throws SQLException Return The length of the CLOB is returned. setString(long pos, String str) Function: Writes the given Java string to the CLOB value that this CLOB object designates at position pos. Characteristic Description Syntax public int setString(long pos, String str) throws SQLException where the parameter: • pos is the position at which to start writing to the CLOB value that this CLOB object represents • str is the string to be written to the CLOB value that this CLOB designates Return The number of characters written is returned. Note: The maximum number of bytes that can be set is 64000. setString(long pos, String str, int offset, int len) Function: Writes len characters of str, starting at character offset, to the CLOB value that this CLOB represents. Teradata Driver for the JDBC Interface User Guide 97 Chapter 3: JDBC Methods CLOB Interface Methods Characteristic Description Syntax public int setString(long pos, String str, int offset, int len) throws SQLException where the parameter: • pos is the position at which to start writing to this CLOB object • str is the string to be written to the CLOB value that this CLOB object represents • offset is the offset into str to start reading the characters to be written • len is the number of characters to be written Return The number of characters written is returned. Note: The maximum number of bytes that can be set is 64000. setAsciiStream(long pos) Function: Retrieves a stream to be used to write Ascii characters to the CLOB value that this CLOB object represents, starting at position pos. Characteristic Description Syntax public OutputStream setAsciiStream(long pos) throws SQLException where the parameter pos is the position at which to start writing to this CLOB object Return The stream to which ASCII-encoded characters can be written is returned. setCharacterStream(long pos) Function: Retrieves a stream to be used to write a stream of Unicode characters to the CLOB value that this CLOB object represents, at position pos. Characteristic Description Syntax public Writer setCharacterStream(long pos) throws SQLException where the parameter pos is the position at which to start writing to the CLOB value Return A stream to which Unicode-encoded characters can be written is returned. truncate(long len) Function: Truncates the CLOB value that this CLOB designates to have a length of len characters. 98 Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods CallableStatement Methods Characteristic Description Syntax public void truncate(long len) throws SQLException where the parameter len is the length, in bytes, to which the CLOB value truncates CallableStatement Methods Description A CallableStatement is an object that represents a precompiled SQL statement. Methods Descriptions of the CallableStatement methods supported are presented in alphabetical order. Previous releases of the Teradata Driver for the JDBC Interface returned an erroneous result set if you used CallableStatement.execute() and CallableStatement.executeQuery() to execute macros. Starting with release 03.01.00, you must execute macros using a Statement or PreparedStatement. Using CallableStatement results in an empty result set because Teradata Stored Procedures do not return result sets. getBigDecimal(int parameterIndex) Function Gets the value of a JDBC NUMERIC parameter as a java.math.BigDecimal object with as many digits to the right of the decimal point as the value contains. Syntax public BigDecimal getBigDecimal(int parameterIndex) throws SQLException Returns Where parameter . . . Is . . . parameterIndex the first parameter is 1, the second is 2, and so on. The parameter value in full precision. If the value is SQL NULL, the result is null. Teradata Driver for the JDBC Interface User Guide 99 Chapter 3: JDBC Methods CallableStatement Methods getBigDecimal(int parameterIndex, int scale) Function [DEPRECATED] Gets the value of a JDBC NUMERIC parameter as a java.math.BigDecimal object with scale digits to the right of the decimal point. Syntax public BigDecimal getBigDecimal(int parameterIndex, int scale) throws SQLException Returns Where parameter . . . Is . . . parameterIndex the first parameter is 1, the second is 2, and so on. scale the number of digits to the right of the decimal point. The parameter value in full precision. If the value is SQL NULL, the result is null. getBoolean(int parameterIndex) Function Gets the value of a JDBC BIT parameter as a boolean in the Java programming language. Syntax public boolean getBoolean(int parameterIndex) throws SQLException Returns Where parameter . . . Is . . . parameterIndex the first parameter is 1, the second is 2, and so on. The parameter value. If the value is SQL NULL, the result is false. getByte(int parameterIndex) Function Syntax Returns 100 Gets the value of a JDBC TINYINT parameter as a byte in the Java programming language. public byte getByte(int parameterIndex) throws SQLException Where parameter . . . Is . . . parameterIndex the first parameter is 1, the second is 2, and so on. The parameter value. If the value is SQL NULL, the result is 0. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods CallableStatement Methods getBytes(int parameterIndex) Function Syntax Returns Gets the value of a JDBC BINARY or VARBINARY parameter as an array of byte values in the Java programming language. public byte[] getBytes(int parameterIndex) throws SQLException Where parameter . . . Is . . . parameterIndex the first parameter is 1, the second is 2, and so on. The parameter value. If the value is SQL NULL, the result is null. getDate(int parameterIndex) Function Syntax Gets the value of a JDBC DATE parameter as a java.sql.Date object. public Date getDate(int parameterIndex) throws SQLException Where parameter . . . Is . . . parameterIndex the first parameter is 1, the second is 2, and so on. Returns The parameter value. If the value is SQL NULL, the result is null. Note Maps to ResultSet.getDate(), see this method for further information. getDate(int parameterIndex, Calendar cal) Function Syntax Gets the value of a JDBC DATE parameter as a java.sql.Date object. public Date getDate(int parameterIndex, Calendar cal) throws SQLException Where parameter . . . Is . . . parameterIndex the first parameter is 1, the second is 2, and so on. cal the Calendar object the driver will use to construct the date. Returns The parameter value. If the value is SQL NULL, the result is null. Note Maps to ResultSet.getDate(), see this method for further information. Teradata Driver for the JDBC Interface User Guide 101 Chapter 3: JDBC Methods CallableStatement Methods getDouble(int parameterIndex) Function Syntax Returns Gets the value of a JDBC DOUBLE parameter as a double in the Java programming language. public double getDouble(int parameterIndex) throws SQLException Where parameter . . . Is . . . parameterIndex the first parameter is 1, the second is 2, and so on. The parameter value. If the value is SQL NULL, the result is 0. getFloat(int parameterIndex) Function Syntax Returns Gets the value of a JDBC FLOAT parameter as a float in the Java programming language. public float getFloat(int parameterIndex) throws SQLException Where parameter . . . Is . . . parameterIndex the first parameter is 1, the second is 2, and so on. The parameter value. If the value is SQL NULL, the result is 0. getInt(int parameterIndex) Function Syntax Returns Gets the value of a JDBC INTEGER parameter as an int in the Java programming language. public int getInt(int parameterIndex) throws SQLException Where parameter . . . Is . . . parameterIndex the first parameter is 1, the second is 2, and so on. The parameter value. If the value is SQL NULL, the result is 0. getLobData( ) Function Syntax Returns 102 Retrieves the Lob data from the input stream and returns it to the database. public InputStream getLobData() throws SQLException Returns the Lob data from the input stream to the database. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods CallableStatement Methods getLong(int parameterIndex) Function Syntax Returns Gets the value of a JDBC BIGINT parameter as a long in the Java programming language. public int getLong(int parameterIndex) throws SQLException Where parameter . . . Is . . . parameterIndex the first parameter is 1, the second is 2, and so on. The parameter value. If the value is SQL NULL, the result is 0. getObject(int parameterIndex) Function Syntax Gets the value of a parameter as an object in the Java programming language. public Object getObject(int parameterIndex) throws SQLException Where parameter . . . Is . . . parameterIndex the first parameter is 1, the second is 2, and so on. Returns A java.lang.Object holding the OUT parameter value. Note This method returns a Java object whose type corresponds to the JDBC type that was registered for this parameter using the method registerOutParameter. By registering the target JDBC type as java.sql.Types.OTHER, this method can be used to read database-specific abstract data types. getShort(int parameterIndex) Function Syntax Returns Gets the value of a JDBC SMALLINT parameter as a short in the Java programming language. public short getShort(int parameterIndex) throws SQLException Where parameter . . . Is . . . parameterIndex the first parameter is 1, the second is 2, and so on. The parameter value. If the value is SQL NULL, the result is 0. Teradata Driver for the JDBC Interface User Guide 103 Chapter 3: JDBC Methods CallableStatement Methods getString(int parameterIndex) Function Syntax Retrieves the value of a JDBC CHAR, VARCHAR, or LONGVARCHAR parameter as a String in the Java programming language. public String getString(int parameterIndex) throws SQLException Where parameter . . . Is . . . parameterIndex the first parameter is 1, the second is 2, and so on. Returns The parameter value. If the value is SQL NULL, the result is null. Note For the fixed-length type JDBC CHAR, the String object returned has exactly the same value the JDBC CHAR value had in the database, including any padding added by the database. getTime(int parameterIndex) Function Syntax Gets the value of a JDBC TIME parameter as a java.sql.Time object. public Time getTime(int parameterIndex) throws SQLException Where parameter . . . Is . . . parameterIndex the first parameter is 1, the second is 2, and so on. Note: Maps to ResultSet.getDate(), see this method for further information. Returns The parameter value. If the value is SQL NULL, the result is null. Note Maps to ResultSet.getTime(), see this method for further information. getTime(int parameterIndex, Calendar cal) Function Syntax Gets the value of a JDBC TIME parameter as a java.sql.Time object. public Time getTime(int parameterIndex, Calendar cal) throws SQLException Where parameter . . . Is . . . parameterIndex the first parameter is 1, the second is 2, and so on. cal the Calendar object the driver will use to construct the date. Note: Maps to ResultSet.getDate(), see this method for further information. 104 Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods CallableStatement Methods Returns The parameter value. If the value is SQL NULL, the result is null. Note Maps to ResultSet.getTime(), see this method for further information. getTimestamp(int parameterIndex) Function Syntax Gets the value of a JDBC TIMESTAMP parameter as a java.sql.Timestamp object. public Timestamp getTimestamp(int parameterIndex) throws SQLException Where parameter . . . Is . . . parameterIndex the first parameter is 1, the second is 2, and so on. Returns The parameter value. If the value is SQL NULL, the result is null. Note Maps to ResultSet.getTimestamp(), see this method for further information. getTimestamp(int parameterIndex, Calendar cal) Function Syntax Gets the value of a JDBC TIMESTAMP parameter as a java.sql.Timestamp object. public Timestamp getTimestamp(int parameterIndex, Calendar cal) throws SQLException Where parameter . . . Is . . . parameterIndex the first parameter is 1, the second is 2, and so on. cal the Calendar object the driver will use to construct the date. Returns The parameter value. If the value is SQL NULL, the result is null. Note Maps to ResultSet.getTimestamp(), see this method for further information. registerOutParameter(int parameterIndex, int sqlType) Function Registers the OUT parameter in ordinal position parameterIndex to the JDBC type sqlType. Syntax public void registerOutParameter(int parameterIndex, int sqlType) throws SQLException Where parameter . . . Is . . . parameterIndex the first parameter is 1, the second is 2, and so on. Teradata Driver for the JDBC Interface User Guide 105 Chapter 3: JDBC Methods CallableStatement Methods sqlType Note the JDBC type code defined by java.sql.Types. If the parameter is of type Numeric or Decimal, the version of registerOutParameter that accepts a scale value should be used. All OUT parameters must be registered before a stored procedure is executed. The JDBC type specified by sqlType for an OUT parameter determines the Java type that must be used in the get method to read the value of that parameter. If the JDBC type expected to be returned to this output parameter is specific to this particular database, sqlType should be java.sql.Types.OTHER. The method getObject(int) retrieves the value. registerOutParameter(int parameterIndex, int sqlType, int scale) Function Registers the parameter in ordinal position parameterIndex to be of JDBC type sqlType. Syntax public void registerOutParameter(int parameterIndex, int sqlType, int scale) throws SQLException Note Where parameter . . . Is . . . parameterIndex the first parameter is 1, the second is 2, and so on. sqlType the JDBC type code defined by java.sql.Types. If the parameter is of type Numeric or Decimal, the version of registerOutParameter that accepts a scale value should be used. scale the desired number of digits to the right of the decimal point. It must be greater than or equal to zero. This method must be called before a stored procedure is executed. The JDBC type specified by sqlType for an OUT parameter determines the Java type that must be used in the get method to read the value of that parameter. This version of registerOutParameter should be used when the parameter is of JDBC type NUMERIC or DECIMAL. registerOutParameter(int parameterIndex, int sqlType, String typename) Function Syntax 106 Registers the designated output parameter. public void registerOutParameter(int parameterIndex, int sqlType, String typename) throws SQLException Where parameter . . . Is . . . parameterIndex the first parameter is 1, the second is 2, and so on. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods Connection Methods Note sqlType the JDBC type code defined by java.sql.Types. If the parameter is of type Numeric or Decimal, the version of registerOutParameter that accepts a scale value should be used. typename the fully qualified name of an SQL structured type. The last parameter is ignored. wasNull() Function Syntax Indicates whether or not the last OUT parameter read had the value of SQL NULL. public boolean wasNull() throws SQLException Returns • True if the last parameter read was SQL NULL. • False otherwise. Note This method should be called only after calling the get method; otherwise, there is no value to use in determining whether it is null or not. Connection Methods Description A Connection represents a session with a specific database. Within the context of a Connection, SQL statements are executed and results are returned. A Connection's database is able to provide information describing its tables, its supported SQL grammar, its stored procedures, the capabilities of this connection, and so forth. This information is obtained with the getMetaData method. Note: By default, the Connection automatically commits changes after executing each statement. If auto commit is disabled, an explicit commit must be done or database changes are not saved. Methods The following subsections provide a brief description of each supported Connection method, presented in alphabetic order. clearWarnings() Function Syntax After this call, getWarnings returns null until a new warning is reported for this Connection. public void clearWarnings() throws SQLException Teradata Driver for the JDBC Interface User Guide 107 Chapter 3: JDBC Methods Connection Methods close() Function Syntax Note In some cases, it is desirable to immediately release a Connection's database and JDBC resources instead of waiting for them to be automatically released. The close method provides this immediate release. public void close() throws SQLException A Connection is automatically closed when it is garbage collected. Certain fatal errors also result in a closed Connection. commit() Function Commit makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by the Connection. This method should only be used when auto commit has been disabled. Syntax Note public void commit() throws SQLException See also “setAutoCommit(boolean autoCommit)” on page 117. createStatement() Function Syntax Creates a Statement object for sending SQL statements to the database. public Statement createStatement() throws SQLException Returns A new statement object. Note SQL statements without parameters are normally executed using statement objects. If the same SQL statement is executed many times, it is more efficient to use a prepared statement. createStatement(int resultSetType, int resultSetConcurrency) Function: Creates a statement object for sending SQL statements to the database. This method is the same as the createStatement() method, except that it allows the resultSetType and resultSetConcurrencyType to be overwritten. Characteristic Description Syntax public Statement createStatement(int resultSetType, int resultSetConcurrency) throws SQLException where the parameter: • resultSetType is a result set type • resultSetConcurrency is a concurrency type 108 Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods Connection Methods Characteristic Description Return A new statement object is returned. Note: SQL statements without parameters are normally executed using statement objects. If the same SQL statement is executed many times, it is more efficient to use a prepared statement. getAutoCommit() Function Syntax Returns Gets the current auto-commit state. public boolean getAutoCommit() throws SQLException Current state of auto-commit mode. getCatalog() Function Syntax Gets the current catalog name for the connection. public String getCatalog() throws SQLException Returns Catalog name for the connection or null. Note Since the database does not support catalogs, ““ is always returned. getHoldability() Function Syntax Retrieves the current holdability of ResultSet objects created using this Connection object. public int getHoldability() throws SQLException Returns The default holdability: ResultSet.HOLD_CURSORS_OVER_COMMIT. Note Teradata JDBC driver currently does not support ResultSet.CLOSE_CURSORS_AT_COMMIT. getMetaData() Function Syntax A Connection's database is able to provide information describing its tables, its supported SQL grammar, its stored procedures, the capabilities of this connection, etc. This information is made available through a DatabaseMetaData object. public DatabaseMetaData getMetaData() throws SQLException Teradata Driver for the JDBC Interface User Guide 109 Chapter 3: JDBC Methods Connection Methods Returns A DatabaseMetaData object for this Connection. getTransactionIsolation() Function Syntax Returns Retrieves this Connection object's current transaction isolation level. public int getTransactionIsolation() throws SQLException Returns the current transaction isolation level, which will be one of the following constants: Connection.TRANSACTION_READ_UNCOMMITTED, Connection.TRANSACTION_READ_COMMITTED, Connection.TRANSACTION_REPEATABLE_READ, Connection.TRANSACTION_SERIALIZABLE, or Connection.TRANSACTION_NONE getTypeMap() Function Syntax Returns Retrieves the Map object associated with this Connection object. Unless the application has added an entry, the type map returned will be empty. public Map<String,Class<?>> getTypeMap() throws SQLException Returns the java.util.Map object associated with this Connection object. getWarnings() Function Syntax Returns the first warning reported by calls on this Connection. public SQLWarning getWarnings() throws SQLException Returns The first SQL warning or null. Note Subsequent warnings will be chained to this SQL warning. isClosed() Function Syntax Returns 110 Tests to see if a Connection is closed. public boolean isClosed() throws SQLException • True if the Connection is closed. • False if the Connection is still open. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods Connection Methods isReadOnly() Function Syntax Tests the connection to determine if it is in read-only mode. public boolean isReadOnly() throws SQLException Returns • True if the connection is read-only. • False if the connection is otherwise. Note isReadOnly always returns False. nativeSQL(String sql) Function Syntax Returns A driver may convert the JDBC SQL grammar into its system's native SQL grammar before sending it. NativeSQL returns the native form of the statement. public String nativeSQL(String sql) throws SQLException Where parameter . . . Is . . . sql a SQL statement that may contain one or more '?' parameter placeholders. The native form of this statement. prepareCall(String sql) Function Syntax Creates a CallableStatement object for calling database stored procedures. public CallableStatement prepareCall(String sql) throws SQLException Where parameter . . . Is . . . sql a SQL statement that may contain one or more '?' parameter placeholders. Typically this statement is a JDBC function call escape string. Returns A new CallableStatement object containing the precompiled SQL statement. Note The CallableStatement provides methods for setting up its IN and OUT parameters, and methods for executing the call to a stored procedure. This method is optimized for handling stored procedure call statements. Some drivers may send the call statement to the database when the method prepareCall is done. Others may wait until the CallableStatement is executed. Though this has no direct effect on users, it does affect which method throws certain SQLExceptions. Teradata Driver for the JDBC Interface User Guide 111 Chapter 3: JDBC Methods Connection Methods ResultSets created using the returned CallableStatement have forward-only type and read-only concurrence, by default. prepareCall(String sql, int resultSetType, int resultSetConcurrency) Function Syntax Creates a CallableStatement object for calling database stored procedures. public CallableStatement prepareCall(String sql, int resultSetType, int resultSetConcurrency) throws SQLException Where parameter . . . Is . . . sql a SQL statement that may contain one or more '?' parameter placeholders. Typically this statement is a JDBC function call escape string. resultSetType a result set type resultSetConcurency a concurrency type Returns A new CallableStatement object containing the precompiled SQL statement. Note The CallableStatement provides methods for setting up its IN and OUT parameters, and methods for executing the call to a stored procedure. This method is optimized for handling stored procedure call statements. Some drivers may send the call statement to the database when the method prepareCall is done. Others may wait until the CallableStatement is executed. Though this has no direct effect on users, it does affect which method throws certain SQLExceptions. ResultSets created using the returned CallableStatement have forward-only type and read-only concurrence, by default. prepareStatement(String sql) Function Creates a PreparedStatement object for sending parameterized SQL statements to the database. Syntax public PreparedStatement prepareStatement (String sql) throws SQLException Returns 112 Where parameter . . . Is . . . sql a SQL statement that may contain one or more '?' IN parameter placeholders. A new PreparedStatement object containing the precompiled statement Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods Connection Methods Note A SQL statement with or without IN parameters can be precompiled and stored in a PreparedStatement object. This object can then be used to efficiently execute this statement multiple times. This method is optimized for handling parametric SQL statements that benefit from precompilation. If the driver supports precompilation, the method prepareStatement will send the statement to the database for precompilation. Some drivers may not support precompilation. In this case, the statement may not be sent to the database until the PreparedStatement is executed. Though this has no direct effect on users, it does affect which method throws certain SQLExceptions. ResultSets created using the returned PreparedStatement have forward-only type and read-only concurrence, by default. Connection.prepareStatement(String query) will send the query to the database for parsing. If there is an error with the query, an exception will be generated at this time (for example the table is not yet created). For earlier releases, Connection.prepareStatement(String query) only stored the query instead of sending it to the database for parsing, so no JDBC Exception is generated (example: if the table had not been created yet). Teradata Driver for the JDBC Interface User Guide 113 Chapter 3: JDBC Methods Connection Methods prepareStatement(String sql, int [] columnIndexes) Function Creates a default PreparedStatement object capable of returning the auto-generated keys designated by the given array. This array contains the indexes of the columns in the target table that contain the auto-generated keys that should be made available. This array is ignored if the SQL statement is not an INSERT statement. An SQL statement with or without IN parameters can be pre-compiled and stored in a PreparedStatement object. This object can then be used to efficiently execute this statement multiple times. This method is optimized for handling parametric SQL statements that benefit from precompilation. If the driver supports precompilation, the method prepareStatement will send the statement to the database for precompilation. Some drivers may not support precompilation. In this case, the statement may not be sent to the database until the PreparedStatement object is executed. This has no direct effect on users; however, it does affect which methods throw certain SQLExceptions. Result sets created using the returned PreparedStatement object will by default be type TYPE_FORWARD_ONLY and have a concurrency level of CONCUR_READ_ONLY. Syntax Returns 114 public PreparedStatement prepareStatement (String sql, int[] columnIndexes) throws SQLException Where parameter . . . Is . . . sql an SQL statement that may contain one or more '?' IN parameter placeholders. columnIndexes an array of column indexes indicating the columns that should be returned from the inserted row or rows. A new PreparedStatement object, containing the pre-compiled statement, that is capable of returning the auto-generated keys designated by the given array of column indexes. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods Connection Methods prepareStatement(String sql, String[] columnNames) Function Creates a default PreparedStatement object capable of returning the auto-generated keys designated by the given array. This array contains the names of the columns in the target table that contain the auto-generated keys that should be returned. This array is ignored if the SQL statement is not an INSERT statement. An SQL statement with or without IN parameters can be pre-compiled and stored in a PreparedStatement object. This object can then be used to efficiently execute this statement multiple times. This method is optimized for handling parametric SQL statements that benefit from precompilation. If the driver supports precompilation, the method prepareStatement will send the statement to the database for precompilation. Some drivers may not support precompilation. In this case, the statement may not be sent to the database until the PreparedStatement object is executed. This has no direct effect on users; however, it does affect which methods throw certain SQLExceptions. Result sets created using the returned PreparedStatement object will by default be type TYPE_FORWARD_ONLY and have a concurrency level of CONCUR_READ_ONLY. Syntax Returns public PreparedStatement prepareStatement (String sql, String[] columnNames) throws SQLException Where parameter . . . Is . . . sql a SQL statement that may contain one or more '?' IN parameter placeholders. columnNames an array of column names indicating the columns that should be returned from the inserted row or rows. A new PreparedStatement object, containing the pre-compiled statement, that is capable of returning the auto-generated keys designated by the given array of column names. prepareStatement(String sql, int autogeneratedKeys) Function Creates a default PreparedStatement object that has the capability to retrieve autogenerated keys. The given constant tells the driver whether it should make autogenerated keys available for retrieval. This parameter is ignored if the SQL statement is not an INSERT statement. This method is optimized for handling parametric SQL statements that benefit from precompilation. If the driver supports precompilation, the method prepareStatement will send the statement to the database for precompilation. Some drivers may not support precompilation. In this case, the statement may not be sent to the database until the PreparedStatement object is executed. This has no direct effect on users; however, it does affect which methods throw certain SQLExceptions. Result sets created using the returned PreparedStatement object will by default be type TYPE_FORWARD_ONLY and have a concurrency level of CONCUR_READ_ONLY. Teradata Driver for the JDBC Interface User Guide 115 Chapter 3: JDBC Methods Connection Methods Syntax public PreparedStatement prepareStatement (String sql, int autogeneratedKeys) throws SQLException Where parameter . . . Is . . . sql a SQL statement that may contain one or more '?' IN parameter placeholders. autogeneratedKeys a flag indicating whether auto-generated keys should be returned; one of Statement.RETURN_GENERATED_KEYS or Statement.NO_GENERATED_KEYS. Returns a new PreparedStatement object, containing the pre-compiled SQL statement, that will have the capability of returning auto-generated keys. Note If a database access error occurs or the given parameter is not a Statement constant indicating whether auto-generated keys should be returned, throws and SQLException. Some drivers may not support precompilation. In this case, the statement may not be sent to the database until the PreparedStatement is executed. Though this has no direct effect on users, it does affect which method throws certain SQLExceptions. ResultSets created using the returned PreparedStatement have forward-only type and read-only concurrence, by default. prepareStatement(String sql, int resultSetType, int resultSetConcurrency) Function Syntax Creates a PreparedStatement object for sending parameterized SQL statements to the database. public PreparedStatement prepareStatement (String sql, int resultSetType, int resultSetConcurrency) throws SQLException Where parameter . . . Is . . . sql a SQL statement that may contain one or more '?' IN parameter placeholders. resultSetType a result set type resultSetConcurrency a concurrency type Returns A new PreparedStatement object containing the precompiled statement Note A SQL statement with or without IN parameters can be precompiled and stored in a PreparedStatement object. This object can then be used to efficiently execute this statement multiple times. This method is optimized for handling parametric SQL statements that benefit from precompilation. 116 Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods Connection Methods If the driver supports precompilation, the method prepareStatement will send the statement to the database for precompilation. Some drivers may not support precompilation. In this case, the statement may not be sent to the database until the PreparedStatement is executed. Though this has no direct effect on users, it does affect which method throws certain SQLExceptions. ResultSets created using the returned PreparedStatement have forward-only type and read-only concurrence, by default. rollback() Function Syntax Note Rollback drops all changes made since the previous commit/rollback and releases any database locks currently held by the Connection. public void rollback() throws SQLException This method should only be used when auto commit has been disabled. See also “setAutoCommit(boolean autoCommit)” on page 117. setAutoCommit(boolean autoCommit) Function If a Connection is in auto-commit mode, then all its SQL statements will be executed and committed as individual transactions. Otherwise, its SQL statements are grouped into transactions that are terminated by either commit() or rollback(). By default, new connections are in auto-commit mode. Syntax public void setAutoCommit(boolean autoCommit) throws SQLException Where parameter . . . Is . . . autoCommit the enable/disable specification: • True enables auto-commit. • False disables auto-commit. Note The commit occurs when the statement completes or the next execute occurs, whichever comes first. In the case of statements returning a ResultSet, the statement completes when the last row of the ResultSet has been retrieved or the ResultSet has been closed. In advanced cases, a single statement may return multiple results as well as output parameter values. Here the commit occurs when all results and output parameter values have been retrieved. Teradata Driver for the JDBC Interface User Guide 117 Chapter 3: JDBC Methods Connection Methods setCatalog(String catalog) Function Syntax Note If the driver supports catalogs, this method sets a catalog name. The name selects working space in the connection’s database. If catalogs are not supported, setCatalog is ignored. public void setCatalog(String catalog) throws SQLException Where parameter . . . Is . . . catalog catalog name. As per the standard, setCatalog is silently ignored. setTransactionIsolation(int level) Function Syntax Attempts to change the transaction isolation level for this Connection object to the one given. The constants defined in the interface Connection are the possible transaction isolation levels. public void setTransactionIsolation(int level) throws SQLException Where parameter . . . Is . . . level one of the following Connection constants: Connection.TRANSACTION_READ_UNCOMMITTED, Connection.TRANSACTION_READ_COMMITTED, Connection.TRANSACTION_REPEATABLE_READ, or Connection.TRANSACTION_SERIALIZABLE. Note: Connection.TRANSACTION_NONE cannot be used because it specifies that transactions are not supported. Note If the requested transaction isolation level is not supported, it will be mapped to a higher, more restrictive supported transaction isolation level. The DatabaseMetaData method supportsTransactionIsolationLevel may be used to determine whether or not the driver supports a given level. setTypeMap(Map<String,Class<?>> map) Function Syntax Installs the given TypeMap object as the type map for this Connection object. The type map will be used for the custom mapping of SQL structured types and distinct types. public void setTypeMap(Map<String,Class<?>> map) throws SQLException Where parameter . . . 118 Is . . . Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods ConnectionEvent Methods map the java.util.Map object to install as the replacement for this Connection object's default type map. ConnectionEvent Methods Description The ConnectionEvent class provides information about the source of a connection related event. ConnectionEvent objects provide the following information: • The pooled connection that generated the event • The SQLException about to be thrown to the application (in the case of an error event) Methods ConnectionEvent(PooledConnection con) Function Syntax Returns Construct a ConnectionEvent object. public ConnectionEvent(PooledConnection con) SQLException defaults to null. Where parameter . . . Is . . . con the pooled connection that is the source of the event. Connection Event. ConnectionEvent(PooledConnection con, SQLException ex) Function Syntax Returns Construct a ConnectionEvent object. public ConnectionEvent(PooledConnection con, SQLException ex) Where parameter . . . Is . . . con the pooled connection that is the source of the event. ex the SQLException about to be thrown to the application. Connection Event. Teradata Driver for the JDBC Interface User Guide 119 Chapter 3: JDBC Methods ConnectionEventListener Methods getSQLException() Function Syntax Get the SQLException. public SQLException getSQLException() Returns The SQLException about to be thrown. Note May be null. ConnectionEventListener Methods Description A ConnectionEventListener is an object that registers to receive events generated by a PooledConnection. The ConnectionEventListener interface is implemented by a connection pooling component. A connection pooling component will usually be provided by a JDBC driver vendor, or another system software vendor. A ConnectionEventListener is notified by a JDBC driver when an application is finished using its Connection object. This event occurs after the application calls close on its representation of the PooledConnection. A ConnectionEventListener is also notified when a Connection error occurs due to the fact that the PooledConnection is unfit for future use - the server has crashed, for example. The listener is notified, by the JDBC driver, just before the driver throws an SQLException to the application using the PooledConnection. Methods connectionClosed(ConnectionEvent event) Function Syntax 120 Notifies the ConnectionEvent Listener when the application calls close() on its representation of the connection. public void connectionClosed(ConnectionEvent event) Where parameter . . . Is . . . event an event object describing the source of the event. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods ConnectionPoolDataSource Methods connectionErrorOccurred(ConnectionEvent event) Function Syntax Notifies the ConnectionEvent Listener when a fatal connection error occurs, just before an SQLException is thrown to the application. public void connectionErrorOccurred(ConnectionEvent event) Where parameter . . . Is . . . event an event object describing the source of the event. It contains the SQL exception that the driver throws. ConnectionPoolDataSource Methods Description A ConnectionPoolDataSource object is a factory for PooledConnection objects. An object that implements this interface will typically be registered with a JNDI service. Methods getLoginTimeout() Function Gets the maximum time in seconds that this connection pool data source object can wait while attempting to connect to a database. A value of zero specifies that the timeout is the default system timeout if there is one; otherwise it specifies that there is no timeout. When a DataSource object is created the login timeout is initially zero. Syntax Returns public int getLoginTimeout() throws SQLException The DataSource login timeout value. getLogWriter() Function Gets the log writer for this connection pool data source object. The log writer is a character output stream to which all logging and tracing messages for this data source object instance will be printed. This includes messages printed by the methods of this object, messages printed by methods of other objects manufactured by this object, and so on. Messages printed to a data source specific log writer are not printed to the log writer associated with the java.sql.DriverManager class. When a DataSource object is created the log writer is initially null, in other words, logging is disabled. Syntax public PrintWriter getLogWriter() throws SQLException Teradata Driver for the JDBC Interface User Guide 121 Chapter 3: JDBC Methods ConnectionPoolDataSource Methods Returns The log writer for this connection pool data source object; a null if disabled. getPooledConnection() Function Attempts to establish a database connection which can be used as a pooled connection. Syntax public PooledConnection getPooledConnection() throws SQLException Returns A pooled connection to the database. getPooledConnection(String username, String password) Function Attempts to establish a database connection which can be used as a pooled connection. Syntax public PooledConnection getPooledConnection(String username, String password) throws SQLException Returns Where parameter . . . Is . . . username the database user on whose behalf the Connection is being made. password the user’s password. A Connection to the database. setLoginTimeout(int seconds) Function Syntax Note Sets the maximum time in seconds that this connection pool data source object will wait while attempting to connect to a database. public void setLoginTimeout(int seconds) throws SQLException Where parameter . . . Is . . . seconds the data source login time limit. Sets the maximum time in seconds that this data source will wait while attempting to connect to a database. A value of zero specifies that the timeout is the default system timeout if there is one; otherwise it specifies that there is no timeout. When a DataSource object is created the login timeout is initially zero. This method is supported, but has no effect. 122 Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods DatabaseMetaData Methods setLogWriter(PrintWriter out) Function Sets the log writer for this connection pool data source object to the java.io.PrintWriter.object. Syntax public void setLogWriter(PrintWriter out) throws SQLException Where parameter . . . Is . . . out the new log writer; to disable logging, set to null. Returns The log writer for this data source; a null if disabled. Note The log writer is a character output stream to which all logging and tracing messages for this data source object instance will be printed. This includes messages printed by the methods of this object, messages printed by methods of other objects manufactured by this object, and so on. Messages printed to a data source specific log writer are not printed to the log writer associated with the java.sql.DriverManager class. When a DataSource object is created the log writer is initially null, in other words, logging is disabled. DatabaseMetaData Methods Description The DatabaseMetaData class provides information about the database as a whole. Many of the methods here return lists of information in ResultSets. You can use the normal ResultSet methods such as getString and getInt to retrieve the data from these ResultSets. If a given form of metadata is not available, these methods throw an SQLException. Some of these methods take arguments that are String patterns. These arguments all have names such as fooPattern. Within a pattern String, "%" means match any substring of zero or more characters, and "_" means match any one character. Only metadata entries matching the search pattern are returned. If a search pattern argument is set to a null, it means that argument's criteria should be dropped from the search. An SQLException will be thrown if a driver does not support a metadata method. In the case of methods that return a ResultSet, either a ResultSet (which may be empty) is returned or an SQLException is thrown. Methods The following subsections provide a brief description of each supported DatabaseMetaData method, presented in alphabetic order. Teradata Driver for the JDBC Interface User Guide 123 Chapter 3: JDBC Methods DatabaseMetaData Methods allProceduresAreCallable() Function Syntax Returns Finds out if all of the procedures returned by getProcedures can be called by the current user. public boolean allProceduresAreCallable() throws SQLException • True if all of the procedures returned by getProcedures can be called by the current user. • False if they cannot be called by the current user. allTablesAreSelectable() Function Syntax Returns Finds out if all the tables returned by getTable can be selected by the current user. public boolean allTablesAreSelectable() throws SQLException • True if all of the tables returned by getTable can be selected by the current user. • False if they cannot be selected by the current user. dataDefinitionCausesTransactionCommit() Function Finds out if a data definition statement within a transaction forces the transaction to commit. Syntax public boolean dataDefinitionCausesTransactionCommit() throws SQLException Returns • True if a data definition statement within a transaction forces the transaction to commit. • False if a data definition statement within a transaction does not force the transaction to commit. dataDefinitionIgnoredInTransactions() Function Finds out if a data definition statement within a transaction is ignored. Syntax public boolean dataDefinitionIgnoredInTransactions() throws SQLException Returns • True if a data definition statement within a transaction is ignored. • False if a data definition statement within a transaction is not ignored. deletesAreDetected(int type) Function 124 Finds out if a visible row delete can be detected by calling ResultSet.rowDeleted(). Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods DatabaseMetaData Methods If deletesAreDetected() returns false, then deleted rows are removed from the ResultSet. Syntax Returns public boolean deletesAreDetected(int type) throws SQLException • True if changes are detected by the resultset type. • False if changes are not detected by the resultset type. doesMaxRowSizeIncludeBlobs() Function Syntax Returns Finds out if getMaxRowSize() includes LONGVARCHAR and LONGVARBINARY blobs. public boolean doesMaxRowSizeIncludeBlobs() throws SQLException • True if getMaxRowSize() includes LONGVARCHAR and LONGVARBINARY blobs. • False if getMaxRowSize() does not include LONGVARCHAR and LONGVARBINARY blobs. getAttributes(String catalog, String schemaPattern, String typeNamePattern, String attributeNamePattern) Function Retrieves a description of the given attribute of the given type for a user-defined type (UDT) that is available in the given schema and catalog. Descriptions are returned only for attributes of UDTs matching the catalog, schema, type, and attribute name criteria. They are ordered by: • TYPE_SCHEM • TYPE_NAME • ORDINAL_POSITION This description does not contain inherited attributes. Each column description includes: Column Description TYPE_CAT String Type catalog (may be null). TYPE_SCHEM String Type schema (may be null). TYPE_NAME String Type name. ATTR_NAME String Attribute name. DATA_TYPE int Attribute type SQL type from java.sql.Types Teradata Driver for the JDBC Interface User Guide 125 Chapter 3: JDBC Methods DatabaseMetaData Methods ATTR_TYPE_NAME String Data source dependent type name. For a UDT, the type name is fully qualified. For a REF, the type name is fully qualified and represents the target type of the reference type. ATTR_SIZE int Column size. For char or date types, this is the maximum number of characters. For numeric or decimal types, this is precision. DECIMAL_DIGITS int The number of fractional digits. NUM_PREC_RADIX int Radix (typically either 10 or 2). NULLABLE int Is NULL allowed? • attributeNoNulls—Might not allow NULL values. • attributeNullable—Definitely allows NULL values. • attributeNullableUnknown—Nullab ility unknown. 126 REMARKS String Comment describing column (may be null). ATTR_DEF String Default value (may be null). SQL_DATA_TYPE int Not used SQL_DATETIME_SUB int Not used. CHAR_OCTET_LENGTH int For char types, the maximum number of bytes in the column. ORDINAL_POSITION int Index of column in table (starting at 1). IS_NULLABLE String • NO means column definitely does not allow NULL values. • YES means the column might allow NULL values. An empty string means unknown. SCOPE_CATALOG String Catalog of table that is the scope of a reference attribute (null if DATA_TYPE isn't REF) SCOPE_SCHEMA String Schema of table that is the scope of a reference attribute (null if DATA_TYPE isn't REF) Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods DatabaseMetaData Methods Syntax SCOPE_TABLE String Source type of a distinct type or usergenerated Ref type, SQL type from java.sql.Types (null if DATA_TYPE isn't DISTINCT or user-generated REF) SOURCE_DATA_TYPE short Source type of a distinct type or usergenerated Ref type, SQL type from java.sql.Types (null if DATA_TYPE isn't DISTINCT or user-generated REF) public ResultSet getAttributes(String catalog, String schemaPattern, String typeNamePattern, String attributeNamePattern) throws SQLException Where parameter . . . Is . . . catalog a catalog name; must match the catalog name as it is stored in the database: • "" retrieve those without a catalog. • null means drop catalog name from the selection criteria. schemaPattern A schema name; must match the schema name as it is stored in the database: • "" retrieve those without a catalog. • null means drop catalog name from the selection criteria. Returns typeNamePattern A type name pattern. attributeNamePattern An attribute name pattern. ResultSet—each row is an attribute description. getBestRowIdentifier(String catalog, String schema, String table, int scope, boolean nullable) Function Retrieves a description of a table's optimal set of columns that uniquely identifies a row. They are ordered by SCOPE. Each column description includes: Column Teradata Driver for the JDBC Interface User Guide Description 127 Chapter 3: JDBC Methods DatabaseMetaData Methods SCOPE Short Actual scope of result: • bestRowTemporary - very temporary, while using row • bestRowTransaction - valid for remainder of current transaction • bestRowSession - valid for remainder of current session Syntax COLUMN_NAME String Column name. DATA_TYPE int SQL data type from java.sql.Types . TYPE_NAME String Data source dependent type name. For a UDT, the type name is fully qualified. COLUMN_SIZE int Precision. BUFFER_LENGTH int Is not used. DECIMAL_DIGITS short Scale. PSEUDO_COLUMN short • bestRowUnknown - may or may not be pseudo column • best RowNotPseudo - is NOT a pseudo column • bestRowPseudo - is a pseudo column public ResultSet getBestRowIdentifier(String catalog, String schema, String table, int scope, boolean nullable) throws SQLException Where parameter . . . Is . . . catalog A catalog name; must match the catalog name as it is stored in the database: • "" retrieve those without a catalog. • null means that the catalog name should not be used to narrow the search. schema A schema name pattern; must match the schema name as it is stored in the database. • "" retrieve those without a schema name. • null means that the schema name should not be used to narrow the search. 128 Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods DatabaseMetaData Methods Returns table A table name; must match the table name as it is stored in the database. scope The scope of interest; use same values as SCOPE. nullable Include columns that are nullable. ResultSet---each row is a column description getCatalogs() Function Finds out the catalog names available in the database. Each column description includes: Syntax Column Description TABLE_CAT String Table catalog name. public ResultSet getCatalogs() throws SQLException Returns The results are ordered by catalog name. Each row has a single String column that is a catalog name. Note Currently returns a null. Will be changed in a future release to return an empty result set. getCatalogSeparator() Function Syntax Finds out the separator string between catalog and table name. public String getCatalogSeparator() throws SQLException Returns The separator string between catalog and table name. Note Always returns a "". Catalogs are not supported on the database. getCatalogTerm() Function Syntax Returns Finds out the preferred vendor term for “catalog.” public String getCatalogTerm() throws SQLException The preferred vendor term for “catalog.” Teradata Driver for the JDBC Interface User Guide 129 Chapter 3: JDBC Methods DatabaseMetaData Methods Note Always returns a ““. Catalogs are not supported on the database. getColumnPrivileges(String catalog, String schema, String tableName, String columnNamePattern) Function Retrieves a description of the access rights for a table's columns. Only privileges matching the column name criteria are returned. They are ordered by: • COLUMN_NAME • PRIVILEGE Each privilege description includes: Syntax Column Description TABLE_CAT String Table catalog (may be null). TABLE_SCHEM String Table schema (may be null). TABLE_NAME String Table name. COLUMN_NAME String Column name. GRANTORString Grantor of access (may be null). GRANTEE String Grantee of access . PRIVILEGE String Name of access (SELECT, INSERT, UPDATE, REFRENCES, ...). IS_GRANTABLE String “YES” if grantee is permitted to grant to others; "NO" if not; null if unknown. public ResultSet getColumnPrivileges(String catalog, String schema, String table, String columnNamePattern) throws SQLException Where parameter . . . Is . . . catalog a catalog name; must match the catalog name as it is stored in the database: • "" retrieves those without a catalog. • null means that the catalog name should not be used to narrow the search. 130 Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods DatabaseMetaData Methods schema A schema name pattern; must match the schema name as it is stored in the database. • "" retrieves those without a schema. • null means that the schema name should not be used to narrow the search table A table name; must match the table name as it is stored in the database. columnNamePattern A column name pattern; must match the column name as it is stored in the database. Returns ResultSet—each row is a column privilege description. Note See also the “getSearchStringEscape()” on page 151 method. getColumns(String catalog, String schemaPattern, String tableNamePattern, String columnNamePattern) Function Gets a description of table columns available in the specified catalog. Only column descriptions matching the catalog, schema, table and column name criteria are returned. They are ordered by: • TABLE_SCHEM • TABLE_NAME • ORDINAL_POSITION Each column description includes: Column Description TABLE_CAT String Table catalog (may be null). TABLE_SCHEM String Table schema (may be null). TABLE_NAME String Table name. COLUMN_NAME String Column name. DATA_TYPE short SQL type from java.sql.Types. TYPE_NAME String Data source dependent type name. For a UDT, the type name is fully qualified. Teradata Driver for the JDBC Interface User Guide 131 Chapter 3: JDBC Methods DatabaseMetaData Methods 132 COLUMN_SIZE int Column size. For char or date types, this is the maximum number of characters. For numeric or decimal types, this is precision. BUFFER_LENGTH Is not used. DECIMAL_DIGITS int The number of fractional digits. NUM_PREC_RADIX int Radix (typically either 10 or 2). NULLABLE int • columnNoNulls—Might not allow NULL values. • columnNullable—Definitely allows NULL values. • columnNullableUnknown—Nullabil ity unknown. REMARKS String Comment describing column (may be null). COLUMN_DEF String Default value (may be null). SQL_DATA_TYPE int Not used SQL_DATETIME_SUB int Not used. CHAR_OCTET_LENGTH int For char types, the maximum number of bytes in the column. ORDINAL_POSITION int Index of column in table (starting at 1). IS_NULLABLE String • NO means column definitely does not allow NULL values. • YES means the column might allow NULL values. An empty string means nobody knows. SCOPE_CATLOG String Catalog of table that is the scope of a reference attribute (null if DATA_TYPE isn't REF) SCOPE_SCHEMA String Schema of table that is the scope of a reference attribute (null if the DATA_TYPE isn't REF) SCOPE_TABLE String Table name that this the scope of a reference attribute (null if the DATA_TYPE isn't REF) SOURCE_DATA_TYPE short Source type of a distinct type, SQL type from java.sql.Types (null if DATA_TYPE isn't DISTINCT) Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods DatabaseMetaData Methods Syntax public ResultSet getColumns(String catalog, String schemaPattern, String tableNamePattern, String columnNamePattern) throws SQLException Where parameter . . . Is . . . catalog a catalog name: • "" retrieves those without a catalog. • null means drop catalog name from the selection criteria. schemaPattern A schema name pattern. • "" retrieves those without a schema. • null means drop schema name from the selection criteria. tableNamePattern A table name pattern. columnNamePattern A column name pattern. Returns ResultSet—each row is a column description. Note See also the “getSearchStringEscape()” on page 151 method. getConnection() Function Syntax Returns Retrieves the connection that produced this metadata object. public Connection getConnection() throws SQLException The connection that produced this metadata object Teradata Driver for the JDBC Interface User Guide 133 Chapter 3: JDBC Methods DatabaseMetaData Methods getCrossReference(String primaryCatalog, String primarySchema, String primaryTable, String foreignCatalog, String foreignSchema, String foreignTable) Function Retrieves a description of the foreign key columns in the given foreign key table that reference the primary key columns of the given primary key table (describe how one table imports another's key). This should normally return a single foreign key/primary key pair because most tables import a foreign key from a table only once. They are ordered by: • • • • FKTABLE_CAT FKTABLE_SCHEM FKTABLE_NAME KEY_SEQ Each column description includes: 134 Column Description PKTABLE_CAT String Primary key table catalog (may be null). PKTABLE_SCHEM String Primary key table schema (may be null). PKTABLE_NAME String Primary key table name. PKCOLUMN_NAME String Primary key column name. FKTABLE_CAT String Foreign key table catalog (may be null) being exported (may be null). FKTABLE_SCHEM String Foreign key table schema (may be null) being exported (may be null). FKTABLE_NAME String Foreign key column name being exported. FKCOLUMN_NAME String Foreign key column name being exported. KEY_SEQ short Sequence number within foreign key. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods DatabaseMetaData Methods UPDATE_RULE short What happens to foreign key when primary is updated: • importedNoAction - do not allow update of primary key if it has been imported • importedKeyCascade - change imported key to agree with primary key update • importedKeySetNull - change imported key to NULL if its primary key has been updated • importedKeySetDefault - change imported key to default values if its primary key has been updated • importedKeyRestrict - same as importedKeyNoAction (for ODBC 2.x compatibility) DELETE_RULE short What happens to the foreign key when primary is deleted. • importedKeyNoAction - do not allow delete of primary key if it has been imported. • importedKeyCascade - delete rows that import a deleted key. • importedKeySetNull - change imported key to NULL if its primary key has been deleted. • importedKeyRestrict - same as importedKeyNoAction (for ODBC 2.x compatibility). • importedKeySetDefault - change imported key to default if its primary key has been deleted. FK_NAME String Foreign key name (may be null). PK_NAME String Primary key name (may be null). DEFERRABILITY short Can the evaluation of foreign key constraints be deferred until commit: • importedKeyInitiallyDeferred see SQL92 for definition. • importedKeyInitiallyImmediate see SQL92 for definition. • importedKeyNotDeferrable - see SQL92 for definition. Teradata Driver for the JDBC Interface User Guide 135 Chapter 3: JDBC Methods DatabaseMetaData Methods Syntax public ResultSet getCrossReference(String primaryCatalog, String primarySchema, String primaryTable, String foreignCatalog, String foreignSchema, String foreignTable) throws SQLException Where parameter . . . Is . . . primaryCatalog A catalog name; must match the catalog name as it is stored in the database: • "" retrieves those without a catalog. • null means drop catalog name from the selection criteria. primarySchema A schema name pattern; must match the schema name as it is stored in the database. • "" retrieves those without a schema. • null means drop schema name from the selection criteria. primaryTable The name of the table that exports the key; must match the table name as it is stored in the database. foreignCatalog A catalog name; must match the catalog name as it is stored in the database. • "" retrieves those without a catalog. • null means drop catalog name from the selection criteria. foreignSchema A schema name; must match the schema name as it is stored in the database. • "" retrieves those without a schema. • null means drop schema name from the selection criteria. foreignTable 136 The name of the table that imports the key; must match the table name as it is stored in the database. Returns ResultSet—each row is a foreign key column description. Note See also the getImportedKeys(java.lang.String, java.lang.String, java.lang.String) method. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods DatabaseMetaData Methods getDatabaseMajorVersion() Function: Retrieves the major version number of the underlying database. Characteristic Description Syntax public int getDatabaseMajorVersion() Returns The underlying database’s major version is returned. Note: The major version is the value following the letter V for supported database releases prior to 12.0, such as it returns value 2 for database release V2R6, but it returns value 12 for database release 12.0. getDatabaseMinorVersion() Function: Retrieves the minor version number of the underlying database. Characteristic Description Syntax public int getDatabaseMinorVersion() Return The underlying database’s minor version is returned. Note: The minor version is the value following the letter R for supported database releases prior to 12.0, such as it returns value 6 for database release V2R6, but it returns value 0 for database release 12.0. getDatabaseProductName() Function Syntax Returns Finds out the name of this database product. public String getDatabaseProductName() throws SQLException The database product name. getDatabaseProductVersion() Function: Determines the version of this database product. Characteristic Description Syntax public String getDatabaseProductVersion() throws SQLException Return The database version is returned. Note: The database version is a string that always begins with Teradata Database and that includes V2R for supported database releases prior to 12.0, but does not include V2R for 12.0. Teradata Driver for the JDBC Interface User Guide 137 Chapter 3: JDBC Methods DatabaseMetaData Methods getDefaultTransactionIsolation() Function Syntax Finds out the default transaction isolation level of the database. public int getDefaultTransactionIsolation() throws SQLException Returns The default isolation level. Note The values are defined in java.sql.Connection. getDriverMajorVersion() Function Syntax Returns Finds out this JDBC driver's major version number. public int getDriverMajorVersion() The JDBC driver major version number. getDriverMinorVersion() Function Syntax Returns Finds out this JDBC driver's minor version number. public int getDriverMinorVersion() The JDBC driver minor version number. getDriverName() Function Syntax Returns Finds out the name of this JDBC driver. public String getDriverName() throws SQLException The JDBC driver name. getDriverVersion() Function Syntax Returns 138 Finds out the version of this JDBC driver. public String getDriverVersion() throws SQLException The JDBC driver version. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods DatabaseMetaData Methods getExtraNameCharacters() Function Syntax Returns Gets all the "extra" characters that can be used in unquoted identifier names (those beyond a-z, A-Z, 0-9 and _). public String getExtraNameCharacters() throws SQLException The string containing extra characters. getIdentifierQuoteString() Function Syntax Finds out the string used to quote SQL identifiers. public String getIdentifierQuoteString() throws SQLException Returns • If identifier quoting is supported, it returns the string used to quote SQL identifiers. • If identifier quoting is not supported, a space (" ") is returned. Note A JDBC-compliant driver always uses a double-quote character. Teradata Driver for the JDBC Interface User Guide 139 Chapter 3: JDBC Methods DatabaseMetaData Methods getIndexInfo(String catalog, String schema, String table, boolean unique, boolean approximate) Function Gets a description of the indices and statistics for a table. They are ordered by NON_UNIQUE, TYPE, INDEX_NAME, and ORDINAL_POSITION. Each index column description includes: Column Description TABLE_CAT String Table catalog (may be null). TABLE_SCHEM String Table schema (may be null). TABLE_NAME String Table name. NON_UNIQUE String Can index values be non-unique? False when TYPE is tableIndexStatistic. INDEX_QUALIFIER String Index catalog (may be null). null when TYPE is tableIndexStatistic. INDEX_NAME String Index Name. null when TYPE is tableIndexStatistic, or when the index is unnamed. Teradata permits unnamed indices; refer to the Teradata SQL Reference Data Definition Statements for more information. TYPE short Index Type: • tableIndexStatistic: identifies the table statistics that are returned in conjunction with a table’s index descriptions. • tableIndexClustered: this is a clustered index. • tableIndexHashed: this is a hashed index. • tableIndexOther: this is some other style of index. ORDINAL_POSITION short Column sequence number within index. Zero when TYPE is tableIndexStatistic. COLUMN_NAME String Column Name. Null when TYPE is tableIndexStatistic. ASC_OR_DESC String Column sort sequence. • A: ascending • D: descending May be null if sort sequence is not supported. Null when TYPE is tableIndexStatistic. 140 Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods DatabaseMetaData Methods Syntax CARDINALITY int When TYPE is tableIndexStatistic, this is the number of rows in the table. Otherwise, it is the number of unique values in the index. PAGES int When TYPE is tableIndexStatistic, this is the number of pages used for the table. Otherwise, it is the number of pages used for the current index. FILTER_CONDITION String Filter condition, if any (may be null) public ResultSet getIndexInfo(String catalog, String schema, String table, boolean unique, boolean approximate) throws SQLException Where parameter . . . Is . . . catalog a catalog name: • "" retrieves those without a catalog. • null means drop catalog name from the selection criteria. schema a schema name: "" retrieves those without a schema. table A table name. unique Indice uniqueness: • True: returns only indices for unique values. • False: returns indices regardless of whether unique or not. approximate Approximate values: • True: result is allowed to reflect approximate or out of data values. • False: results are requested to be accurate. Returns ResultSet—each row is an index column description. getMaxBinaryLiteralLength() Function Syntax Finds out how many hex characters you can have in an in line binary literal. public int getMaxBinaryLiteralLength() throws SQLException Returns The maximum binary literal length in hex characters. Note A result of zero means that there is no limit to the binary literal or the limit is unknown. Teradata Driver for the JDBC Interface User Guide 141 Chapter 3: JDBC Methods DatabaseMetaData Methods getMaxCatalogNameLength() Function Syntax Determines the maximum length of a catalog name. public int getMaxCatalogNameLength() throws SQLException Returns The maximum catalog name length in bytes. Note A result of zero means that there is no limit to the catalog name or the limit is unknown. getMaxCharLiteralLength() Function Syntax Finds out the maximum length for a character literal. public int getMaxCharLiteralLength() throws SQLException Returns The maximum literal length. Note A result of zero means that there is no limit to the Character literal or the limit is unknown. getMaxColumnNameLength() Function Syntax Returns Finds out the limit on column name length. public int getMaxColumnNameLength() throws SQLException The maximum literal length for a column name. getMaxColumnsInGroupBy() Function Syntax 142 Finds out the maximum number of columns in a GROUP BY clause. public int getMaxColumnsInGroupBy() throws SQLException Returns The maximum number of columns in a a GROUP BY clause. Note A result of zero means that there is no limit or the limit is unknown. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods DatabaseMetaData Methods getMaxColumnsInIndex() Function Syntax Finds out the maximum number of columns allowed in an index. public int getMaxColumnsInIndex() throws SQLException Returns The maximum number of columns allowed in an index. Note A result of zero means that there is no limit or the limit is unknown. getMaxColumnsInOrderBy() Function Syntax Finds out the maximum number of columns allowed in an ORDER BY clause. public int getMaxColumnsInOrderBy() throws SQLException Returns The maximum number of columns allowed in an ORDER BY clause. Note A result of zero means that there is no limit or the limit is unknown. getMaxColumnsInSelect() Function Syntax Finds out the maximum number of columns allowed in a SELECT list. public int getMaxColumnsInSelect() throws SQLException Returns The maximum number of columns allowed in a SELECT list. Note A result of zero means that there is no limit or the limit is unknown. getMaxColumnsInTable() Function Syntax Finds out the maximum number of columns allowed in a table. public int getMaxColumnsInTable() throws SQLException Returns The maximum number of columns allowed in a table. Note A result of zero means that there is no limit or the limit is unknown. Teradata Driver for the JDBC Interface User Guide 143 Chapter 3: JDBC Methods DatabaseMetaData Methods getMaxConnections() Function Syntax Finds out how many active connections are allowed at a time to this database. public int getMaxConnections() throws SQLException Returns The maximum active connections allowed at a time to this database. Note A result of zero means that there is no limit or the limit is unknown. getMaxCursorNameLength() Function Syntax Finds out the maximum cursor name length in bytes. public int getMaxCursorNameLength() throws SQLException Returns The maximum cursor name length in bytes. Note A result of zero means that there is no limit or the limit is unknown. getMaxIndexLength() Function Syntax Finds out the maximum length of an index in bytes. public int getMaxIndexLength() throws SQLException Returns The maximum length of an index in bytes. Note Includes the composite of all the constituent parts of the index. A result of zero means that there is no limit or the limit is unknown. getMaxProcedureNameLength() Function Syntax 144 Determines the maximum length of a procedure name. public int getMaxProcedureNameLength() throws SQLException Returns The maximum procedure name length in bytes. Note A result of zero means that there is no limit to the procedure name or the limit is unknown. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods DatabaseMetaData Methods getMaxRowSize() Function Syntax Finds out the maximum length of a single row in bytes. public int getMaxRowSize() throws SQLException Returns The maximum length of a single row in bytes. Note A result of zero means that there is no limit or the limit is unknown. getMaxSchemaNameLength() Function Syntax Finds out the maximum length allowed for a schema name in bytes. public int getMaxSchemaNameLength() throws SQLException Returns The maximum length allowed for a schema name in bytes. Note A result of zero means that there is no limit or the limit is unknown. getMaxStatementLength() Function Syntax Finds out the maximum length of an SQL statement in bytes. public int getMaxStatementLength() throws SQLException Returns The maximum length of an SQL statement in bytes. Note A result of zero means that there is no limit or the limit is unknown. getMaxStatements() Function Syntax Finds out how many active statements can be open at one time. public int getMaxStatements() throws SQLException Returns The maximum number of active statements allowed at one time. Note A result of zero means that there is no limit or the limit is unknown. Teradata Driver for the JDBC Interface User Guide 145 Chapter 3: JDBC Methods DatabaseMetaData Methods getMaxTableNameLength() Function Syntax Finds out the maximum length of a table name in bytes. public int getMaxTableNameLength() throws SQLException Returns The maximum length of a table name in bytes. Note A result of zero means that there is no limit or the limit is unknown. getMaxTablesInSelect() Function Syntax Finds out the maximum number of tables in a SELECT statement. public int getMaxTablesInSelect() throws SQLException Returns The maximum number of tables allowed in a SELECT statement. Note A result of zero means that there is no limit or the limit is not known. getMaxUserNameLength() Function Syntax Finds out the maximum length of a user name. public int getMaxUserNameLength() throws SQLException Returns The maximum user name length in bytes. Note Zero means that there is no limit or the limit is not known. getNumericFunctions() Function Syntax Returns Gets a comma separated list of the X/Open CLI math function names in JDBC function escape clauses. public String getNumericFunctions() throws SQLException The list of math functions. getPrimaryKeys(String catalog, String schema, String table) Function Gets a description of a table's primary key columns. They are ordered by COLUMN_NAME. Each primary key column description has the following columns: 146 Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods DatabaseMetaData Methods Syntax Returns Column Description TABLE_CAT String Table catalog (may be null). TABLE_SCHEM String Table schema (may be null). TABLE_NAME String Table name. COLUMN_NAME String Column name. KEY_SEQ short Sequence number within primary key. PK_NAME String Primary key name (may be null). public ResultSet getPrimaryKeys(String catalog, String schema, String table) throws SQLException Where parameter . . . Is . . . catalog a catalog name; "" retrieves those without a catalog; null means drop catalog name from the selection criteria. schema a schema name; "" retrieves those without a schema. table a table name. ResultSet - each row is a primary key column description getProcedureColumns(String catalog, String schemaPattern, String procedureNamePattern, String columnNamePattern) Function Syntax Gets a description of the stored procedure parameters and result columns of a catalog. public ResultSet getProcedureColumns(String catalog, String schemaPattern, String procedureNamePattern, String columnNamePattern) throws SQLException Where parameter . . . Is . . . catalog a catalog name: • "" retrieves those without a catalog. • null means drop catalog name from the selection criteria. schemaPattern a schema name pattern: • "" retrieves those without a schema. • null means drop schema name from the selection criteria. Teradata Driver for the JDBC Interface User Guide 147 Chapter 3: JDBC Methods DatabaseMetaData Methods Returns procedureNamePattern a procedure name pattern. columnNamePattern a column name pattern. Descriptions matching the schema, procedure and parameter name criteria, ordered by PROCEDURE_SCHEM and PROCEDURE_NAME. Within this, the return value, if any, is first. Next are the parameter descriptions in call order. The column descriptions follow in column number order. Each row in the ResultSet is a parameter description or column description with the following fields: Column Description PROCEDURE_CAT String Procedure catalog (may be null). PROCEDURE_SCHEM String Procedure schema (may be null). PROCEDURE_NAME String Procedure name. COLUMN_NAME String Column/parameter name. COLUMN_TYPE short Kind of column parameter: • procedureColumnUnknown—Nobody knows. • procedureColumnIn—The IN parameter. • procedureColumnInOut—The INOUT parameter. • procedureColumnOut—The OUT parameter. • procedureColumnReturn—Procedure return value. • procedureColumnResult—Result column in ResultSet. 148 DATA_TYPE int SQL type from java.sql.Types. TYPE_NAME String SQL type name, for a UDT type the type name is fully qualified. PRECISION int Precision. LENGTH int Length in bytes of data. SCALE short Scale. RADIX short Radix. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods DatabaseMetaData Methods NULLABLE short Can it contain NULL? • procedureNoNulls-does not allow NULL values. • procedureNullable-Allows NULL values. • procedureNullableUnknown. REMARKS String Note Comment describing parameter/column. Note: Some databases may not return the column descriptions for a procedure. Additional columns beyond REMARKS can be defined by the database. getProcedures(String catalog, String schemaPattern, String procedureNamePattern) Function Syntax Gets a description of the stored procedures available in a catalog. public ResultSet getProcedures(String catalog, String schemaPattern, String procedureNamePattern) throws SQLException Where parameter . . . Is . . . catalog a catalog name: • "" retrieves those without a catalog. • null means drop catalog name from the selection criteria. schemaPattern a schema name pattern: "" retrieves those without a schema. procedureNamePattern Returns a procedure name pattern. ResultSet where each row is a procedure description, ordered by PROCEDURE_SCHEM, and PROCEDURE_NAME. Each procedure description has the following columns: Column Description PROCEDURE_CAT String Procedure catalog (may be null). PROCEDURE_SCHEM String Procedure schema (may be null). PROCEDURE_NAME String Procedure name. Reserved Reserved for future use. Reserved Reserved for future use. Teradata Driver for the JDBC Interface User Guide 149 Chapter 3: JDBC Methods DatabaseMetaData Methods Reserved Reserved for future use. REMARKS String Explanatory comment on the procedure. PROCEDURE_TYPE short Kind of procedure: • procedureResultunknown-may return result. • procedureNoResult-does not return guilty • procedureReturnsResult-Returns a result. getProcedureTerm() Function Syntax Returns Finds out the database vendor preferred term for “procedure”. public String getProcedureTerm() throws SQLException The database vendor’s preferred term for “procedure”. getResultSetHoldability() Function Syntax Retrieves the default holdability of this ResultSet object. public int getResultSetHoldability() throws SQLException Returns The default holdability: ResultSet.HOLD_CURSORS_OVER_COMMIT. Note Teradata JDBC driver currently does not support ResultSet.CLOSE_CURSORS_AT_COMMIT. getSchemas() Function Syntax Returns 150 Gets the schema names available in this database. The results are ordered by schema name. public ResultSet getSchemas() throws SQLException Column Description TABLE_SCHEM String Schema name. ResultSet - each row has a single String column that is a schema name. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods DatabaseMetaData Methods getSchemaTerm() Function Syntax Returns Finds out the term for schema that is preferred by the database vendor. public String getSchemaTerm() throws SQLException The term for schema that is preferred by the database vendor. getSearchStringEscape() Function Gets the string that can be used to escape wildcard characters. This is the string that can be used to escape “_”or “%” in the string pattern style catalog search parameters where: • The “_” character represents any single character • The “%” character represents any sequence of zero or more characters Syntax Returns public String getSearchStringEscape() throws SQLException The string used to escape wildcard characters. getSQLKeywords() Function Syntax Returns Gets a comma-separated list of all the SQL keywords in a database that are NOT also SQL92 keywords. public String getSQLKeywords() throws SQLException The list of keywords. getStringFunctions() Function Syntax Returns Gets a comma separated list of X/Open CLI string function names used in the JDBC function escape clause. public String getStringFunctions() throws SQLException The list of string functions. getSystemFunctions() Function Gets a comma-separated list of X/Open CLI system function names. These are the X/Open CLI system function names used in the JDBC function escape clause. Teradata Driver for the JDBC Interface User Guide 151 Chapter 3: JDBC Methods DatabaseMetaData Methods Syntax Returns public String getSystemFunctions() throws SQLException The list of system functions. getTablePrivileges(String catalog, String schemaPattern, String tableNamePattern) Function Retrieves a description of the access rights for each table available in a catalog. Note that a table privilege applies to one or more columns in the table. It would be wrong to assume that this privilege applies to all columns (this may be true for some systems but is not true for all.) Only privileges matching the schema and table name criteria are returned. They are ordered by: • TABLE_SCHEM • TABLE_NAME • PRIVILEGE Each table description includes: Syntax Column Description TABLE_CAT String Table catalog (may be null). TABLE_SCHEM String Table schema (may be null). TABLE_NAME String Table name. GRANTOR String Grantor of access (may be null). GRANTEE String Grantee of access. PRIVILEGE String Name of access (SELECT, INSERT, UPDATE, REFRENCES, ...). IS_GRANTABLE String “YES” if grantee is permitted to grant to others; “NO” if not; null if unknown. public ResultSet getTablePrivileges(String catalog, String schemaPattern, String tableNamePattern)throws SQLException Where parameter . . . Is . . . catalog A catalog name; must match the catalog name as it is stored in the database: • "" retrieves those without a catalog. • null means that the catalog name should not be used to narrow the search. 152 Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods DatabaseMetaData Methods schemaPattern A schema name pattern; must match the schema name as it is stored in the database: • "" retrieves those without a schema. • null means that the schema name should not be used to narrow the search. tableNamePattern A table name pattern; must match the table name as it is stored in the database. Returns ResultSet - each row is a table privilege description. Note See also the “getSearchStringEscape()” on page 151. getTables(String catalog, String schemaPattern, String tableNamePattern, String[] types) Function Gets a description of tables available in a catalog, ordered by: • TABLE_TYPE • TABLE_SCHEM • TABLE_NAME Only table descriptions matching the catalog, schema, table name and type criteria are returned. Each table description includes: Column Description TABLE_CAT String Table catalog (may be null). TABLE_SCHEM String Table schema (may be null). TABLE_NAME String Table name. TABLE_TYPE String Table type. Typical types are: • • • • • • • REMARKS String Syntax TABLE VIEW SYSTEM TABLE GLOBAL TEMPORARY LOCAL TEMPORARY ALIAS SYNONYM Explanatory comment on the table. public ResultSet getTables(String catalog, String schemaPattern, String tableNamePattern, String[] types) throws SQLException Teradata Driver for the JDBC Interface User Guide 153 Chapter 3: JDBC Methods DatabaseMetaData Methods Where parameter . . . Is . . . catalog a catalog name: • "" retrieves those without a catalog. • null means drop catalog name from the selection criteria. schemaPattern a schema name pattern: "" retrieves those without a schema. tableNamePattern a table name pattern. types a list of table types to include: null returns all types. Returns ResultSet - each row is a table description. Note Some databases may not return information for all tables. See also the “getSearchStringEscape()” on page 151. getTableTypes() Function Syntax Gets the table types available in the database system. The results are ordered by table types. public getTableTypes() throws SQLException Column Description TABLE_TYPE String table type. Typical types are: • • • • • • • Returns TABLE VIEW SYSTEM TABLE GLOBAL TEMPORARY LOCAL TEMPORARY ALIAS SYNONYM A ResultSet object with each row has a single string column is a table type. getTimeDateFunctions() Function 154 Gets a comma-separated list of time and date functions. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods DatabaseMetaData Methods Syntax Returns public String getTimeDateFunctions() throws SQLException The list of time and date functions. getTypeInfo() Function Get a description of all the standard SQL types supported by this database. They are ordered by DATA_TYPE and then by how closely the data type maps to the corresponding JDBC SQL type. Each type description has the following columns: Column Description TYPE_NAME String type name. DATA_TYPE Short SQL data type from java.sql.Types. PRECISION int maximum precision. LITERAL_PREFIX String prefix used to quote a literal (may be null.) LITERAL_SUFFIX String suffix used to quote a literal (may be null.) CREATE_PARAMS String parameters used in creating the type (may be null.) NULLABLE short indicating whether the column can be a null” • type NoNulls - does not allow NULL values. • type Nullable - allows NULL values. • type NullableUnknown. CASE_SENSITIVE boolean true to indicate that the type is case-sensitive. false indicates that it is not case-sensitive. SEARCHABLE Short indicating whether it is possible to uses a WHERE clause. • typePredNone - no support. • typePredChar - only supported with WHERE....LIKE. • typePredBasic - support except for WHERE....LIKE. • typeSearchable - support for all WHERE. UNSIGNED_ATTRIBUTE boolean • true indicates the type is unsigned. • false indicates that it is signed. FIXED_PREC_SCALE boolean • true indicates the type can be a money value. • false indicates that the type cannot be a money value. Teradata Driver for the JDBC Interface User Guide 155 Chapter 3: JDBC Methods DatabaseMetaData Methods Syntax Returns AUTO_INCREMENT boolean • true indicates the type can be used for autoincrement. • false indicates that the type cannot be used for auto-increment. LOCAL_TYPE_NAME String localized version of type name (may be null). MINIMUM_SCALE short minimum scale supported. MAXIMUM_SCALE short maximum scale supported. SQL_DATA_TYPE int unused. SQL_DATETIME_SUB int unused. NUM_PREC_RADIX int usually 2 or 10. public ResultSet getTypeInfo() throws SQLException ResultSet - each row is an SQL type description. getUDTs(String catalog, String schemaPattern, string typeNamePattern, int[] types) Function Retrieves a description of the user-defined types (UDTs) defined in a particular schema. Schema-specific UDTs may have type JAVA_OBJECT, STRUCT, or DISTINCT. Only types matching the catalog, schema, type name and type criteria are returned. They are ordered by: • DATA_TYPE • TYPE_SCHEM • TYPE_NAME The type name parameter may be a fully-qualified name. In this case, the catalog and schemaPattern parameters are ignored. Each type description has the following columns: 156 Column Description TYPE_CAT String The type's catalog (may be null). TYPE_SCHEM String Type's schema (may be null). TYPE_NAME String Type name. CLASS_NAME String Java class name. DATA_TYPE int Type value defined in java.sql.Types. One of JAVA_OBJECT, STRUCT, or DISTINCT. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods DatabaseMetaData Methods Syntax REMARKS String Explanatory comment on the type. BASE_TYPE short Type code of the source type of a DISTINCT type or the type that implements the usergenerated reference type of the SELF_REFERENCING_COLUMN of a structured type as defined in java.sql.Types (null if DATA_TYPE is not DISTINCT or not STRUCT with REFERENCE_GENERATION = USER_DEFINED). public ResultSet getUDTs(String catalog, String schemaPattern, string typeNamePattern, int[] types) throws SQLException Where parameter . . . Is . . . catalog a catalog name: • "" retrieve those without a catalog. • null means drop catalog name from the selection criteria. schemaPattern a schema name pattern: • "" retrieve those without a catalog. • null means drop catalog name from the selection criteria. Returns typeNamePattern a type name pattern. types a list of user-defined types (JAVA_OBJECT, STRUCT, or DISTINCT) to include; null returns all types. ResultSet - each row describes a UDT. getURL() Function Syntax Returns Finds out the URL for this database. public String getURL() throws SQLException • If it can be generated, the URL. • If it cannot be generated, null. getUserName() Function Syntax Finds out your user name, as known to the database. public String getUserName() throws SQLException Teradata Driver for the JDBC Interface User Guide 157 Chapter 3: JDBC Methods DatabaseMetaData Methods Returns Your database user name. getVersionColumns(String catalog, String schema, string table) Function Retrieves a description of a table's columns that are automatically updated when any value in a row is updated. They are unordered. Each column description has the following columns: Column Description SCOPE short Is not used. COLUMN_NAME String Column name. DATA_TYPE int SQL data type from java.sql.Types. TYPE_NAME String Data source-dependent type name. COLUMN_SIZE int Precision. BUFFER_LENGTH int Length of column value in bytes. DECIMAL_DIGITS short Scale. PSEUDO_COLUMN short Determines if this is pseudo column like an Oracle ROWID: • versionColumnUnknown - may or may not be pseudo column. • versionColumnNotPseudo - is NOT a pseudo column. • versionColumnPseudo - is a pseudo column. Syntax getVersionColumns(String catalog, String schema, String table) throws SQLException Where parameter . . . Is . . . catalog a catalog name; must match the catalog name as it is stored in the database: • "" retrieve those without a catalog. • null means that the catalog name should not be used to narrow the search. schema a schema name; must match the schema name as it is stored in the database: • “” retrieve those without a schema. • null means that the schema name should not be used to narrow the search. 158 Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods DatabaseMetaData Methods table a table name; must match the table name as it is stored in the database. Returns A ResultSet object in which each row is a column description. Note Teradata implementation for getVersionColumns is limited and gives back only an empty resultset. insertsAreDetected(int type) Function Syntax Returns Finds out if a visible row insert can be detected by calling ResultSet.rowInserted(). public boolean insertsAreDetected(int type) throws SQLException Where parameter . . . Is . . . type the ResultSet type, such as TYPE_XXX. • True, if changes are detected by the resultset type. • False, if changes are not detected by the resultset type. isCatalogAtStart() Function Syntax Determines if a catalog appears at the start of a table. public boolean isCatalogAtStart() throws SQLException Returns • True if the catalog appears at the start of the table. • False if it does not appear at the start of the table. Note If False, the catalog appears at the end of the table. This method is supported by the Teradata JDBC Driver, but it is not supported by the Teradata Database. Teradata will return a null result set. isReadOnly() Function Syntax Returns Finds out if the database in read-only mode. public boolean isReadOnly() throws SQLException • True if the database is in read-only mode. • False if the database is not in read-only mode. Teradata Driver for the JDBC Interface User Guide 159 Chapter 3: JDBC Methods DatabaseMetaData Methods nullPlusNonNullIsNull() Function Syntax Returns Finds out if concatenations between NULL and nonNULL values is NULL. public boolean nullPlusNonNullIsNull() throws SQLException • True if concatenations between NULL and nonNULL values are NULL. • False if concatenations between NULL and nonNULL values are not NULL. nullsAreSortedAtEnd() Function Syntax Returns Finds out if NULL values are sorted at the end regardless of sort order. public boolean nullsAreSortedAtEnd() throws SQLException • True if NULL values are sorted at the end regardless of sort order. • False if NULL values are not sorted at the end. nullsAreSortedAtStart() Function Syntax Returns Finds out if NULL values sorted at the start regardless of sort order. public boolean nullsAreSortedAtStart() throws SQLException • True if NULL values sorted at the start regardless of sort order. • False nullsAreSortedHigh() Function Syntax Returns Finds out if NULL values are sorted high. public boolean nullsAreSortedHigh() throws SQLException • True if null values are sorted high. • False if null values are not sorted high. nullsAreSortedLow() Function Syntax Returns 160 Finds out if NULL values are sorted low. public boolean nullsAreSortedLow() throws SQLException • True if NULL values are sorted low. • False if null values are not sorted high. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods DatabaseMetaData Methods othersDeletesAreVisible(int type) Function Syntax Finds out if deletes made by others are visible. public boolean othersDeletesAreVisible(int type) throws SQLException Where parameter . . . Is . . . type the ResultSet type, such as TYPE_XXX. Returns • True if deletes made by others are visible for the ResultSet type. • False if deletes made by others are not visible for the ResultSet type. Note Always returns False, since updateable ResultSets are not supported. othersInsertsAreVisible(int type) Function Syntax Finds out if inserts made by others are visible. public boolean othersInsertsAreVisible(int type) throws SQLException Where parameter . . . Is . . . type the ResultSet type, such as TYPE_XXX. Returns • True if inserts made by others are visible for the ResultSet type. • False if inserts made by others are not visible for the ResultSet type. Note Always returns False, since updateable ResultSets are not supported. othersUpdatesAreVisible(int type) Function Syntax Finds out if updates made by others are visible. public boolean othersUpdatesAreVisible(int type) throws SQLException Where parameter . . . Is . . . type the ResultSet type, such as TYPE_XXX. Returns • True if updates made by others are visible for the ResultSet type. • False if updates made by others are not visible for the ResultSet type. Note Always returns False, since updateable ResultSets are not supported. Teradata Driver for the JDBC Interface User Guide 161 Chapter 3: JDBC Methods DatabaseMetaData Methods ownDeletesAreVisible(int type) Function Syntax Finds out if the own deletes of a ResultSet are visible. public boolean ownDeletesAreVisible(int type) throws SQLException Where parameter . . . Is . . . type the ResultSet type, such as TYPE_XXX. Returns • True if deletes are visible for the ResultSet type. • False if deletes are not visible for the ResultSet type. Note Always returns False, since updateable ResultSets are not supported. ownInsertsAreVisible(int type) Function Syntax Finds out if the own inserts of a ResultSet are visible. public boolean ownInsertsAreVisible(int type) throws SQLException Where parameter . . . Is . . . type the ResultSet type, such as TYPE_XXX. Returns • True if inserts are visible for the ResultSet type. • False if inserts are not visible for the ResultSet type. Note Always returns False, since updateable ResultSets are not supported. ownUpdatesAreVisible(int type) Function Syntax 162 Finds out if the own updates of a ResultSet are visible. public boolean ownUpdatesAreVisible(int type) throws SQLException Where parameter . . . Is . . . type the ResultSet type, such as TYPE_XXX. Returns • True if updates are visible for the ResultSet type. • False if updates are not visible for the ResultSet type. Note Always returns False, since updateable ResultSets are not supported. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods DatabaseMetaData Methods storesLowerCaseIdentifiers() Function Syntax Returns Finds out if the database treats mixed case unquoted SQL identifiers as case insensitive and stores them in lower case. public boolean storesLowerCaseIdentifiers() throws SQLException • True if the database treats mixed case unquoted SQL identifiers as case insensitive and stores them in lower case. • False if the database does not treat mixed case unquoted SQL identifiers as case insensitive. storesLowerCaseQuotedIdentifiers() Function Finds out if the database treats mixed case quoted SQL identifiers as case insensitive and stores them in lower case. Syntax public boolean storesLowerCaseQuotedIdentifiers() throws SQLException Returns • True if the database treats mixed case quoted SQL identifiers as case insensitive and stores them in lower case. • False if the database does not treat mixed case quoted SQL identifiers as case insensitive. storesMixedCaseIdentifiers() Function Syntax Returns Finds out if the database treats mixed case unquoted SQL identifiers as case insensitive and stores them in mixed case. public boolean storesMixedCaseIdentifiers() throws SQLException • True if the database treats mixed case unquoted SQL identifiers as case insensitive and stores them in mixed case. • False if the database does not treat mixed case unquoted SQL identifiers as case insensitive. storesMixedCaseQuotedIdentifiers() Function Finds out if the database treats mixed case quoted SQL identifiers as case insensitive and stores them in mixed case. Syntax public boolean storesMixedCaseQuotedIdentifiers() throws SQLException Returns • True if the database treats mixed case quoted SQL identifiers as case insensitive and stores them in mixed case. • False if the database does not treat mixed case quoted SQL identifiers as case insensitive. Teradata Driver for the JDBC Interface User Guide 163 Chapter 3: JDBC Methods DatabaseMetaData Methods storesUpperCaseIdentifiers() Function Syntax Returns Finds out if the database treats mixed case unquoted SQL identifiers as case insensitive and stores them in upper case. public boolean storesUpperCaseIdentifiers() throws SQLException • True if the database treats mixed case unquoted SQL identifiers as case insensitive and stores them in upper case. • False if the database does not treat mixed case unquoted SQL identifiers as case insensitive. storesUpperCaseQuotedIdentifiers() Function Finds out if the database treats mixed case quoted SQL identifiers as case insensitive and stores them in upper case. Syntax public boolean storesUpperCaseQuotedIdentifiers() throws SQLException Returns • True if the database treats mixed case quoted SQL identifiers as case insensitive and stores them in upper case. • False if the database does not treat mixed case quoted SQL identifiers as case insensitive. supportsAlterTableWithAddColumn() Function Finds out if ALTER TABLE with add column is supported. Syntax public boolean supportsAlterTableWithAddColumn() throws SQLException Returns • True if ALTER TABLE with add column is supported. • False if ALTER TABLE with add column is not supported. supportsAlterTableWithDropColumn() Function 164 Finds out if ALTER TABLE with drop column is supported. Syntax public boolean supportsAlterTableWithDropColumn() throws SQLException Returns • True if ALTER TABLE with drop column is supported. • False if ALTER TABLE with drop column is not supported. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods DatabaseMetaData Methods supportsANSI92EntryLevelSQL() Function Syntax Finds out if the ANSI92 entry level SQL grammar is supported. public boolean supportsANSI92EntryLevelSQL() throws SQLException Returns True if the ANSI92 entry level SQL grammar is supported. Note All JDBC-compliant drivers must return true. supportsANSI92FullSQL() Function Syntax Returns Finds out if the ANSI92 full SQL grammar is supported. public boolean supportsANSI92FullSQL() throws SQLException • True if the ANSI92 full SQL grammar is supported. • False if the ANSI92 full SQL grammar is not supported. supportsANSI92IntermediateSQL() Function Finds out if the ANSI92 intermediate SQL grammar is supported. Syntax public boolean supportsANSI92IntermediateSQL() throws SQLException Returns • True if the ANSI92 intermediate SQL grammar is supported. • False if the ANSI92 intermediate SQL grammar is not supported. supportsBatchUpdates() Function Syntax Returns Finds out if the driver supports batch updates. public boolean supportsBatchUpdates() throws SQLException • True if the driver supports batch updates. • False if the driver does not support batch updates. supportsCatalogsInDataManipulation() Function Syntax Finds out if a catalog name can be used in a data manipulation statement. public boolean supportsCatalogsInDataManipulation() throws SQLException Teradata Driver for the JDBC Interface User Guide 165 Chapter 3: JDBC Methods DatabaseMetaData Methods Returns • True if a catalog name can be used in a data manipulation statement. • False if a catalog name cannot be used in a data manipulation statement. supportsCatalogsInIndexDefinitions() Function Finds out if a catalog name can be used in an index definition statement. Syntax public boolean supportsCatalogsInIndexDefinitions() throws SQLException Returns • True if a catalog name can be used in an index definition statement. • False if a catalog name cannot be used in an index definition statement. supportsCatalogsInPrivilegeDefinitions() Function Finds out if a catalog name can be used in a privilege definition statement. Syntax public boolean supportsCatalogsInPrivilegeDefinitions() throws SQLException Returns • True if a catalog name can be used in a privilege definition statement. • False if a catalog name cannot be used in a privilege definition statement. supportsCatalogsInProcedureCalls() Function Finds out if a catalog name can be used in a procedure call statement. Syntax public boolean supportsCatalogsInProcedureCalls() throws SQLException Returns • True if a catalog name can be used in a procedure call statement. • False if a catalog name cannot be used in a procedure call statement. supportsCatalogsInTableDefinitions() Function 166 Finds out if a catalog name be used in a table definition statement. Syntax public boolean supportsCatalogsInTableDefinitions() throws SQLException Returns • True if a catalog name be used in a table definition statement. • False if a catalog name cannot be used in a table definition statement. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods DatabaseMetaData Methods supportsColumnAliasing() Function Syntax Finds out if column aliasing is supported. If it is supported, the SQL AS clause can be used to provide names for computed columns or to provide alias names for columns as required. public boolean supportsColumnAliasing() throws SQLException Returns True if column aliasing is supported. Note A JDBC-compliant driver always returns true. supportsConvert() Function Syntax Returns Finds out if the CONVERT function between SQL types is supported. public boolean supportsConvert() throws SQLException • True if the CONVERT function between SQL types is supported. • False if the CONVERT function between SQL types is not supported. supportsConvert(int fromType, int toType) Function Syntax Returns Finds out if the CONVERT function between SQL types is supported. public boolean supportsConvert(int fromType, int toType) throws SQLException Where parameter . . . Is . . . fromType converted from this type. toType converted to this type. • True if the CONVERT function between SQL types is supported. • False if the CONVERT function between SQL types is not supported. supportsCoreSQLGrammar() Function Syntax Returns Finds out if the ODBC Core SQL grammar is supported. public boolean supportsCoreSQLGrammar() throws SQLException • True if the ODBC Core SQL grammar is supported. • False if the ODBC Core SQL grammar is not supported. Teradata Driver for the JDBC Interface User Guide 167 Chapter 3: JDBC Methods DatabaseMetaData Methods supportsCorrelatedSubqueries() Function Syntax Finds out if correlated subqueries are supported. public boolean supportsCorrelatedSubqueries() throws SQLException Returns True if correlated subqueries are supported. Note A JDBC-compliant driver always returns true. supportsDataDefinitionAndDataManipulationTransactions() Function Syntax Returns Finds out if both data definition and data manipulation statements within a transaction are supported. public boolean supportsDataDefinitionAndDataManipulationTransactions() throws SQLException • True if both data definition and data manipulation statements within a transaction are supported. • False if data definition or data manipulation statements within a transaction are not supported. supportsDataManipulationTransactionsOnly() Function Finds out if only data manipulation statements within a transaction are supported. Syntax public boolean supportsDataManipulationTransactionsOnly() throws SQLException Returns • True if only data manipulation statements within a transaction are supported. • False if only data definition statements within a transaction are also supported. supportsDifferentTableCorrelationNames() 168 Function If table correlation names are supported, finds out if they must be different from the names of the tables. Syntax public boolean supportsDifferentTableCorrelationNames() throws SQLException Returns • True if supported table correlation names must be different. • False if supported table correlation names need not be different. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods DatabaseMetaData Methods supportsExpressionsInOrderBy() Function Finds out if expressions in ORDER BY lists are supported. Syntax public boolean supportsExpressionsInOrderBy() throws SQLException Returns • True if expressions in ORDER BY lists are supported. • False if expressions in ORDER BY lists are not supported. supportsExtendedSQLGrammar() Function Syntax Returns Finds out if the ODBC Extended SQL grammar is supported. public boolean supportsExtendedSQLGrammar() throws SQLException • True if the ODBC Extended SQL grammar is supported. • False if the ODBC Extended SQL grammar is not supported. supportsFullOuterJoins() Function Syntax Returns Finds out if full nested outer joins are supported. public boolean supportsFullOuterJoins() throws SQLException • True if full nested outer joins are supported. • False if full nested outer joins are not supported. supportsGetGeneratedKeys() Function Syntax Returns Determines if auto-generated keys can be retrieved after a statement has been executed. public boolean supportsGetGeneratedKeys() throws SQLException • True if auto-generated keys can be retrieved after a statement has been executed. • False if otherwise. supportsGroupBy() Function Syntax Returns Finds out if some form of GROUP BY clause is supported. public boolean supportsGroupBy() throws SQLException • True if some form of GROUP BY clause is supported. • False if some form of GROUP BY clause is not supported. Teradata Driver for the JDBC Interface User Guide 169 Chapter 3: JDBC Methods DatabaseMetaData Methods supportsGroupByBeyondSelect() Function Finds out if a GROUP BY clause can add columns not in the SELECT provided it specifies all the columns in the SELECT. Syntax public boolean supportsGroupByBeyondSelect() throws SQLException Returns • True if a GROUP BY clause can add columns not in the SELECT provided it specifies all the columns in the SELECT. • False if a GROUP BY clause cannot add columns not in the SELECT. supportsGroupByUnrelated() Function Syntax Returns Finds out if a GROUP BY clause can use columns not in the SELECT. public boolean supportsGroupByUnrelated() throws SQLException • True if a GROUP BY clause can use columns not in the SELECT. • False if a GROUP BY clause cannot use columns not in the SELECT. supportsIntegrityEnhancementFacility() Function Finds out if the SQL Integrity Enhancement Facility is supported. Syntax public boolean supportsIntegrityEnhancementFacility() throws SQLException Returns • True if the facility is supported. • False if the facility is not supported. supportsLikeEscapeClause() Function Syntax Finds out if the escape character in LIKE clauses is supported. public boolean supportsLikeEscapeClause() throws SQLException Returns True if the escape character in LIKE clauses is supported. Note A JDBC-compliant driver always returns true. supportsLimitedOuterJoins() Function Syntax 170 Finds out if there is limited support for outer joins. public boolean supportsLimitedOuterJoins() throws SQLException Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods DatabaseMetaData Methods Returns • True if there is limited support for outer joins. • False if there is not limited support for outer joins. Note This will be true if supportFullOuterJoins is true. supportsMinimumSQLGrammar() Function Syntax Finds out if the ODBC Minimum SQL grammar is supported. public boolean supportsMinimumSQLGrammar() throws SQLException Returns • True if the ODBC Minimum SQL grammar is supported. • False if the ODBC Minimum SQL grammar is not supported. Note All JDBC-compliant drivers must return true. supportsMixedCaseIdentifiers() Function Finds out if the database treats mixed case unquoted SQL identifiers as case sensitive and as a result stores them in mixed case. Syntax public boolean supportsMixedCaseIdentifiers() throws SQLException Returns • True if the database treats mixed case unquoted SQL identifiers as case sensitive and as a result stores them in mixed case. • False if the database does not treat mixed case unquoted SQL identifiers as case sensitive. Note A JDBC-compliant driver will always return false. supportsMixedCaseQuotedIdentifiers() Function Finds out if the database treats mixed case quoted SQL identifiers as case sensitive and as a result stores them in mixed case. Syntax public boolean supportsMixedCaseQuotedIdentifiers() throws SQLException Returns • True if the database treats mixed case quoted SQL identifiers as case sensitive and as a result stores them in mixed case. • False if the database does not treat mixed case quoted SQL identifiers as case sensitive. Note A JDBC-compliant driver will always return false. Teradata Driver for the JDBC Interface User Guide 171 Chapter 3: JDBC Methods DatabaseMetaData Methods supportsMultipleOpenResults() Function: Determines if it is possible to have multiple ResultSet objects returned from a CallableStatement object simultaneously. Characteristic Description Syntax public boolean supportsMultipleOpenResults() throws SQLException Return • True, if a CallableStatement object can return multiple ResultSet objects simultaneously • False, if otherwise supportsMultipleResultSets() Function Syntax Returns Finds out if multiple ResultSets from a single execute are supported. public boolean supportsMultipleResultSets() throws SQLException • True if multiple ResultSets from a single execute are supported. • False if multiple ResultSets from a single execute are not supported. supportsMultipleTransactions() Function Finds out if multiple transactions can be open at once (on different connections). Syntax public boolean supportsMultipleTransactions() throws SQLException Returns • True if multiple transactions can be open at once (on different connections). • False if multiple transactions cannot be open at once (on different connections). supportsNonNullableColumns() Function Syntax Finds out if columns can be defined as non-nullable. public boolean supportsNonNullableColumns() throws SQLException Returns True if columns can be defined as non-nullable. Note A JDBC-compliant driver always returns true. supportsOpenCursorsAcrossCommit() Function 172 Finds out if cursors can remain open across commits. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods DatabaseMetaData Methods Syntax public boolean supportsOpenCursorsAcrossCommit() throws SQLException Returns • True if cursors can remain open across commits. • False if cursors cannot remain open across commits. supportsOpenCursorsAcrossRollback() Function Finds out if cursors can remain open across rollbacks. Syntax public boolean supportsOpenCursorsAcrossRollback() throws SQLException Returns • True if cursors can remain open across rollbacks. • False if cursors cannot remain open across rollbacks. supportsOpenStatementsAcrossCommit() Function Finds out if statements remain open across commits. Syntax public boolean supportsOpenStatementsAcrossCommit() throws SQLException Returns • True if statements always remain open across commits. • False if statements might not remain open across commits. supportsOpenStatementsAcrossRollback() Function Finds out if statements can remain open across rollbacks. Syntax public boolean supportsOpenStatementsAcrossRollback() throws SQLException Returns • True if statements always remain open across rollback. • False if statements might not remain open across rollbacks. supportsOrderByUnrelated() Function Syntax Returns Finds out if an ORDER BY clause can use columns not in the SELECT statement. public boolean supportsOrderByUnrelated() throws SQLException • True if an ORDER BY clause can use columns not in the SELECT statement. • False if an ORDER BY clause cannot use columns not in the SELECT statement. Teradata Driver for the JDBC Interface User Guide 173 Chapter 3: JDBC Methods DatabaseMetaData Methods supportsOuterJoins() Function Syntax Returns Finds out if some form of outer join is supported. public boolean supportsOuterJoins() throws SQLException • True if some form of outer join is supported. • False if some form of outer join is not supported. supportsPositionedDelete() Function Syntax Returns Finds out if positioned DELETE is supported. public boolean supportsPositionedDelete() throws SQLException • True if positioned DELETE is supported. • False if positioned DELETE is not supported. supportsPositionedUpdate() Function Syntax Returns Finds out if positioned UPDATE is supported. public boolean supportsPositionedUpdate() throws SQLException • True if positioned UPDATE is supported. • False if positioned UPDATE is not supported. supportsResultSetConcurrency(int type, int concurrency) Function Finds out if the database supports the concurrency type in combination with the given ResultSet type. Syntax public boolean supportsResultSetConcurrency(int type, int concurrency) throws SQLException Returns 174 Where parameter . . . Is . . . type the ResultSet type, such as TYPE_XXX. concurrency the type defined in java.sql.ResultSet. • True if the database supports the concurrency type in combination with the ResultSet type. • False if the database does not supports the concurrency type in combination with the ResultSet type. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods DatabaseMetaData Methods supportsResultSetHoldability(int holdability) Function Syntax Retrieves whether this database supports the given result set holdability. public boolean supportsResultSetHoldability(int holdability) throws SQLException Where parameter . . . Is . . . holdability one of the following constants: ResultSet.HOLD_CURSORS_OVER_COMMIT or ResultSet.CLOSE_CURSORS_AT_COMMIT. Returns • True if this database supports the given result set holdability. • False if this database does not support the given result set holdability. Note Teradata JDBC driver currently does not support ResultSet.CLOSE_CURSORS_AT_COMMIT, and the method returns false for it. supportsResultSetType(int type) Function Syntax Returns Finds out if the database supports the given ResultSet type. public boolean supportsResultSetType(int type) throws SQLException Where parameter . . . Is . . . type the ResultSet type, such as TYPE_XXX. • True if the database supports the ResultSet type. • False if the database does not support the ResultSet type. supportsSchemasInDataManipulation() Function Finds out if a schema name can be used in a data manipulation statement. Syntax public boolean supportsSchemasInDataManipulation() throws SQLException Returns • True if a schema name can be used in a data manipulation statement. • False if a schema name cannot be used in a data manipulation statement. supportsSchemasInIndexDefinitions() Function Syntax Finds out if a schema name can be used in an index definition statement. public boolean supportsSchemasInIndexDefinitions() throws SQLException Teradata Driver for the JDBC Interface User Guide 175 Chapter 3: JDBC Methods DatabaseMetaData Methods Returns • True if a schema name can be used in an in index definition statement. • False if a schema name cannot be used in an in index definition statement. supportsSchemasInPrivilegeDefinitions() Function Finds out if a schema name can be used in a privilege definition statement. Syntax public boolean supportsSchemasInPrivilegeDefinitions() throws SQLException Returns • True if a schema name can be used in a privilege definition statement. • False if a schema name cannot be used in a privilege definition statement. supportsSchemasInProcedureCalls() Function Finds out if a schema name can be used in a procedure call statement. Syntax public boolean supportsSchemasInProcedureCalls() throws SQLException Returns • True if a schema name can be used in a privilege definition statement. • False if a schema name cannot be used in a privilege definition statement. supportsSchemasInTableDefinitions() Function Finds out if a schema name can be used in a table definition statement. Syntax public boolean supportsSchemasInTableDefinitions() throws SQLException Returns • True if a schema name can be used in a table definition statement. • False if a schema name cannot be used in a table definition statement. supportsSelectForUpdate() Function Syntax Returns Finds out if the SELECT for UPDATE function is supported. public boolean supportsSelectForUpdate() throws SQLException • True if the function is supported. • False if the function is not supported. supportsStoredProcedures() Function 176 Finds out if stored procedure calls using the stored procedure escape syntax are supported. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods DatabaseMetaData Methods Syntax Returns public boolean supportsStoredProcedures() throws SQLException • True if stored procedure calls using the stored procedure escape syntax are supported. • False if stored procedure calls using the stored procedure escape syntax are not supported supportsSubqueriesInComparisons() Function Syntax Finds out if subqueries in comparison expressions are supported. public boolean supportsSubqueriesInComparisons() throws SQLException Returns True if subqueries in comparison expressions are supported. Note A JDBC-compliant driver always returns true. supportsSubqueriesInExists() Function Syntax Finds out if subqueries in “exists” expressions are supported. public boolean supportsSubqueriesInExists() throws SQLException Returns True if subqueries in “exists” expressions are supported. Note A JDBC-compliant driver always returns true. supportsSubqueriesInIns() Function Syntax Finds out if subqueries in “in” statements are supported. public boolean supportsSubqueriesInIns() throws SQLException Returns True if subqueries in “in” statements are supported. Note A JDBC-compliant driver always returns true. supportsSubqueriesInQuantifieds() Function Syntax Finds out if subqueries in quantified expressions are supported. public boolean supportsSubqueriesInQuantifieds() throws SQLException Teradata Driver for the JDBC Interface User Guide 177 Chapter 3: JDBC Methods DatabaseMetaData Methods Returns True if subqueries in quantified expressions are supported. Note A JDBC-compliant driver always returns true. supportsTableCorrelationNames() Function Finds out if table correlation names are supported. Syntax public boolean supportsTableCorrelationNames() throws SQLException Returns • True if table correlation names are supported. • False if table correlation names are not supported. Note JDBC-compliant drivers always return a value of true. supportsTransactionIsolationLevel(int level) Function Syntax Returns Finds out if the database supports the given transaction isolation level. public boolean supportsTransactionIsolationLevel(int level) throws SQLException Where parameter . . . Is . . . level the value defined in the java.sql.Connection method. • True if the database supports the transaction level. • False if the database does not support the transaction level. supportsTransactions() Function Syntax Finds out if transactions are supported. public boolean supportsTransactions() throws SQLException Returns • True if transactions are supported. • False if transactions are not supported. Note If transactions are not supported, commit is a no-op and the isolation level is TRANSACTION_NONE. supportsUnion() Function 178 Finds out if SQL UNION is supported. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods DatabaseMetaData Methods Syntax Returns public boolean supportsUnion() throws SQLException • True if SQL UNION is supported. • False if SQL UNION is not supported. supportsUnionAll() Function Syntax Returns Finds out if SQL UNION ALL is supported. public boolean supportsUnionAll() throws SQLException • True if SQL UNION ALL is supported. • False if SQL UNION ALL is not supported. updatesAreDetected(int type) Function Syntax Finds out if a visible row update can be detected by calling the method ResultSet.rowUpdated. public boolean updatesAreDetected(int type) throws SQLException Where parameter . . . Is . . . type the ResultSet type, such as TYPE_XXX. Returns • True if changes are detected by the ResultSet type. • False if changes are not detected by the ResultSet type. Note Returns False, since updateable ResultSets are not supported. usesLocalFilePerTable() Function Syntax Returns Finds out if the database uses a local file for each table. public boolean usesLocalFilePerTable() throws SQLException • True if the database uses a local file for each table. • False if the database does not use a local file for each table. usesLocalFiles() Function Syntax Finds out if the database store tables in a local file. public boolean usesLocalFiles() throws SQLException Teradata Driver for the JDBC Interface User Guide 179 Chapter 3: JDBC Methods DataSource Methods Returns • True if the database store tables in a local file. • True if the database does not store tables in a local file. DataSource Methods Description A DataSource object is a factory for Connection objects. An object that implements the DataSource interface will typically be registered with a JNDI service provider. A JDBC driver that is accessed via the DataSource API does not automatically register itself with the DriverManager. Methods getConnection() Function Syntax Returns Attempts to establish a database connection. The DriverManager attempts to connect to a database. public Connection getConnection() throws SQLException A connection to a database data source. getConnection(String username, String password) Function Attempts to establish a database connection. The DriverManager attempts to select an appropriate driver from the set of registered JDBC drivers. Syntax public Connection getConnection(String username, String password) throws SQLException Returns Where parameter . . . Is . . . username the database user on whose behalf the Connection is being made. password the user’s password. A connection to the database data source. getLoginTimeout() Function 180 Gets the maximum time in seconds that this data source can wait while attempting to connect to a database. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods DataSource Methods Syntax public int getLoginTimeout() throws SQLException Returns DataSource login timeout value. Note A value of zero specifies that the timeout is the default system timeout if there is one; otherwise it specifies that there is no timeout. When a DataSource object is created the login timeout is initially zero. See also, “setLoginTimeout(int seconds).” getLogWriter() Function Syntax Get the log writer for this data source. public PrintWriter getLogWriter() throws SQLException Returns The log writer for this data source, null if logging is disabled. Note The log writer is a character output stream to which all logging and tracing messages for this data source object instance will be printed. This includes messages printed by the methods of this object, messages printed by methods of other objects manufactured by this object, and so on. Messages printed to a data source specific log writer are not printed to the log writer associated with the java.sql.Drivermanager class. When a DataSource object is created the log writer is initially null, in other words, logging is disabled. See also, “setLogWriter(PrintWriter out).” setLoginTimeout(int seconds) Function Syntax Note Sets the maximum time in seconds that this data source will wait while attempting to connect to a database. public void setLoginTimeout(int seconds) throws SQLException Where parameter . . . Is . . . seconds the data source login time limit. A value of zero specifies that the timeout is the default system timeout if there is one; otherwise it specifies that there is no timeout. When a DataSource object is created the login timeout is initially zero. See also, “getLoginTimeout().” setLogWriter(PrintWriter out) Function Set the log writer for this data source. Teradata Driver for the JDBC Interface User Guide 181 Chapter 3: JDBC Methods DriverManager Methods Syntax Note public void setLogWriter(PrintWriter out) throws SQLException Where parameter . . . Is . . . out the new log writer; to disable logging, set to null. The log writer is a character output stream to which all logging and tracing messages for this data source object instance will be printed. This includes messages printed by the methods of this object, messages printed by methods of other objects manufactured by this object, and so on. Messages printed to a data source specific log writer are not printed to the log writer associated with the java.sql.Drivermanager class. When a DataSource object is created the log writer is initially null, in other words, logging is disabled. See also, “getLogWriter().” DriverManager Methods Description The DriverManager provides a basic service for managing a set of JDBC drivers. As part of its initialization, the DriverManager class will attempt to load the driver classes referenced in the "jdbc.drivers" system property. This allows you to customize the JDBC Drivers used by your applications. For example in your ~/.hotjava/properties file you might specify: jdbc.drivers=foo.bah.Driver:wombat.sql.Driver:bad.taste.ourDriver A program can also explicitly load JDBC drivers at any time. For example, the my.sql.Driver is loaded with the following statement: Class.forName("my.sql.Driver").newInstance(); When getConnection is called the DriverManager will attempt to locate a suitable driver from amongst those loaded at initialization and those loaded explicitly using the same classloader as the current applet or application. Methods The following subsections provide a brief description of each supported DriverManager method, presented in alphabetic order. deregisterDriver(Driver driver) Function Drops a driver from the DriverManager list. Applets can only deregister drivers from their own classloader. 182 Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods DriverManager Methods Syntax public static void deregisterDriver(Driver driver) throws SQLException Where parameter . . . Is . . . driver the JDBC driver to drop. getConnection(String url) Function Attempts to establish a connection to the given database URL. The DriverManager attempts to select an appropriate driver from the set of registered JDBC drivers. Syntax public static Connection getConnection(String url) throws SQLException Where parameter . . . Is . . . url a database URL of the form: jdbc:subprotocol:subname Returns A connection to the URL. getConnection(String url, Properties info) Function Attempts to establish a connection to the given database URL. The DriverManager attempts to select an appropriate driver from the set of registered JDBC drivers. Syntax public static Connection getConnection(String url, Properties info) throws SQLException Where parameter . . . Is . . . url a database URL of the form: jdbc:subprotocol:subname info Returns a list connection argument string tag/value pairs. At a minimum, the user and password properties should be included. A connection to the URL. Teradata Driver for the JDBC Interface User Guide 183 Chapter 3: JDBC Methods DriverManager Methods getConnection(String url, String user, String password) Function Attempts to establish a connection to the given database URL. The DriverManager attempts to select an appropriate driver from the set of registered JDBC drivers. Syntax public static Connection getConnection(String url, String user, String password) throws SQLException Where parameter . . . Is . . . url a database URL of the form: jdbc:subprotocol:subname Returns user the database user on whose behalf the connection is being made. password the password for the user. A connection to the URL. getDriver(String url) Function Attempts to locate a driver that understands the given URL. The DriverManager attempts to select an appropriate driver from the set of registered JDBC drivers. Syntax public static Driver getDriver(String url) throws SQLException Where parameter . . . Is . . . url a database URL of the form: jdbc:subprotocol:subname Returns A driver object representing a driver that can connect to the URL. getDrivers() Function Syntax Returns 184 Returns an enumeration with all of the currently loaded JDBC drivers that the current caller has access. public static Enumeration getDrivers() The list of JDBC drivers loaded by the caller's class loader. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods DriverManager Methods Note The classname of a driver can be found using: d.getClass().getName() getLoginTimeout() Function Syntax Returns Finds the maximum time that a driver can wait to login to the database. public static int getLoginTimeout() The driver login time limit in seconds. getLogStream() Function Syntax Returns [DEPREC ATED] Gets the logging/tracing PrintStream that is used by the DriverManager and all drivers. public static PrintStream getLogStream() • The logging/tracing PrintStream. • If disabled, null is returned. println(String message) Function Syntax Prints a message to the current JDBC log stream. public static void println(String message) Where parameter . . . Is . . . message a log or tracing message. registerDriver(Driver driver) Function A newly loaded driver class should call registerDriver to make itself known to the DriverManager. Syntax public static void registerDriver(Driver driver) throws SQLException Where parameter . . . Is . . . driver the new JDBC driver registered with the DriverManager. Teradata Driver for the JDBC Interface User Guide 185 Chapter 3: JDBC Methods ParameterMetaData Methods setLoginTimeout(int seconds) Function Syntax [DEPRECATED] Set the maximum time that a driver will wait to connect to the database. public static void setLoginTimeout(int seconds) Where parameter . . . Is . . . seconds the time allowed to wait in seconds. setLogStream(PrintStream out) Function Sets the logging/tracing PrintStream that is used by the DriverManager and all drivers. Syntax public static void setLogStream(PrintStream out) throws SecurityException Note Where parameter . . . Is . . . out the new logging/tracing PrintStream. To disable, set to null. This method checks for an SQLPermission object before setting the stream. If a SecurityManager exists, and its checkPermission method disallows setting the log writer, a java.lang.SecurityException is thrown. ParameterMetaData Methods Description The ParameterMetadata methods provide a way to get information about the types and properties of the parameters in a PreparedStatement object. Methods getParameterCount() Function Syntax Returns 186 Retrieves the number of parameters in the PreparedStatement object for which this ParameterMetaData object contains information. public int getParameterCount() throws SQLException The number of parameters. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods ParameterMetaData Methods isNullable(int param) Function Syntax Returns Retrieves whether null values are allowed in the designated parameter. public int isNullable(int param) throws SQLException Where parameter . . . Is . . . param is the parameter to check, the first parameter is 1, the second is 2, ... the nullability status of the given parameter; one of ParameterMetaData.parameterNoNulls, ParameterMetaData.parameterNullable, or ParameterMetaData.parameterNullableUnknown. isSigned(int param) Function Syntax Returns Retrieves whether values for the designated parameter can be signed numbers. public boolean isSigned(int param) throws SQLException Where parameter . . . Is . . . param is the parameter to check, the first parameter is 1, the second is 2, ... true if so; false otherwise. getPrecision(int param) Function Syntax Returns Retrieves the designated parameter's number of decimal digits. public int getPrecision(int param) throws SQLException Where parameter . . . Is . . . param is the parameter to check, the first parameter is 1, the second is 2, ... precision. 0 is returned if precision is not applicable to the parameter. Teradata Driver for the JDBC Interface User Guide 187 Chapter 3: JDBC Methods ParameterMetaData Methods getScale(int param) Function Syntax Returns Retrieves the designated parameter's number of digits to right of the decimal point. public int getScale(int param) throws SQLException Where parameter . . . Is . . . param is the parameter to check, the first parameter is 1, the second is 2, ... scale. 0 is returned if scale is not applicable to the parameter. getParameterType(int param) Function Syntax Returns Retrieves the designated parameter's SQL type. public int getParameterType(int param) throws SQLException Where parameter . . . Is . . . param is the parameter to check, the first parameter is 1, the second is 2, ... SQL type from java.sql.Types. java.sql.Types.NULL will be returned if the parameter type cannot be determined. getParameterTypeName(int param) Function Syntax Returns 188 Retrieves the designated parameter's database-specific type name. public String getParameterTypeName(int param) throws SQLException Where parameter . . . Is . . . param is the parameter to check, the first parameter is 1, the second is 2, ... type the name used by the database. If the parameter type is a user-defined type, then a fully-qualified type name is returned. "null" will be returned if the parameter typeName cannot be determined. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods ParameterMetaData Methods getParameterClassName(int param) Function Retrieves the fully-qualified name of the Java class whose instances should be passed to the method PreparedStatement.setObject. Syntax public String getParameterClassName(int param) throws SQLException Returns Where parameter . . . Is . . . param is the parameter to check, the first parameter is 1, the second is 2, ... the fully-qualified name of the class in the Java programming language that would be used by the method PreparedStatement.setObject to set the value in the specified parameter. This is the class name used for custom mapping. "null" will be returned if the Class name cannot be determined. getParameterMode(int param) Function Syntax Returns Retrieves the designated parameter's mode. public int getParameterMode(int param) throws SQLException Where parameter . . . Is . . . param is the parameter to check, the first parameter is 1, the second is 2, ... Returns: mode of the parameter; one of ParameterMetaData.parameterModeIn, ParameterMetaData.parameterModeOut, ParameterMetaData.parameterModeInOut or ParameterMetaData.parameterModeUnknown. Teradata Driver for the JDBC Interface User Guide 189 Chapter 3: JDBC Methods PooledConnection Methods PooledConnection Methods Description A PooledConnection object is a connection object that provides hooks for connection pool management. A PooledConnection object represents a physical connection to a data source. Methods addConnectionEventListener(ConnectionEventListener listener) Function Add an event listener. Registers the event listener so it will be notified whenever an event happens in the pool connection object. Syntax public void addConnectionEventListener(ConnectionEventListener listener) Where parameter . . . Is . . . listener the object added as a “listener” to the event. close() Function Syntax Close the physical connection. public void close() throws SQLException getConnection() Function Syntax Returns Create an object handle for this physical connection. The object returned is a temporary handle used by application code to refer to a physical connection that is being pooled. public Connection getConnection() throws SQLException A Connection object, a handle to this pooled connection object. removeConnectionEventListener(ConnectionEventListener listener) Function Syntax 190 Remove an event listener. public void removeConnectionEventListener(ConnectionEventListener listener) Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods PreparedStatement Methods Where parameter . . . Is . . . listener the object removed from being a “listener” to the event. PreparedStatement Methods Description A PreparedStatement is an object that represents a precompiled SQL statement. A PreparedStatement can efficiently execute the precompiled SQL statement multiple times. Methods The following subsections provide a brief description of each supported PreparedStatement method, presented in alphabetic order. addBatch() Function: This method adds a set of parameters to the PreparedStatement object’s batch of commands. Characteristic Description Syntax public void addBatch() throws SQLException Note: It is recommended to use this method with auto-commit disabled. clearParameters() Function Syntax Note Clears the current parameter values immediately. public void clearParameters() throws SQLException In general, parameter values remain in force for repeated use of a Statement. Setting a parameter value automatically clears its previous value. However, in some cases it is useful to immediately release the resources used by the current parameter values. This can be done by calling clearParameters. execute() Function Syntax Executes any kind of SQL statement. public boolean execute() throws SQLException Teradata Driver for the JDBC Interface User Guide 191 Chapter 3: JDBC Methods PreparedStatement Methods Note Some prepared statements return multiple results. The execute method handles these complex statements as well as the simpler form of statements handled by the executeQuery and executeUpdate methods. executeQuery() Function Syntax Executes the SQL query in this PreparedStatement object. public ResultSet executeQuery() throws SQLException Returns The ResultSet that contains the data produced by the query. If used inappropriately, returns an exception according to the JDBC standard. Note The ResultSet is never null. An exception is returned if used to execute a statement that does not return a result set. The error is 1077 "executeQuery() cannot be used when there is no result set expected; use executeUpdate() or execute()". An exception is returned if the request contains multiple statements. The error is 1079 "% executeQuery() cannot be used when the request contains multiple statements; use execute()". executeUpdate() Function Syntax Executes the SQL INSERT, UPDATE or DELETE statement in this PreparedStatement object. public int executeUpdate() throws SQLException Returns Either the row count for INSERT, UPDATE, or DELETE statements, or 0 for SQL statements that return nothing. If used inappropriately, returns an exception according to the JDBC standard. Note The executeUpdate objects can also execute SQL statements that return nothing, such as DDL statements. An exception is returned if used to execute a statement that returns a result set. The error is 1078 "executeUpdate() cannot be used when a result set is expected; use executeQuery() or execute()". An exception is returned if the request contains multiple statements. The error is 1079 "% executeUpdate() cannot be used when the request contains multiple statements; use execute()". getMetaData() Function Syntax 192 Retrieves the number, types and properties of a ResultSet object’s columns. public ResultSetMetaData getMetaData() throws SQLException Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods PreparedStatement Methods Returns The description of the ResultSet’s columns. getParameterMetaData() Function Retrieves the number, types and properties of this PreparedStatement object's parameters. Syntax public ParameterMetaData getParameterMetaData() throws SQLException Returns A ParameterMetaData object. An exception is thrown if ParameterMetaData is not available. setAsciiStream(int parameterIndex, InputStream x, int length) Function Sets the designated parameter to the given input stream, which will have the specified number of bytes. Syntax public void setAsciiStream(int parameterIndex, InputStream x, int length) throws SQLException Note Where parameter . . . Is . . . parameterIndex the parameter specification. The first parameter is 1, the second is 2, . . . x the Java input stream that contains the ASCII parameter value. length the number of bytes in the stream. When a very large ASCII value is input to a LONGVARCHAR parameter, it may be more practical to send it via a java.io.InputStream. JDBC will read the data from the stream as needed, until it reaches end-of-file. The JDBC driver will do any necessary conversion from ASCII to the database char format. This stream object can either be a standard Java stream object or your own subclass that implements the standard interface. setBigDecimal(int parameterIndex, BigDecimal x) Function Sets the designated parameter to a java.math.BigDecimal value. The driver converts this to an SQL NUMERIC value when it sends it to the database. Syntax public void setBigDecimal(int parameterIndex, BigDecimal x) throws SQLException Where parameter . . . Teradata Driver for the JDBC Interface User Guide Is . . . 193 Chapter 3: JDBC Methods PreparedStatement Methods parameterIndex the parameter specification. The first parameter is 1, the second is 2, . . . x the parameter value. setBinaryStream(int parameterIndex, InputStream x, int length) Function Sets the designated parameter to the given input stream, which will have the specified number of bytes. Syntax public void setBinaryStream(int parameterIndex, InputStream x, int length) throws SQLException Note Where parameter . . . Is . . . parameterIndex the parameter specification. The first parameter is 1, the second is 2, . . . x the Java input stream that contains the binary parameter value. length the number of bytes in the stream. When a very large binary value is input to a LONGVARBINARY parameter, it may be more practical to send it via a java.io.InputStream. JDBC will read the data from the stream as needed, until it reaches end-of-file. This stream object can either be a standard Java stream object or your own subclass that implements the standard interface. setBlob(int i, Blob x) Function Syntax Sets the parameter number to a Blob object. public void setBlob(int i, Blob x) throws SQLException Where parameter . . . Is . . . i the parameter specification. The first parameter is 1, the second is 2, . . . x a BLOB object that maps an SQL BLOB value setBoolean(int parameterIndex, boolean x) Function 194 Sets the designated parameter to a Java boolean value. The driver converts this to an SQL BIT value and sends it to the database. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods PreparedStatement Methods Syntax public void setBoolean(int parameterIndex, boolean x) throws SQLException Where parameter . . . Is . . . parameterIndex the parameter specification. The first parameter is 1, the second is 2, . . . x the parameter value. setByte(int parameterIndex, byte x) Function Sets the designated parameter to a Java byte value. The driver converts this to an SQL TINYINT value and sends it to the database. Syntax public void setByte(int parameterIndex, byte x) throws SQLException Where parameter . . . Is . . . parameterIndex the parameter specification. The first parameter is 1, the second is 2, . . . x the parameter value. setBytes(int parameterIndex, byte[ ] x) Function Syntax Sets the designated parameter to a Java array of bytes. The driver converts this to an SQL VARBINARY or LONGVARBINARY (depending on the size of the argument size relative to the VARBINARY limits of the driver), and sends it to the database. public void setBytes(int parameterIndex, byte[] x) throws SQLException Where parameter . . . Is . . . parameterIndex the parameter specification. The first parameter is 1, the second is 2, . . . x the parameter value. setCharacterStream(int parameterIndex, Reader reader, int length) Function Sets the designated parameter to the given Reader object, which is the given number of characters long. Syntax public void setCharacterStream(int parameterIndex, Reader reader, int length) throws SQLException Teradata Driver for the JDBC Interface User Guide 195 Chapter 3: JDBC Methods PreparedStatement Methods Note Where parameter . . . Is . . . parameterIndex the parameter specification. The first parameter is 1, the second is 2, . . . reader the java reader that contains the UNICODE data. length the number of characters in the stream. When a very large UNICODE value is input to a LONGVARCHAR parameter, it may be more practical to send it via a java.io.Reader. JDBC will read the data from the stream as needed, until it reaches end-of-file. The JDBC driver will do any necessary conversion from UNICODE to the database char format. This stream object can either be a standard Java stream object or your own subclass that implements the standard interface. setClob( int i, Clob x) Function Syntax Sets the parameter number to a CLOB object. public void setClob(int i, Clob x) throws SQL exception Where parameter . . . Is . . . i the parameter specification. The first parameter is 1, the second is 2, . . . x A CLOB object that maps an SQL CLOB value setDate(int parameterIndex, Date x) 196 Function Sets the designated parameter to a java.sql.Date value. The driver converts this to an SQL DATE value and sends it to the database. Syntax public void setDate(int parameterIndex, Date x) throws SQLException Where parameter . . . Is . . . parameterIndex the parameter specification. The first parameter is 1, the second is 2, . . . x the parameter value. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods PreparedStatement Methods setDate(int parameterIndex, Date x, Calendar cal) Function Sets the designated parameter to a java.sql.Date value, using the given Calendar object. Syntax public void setDate(int parameterIndex, Date x, Calendar cal) throws SQLException Note Where parameter . . . Is . . . parameterIndex the parameter specification. The first parameter is 1, the second is 2, . . . x the parameter value. cal the Calendar object the driver will use to construct the date. With a Calendar object, the driver can calculate the date taking into account a custom timezone and locale. If no Calendar object is specified, the driver uses the default timezone and locale. The driver ignores the Calendar object since the Teradata Database does not support time zones for dates. setDouble(int parameterIndex, double x) Function Sets the designated parameter to a Java double value. The driver converts this to an SQL DOUBLE value and sends it to the database. Syntax public void setDouble(int parameterIndex, double x) throws SQLException Where parameter . . . Is . . . parameterIndex the parameter specification. The first parameter is 1, the second is 2, . . . x the parameter value. setFloat(int parameterIndex, float x) Function Sets the designated parameter to a Java float value. The driver converts this to an SQL FLOAT value and sends it to the database. Syntax public void setFloat(int parameterIndex, float x) throws SQLException Where parameter . . . Is . . . parameterIndex the parameter specification. The first parameter is 1, the second is 2, . . . Teradata Driver for the JDBC Interface User Guide 197 Chapter 3: JDBC Methods PreparedStatement Methods x the parameter value. setInt(int parameterIndex, int x) Function Sets the designated parameter to a Java int value. The driver converts this to an SQL INTEGER value and sends it to the database. Syntax public void setInt(int parameterIndex, int x) throws SQLException Where parameter . . . Is . . . parameterIndex the parameter specification. The first parameter is 1, the second is 2, . . . x the parameter value. setLong(int parameterIndex, long x) Function Sets the designated parameter to a Java long value. The driver converts this to an SQL BIGINT value and sends it to the database. Syntax public void setLong(int parameterIndex, long x) throws SQLException Where parameter . . . Is . . . parameterIndex the parameter specification. The first parameter is 1, the second is 2, . . . x the parameter value. setNull(int parameterIndex, int sqlType) Function Syntax 198 Sets the designated parameter to SQL NULL. public void setNull(int parameterIndex, int sqlType) throws SQLException Where parameter . . . Is . . . parameterIndex the parameter specification. The first parameter is 1, the second is 2, . . . sqlType the SQL type code defined in java.sql.Types. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods PreparedStatement Methods Note You must specify the sqlType parameter. Null Expressions: If any expression in a comparison is null, the result of the comparison is unknown. For a comparison to provide a TRUE result when comparing fields that might result in nulls, the statement must include the IS [NOT] NULL operator. setNull(int paramIndex, int sqlType, String typeName) Function Sets the designated parameter to SQL NULL. Use this version of setNull for user-named types and REF type parameters. Examples of user-named types include: • • • • Syntax Note STRUCT DISTINCT JAVA_OBJECT named array types public void setNull(int paramIndex, int sqlType, String typeName) throws SQLException Where parameter . . . Is . . . parameterIndex the parameter specification. The first parameter is 1, the second is 2, . . . sqlType the SQL type code defined in java.sql.Types. typeName the fully qualified name of an SQL user-named type, ignored if the parameter is not a user-named type or REF. To be portable, applications must give the SQL type code and the fully-qualified SQL type name when specifying a NULL user-defined or REF parameter. Null Expressions: If any expression in a comparison is null, the result of the comparison is unknown. For a comparison to provide a TRUE result when comparing fields that might result in nulls, the statement must include the IS [NOT] NULL operator. In the case of a user-named type the name is the type name of the parameter itself. For a REF parameter the name is the type name of the referenced type. If a JDBC driver does not need the type code or type name information, it may ignore it. Although it is intended for user-named and Ref parameters, this method may be used to set a null parameter of any JDBC type. If the parameter does not have a user-named or REF type, the given typeName is ignored. Teradata Driver for the JDBC Interface User Guide 199 Chapter 3: JDBC Methods PreparedStatement Methods setObject(int parameterIndex, Object x) Function Sets the value of a parameter using an object. Use the java.lang equivalent objects for integral values. Syntax public void setObject(int parameterIndex, Object x) throws SQLException Note Where parameter . . . Is . . . parameterIndex the parameter specification. The first parameter is 1, the second is 2, . . . x the object containing the input parameter value. The JDBC specification specifies a standard mapping from Java Object types to SQL types. The given argument java object will be converted to the corresponding SQL type before being sent to the database. Note that this method may be used to pass database-specific abstract data types, by using a Driver-specific Java type. If the object is of a class implementing SQLData, the JDBC driver should call its method writeSQL to write it to the SQL data stream. If, on the other hand, the object is of a class implementing Ref, Blob, Clob, Struct, or Array, then the driver should pass it to the database as a value of the corresponding SQL type. This method throws an exception if there is an ambiguity, for example, if the object is of a class implementing more than one of those interfaces. setObject(int parameterIndex, Object x, int targetSqlType) Function Sets the value of the designated parameter with the given object. This method is like the preceding setObject method, except that it assumes a scale of zero. Syntax public void setObject(int parameterIndex, Object x, int targetSqlType) throws SQLException Where parameter . . . Is . . . parameterIndex the parameter specification. The first parameter is 1, the second is 2, . . . x the object containing the input parameter value. targetSqlType the SQL type (as defined in java.sql.Types) to be sent to the database setObject(int parameterIndex, Object x, int targetSqlType, int 200 Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods PreparedStatement Methods scale) Function Sets the value of a parameter using an object. The second argument must be an object type. For integral values, the java.lang equivalent objects should be used. Syntax public void setObject(int parameterIndex, Object x, int targetSqlType, int scale) throws SQLException Where parameter . . . Is . . . parameterIndex the parameter specification. The first parameter is 1, the second is 2, . . . x the object containing the input parameter value. targetSqlType the SQL type (as defined in java.sql.Types) to be sent to the database. The scale argument may further qualify this type. scale for java.sql.Types.DECIMAL or java.sql.Types.NUMERIC types, this is the number of digits after the decimal point. For all other types, this value will be ignored. Note The given Java object will be converted to the targetSqlType before being sent to the database. If the object has a custom mapping (is of a class implementing SQLData), the JDBC driver should call its method writeSQL to write it to the SQL data stream. If, on the other hand, the object is of a class implementing Ref, Blob, Clob, Struct, or Array, the driver should pass it to the database as a value of the corresponding SQL type. This method may be used to pass database-specific abstract data types. setShort(int parameterIndex, short x) Function Sets the designated parameter to a Java short value. The driver converts this to an SQL SMALLINT value and sends it to the database. Syntax public void setShort(int parameterIndex, short x) throws SQLException Where parameter . . . Is . . . parameterIndex the parameter specification. The first parameter is 1, the second is 2, . . . Teradata Driver for the JDBC Interface User Guide 201 Chapter 3: JDBC Methods PreparedStatement Methods x the parameter value. setString(int parameterIndex, String x) Function Sets the designated parameter to a Java String value. The driver converts this to an SQL VARCHAR or LONGVARCHAR value (depending on the size of the argument size relative to VARCHAR limits of the driver), and sends it to the database. Syntax public void setString(int parameterIndex, String x) throws SQLException Where parameter . . . Is . . . parameterIndex the parameter specification. The first parameter is 1, the second is 2, . . . x the parameter value. setTime(int parameterIndex, Time x) Function Sets the designated parameter to a java.sql.Time value. The driver converts this to an SQL TIME value when it sends it to the database. Syntax public void setTime(int parameterIndex, Time x) throws SQLException Where parameter . . . Is . . . parameterIndex the parameter specification. The first parameter is 1, the second is 2, . . . x the parameter value. setTime(int parameterIndex, Time x, Calendar cal) 202 Function Sets the designated parameter to a java.sql.Time value, using the given Calendar object. Syntax public void setTime(int parameterIndex, Time x, Calendar cal) throws SQLException Where parameter . . . Is . . . parameterIndex the parameter specification. The first parameter is 1, the second is 2, . . . Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods PreparedStatement Methods Note x the parameter value. cal the Calendar object the driver will use to construct the time. The driver uses the Calendar object to construct an SQL TIME, which the driver then sends to the database. With a Calendar object, the driver can calculate the time taking into account a custom timezone and locale. If no Calendar object is specified, the driver uses the default timezone and locale. setTimestamp(int parameterIndex, Timestamp x) Function Sets the designated parameter to a java.sql.Timestamp value. The driver converts this to an SQL TIMESTAMP value when it sends it to the database. Syntax public void setTimestamp(int parameterIndex, Timestamp x) throws SQLException Where parameter . . . Is . . . parameterIndex the parameter specification. The first parameter is 1, the second is 2, . . . x the parameter value. setTimestamp(int parameterIndex, Timestamp x, Calendar cal) Function Sets the designated parameter to a java.sql.Timestamp value, using the given Calendar object. Syntax public void setTimestamp(int parameterIndex, Timestamp x, Calendar cal) throws SQLException Where parameter . . . Is . . . parameterIndex the parameter specification. The first parameter is 1, the second is 2, . . . x the parameter value. cal the Calendar object the driver will use to construct the time. The driver uses the Calendar object to construct an SQL TIMESTAMP, which the driver then sends to the database. Teradata Driver for the JDBC Interface User Guide 203 Chapter 3: JDBC Methods ResultSet Methods Note With a a Calendar object, the driver can calculate the timestamp taking into account a custom timezone and locale. If no Calendar object is specified, the driver uses the default timezone and locale. setUnicodeStream(int parameterIndex, InputStream x, int length) Function [DEPRECATED] Sets the designated parameter to the input stream specified by x. Data is read from the stream until EOF. The format of the input stream must be UTF-8. Syntax public void setUnicodeStream(int parameterIndex, InputStream x, int length) throws SQLException Where parameter . . . Is . . . parameterIndex the parameter specification. The first parameter is 1, the second is 2, . . . x the java input stream containing the UNICODE parameter value. length the bytes in the input stream. ResultSet Methods Description A ResultSet provides access to a table of data generated by executing a Statement. The table rows are retrieved in sequence. Within a row its column values can be accessed in any order. A ResultSet maintains a cursor pointing to its current row of data. Initially the cursor is positioned before the first row. The 'next' method moves the cursor to the next row. A default ResultSet object is not updatable and has a cursor that moves forward only. As a result, you can iterate through it only once and only from the first row to the last row. It is possible to produce ResultSet objects that are scrollable and/or updatable. The getXXX methods retrieve column values for the current row. Retrieve values either using the index number of the column, or by using the name of the column. In general, using the column index is more efficient. Columns numbering begins at 1. For maximum portability, read ResultSet columns within each row in left-to-right order and read each column only once. For the getXXX methods, the Teradata Driver for the JDBC Interface attempts to convert the underlying data to the specified Java type and returns a suitable Java value. See the JDBC specification for allowable mappings from SQL types to Java types with the ResultSet.getXXX methods. 204 Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods ResultSet Methods Column names used as input to getXXX methods are case-insensitive. When performing a getXXX using a column name, if several columns have the same name, then the value of the first matching column is returned. A set of updater methods was added to this interface in the JDBC 2.0 API (JDK 1.2). The comments regarding parameters to the getter methods also apply to parameters to the updater methods. A ResultSet is automatically closed by the Statement that generated it when that Statement is closed, re-executed, or is used to retrieve the next result from a sequence of multiple results. The ResultSetMetaData object returned by the getMetaData method provides the number, types, and properties of a ResultSet’s columns. Methods The following subsections provide a brief description of each supported ResultSet method, presented in alphabetic order. absolute(int row) Function Syntax Returns The cursor is moved to the row number in the ResultSet object. public int absolute(int row) throws SQLException Where parameter . . . Is . . . row contains the number of the row where the cursor should move. If the row number is positive, the cursor moves in relation to the first row. If the row number is negative, the cursor position moves in relation to the last row. True if the cursor is located on the ResultSet. False, if it is not. Notes • Throws the SQLException if a database access error occurs, or if the ResultSetType is TYPE_FORWARD_ONLY. • If you call absolute(1), it is the same as calling first(). • If you call absolute(-1), it is the same as calling last(). afterLast() Function Syntax The cursor is moved to just after the last row of the ResultSet object. public void afterLast() throws SQLException Teradata Driver for the JDBC Interface User Guide 205 Chapter 3: JDBC Methods ResultSet Methods Notes • If the ResultSet contains no rows, this method will have no effect. • Throws the SQLException if a database access error occurs, or if the ResultSetType is TYPE_FORWARD_ONLY. beforeFirst() Function Syntax Notes The cursor is moved to just before the first row of the ResultSet object. public void beforeFirst() throws SQLException • If the ResultSet contains no rows, this method will have no effect. • Throws the SQLException if a database access error occurs, or if the ResultSetType is TYPE_FORWARD_ONLY. cancelRowUpdates() Function: Cancels the updates made to the current row in this ResultSet object. This method may be called after calling an updater method(s) and before calling the method updateRow to roll back the updates made to a row. If no updates have been made or updateRow has already been called, this method has no effect. Character Description Syntax public void cancelRowUpdate() throws SQLException Note: Throws the SQLException if a database access error occurs or if this method is called when the cursor is on the insert row. clearWarnings() Function Syntax Clears all warnings reported on this ResultSet object. After this call, getWarnings returns null until a new warning is reported for this ResultSet. public void clearWarnings() throws SQLException close() Function Syntax Note 206 In some cases, it is desirable to immediately release a ResultSet's database and JDBC resources instead of waiting for this to happen when it is automatically closed. The close method provides this immediate release. public void close() throws SQLException A ResultSet is automatically closed by the statement that generated it when that statement is closed, re-executed, or is used to retrieve the next result from a sequence of multiple results. A ResultSet is also automatically closed when it is garbage collected. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods ResultSet Methods deleteRow() Function: Deletes the current row from this ResultSet object and from the underlying database. This method cannot be called when the cursor is on the insert row. Characteristic Description Syntax public void deleteRow() throws SQLException Note: Throws the SQLException if a database access error occurs or if this method is called when the cursor is on the insert row findColumn(String columnName) Function Syntax Returns Maps a Resultset column name to a ResultSet column index. public int findColumn(String columnName) throws SQLException Where parameter . . . Is . . . columnName the name of the column. The column index of columnName. first() Function Syntax Moves the cursor to the ResultSet object first row. public boolean first() throws SQLException Returns • True, if the location of the cursor is a valid row. • False, if there are no rows in the ResultSet. Notes Throws the SQLException if a database access error occurs, or if the ResultSetType is TYPE_FORWARD_ONLY. getAsciiStream(int columnIndex) Function Syntax Gets the value of a column designated by columnIndex in the current row of this ResultSet object as a stream of ASCII characters. The value can then be read in chunks from the stream. public InputStream getAsciiStream(int columnIndex) throws SQLException Where parameter . . . Teradata Driver for the JDBC Interface User Guide Is . . . 207 Chapter 3: JDBC Methods ResultSet Methods columnIndex the column specification. The first column is 1, the second is 2, . . . Returns A Java input stream that delivers the database column value as a stream of one-byte ASCII characters. If the value is SQL NULL then the result is null. Note This method is particularly suitable for retrieving large LONGVARCHAR values. The JDBC driver will do any necessary conversion from the database format into ASCII. All the data in the returned stream must be read prior to getting the value of any other column. The next call to a get method implicitly closes the stream. Also, a stream may return 0 when the method available is called whether there is data available or not. getAsciiStream(String columnName) Function Gets the value of a column in the current row of this ResultSet object as a stream of ASCII characters. The value can then be read in chunks from the stream. Syntax public InputStream getAsciiStream(String columnName) throws SQLException Where parameter . . . Is . . . columnName the SQL name of the column. Returns A Java input stream that delivers the database column value as a stream of one-byte ASCII characters. Note This method is particularly suitable for retrieving large LONGVARCHAR values. The JDBC driver will do any necessary conversion from the database format into ASCII. If the value is SQL NULL then the result is null. All the data in the returned stream must be read prior to getting the value of any other column. The next call to a get method implicitly closes the stream. Also, a stream may return 0 when the method available is called whether there is data available or not. getBigDecimal(int columnIndex) 208 Function Gets the value of the column designated by columnIndex in the current row of this ResultSet object as a java.math.BigDecimal with full precision. Syntax public BigDecimal getBigDecimal(int columnIndex) throws SQLException Where parameter . . . Is . . . columnIndex the column specification. The first column is 1, the second is 2, . . . Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods ResultSet Methods Returns The column value. Note If the value is SQL NULL, the result is NULL. getBigDecimal(int columnIndex, int scale) Function Gets the value of the column designated by columnIndex in the current row of this ResultSet object as a java.sql.BigDecimal with full precision. Syntax public BigDecimal getBigDecimal(int columnIndex, int scale) throws SQLException Where parameter . . . Is . . . columnIndex the column specification. The first column is 1, the second is 2, . . . scale the number of digits to the right of the decimal point. Returns The column value. Note If the value is SQL NULL, the result is NULL. getBigDecimal(String columnName) Function Gets the value of a column designated by columnName in the current row of this ResultSet object as a java.math.BigDecimal with full precision. Syntax public BigDecimal getBigDecimal(String columnName) throws SQLException Where parameter . . . Is . . . columnName the SQL name of the column. Returns The column value. Note If the value is SQL NULL, the result is NULL. getBigDecimal(String columnName, int scale) Function Gets the value of a column designated by columnName in the current row of this ResultSet object as a java.math.BigDecimal. Syntax public BigDecimal getBigDecimal(String columnName, int scale) throws SQLException Teradata Driver for the JDBC Interface User Guide 209 Chapter 3: JDBC Methods ResultSet Methods Where parameter . . . Is . . . columnName the SQL name of the column. scale the number of digits to the right of the decimal point. Returns The column value. Note If the value is SQL NULL, the result is NULL. getBinaryStream(int columnIndex) Function Syntax Gets the column value designated by columnIndex as a stream of uninterpreted bytes and read in chunks from the stream. This method is particularly suitable for retrieving large LONGVARBINARY values. public InputStream getBinaryStream(int columnIndex) throws SQLException Where parameter . . . Is . . . columnIndex the column specification. The first column is 1, the second is 2, . . . Returns A Java input stream that delivers the database column value as a stream of uninterpreted bytes. Note If the value is SQL NULL, then the result is null. All the data in the returned stream must be read before getting the value of any other column. The next call to a get method implicitly closes the stream. Also, a stream may return zero for available( ) whether data is available or not. getBinaryStream(String columnName) Function Gets the column value designated by columnName as a stream of uninterpreted bytes and read in chunks from the stream. Syntax public InputStream getBinaryStream(String columnName) throws SQLException Returns 210 Where parameter . . . Is . . . columnName SQL name of the column. A Java input stream that delivers the database column value as a stream of uninterpreted bytes. If the value is SQL NULL, then the result is null. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods ResultSet Methods Note This method is particularly suitable for retrieving large LONGVARBINARY values. All the data in the returned stream must be read before getting the value of any other column. The next call to a get method implicitly closes the stream. Also, a stream may return zero for available( ) whether data is available or not. getBlob(int i) Function Syntax Returns Returns the value of the designated column in the current row of this ResultSet object as a Blob object in the Java programming language. public Blob getBlob(int i) throws SQLException Where parameter . . . Is . . . i the column specification. The first column is 1, the second is 2, . . . Returns a Blob object representing the SQL BLOB value in the specified column. getBlob(String colName) Function Syntax Returns Returns the value of the designated column in the current row of this ResultSet object as a Blob object in the Java programming language. public Blob getBlob(String colName) throws SQLException Where parameter . . . Is . . . colName the name of the column from which to retrieve the value. Returns a Blob object representing the SQL BLOB value in the specified column. getBoolean(int columnIndex) Function Syntax Returns Gets the value of a column designated by columnIndex in the current row of the ResultSet as a Java boolean. public boolean getBoolean(int columnIndex) throws SQLException Where parameter . . . Is . . . columnIndex the column specification. The first column is 1, the second is 2, . . . The value of the designated column. Teradata Driver for the JDBC Interface User Guide 211 Chapter 3: JDBC Methods ResultSet Methods Note If the value is SQL NULL, the result is false. getBoolean(String columnName) Function Gets the value of a column designated by columnName in the current row of the ResultSet as a Java boolean. Syntax public boolean getBoolean(String columnName) throws SQLException Where parameter . . . Is . . . columnName the SQL name of the column. Returns The value of the designated column. Note If the value is SQL NULL, the result is false. getByte(int columnIndex) Function Syntax Gets the value of a column designated by columnIndex in the current row as a Java byte. public byte getByte(int columnIndex) throws SQLException Where parameter . . . Is . . . columnIndex the column specification. The first column is 1, the second is 2, . . . Returns The value of the designated column. Note If the value is SQL NULL, the result is 0. getByte(String columnName) Function Syntax Returns 212 Gets the value of a column designated by columnName in the current row as a Java byte. public byte getByte(String columnName) throws SQLException Where parameter . . . Is . . . columnName the SQL name of the column. The value of the designated column. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods ResultSet Methods Note If the value is SQL NULL, the result is 0. getBytes(int columnIndex) Function Syntax Gets the value of a column designated by columnIndex in the current row as a Java byte array. public byte[] getBytes(int columnIndex) throws SQLException Where parameter . . . Is . . . columnIndex the column specification. The first column is 1, the second is 2, . . . Returns The value of the designated column. Note If the value is SQL NULL, the result is null. getBytes(String columnName) Function Gets the value of a column designated by columnName in the current row as a Java byte array. The bytes represent the raw values returned by the driver. Syntax public byte[] getBytes(String columnName) throws SQLException Where parameter . . . Is . . . columnName the SQL name of the column. Returns The value of the designated column. Note If the value is SQL NULL, the result is null. getCharacterStream(int columnIndex) Function Gets the value of a column designated by columnIndex in the current row as a java.io.Reader. Syntax public Reader getCharacterStream(int columnIndex) throws SQLException Where parameter . . . Is . . . columnIndex the column specification. The first column is 1, the second is 2, . . . Teradata Driver for the JDBC Interface User Guide 213 Chapter 3: JDBC Methods ResultSet Methods Returns The value in the specified column as a java.io.Reader. Note If the column value returned is SQL NULL, the result is null. getCharacterStream(String columnName) Function Gets the value of a column designated by columnName in the current row as a java.io.Reader. Syntax public Reader getCharacterStream(String columnName) throws SQLException Where parameter . . . Is . . . columnName the SQL name of the column. Returns The value in the specified column as a java.io.Reader. Note If the column value returned is SQL NULL, the result is null. getClob(int i) Function Syntax Returns Returns the value of the designated column in the current row of this ResultSet object as a Clob object in the Java programming language. public Clob getClob(int i) throws SQLException Where parameter . . . Is . . . in i the column specification. The first column is 1, the second is 2, . . . Returns a Clob object representing the SQL CLOB value in the specified column. getClob(String colName) Function Syntax 214 Returns the value of the designated column in the current row of this ResultSet object as a Clob object in the Java programming language. public Blob getClob(String colName) throws SQLException Where parameter . . . Is . . . colName the name of the column from which to retrieve the value. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods ResultSet Methods Returns Returns a Clob object representing the SQL CLOB value in the specified column. getConcurrency() Function: Retrieves the concurrency mode of this ResultSet object. The concurrency used is determined by the Statement object that created the result set. Characteristic Description Syntax public int getConcurrency() throws SQLException Return The concurrency type is returned, either ResultSet.CONCUR_READ_ONLY or ResultSet.CONCUR_UPDATABLE Note: Throws the SQLException if a database access error occurs getDate(String columnIndex) Function Syntax Gets the value of the column designated by columnIndex in the current row of the ResultSet object as a java.sql.Date object. public Date getDate(String columnIndex) throws SQLException Where parameter . . . Is . . . columnIndex the column specification. The first column is 1, the second is 2, . . . Returns The value of the designated column. Note If the column value returned is SQL NULL, the result is null. getDate(String columnName) Function Syntax Gets the value of the column designated by columnName in the current row of the ResultSet object as a java.sql.Date object. public Date getDate(String columnName) throws SQLException Where parameter . . . Is . . . columnName the SQL name of the column. Returns The value of the designated column. Note If the column value returned is SQL NULL, the result is null. Teradata Driver for the JDBC Interface User Guide 215 Chapter 3: JDBC Methods ResultSet Methods getDate(String columnIndex, Calendar cal) Function Gets the value of the column designated by columnIndex in the current row of the ResultSet object as a java.sql.Date object. Syntax public Date getDate(String columnIndex, Calendar cal) throws SQLException Where parameter . . . Is . . . columnIndex the column specification. The first column is 1, the second is 2, . . . cal the calendar to use in constructing the date. Returns The value of the designated column. Note If the column value returned is SQL NULL, the result is null. This method uses the given calendar to construct an appropriate millisecond value for the Date, if the underlying database does not store timezone information. The time zone is ignored since the Teradata Database does not support time zones with dates. getDate(String columnName, Calendar cal) Function Gets the value of the column designated by columnName in the current row of the ResultSet object as a java.sql.Date object. Syntax public Date getDate(String columnName, Calendar cal) throws SQLException Where parameter . . . Is . . . columnName the SQL name of the column from which to retrieve the value. cal the calendar to use in constructing the date. Returns The column value as a java.sql.Date.object. Note If the column value returned is SQL NULL, the result is null. This method uses the given calendar to construct an appropriate millisecond value for the Date, if the underlying database does not store timezone information. The time zone is ignored since the Teradata Database does not support time zones with dates. 216 Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods ResultSet Methods getDouble(int columnIndex) Function Syntax Gets the value of a column designated by columnIndex in the current row as a Java double. public double getDouble(int columnIndex) throws SQLException Where parameter . . . Is . . . ColumnIndex the column specification. The first column is 1, the second is 2, . . . Returns The value of the designated column. Note If the column value returned is SQL NULL, the value returned is 0. getDouble(String columnName) Function Syntax Gets the value of the column designated by columnName in the current row of this ResultSet as a Java double. public double getDouble(String columnName) throws SQLException Where parameter . . . Is . . . columnName the SQL name of the column. Returns The value of the designated column. Note If the column value returned is SQL NULL, the value returned is 0. getFloat(int columnIndex) Function Syntax Gets the value of a column designated by columnIndex in the current row of this ResultSet object as a Java float. public float getFloat(int columnIndex) throws SQLException Where parameter . . . Is . . . columnIndex the column specification. The first column is 1, the second is 2, . . . Returns The value of the designated column. Note If the column value returned is SQL NULL, the result is 0. Teradata Driver for the JDBC Interface User Guide 217 Chapter 3: JDBC Methods ResultSet Methods getFetchDirection() Function Syntax Returns Gets the fetch direction of the current ResultSet. public float getFetchDirection() throws SQLException The current fetch direction for the ResultSet. getFetchSize() Function Syntax Returns Gets the fetch size of the current ResultSet. public int getFetchSize() throws SQLException The current fetch size for the ResultSet. getFloat(String columnName) Function Syntax Gets the value of a column designated by columnName in the current row of this ResultSet as a Java float. public float getFloat(String columnName) throws SQLException Where parameter . . . Is . . . columnName the SQL name of the column. Returns The value of the designated column. Note If the column value returned is SQL NULL, the result is 0. getInt(int columnIndex) Function Syntax Returns 218 Gets the value of the column designated by columnIndex in the current row of this ResultSet as a Java int. public int getInt(int columnIndex) throws SQLException Where parameter . . . Is . . . columnIndex the column specification. The first column is 1, the second is 2, . . . The value of the designated column. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods ResultSet Methods Note If the column value returned is SQL NULL, the result is 0. getInt(String columnName) Function Syntax Gets the value of a column designated by columnName in the current row of this ResultSet as a Java int. public int getInt(String columnName) throws SQLException Where parameter . . . Is . . . columnName the SQL name of the column. Returns The value of the designated column. Note If the column value returned is SQL NULL, the result is 0. getLong(int columnIndex) Function Syntax Gets the value of a column designated by columnIndex in the current row of this ResultSet as a Java long. public long getLong(int columnIndex) throws SQLException Where parameter . . . Is . . . columnIndex the column specification. The first column is 1, the second is 2, . . . Returns The value of the designated column. Note If the column value returned is SQL NULL, the result is 0. getLong(String columnName) Function Syntax Returns Gets the value of a column designated by coulmnName in the current row of this ResultSet as a Java long. public long getLong(String columnName) throws SQLException Where parameter . . . Is . . . columnName the SQL name of the column. The value of the designated column. Teradata Driver for the JDBC Interface User Guide 219 Chapter 3: JDBC Methods ResultSet Methods Note If the column value returned is SQL NULL, the result is 0. getMetaData() Function Syntax Returns Provides the number, types, and properties of columns in a ResultSet. public ResultSetMetaData getMetaData() throws SQLException The description of ResultSet object’s columns. getObject(int columnIndex) Function Syntax Gets the value of the column designated by columnindex in the current row of this ResultSet as a Java object. public Object getObject(String columnIndex) throws SQLException Where parameter . . . Is . . . columnIndex the column specification. The first column is 1, the second is 2, . . . Returns A java.lang.Object holding the column value. Note This method returns the value of the given column as a Java object. The type of the Java object will be the default Java object type corresponding to the column's SQL type, following the mapping for built-in types specified in the JDBC specification. You can also use this method to read database-specific abstract data types. When the a column contains a structured or distinct value, the behavior of this method is as if it were a call to: getObject(columnIndex, this.getStatement() .getConnection().getTypeMap()) getObject(String columnName) Function Syntax Returns 220 Gets the value of the column designated by columnName in the current row of this ResultSet as a Java object. public Object getObject(String columnName) throws SQLException Where parameter . . . Is . . . columnName the SQL name of the column. A java.lang.Object holding the column value. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods ResultSet Methods Note This method returns the value of the given column as a Java object. The type of the Java object will be the default Java object type corresponding to the column's SQL type, following the mapping for built-in types specified in the JDBC spec. You can also use this method to read database-specific abstract data types. When the a column contains a structured or distinct value, the behavior of this method is as if it were a call to: getObject(columnIndex, this.getStatement() .getConnection().getTypeMap()) getRow() Function Syntax Returns the current row number. public int getRow() throws SQLException Returns • If there is a current row, returns the row number. The first row number is 1. • If there is no current row, returns 0. Note Throws the SQLException if a database access error occurs. getShort(int columnIndex) Function Syntax Gets the value of a column designated by columnIndex in the current row of this ResultSet as a Java short. public short getShort(int columnIndex) throws SQLException Where parameter . . . Is . . . columnIndex the column specification. The first column is 1, the second is 2, . . . Returns The value of the designated column. Note If the column value returned is SQL NULL, the result is 0. getShort(String columnName) Function Syntax Gets the value of a column coulmnName in the current row of this ResultSet as a Java short. public short getShort(String columnName) throws SQLException Where parameter . . . Teradata Driver for the JDBC Interface User Guide Is . . . 221 Chapter 3: JDBC Methods ResultSet Methods columnName the SQL name of the column. Returns The value of the designated column. Note If the column value returned is SQL NULL, the result is 0. getStatement() Function Syntax Returns the Statement that produced this ResultSet object. public Statement getStatement() throws SQLException Returns The Statement that produced the ResultSet or null if the ResultSet was produced some other way. Note If the ResultSet was generated some other way, such as by a DatabaseMetaData method, this method returns null. getString(int columnIndex) Function Syntax Gets the value of a column designated by columnIndex in the current row of this ResultSet as a Java String. public String getString(int columnIndex) throws SQLException Where parameter . . . Is . . . columnIndex the column specification. The first column is 1, the second is 2, . . . Returns The value of the designated column. Note If the column value returned is SQL NULL, the result is null. getString(String columnName) Function Syntax Returns 222 Gets the value of a column designated by coulmnName in the current row of this ResultSet as a Java String. public String getString(String columnName) throws SQLException Where parameter . . . Is . . . columnName the SQL name of the column. The value of the designated column. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods ResultSet Methods Note If the column value returned is SQL NULL, the result is null. getTime(int columnIndex) Function Syntax Gets the value of the column designated by columnIndex in the current row of this ResultSet as a java.sql.Time object. public Time getTime(int columnIndex) throws SQLException Where parameter . . . Is . . . columnIndex the column specification. The first column is 1, the second is 2, . . . Returns The value of the designated column. Note If the column value returned is SQL NULL, the result is null. getTime(String columnName) Function Syntax Gets the value of the column designated by columnName in the current row of this ResultSet as a java.sql.Time object. public Time getTime(String columnName) throws SQLException Where parameter . . . Is . . . columnName the SQL name of the column. Returns The value of the designated column. Note If the column value returned is SQL NULL, the result is null. getTime(int columnIndex, Calendar cal) Function Gets the value of the column designated by columnIndex in the current row of this ResultSet as a java.sql.Time object. Syntax public Time getTime(int columnIndex, Calendar cal) throws SQLException Where parameter . . . Is . . . columnIndex the column specification. The first column is 1, the second is 2, . . . cal the calendar to use in constructing the time. Teradata Driver for the JDBC Interface User Guide 223 Chapter 3: JDBC Methods ResultSet Methods Returns The value of the designated column as a java.sql.Time object. Note If the column value returned is SQL NULL, the result is null. This method uses the given calendar to construct an appropriate millisecond value for the Time if the underlying database does not store timezone. When retrieving datatypes with time zone (time & timestamp), the time zone offset is put into calendar time zone offset and can be retrieved using the following command: cal.getTimeZone().getRawOffset() This is the milliseconds. getTime(String columnName, Calendar cal) Function Gets the value of the column designated by columnName in the current row of this ResultSet as a java.sql.Time object. Syntax public Time getTime(String columnName, Calendar cal) throws SQLException Where parameter . . . Is . . . columnName the SQL name of the column. cal the calendar to use in constructing the time. Returns The value of the designated column as a java.sql.Time object. Note If the column value returned is SQL NULL, the result is null. This method uses the given calendar to construct an appropriate millisecond value for the Time if the underlying database does not store timezone. When retrieving datatypes with time zone (time & timestamp), the time zone offset is put into calendar time zone offset and can be retrieved using the following command: cal.getTimeZone().getRawOffset() This is the milliseconds. getTimestamp(int columnIndex) 224 Function Gets the value of the column designated by columnIndex in the current row of this ResultSet as a java.sql.Timestamp object. Syntax public Timestamp getTimestamp(int columnIndex) throws SQLException Where parameter . . . Is . . . columnIndex the column specification. The first column is 1, the second is 2, . . . Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods ResultSet Methods Returns The value of the designated column. Note If the column value returned is SQL NULL, the result is null. getTimestamp(String columnName) Function Gets the value of the column designated by columnName in the current row of this as a java.sql.Timestamp object Syntax public Timestamp getTimestamp(String columnName) throws SQLException Where parameter . . . Is . . . columnName the SQL name of the column. Returns The value of the designated column. Note If the column value returned is SQL NULL, the result is null. getTimestamp(int columnIndex, Calendar cal) Function Gets the value of the column designated by columnIndex in the current row of this ResultSet as a java.sql.Timestamp object. Syntax public Timestamp getTimestamp(int columnIndex, Calendar cal) throws SQLException Where parameter . . . Is . . . columnIndex the column specification. The first column is 1, the second is 2, . . . cal the calendar to use in constructing the timestamp. Returns The value of the designated column as a java.sql.TimeStamp object. Note If the column value returned is SQL NULL, the result is null. This method uses the given calendar to construct an appropriate millisecond value for the Timestamp if the underlying database does not store timezone information. When retrieving datatypes with time zone (time & timestamp), the time zone offset is put into calendar time zone offset and can be retrieved using the following command: cal.getTimeZone().getRawOffset() This is the milliseconds. Teradata Driver for the JDBC Interface User Guide 225 Chapter 3: JDBC Methods ResultSet Methods getTimestamp(String columnName, Calendar cal) Function Syntax Gets the value of a column in the current row as a java.sql.Timestamp object. public Timestamp getTimestamp(String columnName, Calendar cal) throws SQLException Where parameter . . . Is . . . columnName the SQL name of the column. cal the calendar to use in constructing the timestamp. Returns The value of the designated column as a java.sql.TimeStamp object. Note If the column value returned is SQL NULL, the result is null. This method uses the given calendar to construct an appropriate millisecond value for the Timestamp if the underlying database does not store timezone information. When retrieving datatypes with time zone (time & timestamp), the time zone offset is put into calendar time zone offset and can be retrieved using the following command: cal.getTimeZone().getRawOffset() This is the milliseconds. getType() Function Syntax Returns the ResultSet object type. The Statement object that created the ResultSet determines the ResultSet type. public int getType() throws SQLException Returns • ResultSet.TYPE_FORWARD_ONLY • ResultSet.TYPE_SCROLL_INSENSITIVE, or • ResultSet.TYPE_SCROLL_SENSITIVE Note Throws the SQLException if a database access error occurs. getUnicodeStream(int columnIndex) Function [DEPRECATED] Gets the value of the column designated by columnIndex in the current row of this ResultSet as a stream of Unicode characters. The value can then be read in chunks from the stream. Use getCharacterStream(int columnIndex) in place of getUnicodeStream(int columnIndex). Syntax 226 public InputStream getUnicodeStream(int columnIndex) throws SQLException Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods ResultSet Methods Where parameter . . . Is . . . columnIndex the column specification. The first column is 1, the second is 2, . . . Returns A Java input stream that delivers the database column value as a stream of two-byte Unicode characters. Note If the value is SQL NULL then the result is null. This method is particularly suitable for retrieving large LONGVARCHAR values. The JDBC driver will do any necessary conversion from the database format into Unicode. The byte format of the Unicode stream must be Java UTF8, as defined in the Java Virtual Machine Specification. All the data in the returned stream must be read prior to getting the value of any other column. The next call to a get method implicitly closes the stream. Also, a stream may return 0 when the method available is called whether there is data available or not. getUnicodeStream(String columnName) Function Syntax [DEPRECATED] Gets the value of the column designated by columnName in the current row of this ResultSet as a stream of Unicode characters. The value can then be read in chunks from the stream. public InputStream getUnicodeStream(String columnName) throws SQLException Where parameter . . . Is . . . columnName the SQL name of the column. Returns A Java input stream that delivers the database column value as a stream of two-byte Unicode characters. Note If the value is SQL NULL then the result is null. This method is particularly suitable for retrieving large LONGVARCHAR values. The JDBC driver will do any necessary conversion from the database format into Unicode. The byte format of the Unicode stream must be Java UTF8, as defined in the Java Virtual Machine Specification. All the data in the returned stream must be read prior to getting the value of any other column. The next call to a get method implicitly closes the stream. Also, a stream may return 0 when the method available is called whether there is data available or not. Teradata Driver for the JDBC Interface User Guide 227 Chapter 3: JDBC Methods ResultSet Methods getWarnings() Function The first warning reported by calls on this ResultSet is returned. Subsequent ResultSet warnings will be chained to this SQLWarning. The warning chain is automatically cleared each time a new row is read. Syntax public SQLWarning getWarnings() throws SQLException Returns The first SQLWarning or null. Note This warning chain only covers warnings caused by ResultSet methods. Any warning caused by statement methods (such as reading OUT parameters) will be chained on the Statement object. insertRow() Function: Inserts the contents of the insert row into this ResultSet object and into the database. The cursor must be on the insert row when this method is called. Characteristic Description Syntax public void insertRow() throws SQLException Note: Throws the SQLException if a database access error occurs, if this method is called when the cursor is not on the insert row, or if not all of non-nullable columns in the insert row have been given a value isAfterLast() Function Syntax Determines whether the cursor in the ResultSet Object is located after the last row and returns the result. public boolean isAfterLast() throws SQLException Returns • True, if the cursor is located after the last row in the ResultSet object. • False, if the ResultSet object contains no rows, or if the cursor is not located after the last row. Note Throws the SQLException if a database access error occurs. isBeforeFirst() Function Syntax 228 Determines whether the cursor in the ResultSet Object is located before the first row and returns the result. public boolean isBeforeFirst() throws SQLException Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods ResultSet Methods Returns • True, if the cursor is located before the first row in the ResultSet object. • False, if the ResultSet object contains no rows, or if the cursor is not located before the first row. Note Throws the SQLException if a database access error occurs. isFirst() Function Syntax Determines whether the cursor in the ResultSet Object is located on the first row and returns the result. public boolean isFirst() throws SQLException Returns • True, if the cursor is located on the first row in the ResultSet object. • False, if the cursor is not located on the first row. Note Throws the SQLException if a database access error occurs. isLast() Function Syntax Determines whether the cursor in the ResultSet Object is located on the last row and returns the result. public boolean isLast() throws SQLException Returns • True, if the cursor is located on the last row in the ResultSet object. • False, if the cursor is not located on the last row. Notes • Throws the SQLException if a database access error occurs. • Calling isLast() may require the driver to fetch ahead one row to determine if the current row of the ResultSet object is the last row. last() Function Syntax Repositions the cursor to the last row. public boolean last() throws SQLException Returns • True, if the cursor is repositioned to a valid row in the ResultSet object. • False, if the cursor is not repositioned to a valid row in the ResultSet object. Notes Throws the SQLException if a database access error occurs, or if the ResultSet type is TYPE_FORWARD_ONLY. Teradata Driver for the JDBC Interface User Guide 229 Chapter 3: JDBC Methods ResultSet Methods moveToCurrentRow() Function: Moves the cursor to the remembered cursor position, usually the current row. This method has no effect if the cursor is not on the insert row. Characteristic Description Syntax public void moveToCurrentRow() throws SQLException Note: Throws the SQLException if a database access error occurs or the result set is not updatable moveToInsertRow() Function: Moves the cursor to the insert row. The current cursor position is remembered while the cursor is positioned on the insert row. The insert row is a special row associated with an updatable result set. It is essentially a buffer where a new row may be constructed by calling the updater methods prior to inserting the row into the result set. Only the updater, getter, and insertRow methods may be called when the cursor is on the insert row. All of the non-nullable columns in a result set must be given a value each time this method is called before calling insertRow. An updater method must be called before a getter method can be called on a column value. Characteristic Description Syntax public void moveToInsertRow() throws SQLException Note: Throws the SQLException if a database access error occurs or the result set is not updatable next() Function Syntax Repositions the cursor down one row from its current position. public boolean next() throws SQLException Returns • True, if the row where the cursor is repositioned is valid. • False, if there are no more rows. Note A ResultSet cursor is initially positioned before its first row. The first call to next makes the first row the current row. The second call makes the second row the current row, and so forth. If an input stream from the previous row is open, it is implicitly closed. The ResultSet's warning chain is cleared when a new row is read. previous() Function 230 Repositions the cursor to the previous row in the ResultSet object. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods ResultSet Methods Syntax public boolean previous() throws SQLException Returns • True, if the row where the cursor is repositioned is valid. • False, if the cursor is repositioned off the ResultSet. Notes Throws the SQLException if a database access error occurs, or if the ResultSet type is TYPE_FORWARD_ONLY. refreshRow() Function: An application is not supposed to call the refreshRow() method when the cursor is on the insert row. The refreshRow() method throws an SQLException if the cursor is on the insert row. This method clears up the column values updated by a set of updater methods for the current row in the result set. If refreshRow is called after calling an updater method, but before calling the updateRow method, then the updates made to the row are lost. The refreshRow() method does not read the row from data source again to refresh the current row. Characteristic Description Syntax public void refreshRow() throws SQLException Note: Throws the SQLException if a database access error occurs or if this method is called when the cursor is on the insert row. relative(int rows) Function Syntax Repositions the cursor within the ResultSet a relative number of rows forward or backward from the current position. public boolean relative(int rows) throws SQLException Where parameter . . . Is . . . rows an integer that specifies the number of rows to move from the current position. To move forward specify a positive number. To move backward, specify a negative number. Although 0 is valid, the cursor position will not change. Returns • True, if the row where the cursor is repositioned is valid. • False, if otherwise. Notes Throws the SQLException if a database access error occurs, there is no current row, or the ResultSet type is TYPE_FORWARD_ONLY. Teradata Driver for the JDBC Interface User Guide 231 Chapter 3: JDBC Methods ResultSet Methods rowDeleted() Function Syntax Detects and indicates if a row was deleted. public boolean rowDeleted() throws SQLException Returns • True if a row was deleted and the deletion was detected. • False if otherwise. Note The value returned is dependent on whether the ResultSet object is capable of detecting deletions. rowInserted() Function Syntax Detects and indicates if insertions were made into the current row. public boolean rowInserted() throws SQLException Returns • True if insertions were made into the current row and the insertion was detected. • False if insertions were not made into the current row or the insertion was not detected. Note The value returned is dependent on whether the ResultSet object is capable of detecting visible inserts. rowUpdated() Function Syntax Detects and indicates if updates were made to the current row. public boolean rowUpdated() throws SQLException Returns • True if updates were made into the current row and the updates were detected. • False if updates were not made into the current row or the updates were not detected. Note The value returned is dependent on whether the ResultSet object is capable of detecting visible updates. updateAsciiStream(int columnIndex, InputStream x, int length) Function: Updates the designated column with an ascii stream value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead, the updateRow or insertRow methods are called to update the database. 232 Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods ResultSet Methods Characteristic Description Syntax public void updateAsciiStream(int columnIndex, InputStream x, int length) throws SQLException where the parameter: • columnIndex is the column specification. The first column is 1, the second column is 2, and so forth • x is the new column value • length is the length of the stream Note: Throws the SQLException if a database access error occurs updateAsciiStream(String columnName, InputStream x, int length) Function: Updates the designated column with an ascii stream value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. Characteristic Description Syntax public void updateAsciiStream(String columnName, InputStream x, int length) throws SQLException where the parameter: • columnName is the name of the column • x is the new column value • length is the length of the stream Note: Throws the SQLException if a database access error occurs updateBigDecimal(int columnIndex, BigDecimal x) Function: Updates the designated column with a java.math.BigDecimal value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. Characteristic Description Syntax public void updateBigDecimal(int columnIndex, BigDecimal x) throws SQLException where the parameter: • columnIndex is the column specification. The first column is 1, the second column is 2, and so forth • x is the new column value Note: Throws the SQLException if a database access error occurs Teradata Driver for the JDBC Interface User Guide 233 Chapter 3: JDBC Methods ResultSet Methods updateBigDecimal(String columnName, BigDecimal x) Function: Updates the designated column with a java.math.BigDecimal value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. Characteristic Description Syntax public void updateBigDecimal(String columnName, BigDecimal x) throws SQLException where the parameter: • columnName is the name of the column • x is the new column value Note: Throws the SQLException if a database access error occurs updateBinaryStream(int columnIndex, InputStream x, int length) Function: Updates the designated column with a binary stream value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. Characteristic Description Syntax public void updateBinaryStream(int columnIndex, InputStream x, int length) throws SQLException where the parameter: • columnIndex is the column specification. The first column is 1, the second column is 2, and so forth • x is the new column value • length is the length of the stream Note: Throws the SQLException if a database access error occurs updateBinaryStream(String columnName, InputStream x, int length) Function: Updates the designated column with a binary stream value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. 234 Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods ResultSet Methods Characteristic Description Syntax public void updateBinaryStream(String columnName, InputStream x, int length) throws SQLException where the parameter: • columnName is the name of the column • x is the new column value • length is the length of the stream Note: Throws the SQLException if a database access error occurs updateBlob(int columnIndex, Blob x) Function: Updates the designated column with a java.sql.Blob value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. Characteristic Description Syntax public void updateBlob(int columnIndex, Blob x) throws SQLException where the parameter: • columnIndex is the column specification. The first column is 1, the second column is 2, and so forth • x is the new column value Note: Throws the SQLException if a database access error occurs updateBlob(String columnName, Blob x) Function: Updates the designated column with a java.sql.Blob value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. Characteristic Description Syntax public void updateBlob(String columnName, Blob x) throws SQLException where the parameter: • columnName is the name of the column • x is the new column value Note: Throws the SQLException if a database access error occurs Teradata Driver for the JDBC Interface User Guide 235 Chapter 3: JDBC Methods ResultSet Methods updateByte(int columnIndex, byte x) Function: Updates the designated column with a byte value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. Characteristic Description Syntax public void updateByte(int columnIndex, byte x) throws SQLException where the parameter: • columnIndex is the column specification. The first column is 1, the second column is 2, and so forth • x is the new column value Note: Throws the SQLException if a database access error occurs updateByte(String columnName, byte x) Function: Updates the designated column with a byte value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. Characteristic Description Syntax public void updateByte(String columnName, byte x) throws SQLException where the parameter: • columnName is the name of the column • x is the new column value Note: Throws the SQLException if a database access error occurs updateBytes(int columnIndex, byte[] x) Function: Updates the designated column with a byte array value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. 236 Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods ResultSet Methods Characteristic Description Syntax public void updateBytes(int columnIndex, byte[] x) throws SQLException where the parameter: • columnIndex is the column specification. The first column is 1, the second column is 2, and so forth • x is the new column value Note: Throws the SQLException if a database access error occurs updateBytes(String columnName, byte[] x) Function: Updates the designated column with a byte array value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. Characteristic Description Syntax public void updateBytes(String columnName, byte[] x) throws SQLException where the parameter: • columnName is the name of the column • x is the new column value Note: Throws the SQLException if a database access error occurs updateCharacterStream(int columnIndex, Reader x, int length) Function: Updates the designated column with a character stream value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. Characteristic Description Syntax public void updateCharacterStream(int columnIndex, Reader x, int length) throws SQLException where the parameter: • columnIndex is the column specification. The first column is 1, the second column is 2, and so forth • x is the new column value • length is the length of the stream Note: Throws the SQLException if a database access error occurs Teradata Driver for the JDBC Interface User Guide 237 Chapter 3: JDBC Methods ResultSet Methods updateCharacterStream(String columnName, Reader x, int length) Function: Updates the designated column with a character stream value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. Characteristic Description Syntax public void updateCharacterStream(String columnName, Reader x, int length) throws SQLException where the parameter: • columnName is the name of the column • x is the new column value • length is the length of the stream Note: Throws the SQLException if a database access error occurs updateClob(int columnIndex, Clob x) Function: Updates the designated column with a java.sql.Clob value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. Characteristic Description Syntax public void updateClob(int columnIndex, Clob x) throws SQLException where the parameter: • columnIndex is the column specification. The first column is 1, the second column is 2, and so forth • x is the new column value Note: Throws the SQLException if a database access error occurs updateClob(String columnName, Clob x) Function: Updates the designated column with a java.sql.Clob value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. 238 Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods ResultSet Methods Characteristic Description Syntax public void updateClob(String columnName, Clob x) throws SQLException where the parameter: • columnName is the name of the column • x is the new column value Note: Throws the SQLException if a database access error occurs updateDate(int columnIndex, Date x) Function: Updates the designated column with a java.sql.Date value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. Characteristic Description Syntax public void updateDate(int columnIndex, Date x) throws SQLException where the parameter: • columnIndex is the column specification. The first column is 1, the second column is 2, and so forth • x is the new column value Note: Throws the SQLException if a database access error occurs updateDate(String columnName, Date x) Function: Updates the designated column with a java.sql.Date value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. Characteristic Description Syntax public void updateDate(String columnName, Date x) throws SQLException where the parameter: • columnName is the name of the column • x is the new column value Note: Throws the SQLException if a database access error occurs Teradata Driver for the JDBC Interface User Guide 239 Chapter 3: JDBC Methods ResultSet Methods updateDouble(int columnIndex, double x) Function: Updates the designated column with a double value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. Characteristic Description Syntax public void updateDouble(int columnIndex, double x) throws SQLException where the parameter: • columnIndex is the column specification. The first column is 1, the second column is 2, and so forth • x is the new column value Note: Throws the SQLException if a database access error occurs updateDouble(String columnName, double x) Function: Updates the designated column with a double value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. Characteristic Description Syntax public void updateDouble(String columnName, double x) throws SQLException where the parameter: • columnName is the name of the column • x is the new column value Note: Throws the SQLException if a database access error occurs updateFloat(int columnIndex, float x) Function: Updates the designated column with a float value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. 240 Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods ResultSet Methods Characteristic Description Syntax public void updateFloat(int columnIndex, float x) throws SQLException where the parameter: • columnIndex is the column specification. The first column is 1, the second column is 2, and so forth • x is the new column value Note: Throws the SQLException if a database access error occurs updateFloat(String columnName, float x) Function: Updates the designated column with a float value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. Characteristic Description Syntax public void updateFloat(String columnName, float x) throws SQLException where the parameter: • columnName is the name of the column • x is the new column value Note: Throws the SQLException if a database access error occurs updateInt(int columnIndex, int x) Function: Updates the designated column with an int value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. Characteristic Description Syntax public void updateInt(int columnIndex, int x)throws SQLException where the parameter: • columnIndex is the column specification. The first column is 1, the second column is 2, and so forth • x is the new column value Note: Throws the SQLException if a database access error occurs Teradata Driver for the JDBC Interface User Guide 241 Chapter 3: JDBC Methods ResultSet Methods updateInt(String columnName, int x) Function: Updates the designated column with an int value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. Characteristic Description Syntax public void updateInt(String columnName, int x) throws SQLException where the parameter: • columnName is the name of the column • x is the new column value Note: Throws the SQLException if a database access error occurs updateLong(int columnIndex, long x) Function: Updates the designated column with a long value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. Characteristic Description Syntax public void updateLong(int columnIndex, long x) throws SQLException where the parameter: • columnIndex is the column specification. The first column is 1, the second column is 2, and so forth • x is the new column value Note: Throws the SQLException if a database access error occurs updateLong(String columnName, long x) Function: Updates the designated column with a long value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. 242 Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods ResultSet Methods Characteristic Description Syntax public void updateLong(String columnName, long x) throws SQLException where the parameter: • columnName is the name of the column • x is the new column value Note: Throws the SQLException if a database access error occurs updateNull(int columnIndex) Function: Gives a nullable column a null value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. Characteristic Description Syntax public void updateNull(int columnIndex) throws SQLException where the parameter columnIndex is the column specification. The first column is 1, the second column is 2, and so forth Note: Throws the SQLException if a database access error occurs updateNull(String columnName) Function: Gives a nullable column a null value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. Characteristic Description Syntax public void updateNull(String columnName)throws SQLException where the parameter columnName is the name of the column Note: Throws the SQLException if a database access error occurs updateObject(int columnIndex, Object x) Function: Updates the designated column with an Object value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. Teradata Driver for the JDBC Interface User Guide 243 Chapter 3: JDBC Methods ResultSet Methods Characteristic Description Syntax public void updateObject(int columnIndex, Object x)throws SQLException where the parameter: • columnIndex is the column specification. The first column is 1, the second column is 2, and so forth • x is the new column value Note: Throws the SQLException if a database access error occurs updateObject(int columnIndex, Object x, int scale) Function: Updates the designated column with an Object value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. Characteristic Description Syntax public void updateObject(int columnIndex, Object x, int scale)throws SQLException where the parameter: • columnIndex is the column specification. The first column is 1, the second column is 2, and so forth • x is the new column value • scale is the number of digits after the decimal point (for java.sql.Types.DECIMA or java.sql.Types.NUMERIC). For all other types, this value is ignored. Note: Throws the SQLException if a database access error occurs updateObject(String columnName, Object x) Function: Updates the designated column with an Object value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. Characteristic Description Syntax public void updateObject(String columnName, Object x)throws SQLException where the parameter: • columnName is the name of the column • x is the new column value Note: Throws the SQLException if a database access error occurs 244 Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods ResultSet Methods updateObject(String columnName, Object x, int scale) Function: Updates the designated column with an Object value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. Characteristic Description Syntax public void updateObject(String columnName, Object x, int scale) throws SQLException where the parameter: • columnName is the name of the column • x is the new column value • scale is the number of digits after the decimal point (for java.sql.Types.DECIMA or java.sql.Types.NUMERIC types). For all other types, this value is ignored. Note: Throws the SQLException if a database access error occurs updateRow() Function: Updates the underlying database with the new contents of the current row of this ResultSet object. This method cannot be called when the cursor is on the insert row. Characteristic Description Syntax public void updateRow()throws SQLException Note: Throws the SQLException if a database access error occurs or if this method is called when the cursor is on the insert row updateShort(int columnIndex, short x) Function: Updates the designated column with a short value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. Characteristic Description Syntax public void updateShort(int columnIndex, short x)throws SQLException where the parameter: • columnIndex is the column specification. The first column is 1, the second column is 2, and so forth • x is the new column value Note: Throws the SQLException if a database access error occurs Teradata Driver for the JDBC Interface User Guide 245 Chapter 3: JDBC Methods ResultSet Methods updateShort(String columnName, short x) Function: Updates the designated column with a short value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. Characteristic Description Syntax public void updateShort(String columnName, short x)throws SQLException where the parameter: • columnName is the name of the column • x is the new column value Note: Throws the SQLException if a database access error occurs updateString(int columnIndex, String x) Function: Updates the designated column with a String value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. Characteristic Description Syntax public void updateString(int columnIndex, String x)throws SQLException where the parameter: • columnIndex is the column specification. The first column is 1, the second column is 2, and so forth • x is the new column value Note: Throws the SQLException if a database access error occurs updateString(String columnName, String x) Function: Updates the designated column with a String value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. 246 Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods ResultSet Methods Characteristic Description Syntax public void updateString(String columnName, String x)throws SQLException where the parameter: • columnName is the name of the column • x is the new column value Note: Throws the SQLException if a database access error occurs updateTime(int columnIndex, Time x) Function: Updates the designated column with a java.sql.Time value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. Characteristic Description Syntax public void updateTime(int columnIndex, Time x)throws SQLException where the parameter: • columnIndex is the column specification. The first column is 1, the second column is 2, and so forth • x is the new column value Note: Throws the SQLException if a database access error occurs updateTime(String columnName, Time x) Function: Updates the designated column with a java.sql.Time value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. Characteristic Description Syntax public void updateTime(String columnName, Time x)throws SQLException where the parameter: • columnName is the name of the column • x is the new column value Note: Throws the SQLException if a database access error occurs Teradata Driver for the JDBC Interface User Guide 247 Chapter 3: JDBC Methods ResultSet Methods updateTimestamp(int columnIndex, Timestamp x) Function: Updates the designated column with a java.sql.Timestamp value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. Characteristic Description Syntax public void updateTimestamp(int columnIndex, Timestamp x)throws SQLException where the parameter: • columnIndex is the column specification. The first column is 1, the second column is 2, and so forth • x is the new column value Note: Throws the SQLException if a database access error occurs updateTimestamp(String columnName, Timestamp x) Function: Updates the designated column with a java.sql.Timestamp value. The updater methods are used to update column values in the current row or the insert row. The updater methods do not update the underlying database; instead the updateRow or insertRow methods are called to update the database. Characteristic Description Syntax public void updateTimestamp(String columnName, Timestamp x)throws SQLException where the parameter: • columnName is the name of the column • x is the new column value Note: Throws the SQLException if a database access error occurs wasNull() Function Syntax 248 A column may have the value of SQL NULL. The wasNull method reports whether the last column read had this special value. public boolean wasNull() throws SQLException Returns • True if the last column read was SQL NULL. • False if otherwise. Note You must first call getXXX on a column to try to read its value and then call wasNull() to find if the value was the SQL NULL. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods ResultSetMetaData Methods ResultSetMetaData Methods Description A ResultSetMetaData object can be used to determine the types and properties of the columns in a ResultSet. Methods The following subsections provide a brief description of each supported ResultSetMetaData method, presented in alphabetic order. getColumnClassName(int column) Function Syntax Returns Gets the fully-qualified name of the Java class whose instances are manufactured if the method ResultSet.getObject is called to retrieve a value from the specified column. ResultSet.getObject may return a subclass of the class returned by this method. public String getColumnClassName(int column) throws SQLException Where parameter . . . Is . . . column the column specification. The first column is 1, the second column is 2, . . . A fully-qualified name of a class in the Java programming language that can be used for custom mapping. getColumnCount() Function Syntax Returns Finds out the number of columns in the ResultSet. public int getColumnCount() throws SQLException The number of columns in the ResultSet. getColumnDisplaySize(int column) Function: Determines the normal maximum width of a column in characters. Characteristic Description Syntax public int getColumnDisplaySize(int column) throws SQLException where the parameter column is the column specification. The first column is 1, the second column is 2, and so forth. Teradata Driver for the JDBC Interface User Guide 249 Chapter 3: JDBC Methods ResultSetMetaData Methods Characteristic Description Return The normal maximum width of the column is returned. Note For any character data type, the display size is always calculated based on the Teradata session character set. If the CLIENT_CHARSET connection parameter is specified, then the display size may not be accurate for these data types. getColumnLabel(int column) Function Syntax Returns Finds out the suggested column title for use in printouts and displays. public String getColumnLabel(int column) throws SQLException Where parameter . . . Is . . . column the column specification. The first column is 1, the second column is 2, . . . The suggested column label. getColumnName(int column) Function Syntax Returns Finds out the name of a column. public String getColumnName(int column) throws SQLException Where parameter . . . Is . . . column the column specification. The first column is 1, the second column is 2, . . . The column name. getColumnType(int column) Function Syntax 250 Finds out the SQL type of a column. public int getColumnType(int column) throws SQLException Where parameter . . . Is . . . column the column specification. The first column is 1, the second column is 2, . . . Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods ResultSetMetaData Methods Returns The SQL type of the column. Note If the column type is a user-defined type, then a fully-qualified type name is returned. getColumnTypeName(int column) Function Syntax Returns Finds out the data source specific type name of a column. public String getColumnTypeName(int column) throws SQLException Where parameter . . . Is . . . column the column specification. The first column is 1, the second column is 2, . . . The type name of the column. getPrecision(int column) Function Syntax Returns Finds out the number of decimal digits of a column. public int getPrecision(int column) throws SQLException Where parameter . . . Is . . . column the column specification. The first column is 1, the second column is 2, . . . The precision of the column. getScale(int column) Function Syntax Returns Finds out the number of digits to the right of the decimal point of a column. public int getScale(int column) throws SQLException Where parameter . . . Is . . . column the column specification. The first column is 1, the second column is 2, . . . The number of digits to the right of the decimal point in the column. Teradata Driver for the JDBC Interface User Guide 251 Chapter 3: JDBC Methods Statement Methods isNullable(int column) Function Syntax Returns Finds out if you can you put a NULL in a column. public int isNullable(int column) throws SQLException Where parameter . . . Is . . . column the column specification. The first column is 1, the second column is 2, . . . Either: • columnNoNulls • columnNullable • columnNullableUnknown Statement Methods Description A Statement object is used for: • Executing a static SQL statement • Obtaining the results produced by the statement Only one ResultSet per Statement can be open at any point in time. Therefore, if the reading of one ResultSet is interleaved with the reading of another, each must have been generated by different Statements. All Statement execute methods implicitly close a Statement's current ResultSet if an open one exists. Methods The following subsections provide a brief description of each supported Statement method, presented in alphabetic order. addBatch(String sql) Function Syntax 252 Adds an SQL command to the current batch of commands for this Statement object. public void addBatch(String sql) throws SQLException Where parameter . . . Is . . . sql any SQL statement. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods Statement Methods cancel() Function Cancel can be used by one thread to cancel a statement that is being executed by another thread. If the Teradata Database is still processing the statement when the cancel method is called, then the statement will be cancelled. If the statement had been completed upon receipt of the cancel request, the statement will not be cancelled. In Teradata transaction mode, cancelling a statement rolls back the transaction enclosing the statement. This is the correct and expected behavior for Teradata transaction mode. Warning: In ANSI transaction mode, with auto-commit turned off, cancelling a statement may sometimes roll back the transaction enclosing the statement. This is incorrect behavior for ANSI transaction mode. The intent is to correct this behavior in a future release. Until this behavior is corrected, users should avoid using the cancel method in the problematic situations. Warning: In ANSI transaction mode, using prepared statement batch updates, cancelling the prepared statement may sometimes roll back the transaction enclosing the prepared statement, and may return erroneous update counts for some of the updates in the batch. This is incorrect behavior for ANSI transaction mode. The intent is to correct this behavior in a future release. Until this behavior is corrected, users should avoid using the cancel method in the problematic situations. Syntax public void cancel() throws SQLException clearBatch() Function Syntax Makes the set of commands in the current batch empty. public void clearBatch() throws SQLException clearWarnings() Function Syntax Clears all the warnings reported on this statement. After this call, getWarnings returns null until a new warning is reported for this Statement. public void clearWarnings() throws SQLException close() Function Syntax In many cases, it is desirable to immediately release a Statements's database and JDBC resources instead of waiting for this to happen when it is automatically closed. The close method provides this immediate release. public void close() throws SQLException Teradata Driver for the JDBC Interface User Guide 253 Chapter 3: JDBC Methods Statement Methods Returns A Statement is automatically closed when it is garbage collected. When a Statement is closed, its current ResultSet, if one exists, is also closed. execute(String sql) Function Syntax Executes a SQL statement that may return multiple results. public boolean execute(String sql) throws SQLException Where parameter . . . Is . . . sql any SQL statement. Returns • True if the next result is a ResultSet. • False if it is an update count or if there are no more results. Note Under some uncommon situations, a single SQL statement may return multiple ResultSets and/or update counts. Normally, you can ignore this, unless you are executing a stored procedure that you know may return multiple results, or you are dynamically executing an unknown SQL string. The "execute," "getMoreResults," "getResultSet," and "getUpdateCount" methods let you navigate through multiple results. The "execute" method executes a SQL statement and indicates the form of the first result. You can then use getResultSet or getUpdateCount to retrieve the result, and getMoreResults to move to any subsequent results. See also “getResultSet()” on page 261, “getUpdateCount()” on page 262, and “getMoreResults()” on page 260. executeBatch() Function Submits a batch of commands to the database for execution and if all commands execute successfully, returns an array of update counts. The int elements of the array that is returned are ordered to correspond to the commands in the batch, which are ordered according to the order in which they are added to the batch. The elements in the array returned by the method executeBatch may be one of the following: 1 A number greater than or equal to zero–indicates that the command was processed successfully and is an update count giving the number of rows in the database that were affected by the command's execution. 2 A value of -2–indicates that the command was processed successfully but that the number of rows affected is unknown. SQL command that attempts to return a result set will have a number -2 and the method will throw a BatchUpdateException. 3 A value -3 –indicates that the command failed to execute successfully. Syntax 254 public int[] executeBatch() throws SQLException Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods Statement Methods Returns Throws BatchUpdateException (a subclass of SQLException) if one of the commands sent to the database fails to execute properly or attempts to return a result set. An exception is returned if used to execute a statement that returns result sets. The error is 1080 "executeBatch() cannot be used when a result set is expected; use execute()". execute(String sql, int autoGeneratedKeys) Function Executes the given SQL statement, which may return multiple results, and signals the driver that any auto-generated keys should be made available for retrieval. The driver will ignore this signal if the SQL statement is not an INSERT statement. In some (uncommon) situations, a single SQL statement may return multiple result sets and/or update counts. Normally you can ignore this unless you are (1) executing a stored procedure that you know may return multiple results or (2) you are dynamically executing an unknown SQL string. The execute method executes an SQL statement and indicates the form of the first result. You must then use the methods getResultSet or getUpdateCount to retrieve the result, and getMoreResults to move to any subsequent result(s). Syntax Returns Note public boolean execute(String sql, int autogeneratedKeys) throws SQLException Where parameter . . . Is . . . sql any SQL statement. autoGeneratedKeys a constant indicating whether auto-generated keys should be made available for retrieval using the method getGeneratedKeys; one of the following constants: Statement.RETURN_GENERATED_KEYS or Statement.NO_GENERATED_KEYS . True if the first result is a ResultSet object; false if it is an update count or there are no results. Throws an SQLException if a database access error occurs or the second parameter supplied to this method is not Statement.RETURN_GENERATED_KEYS or Statement.NO_GENERATED_KEYS. Teradata Driver for the JDBC Interface User Guide 255 Chapter 3: JDBC Methods Statement Methods execute(String sql, int[] columnIndexes) Function Executes the given SQL statement, which may return multiple results, and signals the driver that the auto-generated keys indicated in the given array should be made available for retrieval. This array contains the indexes of the columns in the target table that contain the auto-generated keys that should be made available. The driver will ignore the array if the given SQL statement is not an INSERT statement. Under some (uncommon) situations, a single SQL statement may return multiple result sets and/or update counts. Normally you can ignore this unless you are (1) executing a stored procedure that you know may return multiple results or (2) you are dynamically executing an unknown SQL string. The execute method executes an SQL statement and indicates the form of the first result. You must then use the methods getResultSet or getUpdateCount to retrieve the result, and getMoreResults to move to any subsequent result(s). Syntax Returns Note public boolean execute(String sql, int[] columnIndexes) throws SQLException Where parameter . . . Is . . . sql any SQL statement. columnIndexes an array of the indexes of the columns in the inserted row that should be made available for retrieval by a call to the method getGeneratedKeys. True if the first result is a ResultSet object; false if it is an update count or there are no results. Throws an SQLException if a database access error occurs or the elements in the int array passed to this method are not valid column indexes. execute(String sql, String[] columnNames) Function Executes the given SQL statement, which may return multiple results, and signals the driver that the auto-generated keys indicated in the given array should be made available for retrieval. This array contains the names of the columns in the target table that contain the auto-generated keys that should be made available. The driver will ignore the array if the given SQL statement is not an INSERT statement. In some (uncommon) situations, a single SQL statement may return multiple result sets and/or update counts. Normally you can ignore this unless you are (1) executing a stored procedure that you know may return multiple results or (2) you are dynamically executing an unknown SQL string. The execute method executes an SQL statement and indicates the form of the first result. You must then use the methods getResultSet or getUpdateCount to retrieve the result, and getMoreResults to move to any subsequent result(s). Syntax public boolean execute(String sql, String[] columnNames) throws SQLException Where parameter . . . 256 Is . . . Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods Statement Methods Returns Note sql any SQL statement. columnNames an array of the names of the columns in the inserted row that should be made available for retrieval by a call to the method getGeneratedKeys. True if the next result is a ResultSet object; false if it is an update count or there are no more results. Throws an SQLException if a database access error occurs or the elements of the String array passed to this method are not valid column names. executeQuery(String sql) Function Syntax Returns Executes a SQL statement that returns a single ResultSet. public ResultSet executeQuery(String sql) throws SQLException Where parameter . . . Is . . . sql typically, a static SQL SELECT statement. A ResultSet that contains the data produced by the query—never null. executeUpdate(String sql) Function Syntax Returns Executes a SQL INSERT, UPDATE or DELETE statement. In addition, SQL statements that return nothing, such as DDL statements, can be executed. public int executeUpdate(String sql) throws SQLException Where parameter . . . Is . . . sql any SQL INSERT, UPDATE or DELETE statement, or a SQL statement that returns nothing. Either the row count for INSERT, UPDATE, or DELETE, or zero for SQL statements that return nothing. executeUpdate(String sql, int autoGeneratedKeys) Function Executes a SQL INSERT, UPDATE or DELETE statement. In addition, SQL statements that return nothing, such as DDL statements, can be executed. Syntax public int executeUpdate(String sql, int autogeneratedKeys) throws SQLException Where parameter . . . Teradata Driver for the JDBC Interface User Guide Is . . . 257 Chapter 3: JDBC Methods Statement Methods Returns Note sql any SQL INSERT, UPDATE or DELETE statement, or a SQL statement that returns nothing. autoGeneratedKeys a flag indicating whether auto-generated keys should be made available for retrieval; one of the following constants: Statement.RETURN_GENERATED_KEYS Statement.NO_GENERATED_KEYS. Either the row count for INSERT, UPDATE or DELETE statements, or 0 for SQL statements that return nothing. Throws an SQLException if a database access error occurs, the given SQL statement returns a ResultSet object, or the given constant is not one of those allowed. executeUpdate(String sql, int[] columnIndexes) Function Syntax Returns Note Executes the given SQL statement and signals the driver that the auto-generated keys indicated in the given array should be made available for retrieval. The driver will ignore the array if the SQL statement is not an INSERT statement. public int executeUpdate(String sql, int[] columnIndexes) throws SQLException Where parameter . . . Is . . . sql an SQL INSERT, UPDATE or DELETE statement or an SQL statement that returns nothing, such as an SQL DDL statement. columnIndexes an array of column indexes indicating the columns that should be returned from the inserted row. Either the row count for INSERT, UPDATE, or DELETE statements, or 0 for SQL statements that return nothing. Throws an SQLException if a database access error occurs, the SQL statement returns a ResultSet object, or the second argument supplied to this method is not an int array whose elements are valid column indexes. executeUpdate(String sql, String[] columnNames) Function Syntax Executes the given SQL statement and signals the driver that the auto-generated keys indicated in the given array should be made available for retrieval. The driver will ignore the array if the SQL statement is not an INSERT statement. public int executeUpdate(String sql, String[] columnNames) throws SQLException Where parameter . . . 258 Is . . . Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods Statement Methods Returns Note sql an SQL INSERT, UPDATE or DELETE statement or an SQL statement that returns nothing. columnNames an array of the names of the columns that should be returned from the inserted row. Either the row count for INSERT, UPDATE, or DELETE statements, or 0 for SQL statements that return nothing. Throws an SQLException if a database access error occurs, the SQL statement returns a ResultSet object, or the second argument supplied to this method is not a String array whose elements are valid column names. getConnection() Function Syntax Returns Gets the connection object that produced statement. public Connection getConnection() throws SQLException Gets the connection object that produced this statement object. getGeneratedKeys() Function Syntax Returns Retrieves any auto-generated keys created as a result of executing this Statement object. If this Statement object did not generate any keys, an empty ResultSet object is returned. ResultSet getGeneratedKeys() throws SQLException A ResultSet object containing the auto-generated key(s) generated by the execution of this Statement object. getMaxFieldSize() Function Syntax Returns the maxFieldSize limit in bytes. public int getMaxFieldSize() throws SQLException Returns The current maximum column size limit. Zero means unlimited. Note If the limit is exceeded, the excess data is discarded. The maxFieldSize is the maximum amount of data returned for any column value. It only applies to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR columns. Teradata Driver for the JDBC Interface User Guide 259 Chapter 3: JDBC Methods Statement Methods getMaxRows() Function Syntax Returns the maxRows limit. public int getMaxRows() throws SQLException Returns The current maximum row limit. Zero means unlimited. Note The maxRows limit is the maximum number of rows that a ResultSet can contain. If the limit is exceeded, the excess rows are dropped. getMoreResults() Function Syntax Moves to a Statement's next result. It returns true if this result is a ResultSet. public boolean getMoreResults() throws SQLException Returns • True if the next result is a ResultSet. • False if the next result is an update count or there are no more results. Note getMoreResults implicitly closes any current ResultSet obtained with getResultSet. There are no more results when: (!getMoreResults() && (getUpdateCount() == -1) See also “execute(String sql)” on page 254. getMoreResults(int current) Function: Moves to a Statement’s next result; deals with any current ResultSet object according to the instructions specified by the given flag. It returns true if this result is a ResultSet. Characteristic Description Syntax public boolean getMoreResults(int current) throws SQLException where the parameter current is one of the following Statement constants indicating what should happen to current ResultSet objects obtained using the method getResultSet: Statement.CLOSE_CURRENT_RESULT or Statement.KEEP_CURRENT_RESULT Return 260 • True, if the next result is a ResultSet • False, if the next result is an update count or there are no more results Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods Statement Methods Characteristic Description Note getMoreResults(Statement.KEEP_CURRENT_RESULT) is only supported for Statement with its generated ResultSet type to be ResultSet.TYPE_SCROLL_INSENSITIVE. ResultSet.TYPE_SCROLL_INSENSITIVE must be specified in order to use Statement.getMoreResults(Statement.KEEP_CURRENT_RESULT), such as in the following method calls: Connection.createStatement(ResultSet.TYPE_SCROLL_INSENSITIVE, ResultSet.CONCUR_READ_ONLY); Connection.prepareStatement(sql, ResultSet.TYPE_SCROLL_INSENSITIVE, ResultSet.CONCUR_READ_ONLY); Connection.prepareCall(sql, ResultSet.TYPE_SCROLL_INSENSITIVE, ResultSet.CONCUR_READ_ONLY); There are no more results when: (!getMoreResults(current) && getUpdateCount() == -1) Beginning with Teradata Database 12.0, when the application requests the ResultSet type to be ResultSet.TYPE_SCROLL_INSENSITIVE, then the Teradata Driver for the JDBC Interface is able to quickly and efficiently skip to the next result of a multistatement request by using cursor positioning to position to the last row of the current result set. The application must request scrollable result sets to obtain the improved performance when skipping to the next result. If the application requests forwardonly result sets, then cursor positioning is not used, and the Teradata Driver for the JDBC Interface must fetch all rows of the current result set in order to advance to the next result. getQueryTimeout() Function Syntax Retrieves the queryTimeout limit. The limit is the number of seconds the driver will wait for a Statement to execute. public int getQueryTimeout() throws SQLException Returns The current query timeout limit in seconds. Zero means unlimited. Note If the limit is exceeded, a SQLException is thrown. getResultSet() Function Syntax Returns Returns the current result as a ResultSet. This method should only be called once per result. public ResultSet getResultSet() throws SQLException • The current result as a ResultSet. • Null if the result is an update count or there are no more results. Teradata Driver for the JDBC Interface User Guide 261 Chapter 3: JDBC Methods Statement Methods Note See also “execute(String sql)” on page 254. getResultSetConcurrency() Function: Retrieves the result set concurrency for ResultSet objects generated by this Statement object. Characteristic Description Syntax public int getResultSetConcurrency() throws SQLException Return Either ResultSet.CONCUR_READ_ONLY or ResultSet.CONCUR_UPDATABLE is returned. Note: Throws the SQLException if a database access error occurs getResultSetHoldability() Function Syntax Retrieves the result set holdability for ResultSet objects generated by this Statement object. public int getResultSetHoldability() throws SQLException Returns The default holdability: ResultSet.HOLD_CURSORS_OVER_COMMIT. Note Teradata JDBC driver currently does not support ResultSet.CLOSE_CURSORS_AT_COMMIT. getUpdateCount() Function Returns the current result as an update count. It should only be called once per result. Syntax public int getUpdateCount() throws SQLException Returns • The current result as an update count. • -1 if it is a ResultSet or there are no more results. Note See also “execute(String sql)” on page 254. getWarnings() Function Syntax 262 The first warning reported by calls on this Statement is returned. public SQLWarning getWarnings() throws SQLException Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods Statement Methods Returns The first SQL Warning or null. Note A Statement’s execute methods clear its SQLWarning chain. Subsequent Statement warnings will be chained to this SQLWarning. The warning chain is automatically cleared each time a statement is re-executed. If you are processing a ResultSet, any warnings associated with ResultSet reads will be chained on the ResultSet object. setMaxFieldSize(int max) Function Syntax Note Sets the maxFieldSize limit in bytes. public void setMaxFieldSize(int max) throws SQLException Where parameter . . . Is . . . max the new maximum column size limit. (Zero means unlimited.) The maxFieldSize is set to limit the size of data that can be returned for any column value. The limit only applies to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR fields. If the limit is exceeded, the excess data is discarded. For maximum portability, use values greater than 256. setMaxRows(int max) Function Syntax Note Sets the maxRows limit. public void setMaxRows(int max) throws SQLException Where parameter . . . Is . . . max the new maximum rows limit. (Zero means unlimited number of rows.) MaxRows is set to limit the number of rows that any ResultSet can contain. If the limit is exceeded, the excess rows are dropped. setQueryTimeout(int seconds) Function Syntax Sets the queryTimeout limit. public void setQueryTimeout(int seconds) throws SQLException Where parameter . . . Teradata Driver for the JDBC Interface User Guide Is . . . 263 Chapter 3: JDBC Methods TeraDataSource Methods seconds Note the new query timeout limit in seconds. (Zero means an unlimited number of seconds.) The queryTimeout limit is the number of seconds the driver will wait for a Statement to execute. If the limit is exceeded, a SQLException is thrown. TeraDataSource Methods Description The methods used to obtain a connection from a DataSource are the same regardless of the underlying database. The parameters and information that are specific to the database are set when the DataSource is created. For Teradata, this is done with the classes: • TeraDataSource • TeraConnectionPooledDataSource. TeraConnectionPoolDataSource implements javax.sql.ConnectionPoolDataSource, and provides the same connection parameter getter and setter methods as TeraDataSource. The main difference between TeraConnectionPoolDataSource and TeraDataSource is that the first will return pooled connections while the latter will not. From the perspective of creation, they are identical at this time. Everything needed to specify a TeraDataSource must be specified for a TeraConnectionPoolDataSource. The parameters you can set or view here are the same as those used in the URL of the DriverManager.getConnection() method. Additional information about them can be found in “Making a Teradata Database Connection” on page 43 of this book. Warning: As the Teradata Database doesn't provide any means to "reset" a connection, the user of a connection pool data source must be aware that any commands that affect the session defaults must not be used as the new defaults will then be in effect for the next unsuspecting user of that connection. The session parameters that MUST NOT BE CHANGED include: 264 • Database • Collation • Character Set • Transaction Semantics • Dateform • Timezone • Default date format Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods TeraDataSource Methods Methods getACCOUNT() Function: Gets the accountId. It returns the name of the account to be charged. Characteristic Description Syntax public String getACCOUNT() Note: The getAccount and getAccountId methods are deprecated. Use the getACCOUNT method instead. getCharSet()/getCHARSET() Function Syntax Returns Get the session character set. public java.lang.String getCharSet() The character set. getCOMPAT_DBS() Function Syntax Returns Get the COMPAT_DBS value. public java.lang.String getCOMPAT_DBS() The COMPAT_DBS value. getCOMPAT_GETSCHEMA() Function Syntax Returns Get the COMPAT_GETSCHEMA value. public java.lang.String getCOMPAT_GETSCHEMA() The COMPAT_GETSCHEMA value. getCOMPAT_GETTABLE() Function Syntax Returns Get the COMPAT_GETTABLE value. public java.lang.String getCOMPAT_GETTABLE() The COMPAT_GETTABLE value. Teradata Driver for the JDBC Interface User Guide 265 Chapter 3: JDBC Methods TeraDataSource Methods getCOMPAT_ISAUTOINC() Function Syntax Returns Get the COMPAT_ISAUTOINC value. public java.lang.String getCOMPAT_ISAUTOINC() The COMPAT_ISAUTOINC value. getCOMPAT_ISCURRENCY() Function Syntax Returns Get the COMPAT_ISCURRENCY value. public java.lang.String getCOMPAT_ISCURRENCY() The COMPAT_ISCURRENCY value. getCOMPAT_ISDEFWRIT() Function Syntax Returns Get the COMPAT_ISDEFWRIT value. public java.lang.String getCOMPAT_ISDEFWRIT() The COMPAT_ISDEFWRIT value. getCOMPAT_ISREADONLY() Function Syntax Returns Get the COMPAT_ISREADONLY value. public java.lang.String getCOMPAT_ISREADONLY() The COMPAT_ISREADONLY value. getCOMPAT_ISSEARCH() Function Syntax Returns 266 Get the COMPAT_ISSEARCH value. public java.lang.String getCOMPAT_ISSEARCH() The COMPAT_ISSEARCH value. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods TeraDataSource Methods getCOMPAT_ISSIGNED() Function Syntax Returns Get the COMPAT_ISSIGNED value. public java.lang.String getCOMPAT_ISSIGNED() The COMPAT_ISSIGNED value. getCOMPAT_ISWRITABLE() Function Syntax Returns Get the COMPAT_ISWRITABLE value. public java.lang.String getCOMPAT_ISWRITABLE() The COMPAT_ISWRITABLE value. getConnection() Function Syntax Returns Attempt to establish a database connection. public java.sql.Connection getConnection() throws java.sql.SQLException A connection to the database. Teradata Driver for the JDBC Interface User Guide 267 Chapter 3: JDBC Methods TeraDataSource Methods getConnection(java.lang.String username, java.lang.String password) Function Syntax Returns Attempt to establish a database connection. public java.sql.Connection getConnection(java.lang.String username, java.lang.String password) throws java.sql.SQLException Where parameter . . . Is . . . username the database user on whose behalf the Connection is being made. password the user's password. A connection to the database. getDatabase()/getdatabase()/getDATABASE() Function Syntax Returns Get the Default Database name. This returns the name of a default database that will be set at logon time. public java.lang.String getDatabase() The default database name. getdatasourceName() Function Syntax Returns Get the name of this datasource. public java.lang.String getdatasourceName() The datasource name or null. getDBS_PORT() Function Syntax Returns 268 Get the DBS_PORT value. This specifies the TCP/IP port used to access the Teradata Database. public java.lang.String getDBS_PORT() The DBS_PORT value. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods TeraDataSource Methods getdescription() Function Syntax Returns Get the description of the DataSource. public java.lang.String getdescription() A description. getDSName() Function Syntax Returns Get the Database Server name. This returns the name of the server running the Teradata Database. public java.lang.String getDSName() The Database Server name. getENCRYPTDATA() Function Syntax Returns Get the EncryptData flag. public java.lang.String getENCRYPTDATA() “ON” - When set to “ON”, data sent between the Teradata Driver for the JDBC Interface and the Teradata Database are encrypted. This provides greater security, although performance will be effected. “OFF” - When set to “OFF”, data sent between the Teradata Driver for the JDBC Interface and the Teradata Database are not encrypted. Note The setLOGMECH(java.lang.String logMECH) method determines which encryption method will be available and whether or not Single Sign-on is supported. The setENCRYPTDATA(java.lang.String encryptData) determines whether or not data is encrypted on the connection. getFetchRows() Function Syntax Returns Get the Fetch Rows value used in Row Caching. public java.lang.String getFetchRows() The Fetch Rows value. getLOB_SUPPORT() Function Get the LOB_SUPPORT value. Teradata Driver for the JDBC Interface User Guide 269 Chapter 3: JDBC Methods TeraDataSource Methods Syntax Returns public java.lang.String getLOB_SUPPORT() The LOB_SUPPORT value. getLOB_TEMP_TABLE() Function: Gets the LOB_TEMP_TABLE value. Characteristic Description Syntax public java.lang.String getLOB_TEMP_TABLE() Return The tableName used for Updatable Lobs is returned. getLOG() Function Syntax Returns Get the LOG value. public java.lang.String getLOG() The LOG value. getLoginTimeout() Function Syntax Returns Get the Login Timeout. public int getLoginTimeout() throws java.sql.SQLException The login timeout. getLOGDATA() Function Syntax Returns Get the LogData value. public java.lang.String getLOGDATA() The LogData value or null. getLOGMECH() Function Syntax 270 Get the Logon Mechanism value. public java.lang.String getLOGMECH() Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods TeraDataSource Methods Returns The Logon Mechanism or null. getLogWriter() Function Syntax Returns Get the Log File name. public java.io.PrintWriter getLogWriter() The log file name. getpassword() Function Syntax Returns Get the password used for DBS access. public java.lang.String getpassword() The password. getportNumber() Function Syntax Returns This function has been deprecated. Get the port number used by the TeraData JDBC gateway. getPortNumber will log an error message, but will not throw an exception. public java.lang.String getportNumber() The port number. getReference() Function Syntax Returns Get a Reference to the TeraDataSource. public javax.naming.Reference getReference() throws javax.naming.NamingException A Reference to the TeraDataSource. getServerName() Function Syntax Returns This function has been deprecated. Get the Teradata JDBC gateway Server name. getServerName will log an error message, but will not throw an exception. public java.lang.String getServerName() The server name. Teradata Driver for the JDBC Interface User Guide 271 Chapter 3: JDBC Methods TeraDataSource Methods getSP_SPL() Function Syntax Returns Get the SP_SPL value. public java.lang.String getSP_SPL() TheSP_SPL value. getspl() Function Syntax This function has been deprecated. Get the value of Stored Procedure spl option. public java.lang.String getspl() Returns The value of Stored Procedure spl option. Note Use the connection URL Parameter SP_SPL described in “Making a Teradata Database Connection” on page 43. getTransactMode()/getTMODE Function Syntax Returns Get the Transaction Mode value. public java.lang.String getTransactMode() The Transaction Mode value. getTNANO() Function Syntax Returns Get the TNANO value. public java.lang.String getTNANO() The TNANO value. getTSNANO() Function Syntax Returns 272 Get the TSNANO value. public java.lang.String getTSNANO() The TSNANO value. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods TeraDataSource Methods getuser() Function Syntax Returns Get the user name used for DBS access. public java.lang.String getuser() The user name. getUSEXVIEWS() Function: Gets the USEXVIEWS value. Characteristic Description Syntax public java.lang.String Return The USEXVIEWS value is returned. setACCOUNT(String accountId) Function: Sets the accountId. Characteristic Description Syntax public void setACCOUNT(String accountId) The accountId parameter is the accountId value. This sets the name of the account to be charged. Note: The setAccount and setAccountId methods are deprecated. Use the setACCOUNT method instead. setCharSet(java.lang.String CharSet)/ setCHARSET(java.lang.String CharSet) Function Syntax Set the session character set. public void setCharSet(java.lang.String CharSet) Where parameter . . . Is . . . CharSet "ASCII", "KANJISJIS_OS" or "KANJIEUC_0U" setCOMPAT_DBS() Function Set the COMPAT_DBSvalue. Teradata Driver for the JDBC Interface User Guide 273 Chapter 3: JDBC Methods TeraDataSource Methods Syntax public void setCOMPAT_DBS(java.lang.String compatVal) Where parameter . . . Is . . . compatValue COMPAT_DBS value. setCOMPAT_GETSCHEMA() Function Syntax Set the COMPAT_GETSCHEMA value. public void setCOMPAT_SCHEMA(java.lang.String compatVal) Where parameter . . . Is . . . compatValue COMPAT_SCHEMA value. setCOMPAT_GETTABLE() Function Syntax Set the COMPAT_GETTABLE value. public void setCOMPAT_GETTABLE(java.lang.String compatVal) Where parameter . . . Is . . . compatValue GETTABLE value. setCOMPAT_ISAUTOINC() Function Syntax Set the COMPAT_ISAUTOINC value. public void setCOMPAT_ISAUTOINC(java.lang.String compatVal) Where parameter . . . Is . . . compatValue COMPAT_ISAUTOINC value. setCOMPAT_ISCURRENCY() Function Syntax 274 Set the COMPAT_ISCURRENCY value. public void setCOMPAT_ISCURRENCY(java.lang.String compatVal) Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods TeraDataSource Methods Where parameter . . . Is . . . compatValue COMPAT_ISCURRENCY value. setCOMPAT_ISDEFWRIT() Function Syntax Set the COMPAT_ISDEFWRIT value. public void setCOMPAT_ISDEFWRIT(java.lang.String compatVal) Where parameter . . . Is . . . compatValue COMPAT_ISDEFWRIT value. setCOMPAT_ISREADONLY() Function Syntax Set the COMPAT_ISREADONLY value. public void setCOMPAT_ISREADONLY(java.lang.String compatVal) Where parameter . . . Is . . . compatValue COMPAT_ISREADONLY value. setCOMPAT_ISSEARCH() Function Syntax Set the COMPAT_ISSEARCH value. public void setCOMPAT_ISSEARCH(java.lang.String compatVal) Where parameter . . . Is . . . compatValue COMPAT_ISSEARCH value. setCOMPAT_ISSIGNED() Function Syntax Set the COMPAT_ISSIGNED value. public void setCOMPAT_ISSIGNED(java.lang.String compatVal) Where parameter . . . Teradata Driver for the JDBC Interface User Guide Is . . . 275 Chapter 3: JDBC Methods TeraDataSource Methods compatValue COMPAT_ISSIGNED value. setCOMPAT_ISWRITABLE() Function Syntax Set the COMPAT_ISWRITABLE value. public void setCOMPAT_ISWRITABLE(java.lang.String compatVal) Where parameter . . . Is . . . compatValue COMPAT_ISWRITABLE value. setDatabase(java.lang.String database)/ setdatabase(java.lang.String database)/ setDATABASE(java.lang.String database) Function Syntax Set the Default Database name. This sets the name of the default database that will be set at logon time. public void setDatabase(java.lang.String database) Where parameter . . . Is . . . database name of database to access at logon. setdatasourceName(java.lang.String datasourceName) Function Syntax Set the name of this datasource. public void setdatasourceeName(java.lang.String datasour ceName) Where parameter . . . Is . . . datasourceName name of datasource to access at logon. setDBS_PORT(java.lang.String dbsport) Function Syntax 276 Set the DBS_PORT value. public void setDBSPORT(java.lang.String dbsport) Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods TeraDataSource Methods Where parameter . . . Is . . . dbsport TCP/IP port number of the Teradata Database. setdescription(java.lang.String description) Function Syntax Set the description of the DataSource. public void setdescription(java.lang.String description) Where parameter . . . Is . . . description description of DataSource. setDSName(java.lang.String DSName) Function Syntax Set the Database Server name. This sets the name of the server running the Teradata Database. public void setDSName(java.lang.String DSName) Where parameter . . . Is . . . DSName Database Server name. setENCRYPTDATA(java.lang.String encryptData) Function Syntax Set the EncryptData flag. This flag determines whether data is encrypted on this connection. public void setENCRYPTDATA(java.lang.String encryptData) Where parameter . . . Is . . . encryptData “ON” - When set to “ON”, data sent between the Teradata Driver for the JDBC Interface and the Teradata Database are encrypted. This provides greater security, although performance will be effected. “OFF” - When set to “OFF”, data sent between the Teradata Driver for the JDBC Interface and the Teradata Database are not encrypted. Teradata Driver for the JDBC Interface User Guide 277 Chapter 3: JDBC Methods TeraDataSource Methods Note The setLOGMECH(java.lang.String logMECH) method determines which encryption method will be available and whether or not Single Sign-on is supported. The setENCRYPTDATA(java.lang.String encryptData) determines whether or not data is encrypted on the connection. setFetchRows(java.lang.String FetchRows) Function Syntax Set the Fetch Rows. public void setFetchRows(java.lang.String FetchRows) Where parameter . . . Is . . . FetchRows new fetch row value. setLOB_SUPPORT(java.lang.String lobSupport) Function Syntax Set the LOB_SUPPORT value. public void setLOB_SUPPORT(java.lang.String lobSupport) Where parameter . . . Is . . . lobSupport the lobSupport value. setLOB_TEMP_TABLE(java.lang.String) Function: Sets the LOB_TEMP_TABLE value. Characteristic Description Syntax public void setLOB_TEMP_TABLE(java.lang.String lobTempTable) where the lobTempTable parameter is the tableName or databaseName.tableName used for Updatable Lobs. setLOG(java.lang.String lobSupport) Function Syntax Set the LOG value. public void setLOG(java.lang.String logValue) Where parameter . . . 278 Is . . . Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods TeraDataSource Methods logValue the LOG value, “ERROR,” “INFO” or “DEBUG.” setLOGDATA(java.lang.String LogData) Function Syntax Set the Logon Data. This value can be used to pass mechanism specific data to the mechanisms such as authorization tokens or domain/realm information. public void setLOGDATA(java.lang.String LogData) Where parameter . . . Is . . . LogData mechanism specific data to the mechanisms such as authorization tokens or domain/realm information: Teradata Method 1 - unused Teradata Method 2 - unused Kerberos - can contain Kerberos username, instance, and realm. Use is optional. LDAP - contains the Distinguished Name to be used. Note Kerberos example: [email protected]@@mypassword LDAP example: LOGDATA=’dn:cn=John Smith,cn=users,dc=corp,dc=ncr,dc=com password=secret’ setLoginTimeout(int seconds) Function Syntax Set the Login Timeout. public void setLoginTimeout(int seconds) throws java.sql.SQLException Where parameter . . . Is . . . seconds Login Timeout value. setLOGMECH(java.lang.String LogMech) Function Syntax Set the Logon Mechanism. The mechanism determines the level of security used on the connection and whether or not Single Sign-on is supported. public void setLOGMECH(java.lang.String LogMech) Where parameter . . . Teradata Driver for the JDBC Interface User Guide Is . . . 279 Chapter 3: JDBC Methods TeraDataSource Methods LogMech the mechanism to use: • • • • • TD1 - Teradata Method 1 TD2 - Teradata Method 2 KRB5 - Kerberos LDAP - Lightweight Directory Access Protocol a user defined value for proprietary mechanisms setLogWriter(java.io.PrintWriter out) Function Syntax Set the Log File name. public void setLogWriter(java.io.PrintWriter out) throws java.sql.SQLException Where parameter . . . Is . . . out log file name. setpassword(java.lang.String password) Function Syntax Set the password used for DBS access. public void setpassword(java.lang.String password) Where parameter . . . Is . . . password password for DBS user. setportNumber(java.lang.String portNumber) Function Syntax 280 This function has been deprecated. Set the port number used by the Teradata JDBC gateway. setPortNumber will log an error message, but will not throw an exception. public void setportNumber(java.lang.String portNumber) Where parameter . . . Is . . . portNumber port number used by gateway. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods TeraDataSource Methods setServerName(java.lang.String serverName) Function Syntax This function has been deprecated. Set the Teradata JDBC gateway Server name. setServerName will log an error message, but will not throw an exception. public void setServerName(java.lang.String serverName) Where parameter . . . Is . . . ServerName Server name. setSpl(java.lang.String spl) Function Syntax Note This function has been deprecated. Set the value of Stored Procedure spl option. public void setspl(java.lang.String spl) Where parameter . . . Is . . . spl "SPL" or "NOSPL". Use the connection URL Parameter SP_SPL described in “Making a Teradata Database Connection” on page 43. setSP_SPL(java.lang.String splVal) Function Syntax Set the value of Stored Procedure spl option. public void setSP_SPL(java.lang.String splVal) Where parameter . . . Is . . . splVal SPL value. seTMODE(java.lang.String TransactMode) Function Syntax Set the TMODE value. public void setTMODE(java.lang.String tmodeVal) Where parameter . . . Is . . . tmodeVal TMODE value Teradata Driver for the JDBC Interface User Guide 281 Chapter 3: JDBC Methods TeraDataSource Methods setTNANO(java.lang.String tnanoVal) Function Syntax Set the TNANO value. public void setTNANO(java.lang.String tnanoVal) Where parameter . . . Is . . . tnanoVal TNANO value setTransactMode(java.lang.String TransactMode)/ seTMODE(java.lang.String TransactMode) Function Syntax Set the Transaction Mode. public void setTransactMode(java.lang.String TransactMode) Where parameter . . . Is . . . TransactMode "ANSI", "TERA" or "DEFAULT". setTSNANO(java.lang.String tsnanoVal) Function Syntax Set the TSNANO value. public void setTSNANO(java.lang.String tsnanoVal) Where parameter . . . Is . . . tsnanoVal TSNANO value setuser(java.lang.String user) Function Syntax 282 Set the user name used for DBS access. public void setuser(java.lang.String user) Where parameter . . . Is . . . user user name for DBS access. Teradata Driver for the JDBC Interface User Guide Chapter 3: JDBC Methods TeraDataSource Methods setUseXVIEWS(java.lang.String useXviews) Function: Configures the Connection to use or not use X_views when retrieving Database Metadata. Characteristic Description Syntax public void setUSEXVIEWS(java.lang.String useXviews) where • useXviews ?ON? – DatabaseMetaData calls use X views rather than non-X views to retrieve data. This provides greater control over what information can be accessed, though the use of X views has a negative impact on performance. • useXviews ?OFF? – DatabaseMetaData calls use non-X views rather than X views to retrieve data. The setting of USEXVIEWS to OFF is the default setting for a Connection. Teradata Driver for the JDBC Interface User Guide 283 Chapter 3: JDBC Methods TeraDataSource Methods 284 Teradata Driver for the JDBC Interface User Guide APPENDIX A Supported JDBC Methods This appendix contains a synopsis of the JDBC methods supported by the Teradata Driver for the JDBC Interface. The interfaces supported include: • JDBC BLOB Interface Methods • JDBC CLOB Interface Methods • JDBC CallableStatement Methods • JDBC Connection Methods • JDBC ConnectionEvent Methods • JDBC ConnectionEventListener Methods • JDBC ConnectionPoolDataSource Methods • JDBC DatabaseMetaData Methods • JDBC DataSource Methods • JDBC DriverManager Methods • JDBC ParameterMetaData Methods • JDBC PooledConnection Methods • JDBC PreparedStatement Methods • JDBC ResultSet Methods • JDBC ResultSetMetadata Methods • JDBC Statement Methods • TeraDataSource Methods Supported Methods Note: The following tables contain lists of the interfaces implemented for the Teradata JDBC driver. Each interface implemented is contained in a separate table and listed in alphabetical order by method. • “No” in the Supported column of the table indicates that the method is not supported by the Teradata JDBC driver. These rows are bold for clarity. • “Yes” in the Supported column of the table indicates that the method is fully supported by both the Teradata JDBC driver and the Teradata Database • “Yes*” in the Supported column of the table indicates that the method is supported but has no effect Teradata Driver for the JDBC Interface User Guide 285 Appendix A: Supported JDBC Methods Supported Methods • “Yes**” in the Supported column of the table indicates that the method is supported by the Teradata Driver for the JDBC Interface when connected to Teradata Database V2R6.2. • “Yes***” in the Supported column of the table indicates that the method is supported by the Teradata Driver for the JDBC Interface, but is not supported by the Teradata Database. JDBC BLOB Interface Methods Table 29: JDBC BLOB Interface Methods BLOB Methods Supported getBinaryStream() Yes getBytes(long pos, int length) Yes setBytes(long pos, byte[] bytes) Yes setBytes(long pos, byte[] bytes, int offset, int len) Yes length () Yes setBinaryStream(long pos) Yes position(Blob pattern, long start) No position(byte[] pattern, long start) No truncate(long len) Yes JDBC CLOB Interface Methods Table 30: JDBC CLOB Interface Methods 286 CLOB Methods Supported getAsciiStream() Yes getCharacterStream() Yes getSubString(long pos, int length) Yes setString(long pos, String str) Yes setString(long pos, String str, int offset, int len) Yes length() Yes setAsciiStream(long pos) Yes position(Clob searchstr, long start) No position(String searchstr, long start) No setCharacterStream(long pos) Yes truncate(long len) Yes Teradata Driver for the JDBC Interface User Guide Appendix A: Supported JDBC Methods Supported Methods JDBC CallableStatement Methods Table 31: JDBC CallableStatement Methods CallableStatement Methods Supported getArray(int i) (JDBC 2.0) No getBigDecimal(int parameterIndex) (JDBC 2.0) Yes getBigDecimal(int parameterIndex, int scale) [DEPRECATED] (JDBC 2.0) Yes getBlob(int i) (JDBC 2.0) Yes getBoolean(int parameterIndex) Yes getByte(int parameterIndex) Yes getBytes(int parameterIndex) Yes getClob(int i) Yes getDate(int parameterIndex) Yes getDate(int parameterIndex, Calendar cal) (JDBC 2.0) Yes getDouble(int parameterIndex) Yes getFloat(int parameterIndex) Yes getInt(int parameterIndex) Yes getLong(int parameterIndex) Yes getObject(int parameterIndex) Yes getObject(int i, Map map) (JDBC 2.0) Yes getRef(int i) (JDBC 2.0) No getShort(int parameterIndex) Yes getString(int parameterIndex) Yes getTime(int parameterIndex) Yes getTime(int parameterIndex, Calendar cal) (JDBC 2.0) Yes getTimestamp(int parameterIndex) Yes getTimestamp(int parameterIndex, Calendar cal) (JDBC 2.0) Yes registerOutParameter(int parameterIndex, int sqlType) Yes registerOutParameter(int parameterIndex, int sqlType, int scale) Yes registerOutParameter(int parameterIndex, int sqlType, String typeName) Yes*** wasNull() Yes Teradata Driver for the JDBC Interface User Guide 287 Appendix A: Supported JDBC Methods Supported Methods JDBC Connection Methods Table 32: JDBC Connection Methods 288 Connection Methods Supported clearWarnings() Yes close() Yes commit() Yes createStatement() Yes createStatement(int resultSetType, int resultSetConcurrency) (JDBC 2.0) Yes getAutoCommit() Yes getCatalog() Yes*** getHoldability() Yes getMetaData() Yes getTransactionIsolation() Yes getTypeMap() Yes getWarnings() Yes isClosed() Yes isReadOnly() (always returns False) Yes*** nativeSQL(String sql) Yes prepareCall(String sql) Yes prepareCall(String sql, int resultSetType, int resultSetConcurrency) (JDBC 2.0) Yes prepareStatement(String sql) Yes prepareStatement(String sql, int autoGeneratedKeys) Yes prepareStatement(String sql, int[ ] columnIndexes) Yes prepareStatement(String sql, String[ ] columnNames) Yes prepareStatement(String sql, int resultSetType, int resultSetConcurrency) (JDBC 2.0) Yes rollback() Yes setAutoCommit(boolean autoCommit) Yes setCatalog(String catalog) Yes*** setReadOnly(boolean readonly) No setTransactionIsolation(int level) Yes setTypeMap(Map map) Yes Teradata Driver for the JDBC Interface User Guide Appendix A: Supported JDBC Methods Supported Methods JDBC ConnectionEvent Methods Table 33: JDBC ConnectionEvent Methods ConnectionEvent Methods Supported ConnectionEvent(PooledConnection con) Yes ConnectionEvent(PooledConnection con, SQLException ex) Yes getSQLException() Yes JDBC ConnectionEventListener Methods Table 34: JDBC ConnectionEventListener Methods ConnectionEvent Listener Methods Supported connectionClosed(ConnectionEvent event) Yes connectionErrorOccurred(ConnectionEvent event) Yes JDBC ConnectionPoolDataSource Methods Table 35: JDBC ConnectionPoolDataSource Methods ConnectionPoolDataSource Methods Supported getLoginTimeout() Yes getLogWriter() Yes getMaxStatements() Yes getPooledConnection() Yes getPooledConnection(String username, String password) Yes setLoginTimeout(int seconds) Yes* setLogWriter(PrintWriter out) Yes JDBC DatabaseMetaData Methods Table 36: JDBC DatabaseMetaData Methods DatabaseMetaData Methods Supported allProceduresAreCallable() Yes allTablesAreSelectable() Yes dataDefinitionCausesTransactionCommit() Yes Teradata Driver for the JDBC Interface User Guide 289 Appendix A: Supported JDBC Methods Supported Methods Table 36: JDBC DatabaseMetaData Methods (continued) DatabaseMetaData Methods Supported dataDefinitionIgnoredInTransactions() Yes deletesAreDetected(int type) (JDBC 2.0) Yes doesMaxRowSizeIncludeBlobs() Yes getAttributes(String catalog, String schemaPattern, String typeNamePattern, String attributeNamePattern) (JDBC 2.0) Yes getBestRowIdentifier(String catalog, String schema, String table, int scope, boolean nullable) Yes getCatalogs() Yes*** getCatalogSeparator() Yes*** getCatalogTerm() Yes*** getColumnPrivileges(String catalog, String schema, String table, String columnNamePattern) Yes getColumns(String catalog, String schemaPattern, String tableNamePattern, String columnNamePattern) Yes getConnection() (JDBC 2.0) Yes getCrossReference(String primaryCatalog, String primarySchemaPattern, String Yes primaryTable, String foreignCatalog, String foreignSchema, String foreignTable) 290 getDatabaseMajorVersion() Yes getDatabaseMinorVersion() Yes getDatabaseProductName() Yes getDatabaseProductVersion() Yes getDefaultTransactionIsolation() Yes getDriverMajorVersion() Yes getDriverMinorVersion() Yes getDriverName() Yes getDriverVersion() Yes getExportedKeys(String catalog, String schema, String table) Yes getExtraNameCharacters() Yes getIdentifierQuoteString() Yes getImportedKeys(String catalog, String schema, String table) Yes getIndexInfo(String catalog, String schema, String table, boolean unique, boolean approximate) Yes Teradata Driver for the JDBC Interface User Guide Appendix A: Supported JDBC Methods Supported Methods Table 36: JDBC DatabaseMetaData Methods (continued) DatabaseMetaData Methods Supported getMaxBinaryLiteralLength() Yes getMaxCatalogNameLength() Yes*** getMaxCharLiteralLength() Yes getMaxColumnNameLength() Yes getMaxColumnsInGroupBy() Yes getMaxColumnsInIndex() Yes getMaxColumnsInOrderBy() Yes getMaxColumnsInSelect() Yes getMaxColumnsInTable() Yes getMaxConnections() Yes getMaxCursorNameLength() Yes getMaxIndexLength() Yes getMaxProcedureNameLength() Yes getMaxRowSize() Yes getMaxSchemaNameLength() Yes getMaxStatementLength() Yes getMaxStatements() Yes getMaxTableNameLength() Yes getMaxTablesInSelect() Yes getMaxUserNameLength() Yes getNumericFunctions() Yes getPrimaryKeys(String catalog, String schema, String table) Yes getProcedureColumns(String catalog, String schemaPattern, String procedureNamePattern, String columnNamePattern) Yes getProcedures(String catalog, String schemaPattern, String procedureNamePattern) Yes getProcedureTerm() Yes getResultSetHoldability() Yes getSchemas() Yes getSchemaTerm() Yes getSearchStringEscape() Yes Teradata Driver for the JDBC Interface User Guide 291 Appendix A: Supported JDBC Methods Supported Methods Table 36: JDBC DatabaseMetaData Methods (continued) 292 DatabaseMetaData Methods Supported getSQLKeywords() Yes getSQLStateType() Yes getStringFunctions() Yes getSuperTables(String, String, String) Yes getSuperTypes(String, String, String) Yes getSystemFunctions() Yes getTablePrivileges(String catalog, String schemaPattern, String tableNamePattern) Yes getTables(String catalog, String schemaPattern, String tableNamePattern, String[] types) Yes getTableTypes() Yes getTimeDateFunctions() Yes getTypeInfo() Yes getUDTs(String catalog, String schemaPattern, String typeNamePattern, int[] types) (JDBC 2.0) Yes getURL() Yes getUserName() Yes getVersionColumns(String catalog, String schema, String table) Yes insertsAreDetected(int type) (JDBC 2.0) Yes isCatalogAtStart() Yes*** isReadOnly() Yes locatorsUpdateCopy() Yes nullPlusNonNullIsNull() Yes nullsAreSortedAtEnd() Yes nullsAreSortedAtStart() Yes nullsAreSortedHigh() Yes nullsAreSortedLow() Yes othersDeletesAreVisible(int type) (JDBC 2.0) Yes*** othersInsertsAreVisible(int type) (JDBC 2.0) Yes*** othersUpdatesAreVisible(int type) (JDBC 2.0) Yes*** ownDeletesAreVisible(int type) (JDBC 2.0) Yes*** Teradata Driver for the JDBC Interface User Guide Appendix A: Supported JDBC Methods Supported Methods Table 36: JDBC DatabaseMetaData Methods (continued) DatabaseMetaData Methods Supported ownInsertsAreVisible(int type) (JDBC 2.0) Yes*** ownUpdatesAreVisible(int type) (JDBC 2.0) Yes*** storesLowerCaseIdentifiers() Yes storesLowerCaseQuotedIdentifiers() Yes storesMixedCaseIdentifiers() Yes storesMixedCaseQuotedIdentifiers() Yes storesUpperCaseIdentifiers() Yes storesUpperCaseQuotedIdentifiers() Yes supportsAlterTableWithAddColumn() Yes supportsAlterTableWithDropColumn() Yes supportsANSI92EntryLevelSQL() Yes supportsANSI92FullSQL() Yes supportsANSI92IntermediateSQL() Yes supportsBatchUpdates() (JDBC 2.0) Yes supportsCatalogsInDataManipulation() Yes supportsCatalogsInIndexDefinitions() Yes supportsCatalogsInPrivilegeDefinitions() Yes supportsCatalogsInProcedureCalls() Yes supportsCatalogsInTableDefinitions() Yes supportsColumnAliasing() Yes supportsConvert() Yes supportsConvert(int fromType, toType) Yes supportsCoreSQLGrammar() Yes supportsCorrelatedSubqueries() Yes supportsDataDefinitionAndDataManipulationTransactions() Yes supportsDataManipulationTransactionsOnly() Yes supportsDifferentTableCorrelationNames() Yes supportsExpressionsInOrderBy() Yes supportsExtendedSQLGrammar() Yes supportsFullOuterJoins() Yes Teradata Driver for the JDBC Interface User Guide 293 Appendix A: Supported JDBC Methods Supported Methods Table 36: JDBC DatabaseMetaData Methods (continued) 294 DatabaseMetaData Methods Supported supportsGeneratedKeys() Yes supportsGroupBy() Yes supportsGroupByBeyondSelect() Yes supportsGroupByUnrelated() Yes supportsIntegrityEnhancementFacility() Yes supportsLikeEscapeClause() Yes supportsLimitedOuterJoins() Yes supportsMinimumSQLGrammar() Yes supportsMixedCaseIdentifiers() Yes supportsMixedCaseQuotedIdentifiers() Yes supportsMultipleResultSets() Yes supportsMultipleTransactions() Yes supportsNonNullableColumns() Yes supportsOpenCursorsAcrossCommit() Yes supportsOpenCursorsAcrossRollback() Yes supportsOpenStatementsAcrossCommit() Yes supportsOpenStatementsAcrossRollback() Yes supportsOrderByUnrelated() Yes supportsOuterJoins() Yes supportsPositionedDelete() Yes supportsPositionedUpdate() Yes supportsResultSetConcurrency(int type, int concurrency) (JDBC 2.0) Yes supportsResultSetHoldability(int holdability) (JDBC 2.0) Yes supportsResultSetType(int type) (JDBC 2.0) Yes supportsSchemasInDataManipulation() Yes supportsSchemasInIndexDefinitions() Yes supportsSchemasInPrivilegeDefinitions() Yes supportsSchemasInProcedureCalls() Yes supportsSchemasInTableDefinitions() Yes supportsSelectForUpdate() Yes Teradata Driver for the JDBC Interface User Guide Appendix A: Supported JDBC Methods Supported Methods Table 36: JDBC DatabaseMetaData Methods (continued) DatabaseMetaData Methods Supported supportsStoredProcedures() Yes supportsSubqueriesInComparisons() Yes supportsSubqueriesInExists() Yes supportsSubqueriesInIns() Yes supportsSubqueriesInQuantifieds() Yes supportsTableCorrelationNames() Yes supportsTransactionIsolationLevel(int level) Yes supportsTransactions() Yes supportsUnion() Yes supportsUnionAll() Yes updatesAreDetected(int type) (JDBC 2.0) Yes*** usesLocalFilePerTable() Yes usesLocalFiles() Yes JDBC DataSource Methods Table 37: JDBC DataSource Methods DataSource Methods Supported getConnection() Yes getConnection(String username, String password) Yes getLoginTimeout() Yes getLogWriter() Yes setLoginTimeout(int seconds) Yes* setLogWriter(PrintWriter out) Yes JDBC DriverManager Methods Table 38: JDBC DriverManager Methods DriverManager Methods Supported deregisterDriver(Driver driver) Yes getConnection(String url) Yes Teradata Driver for the JDBC Interface User Guide 295 Appendix A: Supported JDBC Methods Supported Methods Table 38: JDBC DriverManager Methods (continued) DriverManager Methods Supported getConnection(String url, Properties info) Yes getConnection(String url, String user, String password) Yes getDriver(String url) Yes getDrivers() Yes getLoginTimeout() Yes getLogStream() [DEPRECATED] Yes getLogWriter() No printIn(String message) Yes registerDriver(Driver driver) Yes setLoginTimeout(int seconds) Yes* setLogStream(PrintStream out) [DEPRECATED] Yes setLogWriter(PrintWriter out) No JDBC ParameterMetaData Methods Table 39: JDBC ParameterMetadata Methods 296 ParameterMetadata Methods Supported getParameterClassName(int param) (JDBC 3.0) Yes getParameterCount() (JDBC 3.0) Yes getParameterType(int param) (JDBC 3.0) Yes getParameterMode(int param) (JDBC 3.0) Yes getParameterTypeName(int param) (JDBC 3.0) Yes getPrecision(int param) (JDBC 3.0) Yes getScale(int param) (JDBC 3.0) Yes isNullable(int param) (JDBC 3.0) Yes isSigned(int param) (JDBC 3.0) Yes Teradata Driver for the JDBC Interface User Guide Appendix A: Supported JDBC Methods Supported Methods JDBC PooledConnection Methods Table 40: JDBC PooledConnection Methods PooledConnection Methods Supported addConnectionEventListener(ConnectionEventListener listener) Yes close() Yes getConnection() Yes removeConnectionEventListener(ConnectionEventListener listener) Yes JDBC PreparedStatement Methods Table 41: JDBC PreparedStatement Methods PreparedStatement Methods Supported addBatch() (JDBC 2.0) Yes clearParameters() Yes execute() Yes executeQuery() Yes executeUpdate() Yes getMetaData() (JDBC 2.0) Yes getParameterMetaData() (JDBC 3.0) Yes setArray(int i, Array x) No setAsciiStream(int parameterIndex, InputStream x, int length) Yes setBigDecimal(int parameterIndex, BigDecimal x) Yes setBinaryStream(int parameterIndex, InputStream x, int length) Yes setBlob(int i, Blob x) (JDBC 2.0) Yes setBoolean(int parameterIndex, boolean x) Yes setByte(int parameterIndex, byte x) Yes setBytes(int parameterIndex, byte[] x) Yes setCharacterStream(int parameterIndex, Reader reader, int length) (JDBC 2.0) Yes setClob(int i, Clob x) (JDBC 2.0) Yes setDate(int parameterIndex, Date x) Yes setDate(int parameterIndex, Date x, Calendar cal) (JDBC 2.0) Yes setDouble(int parameterIndex, Double x) Yes Teradata Driver for the JDBC Interface User Guide 297 Appendix A: Supported JDBC Methods Supported Methods Table 41: JDBC PreparedStatement Methods (continued) PreparedStatement Methods Supported setFloat(int parameterIndex, float x) Yes setInt(int parameterIndex, int x) Yes setLong(int parameterIndex, long x) Yes setNull(int parameterIndex, int sqlType) Yes setNull(int paramIndex, int sqlType, String typeName) (JDBC 2.0) Yes setObject(int parameterIndex, Object x) Yes setObject(int parameterIndex, Object x, int targetSqlType) Yes setObject(int parameterIndex, Object x, int targetSqlType, int scale) Yes setRef(int i, Ref x) (JDBC 2.0) No setShort(int parameterIndex, Short x) Yes setString(int parameterIndex, String x) Yes setTime(int parameterIndex, Time x) Yes setTime(int parameterIndex, Time x, Calendar cal) (JDBC 2.0) Yes setTimestamp(int parameterIndex, Timestamp x) Yes setTimestamp(int parameterIndex, Timestamp x, Calendar cal) (JDBC 2.0) Yes setUnicodeStream(int parameterIndex, InputStream x, int length) [DEPRECATED] Yes JDBC ResultSetMetadata Methods Table 42: JDBC ResultSetMetadata Methods 298 ResultSetMetadata Methods Supported getCatalogName(int column) Yes** getColumnClassName(int column) (JDBC 2.0) Yes getColumnCount() Yes getColumnDisplaySize(int column) Yes getColumnLabel(int column) Yes getColumnName(int column) Yes getColumnType(int column) Yes getColumnTypeName(int column) Yes getPrecision(int column) Yes Teradata Driver for the JDBC Interface User Guide Appendix A: Supported JDBC Methods Supported Methods Table 42: JDBC ResultSetMetadata Methods (continued) ResultSetMetadata Methods Supported getScale(int column) Yes getSchemaName(int column) Yes** getTableName(int column) Yes** isAutoIncrement(int column) Yes** isCaseSensitive(int column) Yes** isCurrency(int column) Yes** isDefinitelyWritable(int column) Yes** isNullable(int column) Yes isReadOnly(int column) Yes** isSearchable(int column) Yes** isSigned(int) column Yes** isWritable(int column) Yes** JDBC ResultSet Methods Table 43: JDBC ResultSet Methods ResultSet Methods Supported absolute(int row) (JDBC 2.0) Yes afterLast() (JDBC 2.0) Yes beforeFirst() (JDBC 2.0) Yes cancelRowUpdates() (JDBC 2.0) Yes clearWarnings() Yes close() Yes deleteRow() (JDBC 2.0) Yes findColumn(String columnName) Yes first() (JDBC 2.0) Yes getArray(int i) (JDBC 2.0) No getArray(String columnName) (JDBC 2.0) No getAsciiStream(int columnIndex) Yes getAsciiStream(String columnName) Yes getBigDecimal(int columnIndex) Yes Teradata Driver for the JDBC Interface User Guide 299 Appendix A: Supported JDBC Methods Supported Methods Table 43: JDBC ResultSet Methods (continued) 300 ResultSet Methods Supported getBigDecimal(int columnIndex, int scale) [Deprecated] Yes getBigDecimal(String columnName) Yes getBigDecimal(String columnName, int scale) [Deprecated] Yes getBinaryStream(int columnIndex) Yes getBinaryStream(String columnName) Yes getBlob(int i) (JDBC 2.0) Yes getBlob(String columnName) (JDBC 2.0) Yes getBoolean(int columnIndex) Yes getBoolean(String columnName) Yes getByte(int columnIndex) Yes getByte(String columnName) Yes getBytes(int columnIndex) Yes getBytes(String columnName) Yes getCharacterStream(int columnIndex) (JDBC 2.0) Yes getCharacterStream(String columnName) (JDBC 2.0) Yes getClob(int i) (JDBC 2.0) Yes getClob(String columnName) (JDBC 2.0) Yes getConcurrency() (JDBC 2.0) Yes getCursorName() No getDate(int columnIndex) Yes getDate(String columnName) Yes getDate(int columnIndex, Calendar cal) (JDBC 2.0) Yes getDate(String columnName, Calendar cal) (JDBC 2.0) Yes getDouble(int columnIndex) Yes getDouble(String columnName) Yes getFetchDirection() (JDBC 2.0) Yes getFetchSize() (JDBC 2.0) Yes getFloat(int columnIndex) Yes getFloat(String columnName) Yes getInt(int columnIndex) Yes Teradata Driver for the JDBC Interface User Guide Appendix A: Supported JDBC Methods Supported Methods Table 43: JDBC ResultSet Methods (continued) ResultSet Methods Supported getInt(String columnName) Yes getLong(int columnIndex) Yes getLong(String columnName) Yes getMetaData() Yes getObject(int columnIndex) Yes getObject(int i, Map map) (JDBC 2.0) Yes getObject(String columnName) Yes getObject(String columnName, Map map) (JDBC 2.0) Yes getRef(int i) (JDBC 2.0) No getRef(String columnName) (JDBC 2.0) No getRow() (JDBC 2.0) Yes getShort(int columnIndex) Yes getShort(String columnName) Yes getStatement() (JDBC 2.0) Yes getString(int columnIndex) Yes getString(String columnName) Yes getTime(int columnIndex) Yes getTime(int columnIndex, Calendar cal) Yes getTime(String columnName) Yes getTime(String columnName, Calendar cal) Yes getTimeStamp(int columnIndex) Yes getTimeStamp(int columnIndex, Calendar cal) Yes getTimeStamp(String columnName) Yes getTimeStamp(String columnName, Calendar cal) Yes getType() (JDBC 2.0) Yes getUnicodeStream(int columnIndex)[Deprecated] Yes getUnicodeStream(String columnName)[Deprecated] Yes getWarnings() Yes insertRow() Yes isAfterLast() Yes Teradata Driver for the JDBC Interface User Guide 301 Appendix A: Supported JDBC Methods Supported Methods Table 43: JDBC ResultSet Methods (continued) ResultSet Methods Supported isBeforeFirst() Yes isFirst() Yes isLast() Yes last() Yes moveToCurrentRow() Yes moveToInsertRow() Yes next() Yes previous() (JDBC 2.0) Yes refreshRow() (JDBC 2.0) Yes relative(int rows) (JDBC 2.0) Yes rowDeleted() (JDBC 2.0) Yes rowInserted() (JDBC 2.0) Yes rowUpdated() (JDBC 2.0) Yes setFetchDirection(int direction) (JDBC 2.0) Yes*** setFetchSize(int rows) (JDBC 2.0) Yes*** updateArray(int columnIndex, Array x) (JDBC 3.0) No updateArray(String columnName, Array x) (JDBC 3.0) No updateAsciiStream(int columnIndex, InputStream x, int length) (JDBC 2.0) Yes updateAsciiStream(String columnName, InputStream x, int length) (JDBC 2.0) Yes 302 updateBigDecimal(int columnIndex, BigDecimal x) (JDBC 2.0) Yes updateBigDecimal(String columnName, BigDecimal x) (JDBC 2.0) Yes updateBinaryStream(int columnIndex, InputStream x, int length) (JDBC 2.0) Yes updateBinaryStream(String columnName, InputStream x, int length) (JDBC 2.0) Yes updateBlob(int columnIndex, Blob x) (JDBC 3.0) Yes updateBlob(String columnName, Blob x) (JDBC 3.0) Yes updateBoolean(int columnIndex, boolean x) (JDBC 2.0) No updateBoolean(String columnName, boolean x) (JDBC 2.0) No updateByte(int columnIndex, byte x) (JDBC 2.0) Yes updateByte(String columnName, byte x) (JDBC 2.0) Yes Teradata Driver for the JDBC Interface User Guide Appendix A: Supported JDBC Methods Supported Methods Table 43: JDBC ResultSet Methods (continued) ResultSet Methods Supported updateBytes(int columnIndex, byte[] x) (JDBC 2.0) Yes updateBytes(String columnName, byte[] x) Yes updateCharacterStream(int columnIndex, Reader x, int length) (JDBC 2.0) Yes updateCharacterStream(String columnName, Reader x, int length) (JDBC 2.0) Yes updateClob(int columnIndex, Clob x) (JDBC 3.0) Yes updateClob(String columnName, Clob x) (JDBC 3.0) Yes updateDate(int columnIndex, Date x) (JDBC 2.0) Yes updateDate(String columnName, Date x) (JDBC 2.0) Yes updateDouble(int columnIndex, double x) (JDBC 2.0) Yes updateDouble(String columnName, double x) (JDBC 2.0) Yes updateFloat(int columnIndex, float x) (JDBC 2.0) Yes updateFloat(String columnName, float x) (JDBC 2.0) Yes updateInt(int columnIndex, int x) (JDBC 2.0) Yes updateInt(String columnName, int x) (JDBC 2.0) Yes updateLong(int columnIndex, long x) (JDBC 2.0) Yes updateLong(String columnName, long x) (JDBC 2.0) Yes updateNull(int columnIndex) (JDBC 2.0) Yes updateNull(String columnName) (JDBC 2.0) Yes updateObject(int columnIndex, Object x) (JDBC 2.0) Yes updateObject(int columnIndex, Object x, int scale) (JDBC 2.0) Yes updateObject(String columnName, Object x) (JDBC 2.0) Yes updateObject(String columnName, Object x, int scale) Yes updateRef(int columnIndex, Ref x) (JDBC 3.0) No updateRef(String columnName, Ref x) (JDBC 3.0) No updateRow() (JDBC 2.0) Yes updateShort(int columnIndex, short x) (JDBC 2.0) Yes updateShort(String columnName, short x) (JDBC 2.0) Yes updateString(int columnIndex, String x) (JDBC 2.0) Yes updateString(String columnName, String x) (JDBC 2.0) Yes updateTime(int columnIndex, Time x) (JDBC 2.0) Yes Teradata Driver for the JDBC Interface User Guide 303 Appendix A: Supported JDBC Methods Supported Methods Table 43: JDBC ResultSet Methods (continued) ResultSet Methods Supported updateTime(String columnName, Time x) (JDBC 2.0) Yes updateTimestamp(int columnIndex, Timestamp x) (JDBC 2.0) Yes updateTimestamp(String columnName, Timestamp x) (JDBC 2.0) Yes wasNull() Yes JDBC Statement Methods Table 44: JDBC Statement Methods 304 Statement Methods Supported addBatch(String sql) (JDBC 2.0) Yes cancel() Yes clearBatch() (JDBC 2.0) Yes clearWarnings() Yes close() Yes execute(String sql) Yes execute(String sql, int autoGeneratedKeys) Yes execute(String sql, int[] columnIndexes) Yes execute(String sql, String[] columnNames) Yes executeBatch() (JDBC 2.0) Yes executeQuery(String sql) Yes executeUpdate(String sql) Yes executeUpdate(String sql, int autoGeneratedKeys) Yes executeUpdate(String sql, int[] columnIndexes) Yes executeUpdate(String sql, String[] columnNames) Yes getConnection() (JDBC 2.0) Yes getFetchDirection() (JDBC 2.0) Yes getFetchSize() (JDBC 2.0) Yes getGeneratedKeys() Yes getMaxFieldSize() Yes getMaxRows() Yes getMoreResults() Yes Teradata Driver for the JDBC Interface User Guide Appendix A: Supported JDBC Methods Supported Methods Table 44: JDBC Statement Methods (continued) Statement Methods Supported getMoreResults(int current) Yes getQueryTimeout() Yes getResultSet() Yes getResultSetConcurrency() (JDBC 2.0) Yes getResultSetHoldability() Yes getResultSetType() (JDBC 2.0) Yes getUpdateCount() Yes getWarnings() Yes setCursorName(String name) No setEscapeProcessing(boolean enable) Yes setFetchDirection(int direction) (JDBC 2.0) Yes*** setFetchSize(int rows) (JDBC 2.0) Yes*** setMaxFieldSize(int max) Yes setMaxRows(int max) Yes setQueryTimeout(int seconds) Yes TeraDataSource Methods Table 45: TeraDataSource Methods TeraDataSource Methods Supported getACCOUNT() Yes getCharSet()/getCHARSET() Yes getCOMPAT_DBS() Yes getCOMPAT_GETSCHEMA() Yes getCOMPAT_GETTABLE() Yes getCOMPAT_ISAUTOINC() Yes getCOMPAT_ISCURRENCY() Yes getCOMPAT_ISDEFWRIT() Yes getCOMPAT_ISREADONLY() Yes getCOMPAT_ISSEARCH() Yes getCOMPAT_ISSIGNED() Yes Teradata Driver for the JDBC Interface User Guide 305 Appendix A: Supported JDBC Methods Supported Methods Table 45: TeraDataSource Methods (continued) 306 TeraDataSource Methods Supported getCOMPAT_ISWRITABLE() Yes getConnection() Yes getConnection(java.lang.String username, java.lang.String password) Yes getDatabase()/getdatabase()/getDATABASE() Yes getdatasourceName() Yes getDBS_PORT() Yes getdebugStr() (removed) No getdescription() Yes getDSName() Yes getENCRYPTDATA Yes getFetchRows() Yes getLOB_SUPPORT() Yes getLOB_TEMP_TABLE() Yes getLOG() Yes getLoginTimeout() Yes getLOGDATA Yes getLOGMECH() Yes getLogWriter() Yes getpassword() Yes getPortnumber() (deprecated) No getReference() Yes getServerName() (deprecated) No getSP_SPL() Yes getspl() Deprecated getTransactMode()/getTMODE() Yes getTMODE() (incorporated above) Yes getTNANO() Yes getTSNANO() Yes getuser() Yes getUSEXVIEWS() Yes Teradata Driver for the JDBC Interface User Guide Appendix A: Supported JDBC Methods Supported Methods Table 45: TeraDataSource Methods (continued) TeraDataSource Methods Supported setACCOUNT(String accountId) Yes setCharSet(java.lang.String CharSet)/setCHARSET(java.lang.String CharSet) Yes setCOMPAT_DBS(java.lang.String compatVal) Yes setCOMPAT_GETSCHEMA(java.lang.String compatVal) Yes setCOMPAT_GETTABLE(java.lang.String compatVal) Yes setCOMPAT_ISAUTINC(java.lang.String compatVal) Yes setCOMPAT_ISCURRENCY(java.lang.String compatVal) Yes setCOMPAT_ISDEFWRIT(java.lang.String compatVal) Yes setCOMPAT_ISREADONLY(java.lang.String compatVal) Yes setCOMPAT_ISSEARCH(java.lang.String compatVal) Yes setCOMPAT_ISSIGNED(java.lang.String compatVal) Yes setCOMPAT_ISWRITABLE(java.lang.String compatVal) Yes setDatabase(java.lang.String database)/setdatabase(java.lang.String database)/ setDATABASE(java.lang.String database) Yes setdatasourceName(java.lang.String datasourceName) Yes setDBS_PORT(java.lang.String dbsport) Yes setdebugStr(java.lang.String debugStr) (removed) No setdescription(java.lang.Sting description) Yes setDSName(java.lang.String DSName) Yes setENCRYPTDATA(java.lang.String encryptdata) Yes setFetchRows(java.lang.String FetchRows) Yes setLOB_SUPPORT(java.lang.String lobSupport) Yes setLOB_TEMP_TABLE(java.lang.String lobTempTable) Yes setLOG(java.lang.String logValue) Yes setLOGDATA(java.lang.String LogData) Yes setLoginTimeout(int seconds) Yes setLOGMECH(java.lang.String LogMech) Yes setLogWriter(java.io.PrintWriter out) Yes setpassword(java.lang.Sting password) Yes setportNumber(java.lang.Sting portNumber) (deprecated) No Teradata Driver for the JDBC Interface User Guide 307 Appendix A: Supported JDBC Methods Supported Methods Table 45: TeraDataSource Methods (continued) 308 TeraDataSource Methods Supported setServerName(java.lang.String serverName) (deprecated) No setSP_SPL(java.lang.String splVal) Yes setSpl(java.lang.String spl) Deprecated setTransactMode(java.lang.String TransactMode)/ setTMODE(java.lang.String TransactMode) Yes setTMODE(java.lang.String tmodeVal) Yes setTNANO(java.lang.String tnanoVal) Yes setTSNANO(java.lang.String tsnanoVal) Yes setuser(java.lang.String user) Yes setUSEXVIEWS() added Yes Teradata Driver for the JDBC Interface User Guide APPENDIX B Troubleshooting This appendix provides information for troubleshooting the following operating system and client software problems associated with Teradata Driver for the JDBC Interface installation: • Invalid UserID, Password, or Account • Numeric Data Truncation • Character Export Width • BigDecimal Behavior for toString When Running on J2SE 5.0 • Transaction Isolation, Concurrency, and Deadlock • Large Object Interface • 1 MB SQL • Multiple Sessions • Application Errors • Checking the Environment Parameters • Troubleshooting COP Discovery • Improving Performance • Java HotSpot Server Virtual Machine Error on Linux Platform • Troubleshooting Security • Troubleshooting JDBC FastLoad • Troubleshooting JDBC Monitor Note: In troubleshooting an installation, note that: • A problem may affect more than one area • There could be more than one problem Invalid UserID, Password, or Account Log on using EBCDIC variants as Teradata Session character sets. One exception is, if the UserID, Password, or Account is in the Kanji character set, the logon fails, and the following error message is returned: Error 8017 - “The UserId, Password or Account is invalid”. Teradata Driver for the JDBC Interface User Guide 309 Appendix B: Troubleshooting Numeric Data Truncation Numeric Data Truncation Teradata Database V2R6.2 introduced support for the SQL data type BIGINT (64-bit integer) and introduced the Large Decimal feature, which expands the maximum precision for the DECIMAL data type to DECIMAL(38). Teradata Database V2R6.1 and earlier releases are limited to a maximum precision of DECIMAL(18). Maximum precision varies by Teradata Database release. This affects how numeric data is handled in the Teradata Driver for the JDBC Interface. If Large Decimal is not supported, the maximum precision for BigDecimal is 18. If Large Decimal is supported, the maximum precision value is 38. The Teradata Driver for JDBC Interface modification allows the PreparedStatement.setBigDecimal method to throw a DataTruncation exception for BigDecimal values that have precision values greater than the maximum precision. When the PreparedStatement setBigDecimal method is used to bind multiple values to a parameter, the Teradata Driver for the JDBC Interface determines the largest number of integral digits bound to the parameter, and then the fractional digits for each of the values is rounded as necessary to fit within the Teradata Database limit of maximum precision for a DECIMAL value. The method PreparedStatement.setLong in the Teradata Driver for the JDBC Interface throws a DataTruncation exception if the maximum precision value is greater than 18 and the SQL data type BIGINT is not supported for the current database. Character Export Width Retrieving fixed character fields (for example, C01 CHAR(10)) utilizing the UTF8 session character set might result in padded strings. This is due to the database export factor utilized when translating characters to the session character set. The recommended workaround is to cast the char field to a varchar. For example: • Original SQL SELECT col1, col2 • FROM myTable Using cast SELECT CAST(col1 AS VARCHAR(10)), CAST (col2 AS VARCHAR(10)) FROM myTable 310 Teradata Driver for the JDBC Interface User Guide Appendix B: Troubleshooting BigDecimal Behavior for toString When Running on J2SE 5.0 BigDecimal Behavior for toString When Running on J2SE 5.0 The BigDecimal toString method in Java 2 Platform, Standard Edition (J2SE) 1.4.2 uses a digit-to-character mapping for the representation of a BigDecimal. With J2SE 5.0, the BigDecimal toString method returns a string representation of a BigDecimal using scientific notation if the number being represented has a negative, or the adjusted exponent is less than -6. The JavaDoc for BigDecimal on Sun's Java Technology web site has more detailed information on the differences between J2SE 5.0 and J2SE 1.4.2 for BigDecimal. The Sun web site is located at: http://www.java.sun.com/products Transaction Isolation, Concurrency, and Deadlock Create and Drop The following error may be seen when creating or dropping a database object, such as a table or stored procedure. It will include an error code of 2631 and an SQL state of “40001”, which indicates that this is a retryable error: com.ncr.teradata.jdbc_4.util.JDBCException: [NCR] [Teradata DBMS]: Transaction ABORTed due to deadlock. If this error occurs, the application can choose to wait a short time and then resubmit the failed create or drop operation. JDBC FastLoad The following error may be seen when using JDBC FastLoad and calling a PreparedStatement setter method. It will include an error code of 2631 and an SQL state of “40001”, which indicates that this is a retryable error: com.ncr.teradata.jdbc_4.util.JDBCException: [NCR] [Teradata DBMS]: Transaction ABORTed due to deadlock If this error occurs, the application can choose to wait a short time and then call the PreparedStatement setter method again. Note that error 2631 may be in a chain of exceptions; it therefore is necessary to walk down the chain of exceptions to get to error 2631. Transaction Isolation A potential deadlock condition can occur with two separate applications, or a single application using two threads, with each thread or application having its own JDBC connection to the Teradata Database. Teradata Driver for the JDBC Interface User Guide 311 Appendix B: Troubleshooting Large Object Interface The problem occurs when one connection is inserting data into a table, while the other connection is attempting to read data from the same table. When using the default transaction isolation level of TRANSACTION_SERIALIZABLE, the following error may be seen on the thread or application that is reading from the table, approximately 2 to 5 minutes after the situation occurs. It includes an error code of 2631. com.ncr.teradata.jdbc_4.util.JDBCException: [NCR] [Teradata DBMS] : Transaction ABORTed due to deadlock. If this error occurs, either: • Resubmit the failed read operation, or • Use a transaction isolation level of TRANSACTION_READ_UNCOMMITTED on the connection reading from the table. Note: The transaction level is set using the java.sql.Connection.setTransactionIsolation method. Though this prevents the problem from occurring, it has the side effect of allowing dirty, non-repeatable, and phantom reads. Whether or not this is acceptable must be determined on an individual application basis. Large Object Interface Description The LOB data type categories for the Teradata Database include BLOB (binary data) and CLOB (character data). The Teradata Driver for the JDBC Interface supports both data types for the Type 4 driver. Number of LOB Columns In the database, up to 32 LOB columns can be defined in a table. BLOBs and CLOBs closely resemble the VARBYTE and VARCHAR data types. LOB Size Limits The Teradata Driver for the JDBC Interface uses the deferred method of handling large objects, and currently handles LOBs up to 2 GB. The deferred method allows LOB data to be processed separately from non-LOB data. Response Limit Exceeded Error The most likely cause of the following error from the Teradata Database is that the application is not properly closing ResultSet objects and Statement objects. SQLState: HY000 Message: [NCR] [Teradata DBMS] : Response limit exceeded. Vendor: 3130 This error message refers to the response from an SQL request, which is the output from a single-statement SQL request or a multi-statement SQL request. 312 Teradata Driver for the JDBC Interface User Guide Appendix B: Troubleshooting Large Object Interface The response limit is a limit imposed by the Teradata Database of a maximum of 16 open responses per connection. • For a single-statement SQL request, the response remains open until either the ResultSet object or the Statement object is closed. • For a multi-statement SQL request, the response remains open until either all the ResultSet objects, or the Statement object is closed. • For an InputStream obtained from Blob.getBinaryStream or Clob.getAsciiStream, or for a Reader obtained from Clob.getCharacterStream, the response remains open until the InputStream or Reader object is closed. To solve this issue, first, examine applications to verify that they have proper exceptionhandling, with final blocks coded to ensure that ResultSet objects, Statement objects, LOB InputStream, and LOB Reader objects are always closed as soon as they are no longer needed. The application cannot rely on garbage collection to close ResultSet objects, Statement objects, LOB InputStream, and LOB Reader objects, since the Java programming language does not guarantee the timeliness of garbage collection. Sometimes it is not possible to modify applications that do not properly close ResultSet objects and Statement objects; for example, if the application is a third-party application and the source code is not available. If the application does not use LOBs, and the application does not use Scrollable Result Sets, and the application does not use Updatable ResultSets, and the application requires more than 16 open responses per connection, then the connection parameter LOB_SUPPORT=OFF can be used as a workaround. For more information about the LOB_SUPPORT connection parameter, see “Making a Teradata Database Connection” on page 43. The Teradata Driver for the JDBC Interface accesses LOBs in deferred mode, meaning that result sets contain LOB locators, rather than actual LOB data. The Teradata Database requires use of the KeepResponse mode to access LOBs in deferred mode. When KeepResponse mode is not used, the Teradata Database automatically closes a response when the response: • Is small enough to fit in a single message from the Teradata Database to the Teradata Driver for the JDBC Interface; or • Spans multiple messages, and the application has read through the response up to the beginning of the last response message When connection parameter LOB_SUPPORT=OFF is specified, the Teradata Driver for the JDBC Interface does not use the KeepResponse mode, which means that LOBs cannot be used. This also means that the Teradata Database automatically closes responses in the two situations listed above, helping an application to avoid reaching the Teradata Database limit of 16 open responses per connection. When connection parameter LOB_SUPPORT=OFF is specified, Scrollable Result Sets and Updatable Result Sets cannot be used. Requesting a Scrollable Result Set and/or Updatable Result Set throws an exception due to a Teradata Database error: [NCR] [Teradata DBMS] : Parcel kind or ordering is invalid. Teradata Driver for the JDBC Interface User Guide 313 Appendix B: Troubleshooting 1 MB SQL 1 MB SQL Using the Type 4 Driver on IBM AIX 5.2 If the following exception is thrown: java.lang.SecurityException: class com.ibm.crypto.provider.SHA configured for MessageDigest(provider: IBMJCE) cannot be accessed.class "com.ibm.crypto.provider.SHA"'s signer information does not match signer information of other classes in the same package. then you need to modify your java.security file to add the Sun crypto provider as the first entry. In the “jre” subdirectory for your JDK, modify jre/lib/security/java.security by adding the following line to the file at the start of the “security.provider” section. security.provider.1=sun.security.provider.Sun [moved from chapter 2] Additional Arguments Needed for IBM AIX platform Additional arguments are needed on the IBM AIX platform with 256 MB or less of memory to support the V2R5.0 long query feature. This could also be the case for any of the platforms that support the Teradata Driver for the JDBC Interface. On the IBM AIX platform, or other platforms found to require additional arguments to support the long query feature, the following arguments need to be added to the java command: -ms256 -mx1024m An example of this command is: java -ms256m -mx1024m DDL1MB If the arguments are not used, the user may receive a core dump for JVM. If -m1024m is not sufficient, the value can be increased to -mx2056m. Submitting Application Using addBatch() and executeBatch() When submitting a 1 MB application using addBatch()and executeBatch(), the following database error may be returned: *** SQLException caught*** SQLState: HY000 Message: [NCR] [Teradata JDBC Driver] : HY001 3714 : Insufficient memory for a Concrete Step for this request. Vendor: 759 This is an indication that the SQL is too large. Shorten the SQL and resubmit the application. 314 Teradata Driver for the JDBC Interface User Guide Appendix B: Troubleshooting Multiple Sessions Database Response Buffer Size Limit The Database Response Buffer size limit is 1 MB. Be aware that ExecuteBatch() always returns an array consisting of a total count and an update count for each INSERT, UPDATE, or DELETE. If the count exceeds 1 MB, the following message is returned from the database: *** SQLException caught*** SQLState: HY000 Message: [NCR] [Teradata JDBC Driver] : HY000 5795: The Response Step Size required for this request exceeds 1 MB. Vendor: 759 Multiple Sessions Multiple Sessions The Microsoft Windows 2000 or Microsoft Windows XP Professional operating systems have a known limitation in the number of sessions you can connect to the Teradata Database using the Teradata Driver for the JDBC Interface. If you attempt to establish a large number of sessions, you receive an error message and the sessions are not established. To correct this operating system limitation, follow these steps: 1 From the Microsoft Windows task bar, select Start and then choose Run. A Run dialog box opens. 2 Type RegEdit in the Open text box. 3 Click OK. A Registry Editor window opens. Figure 4: Registry Editor Window Teradata Driver for the JDBC Interface User Guide 315 Appendix B: Troubleshooting Application Errors 4 From the left pane, navigate to the following location: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\ Session Manager\Subsystems 5 Double-click the Windows name in the right pane. An Edit String dialog box opens. 6 Find the Windows SharedSection parameter in the Value data text box. 7 Increase the value of the third Windows SharedSection parameter. For example, the default value is Windows SharedSection=1024,3072,512. Change 512 to a higher value, such as 1024, 2048, and so forth. Figure 5: Changing the Windows SharedSection Value 8 Click OK to close the Edit String dialog box. 9 Close the Registry Editor window and return to your desktop. 10 Reboot your system to apply the changes. Application Errors Close Not Done If the following error message is received: java.sql.SQLException: [NCR][Teradata JDBC Driver]: executeQuery error: The statement has been cancelled by another thread. This error is received when a cancel is done on a statement and the application/applet continues to use the same statement without doing a close() and a con.createStatement(). Ensure that the application/applet is doing a close and createStatement for every new statement. UTF16 Character Set Error Object names, such as table and column names, can only consist of UTF16 characters in the 7-bit ASCII range. Object names have a maximum length of 30 bytes. Because UTF16 uses two bytes per character, object names that have a length of greater than 15 characters will be truncated by certain operations. The error below is returned if the UTF16 characters are outside the 7-bit ASCII range: 316 Teradata Driver for the JDBC Interface User Guide Appendix B: Troubleshooting Checking the Environment Parameters Message: [NCR] [Teradata DBMS] : Attempt to translate Unicode/Graphic/ KanjiSJI S data to another form has failed Checking the Environment Parameters CLASSPATH If you receive a ClassNotFoundException for “com.ncr.teradata.TeraDriver”, then the problem may be due to the classpath not being set, or the classpath being set incorrectly, such that terajdbc4.jar cannot be found. The terajdbc4.jar file must be listed on the classpath. If you receive a NoClassDefFoundError for “com/ncr/teradata/jtdgss/TdgssManager”, then the problem may be due to the classpath not being set, or the classpath being set incorrectly, such that tdgssjava.jar cannot be found. The tdgssjava.jar file must be listed on the classpath. If you receive one of the following exceptions: • NullPointerException at com.ncr.teradata.jtdgss.TdgssConfigApi.GetMechanisms • IllegalArgumentException “InputStream cannot be null” at javax.xml.parsers.DocumentBuilder.parse, at com.ncr.teradata.jtdgss.TdgssParseXml.parse then the problem may be due to the classpath not being set, or the classpath being set incorrectly, such that tdgssconfig.jar cannot be found. There are many places where the classpath can be set, including, but not limited to: • The CLASSPATH environment variable set in a login script, a profile, the system profile, a shell script, or a batch file. • On the Java command line, using the -classpath option, as typed by the user. • On the Java command line, using the -classpath option, as specified in a shell script or batch file. • In an application server’s classpath configuration for a DataSource definition. No matter where or how you set the classpath, the classpath used for the Teradata Driver for the JDBC Interface must include: • terajdbc4.jar • tdgssjava.jar • tdgssconfig.jar Troubleshooting COP Discovery DNS and Hosts File Entries Check the following entries in DNS or the /etc/hosts file: • Check all entries for incorrect, missing, or duplicate network addresses of COPs, Application Processors (AP), or nodes. Teradata Driver for the JDBC Interface User Guide 317 Appendix B: Troubleshooting Improving Performance • Check that COPs, APs, or nodes in the same group for a Teradata Database have the same dbcname, and that they are numbered sequentially, starting with 1. Remember that the format of a COP name is dbcnameCOPn, where dbcname must begin with an alphabetic character. Improving Performance If the performance of the application seems very slow, here are some recommendations for improvement: • Turn off debug parameters. Make sure all debugging is turned off. See Chapter 2. • Use PreparedStatement where possible. This applies whenever the same SQL statement is submitted many times, but data values differ for each submission. One example would be an INSERT statement that is submitted many times, but with different inserted data values each time. Another example would be a SELECT statement that is submitted many times, but with different comparison values in WHERE-clause conditions each time. If data values are specified as literals in the SQL statement, and the SQL statement is changed with different literal data values upon each submission, then the Teradata Database must parse the SQL statement each time before executing it. For situations like these, a PreparedStatement should be used instead. The SQL statement must have a ? placeholder for each data value that will be changed per submission. The application must prepare the SQL statement once, using the Connection.prepareStatement method. For each submission, the application must bind all the data values using the PreparedStatement.setXXX methods, and then the application must execute the PreparedStatement. The application can repeat the bind and execute steps over and over, with different bound data values each time. This technique provides a substantial performance improvement, because the Teradata Database only needs to parse the SQL statement once, and can reexecute the parsed statement over and over. • Inserting Small LOB Values. The recommended technique for inserting LOB values is to use a PreparedStatement INSERT with ? parameter markers for all column values to be inserted. Use the setBinaryStream method for binding BLOB values to the parameter markers corresponding to BLOB columns, then use the setAsciiStream or setCharacterStream method for binding CLOB values to the parameter markers corresponding to CLOB columns. When the setBinaryStream, setAsciiStream, and setCharacterStream methods are used, the Teradata Driver for the JDBC Interface sends LOB data to the Teradata Database separately from other bound parameter values, so that LOB values do not count towards the Teradata Database limit of 64000 total bytes of bound parameter values per inserted row. To improve the performance of a PreparedStatement INSERT, that is inserting one or more small ( <= 64000 bytes) LOB values per row, the setString method is used to bind a value to a CLOB column, and the setBytes method is used to bind a value to a BLOB 318 Teradata Driver for the JDBC Interface User Guide Appendix B: Troubleshooting Improving Performance column. The SQL INSERT statement must cast the ? parameter marker to a CLOB or BLOB, respectively. INSERT INTO MyTable(id,clob_col) VALUES(?,CAST(? AS CLOB)) prepStmt.setInt(1,id); prepStmt.setString(2,"abc"); Using the setBytes method with a CAST expression forces the Teradata Driver for the JDBC Interface to send the bound parameter value as a VARBYTE value, so it is limited to 64000 bytes, even though the destination column may be a BLOB that can hold values larger than 64000 bytes. Using the setString method with a CAST expression forces the Teradata Driver for the JDBC Interface to send the bound parameter value as a VARCHAR value, so it limited to 64000 bytes, even though the destination column may be a CLOB that can hold values larger than 64000 bytes. If a Unicode session character set (UTF8 or UTF16) is used, and/ or if the destination column is designated CHARACTER SET UNICODE, then the Teradata Database will convert the bound parameter value into two-byte Unicode characters. The value after conversion is limited to 64000 bytes. This technique works only if the total size of all the bound parameter values does not exceed the Teradata Database limit of 64000 bytes for all the bound parameter values for an inserted row. This technique should only be used when performance is critical, and it is known in advance that the total size of all the bound parameter values, including LOB values, does not exceed 64000 bytes per inserted row. This technique is subject to a further limitation such that the total size of all the bound parameter values must not exceed the Teradata Database limit of 64000 bytes for all the bound parameter values for an inserted row, after any necessary character set conversions have been performed by the Teradata Database. If a Unicode session character set (UTF8 or UTF16) is used, and/or if a destination character column is designated CHARACTER SET UNICODE, then the Teradata Database will convert all the bound parameter values that are character data types (CHAR, VARCHAR, CLOB) into two-byte Unicode characters. These two-byte Unicode characters are counted towards the Teradata Database limit of 64000 bytes for all the bound parameter values for an inserted row. • Use executeBatch() where possible. Whenever there are many insert, update, or delete statements that can be submitted together, use the executeBatch() method rather that executeUpdate() or execute(). However, the total buffer length is limited to approximately 1 MB. Using executeBatch() instead of executeUpdate() can improve your performance by more than 50%. • Use connection pooling provided by an application server. Connection pooling is a technique used for sharing server resources among requesting clients. It allows multiple clients to share a cached set of connection objects that provide access to the database. It improves performance by eliminating the overhead associated with establishing a new database connection for each request. However, there are some restrictions. Since it is not currently possible to reset a database connection, users of connection pooling must not change the following session parameters because these changes will be inherited by the next user of the connection: • Database • Collation Teradata Driver for the JDBC Interface User Guide 319 Appendix B: Troubleshooting Java HotSpot Server Virtual Machine Error on Linux Platform • Character Set • Transaction Semantics • Dateform • Timezone • Default Date Format • Use multi-threading. Where possible, use multi-threading with multiple sessions for those requests that can be processed at the same time. It is important to remember, however, not to have multiple concurrent requests on a single session. Teradata does not support this and even though the driver will accept this, it blocks until the current request is complete. This may actually degrade performance. For improved performance, use concurrent sessions with each session running only one request at a time. • Use a Transaction isolation level of TRANSACTION_READ_UNCOMMITTED. This feature can speed up access to data though it comes at the cost of encountering dirty reads, non-repeatable reads, and phantom reads. Whether or not this is suitable should be determined on an individual application basis. • Use TYPE_SCROLL_INSENSITIVE result sets. These can improve performance when used with queries which can return large multiple result sets that do not require all rows to be processed. Beginning with Teradata Database 12.0, when the application requests the ResultSet type to be ResultSet.TYPE_SCROLL_INSENSITIVE, the Teradata Driver for the JDBC Interface is able to quickly and efficiently skip to the next result of a multi-statement request by using cursor positioning to position to the last row of the current result set. If forward-only result sets are used, the same skipping operation will require the JDBC driver to fetch all rows of the current result set first, which can take significantly longer. The following methods will create statements that return TYPE_SCROLL_INSENSITIVE result sets: Connection.createStatement(ResultSet.TYPE_SCROLL_INSENSITIVE, ResultSet.CONCUR_READ_ONLY); Connection.prepareStatement(sql, ResultSet.TYPE_SCROLL_INSENSITIVE, ResultSet.CONCUR_READ_ONLY); Connection.prepareCall(sql, ResultSet.TYPE_SCROLL_INSENSITIVE, ResultSet.CONCUR_READ_ONLY); Java HotSpot Server Virtual Machine Error on Linux Platform Sun Java HotSpot 64-Bit Server Virtual Machine Error on Linux Red Hat Advanced Server 2.1/3.0 Itanium Platform: Java HotSpot JVM error (HotSpot Virtual Machine Error ID: 4E4154495645294E53543F494116140E435050006F) has been observed on Linux Red Hat Advanced Server 2.1/3.0 Itanium platform when running some client applications with Teradata DBS V2R6 using Teradata JDBC Driver 3.2. 320 Teradata Driver for the JDBC Interface User Guide Appendix B: Troubleshooting Troubleshooting Security System configurations: • Java version: “1.4.2_05” (build 1.4.2_05-b04) • Java VM: Java HotSpot(TM) 64-Bit Server VM (build 1.4.2_05-b04, mixed mode) • OS version: Linux 2.4.21-15.EL #1 SMP Thu Apr 22 00:13:07 EDT 2004 ia64 ia64 ia64 • GNU/Linux (64-bit system) This HotSpot JVM error on Linux RedHat Advanced Server 2.1/3.0 Itanium platform has been reported to Sun Microsystem Bug report system, and is currently being reviewed by Sun Microsystems (Incident Review ID: 311761). Troubleshooting Security Troubleshooting Kerberos If you have trouble getting Kerberos to work properly, check the following tables for messages and solutions to common errors. Error Message GSS Exception: No valid credentials provided Cause “kinit” was never run. Solution Run the “kinit” program that resides in the “jre/bin” directory of your Java JDK. Error Message java.lang.SecurityException: Unable to locate a login configuration Cause Failed to specify a configuration file. Solution Specify the configuration file by using the JVM option Djava.security.auth.login.config or by modifying the appropriate “java.security” file. The steps to do this are outlined in the Kerberos Prerequisites section of this document. Error Message javax.security.auth.login.Login Exception: No Login Modules configured for com.sun.security.jgss.initiate Cause The following information is missing or misspelled in you configuration information: (Mechanism level: Failed to find any Kerberos Ticket) com.sun.security.jgss.initiate { com.sun.security.auth.module.Krb5LoginModule sufficient useTicketCache=true; }; Teradata Driver for the JDBC Interface User Guide 321 Appendix B: Troubleshooting Troubleshooting Security Solution Ensure that the above information is present in your Login Configuration Information. See the “Kerberos Perquisites” section of this manual for information on setting Login Configuration. Error Message javax.security.auth.login.LoginException: Pre-authentication information was invalid Cause One of: • Configuration file in “C:\winnt” is bad.... • Invalid Username was used. • Invalid Password was used Solution Validate the configuration file in c:/winnt Validate Username and Password used. Note that the username must be types in “exactly” as it appears in Windows “Active Directory Users”. Error Message [NCR] [Teradata DBMS]: Invalid password Cause This can occur when using Kerberos Single Sign-On when • the Teradata Database user was not defined with the same password as their System logon password • the Teradata Database user was not configured to use SSO 322 Solution Ensure that the same password is being used for both system logon and for the Teradata Database user password. This can be done by logging on without Kerberos with the username and password. If that isn’t the cause, then the Teradata Database user needs to be configured for SSO via the “grant logon with null password” command by a Teradata Database administrator. Error Message GSSException: No valid credentials provided Cause Did not specify -Djavax.security.auth.useSubjectCredsOnly=false Solution Add the -Djavax.security.auth.useSubjectCredsOnly=false to the script that runs your application. Error Message KrbException: Invalid option setting in ticket request. (101) Cause kinit was not run using the "-f" or forwardable option. Solution Run the "kinit" program that resides in the "jre/bin" directory of the Java JDK with the forwardable option set. For example, "kinit -f" (Mechanism level: Failed to find any Kerberos Ticket) (Mechanism level: Failed to find any Kerberos Ticket) Teradata Driver for the JDBC Interface User Guide Appendix B: Troubleshooting Troubleshooting JDBC FastLoad LDAP Authentication Not Supported on MVS LDAP does not support Teradata Driver for the JDBC Interface logon from MVS. An attempt to log on using the LDAP mechanism results in an SQLException with the following error, even when valid information is specified for the LOGDATA parameter (set using URL or DataSource): SQLState: 28000 Error code: 8017 Message: [NCR] [Teradata DBMS] : The UserId, Password or Account is invalid. UserId, Password, or Account is Invalid Error Message: [NCR] [Teradata DBMS] : The UserId, Password or Account is invalid. Vendor: 8017 Cause: In addition to being caused by invalid user, password, or account information, this message will also be displayed when the LDAP or KERBEROS mechanism has been selected and in addition to the required LOGDATA parameter, a username or password has also been provided. Solution: Make sure that only LOGDATA information is provided with LDAP and KERBEROS. Do not set Teradata Database usernames or passwords. Troubleshooting JDBC FastLoad If an SQLException is encountered during JDBC FastLoad, it may be part of a chain of SQL exceptions. To get the complete picture of the cause for the SQLException, it is necessary to walk through the whole chain of SQL exceptions. Likewise, if an SQLWarning is encountered during JDBC FastLoad, it may be part of a chain of SQL warnings. To get a complete picture of the cause for the SQLWarning, it is necessary to walk through the whole chain of SQL warnings. For example: try { PreparedStatement pstmt = con.prepareStatement(“INSERT INTO ...”); try { // using JDBC FastLoad SQLWarning w = pstmt.getWarnings(); while (w != null) StringWriter sw = new StringWriter(); w.printStackTrace(new PrintWriter(sw, true)); System.out.println(“SQL State = ” + w.getSQLState() + “, Error Code = “ + w.getErrorCode() + “\n” + sw.toString()); w = w.getNextWarning(); } Teradata Driver for the JDBC Interface User Guide 323 Appendix B: Troubleshooting Troubleshooting JDBC Monitor } finally { pstmt.close(); } } catch (SQLException e) { while (e != null) { StringWriter sw = new StringWriter(); e.printStackTrace(new PrintWriter(sw, true)); System.out.println(“SQL State = ” + e.getSQLState() + “, Error Code = “ + e.getErrorCode() + “\n” + sw.toString()); e = e.getNextException(); } } When using JDBC FastLoad, details on data errors may be included in the chain of SQL exceptions mentioned above. Some data error details may be quite lengthy. They are in one of two temporary error tables mentioned in “Considerations When Using JDBC FastLoad” on page 86. For more details on the format of the two temporary error tables, see the section on Error Table Formats in the Teradata FastLoad Reference. Information on why JDBC FastLoad was not activated can be obtained by specifying “LOG=INFO” in the URL connection string. Search for “FastLoad ” (note the space after FastLoad) in the resulting LOG output. The same search can be used to find out if JDBC FastLoad was activated. Here is a sample LOG output that shows JDBC FastLoad was not activated: Cannot FastLoad because statement is NOT an INSERT! Here is a sample LOG output that shows JDBC FastLoad was activated: FastLoad found 2 AMP(s) in anmpc2 and created 2 FastLoadConnection(s) and 2 FastLoadPreparedStatement(s) with SESSIONS=8. Troubleshooting JDBC Monitor If an SQLException is encountered by the JDBC Monitor, it may be part of a chain of SQL exceptions. To obtain the complete picture of the cause for the SQLException, it is necessary to step through the entire chain of SQL exceptions. Likewise, if an SQLWarning is encountered by the JDBC Monitor, it may be part of a chain of SQL warnings. To obtain the complete picture of the cause for the SQL Warning, it is necessary to step through the entire chain of SQL warnings. Here is an example: try { PreparedStatement pstmt = con.prepareStatement(“MONITOR VERSION”); try { //bind input values (not shown) boolean resultSetAvailable = pstmt.execute(); //get ResultSet (not shown) SQLWarning w = pstmt.getWarnings(); while (w != null) StringWriter sw = new StringWriter(); 324 Teradata Driver for the JDBC Interface User Guide Appendix B: Troubleshooting Troubleshooting JDBC Monitor w.printStackTrace(new PrintWriter(sw,true)); System.out.printIn(“SQL State = ” + w.getSQLState() + “, Error Code = ” + w.getErrorCode() + “\n” + sw.toString()); w = w.getNextWarning(); } } finally { pstmt.close(); } } catch (SQLException e) { while (e != null) { StringWriter sw = new StringWriter(); e.printStackTrace(new PrintWriter(sw, true)); System.out.printIn(“SQL State = ” + e.getSQLState() + “, Error Code = ” + e.getErrorCode() + “\n” + sw.toString()); e = e.getNextException(); } } Teradata Driver for the JDBC Interface User Guide 325 Appendix B: Troubleshooting Troubleshooting JDBC Monitor 326 Teradata Driver for the JDBC Interface User Guide APPENDIX C Metadata Features and Functions This appendix provides a table that answers questions about the metadata features and functions, and how they are supported by the Teradata JDBC Driver software. Issues and Answers Table 46 describes, in alphabetic order, the metadata features and functions of the Teradata Driver for the JDBC Interface software. Table 46: Metadata Features and Functions Topic/Issue Answer ALTER TABLE Statements Is ALTER TABLE supported: • With add column? • With drop column? • Yes • Yes Catalogs What is the maximum length for a catalog name? Teradata does not use catalogs Does a catalog appear at the start of a qualified table name? No—Teradata does not use catalogs Can a catalog name be used in a: No—Catalog names are not supported • • • • • Data manipulation statement? Index definition statement? Privilege definition statement? Procedure call statement? Table definition statement? Characters What are all the special characters that can be used in unquoted identifier names (those beyond a-z, A-Z, 0-9, and _)? # and $ How many hex characters are allowed in an inline binary literal? 62000 Teradata Driver for the JDBC Interface User Guide 327 Appendix C: Metadata Features and Functions Issues and Answers Table 46: Metadata Features and Functions (continued) Topic/Issue Answer What is the string used to quote SQL identifiers? Double-quote characters: “ “ What is the separator character between the catalog name (Teradata Database database name) and table name? . Is the escape character supported in LIKE clauses? Yes Is the EBCDIC character set supported? The driver does not support the EBCDIC character set since there is no Java encoding for EBCDIC. Character Literals What is the maximum length for a character literal? 31000 characters Columns What is the maximum length of a column name? 30 characters Can columns be defined as non-nullable? Yes Column Aliases Is column aliasing supported? Yes CONVERT Functions Is the CONVERT function supported: • Between SQL types? • Between the given SQL types? • No • No Cursors What is the maximum length of a cursor name? 18 characters Can cursors remain open across: • Commits? • Rollbacks? • No • No Databases 328 What is the URL for this database? jdbc:teradata Is the database in read-only mode? No Teradata Driver for the JDBC Interface User Guide Appendix C: Metadata Features and Functions Issues and Answers Table 46: Metadata Features and Functions (continued) Topic/Issue Answer Does the database: • Use a file for each table? • Store tables in a local file? • No • No Database Connections How many database connections can be active at the same time? Unlimited Data Definitions Does data definition cause transaction commit? No Is data definition ignored in transactions? No Are both data definition and data manipulation statements within a transaction supported? Yes The data definition is allowed but only as the last statement in a transaction. Data Manipulation Statements Are data manipulation statements supported only within a transaction? No DELETE Statements Is positioned DELETE supported? Yes GROUP BY Clauses Is some form of the GROUP BY clause supported? Yes Can a GROUP BY clause: • Use column not in the SELECT statement? • Add columns not in the SELECT statement, provided it specifies all the column that are in the SELECT statement? • Yes • Yes What is the maximum number of columns in a GROUP BY clause? Unlimited Indexes What is the maximum number of columns allowed in an index? 64 What is the maximum length of an index? 64000 bytes Teradata Driver for the JDBC Interface User Guide 329 Appendix C: Metadata Features and Functions Issues and Answers Table 46: Metadata Features and Functions (continued) Topic/Issue Answer Joins Is there limited support for outer joins? Yes Are full nested outer joins supported? Yes Math Functions What are the supported math functions? ABS, ACOS(arg), ACOSH(arg), ASIN(arg), ASINH(arg), ATAN(arg), ATAN2(x,y), ATANH(arg), COS (arg), COSH(arg), EXP, LOG, LN, SIN(arg), SINH(arg), SQRT, TAN(arg), TANH(arg), NULLIFZERO, and ZEROIFNULL Multiple Result Sets Are multiple results from a single execute supported? Yes NULL Values Are concatenations between NULL values and non-NULL values themselves NULL? Yes Are NULL values sorted at the end, regardless of sort order? No Are NULL values sorted at the start, regardless of the sort order? No Are NULL values sorted high? No Are NULL values sorted low? Yes ORDER BY Clauses Are expressions in ORDER BY lists supported? Yes What is the maximum number of columns in an ORDER BY clause? Unlimited Can an ORDER BY clause use columns not in the SELECT statement? Yes Procedures What is the maximum length of a procedure name? 330 30 characters Teradata Driver for the JDBC Interface User Guide Appendix C: Metadata Features and Functions Issues and Answers Table 46: Metadata Features and Functions (continued) Topic/Issue Answer What are the catalog’s stored procedure parameters and result columns? Available What are the stored procedures available in a catalog? Available Are stored procedure calls using the stored procedure escape syntax supported? Yes Product Names What is the name of this database product? Teradata What is the name of this JDBC driver? com.ncr.teradata.TeraDriver Rows What is the maximum length of a single row: 64,256 Does maximum row size include blobs? No Schemas What is the maximum length of a schema name? Schemas are not supported in the Teradata Database, but for database names the maximum length is 30 characters Can a schema name be used in: • • • • • • A data manipulation statement? An index definition statement? A privilege definition statement? A procedure call statement? A macro call statement A table definition statement? • • • • • • Yes Yes Yes (GRANT) Yes Yes Yes SELECT Statements What is the maximum number of columns in a SELECT list? Unlimited What is the maximum number of tables in a SELECT? Unlimited Is SELECT for UPDATE supported? Yes Teradata Driver for the JDBC Interface User Guide 331 Appendix C: Metadata Features and Functions Issues and Answers Table 46: Metadata Features and Functions (continued) Topic/Issue Answer SQL Statements What is the maximum length of an SQL statement? 1048576 How many active statements can be open to the same database at the same time? 16 per session Can statements remain open across: • Commits? • Rollbacks? • No • No Get a comma-separated list of all the SQL keywords in a database that are NOT also SQL92 keywords? See the SQL/Data Dictionary Quick Reference manual How does the database treat mixed-case quoted and unquoted SQL identifiers? As case-insensitive, and stores them in mixed-case format Are the following levels of the ANSI92 SQL grammar supported: • Entry? • Intermediate? • Full? • Yes • Not fully—only some features • Not fully—only some features Is the following ODBC SQL grammar supported: • Minimum? • Core? • Extended • Yes • Yes, except referential integrity • No Is the SQL Integrity Enhancement Facility supported? No Is SQL: • UNION supported? • UNION ALL supported? • Yes • Yes Are updates made to a LOB made on a copy or directly to the LOB? Updates to a LOB are made on a copy Strings What is the string that can be used to escape ‘_’ or ‘%’ in the string pattern style catalog search parameters? Any single character Get a comma-separated list of string functions? trim, substring, substr, msubstr, index, mindex, vargraphic, char2hexint, upper Subqueries 332 Teradata Driver for the JDBC Interface User Guide Appendix C: Metadata Features and Functions Issues and Answers Table 46: Metadata Features and Functions (continued) Topic/Issue Answer Are correlated subqueries supported? Yes Are subqueries supported in: • • • • Comparison expressions? ‘exists’ expressions? ‘in’ statements? Quantified expressions? • • • • Yes Yes Yes Yes User Names What is the maximum length of a user name? 30 characters System Functions Get a comma-separated list of system functions? Characters, bytes, sum, average, count, minimum, maximum Tables What is the maximum length of a table name? 30 characters What is the maximum number of columns in a table? 2000 columns Are table correlation names supported? Yes Table Correlation Names When table correlation names are supported, must Yes they be different from the names of the tables? Teradata Terminology What is the Teradata term for: • Catalog? • Procedure? • Schema? • Database name • Procedure • Database Time and Date Functions Get a comma-separated list of time and date functions? extract, add-months Transactions Are transactions supported? Yes Can multiple transactions on different connections be open at the same time? Yes Teradata Driver for the JDBC Interface User Guide 333 Appendix C: Metadata Features and Functions Issues and Answers Table 46: Metadata Features and Functions (continued) Topic/Issue Answer What's the database default transaction isolation level? 8(Transaction_Serializable) Does the database support the given transaction isolation level? 1 or 8, yes; Others, no 1: TRANSACTION_READ_UNCOMMITTED 8: TRANSACTION_SERIALIZABLE UPDATE Statements Is positioned UPDATE supported: Yes User Names What is the user name known to this database 334 There is no function that returns the user name, but a variable called user (ex. select user;) Teradata Driver for the JDBC Interface User Guide APPENDIX D Data Type Conversions This appendix provides a table for Data Type Conversions. Data Type Conversions Table Table 47 lists the data type conversions that are supported by the Teradata Driver for the JDBC Interface. BYEINT SMALLINT INTEGER n/a n/a n/a DOUBLE PRECISION DECIMAL NUMERIC n/a n/a CHAR VARCHAR LONG VARCHAR BYTE VARBYTE VARBYTE(6400) DATE TIME TIMESTAMP CLOB BLOB n/a n/a n/a n/a n/a Table 47: Data Type Conversions Table TINYINT SMALLINT INTEGER BIGINT REAL FLOAT DOUBLE DECIMAL NUMERIC BIT BOOLEAN CHAR VARCHAR LONGVARCHAR BINARY VARBINARY LONGVARBINARY DATE TIME TIMESTAMP CLOB BLOB ARRAY REF DATALINK STRUCT JAVA OBJECT Teradata Data Types JDBC Data Types ResultSet Methods Prepared Statement Methods getByte setByte X X X X X X X X X X getShort setShort X X X X X X X X X X getInt setInt X X X X X X X X X X getLong setLong X X X X X X X X X X getFloat setFloat X X X X X X X Teradata Driver for the JDBC Interface User Guide 335 Appendix D: Data Type Conversions Data Type Conversions Table BYEINT SMALLINT INTEGER n/a n/a n/a DOUBLE PRECISION DECIMAL NUMERIC n/a n/a CHAR VARCHAR LONG VARCHAR BYTE VARBYTE VARBYTE(6400) DATE TIME TIMESTAMP CLOB BLOB n/a n/a n/a n/a n/a Table 47: Data Type Conversions Table (continued) TINYINT SMALLINT INTEGER BIGINT REAL FLOAT DOUBLE DECIMAL NUMERIC BIT BOOLEAN CHAR VARCHAR LONGVARCHAR BINARY VARBINARY LONGVARBINARY DATE TIME TIMESTAMP CLOB BLOB ARRAY REF DATALINK STRUCT JAVA OBJECT Teradata Data Types JDBC Data Types getDouble setDouble X X X X X X X getBigDecimal setBigDecimal X X X X X X X X X X getBoolean setBoolean X X X X X X X X X X getString setString X X X X X X X X X X X X X X X X getBytes setBytes getDate setDate X X X getTime setTime X X X getTimestamp setTimestamp X X X getAsciiStream setAsciiStream X X X getBinary Stream setBinary Stream getCharacter Stream setCharacter Stream getClob setClob getBlob setBlob getArray setArray getRef setRef 336 X X X X X X X X X X X X X X Teradata Driver for the JDBC Interface User Guide Appendix D: Data Type Conversions Data Type Conversions Table BYEINT SMALLINT INTEGER n/a n/a n/a DOUBLE PRECISION DECIMAL NUMERIC n/a n/a CHAR VARCHAR LONG VARCHAR BYTE VARBYTE VARBYTE(6400) DATE TIME TIMESTAMP CLOB BLOB n/a n/a n/a n/a n/a Table 47: Data Type Conversions Table (continued) TINYINT SMALLINT INTEGER BIGINT REAL FLOAT DOUBLE DECIMAL NUMERIC BIT BOOLEAN CHAR VARCHAR LONGVARCHAR BINARY VARBINARY LONGVARBINARY DATE TIME TIMESTAMP CLOB BLOB ARRAY REF DATALINK STRUCT JAVA OBJECT Teradata Data Types JDBC Data Types getURL setURL getObject ->String X X X getObject ->BigDecimal X X getObject ->Boolean getObject ->Integer X X X getObject ->Long getObject ->Float getObject ->Double getObject ->byte[] getObject ->java.sql.Date getObject ->java.sql.Time getObject ->java.sql. Timestamp getObject ->java.sql.Clob getObject ->java.sql.Blob Teradata Driver for the JDBC Interface User Guide X X X X X X X X X X 337 Appendix D: Data Type Conversions Data Type Conversions Table BYEINT SMALLINT INTEGER n/a n/a n/a DOUBLE PRECISION DECIMAL NUMERIC n/a n/a CHAR VARCHAR LONG VARCHAR BYTE VARBYTE VARBYTE(6400) DATE TIME TIMESTAMP CLOB BLOB n/a n/a n/a n/a n/a Table 47: Data Type Conversions Table (continued) TINYINT SMALLINT INTEGER BIGINT REAL FLOAT DOUBLE DECIMAL NUMERIC BIT BOOLEAN CHAR VARCHAR LONGVARCHAR BINARY VARBINARY LONGVARBINARY DATE TIME TIMESTAMP CLOB BLOB ARRAY REF DATALINK STRUCT JAVA OBJECT Teradata Data Types JDBC Data Types getObject ->java.sql.Array getObject ->java.sql.Struct getObject>java.sql.Ref getObject>java.net.URL getObject ->other class 338 setObject (String) X X X X X X X X X X X X X X X X setObject (BigDecimal) X X X X X X X X X X setObject (Boolean) X X X X X X X X X X setObject (Byte) X X X X X X X X X X setObject (Short) X X X X X X X X X X setObject (Integer) X X X X X X X X X X setObject (Long) X X X X X X X X X X setObject (Float) X X X X X X X setObject (Double) X X X X X X X Teradata Driver for the JDBC Interface User Guide Appendix D: Data Type Conversions Data Type Conversions Table BYEINT SMALLINT INTEGER n/a n/a n/a DOUBLE PRECISION DECIMAL NUMERIC n/a n/a CHAR VARCHAR LONG VARCHAR BYTE VARBYTE VARBYTE(6400) DATE TIME TIMESTAMP CLOB BLOB n/a n/a n/a n/a n/a Table 47: Data Type Conversions Table (continued) TINYINT SMALLINT INTEGER BIGINT REAL FLOAT DOUBLE DECIMAL NUMERIC BIT BOOLEAN CHAR VARCHAR LONGVARCHAR BINARY VARBINARY LONGVARBINARY DATE TIME TIMESTAMP CLOB BLOB ARRAY REF DATALINK STRUCT JAVA OBJECT Teradata Data Types JDBC Data Types setObject (byte[]) X X X setObject (java.sql.Date) X X X setObject (java.sql.Time) X X X setObject(java. sql.Timestamp) X X X setObject(java. sql.Clob) setObject(java. sql.Blob) X X X X X setObject(java. sql.Array) setObject(java. sql.Struct) setObject(java. sql.Ref) setObject(java. net.URL) setObject (other class) Teradata Driver for the JDBC Interface User Guide 339 Appendix D: Data Type Conversions Data Type Conversions Table 340 Teradata Driver for the JDBC Interface User Guide APPENDIX E SQL Data Types Mapping This appendix provides information about how data is mapped between SQL and Java. SQL Data Types Mapping Table The following table defines how data is mapped between SQL and Java. The SQL data type is converted to or converted from corresponding Java data type, based on the type of parameter mapping. Java XSP defaults to simple mapping. Use the External Name clause to specify object mapping. IN Parameter OUT Parameter INOUT Parameter SQL Data Type Simple Map Object Map Simple Map Object Map Simple Map Object Map CHARACTER – java.lang.String – java.lang.String[] – java.lang.String[] VARCHAR – java.lang.String – java.lang.String[] – java.lang.String[] NUMERIC – java.math.BigDec imal – java.math.BigDecimal [] – java.math.BigDecimal[] DECIMAL – java.math.BigDec imal – java.math.BigDecimal [] – java.math.BigDecimal[] BIGINT long java.lang.Long long[] java.lang.Long[] long[] java.lang.Long[] SMALLINT short java.lang.Short short[] java.lang.Short[] short[] java.lang.Short[] INTEGER int java.lang.Integer int[] java.lang.Integer[] int[] java.lang.Integer[] REAL double java.lang.Double double[] java.lang.Double[] double[] java.lang.Double[] FLOAT double java.lang.Double double[] java.lang.Double[] double[] java.lang.Double[] DOUBLE PRECISION double java.lang.Double double[] java.lang.Double[] double[] java.lang.Double[] BYTE byte[] – byte[][] – byte[][] – VARBYTE byte[] – byte[][] – byte[][] – DATE – java.sql.Date – java.sql.Date[] – java.sql.Date[] Teradata Driver for the JDBC Interface User Guide 341 Appendix E: SQL Data Types Mapping SQL Data Types Mapping Table IN Parameter OUT Parameter INOUT Parameter SQL Data Type Simple Map Object Map Simple Map Object Map Simple Map Object Map TIME – java.sql.Time – java.sql.Time[] – java.sql.Time[] TIMESTAMP – java.sql.Timesta mp – java.sql.Timestamp[] – java.sql.Timestamp[] BYTEINT byte java.lang.Byte byte[] java.lang.Byte[] byte[] java.lang.Byte[] CLOB – java.sql.Clob – java.sql.Clob[] – java.sql.Clob[] BLOB – java.sql.Blob – java.sql.Blob[] – java.sql.Blob[] VARGRAPHI C – – – – – – GRAPHIC – – – – – – INTERVAL – java.lang.String – java.lang.String[] – java.lang.String[] UDT** – – – – – – 342 Teradata Driver for the JDBC Interface User Guide Glossary A ANSI: American National Standards Institute. ANSI maintains a standard for SQL. For information about Teradata compliance with ANSI SQL, see the SQL Reference: Fundamentals. Auto Commit: Auto commit is when the database automatically commits changes after executing each statement. B Binding: The act of associating a variable or other placeholder with an actual value. BLOB: Binary Large Object. A large database object that can be anything that does not require character-set conversion, including MIDI, MP3, PDF, and graphics. BLOBS can be up to 2 GB. C Catalog: According to the SQL-92 definition, catalogs are named collections of schemas in an SQL environment. CLOB: Character Large Object. A pure character-based large object in a database. It can be a large text file, HTML, RTF or other character-based file. A CLOB can be up 2 GB. See also BLOB and LOB. Connection: A connection is established when the user logs onto the DBS and ends when the user logs off the Teradata Database. Within the context of a connection, SQL statements are executed and results are returned. In this document, connection and session have the same meaning. D DataSource: A JDBC DataSource provides an alternative to obtaining connections from the Driver Manager. It also provides the ability to obtain pooled connections. J Java Language: Java is a class-based object-oriented language. It is platform-independent and used for Internet/Intranet development. JDBC: JDBC is a call-level SQL interface for Java. Its focus is on executing raw SQL statements and retrieving their results. JDBC is based on the X/Open’s SQL CLI. Teradata Driver for the JDBC Interface User Guide 343 Glossary L LOB: Large object. A database object that is large in size. LOBs can be up to 2 GB. There are two types of LOBs: CLOBs and BLOBs. CLOBs are character-based objects. BLOBs are binarybased objects. See also CLOB and BLOB. P Pooled Connection: A connection to the database that can be reused. Precision: The number of bits or digits representing a number. R Request: A request is composed up of one or more SQL statements. In host software, a message sent from an application program to Teradata Database. Resource File: A resource file is a file that stores all the locale specific messages for errors, warnings, traces, and so forth, in a pre-defined format. S Scale: The number of bits or digits representing the fractional part of a number. Schema: According to the SQL-92 definition, tables are contained in a higher level object call a schema. The full name of SQL-92 objects have three components: the catalog name, the schema name, and the object name. For example a table could be accessed using the following: catalog_name.schema_name.table_name. In Teradata Database there is no equivalent for the catalog name but the schema name maps to database name. In Teradata Database_ name.table_name would be equivalent to schema_name.table_name. Session: SPL: A session is a single connection with the Teradata Database. Stored Procedure Language. A language used to create stored procedures in a database. SQL: Structured Query Language. An industry-standard language for creating, updating, and querying RDBMSs. IBM developed SQL in the 1970s for use in System R. It is the default standard as well as being an ISO and an ANSI standard. It is often embedded in generalpurpose programming languages. A programming language used to communicate with Teradata Database. Statement: A single SQL command. A request for processing by Teradata Database. A statement consists of a keyword verb, optional phrases, and operands, and is processed as a single entity. T TDSP: Teradata Stored Procedures. 344 Teradata Driver for the JDBC Interface User Guide Glossary Transaction: A set of Teradata SQL statements executed as a unit. All of the statements must execute normally or else any changes made during the transaction are backed out and none of the remaining statements in the transaction are executed. Teradata Database supports ANSI and Teradata transaction semantics. Teradata Driver for the JDBC Interface User Guide 345 Glossary 346 Teradata Driver for the JDBC Interface User Guide Index A ACCOUNT= 44 addBatch() 191 addBatch(String sql) 252 addConnectionEventListener(ConnectionEventListner listener) 190 AIX 24 allProceduresAreCallable() 124 allTablesAreSelectable() 124 ALTER TABLE statements 327 architecture JDBC 27 three-tier 21 B beforeFirst() 206 Binary Large Object (BLOB) Interface Methods 94 C CallableStatement Methods 99, 107 cancel() 253 cancelRowUpdates() 206 catalogs 327 Character Large Object (CLOB) Interface Methods 96 character literals 328 characters 327 CHARSET 44 checking hosts file entries 317 clearBatch() 253 clearParameters() 191 clearWarnings() 107, 205, 206, 207, 253 close() 108, 190, 206, 253 column aliases 328 columnIndexes) 114, 256, 258 columnNames) 115, 256, 258 columns 328 commit() 108 COMPAT_DBS 44 COMPAT_GETSCHEMA 44 COMPAT_GETTABLE 44 COMPAT_ISAUTOINC 44 COMPAT_ISCURRENCY 44 COMPAT_ISDEFWRIT 44 COMPAT_ISREADONLY 44 Teradata Driver for the JDBC Interface User Guide COMPAT_ISSEARCH 44 COMPAT_ISSIGNED 44 COMPAT_ISWRITABLE 44 connection parameters 45 connectionClosed(ConnectionEvent event) 120 connectionErrorOccurred(ConnectionEvent event) 121 ConnectionEvent(PooledConnection con) 119 ConnectionEvent(PooledConnection con, SQLException ex) 119 CONVERT functions 328 createStatement() 108 createStatement(int resultSetType, int resultSetConcurrency) 108 cursors 328 D data definitions 329 data manipulation statements 329 DATABASE 44 database connection parameters 45 ACCOUNT 45 ACCOUNTID 45 CHARSET 46 COMPAT_DBS 46 COMPAT_GETSCHEMA 48 COMPAT_GETTABLE 48 COMPAT_ISAUTOINC 47 COMPAT_ISCURRENCY 47 COMPAT_ISDEFWRIT 48 COMPAT_ISREADONLY 47 COMPAT_ISSEARCH 47 COMPAT_ISSIGNED 47 COMPAT_ISWRITABLE 48 DATABASE 48 DBS_PORT 48 DEBUG 48 ENCRYPTDATA 49 featureProps 49 GOVERN 49 LOB_SUPPORT 49 LOB_TEMP_TABLE 49 LOG 50 LOGDATA 50 LOGMECH 51 NEW_PASSWORD 52 347 Index PARTITION 52 SESSIONS 53 SP_SPL 53 TMODE 53 TNANO 53 TSNANO 53 TYPE 54 USEXVIEWS 54 database connections 329 databases 328 dataDefinitionCausesTransactionCommit() 124 dataDefinitionIgnoredInTransactions() 124 date function 333 DBS_PORT 44 delete statements 329 deleteRow() 207 deletesAreDetected(int type) 124 deregisterDriver(Driver driver) 182 doesMaxRowSizeIncludeBlobs() 125 Driver Requirements 23 E ENCRYPTDATA 45 execute() 191 execute(String sql) 254 executeBatch() 254 executeQuery() 192 executeQuery(String sql) 257 executeUpdate() 192 executeUpdate(String sql) 255, 257 F findColumn(String columnName) 205, 207 G getACCOUNT() 265 getAsciiStream( ) 96 getAsciiStream(int columnIndex) 207 getAsciiStream(String columnName) 208 getAttributes(String catalog, String schemaPattern, String typeNamePattern, String attributeNamePattern) 125 getAutoCommit() 109 getBestRowIdentifier(String catalog, String schema, String table, int scope, boolean nullable) 127 getBigDecimal(int columnIndex) 208 getBigDecimal(int columnIndex, int scale) 209 getBigDecimal(int parameterIndex) 99 getBigDecimal(int parameterIndex, int scale) 100 getBigDecimal(String columnName) 209 getBigDecimal(String columnName, int scale) 209 getBinaryStream( ) 94 getBinaryStream(int columnIndex) 210 348 getBinaryStream(String columnName) 210 getBlob 211 getBlob(int i) 211 getBlob(String colName) 211 getBoolean(int columnIndex) 211 getBoolean(int parameterIndex) 100 getBoolean(String columnName) 212 getByte(int columnIndex) 212 getByte(int parameterIndex) 100 getByte(String columnName) 212 getBytes(int columnIndex) 213 getBytes(int parameterIndex) 101 getBytes(long pos, integer length) 94 getBytes(String columnName) 213 getCatalog() 109 getCatalogs() 129 getCatalogSeparator() 129 getCatalogTerm() 129 getCharacterStream( ) 96 getCharacterStream(int columnIndex) 213 getCharacterStream(String columnName) 214 getCharSet() 265 getClob(int i) 214 getClob(String colName) 214 getColumnClassName(int column) 249 getColumnCount() 249 getColumnDisplaySize(int column) 249 getColumnLabel(int column) 250 getColumnName(int column) 250 getColumns(String catalog, String schema, String tableName, String columnNamePattern) 130 getColumns(String catalog, String schemaPattern, String tableNamePattern, String columnNamePattern) 131 getColumnType(int column) 250 getColumnTypeName(int column) 251 getCOMPAT 265 getCOMPAT_DBS() 265 getCOMPAT_GETSCHEMA() 265 getCOMPAT_GETTABLE() 265 getCOMPAT_ISAUTOINC() 266 getCOMPAT_ISCURRENCY() 266 getCOMPAT_ISDEFWRIT() 266 getCOMPAT_ISREADONLY() 266 getCOMPAT_ISSEARCH() 266 getCOMPAT_ISSIGNED() 267 getCOMPAT_ISWRITABLE() 267 getConcurrency() 215 getConnection() 133, 180, 190, 259, 267 getConnection(java.lang.String username, java.lang.String password) 268 getConnection(String url) 183 getConnection(String url, Properties info) 183 getConnection(String url, String user, String password) 184 getConnection(String username, String password) 180 Teradata Driver for the JDBC Interface User Guide Index getCrossReference(String primaryCatalog, String primarySchema, String primaryTable, String foreignCatalog, String foreignSchema, String foreignTable) 134 getDatabase()/getdatabase()/getDATABASE() 268 getDatabaseMajorVersion() 137 getDatabaseMinorVersion() 137 getdatabaseName() 268 getDatabaseProductName() 137 getDatabaseProductVersion() 137 getdatasourceName() 268 getDate(int parameterIndex) 101 getDate(int parameterIndex, Calendar cal) 101 getDate(String columnIndex) 215 getDate(String columnIndex, Calendar cal) 216 getDate(String columnName) 215 getDate(String columnName, Calendar cal) 216 getDBS 268 getDBS_PORT() 268 getDefaultTransaction Isolation() 138 getdescription() 269 getDouble(int columnIndex) 217 getDouble(int parameterIndex) 102 getDouble(String columnName) 217 getDriver(String url) 184 getDriverMajorVersion() 138 getDriverMinorVersion() 138 getDriverName() 138 getDrivers() 184 getDriverVersion() 138 getDSName() 269 getENCRYPTDATA() 269 getExtraNameCharacters() 139 getFetchDirection() 218 getFetchRows() 269 getFetchSize() 218 getFloat(int columnIndex) 217 getFloat(int parameterIndex) 102 getFloat(String columnName) 218 getHoldability() 109 getIdentifierQuoteString() 139 getIndexInfo(String catalog, String schema, String table, boolean unique, boolean approximate) 140 getInt(int columnIndex) 218 getInt(int parameterIndex) 102 getInt(String columnName) 219 getLOB_SUPPORT() 269 getLOB_TEMP_TABLE() 270, 306 getLobData( ) 102 getLOG() 270 getLOGDATA() 270 getLoginTimeout() 121, 180, 185, 270 getLOGMECH() 270 getLogStream() 185 Teradata Driver for the JDBC Interface User Guide getLogWriter() 121, 181, 271 getLong(int columnIndex) 219 getLong(int parameterIndex) 103 getLong(String columnName) 219 getMaxBinaryLiteralLength() 141 getMaxCatalogNameLength() 142 getMaxCharLiteralLength() 142 getMaxColumnNameLength() 142 getMaxColumnsInGroupBy() 142 getMaxColumnsInIndex() 143 getMaxColumnsInOrderBy() 143 getMaxColumnsInSelect() 143 getMaxColumnsInTable() 143 getMaxConnections() 144 getMaxCursorNameLength() 144 getMaxFieldSize() 259 getMaxIndexLength() 144 getMaxProcedureNameLength() 144 getMaxRows() 260 getMaxRowSize() 145 getMaxSchemaNameLength() 145 getMaxStatementLength() 145 getMaxStatements() 145 getMaxTableNameLength() 146 getMaxTablesInSelect() 146 getMaxUserNameLength() 146 getMetaData() 109, 192, 220 getMoreResults() 260 getMoreResults(int current) 260 getNumericFunctions() 146 getObject(int columnIndex) 220 getObject(int parameterIndex) 103 getObject(String columnName) 220 getParameterClassName(int param) 189 getParameterCount() 186 getParameterMode(int param) 189 getParameterType(int param) 188 getParameterTypeName(int param) 188 getpassword() 271 getPooledConnection() 122 getPooledConnection(String username, String password) 122 getportNumber() 271 getPrecision(int column) 251 getPrecision(int param) 187 getPrimaryKeys(String catalog, String schema, String table) 146 getProcedureColumns(String catalog, String schemaPattern, String procedureNamePattern, String columnNamePattern) 147 getProcedures(String catalog, String schemaPattern, String procedureNamePattern) 149 getProcedureTerm() 150 getQueryTimeout() 261 349 Index getReference() 271 getResultSet() 261 getResultSetConcurrency() 262 getResultSetHoldability() 150, 262 getRow() 221 getScale(int column) 251 getScale(int param) 188 getSchemas() 150 getSchemaTerm() 151 getSearchStringEscape() 151 getServerName() 271 getShort(int columnIndex) 221 getShort(int parameterIndex) 103 getSP_SPL() 272 getspl() 272 getSQLException() 120 getSQLKeywords() 151 getStatement() 222 getString(int columnIndex) 222 getString(int parameterIndex) 104 getString(String columnName) 222 getStringFunctions() 151 getSubString(long pos, int length) 97 getSystemFunctions() 151 getTablePrivileges(String catalog, String schemaPattern, String tableNamePattern) 152 getTableTypes() 154 getTime(int columnIndex) 223 getTime(int columnIndex, Calendar cal) 223 getTime(int parameterIndex) 104 getTime(int parameterIndex, Calendar cal) 104 getTime(String columnName) 223 getTime(String columnName, Calendar cal) 224 getTimeDateFunctions() 154 getTimestamp(int columnIndex) 224 getTimestamp(int columnIndex, Calendar cal) 225 getTimestamp(int parameterIndex) 105 getTimestamp(int parameterIndex, Calendar cal) 105 getTimestamp(String columnName) 225 getTimestamp(String columnName, Calendar cal) 226 getTNANO() 272 getTransactionIsolation() 110 getTransactMode() 272 getTSNANO() 272 getType() 226 getTypeInfo() 155 getTypeMap() 110 getUnicodeStream(int columnIndex) 226 getUnicodeStream(String columnName) 227 getUpdateCount() 262 getURL() 157 getuser() 273 getUserName() 157 getUSEXVIEWS() 273 350 getVersionColumns(String catalog, String schema, string table) 158 getWarnings() 110, 228, 262 Glossary 343 GOVERN= 45 GROUP BY clauses 329 H HP-UX 24 I indexes 329 insertRow() 228 insertsAreDetected(int type) 159 isAfterLast() 228 isBeforeFirst() 228 isCatalogAtStart() 159 isClosed() 110 isFirst() 229 isLast() 229 isNullable(int column) 252 isNullable(int param) 187 isReadOnly() 111, 159 isSigned(int param) 187 J Java 21 applications 25 classes 27 database connectivity 21, 25 language 27 programs 21 Java Development Kit 23 Java External Stored Procedures 76 java.sql.Blob 25 Java.sql.CallableStatement 26 java.sql.Clob 25 java.sql.Connection JDBC interface 25 java.sql.DatabaseMetaData JDBC interface 25 java.sql.DataSource 25 java.sql.DriverManager JDBC interface 25 java.sql.ParameterMetaData 25 java.sql.PreparedStatement JDBC interface 26 java.sql.ResultSet JDBC interface 26 java.sql.ResultSetMetaData JDBC interface 26 java.sql.Statement JDBC interface 26 javax.sql.ConnectionEventListener 26 javax.sql.ConnectionPoolDataSource 26 javax.sql.PooledConnection 26 JDBC architecture 27 interface Teradata Driver for the JDBC Interface User Guide Index list of 25 Teradata driver 27 JDBC Driver Type 2 27 JDBC FastLoad 85 JDBC Monitor 87 JdbcRowSetImpl 65 JDK 23 joins 330 K KRB5 50 L last() 229 LDAP 50 length() BLOB 94 CLOB 97 LOB_SUPPORT 45 LOB_TEMP_TABLE= 45 LOG 45 LOGDATA 45 LOGMECH 45 M math functions 330 metadata features and functions 327 moveToCurrentRow() 230 moveToInsertRow() 230 multiple result sets 330 Multi-threading on AIX 5.1 64 N nativeSQL(String sql) 111 NEW_PASSWORD= 45 next() 230 null values 330 nullPlusNonNullIsNull() 160 nullsAreSortedAtEnd() 160 nullsAreSortedAtStart() 160 nullsAreSortedHigh() 160 nullsAreSortedLow() 160 O ORDER BY clauses 330 othersDeletesAreVisible(int type) 161 othersInsertsAreVisible(int type) 161 othersUpdatesAreVisible(int type) 161 ownDeletesAreVisible(int type) 162 Teradata Driver for the JDBC Interface User Guide ownInsertsAreVisible(int type) 162 ownUpdatesAreVisible(int type) 162 P parameters database connection 45 PARTITION= 45 prepareCall(String sql) 111 prepareCall(String sql, int resultSetType, int resultSetConcurrency) 112 prepareStatement(String sql) 112 prepareStatement(String sql, int autogeneratedKeys) 115 prepareStatement(String sql, int resultSetType, int resultSetConcurrency) 116 previous() 230 println(String message) 185 procedures 330 product names 331 product version numbers 3 Q Query Banding 39 syntax 40 R refreshRow() 231 registerDriver(Driver driver) 185 registerOutParameter(int parameterIndex, int sqlType) 105 registerOutParameter(int parameterIndex, int sqlType, int scale) 106 registerOutParameter(int parameterIndex, int sqlType, String typename) 106 relative(int rows) 231 removeConnectionEventListener(ConnectionEventListener listener) 190 rollback() 117 rowDeleted() 232 rowInserted() 232 rows 331 RowSet rows 65 rowUpdated() 232 S schemas 331 SELECT statements 331 Session Defaults Warning 55 Session Parameters 55 SESSIONS= 45 setACCOUNT(String accountId) 273 setAsciiStream(int parameterIndex, InputStream x, int 351 Index length) 193 setAutoCommit(boolean autoCommit) 117 setBigDecimal(int parameterIndex, BigDecimal x) 193 setBinaryStream(int parameterIndex, InputStream x, int length) 194 setBlob(int i, Blob x) 194 setBoolean(int parameterIndex, boolean x) 194 setByte(int parameterIndex, byte x) 195 setCatalog(String catalog) 118 setCharacterStream(int parameterIndex, Reader reader, int length) 195 setCharSet(java.lang.String CharSet) 273 setClob( int i, Clob x) 196 setCOMPAT_DBS() 273 setCOMPAT_GETSCHEMA() 274 setCOMPAT_GETTABLE() 274 setCOMPAT_ISAUTOINC() 274 setCOMPAT_ISCURRENCY() 274 setCOMPAT_ISDEFWRIT() 275 setCOMPAT_ISREADONLY() 275 setCOMPAT_ISSEARCH() 275 setCOMPAT_ISSIGNED() 275 setCOMPAT_ISWRITABLE() 276 setDatabaseName(java.lang.String databaseName) 276 setdatasourceName(java.lang.String databaseName) 276 setDate(int parameterIndex, Date x) 196 setDate(int parameterIndex, Date x, Calendar cal) 197 setDBS_PORT(java.lang.String dbsport) 276 setdescription(java.lang.String description) 277 setDouble(int parameterIndex, double x) 197 setDSName(java.lang.String DSName) 277 setENCRYPTDATA(java.lang.String encryptData) 277 setFetchRows(java.lang.String FetchRows) 278 setFloat(int parameterIndex, float x) 197 setInt(int parameterIndex, int x) 198 setLOB_SUPPORT(java.lang.String lobSupport) 278 setLOB_TEMP_TABLE(java.lang.String lobTempTable) 307 setLOB_TEMP_TABLE(java.lang.String) 278 setLOG(java.lang.String lobSupport) 278 setLOGDATA(java.lang.String LogData) 279 setLoginTimeout(int seconds) 122, 181, 186, 279 setLOGMECH(java.lang.String LogMech) 279 setLogStream(PrintStream out) 186 setLogWriter(java.io.PrintWriter out) 280 setLogWriter(PrintWriter out) 123, 181 setLong(int parameterIndex, long x) 198 setMaxFieldSize(int max) 263 setMaxRows(int max) 263 setNull(int parameterIndex, int sqlType) 198 setNull(int paramIndex, int sqlType, String typeName) 199 setObject(int parameterIndex, Object x) 200 setObject(int parameterIndex, Object x, int targetSqlType) 200 setObject(int parameterIndex, Object x, int targetSqlType, int 352 scale) 200 setpassword(java.lang.String password) 280 setportNumber(java.lang.String portNumber) 280 setQueryTimeout(int seconds) 263 setServerName(java.lang.String serverName) 281 setShort(int parameterIndex, short x) 201 setSpl(java.lang.String spl) 281 setspl(java.lang.String spl) 281 setString(int parameterIndex, String x) 202 setTime(int parameterIndex, Time x) 202 setTime(int parameterIndex, Time x, Calendar cal) 202 setTimestamp(int parameterIndex, Timestamp x) 203 setTimestamp(int parameterIndex, Timestamp x, Calendar cal) 203 setTMODE(java.lang.String TransactMode) 281 setTNANO(java.lang.String tnanoVal) 282 setTransactionIsolation(int level) 118 setTransactMode(java.lang.String TransactMode) 282 setTypeMap(Map> map) 118 setUnicodeStream(int parameterIndex, InputStream x, int length) 204 setuser(java.lang.String user) 282 setUseXVIEWS(java.lang.String useXviews) 283 software releases supported 3 SP_SPL 45 SQL and Java data mapping 341 SQL statements 332 Stored Procedure Dynamic Result Set 85 storesLowerCaseIdentifiers() 163 storesLowerCaseQuotedIdentifiers() 163 storesMixedCaseIdentifiers() 163 storesMixedCaseQuotedIdentifiers() 163 storesUpperCaseIdentifiers() 164 storesUpperCaseQuotedIdentifiers() 164 strings 332 subqueries 332 Sun Solaris SPARC 23 supportsAlterTableWithAddColumn() 164 supportsAlterTableWithDropColumn() 164 supportsANSI92EntryLevelSQL() 165 supportsANSI92FullSQL() 165 supportsANSI92IntermediateSQL() 165 supportsBatchUpdates() 165 supportsCatalogsInDataManipulation() 165 supportsCatalogsInIndexDefinitions() 166 supportsCatalogsInPrivilegeDefinitions() 166 supportsCatalogsInProcedureCalls() 166 supportsCatalogsInTableDefinitions() 166 supportsColumnAliasing() 167 supportsConvert() 167 supportsConvert(int fromType, int toType) 167 supportsCoreSQLGrammar() 167 supportsCorrelatedSubqueries() 168 Teradata Driver for the JDBC Interface User Guide Index supportsDataDefinitionAndDataManipulationTransactions( ) 168 supportsDataManipulationTransactionsOnly() 168 supportsDifferentTableCorrelationNames() 168 supportsExpressionsInOrderBy() 169 supportsExtendedSQLGrammar() 169 supportsFullOuterJoins() 169 supportsGroupBy() 169 supportsGroupByBeyondSelect() 170 supportsGroupByUnrelated() 170 supportsIntegrityEnhancementFacility() 170 supportsLikeEscapeClause( 170 supportsLimitedOuterJoins() 170 supportsMinimumSQLGrammar() 171 supportsMixedCaseIdentifiers() 171 supportsMixedCaseQuotedIdentifiers() 171 supportsMultipleOpenResults() 172 supportsMultipleResultSets() 172 supportsMultipleTransactions() 172 supportsNonNullableColumns() 172 supportsOpenCursorsAcrossCommit() 172 supportsOpenCursorsAcrossRollback() 173 supportsOpenStatementsAcrossCommit() 173 supportsOpenStatementsAcrossRollback() 173 supportsOrderByUnrelated() 173 supportsOuterJoins() 174 supportsPositionedDelete() 174 supportsPositionedUpdate() 174 supportsResultSetConcurrency(int type, int concurrency) 174 supportsResultSetHoldability(int holdability) 175 supportsResultSetType(int type) 175 supportsSchemasInDataManipulation() 175 supportsSchemasInIndexDefinitions() 175 supportsSchemasInPrivilegeDefinitions() 176 supportsSchemasInProcedureCalls() 176 supportsSchemasInTableDefinitions() 176 supportsSelectForUpdate() 176 supportsStoredProcedures() 176 supportsSubqueriesInComparisons() 177 supportsSubqueriesInExists() 177 supportsSubqueriesInIns() 177 supportsSubqueriesInQuantifieds() 177 supportsTableCorrelationNames() 178 supportsTransactionIsolationLevel(int level) 178 supportsTransactions() 178 supportsUnion() 178 supportsUnionAll() 179 system functions 333 T table correlation names 333 tables 333 Teradata Driver for the JDBC Interface User Guide TD1 50 TD2 50 Teradata 27 Teradata Driver for the JDBC interface 27 Teradata terminology 333 three-tier architecture 21 time function 333 TMODE 45 transactions 333 troubleshooting 309 TSNANO 45 two-tier architecture depicted 27 TYPE= 45 types) 153, 156 U Updatable Result Set 80 UPDATE statements 334 updateArray(int columnIndex, Array x) (JDBC 3.0) 302 updateArray(String columnName, Array x) (JDBC 3.0) 302 updateAsciiStream(int columnIndex, InputStream x, int length) 232 updateAsciiStream(String columnName, InputStream x, int length) 233 updateBigDecimal(int columnIndex, BigDecimal x) 233 updateBigDecimal(String columnName, BigDecimal x) 234 updateBinaryStream(int columnIndex, InputStream x, int length) 234 updateBinaryStream(String columnName, InputStream x, int length) 234 updateBlob(int columnIndex, Blob x) 235 updateBlob(String columnName, Blob x) 235 updateBoolean(int columnIndex, boolean x) (JDBC 2.0) 302 updateBoolean(String columnName, boolean x) (JDBC 2.0) 302 updateByte(int columnIndex, byte x) 236 updateByte(String columnName, byte x) 236 updateCharacterStream(int columnIndex, Reader x, int length) 237 updateCharacterStream(String columnName, Reader x, int length) 238 updateClob(int columnIndex, Clob x) 238 updateClob(String columnName, Clob x) 238 updateDate(int columnIndex, Date x) 239 updateDate(String columnName, Date x) 239 updateDouble(int columnIndex, double x) 240 updateDouble(String columnName, double x) 240 updateFloat(int columnIndex, float x) 240 updateFloat(String columnName, float x) 241 updateInt(int columnIndex, int x) 241 updateInt(String columnName, int x) 242 353 Index updateLong(int columnIndex, long x) 242 updateLong(String columnName, long x) 242 updateNull(int columnIndex) 243 updateNull(String columnName) 243 updateObject(int columnIndex, Object x) 243 updateObject(int columnIndex, Object x, int scale) 244 updateObject(String columnName, Object x) 244 updateObject(String columnName, Object x, int scale) 245 updateRef(int columnIndex, Ref x) (JDBC 3.0) 303 updateRef(String columnName, Ref x) (JDBC 3.0) 303 updateRow() 245 updatesAreDetected(int type) 179 updateShort(int columnIndex, short x) 245 updateShort(String columnName, short x) 246 updateString(int columnIndex, String x) 246 updateString(String columnName, String x) 246 updateTime(int columnIndex, Time x) 247 updateTime(String columnName, Time x) 247 updateTimestamp(int columnIndex, Timestamp x) 248 updateTimestamp(String columnName, Timestamp x) 248 user names 333, 334 usesLocalFilePerTable() 179 usesLocalFiles() 179 USEXVIEWS= 45 V version numbers 3 W wasNull() 107, 248 Windows 23 X x) 195, 236, 237 354 Teradata Driver for the JDBC Interface User Guide
