Teradata JDBC Driver User Guide

Teradata JDBC DriverUser Guide

Release 13.00.00B035-2403-088ASeptember 2008

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, RACF, Tivoli, z/OS, and z/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 trademark 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-2008 by Teradata Corporation. All Rights Reserved.

mailto:[email protected]

Preface

Purpose

This book provides information about Teradata JDBC Driver, 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 JDBC Driver 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 13.00.00

• Teradata Tools and Utilities 13.00.00

• Teradata JDBC Driver Release 13.00.00

Note: See “Determining the Current Version of the Teradata JDBC Driver” on page 23 to verify the Teradata JDBC Driver version number.

To locate detailed supported-release information:

1 Go to http://www.info.teradata.com/.

2 Under Online Publications, click General Search.

3 Type 3119 in the Publication Product ID box.

4 Under Sort By, select Date.

5 Click Search.

6 Open the version of the Teradata Tools and Utilities ##.##.## Supported Platforms and Product Versions spreadsheet associated with this release.

The spreadsheet includes supported Teradata Database versions, platforms, and product release numbers.

Teradata JDBC Driver User Guide 3

http://www.info.teradata.com/

PrefacePrerequisites

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.

Date and Release Description

September 2008

13.00.00

Updates to the TTU 13.0 release of Teradata JDBC Driver User Guide have been applied.

August 2008

13.00.00

• Changed product name from Teradata Driver for the JDBC Interface to Teradata JDBC Driver

• Added new sections to Chapter 2: Session Time Zone, Multi-Statement Requests, Teradata Database Macros, and Creating User-Defined Functions and External Stored Procedures

• Changed code in Appendix B: Troubleshooting to reflect improved JDBC FastLoad exception handling of PreparedStatement.executeBatch and Connection rollback

• Added information in the “Making a Teradata Database Connection” section regarding the LOB_SUPPORT database connection parameter

• Added information in the “Making a Teradata Database Connection” section regarding the TNANO and TSNANO database connection parameters and JDBC FastLoad connections. Removed text in the “Enabling JDBC FastLoad” section concerning the TNANO and TSNANO connection parameters.

• Added information to “Troubleshooting JDBC FastLoad” in Appendix B

• Removed references to tdgssjava.jar in Chapter 2 and Appendix B

• Updated login time-out functionality information; use value set by DriverManager.setLoginTimeout or DataSource.setLoginTimeout

• Updated references to MVS operating system to z/OS in Chapter 2

• Added support information for JDBC FastExport

• Removed KATAKANAEBCDIC listing in Chapter 2

• Added Session DateForm section in Chapter 2

4 Teradata JDBC Driver User Guide

PrefaceAdditional Information

Additional Information

Additional information that supports this product and Teradata Tools and Utilities is available at the web sites listed in the table that follows. 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.

August 2008 (continued)

13.00.00

• Added Limitations section to Java External Stored Procedures section in Chapter 2

• Incorporated information from client UDT/UDM Orange Book. New “User-Defined Types” section added in Chapter 2

Date and Release Description

Type of Information Description Access to Information

Release overview

Late information

Use the Release Definition for the following information:

• Overview of all of the products in the release

• Information received too late to be included in the manuals

• Operating systems and Teradata Database versions that are certified to work with each product

• Version numbers of each product and the documentation for each product

• Information about available training and the support center


2 Under Online Publications, click General Search.

3 Type 2029 in the Publication Product ID box.

4 Click Search.

5 Select the appropriate Release Definition from the search results.




Additional product information

Use the Teradata Information Products web site to view or download specific manuals that supply related or additional information to this manual.


2 Under the Online Publications subcategory, Browse by Category, click Data Warehousing.

3 Do one of the following:

• For a list of Teradata Tools and Utilities documents, click Teradata Tools and Utilities, and then select an item under Releases or Products.

• Select a link to any of the data warehousing publications categories listed.

Specific books related to Teradata JDBC Driver are as follows:

• Teradata Manager Installation GuideB035-2402-mmyA

• Teradata JDBC Driver User GuideB035-2403-mmyA

• Teradata MultiLoad ReferenceB035-2409-mmyA

• Teradata FastExport ReferenceB035-2410-mmyA

• Basic Teradata Query ReferenceB035-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 ReferenceB035-2411-mmyA

• Teradata Archive/Recovery Utility ReferenceB035-2412-mmyA





• (Continued from the bulleted list above)

• Teradata Manager User GuideB035-2428-mmyA

• Teradata System Emulation Tool User GuideB035-2492-mmyA

• OLE DB Provider for Teradata Installation and User GuideB035-2498-mmyA

• Teradata Administrator User GuideB035-2502-mmyA

• Teradata Statistics Wizard User GuideB035-2503-mmyA

• Teradata SQL Assistant/Web Edition User GuideB035-2505-mmyA

• Teradata Index Wizard User GuideB035-2506-mmyA

• Teradata SQL Assistant for Microsoft Windows User GuideB035-2430-mmyA

• Teradata Access Module for Tivoli Installation and User GuideB035-2444-mmyA

• Teradata Tools and Utilities Installation Guide for UNIX and LinuxB035-2459-mmyA

• Teradata Dynamic Workload Manager User GuideB035-2513-mmyA

• Teradata Workload Analyzer User GuideB035-2514-mmyA

• Teradata Parallel Data Pump ReferenceB035-3021-mmyA

• ODBC Driver for Teradata User GuideB035-2509-mmyA

• Teradata Director Program ReferenceB035-2510-mmyA

• Teradata Query Scheduler Administrator GuideB035-2511-mmyA

• Teradata Query Scheduler User GuideB035-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.


2 Under the Online Publications subcategory, Browse by Category, click Data Warehousing.

3 Click CD-ROM List and Images.

4 Follow the ordering instructions.





Ordering information for manuals

Use the Teradata Information Products web site to order printed versions of manuals.


2 Under Print & CD Publications, click How to Order.

3 Follow the ordering instructions.

General information about Teradata

The Teradata home page provides links to numerous sources of information about Teradata. Links include:

• Executive reports, case studies of customer experiences with Teradata, and thought leadership

• Technical information, solutions, and expert advice

• Press releases, mentions, and media resources

1 Go to Teradata.com.

2 Select a link.




http://www.teradata.com

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Application Server Compatibility Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Driver Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Downloading the Java Development Kit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Determining the Current Version of the Teradata JDBC Driver . . . . . . . . . . . . . . . . . . . 23

JDBC Interface Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Teradata JDBC Driver Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Type 4 JDBC Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

The JDBC Type 4 Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

How It Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Benefits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Support for Internationalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Java Virtual Machine Locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Data Flow From a Java Application to Teradata JDBC Driver . . . . . . . . . . . . . . . . . . . . . 27

Data Flow Between the Teradata JDBC Driver and Teradata Database . . . . . . . . . . . . . . 29

Character Mapping Differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Data Flow From the Teradata JDBC Driver to a Java Application . . . . . . . . . . . . . . . . . . 31

Modifying SQL Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Null Expressions Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Correcting the SQL Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32


Table of Contents

Chapter 2: Using the Teradata JDBC Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33

JDBC Escape Clauses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34

Date and Time Literals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34

JDBC Scalar Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34

LIKE Predicate Escape Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36

Outer Joins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37

Calls to Stored Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37

Query Banding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37

Why is Query Banding Needed? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38

Use Case Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38

Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39

Recommended QueryBand Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39

Uses for the QueryBand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40

Importing the SQL Package and Loading the Teradata JDBC Driver . . . . . . . . . . . . . . . . . . . .40

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40

Making a Teradata Database Connection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41

JDBC Type 3 Driver to Type 4 Driver Migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41

The Type 4 Connection URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42

Data Source Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53

Type 4 COP Discovery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54

LogonSource Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56

Example LogonSource value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56

Field 4 - TDPID (target Teradata Database hostname) Field . . . . . . . . . . . . . . . . . . . . . . .57

Field 5 - Client Process ID/Thread ID Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57

Field 6 - Client Process User Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58

Field 7 - Client Program Name Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58

Field 8 - LogonSource string version 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58

Program Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58

Converting Sample files to EBCDIC for z/OS USS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58

Running a Sample Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59

Running on Sun Solaris SPARC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59

Date, Time, Timestamp Values and Time Zones. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60

Session DateForm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61

Receiving DATE Values from the Teradata Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62

Sending DATE Values to the Teradata Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62

Session Time Zone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63

Stored Procedure TIME and TIMESTAMP INOUT Parameters. . . . . . . . . . . . . . . . . . . . . . . .66

Multi-Statement Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67

Teradata Database Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67


Table of Contents

Creating User-Defined Functions and External Stored Procedures. . . . . . . . . . . . . . . . . . . . . 67

User-Defined Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

External Stored Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Source File Locations for JDBC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

User-Defined Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Updatable LOBs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Temporary Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Connection Parameter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Update LOB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

SQL Literals and SQL Injection Attacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Multi-Threading Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Multi-threading on IBM AIX 5.1 and Using 64-bit JDK on Microsoft Windows . . . . . . 74

Using Type 4 Driver with ResultSetMetaData Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Using Type 4 Driver with Sun JDK 5.0 Implementation of JDBC RowSet Interface . . . . . . . 75

Encryption, Authentication, and Authorization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

URL and DataSource Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Meeting Kerberos Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Server-Side Default Authentication Mechanism. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

C and Java Application Sharing of XML Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Generated Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Multi-Statement Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

PreparedStatement Batch Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Insert-Select Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Exceptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Upsert Statements are not Supported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

ParameterMetaData and Ambiguous Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Java External Stored Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

JAR Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

Transferring Java XSP From the Client to the DBS Server. . . . . . . . . . . . . . . . . . . . . . . . . 87

Defining the SQL Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Parameter Usage Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Default Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Invoking a Java XSP from JDBC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Transaction Semantics and Java XSPs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Updatable Result Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Making a Result Set Updatable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Non-updatable Result Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Inner Joins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Outer Joins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Using Updatable Result Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92


Table of Contents

Result Set Type and Concurrency Upgrading and Downgrading . . . . . . . . . . . . . . . . . . . .93

Exceptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94

Stored Procedure Dynamic Result Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95

Special Floating Point Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95

PreparedStatement Batch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96

JDBC FastLoad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96

Enabling JDBC FastLoad. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96

Considerations When Using JDBC FastLoad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97

JDBC Data Types Supported by JDBC FastLoad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98

JDBC Escape Functions in Support of JDBC FastLoad . . . . . . . . . . . . . . . . . . . . . . . . . . . .98

JDBC FastExport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98

Enabling JDBC FastExport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98

Considerations when Using JDBC FastExport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99

JDBC Data Types Supported by JDBC FastExport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99

JDBC Escape Functions in Support of JDBC FastExport . . . . . . . . . . . . . . . . . . . . . . . . . . .99

JDBC Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100

Enabling JDBC Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100

Considerations When Using JDBC Monitor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100

JDBC Data Types Supported by JDBC Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101

Teradata Database PM/API Statements Supported by JDBC Monitor. . . . . . . . . . . . . . .101

Chapter 3: JDBC Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105

BLOB Interface Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106

Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106

CLOB Interface Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108

Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108

CallableStatement Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111

Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111

Connection Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119

Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119

ConnectionEvent Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130

Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130

ConnectionEventListener Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131


Table of Contents

Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

ConnectionPoolDataSource Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

DatabaseMetaData Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

DataSource Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

DriverManager Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

ParameterMetaData Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

PooledConnection Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

PreparedStatement Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

ResultSet Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Statement Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

TeraDataSource Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

Appendix A: Supported JDBC Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

Supported Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

JDBC BLOB Interface Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288

JDBC CLOB Interface Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288

JDBC CallableStatement Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289


Table of Contents

JDBC Connection Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .290

JDBC ConnectionEvent Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .291

JDBC ConnectionEventListener Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .291

JDBC ConnectionPoolDataSource Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .291

JDBC DatabaseMetaData Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .291

JDBC DataSource Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .297

JDBC DriverManager Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .297

JDBC ParameterMetaData Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .298

JDBC PooledConnection Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .299

JDBC PreparedStatement Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .299

JDBC ResultSetMetadata Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .300

JDBC ResultSet Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .301

JDBC Statement Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .306

TeraDataSource Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .307

Appendix B: Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .311

Invalid UserID, Password, or Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .311

Numeric Data Truncation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .312

Character Export Width. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .312

BigDecimal Behavior for toString When Running on J2SE 5.0 . . . . . . . . . . . . . . . . . . . . . . . .312

Transaction Isolation, Concurrency, and Deadlock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .313

Create and Drop. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .313

JDBC FastLoad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .313

Transaction Isolation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .313

Large Object Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .314

Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .314

Number of LOB Columns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .314

LOB Size Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .314

Response Limit Exceeded Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .314

Checking the Environment Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .316

CLASSPATH. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .316

Troubleshooting COP Discovery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .316

DNS and Hosts File Entries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .316

Improving Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .317

Java HotSpot Server Virtual Machine Error on Linux Platform . . . . . . . . . . . . . . . . . . . . . . .319

Troubleshooting Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .320

Troubleshooting Kerberos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .320

LDAP Authentication Not Supported on z/OS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .321


Table of Contents

UserId, Password, or Account is Invalid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322

Troubleshooting JDBC FastLoad. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322

Troubleshooting JDBC FastExport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323

Troubleshooting JDBC Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324

USEXViews=ON Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

Slow Logon on Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326

Using a Command Line Argument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

Changing /dev/random to be a symbolic link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

Appendix C: Metadata Features and Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

Issues and Answers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

Appendix D: Data Type Conversions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337

Data Type Conversions Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337

Appendix E: SQL Data Types Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343

SQL Data Types Mapping Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349


Table of Contents


List of Figures

Figure 1: JDBC Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Figure 2: JDBC Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Figure 3: JDBC Type 4 Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26


List of Figures


List of Tables

Table 1: Java Development Kit (JDK) Version. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Table 2: JDBC Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Table 3: Character Set Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Table 4: Internal Unicode Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Table 5: Date and Time Literals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Table 6: Numeric, String, and Time and Date Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Table 7: System Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Table 8: Conversion Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Table 9: URL String. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Table 10: Database Connection Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Table 11: Determining Data Values Stored in a TIME or TIMESTAMP Destination . . . . . . 64

Table 12: JDBC Object Thread Safety . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Table 13: URL and DataSource Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Table 14: Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Table 15: Data Type Ambiguous or Unknown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Table 16: Data Type Ambiguous or Unknown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

Table 17: Insert Performance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Table 18: IDENTIFY Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Table 19: MONITOR PHYSICAL CONFIG Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Table 20: MONITOR PHYSICAL RESOURCE Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Table 21: MONITOR PHYSICAL SUMMARY Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Table 22: MONITOR SESSION Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Table 23: MONITOR SQL Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Table 24: MONITOR VERSION Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Table 25: MONITOR VIRTUAL CONFIG Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Table 26: MONITOR VIRTUAL RESOURCE Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Table 27: MONITOR VIRTUAL SUMMARY Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Table 28: SET SESSION RATE Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Table 29: TDWM STATISTICS Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Table 30: TDWM SUMMARY Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Table 31: JDBC BLOB Interface Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288

Table 32: JDBC CLOB Interface Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288


List of Tables

Table 33: JDBC CallableStatement Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .289

Table 34: JDBC Connection Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .290

Table 35: JDBC ConnectionEvent Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .291

Table 36: JDBC ConnectionEventListener Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .291

Table 37: JDBC ConnectionPoolDataSource Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .291

Table 38: JDBC DatabaseMetaData Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .291

Table 39: JDBC DataSource Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .297

Table 40: JDBC DriverManager Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .297

Table 41: JDBC ParameterMetadata Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .298

Table 42: JDBC PooledConnection Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .299

Table 43: JDBC PreparedStatement Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .299

Table 44: JDBC ResultSetMetadata Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .300

Table 45: JDBC ResultSet Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .301

Table 46: JDBC Statement Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .306

Table 47: TeraDataSource Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .307

Table 48: Metadata Features and Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .329

Table 49: Data Type Conversions Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .337


CHAPTER 1

Overview

This chapter describes Java Database Connectivity (JDBC), the Teradata JDBC Driver, 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 JDBC Driver Description

• The JDBC Type 4 Architecture

• Support for Internationalization

• Modifying SQL Statements

What’s New

• Product name changed to Teradata JDBC Driver User Guide

• JDBC FastExport enables efficient transfer of large amounts of data from tables and views

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.

• 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.

• If executeBatch is used where one or more of the SQL statements return a result set, then an SQLException is thrown.


Chapter 1: OverviewApplication Server Compatibility Documentation

Application Server Compatibility Documentation

Application server compatibility documentation is available from http://www.teradata.com Teradata Download Center in the Teradata JDBC Driver section. The application server compatibility documentation lists the application server versions supported by each release of the Teradata JDBC Driver, and includes detailed instructions for how to configure Data Source and Connection Pools within each supported application server.

As support is added for more application server versions, the Teradata Download Center will be updated to include more application server compatibility documentation. Check with the Teradata Download Center regularly for updates.

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 XX.XX.XX Supported and Certified Versions, B035-3119-mmyK. This spreadsheet shows version numbers and platform information for all supported Teradata Tools and Utilities products and is availableat http://www.info.teradata.com.

Downloading the Java Development Kit

To start Java development after the Teradata JDBC Driver is installed, download the Java Development Kit (JDK). Table 1 includes the supported versions of JDK:

Table 1: Java Development Kit (JDK) Version

Operating System JDK Version

Microsoft Windows (2000, Server 2003, XP, and Vista)

JDK 1.4 , JDK 5.0, or JDK 6.0 from Sun JDK 5.0 is certified for Windows 32-bit.

JDK 5.0 is certified for Windows XP Professional x64 using EM64T

JDK 6.0 is certified for Windows 64-bit

Sun Solaris JDK 1.4, JDK 5.0, or JDK 6.0 from Sun JDK 5.0 is certified for Solaris 10 32-bit and 64-bit.

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, JDK 5.0, or JDK 6.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


http://www.info.teradata.com


http://www.hp.com/products1/unix/java

http://www-106.ibm.com/developerworks/java/jdk/?dwzone=java

Chapter 1: OverviewDriver Requirements

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 Teradata JDBC Driver

Windows

To determine the currently installed version of the Teradata JDBC Driver 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.MFtype META-INF\MANIFEST.MF

UNIX and Linux

To determine the currently installed version of the Teradata JDBC Driver 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.MFcat META-INF/MANIFEST.MF

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, JDK 5.0, or JDK 6.0 from Sun, or

JDK 1.4, JDK 5.0, or JDK 6.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.

JDK 6.0 is certified for Linux 64-bit.

Table 1: Java Development Kit (JDK) Version (continued)

Operating System JDK Version






Chapter 1: OverviewJDBC 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

2403B003

Driver Manageror DataSource

Connection Connection ConnectionConnection Connection

Statement DatabaseMetaData

CallableStatement

PreparedStatement

ResultSet ResultSetResultSet

ResultSetMetaData

Statement

ResultSet

PreparedStatement

ParameterMetaData

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


Chapter 1: OverviewJDBC Interface 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.

Table 2: JDBC Interfaces (continued)

Interface Name Description


Chapter 1: OverviewTeradata JDBC Driver Description

Teradata JDBC Driver Description

The Teradata JDBC Driver 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

Type 4 JDBC Driver

The Type 4 JDBC driver communicates directly with the Teradata Database.

The JDBC Type 4 Architecture

Description

The Teradata JDBC Driver uses a two-tier architecture to access the Teradata Database as shown in Figure 3.

Figure 3: JDBC Type 4 Architecture

Java Application

JDBC API

JDBC Driver Manager

JDBC Driver API

Type 4 Driver

Teradata Database

2403B001

Client Computer

Java Program

Teradata JDBCDriver

2403A004

Teradata Database


Chapter 1: OverviewSupport for Internationalization

How It Works

The Teradata JDBC Driver is platform-independent and can be used on any system that has a supported Java Virtual Machine (JVM) installed.

Java classes of the Teradata JDBC Driver 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 JDBC Driver provides support for the Japanese locale, such that the message text of Teradata JDBC Driver exceptions is provided in Japanese, when the Japanese locale is used for the JVM.

This applies only to Teradata JDBC Driver 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 JDBC Driver exceptions is provided in English for all locales other than the Japanese locale.

Data Flow From a Java Application to Teradata JDBC Driver

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 JDBC Driver 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 JDBC Driver as java.lang.String objects, the Teradata JDBC Driver does not convert from non-Unicode to Unicode characters, because java.lang.String objects always contain Unicode characters.



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 JDBC Driver.

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:



prepstmt.setAsciiStream(columnIndex, new FileInputStream("ascii.txt"))

Data Flow Between the Teradata JDBC Driver and Teradata Database

The Teradata JDBC Driver 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 JDBC Driver 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

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

LATIN1_0A ISO8859_1

LATIN1252_0A Cp1252

LATIN9_0A ISO8859_15_FDIS

SCHEBCDIC935_2IJ Cp935

SCHGB2312_1T0 EUC_CN



Although the CLIENT_CHARSET connection parameter can be used to override the Teradata JDBC Driver 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

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 correctly, since there are multiple Unicode character translations for the SJIS, EUC, and EBCDIC code points for the WAVE DASH and MINUS SIGN characters.

TCHBIG5_1R0 BIG5

TCHEBCDIC937_3IB Cp937

Table 3: Character Set Mapping (continued)

Teradata Session Character Set Java Character Set

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


Chapter 1: OverviewModifying SQL Statements

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 JDBC Driver 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 JDBC Driver 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 non-ASCII character data.

Modifying SQL Statements

Teradata JDBC Driver 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 JDBC Driver 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

Note that this statement never returns any rows because null is never equal to anything including itself.

The problem was fixed in the Teradata JDBC Driver Release 3.2, but the fix might potentially change the output of some applications.


Chapter 1: OverviewModifying SQL Statements

Null Expressions Policy

In SQL Functions, Operators, Expressions, and Predicates, 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 JDBC Driver 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.


CHAPTER 2

Using the Teradata JDBC Driver

This chapter describes using the Teradata JDBC Driver software in Java programs, and guides you through the process of getting the Teradata JDBC Driver running on site:

• JDBC Escape Clauses

• Query Banding

• Importing the SQL Package and Loading the Teradata JDBC Driver

• Making a Teradata Database Connection

• LogonSource Format

• Program Examples

• Running a Sample Application

• Date, Time, Timestamp Values and Time Zones

• Session DateForm

• Session Time Zone

• Stored Procedure TIME and TIMESTAMP INOUT Parameters

• Multi-Statement Requests

• Teradata Database Macros

• Creating User-Defined Functions and External Stored Procedures

• User-Defined Types

• Encryption, Authentication, and Authorization

• Generated Keys

• ParameterMetaData and Ambiguous Types

• Java External Stored Procedures

• Updatable Result Set

• Stored Procedure Dynamic Result Set

• JDBC FastLoad

• JDBC FastExport

• JDBC Monitor


Chapter 2: Using the Teradata JDBC DriverJDBC Escape Clauses

JDBC Escape Clauses

When JDBC escape clause processing is enabled, the Teradata JDBC Driver 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:

{keyword . . . parameters . . . }

Teradata JDBC Driver 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:

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 JDBC Driver:

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...]



System Functions

Table 7 lists the system functions available.

Table 6: Numeric, String, and Time and Date Functions

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)

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) WEEK(date)

TAN(float) YEAR(date)



Conversion FunctionsCONVERT(value, SQLtype)

where SQLtype is one of the types listed in Table 8:

LIKE Predicate Escape Characters

Teradata JDBC Driver 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.

Table 7: System Functions

System Functions

DATABASE()

IFNULL(expression, value)

USER()

Table 8: Conversion Functions

Conversion Functions

DATE

DECIMAL

DOUBLE

INTEGER

FLOAT

LONGVARCHAR

SMALLINT

TIME

TIMESTAMP

TINYINT

VARBINARY

VARCHAR

CHAR

BINARY


Chapter 2: Using the Teradata JDBC DriverQuery Banding

Outer Joins

The Teradata JDBC Driver 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:

{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 JDBC Driver 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 JDBC Driver 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 JDBC Driver.

Applications that inadvertently relied on the behavior of previous Teradata JDBC Driver 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 introduced 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 charge back, 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

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 end-users 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:

• 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)

• 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


Chapter 2: Using the Teradata JDBC DriverImporting the SQL Package and Loading the Teradata JDBC Driver

• 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.

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 http://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 http://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 JDBC Driver

Introduction

The JDBC application must have the SQL Interface package imported and the Teradata JDBC Driver loaded.




Chapter 2: Using the Teradata JDBC DriverMaking a Teradata Database Connection

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 JDBC Driver

1 Verify that the following Teradata files are on the Java development platform:

• terajdbc4.jar

• tdgssconfig.jar

2 Check CLASSPATH to see if it includes the following java archive files:

• terajdbc4.jar

• tdgssconfig.jar

3 Place the following line near the top of the program:

import java.sql.*;

4 Use the following statement to load and register the Teradata JDBC Driver:

Class.forName(“com.teradata.jdbc.TeraDriver”);

Making a Teradata Database Connection

JDBC Type 3 Driver to Type 4 Driver Migration

The Type 3 Teradata JDBC Driver 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 JDBC Driver.

To do this, change the application’s connection Universal Resource Locator (URL) as follows:

JDBC Type 3: jdbc:teradata://gwhost:port/dbshostJDBC Type 4: 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 JDBC Driver 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.

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 JDBC Driver 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 z/OS.

• 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

• DATABASE=default database name

• DBS_PORT=number



Table 10 lists the Database Connection parameters.

• 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/FASTEXPORT}

• USEXVIEWS={ON/OFF}

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.

Table 9: URL String (continued)

Syntax Element 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 JDBC Driver 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 z/OS.

The default value is set to ASCII.

Table 10: Database Connection Parameters (continued)




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_ISAUTOINCCOMPAT_ISCURRENCY COMPAT_ISSIGNEDCOMPAT_ISSEARCHCOMPAT_ISREADONLYCOMPAT_ISWRITABLECOMPAT_ISDEFWRITCOMPAT_GETSCHEMACOMPAT_GETTABLE

to call the following ResultSetMetaData methods:

isAutoIncrement() isCurrency()isSigned()isSearchable()isReadOnly()isWritable()isDefinitelyWritable()getSchemaName()getTableName().

Otherwise, DriverManager.getConnection() throws an SQLException.

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.

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.


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.


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.


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.

Note: The DATABASE connection parameter works normally for a user with an expired password when the NEW_PASSWORD connection parameter is also specified. However, the DATABASE connection parameter has no effect for a conditional connection that is established for a user with an expired password when the NEW_PASSWORD connection parameter is not specified. In this situation, the application can submit a MODIFY USER statement to assign a new password to the user. After the new password has been set, the application can submit a DATABASE statement to change the default database for the connection.

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.

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 314 if you receive “Response limit exceeded” errors.

Turning LOB_SUPPORT OFF while using scrollable result sets or updatable result sets causes the driver to downgrade the result set to forward-only (scrollable result sets) or read-only (updatable result sets). In addition, an SQLWarning is returned to indicate the downgrade.





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 JDBC Driver will not automatically create the table. See Updatable LOBs for more information.

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


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=teradata,dc=com password=secret'





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 JDBC Driver 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 JDBC Driver 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.





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 JDBC Driver, 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 JDBC Driver 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 JDBC Driver 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 JDBC Driver to use the standard protocol for all SQL statements

• MONITOR – directs the Teradata JDBC Driver to use the Monitor protocol for all SQL statements





SESSIONS Specifies the number of FastLoad or FastExport connections to be created, where 1 <= number of FastLoad or FastExport 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 use the default value; that is, omit the SESSIONS parameter and let the Teradata JDBC Driver create the appropriate number of FastLoad or FastExport connections.

SP_SPL This parameter is only used when creating or replacing Teradata 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 Request 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

The TNANO and TSNANO connection parameters are ignored for JDBC FastLoad and FastExport connections.





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 available from the http://www.teradata.com Teradata Download Center in the Teradata JDBC Driver section for information on using the Teradata JDBC Driver 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 267 for additional information.

TYPE Specifies the type of protocol to be used with the Teradata Database for SQL statements. Options are:

• DEFAULT–directs the Teradata JDBC Driver to use the standard protocol for all SQL statements

• FASTLOAD–directs the Teradata JDBC Driver to use the FastLoad protocol for FastLoad-capable SQL INSERT statements and the standard protocol for all other SQL statements

• FASTEXPORT–directs the Teradata JDBC Driver to use the FastExport protocol for FastExport-capable SQL SELECT statements and the standard protocol for all other SQL statements

The default is DEFAULT.

USEXVIEWS The USEXVIEWS parameter instructs the Teradata JDBC Driver 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.






DataSources are accessed with the JNDI. For more information, check:

http://java.sun.com/products/jndi/

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 JDBC Driver 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.


http://java.sun.com/products/jndi/


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.

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 JDBC Driver 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.


Chapter 2: Using the Teradata JDBC DriverLogonSource Format

LogonSource Format

When the Teradata JDBC Driver establishes a connection to the Teradata Database, the Teradata JDBC Driver composes a string value that is stored in 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 JDBC Driver and other clients are entered into the database in uppercase.

The Teradata JDBC Driver 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 JDBC Driver 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 JDBC Driver. 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 JDBC Driver. 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 c12345678901234567890123456789012345678901234567890123456789012345678901 o n b<--set by Teradata Database--><--------------set by client-------------> t e(TCP/IP) 11AB 153.64.135.140 CHARON;CHARONCOP1/153.64.116.144:1025 i l(TCP/IP) 11AB 153.64.135.140 CHARON.SANDIEGOCA.COM;CHARONCOP1.SAND n o----------------------------- ----------------------------------------- u w 1 2 3 4 e 12345678901234567890123456789012345678901 d Truncated to the space remaining in the 97 chars, after


Chapter 2: Using the Teradata JDBC DriverLogonSource Format

the subsequent fields are composed

c f 7 8 9 10 11 12 o r 234567890123456789012345678901234567890123456789012345678 n o t m <------------------set by client-------------------------> i CID=C2A132 ROOTUSER JDBC03.02.00.00;1.4.2_01 01 LSS n a CID=C2A132 ROOTUSER JDBC03.02.00.00;1.4.2_01 01 LSS u b ------------ -------- -------------------------- ------ e o 1 1 2 d v 123456789012 12345678 12345678901234567890123456 123456 e Will be Trunc'ed Trunc'ed to 26 chars Hardcoded 12 chars to 20 chars (may be less) 6 chars or less (may be less)

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.teradata.com” is: CS4300S1.SANDIEGOCA.TERADATA.COM;CS4300S1COP1.SAN

Field 5 - Client Process ID/Thread ID Field

Note: The Teradata JDBC Driver 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 JDBC Driver 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 JDBC Driver always prefixes connection ID


Chapter 2: Using the Teradata JDBC DriverProgram Examples

values with the prefix “cid=”, to make it easy to distinguish connection ID values from other values.

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 JDBC Driver 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 for the example programs.

Converting Sample files 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.



Chapter 2: Using the Teradata JDBC DriverRunning a Sample Application

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.

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, and tdgssconfig.jar to the development platform. The following commands assume that all the 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 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

5 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;tdgssconfig.jar sample1

7 [UNIX only]Run the application on UNIX by entering the following:

java -classpath .:terajdbc4.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:tdgssconfig.jar sample1java -d32 -classpath .:terajdbc4.jar:tdgssconfig.jar sample1java -d64 -classpath .:terajdbc4.jar:tdgssconfig.jar sample1


Chapter 2: Using the Teradata JDBC DriverDate, Time, Timestamp Values and Time Zones

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.

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.

Date, Time, Timestamp Values and Time Zones

The java.sql.Date, Time, and Timestamp objects’ valueOf methods construct a value relative to JVM default timezone.

The java.sql.Date, Time, and Timestamp objects’ toString methods print the value relative to JVM default timezone.

The Teradata JDBC Driver ‘s PreparedStatement and CallableStatement setter methods setDate, setTime, and setTimestamp send to the Teradata Database the java.sql.Date, Time, or Timestamp value that matches what the java.sql.Date, Time, or Timestamp object’s toString method would print at the time that the setter method is called, meaning the value is relative to the JVM default timezone at the time that the setter method is called.

Therefore, when an application calls setDate, setTime, or setTimestamp, the application must ensure that the JVM default timezone in effect is the same as what was in effect when that java.sql.Date, Time, or Timestamp object was created.

Setter methods setDate, setTime, and setTimestamp with a Calendar argument send the java.sql.Date, Time, or Timestamp value to the Teradata Database in exactly the same way as the corresponding method without Calendar argument; specifically, the value that matches what the java.sql.Date, Time, or Timestamp object’s toString method would print at the time that the setter method is called, meaning the value is relative to the JVM default timezone at the time that the setter method is called.

The setDate without Calendar sends SQL data type DATE value to the Teradata Database.

The setDate with Calendar sends SQL data type DATE value to the Teradata Database, and the Calendar argument is ignored.

Because the Teradata Database does not provide a DATE WITH TIME ZONE data type, it is recommended that applications avoid calling setDate with Calendar, and only call setDate without Calendar. The Teradata JDBC Driver currently ignores the Calendar argument of setDate with Calendar, and the method behaves exactly as setDate without Calendar. Note that the behavior of the Teradata JDBC Driver’s setDate with Calendar may change in the future if the Teradata Database provides a DATE WITH TIME ZONE data type, which in turn may affect your application’s behavior.

The setTime without Calendar sends SQL data type TIME to the Teradata Database.


Chapter 2: Using the Teradata JDBC DriverSession DateForm

The setTime with Calendar sends SQL data type TIME WITH TIME ZONE to the Teradata Database.

The Time value sent to the database matches what the Time object’s toString method would print, and the Calendar argument’s timezone is sent as a separate TIME ZONE field. The Teradata JDBC Driver accepts any Calendar argument from the application; the Teradata JDBC Driver cannot and does not restrict the Calendar argument’s timezone to match the timezone that was in effect when the Time object was originally created.

The setTimestamp without Calendar sends SQL data type TIMESTAMP to the Teradata Database.

The setTimestamp with Calendar sends SQL data type TIMESTAMP WITH TIME ZONE to the Teradata Database.

The Timestamp value sent to the database matches what the Timestamp object’s toString method would print, and the Calendar argument’s timezone is sent as a separate TIME ZONE field. The Teradata JDBC Driver accepts any Calendar argument from the application; the Teradata JDBC Driver cannot and does not restrict the Calendar argument’s timezone to match the timezone that was in effect when the Timestamp object was originally created.

Session DateForm

The session’s current DateForm primarily dictates how DATE values are transmitted from the Teradata Database to the Teradata JDBC Driver. The session’s current DateForm also dictates how the Teradata Database performs implicit conversions from a PreparedStatement/CallableStatement setString value to a destination DATE column or parameter.

ANSIDate is the recommended DateForm. When the session’s current DateForm is ANSIDate, then the Teradata Database transmits DATE values to the Teradata JDBC Driver as 10-character values in the form “YYYY-MM-DD”, and the Teradata Database rejects non-Y2K-compliant implicit conversions from a PreparedStatement setString value to a destination DATE column or parameter. (Teradata Database error 2666 is returned in this situation.)

The IntegerDate DateForm is provided for legacy applications. When the session’s current DateForm is IntegerDate, then the Teradata Database transmits DATE values to the Teradata JDBC Driver as 4-byte binary values, and the Teradata Database accepts non-Y2K-compliant implicit conversions from a PreparedStatement setString value to a destination DATE column or parameter. (The Teradata Database uses 19 as the century digits for the year in this situation.)

It is possible to specify a DateForm attribute for a Teradata Database user with the CREATE USER command or the MODIFY USER command. When a session is first established, the session’s current DateForm defaults to the user’s DateForm, if available; or to the system default defined by the DATEFORM parameter in the DBSControl record.

The HELP SESSION command shows the session’s current DateForm.


Chapter 2: Using the Teradata JDBC DriverSession DateForm

The session’s current DateForm can be changed by executing the SQL commands SET SESSION DATEFORM=ANSIDATE or SET SESSION DATEFORM=INTEGERDATE. It is not recommended for a Java application to execute the SET SESSION DATEFORM commands using a pooled connection within an application server.

Receiving DATE Values from the Teradata Database

With TTU 8.1 and earlier releases of the Teradata JDBC Driver, less accurate information was provided for DATE values when the session’s current DateForm is ANSIDate. For a DATE value received from the Teradata Database, the ResultSetMetadata getColumnType method returned java.sql.Types.CHAR, the ResultSetMetadata getColumn ClassName method returned java.lang.String, and the ResultSet getObject method returned a String value.

Beginning with TTU 8.2 Teradata JDBC Driver 3.4, more accurate information is provided for DATE values when the session’s current DateForm is ANSIDate. For a DATE value received from the Teradata Database, the ResultSetMetadata getColumnType method returns java.sql.Types.DATE, the ResultSetMetadata getColumnClassName method returns java.sql.Date, and the ResultSet getObject method returns a java.sql.Date value.

Sending DATE Values to the Teradata Database

Beginning with Teradata JDBC Driver 12.0 and Teradata Database 12.0, the Teradata JDBC Driver sends java.sql.Date values to the Teradata Database as DATE values using the ANSIDate DateForm. This provides Y2K-compliant implicit conversion for java.sql.Date values that are specified with the PreparedStatement/CallableStatement setDate or setObject methods, and sent to destination CHAR/VARCHAR columns and parameters.

A legacy application requiring non-Y2K-compliant behavior can use Teradata-specific Escape Syntax functions introduced in Teradata JDBC Driver 12.0. The DateForm in effect at the time that an application calls the PreparedStatement/CallableStatement setDate or setObject method is the DateForm that is used for the corresponding DATE value sent to the Teradata Database.

// DateForm=IntegerDate provides non-Y2K-compliant implicit// conversions from java.sql.Date to CHAR/VARCHARconnection.nativeSQL(“{fn teradata_useintegerdate}”);

// DateForm=ANSIDate provides Y2K-compliant implicit conversion // from java.sql.Date to CHAR/VARCHAR (the default behavior)connection.nativeSQL(“{fn teradata_useansidate}”);

Teradata Database releases 12.0 through 12.0.1.1 only accept DATE values whose DateForm matches the session’s current DateForm. When the session’s current DateForm is:

• IntegerDate and a DATE value with ANSIDate DateForm is sent to the Teradata Database, then the Teradata Database returns error 2665 (“Invalid date”)

• ANSIDate and a DATE value with IntegerDate DateForm is sent to the Teradata Database, then the Teradata Database returns error 3610 (“Internal error: Please do not resubmit the last request. SubCode, CrashCode”)

This restriction was removed beginning with Teradata Database 12.0.1.2.


Chapter 2: Using the Teradata JDBC DriverSession Time Zone

Session Time Zone

All TIME and TIMESTAMP data is associated with time zones explicitly or implicitly. The user’s default time zone is in effect initially when a connection (session) is established with the Teradata Database. If no default time zone is defined for the user, then the system default time zone is in effect initially for a connection. The connection’s time zone can be changed by the SET TIME ZONE statement. For more information, see SET TIME ZONE in SQL Data Definition Language.

The PreparedStatement interface defines setTime and setTimestamp methods both with and without a Calendar argument:

• When an application uses the PreparedStatement setTime and setTimestamp methods without a Calendar argument, then the Teradata Database implicitly associates the connection’s time zone with the TIME or TIMESTAMP value;

• When an application uses the PreparedStatement setTime and setTimestamp methods with a Calendar argument, then the Teradata Database explicitly associates the specified Calendar’s time zone with the TIME or TIMESTAMP value.

TIME and TIMESTAMP table columns and stored procedure parameters can be declared with or without a time zone field: TIME, TIME WITH TIME ZONE, TIMESTAMP, and TIMESTAMP WITH TIME ZONE:

• TIME and TIMESTAMP table columns and stored procedure parameters declared without a time zone field contain values relative to UTC;

• TIME and TIMESTAMP table columns and stored procedure parameters declared with a time zone field contain values relative to the value’s time zone.

Table 11 illustrates how the Teradata Database uses the combination of the input data value and its implicitly or explicitly associated time zone, and whether the destination is declared with or without a time zone field, to determine the resulting data value that is stored in a TIME or TIMESTAMP destination.



Table 11: Determining Data Values Stored in a TIME or TIMESTAMP Destination

Connection’s Time Zone

Calendar Argument Used?

Destination Data Type (table column or stored procedure parameter) Includes Time Zone Field? Result Examples

UTC +00:00 No

• PreparedStatement setTime without Calendar argument

• PreparedStatement setTimestamp without Calendar argument

No

• TIME

• TIMESTAMP

Therefore, destination data values are relative to UTC

Teradata Database assumes that input data value is relative to the connection’s time zone and the Teradata Database does no conversion because the connection’s time zone is UTC

setTime(int index, Time x)x = 17:10:47:046 produces column value: 17:10:47.046000

setTimestamp(int index, Timestamp x) x = 2006-04-12 17:10:47:046 produces column value: 2006-04-12 17:10:47.046000

-10:00 No

• PreparedStatement setTime without Calendar argument

• PreparedStatement setTimestamp without Calendar argument

No

• TIME

• TIMESTAMP


Teradata Database assumes that input data value is relative to the connection’s time zone and the Teradata Database converts the input data value to UTC before putting the data value into the destination

setTime(int index, Time x)x = 17:10:47:046 produces column value: 03:10:47.046000

setTimestamp(int index, Timestamp x) x = 2006-04-12 17:10:47:046 produces column value: 2006-04-13 03:10:47.046000

Not relevant Yes

• Prepared Statement setTime with Calendar argument

• Prepared Statement setTimestamp with Calendar argument

No

• TIME

• TIMESTAMP


Teradata Database recognizes that the input data value includes an explicit time zone, and the Teradata Database converts the input data value to UTC before putting the data value into the destination

setTime(int index, Time x, Calendar cal)x = 17:10:47:046 Calendar time zone = -08:00 produces column value: 01:10:47.046000

setTimestamp(int index, Time x, Calendar cal) x = 2006-04-12 17:10:47:046; Calendar time zone = -08:00 produces column value: 2006-04-13 01:10:47.046000



Not relevant Yes

• Prepared Statement setTime with Calendar argument

• Prepared Statement setTimestamp with Calendar argument

Yes

• TIME WITH TIME ZONE

• TIMESTAMP WITH TIME ZONE

Teradata Database recognizes that input data value includes an explicit time zone, and the Teradata Database does no conversion and puts the input data value and its time zone into the destination

setTime(int index, Time x, Calendar cal)x = 17:10:47:046 Calendar time zone = -08:00 produces column value: 17:10:47.046000-08:00

setTimestamp(int index, Time x, Calendar cal) x = 2006-04-12 17:10:47:046 Calendar time zone = -08:00 produces column value: 2006-04-12 17:10:47.046000-08:00

UTC +00:00 No

• Prepared Statement setTime without Calendar argument

• Prepared Statement setTimestamp without Calendar argument

Yes



Teradata Database assumes that input data value is relative to the connection’s time zone and the Teradata Database does no conversion and puts the input data value and the connection’s time zone into the destination

setTime(int index, Time x)x = 17:10:47:046 produces column value: 17:10:47.046000+00:00

setTimestamp(int index, Time x) x = 2006-04-12 17:10:47:046 produces column value: 2006-04-12 17:10:47.046000-00:00

-10:00 No

• Prepared Statement setTime without Calendar argument

• Prepared Statement setTimestamp without Calendar argument

Yes



Teradata Database assumes that input data value is relative to the connection’s time zone and the Teradata Database does no conversion and puts the input data value and the connection’s time zone into the destination

setTime(int index, Time x)x = 17:10:47:046 produces column value: 17:10:47.046000-10:00

setTimestamp(int index, Time x) x = 2006-04-12 17:10:47:046 produces column value: 2006-04-12 17:10:47.046000-10:00

Table 11: Determining Data Values Stored in a TIME or TIMESTAMP Destination (continued)

Connection’s Time Zone

Calendar Argument Used?

Destination Data Type (table column or stored procedure parameter) Includes Time Zone Field? Result Examples


Chapter 2: Using the Teradata JDBC DriverStored Procedure TIME and TIMESTAMP INOUT Parameters

Stored Procedure TIME and TIMESTAMP INOUT Parameters

The Teradata Database forces the output value for an INOUT parameter, as set by a stored procedure, to conform exactly to the same data type attributes as the bound input value for the INOUT parameter.

When calling a stored procedure having INOUT parameters of type TIME WITH TIME ZONE and or TIMESTAMP WITH TIME ZONE, the application must bind values using the CallableStatement methods setTime or setTimestamp, respectively, with a Calendar argument. If the Calendar argument is not used, the Teradata Database returns error 3996 (Right truncation of string data). Also, the setNull method cannot be used to bind a NULL value to an INOUT parameter of type TIME WITH TIME ZONE or TIMESTAMP WITH TIME ZONE. You must instead specify a null data value, using the setTime or setTimestamp method with a Calendar argument.

The Teradata Database does not currently provide or permit implicit or explicit data type conversions for TIME and TIMESTAMP values that reduce the number of fractional digits of the value.

The Teradata JDBC Driver connection parameters TNANO and TSNANO exist to work around this Teradata Database limitation. The TNANO and TSNANO connection parameters are awkward to use, however, because they force all TIME data values to have the same number of fractional digits (as specified by TNANO), and or force all TIMESTAMP data values to the same data type attributes as the bound input value for the INOUT parameter.

• It is not possible to bind an input TIME or TIMESTAMP value to a stored procedure INOUT parameter when the input value has a larger number of fractional digits than used to declare the INOUT parameter –the Teradata Database returns error 5404 (Datetime field overflow).

• It is possible to bind an input TIME or TIMESTAMP value to a stored procedure INOUT parameter when the input value has a smaller number of fractional digits than used to declare the INOUT parameter. Unfortunately, however, the stored procedure is restricted from returning an output value with more fractional digits than the input value, because the Teradata Database returns error 5404 (Datetime field overflow). The stored procedure might not be able to return an output value with all the fractional digits used to declare the INOUT parameter.

• The net effect is that an application is effectively required to bind input TIME and TIMESTAMP values for stored procedure INOUT parameters with exactly the same number of fractional digits used to declare the INOUT parameters. Because the TNANO and TSNANO connection parameters force all data values to have the same number of fractional digits, an application might not be able to call stored procedures declared with INOUT parameters having differing numbers of fractional digits.

For example, the following stored procedure might encounter this problem:

REPLACE PROCEDURE MyProc(INOUT p1 TIMESTAMP(2), INOUT p1 TIMESTAMP(5))


Chapter 2: Using the Teradata JDBC DriverMulti-Statement Requests

Regarding NULL TIME and TIMESTAMP values bound to PreparedStatement or CallableStatement parameters, when the TNANO or TSNANO connection parameter is not specified, the Teradata JDBC Driver has default behavior that assumes that each NULL TIME or TIMESTAMP value, respectively, has zero fractional digits. This default behavior works with all possible INSERT and UPDATE destination TIME and TIMESTAMP columns, regardless of the number of fractional digits used in declaration. This default behavior does not work with stored procedure INOUT parameters declared with more than zero fractional digits.

Until the Teradata Database is enhanced, applications that call stored procedures with TIME and TIMESTAMP INOUT parameters must follow these guidelines:

1 The TNANO and TSNANO connection parameters must be specified

2 The stored procedure TIME and TIMESTAMP INOUT parameters’ fractional digits must all be declared to be the same and they must match the TNANO and TSNANO connection parameters, respectively.

Multi-Statement Requests

Multi-statement requests can be performed by executing one SQL statement consisting of multiple SQL commands, separated by semicolons. Multi-statement requests can be executed using Statement.execute() method. The application can retrieve the result using Statement.getResultSet() or Statement.getUpdateCount() methods and in case multiple results are returned, then the application must use Statement.getMoreResults() method to iterate through these results.

Teradata Database Macros

A Teradata Database macro consists of one or more SQL statements. Macros can be executed using Statement.execute() method. The application can retrieve the result using Statement.getResultSet() or Statement.getUpdateCount() methods and in case multiple results are returned, then the application must use Statement.getMoreResults() method to iterate through these results.

Creating User-Defined Functions and External Stored Procedures

User-Defined Functions

The “CREATE/REPLACE FUNCTION” statement is used to create a User-Defined Function (UDF) and it always returns a result set. The Statement.executeQuery() or Statement.execute() methods can be used to execute this statement.


Chapter 2: Using the Teradata JDBC DriverUser-Defined Types

For more information regarding UDFs, refer to User-Defined Functions in SQL External Routine Programming.

External Stored Procedures

The “CREATE/REPLACE PROCEDURE” statement is used to create an External Stored Procedure (XSP). This can be executed using the Statement.execute() or Statement.executeUpdate() methods. The Statement.getWarnings() method can be used to retrieve the SQLWarning returned by the Statement object.

For more information regarding XSPs, refer to External Stored Procedures in SQL External Routine Programming.

For more information on Java XSPs, refer to the section in this chapter, “Java External Stored Procedures” on page 86.

Source File Locations for JDBC

The Teradata JDBC Driver 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 JDBC Driver 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 JDBC Driver can transfer the source file to the server node.

User-Defined Types

Teradata JDBC Driver supports the following User-Defined Types (UDT) functionality:

• UDT values can be composed using UDT constructors and UDT mutator methods. (PreparedStatement parameter markers can correspond to individual UDT attribute values that represent arguments to UDT constructors and UDT mutator methods. PreparedStatement parameter markers cannot correspond to entire UDT values using JDBC custom type mapping or java.sql.Struct values.)

• Using the SELECT statement’s “.ALL” syntax, UDT attribute values can be retrieved as ResultSet column values

• User-Defined Methods (UDM) can be created using source files that are client resources available on the classpath, or using source files located on the Teradata Database server

• UDT metadata is available from DatabaseMetaData, ResultSetMetaData, and ParameterMetaData methods:



MetaData Method UDT MetaData Description

DatabaseMetaData getAttributes Retrieves a description of the given attribute of the given type for a UDT that is available in the given schema and catalog (catalog should be null because no catalog is supported in Teradata. For UDT attributes as UDT types, the type name is fully qualified. The UDT attribute type is returned in the ATTR_TYPE_NAME column.

DatabaseMetaData getUDTs Retrieves a description of the UDTs defined in a particular schema. Schema-specific UDTS can have type STRUCT and DISTINCT. (Type JAVA_OBJECT is not supported in Teradata.) The UDT name is returned in the TYPE_NAME column.

DatabaseMetaData getColumns Retrieves a description of table columns available in the specified schema and catalog. (Catalog should be null because no catalog is supported in Teradata.) For columns as UDT types, the type name is fully qualified. The UDT name is returned in the TYPE_NAME column.

DatabaseMetaData getProcedureColumns Retrieves a description of stored procedure parameter and result columns in the specified schema and catalog. (Catalog should be null because no catalog is supported in Teradata.) For columns as UDT types, the type name is fully qualified. The UDT name is returned in the TYPE_NAME column.

DatabaseMetaData getBestRowIdentifier Retrieves a description of a table’s optimal set of columns that uniquely identified a row in the specified schema and catalog. (Catalog should be null because no catalog is supported in Teradata.) For columns as UDT types, the type name is fully qualified. The UDT name is returned in the TYPE_NAME column.



Teradata JDBC Driver does not currently support the following UDT functionality. If you attempt to use any of the following functionality, you will be forced to change your Java application at a later date when support is available.

• JDBC custom type mapping is not supported

• java.sql.Struct values are not supported

• Binding entire UDT values to PreparedStatement parameter markers is not supported. (PreparedStatement parameter markers can correspond to individual UDT attribute values that represent arguments to UDT constructors and UDT mutator methods. PreparedStatement parameter markers cannot correspond to entire UDT values using JDBC custom type mapping or java.sql.Struct values.)

• Retrieving UDT values from ResultSet columns is not supported

• Retrieving output UDT values from stored procedure INOUT or OUT parameters is not supported

Creating a UDT using Teradata JDBC Driver is done in a similar manner to creating other database objects. A Java application can call the Statement execute or executeUpdate method to issue the appropriate “CREATE TYPE” SQL statement followed by “CREATE METHOD”, “CREATE TRANSFORM”, and “CREATE ORDERING” statements as needed to fully create the type.

When creating UDMs, if the “CREATE METHOD” statement indicates that the source file containing the method definition is located on the client, then the source file must be available as a resource on the classpath. Teradata JDBC Driver automatically loads the resource from classpath and transfers it to the Teradata Database.

DatabaseMetaData getTypeInfo Retrieves a description of all the standard SQL types supported by this database. Teradata supports SQL distinct types and structured types; as a result, the returned result set includes one row with a TYPE_NAME of DISTINCT and a DATA_TYPE of java.sql.Types.DISTINCT, and one row with a TYPE_NAME of STRUCT and a DATA_TYPE of java.sql.Types.STRUCT.

ResultSetMetaData getColumnTypeName If the column type is a UDT, then a fully qualified type name is returned.

ParameterMetaData getParameterTypeName If the column type is a UDT, then a fully qualified type name is returned.

MetaData Method UDT MetaData Description


Chapter 2: Using the Teradata JDBC DriverUpdatable LOBs

Updatable LOBs

Temporary Table

Before LOB updates can be used with the Teradata JDBC Driver, 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 JDBC Driver 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.

LOB_TEMP_TABLE=tableName

[Optional]Specify a database name:

LOB_TEMP_TABLE=databaseName.tableName

See Table 10 on page 43 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.

Teradata JDBC Driver 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);


Chapter 2: Using the Teradata JDBC DriverSQL Literals and SQL Injection Attacks

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.

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.


Chapter 2: Using the Teradata JDBC DriverMulti-Threading Issues

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 JDBC Driver blocks until the previous request has returned. This may negatively impact performance.

Table 12 contains JDBC Object Thread safety information.

Table 12: 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.


Chapter 2: Using the Teradata JDBC DriverUsing Type 4 Driver with ResultSetMetaData Methods

Multi-threading on IBM AIX 5.1 and Using 64-bit JDK on Microsoft Windows

When using the Type 4 Teradata JDBC Driver 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 JDBC Driver throws an SQL Exception when the following nine ResultSetMetaData methods are invoked:

• isAutoIncrement()

• 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:

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.

Table 12: JDBC Object Thread Safety (continued)

JDBC Object Thread Safety


Chapter 2: Using the Teradata JDBC DriverUsing Type 4 Driver with Sun JDK 5.0 Implementation of JDBC RowSet Interface

COMPAT_DBS=true/falseCOMPAT_ISAUTOINC=true/falseCOMPAT_ISCURRENCY=true/falseCOMPAT_ISSIGNED=true/falseCOMPAT_ISSEARCH=true/falseCOMPAT_ISREADONLY=true/falseCOMPAT_ISWRITABLE=true/falseCOMPAT_ISDEFWRIT=true/falseCOMPAT_GETSCHEMA=ReturnValueCOMPAT_GETTABLE=ReturnValue

Refer to the tables in “Making a Teradata Database Connection” on page 41 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 JDBC Driver works with the Sun JDK 5.0 implementation of JDBC RowSet Interface. When using 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 JDBC Driver will throw SQLException when the following six ResultSetMetaData methods are invoked through JdbcRowSetImpl(java.sql.ResultSet resultSet):

• isAutoIncrement()

• isCurrency()

• isSigned()

• isSearchable()

• getSchemaName()

• getTableName()


Chapter 2: Using the Teradata JDBC DriverEncryption, Authentication, and Authorization

To use the constructor, JdbcRowSetImpl(java.sql.ResultSet resultSet), supply the following URL options:

COMPAT_DBS=true/falseCOMPAT_ISAUTOINC=true/falseCOMPAT_ISCURRENCY=true/falseCOMPAT_ISSIGNED=true/falseCOMPAT_ISSEARCH=true/falseCOMPAT_GETSCHEMA=ReturnValueCOMPAT_GETTABLE=ReturnValue

Refer to the section “Using Type 4 Driver with ResultSetMetaData Methods” on page 74 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 JDBC Driver 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 JDBC Driver 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:

• Authentication

• Authorization

• Encryption

The Logon Mechanisms supported are:

• Teradata Method 1

• Teradata Method 2

• Kerberos

• LDAP

The Teradata JDBC Driver 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 13 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.

Prerequisites

Logons with any mechanism other than TD1 and TD2 using the UTF16 session character set are not accepted if either the Teradata JDBC Driver 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:

• Parcel kind or ordering is invalid (Error code 3748)

• UserID, Password, or Account is invalid (Error code 8017)

Table 14 lists the prerequisites for each of the methods.

Table 13: 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.

Table 14: 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



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 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 preauthentication” 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.

Kerberos Requires a significant number of administration tasks on the machine that is running the Teradata JDBC Driver. See “Meeting Kerberos Prerequisites” for more detail.

To use UTF16 with Kerberos authentication, the Teradata JDBC Driver 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 JDBC Driver.

To use UTF16 with LDAP authentication, the Teradata JDBC Driver must be version 3.3 or later, and the Teradata Database must be V2R6.1 or later.

Table 14: Prerequisites (continued)

Method Description



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>kinitPassword for [email protected]:MypasswordNew 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

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 = trueticket_lifetime = 6000default_realm = ESROOTDOM.ESDEV.TDATclockskew = 13000default_tkt_enctypes = des-cbc-md5default_tgs_enctypes = des-cbc-md5



checksum_type=2[realms]ESROOTDOM.ESDEV.TDAT = {kdc = esroot.esrootdom.esdev.tdat:88default_domain = esrootdom}[domain_realm]esrootdom = {.esrootdom = ESROOTDOM.ESDEV.TDATesrootdom = 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:

• Edit the java.security file located in the lib/security directory of J2RE

• 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 Data Definition Language.

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.

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 JDBC Driver download package. Instead, the classpath for Java applications is set to include the TeraGSS directory that contains TdgssUserConfigFile.xml.


Chapter 2: Using the Teradata JDBC DriverGenerated Keys

The classpath must be set to include the following:

• terajdbc4.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 available from the http://www.teradata.com Teradata Download Center in the Teradata JDBC Driver section for complete instructions on how to use the Teradata JDBC Driver 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 JDBC Driver 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 JDBC Driver, the following methods were added or enabled to support generated keys:

• Statement.getGeneratedKeys()

• Statement.executeUpdate(String sql, int autoGeneratedKeys)

• Statement.executeUpdate(String sql, int[] columnIndexes)

• 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)




Chapter 2: Using the Teradata JDBC DriverGenerated Keys

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 JDBC Driver 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)

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.


Chapter 2: Using the Teradata JDBC DriverParameterMetaData and Ambiguous Types

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.

ParameterMetaData 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 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 15 outlines what is returned in cases where the data type of a parameter is ambiguous, and is considered an unknown data type.


Chapter 2: Using the Teradata JDBC DriverParameterMetaData and Ambiguous Types

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 16 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 or Unknown

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

Table 16: Data Type Ambiguous or Unknown

java.sql.ResultSetMetaData Method Value Returned for an Unknown Data Type

getCatalogName "" (a zero-length string)

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


Chapter 2: Using the Teradata JDBC DriverJava External Stored Procedures

Java External Stored Procedures

The Teradata JDBC Driver 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:

• Compile the Java source outside of the database and place the resulting class or classes (the byte code) in a jar file

Note: Teradata Database 12.0 and 13.0 do not support Java Stored Procedures compiled with JDK 6.0. Only Java Stored Procedures compiled with JDK 1.4.2 or JDK 5.0 are supported.

• Register the resulting jar file with the database by calling an XSP named SQLJ.INSTALL_JAR

• 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

isCaseSensitive false

isCurrency false

isDefinitelyWritable false

isNullable ResultSetMetaData.columnNullableUnknown

isReadOnly false

isSearchable false

isSigned false

isWritable false

Table 16: Data Type Ambiguous or Unknown (continued)

java.sql.ResultSetMetaData Method Value Returned for an Unknown Data Type



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

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 JDBC Driver 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 JDBC Driver can transfer the source file to the server node.

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 JDBC Driver. If the <location designator> specifies ‘SJ!’ then the jar is located on the database server using the <server jar path>.



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 DATAPARAMETER STYLE JAVAEXTERNAL 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 DATAPARAMETER STYLE JAVAEXTERNAL 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” +“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);// Setting up input parameter valuecStmt.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 callcStmt.executeUpdate();// Displaying procedure call resultSystem.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 reviewcreateClobFile(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 JDBC Driver, 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.

Limitations

The following SQL statements are not supported in a Java stored procedure when being used to generate a dynamic result set. This also means that they cannot be mixed with other SQL statements in a multi-statement request when some of these other SQL statements are used to generate a dynamic result set:

• HELP SESSION

• HELP VOLATILE TABLE

• HELP CONSTRAINT

• HELP STATISTICS

• HELP [TEMPORARY] INDEX

• HELP TRANSFORM

• HELP TRIGGER

• HELP REPLICATION GROUP

• SHOW REPLICATION GROUP

• SHOW SPECIFIC METHOD

• SHOW FUNCTION <User’s UDF>

• ShowType <User’s type>

• SHOW PROCEDURE

The following restrictions apply when returning auto-generated keys result sets from a Java stored procedure:


Chapter 2: Using the Teradata JDBC DriverUpdatable Result Set

• If the Java stored procedure specified RETURN_GENERATED_KEYS, then the client application will receive a one-column ResultSet containing just the identity column value(s)

• If the Java stored procedure specified an array of columns, then the client application will receive a ResultSet containing all the columns of the destination table

• Returning a PreparedStatement batch’s generated keys result set from a Java stored procedure is not supported

A Java stored procedure can never directly or indirectly call another Java stored procedure.

Teradata Database 12.0 and 13.0 do not support Java Stored Procedures compiled with JDK 6.0. Only Java Stored Procedures compiled with JDK 1.4.2 or JDK 5.0 are supported.

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.

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 JDBC Driver 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 JDBC Driver 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 updateRow and deleteRow fail and the Teradata JDBC Driver 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 JDBC Driver 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 JDBC Driver throws an SQLException.

Using Updatable Result Set

The following are some common scenarios for using updatable result set with the Teradata JDBC Driver:

• 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 rsrs.updateString(“STATE”, “CALIFORNIA”); // updates the



// STATE column of row 3 to be CALIFORNIArs.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 rowrs.updateString(1, “Michael”); // updates the

// first column of the insert row to be Michaelrs.updateInt(2, 35); // updates the second column to be 35rs.updateBoolean(3, true); // updates the third column to truers.insertRow(); // inserts the row in the data sourcers.moveToCurrentRow(); // moves back to current row

• Delete the current row in the database

rs.absolute(3); // moves the cursor to the third row of rsrs.deleteRow(); // deletes the current row 3 in the data source

• Refresh the current row in the database

The Teradata JDBC Driver implements the method refreshRow to clear 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 the updater methods, but before calling the method updateRow, then the updates made to the row are lost. However, the Teradata JDBC Driver 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 rsrs.updateString(“STATE”, “CALIFORNIA”); // updates the

// STATE column of row 3 to be CALIFORNIArs.updateInt(“AMOUNT”, 58); // updates the second column to be 35rs.refreshRow(); // clears up the update column

// values for the current rowrs.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 upgraded or downgraded.

Scenario 1: Type Upgrading

The Teradata JDBC Driver 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 and later

• 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:

• 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 and later

• 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 JDBC Driver 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 JDBC Driver throws an SQLException.

Error 1197: No unique primary index (UPI) or key columns are fetched in this result set from the table


Chapter 2: Using the Teradata JDBC DriverStored Procedure Dynamic Result Set

• Method insertRow: The Teradata JDBC Driver throws an SQLException for the following conditions:

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 non-null value for the table

• The Teradata JDBC Driver 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 JDBC Driver 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

• The Teradata JDBC Driver 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.

Special Floating Point Values

The Teradata Database does not provide complete support for the special floating point values positive infinity, negative infinity, and Not a Number (NaN). It is possible for a Java application to use a PreparedStatement to bind and insert special floating point values into a FLOAT column in the Teradata Database. However, because special floating point values are not fully supported by the Teradata Database, incorrect results and Teradata Database errors might occur for SELECT statements with WHERE clause conditions that reference special floating point values.


Chapter 2: Using the Teradata JDBC DriverPreparedStatement Batch

PreparedStatement Batch

A PreparedStatement batch provides efficient inserting, updating, or deleting data where the SQL statement remains the same and only the data values differ for each submission.

Insert performance depends on many factors, such as the number of columns, the column data types, the data value sizes, and so on. Table 17 provides general comparisons of different insert techniques, ordered from slowest to fastest.

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 may be three to 10 times faster than the corresponding SQL PreparedStatement batched insert. In other words, JDBC FastLoad may take only 10% to 33% of the time for the equivalent SQL PreparedStatement batch 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.

Table 17: Insert Performance

Throughput Insert Technique Comments

Lowest SQL non-prepared statement insert using literal data values

–

– SQL PreparedSttement insert using question-mark parameters (non-batch)

Significantly faster than the previous approach

– SQL PreparedStatement batch insert using question-mark parameters, with the recommended batch size. A batch size of roughly 500 to 1000 works well for most applications.

Can be 10 to 40 times faster than the previous approach

Highest JDBC FastLoad PreparedStatement batch using question-mark parameters, with the recommended batch size. A batch size of roughly 500 to 1000 works well for most applications.

Can be 3 to 10 times faster than the previous approach. JDBC FastLoad is only recommended for loading large amounts of data (at least 100,000 rows total).


Chapter 2: Using the Teradata JDBC DriverJDBC FastLoad

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

• All Teradata data types declared in the destination table must be supported by JDBC FastLoad

Considerations When Using JDBC FastLoad

Keep in mind the following considerations. JDBC FastLoad:

• Requires that the destination table in a Teradata Database 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.

• Is recommended only for loading large amounts of data (at least 100,000 rows total). JDBC FastLoad will be slower than a normal SQL INSERT when inserting a small number of rows, due to the overhead involved in starting the FastLoad operation.

• 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.


Chapter 2: Using the Teradata JDBC DriverJDBC FastExport

JDBC Data Types Supported by JDBC FastLoad

Not all of the JDBC data types supported by the Teradata JDBC Driver are supported by JDBC FastLoad; for example, BLOB and CLOB. Likewise, not all of the JDBC data type conversions supported by the Teradata JDBC Driver 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.

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 FastExport

JDBC FastExport provides a method for quickly retrieving large amounts of data from a Teradata Database table or view. The actual performance of JDBC FastExport varies, depending on the application and database configuration.

For example, given an unconstrained network, JDBC FastExport may be two to three times faster than the corresponding SQL PreparedStatement select. In other words, JDBC FastExport may take only 33% to 50% of the time for the equivalent SQL PreparedStatement select.

Enabling JDBC FastExport

JDBC FastExport is enabled with TYPE=FASTEXPORT in the URL connection string. When enabled, the FastExport protocol is used with the Teradata Database for FastExport-capable SQL SELECT statements. For all other SQL statements, including SQL SELECT statements not FastExport-capable, the standard protocol is used with the Teradata Database.

To qualify for JDBC FastExport, the SQL SELECT statement must meet the following criteria:

• JDBC FastExport must be used with a PreparedStatement

• The Teradata session character set must be ASCII, UTF8, or UTF16


Chapter 2: Using the Teradata JDBC DriverJDBC FastExport

• All Teradata data types declared in the source table or view must be supported by JDBC FastExport

Considerations when Using JDBC FastExport

• JDBC FastExport supports single-statement SQL SELECT, and supports multi-statement requests composed of multiple SQL SELECT statements only

• JDBC FastExport supports ? parameter markers in WHERE clause conditions. However, the Teradata Database does not permit the = operator for primary or unique secondary indexes: an SQLException will be thrown for Teradata Database error 3695 “A Single AMP Select statement has been issued in FastExport”

• For best efficiency, do not use GROUP BY and ORDER BY clauses with JDBC FastExport

• An SQLWarning can be set by JDBC FastExport. Applications should examine the SQLWarning chain after a single-statement or multi-statement SQL SELECT has been prepared or executed.

• More than one JDBC FastExport PreparedStatements can be used at the same time, but are subject to limitations imposed by the Teradata Database. For details on the imposed limitations, see the section on Restrictions and Limitations in the Teradata FastExport Reference.

JDBC Data Types Supported by JDBC FastExport

Not all of the JDBC data types supported by the Teradata JDBC Driver are supported by JDBC FastExport; for example, BLOB and CLOB are not supported.

JDBC Escape Functions in Support of JDBC FastExport

• 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 FastExport connections that can be created.

• Connection.nativeSQL(“{fn teradata_logon_sequence_number()}”)

Returns comma-separated pairs of a JDBC FastExport-capable PreparedStatement.hashCode() and the associated Logon Sequence Number (LSN) of any JDBC FastExport PreparedStatement created by this Connection.

For example, a string of “6166383,1850,22323092,1851” indicates that two JDBC FastExport PreparedStatements are active. The first JDBC FastExport PreparedStatement has hash code 61663483 and uses LSN 1850. The second has hash code 22323092 and uses LSN 1851.

The information helps in finding the DBC.SessionInfo.SessionNo of JDBC FastExport connections, as shown in Program Examples. The LSN is not allocated until JDBC FastExport becomes active. JDBC FastExport becomes active when ? parameter markers are used in a WHERE clause condition and at least one column value is bound using the JDBC FastExport PreparedStatement. Otherwise, JDBC FastExport becomes active when the JDBC FastExport PreparedStatement is executed.


Chapter 2: Using the Teradata JDBC DriverJDBC Monitor

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 JDBC Driver 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 JDBC Driver 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

• 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 JDBC Driver are supported by JDBC Monitor; for example, BLOB and CLOB. Likewise, not all of the JDBC data type conversions supported by the Teradata JDBC Driver 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 18 describes the IDENTIFY statement.

Table 19 describes the MONITOR PHYSICAL CONFIG statement.

Table 18: 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

6 (table_id) setInt Unique ID of a table

Note: Nullable

Table 19: MONITOR PHYSICAL CONFIG Statement





Table 20 describes the MONITOR PHYSICAL RESOURCE statement.

Table 21 describes the MONITOR PHYSICAL SUMMARY statement.

Table 22 describes the MONITOR SESSION statement.

Table 23 describes the MONITOR SQL statement.

Table 20: MONITOR PHYSICAL RESOURCE Statement



Table 21: MONITOR PHYSICAL SUMMARY Statement

Parameter PreparedStatement Descriptiona

a. If MONITOR PHYSICAL SUMMARY is executed on MP-RAS platforms, the Teradata 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 22: MONITOR SESSION Statement


a. SET SESSION RATE must have been executed to set a valid session rate before MONITOR SESSION can succeed.



Note: Nullable


Note: Nullable

4 (user_name) setString Name of the user or database that is running this session

Note: Nullable



Table 24 describes the MONITOR VERSION statement.

Table 25 describes the MONITOR VIRTUAL CONFIG statement.

Table 26 describes the MONITOR VIRTUAL RESOURCE statement.

Table 23: MONITOR SQL Statement


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.


Note: A version id of “2” MUST NEVER be bound when running MONITOR SQL or the Teradata 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.


Note: Nullable


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.

Table 24: MONITOR VERSION Statement



Table 25: MONITOR VIRTUAL CONFIG Statement





Table 27 describes the MONITOR VIRTUAL SUMMARY statement.

Table 28 describe the SET SESSION RATE statement.

Table 29 describes the TDWM STATISTICS statement.

Table 30 describes the TDWM SUMMARY statement.

Table 26: MONITOR VIRTUAL RESOURCE Statement



Table 27: MONITOR VIRTUAL SUMMARY Statement



Table 28: SET SESSION RATE Statement



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 29: TDWM STATISTICS Statement



2 (request_flag) setShort Indicates the type of request

Table 30: TDWM SUMMARY Statement




CHAPTER 3

JDBC Methods

This chapter describes the JDBC methods supported by the Teradata JDBC Driver 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

• Statement Methods

• TeraDataSource Methods


Chapter 3: JDBC MethodsBLOB Interface Methods

BLOB Interface Methods

Description

This section describes the BLOB interface methods. A BLOB is a large database object that can be anything not requiring character-set conversion, including MIDI, MP3, PDF, and graphics.

Methods

getBinaryStream( )

Function: Materializes the BLOB value designated by this BLOB object as a stream of uninterpreted bytes.

getBytes(long pos, integer length)

Function: Materializes the BLOB value designated by this BLOB object as an array of bytes.

length( )

Function: Returns the number of bytes in the BLOB value that the BLOB object designates.

Characteristic Description

Syntax public InputStream getBinaryStream() throws SQLException

Return A stream containing the BLOB data is returned.


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 is copied

Return A byte of size length containing consecutive bytes from the BLOB value is returned.


Syntax public long length() throws SQLException

Return The length of the BLOB in bytes is returned.


Chapter 3: JDBC MethodsBLOB 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.

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.

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.


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.


Syntax public int setBytes(long pos, byte[] bytes, int offset, int len) throws SQLException


• 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

Return The number of bytes written is returned.

Note: The maximum length of bytes that can be set is 64000.


Chapter 3: JDBC MethodsCLOB Interface Methods

truncate(long len)

Function: Truncates the BLOB value that this BLOB object represents to be len bytes in length.

CLOB Interface Methods

Description

This section describes the CLOB interface methods. A CLOB is a pure character-based large object in a database. It can be a large text file, HTML, RTF, or other character-based file.

Methods

getAsciiStream( )

Function: Gets the CLOB value designated by this CLOB object as a stream of Ascii characters.

getCharacterStream( )

Function: Gets the CLOB value designated by this CLOB object as a Unicode stream.


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.


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


Syntax public InputStream getAsciiStream() throws SQLException

Return A java.io InputStream object containing the data in the CLOB is returned.


Syntax public Reader getCharacterStream() throws SQLException



getSubString(long pos, int length)

Function: Returns a copy of the specified substring in the CLOB value designated by this CLOB object.

length()

Function: Returns the number of bytes in the CLOB value designated by this CLOB object.

setString(long pos, String str)

Function: Writes the given Java string to the CLOB value that this CLOB object designates at position pos.

Return A java.io Reader object containing the data in the CLOB is returned.


Syntax public String getSubString(long pos, int length) throws SQLException


• 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.


Syntax public long length() throws SQLException

Return The length of the CLOB is returned.


Syntax public int setString(long pos, String str) throws SQLException


• 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.

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.

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.


Syntax public int setString(long pos, String str, int offset, int len) throws SQLException


• 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.


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.


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.


Chapter 3: JDBC MethodsCallableStatement Methods

truncate(long len)

Function: Truncates the CLOB value that this CLOB designates to have a length of len characters.

CallableStatement Methods

Description

A CallableStatement is an object that represents a precompiled SQL statement.

Starting with Release 03.01.00, macros must be executed using a Statement or PreparedStatement. Using CallableStatement results in an empty result set because Teradata Stored Procedures do not return result sets. Previous releases of the Teradata JDBC Driver returned an erroneous result set if CallableStatement.execute() and CallableStatement.executeQuery() were used to execute macros.

Methods

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.

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 void truncate(long len) throws SQLException

where the parameter len is the length, in bytes, to which the CLOB value truncates


Syntax public BigDecimal getBigDecimal(int parameterIndex) throws SQLException

where the first parameterIndex parameter is 1, the second is 2, and so on

Return The parameter value in full precision is returned. 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.

getByte(int parameterIndex)

Function: Gets the value of a JDBC TINYINT parameter as a byte in the Java programming language.

getBytes(int parameterIndex)

Function: Gets the value of a JDBC BINARY or VARBINARY parameter as an array of byte values in the Java programming language.


Syntax public BigDecimal getBigDecimal(int parameterIndex, int scale) throws SQLException

where:

• the first parameterIndex parameter is 1, the second is 2, and so on

• scale is the number of digits to the right of the decimal point

Return The parameter value in full precision is returned. If the value is SQL NULL, the result is null.


Syntax public boolean getBoolean(int parameterIndex) throws SQLException


Return The parameter value is returned. If the value is SQL NULL, the result is false.


Syntax public byte getByte(int parameterIndex) throws SQLException


Return The parameter value is returned. If the value is SQL NULL, the result is 0.


Syntax public byte[] getBytes(int parameterIndex) throws SQLException


Return The parameter value is returned. If the value is SQL NULL, the result is null.



getDate(int parameterIndex)

Function: Gets the value of a JDBC DATE parameter as a java.sql.Date object.

getDate(int parameterIndex, Calendar cal)

Function: Gets the value of a JDBC DATE parameter as a java.sql.Date object.

getDouble(int parameterIndex)

Function: Gets the value of a JDBC DOUBLE parameter as a double in the Java programming language.

getFloat(int parameterIndex)

Function: Gets the value of a JDBC FLOAT parameter as a float in the Java programming language.


Syntax public Date getDate(int parameterIndex) throws SQLException



Note: Maps to ResultSet.getDate(); see this method for further information.


Syntax public Date getDate(int parameterIndex, Calendar cal) throws SQLException

where


• cal is the Calendar object the driver will use to construct the date




Syntax public double getDouble(int parameterIndex) throws SQLException





getInt(int parameterIndex)

Function: Gets the value of a JDBC INTEGER parameter as an int in the Java programming language.

getLobData( )

Function: Retrieves the Lob data from the input stream and returns it to the database.

getLong(int parameterIndex)

Function: Gets the value of a JDBC BIGINT parameter as a long in the Java programming language.

getObject(int parameterIndex)

Function: Gets the value of a parameter as an object in the Java programming language.


Syntax public float getFloat(int parameterIndex) throws SQLException




Syntax public int getInt(int parameterIndex) throws SQLException




Syntax public InputStream getLobData() throws SQLException

Return The Lob data from the input stream to the database is returned.


Syntax public int getLong(int parameterIndex) throws SQLException





getShort(int parameterIndex)

Function: Gets the value of a JDBC SMALLINT parameter as a short in the Java programming language.

getString(int parameterIndex)

Function: Retrieves the value of a JDBC CHAR, VARCHAR, or LONGVARCHAR parameter as a String in the Java programming language.

getTime(int parameterIndex)

Function: Gets the value of a JDBC TIME parameter as a java.sql.Time object.


Syntax public Object getObject(int parameterIndex) throws SQLException


Return A java.lang.Object holding the OUT parameter value is returned.

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.


Syntax public short getShort(int parameterIndex) throws SQLException




Syntax public String getString(int parameterIndex) throws SQLException



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, Calendar cal)

Function: Gets the value of a JDBC TIME parameter as a java.sql.Time object.

getTimestamp(int parameterIndex)

Function: Gets the value of a JDBC TIMESTAMP parameter as a java.sql.Timestamp object.

getTimestamp(int parameterIndex, Calendar cal)

Function: Gets the value of a JDBC TIMESTAMP parameter as a java.sql.Timestamp object.


Syntax public Time getTime(int parameterIndex) throws SQLException




Note: Maps to ResultSet.getTime(); see this method for further information.


Syntax public Time getTime(int parameterIndex, Calendar cal) throws SQLException

where





Note: Maps to ResultSet.getTime(); see this method for further information.


Syntax public Timestamp getTimestamp(int parameterIndex) throws SQLException



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.

registerOutParameter(int parameterIndex, int sqlType, int scale)

Function: Registers the parameter in ordinal position parameterIndex to be of JDBC type sqlType.


Syntax public Timestamp getTimestamp(int parameterIndex, Calendar cal) throws SQLException

where




Note: Maps to ResultSet.getTimestamp(); see this method for further information.


Syntax public void registerOutParameter(int parameterIndex, int sqlType) throws SQLException

where


• sqlType is 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.

Note: 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, String typename)

Function: Registers the designated output parameter.

wasNull()

Function: Indicates whether or not the last OUT parameter read had the value of SQL NULL.


Syntax public void registerOutParameter(int parameterIndex, int sqlType, int scale) throws SQLException

where



• scale is the desired number of digits to the right of the decimal point. It must be greater than or equal to 0.

Note: 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.


Syntax public void registerOutParameter(int parameterIndex, int sqlType, String typename) throws SQLException

where



• typename is the fully qualified name of an SQL structured type.

Note: The last parameter is ignored.


Syntax public boolean wasNull() throws SQLException

Return 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.


Chapter 3: JDBC MethodsConnection Methods

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.

clearWarnings()

Function: After this call, getWarnings returns null until a new warning is reported for this Connection.

close()

Function: 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.

commit()

Function: Commit makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by the Connection.


Syntax public void clearWarnings() throws SQLException


Syntax public void close() throws SQLException

Note: A Connection is automatically closed when it is garbage collected. Certain fatal errors also result in a closed Connection.


Syntax public void commit() throws SQLException



createStatement()

Function: Creates a Statement object for sending SQL statements to the database.

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.

getAutoCommit()

Function: Gets the current auto-commit state.

getCatalog()

Function: Gets the current catalog name for the connection.

Note: This method is only to be used when auto-commit is disabled. See also “setAutoCommit(boolean autoCommit)” on page 128.


Syntax public Statement createStatement() throws SQLException

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.


Syntax public Statement createStatement(int resultSetType, int resultSetConcurrency) throws SQLException


• resultSetType is a result set type

• resultSetConcurrency is a concurrency type

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.


Syntax public boolean getAutoCommit() throws SQLException

Return Current state of auto-commit mode is returned.




getHoldability()

getMetaData()

Function: 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 on. This information is made available through a DatabaseMetaData object.

getTransactionIsolation()

Function: Retrieves this Connection object’s current transaction isolation level.


Syntax public String getCatalog() throws SQLException

Return Catalog name for the connection or null is returned.

Note: Since the database does not support catalogs, ““ is always returned.

Function Retrieves the current holdability of ResultSet objects created using this Connection object.

Syntax 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.


Syntax public DatabaseMetaData getMetaData() throws SQLException

Return A DatabaseMetaData object for this Connection is returned.


Syntax public int getTransactionIsolation() throws SQLException

Return 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: Retrieves the Map object associated with this Connection object. Unless the application has added an entry, the type map returned will be empty.

getWarnings()

Function: Returns the first warning reported by calls on this Connection.

isClosed()

Function: Tests to see if a Connection is closed.

isReadOnly()

Function: Tests the connection to determine if it is in read-only mode.


Syntax public Map<String,Class<?>> getTypeMap() throws SQLException

Return Returns the java.util.Map object associated with this Connection object.


Syntax public SQLWarning getWarnings() throws SQLException

Return The first SQL warning or null is returned.

Note: Subsequent warnings will be chained to this SQL warning.


Syntax public boolean isClosed() throws SQLException

Return True, if the Connection is closed

False, if the Connection is still open


Syntax public boolean isReadOnly() throws SQLException

Return True, if the connection is read-only

False, if the connection is otherwise

Note: isReadOnly always returns False.

Note: isReadOnly always returns False.



nativeSQL(String sql)

Function: 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.

prepareCall(String sql)

Function: Creates a CallableStatement object for calling database stored procedures.

prepareCall(String sql, int resultSetType, int resultSetConcurrency)

Function: Creates a CallableStatement object for calling database stored procedures.


Syntax public String nativeSQL(String sql) throws SQLException

where the sql parameter is an SQL statement that may contain one or more question-mark parameter placeholders

Return The native form of this statement is returned.


Syntax public CallableStatement prepareCall(String sql) throws SQLException

where the sql parameter is an SQL statement that may contain one or more question-mark parameter placeholders

Typically this statement is a JDBC function call escape string.

Return A new CallableStatement object containing the precompiled SQL statement is returned.

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 CallableStatement prepareCall(String sql, int resultSetType, int resultSetConcurrency) throws SQLException


• sql is an SQL statement that may contain one or more question-mark parameter placeholders. Typically, this statement is a JDBC function call escape string.



Return A new CallableStatement object containing the precompiled SQL statement is returned.

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.


Syntax public PreparedStatement prepareStatement(String sql) throws SQLException

where the sql parameter is an SQL statement that may contain one or more question-mark IN parameter placeholders

Return A new PreparedStatement object containing the precompiled statement is returned.



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 to 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 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 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.

Note: An 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 (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 yet been created).




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 to 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 precompiled and stored in a PreparedStatement object. This object can then be used to efficiently execute this statement multiple times.




Syntax public PreparedStatement prepareStatement(String sql, int[] columnIndexes) throws SQLException


• sql is an SQL statement that may contain one or more question-mark IN parameter placeholders

• columnIndexes is an array of column indexes indicating the columns that should be returned from the inserted row or rows

Return A new PreparedStatement object, containing the precompiled statement that is capable of returning the auto-generated keys designated by the given array of column indexes is returned.


Syntax public PreparedStatement prepareStatement(String sql, String[] columnNames) throws SQLException



• columnNames is an array of column names indicating the columns that should be returned from the inserted row or rows

Return A new PreparedStatement object, containing the precompiled statement that is capable of returning the auto-generated keys designated by the given array of column names is returned.



prepareStatement(String sql, int autogeneratedKeys)

Function: Creates a default PreparedStatement object that has the capability to retrieve auto-generated keys. The given constant tells the driver whether it should make auto-generated keys available for retrieval. This parameter is ignored if the SQL statement is not an INSERT statement.



prepareStatement(String sql, int resultSetType, int resultSetConcurrency)

Function: Creates a PreparedStatement object for sending parameterized SQL statements to the database.


Syntax public PreparedStatement prepareStatement(String sql, int autogeneratedKeys) throws SQLException



• autogeneratedKeys is a flag indicating whether auto-generated keys should be returned; one of Statement.RETURN_GENERATED_KEYS or Statement.NO_GENERATED_KEYS

Return A new PreparedStatement object, containing the precompiled SQL statement that will have the capability of returning auto-generated keys is returned.

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.





rollback()

Function: Drops all changes made since the previous commit/rollback and releases any database locks currently held by the Connection.

setAutoCommit(boolean autoCommit)

Function: If a Connection is in auto-commit mode, then all its SQL statements are executed and committed as individual transactions. Otherwise, its SQL statements are grouped into transactions that are terminated by either a commit() or rollback().

By default, new connections are in auto-commit mode.


Syntax public PreparedStatement prepareStatement(String sql, int resultSetType, int resultSetConcurrency) throws SQLException





Return A new PreparedStatement object containing the precompiled statement is returned.

Note: An 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.




Syntax public void rollback() throws SQLException

Note: This method is only to be used when auto-commit is disabled.

See also “setAutoCommit(boolean autoCommit)” on page 128.



setCatalog(String catalog)

Function: 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.

setTransactionIsolation(int level)

Function: 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.


Syntax public void setAutoCommit(boolean autoCommit) throws SQLException

where the autoCommit parameter is 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.


Syntax public void setCatalog(String catalog) throws SQLException

where the catalog parameter is a catalog name

Note: As per the standard, setCatalog is silently ignored.


Syntax public void setTransactionIsolation(int level) throws SQLException

where the level parameter is 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.


Chapter 3: JDBC MethodsConnectionEvent Methods

setTypeMap(Map<String,Class<?>>map)

Function: Installs the given TypeMap object as the type map for this Connection object. The type map is used for the custom mapping of SQL structured types and distinct types.

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: Construct a ConnectionEvent object.

ConnectionEvent(PooledConnection con, SQLException ex)

Function: Construct a ConnectionEvent object.

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.


Syntax public void setTypeMap(Map<String,Class<?>> map) throws SQLException

where the map parameter is the java.util.Map object to install as the replacement for this Connection object's default type map



Syntax public ConnectionEvent(PooledConnection con)SQLException defaults to null.

where the con parameter is the pooled connection that is the source of the event.

Return ConnectionEvent is returned.


Chapter 3: JDBC MethodsConnectionEventListener Methods

getSQLException()

Function: Get the SQLException.

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 is usually 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: Notifies the ConnectionEventListener when the application calls close() on its representation of the connection.


Syntax public ConnectionEvent(PooledConnection con, SQLException ex)

where

• con is the pooled connection that is the source of the event

• ex is the SQLException about to be thrown to the application

Return Connection Event is returned.


Syntax public SQLException getSQLException()

Return The SQLException about to be thrown is returned.

Note: May be null


Chapter 3: JDBC MethodsConnectionPoolDataSource Methods

connectionErrorOccurred(ConnectionEvent event)

Function: Notifies the ConnectionEventListener when a fatal connection error occurs, just before an SQLException is thrown to the application.

ConnectionPoolDataSource Methods

Description

A ConnectionPoolDataSource object is a factory for PooledConnection objects. An object that implements this interface is typically registered with a Java Naming and Directory Interface (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.

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 are printed. This includes messages printed by the methods of this


Syntax public void connectionClosed(ConnectionEvent event)

where the event parameter is an event object describing the source of the event


Syntax public void connectionErrorOccurred(ConnectionEvent event)

where the event parameter is an event object describing the source of the event. It contains the SQL exception that the driver throws.


Syntax public int getLoginTimeout() throws SQLException

Return The DataSource login timeout value is returned.


Chapter 3: JDBC MethodsConnectionPoolDataSource Methods

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; logging is disabled.

getPooledConnection()

Function: Attempts to establish a database connection which can be used as a pooled connection.

getPooledConnection(String username, String password)

Function: Attempts to establish a database connection which can be used as a pooled connection.

setLoginTimeout(int seconds)

Function: Sets the maximum time in seconds that this connection pool data source object will wait while attempting to connect to a database.


Syntax public PrintWriter getLogWriter() throws SQLException

Return The log writer for this connection pool data source object is returned; a null if disabled.


Syntax public PooledConnection getPooledConnection() throws SQLException

Return A pooled connection to the database is returned.


Syntax public PooledConnection getPooledConnection(String username, String password) throws SQLException


• username is the database user on whose behalf the Connection is being made

• password is the user’s password

Return A Connection to the database is returned.


Chapter 3: JDBC MethodsDatabaseMetaData Methods

setLogWriter(PrintWriter out)

Function: Sets the log writer for this connection pool data source object to the java.io.PrintWriter.object.

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. 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, that argument's criteria is to be dropped from the search.


Syntax public void setLoginTimeout(int seconds) throws SQLException

where the seconds parameter is the data source login time limit

Note: 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.


Syntax public void setLogWriter(PrintWriter out)throws SQLException

where the out parameter is the new log writer; to disable logging, set to null

Return The log writer for this data source is returned; 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 are 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; logging is disabled.



An SQLException is 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.

allProceduresAreCallable()

Function: Determines if all of the procedures returned by getProcedures can be called by the current user.

allTablesAreSelectable()

Function: Determines if all the tables returned by getTable can be selected by the current user.

dataDefinitionCausesTransactionCommit()

Function: Determines if a data definition statement within a transaction forces the transaction to commit.


Syntax public boolean allProceduresAreCallable() throws SQLException

Return 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


Syntax public boolean allTablesAreSelectable() throws SQLException

Return 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


Syntax public boolean dataDefinitionCausesTransactionCommit() throws SQLException

Return 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: Determines if a data definition statement within a transaction is ignored.

deletesAreDetected(int type)

Function: Determines if a visible row delete can be detected by calling ResultSet.rowDeleted().

If deletesAreDetected() returns false, then deleted rows are removed from the ResultSet.

doesMaxRowSizeIncludeBlobs()

Function: Determines if getMaxRowSize() includes 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


Syntax public boolean dataDefinitionIgnoredInTransactions() throws SQLException

Return True, if a data definition statement within a transaction is ignored

False, if a data definition statement within a transaction is not ignored


Syntax public boolean deletesAreDetected(int type) throws SQLException

Return True, if changes are detected by the resultset type

False, if changes are not detected by the resultset type


Syntax public boolean doesMaxRowSizeIncludeBlobs() throws SQLException

Return True, if getMaxRowSize() includes LONGVARCHAR and LONGVARBINARY Blobs

False, if getMaxRowSize() does not include LONGVARCHAR and LONGVARBINARY Blobs



• 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

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–Nullability unknown

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–the column definitely does not allow NULL values

Yes–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)



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.


SCOPE_TABLE String Source type of a distinct type or user-generated 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 user-generated Ref type, SQL type from java.sql.Types (null if DATA_TYPE isn't DISTINCT or user-generated REF)


Syntax public ResultSet getAttributes(String catalog, String schemaPattern, String typeNamePattern, String attributeNamePattern) throws SQLException


• catalog is a catalog name; must match the catalog name as it is stored in the database: "" –retrieve those without a catalognull –drop catalog name from the selection criteria

• schemaPattern is a schema name; must match the schema name as it is stored in the database:"" –retrieve those without a catalog.null –drop catalog name from the selection criteria

• typeNamePattern is a type name pattern

• attributeNamePattern is an attribute name pattern

Return ResultSet–each row is an attribute description

Column Description

SCOPE Short Actual scope of results:

• bestRowTemporary –very temporary, while using row

• bestRowTransaction–valid for remainder of current transaction

• bestRowSession–valid for remainder of current session

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 Description



getCatalogs()

Function: Determines the catalog names available in the database.

Each catalog description includes:

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


Syntax public ResultSet getBestRowIdentifier(String catalog, String schema, String table, int scope, boolean nullable) throws SQLException


• catalog is a catalog name; must match the catalog name as it is stored in the database:" –retrieve those without a catalognull –the catalog name is not to be used to narrow the search

• schema is a schema name pattern; must match the schema name as it is stored in the database: "" –retrieve those without a schema namenull –the schema name is not to be used to narrow the search

• table is a table name; must match the table name as it is stored in the database

• scope is the scope of interest; use same values as SCOPE

• nullable includes columns that are nullable

Return ResultSet–each row is a column description

Column Description

TABLE_CAT String Table catalog name


Syntax public ResultSet getCatalogs() throws SQLException

Return The results are ordered by catalog name. Each row has a single String column that is a catalog name.

Column Description



getCatalogSeparator()

Function: Determines the separator string between catalog and table name.

getCatalogTerm()

Function: Determines the preferred vendor term for catalog.

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:

Note: Currently returns a null. Will be changed in a future release to return an empty result set.


Syntax public String getCatalogSeparator() throws SQLException

Return The separator string between catalog and table name is returned.

Note: Always returns a "". Catalogs are not supported on the database.

Note: Always returns a "". Catalogs are not supported on the database.


Syntax public String getCatalogTerm() throws SQLException

Return The preferred vendor term for catalog is returned.

Note: Always returns a ““. Catalogs are not supported on the database.

Note: Always returns a ““. Catalogs are not supported on the database.

Column Description

TABLE_CAT String Table catalog (may be null)

TABLE_SCHEM String Table schema (may be null)

TABLE_NAME String Table name





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


GRANTORString Grantor of access (may be null)

GRANTEE String Grantee of access

PRIVILEGE String Name of access (SELECT, INSERT, UPDATE, REFRENCES, and so on)

IS_GRANTABLE String YES if grantee is permitted to grant to others;NO if not; null if unknown


Syntax public ResultSet getColumnPrivileges(String catalog,String schema, String table, String columnNamePattern)throws SQLException


• catalog is a catalog name; must match the catalog name as it is stored in the database:"" –retrieves those without a catalognull –the catalog name is not to be used to narrow the search

• schema is a schema name pattern; must match the schema name as it is stored in the database: "" –retrieve those without a schema namenull –the schema name is not to be used to narrow the search


• columnNamePattern is a column name pattern; must match the column name as it is stored in the database

Return ResultSet–each row is a column privilege description

Note: See also the method “getSearchStringEscape()” on page 158.

Column Description



Column Description





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.

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–Nullability 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–the column definitely does not allow NULL values

YES–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)

SCOPE_TABLE String Table name that is the scope of a reference attribute (null if the DATA_TYPE isn't REF)

SOURCE_DATA_TYPE short Source type of a distinct type of user-generated Ref type, SQL type from java.sql.Types (null if DATA_TYPE isn’t DISTINCT or user-generated REF)



getConnection()

Function: Retrieves the connection that produced this metadata object.

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 normally returns 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



Syntax public ResultSet getColumns(String catalog, String schemaPattern, String tableNamePattern, String columnNamePattern) throws SQLException


• catalog is a catalog name““ –retrieves those without a catalognull –drop catalog name from the selection criteria

• schemaPattern is a schema name pattern““ –retrieves those without a catalognull –drop catalog name from the selection criteria

• tableNamePattern is a table name pattern

• columnNamePattern is an attribute name pattern

Return ResultSet–each row is a a column name pattern



Syntax public Connection getConnection() throws SQLException

Return The connection that produced this metadata object is returned.



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

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



getDatabaseMajorVersion()

Function: Retrieves the major version number of the underlying database.

getDatabaseMinorVersion()

Function: Retrieves the minor version number of the underlying database.


Syntax public ResultSet getCrossReference(String primaryCatalog, String primarySchema, String primaryTable, String foreignCatalog, String foreignSchema, String foreignTable) throws SQLException


• primaryCatalog is a catalog name; must match the catalog name as it is stored in the database:““ –retrieves those without a catalognull –drop catalog name from the selection criteria

• primarySchema is a schema name pattern; must match the schema name as it is stored in the database:““ –retrieves those without a schemanull –drop schema name from the selection criteria

• primaryTable is the name of the table that exports the key; must match the table name as it is stored in the database

• foreignCatalog is a catalog name; must match the catalog name as it is stored in the database:““ –retrieves those without a catalognull –drop catalog name from the selection criteria

• foreignSchema is a schema name; must match the schema name as it is stored in the database:““ –retrieves those without a schemanull –drop schema name from the selection criteria

• foreignTable is the name of the table that imports the key; must match the table name as it is stored in the database

Return ResultSet–each row is a foreign key column description

Note: See also the getImportedKeys(java.lang.String, java.lang.String, java.lang.String) method.


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.



getDatabaseProductName()

Function: Determines the name of this database product.

getDatabaseProductVersion()

Function: Determines the version of this database product.

getDefaultTransactionIsolation()

Function: Determines the default transaction isolation level of the database

getDriverMajorVersion()

Function: Determines this JDBC Driver’s major version number.


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.


Syntax public String getDatabaseProductName() throws SQLException

Return The database product name is returned.


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.


Syntax public int getDefaultTransactionIsolation() throws SQLException

Return The default isolation level is returned.

Note: The values are defined in java.sql.Connection.



getDriverMinorVersion()

Function: Determines this JDBC Driver’s minor version number

getDriverName()

Function: Determines the name of this JDBC Driver.

getDriverVersion()

Function: Determines the version of this JDBC Driver.

getExtraNameCharacters()

Function: Gets all the extra characters that can be used in unquoted identifier names; those beyond a-z, A-Z, 0-9, and _.


Syntax public int getDriverMajorVersion()

Return The JDBC Driver major version number is returned.


Syntax public int getDriverMinorVersion()

Return The JDBC Driver minor version number is returned.


Syntax public String getDriverName() throws SQLException

Return The JDBC Driver name is returned.


Syntax public String getDriverVersion() throws SQLException

Return The JDBC Driver version is returned.


Syntax public String getExtraNameCharacters() throws SQLException

Return The string containing extra characters is returned.



getIdentifierQuoteString()

Function: Determines the string used to quote SQL identifiers.

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:


Syntax public String getIdentifierQuoteString() throws SQLException

Return 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.

Column Description




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.



getMaxBinaryLiteralLength()

Function: Determines how many hex characters are permitted in an in line binary literal.

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.

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 conditions, if any (may be null)


Syntax public ResultSet getIndexInfo(String catalog, String schema, String table, boolean unique, boolean approximate) throws SQLException


• catalog is a catalog name:““ –retrieves those without a catalognull –drop catalog name from the selection criteria

• schema is a schema name:““ –retrieves those without a schema

• table is a table name

• unique is indice uniqueness:True–returns only indices for unique valuesFalse–returns indices regardless of whether unique or not

• approximate is approximate values:True–result is allowed to reflect approximate or out-of-data valuesFalse–results are requested to be accurate

Return ResultSet–each row is an index column description

Characteristics Description

Syntax public int getMaxBinaryLiteralLength() throws SQLException

Return The maximum binary literal length in hex characters is returned.

Note: A result of zero indicates that there is no limit to the binary literal or the limit is unknown.

Column Description



getMaxCatalogNameLength()

Function: Determines the maximum length of a catalog name.

getMaxCharLiteralLength()

Function: Determines the maximum length for a character literal.

getMaxColumnNameLength()

Function: Determines the limit on column name length.

getMaxColumnsInGroupBy()

Function: Determines the maximum number of columns in a GROUP BY clause.

getMaxColumnsInIndex()

Function: Determines the maximum number of columns allowed in an index.


Syntax public int getMaxCatalogNameLength() throws SQLException

Return The maximum catalog name length in bytes is returned.

Note: A result of zero indicates that there is no limit to the catalog name or the limit is unknown.


Syntax public int getMaxCharLiteralLength() throws SQLException

Return The maximum literal length is returned.

Note: A result of zero indicates that there is no limit to the Character literal or the limit is unknown.


Syntax public int getMaxColumnNameLength() throws SQLException

Return The maximum literal length for a column name is returned.


Syntax public int getMaxColumnsInGroupBy() throws SQLException

Return The maximum number of columns in a GROUP BY clause is returned.

Note: A result of zero indicates that there is no limit or the limit is unknown.



getMaxColumnsInOrderBy()

Function: Determines the maximum number of columns allowed in an ORDER BY clause.

getMaxColumnsInSelect()

Function: Determines the maximum number of columns allowed in a SELECT list.

getMaxColumnsInTable()

Function: Determines the maximum number of columns allowed in a table.

getMaxConnections()

Function: Determines how many active connections are allowed at a time to this database.


Syntax public int getMaxColumnsInIndex() throws SQLException

Return The maximum number of columns allowed in an index is returned.



Syntax public int getMaxColumnsInOrderBy() throws SQLException

Return The maximum number of columns allowed in an ORDER BY clause is returned.



Syntax public int getMaxColumnsInSelect() throws SQLException

Return The maximum number of columns allowed in a SELECT list is returned.



Syntax public int getMaxColumnsInTable() throws SQLException

Return The maximum number of columns allowed in a table is returned.




getMaxCursorNameLength()

Function: Determines the maximum cursor name length in bytes.

getMaxIndexLength()

Function: Determines the maximum length of an index in bytes.

getMaxProcedureNameLength()

Function: Determines the maximum length of a procedure name.

getMaxRowSize()

Function: Determines the maximum length of a single row in bytes.


Syntax public int getMaxConnections() throws SQLException

Return The maximum active connections allowed at a time to this database is returned.



Syntax public int getMaxCursorNameLength() throws SQLException

Return The maximum cursor name length in bytes is returned.



Syntax public int getMaxIndexLength() throws SQLException

Return The maximum length of an index in bytes is returned.



Syntax public int getMaxProcedureNameLength() throws SQLException

Return The maximum procedure name length in bytes is returned.




getMaxSchemaNameLength()

Function: Determines the maximum length allowed for a schema name in bytes.

getMaxStatementLength()

Function: Determines the maximum length of an SQL statement in bytes.

getMaxStatements()

Function: Determines how many active statements can be open at any one time.

getMaxTableNameLength()

Function: Determines the maximum length of a table name in bytes.


Syntax public int getMaxRowSize() throws SQLException

Return The maximum length of a single row in bytes is returned.



Syntax public int getMaxSchemaNameLength() throws SQLException

Return The maximum length allowed for a schema name in bytes is returned.



Syntax public int getMaxStatementLength() throws SQLException

Return The maximum length of an SQL statement in bytes is returned.



Syntax public int getMaxStatements() throws SQLException

Return The maximum number of active statements allowed at one time is returned.




getMaxTablesInSelect()

Function: Determines the maximum number of tables in a SELECT statement.

getMaxUserNameLength()

Function: Determines the maximum length of a user name.

getNumericFunctions()

Function: Gets a comma-separated list of the X/Open CLI math function names in JDBC function escape clauses.

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:


Syntax public int getMaxTableNameLength() throws SQLException

Return The maximum length of a table name in bytes is returned.



Syntax public int getMaxTablesInSelect() throws SQLException

Return The maximum number of tables allowed in a SELECT statement is returned.



Syntax public int getMaxUserNameLength() throws SQLException

Return The maximum user name length in bytes is returned.

Note: Zero indicates that there is no limit or the limit is not known.


Syntax public String getNumericFunctions() throws SQLException

Return The list of math functions is returned.



getProcedureColumns(String catalog, String schemaPattern, String procedureNamePattern, String columnNamePattern)

Function: Gets a description of the stored procedure parameters and result columns of a catalog.

Column Description





KEY_SEQ short Sequence number within primary key

PK_NAME String Primary key name (may be null)


Syntax public ResultSet getPrimaryKeys(String catalog, String schema, String table) throws SQLException



• schema is a schema name:““ –retrieves those without a schema

• table is a table name

Return ResultSet–each row is a primary key column description


Syntax public ResultSet getProcedureColumns(String catalog, String schemaPattern, String procedureNamePattern, String columnNamePattern) throws SQLException


• catalog is a catalog name: ““ –retrieves those without a catalognull –drop catalog name from the selection criteria

• schemaPattern is a schema name pattern:““ –retrieves those without a schemanull –drop schema name from the selection criteria

• procedureNamePattern is a procedure name pattern

• columnNamePattern is a column name pattern



The column descriptions follow in column number order.

Each row in the ResultSet is a parameter description or column description with the following fields:

Return 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.

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 Type 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

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

NULLABLE short Can it contain NULL?

• procedureNoNulls–does not allow NULL values

• procedureNullable–allows NULL values

• procedureNullableUnknown

REMARKS String 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: Gets a description of the stored procedures available in a catalog.

Each procedure description has the following columns:

getProcedureTerm()

Function: Determines the database vendor preferred term for procedure.


Syntax public ResultSet getProcedures(String catalog, String schemaPattern, String procedureNamePattern) throws SQLException



• schemaPattern is a schema name pattern:““ –retrieves those without a schema

• procedureNamePattern is a procedure name pattern

Return ResultSet where each row is a procedure description, ordered by PROCEDURE_SCHEM and PROCEDURE_NAME.

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



REMARKS String Explanatory comment on the procedure

PROCEDURE_TYPE short Type of procedure:

• procedureResultunknown–may return result

• procedureNoResult–does not return guilty

• procedureReturnsResult–returns a result


Syntax public String getProcedureTerm() throws SQLException



getResultSetHoldability()

Function: Retrieves the default holdability of this ResultSet object.

getSchemas()

Function: Gets the schema names available in this database; results are ordered by schema name.

getSchemaTerm()

Function: Determines 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

Return The database vendor’s preferred term for procedure is returned.


Syntax public int getResultSetHoldability() throws SQLException

Return The default holdability: ResultSet_HOLD_CURSORS_OVER_COMMIT is returned.

Note: The Teradata JDBC Driver currently does not support ResultSet.CLOSE_CURSORS_AT_COMMIT


Syntax public ResultSet getSchemas() throws SQLException

where TABLE_SCHEM String is the schema name

Return ResultSet–each row has a single String column that is a schema name


Syntax public String getSchemaTerm() throws SQLException

Return The term for schema that is preferred by the database vendor is returned.




getSQLKeywords()

Function: Gets a comma-separated list of all the SQL keywords in a database that are NOT also SQL92 keywords.

getStringFunctions()

Function: Gets a comma-separated list of X/Open CLI string function names used in the JDBC function escape clause.

getSystemFunctions()

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.

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 is 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; ordered by:

• TABLE_SCHEM


Syntax public String getSearchStringEscape() throws SQLException

Return The string used to escape wildcard characters is returned.


Syntax public String getSQLKeywords() throws SQLException

Return The list of keywords is returned.


Syntax public String getStringFunctions() throws SQLException

Return The list of string functions is returned.


Syntax public String getSystemFunctions() throws SQLException

Return The list of system functions is returned.



• TABLE_NAME

• PRIVILEGE

Each table description includes:

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

Column Description




GRANTOR String Grantor of access (may be null)

GRANTEE String Grantee of access

PRIVILEGE String Name of access (SELECT, INSERT, UPDATE, REFERENCES, and so on)

IS_GRANTABLE String YES if grantee is permitted to grant to others;NO if not;null if unknown


Syntax public ResultSet getTablePrivileges(String catalog, String schemaPattern, String tableNamePattern)throws SQLException


• catalog is a catalog name; must match the catalog name as it is stored in the database:““ –retrieves those without a catalognull –the catalog name should not be used to narrow the search

• schemaPatternis a schema name pattern; must match the schema name as it is stored in the database:““ –retrieves those without a schemanull –the schema name should not be used to narrow the search

• tableNamePattern is a table name pattern; must match the table name as it is stored in the database

Return ResultSet–each row is a table privilege description




Only table descriptions matching the catalog, schema, table name, and type criteria are returned.

Each table description includes:

getTableTypes()

Function: Gets the table types available in the database system. The results are ordered by table types.

Column Description




TABLE_TYPE String Table type. Typical types are:

• TABLE

• VIEW

• SYSTEM TABLE

• GLOBAL TEMPORARY

• LOCAL TEMPORARY

• ALIAS

• SYNONYM

REMARKS String Explanatory comment on the table


Syntax public ResultSet getTables(String catalog, String schemaPattern, String tableNamePattern, String[] types) throws SQLException



• schemaPattern is a schema name pattern;““ –retrieves those without a schema

• tableNamePattern is a table name pattern

• types is a list of table types to include:null –returns all types

Return ResultSet–each row is a table description

Note: Some databases may not return information for all tables.

See also the method “getSearchStringEscape()” on page 158.



getTimeDateFunctions()

Function: Gets a comma-separated list of time and date functions.

getTypeInfo()

Function: Gets 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:


Syntax public getTableTypes() throws SQLException

where the TABLE_TYPE Stringcolumn is a table type. Typical types are:

• TABLE

• VIEW

• SYSTEM TABLE

• GLOBAL TEMPORARY

• LOCAL TEMPORARY

• ALIAS

• SYNONYM

Return A ResultSet object with each row as a single string column is a table type


Syntax public String getTimeDateFunctions() throws SQLException

Return The list of time and date functions is returned.

Column Description


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)



getUDTs(String catalog, String schemaPattern, string typeNamePattern, int[] types)

Function: Retrieves a description of the UDTs defined in a particular schema. 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:

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 Indicates whether it is possible to use 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

AUTO_INCREMENT boolean True indicates the type can be used for auto-increment

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


Syntax public ResultSet getTypeInfo() throws SQLException

Return ResultSet–each row is an SQL type description

Column Description



• 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.

getURL()

Function: Determines the URL for this database.

Column Description

TYPE_CAT String The type’s catalog (may be null)

TYPE_SCHEM String Type’s schema (may be null)


CLASS_NAME String Java class name

DATA_TYPE int Type value defined in java.sql.Types. One of JAVA_OBJECT, STRUCT, or DISTINCT.

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 user-generated 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).


Syntax public ResultSet getUDTs(String catalog, String schemaPattern, string typeNamePattern, int[] types) throws SQLException


• catalog is a catalog name:““ –retrieve those without a catalognull –drop catalog name from the selection criteria

• schemaPattern is a schema name pattern:““ –retrieve those without a catalognull –drop catalog name from the selection criteria

• typeNamePattern is a type name pattern

• types is a list of user-defined types (JAVA_OBJECT, STRUCT, or DISTINCT) to include; null –returns all types

Return ResultSet–each row describes a UDT



getUserName()

Function: Determines your user name, as known to the database.

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:


Syntax public String getURL() throws SQLException

Return If it can be generated, the URL;

If it cannot be generated, null.


Syntax public String getUserName() throws SQLException

Return Your database user name is returned.

Column Description

SCOPE short Is not used


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



insertsAreDetected(int type)

Function: Determines if a visible row insert can be detected by calling ResultSet.rowInserted().

isCatalogAtStart()

Function: Determines if a catalog appears at the start of a table.


Syntax getVersionColumns(String catalog, String schema, String table) throws SQLException


• catalog is a catalog name; must match the catalog name as it is stored in the database:““ –retrieves those without a catalognull –the catalog name should not be used to narrow the search

• schema is a schema name; must match the schema name as it is stored in the database:““ –retrieves those without a schemanull –the schema name should not be used to narrow the search


Return A ResultSet object in which each row is a column description is returned.

Note: Teradata implementation for getVersionColumns is limited and gives back only an empty resultset.


Syntax public boolean insertsAreDetected(int type) throws SQLException

where the parameter type is the ResultSet type, such as TYPE_XXX

Return True, if changes are detected by the resultset type

False, if changes are not detected by the resultset type


Syntax public boolean isCatalogAtStart() throws SQLException

Return True, if the catalog appears at the start of the table

False, if it does not appear at the start of the table

Note: 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: Determines if the database is in read-only mode.

nullPlusNonNullIsNull()

Function: Determines if concatenations between NULL and nonNULL values is NULL.

nullsAreSortedAtEnd()

Function: Determines if NULL values are sorted at the end, regardless of sort order.

nullsAreSortedAtStart()

Function: Determines if NULL values are sorted at the start, regardless of sort order.

nullsAreSortedHigh()

Function: Determines if NULL values are sorted high.


Syntax public boolean isReadOnly() throws SQLException

Return True, if the database is in read-only mode

False, if the database is not in read-only mode


Syntax public boolean nullPlusNonNullIsNull() throws SQLException

Return True, if concatenations between NULL and nonNULL values are NULL

False, if concatenations between NULL and nonNULL values are not NULL


Syntax public boolean nullsAreSortedAtEnd() throws SQLException

Return True, if NULL values are sorted at the end, regardless of sort order

False, if NULL values are not sorted at the end


Syntax public boolean nullsAreSortedAtStart() throws SQLException

Return True, if NULL values sorted at the start, regardless of sort order

False



nullsAreSortedLow()

Function: Determines if NULL values are sorted low.

othersDeletesAreVisible(int type)

Function: Determines if deletes made by others are visible.

othersInsertsAreVisible(int type)

Function: Determines if inserts made by others are visible.


Syntax public boolean nullsAreSortedHigh() throws SQLException

Return True, if null values are sorted high

False, if null values are not sorted high


Syntax public boolean nullsAreSortedLow() throws SQLException

Return True, if NULL values are sorted low

False, if null values are not sorted low


Syntax public boolean othersDeletesAreVisible(int type) throws SQLException

where the type parameter is the ResultSet type, such as TYPE_XXX

Return 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, because updatable ResultSets are not supported.


Syntax public boolean othersInsertsAreVisible(int type) throws SQLException


Return 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




othersUpdatesAreVisible(int type)

Function: Determines if updates made by others are visible.

ownDeletesAreVisible(int type)

Function: Determines if the own deletes of a ResultSet are visible.

ownInsertsAreVisible(int type)

Function: Determines if the own inserts of a ResultSet are visible.

ownUpdatesAreVisible(int type)

Function: Determines if the own updates of a ResultSet are visible.


Syntax public boolean othersUpdatesAreVisible(int type) throws SQLException


Return 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



Syntax public boolean ownDeletesAreVisible(int type) throws SQLException


Return True, if deletes are visible for the ResultSet type

False, if deletes are not visible for the ResultSet type



Syntax public boolean ownInsertsAreVisible(int type) throws SQLException


Return True, if inserts are visible for the ResultSet type

False, if inserts are not visible for the ResultSet type




storesLowerCaseIdentifiers()

Function: Determines if the database treats mixed case unquoted SQL identifiers as case-insensitive and stores them in lower case.

storesLowerCaseQuotedIdentifiers()

Function: Determines if the database treats mixed case quoted SQL identifiers as case-insensitive and stores them in lower case.

storesMixedCaseIdentifiers()

Function: Determines if the database treats mixed case unquoted SQL identifiers as case-insensitive and stores them in mixed case.


Syntax public boolean ownUpdatesAreVisible(int type) throws SQLException


Return True, if updates are visible for the ResultSet type

False, if updates are not visible for the ResultSet type



Syntax public boolean storesLowerCaseIdentifiers() throws SQLException

Return 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


Syntax public boolean storesLowerCaseQuotedIdentifiers() throws SQLException

Return 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



storesMixedCaseQuotedIdentifiers()

Function: Determines if the database treats mixed case quoted SQL identifiers as case-insensitive and stores them in mixed case.

storesUpperCaseIdentifiers()

Function: Determines if the database treats mixed case unquoted SQL identifiers as case-insensitive and stores them in upper case.

storesUpperCaseQuotedIdentifiers()

Function: Determines if the database treats mixed case quoted SQL identifiers as case-insensitive and stores them in upper case.


Syntax public boolean storesMixedCaseIdentifiers() throws SQLException

Return True, if the database treats mixed case unquoted SQL identifiers as case-insensitive and stores them in mixed case



Syntax public boolean storesMixedCaseQuotedIdentifiers() throws SQLException

Return True, if the database treats mixed case quoted SQL identifiers as case-insensitive and stores them in mixed case



Syntax public boolean storesUpperCaseIdentifiers() throws SQLException

Return True, if the database treats mixed case unquoted SQL identifiers as case-insensitive and stores them in upper case



Syntax public boolean storesUpperCaseQuotedIdentifiers() throws SQLException



supportsAlterTableWithAddColumn()

Function: Determines if ALTER TABLE with add column is supported.

supportsAlterTableWithDropColumn()

Function: Determines if ALTER TABLE with drop column is supported.

supportsANSI92EntryLevelSQL()

Function: Determines if the ANSI92 entry level SQL grammar is supported.

supportsANSI92FullSQL()

Function: Determines if the ANSI92 full SQL grammar is supported.

Return True, if the database treats mixed case quoted SQL identifiers as case-insensitive and stores them in upper case



Syntax public boolean supportsAlterTableWithAddColumn() throws SQLException

Return True, if ALTER TABLE with add column is supported

False, if ALTER TABLE with add column is not supported


Syntax public boolean supportsAlterTableWithDropColumn() throws SQLException

Return True, if ALTER TABLE with drop column is supported

False, if ALTER TABLE with drop column is not supported


Syntax public boolean supportsANSI92EntryLevelSQL() throws SQLException

Return True if the ANSI92 entry level SQL grammar is supported

Note: All JDBC-compliant drivers must return true.




supportsANSI92IntermediateSQL()

Function: Determines if the ANSI92 intermediate SQL grammar is supported.

supportsBatchUpdates()

Function: Determines if the driver supports batch updates.

supportsCatalogsInDataManipulation()

Function: Determines if a catalog name can be used in a data manipulation statement.

supportsCatalogsInIndexDefinitions()

Function: Determines if a catalog name can be used in an index definition statement.


Syntax public boolean supportsANSI92FullSQL() throws SQLException

Return True, if the ANSI92 full SQL grammar is supported

False, if the ANSI92 full SQL grammar is not supported


Syntax public boolean supportsANSI92IntermediateSQL() throws SQLException

Return True, if the ANSI92 intermediate SQL grammar is supported

False, if the ANSI92 intermediate SQL grammar is not supported


Syntax public boolean supportsBatchUpdates() throws SQLException

Return True, if the driver supports batch updates

False, if the driver does not support batch updates


Syntax public boolean supportsCatalogsInDataManipulation() throws SQLException

Return 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



supportsCatalogsInPrivilegeDefinitions()

Function: Determines if a catalog name can be used in a privilege definition statement.

supportsCatalogsInProcedureCalls()

Function: Determines if a catalog name can be used in a procedure call statement.

supportsCatalogsInTableDefinitions()

Function: Determines if a catalog name can be used in a table definition statement.

supportsColumnAliasing()

Function: Determines 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.


Syntax public boolean supportsCatalogsInIndexDefinitions() throws SQLException

Return 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


Syntax public boolean supportsCatalogsInPrivilegeDefinitions() throws SQLException

Return 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


Syntax public boolean supportsCatalogsInProcedureCalls() throws SQLException

Return 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


Syntax public boolean supportsCatalogsInTableDefinitions() throws SQLException

Return True, if a catalog name can be used in a table definition statement

False, if a catalog name cannot be used in a table definition statement



supportsConvert()

Function: Determines if the CONVERT function between SQL types is supported.

supportsConvert(int fromType, int toType)

Function: Determines if the CONVERT function between SQL types is supported.

supportsCoreSQLGrammar()

Function: Determines if the ODBC Core SQL grammar is supported.


Syntax public boolean supportsColumnAliasing() throws SQLException

Return True, if column aliasing is supported

Note: A JDBC-compliant driver always returns true.


Syntax public boolean supportsConvert() throws SQLException

Return True, if the CONVERT function between SQL types is supported

False, if the CONVERT function between SQL types is not supported


Syntax public boolean supportsConvert(int fromType, int toType) throws SQLException


• fromType is converted from this type

• toType is converted to this type

Return True, if the CONVERT function between SQL types is supported

False, if the CONVERT function between SQL types is not supported


Syntax public boolean supportsCoreSQLGrammar() throws SQLException

Return True, if the ODBC core SQL grammar is supported

False, if the ODBC core SQL grammar is not supported



supportsCorrelatedSubqueries()

Function: Determines if correlated subqueries are supported.

supportsDataDefinitionAndDataManipulationTransactions()

Function: Determines if both data definition and data manipulation statements within a transaction are supported.

supportsDataManipulationTransactionsOnly()

Function: Determines if only data manipulation statements within a transaction are supported.

supportsDifferentTableCorrelationNames()

Function: If table correlation names are supported, determines if they must be different from the names of the tables.


Syntax public boolean supportsCorrelatedSubqueries() throws SQLException

Return True, if correlated subqueries are supported



Syntax public boolean supportsDataDefinitionAndDataManipulationTransactions() throws SQLException

Return True, if both a data definition and data manipulation statement within a transaction are supported

False, if data definition or data manipulation statements within a transaction are not supported


Syntax public boolean supportsDataManipulationTransactionsOnly() throws SQLException

Return True, if only data manipulation statements within a transaction are supported

False, if only data definition statements within a transaction are also supported



supportsExpressionsInOrderBy()

Function: Determines if expressions in ORDER BY list are supported.

supportsExtendedSQLGrammar()

Function: Determines if the ODBC extended SQL grammar is supported.

supportsFullOuterJoins()

Function: Determines if full nested outer joins are supported.

supportsGetGeneratedKeys()

Function: Determines if auto-generated keys can be retrieved after a statement has been executed.


Syntax public boolean supportsDifferentTableCorrelationNames() throws SQLException

Return True, if supported table correlation names must be different

False, if supported table correlation names need not be different


Syntax public boolean supportsExpressionsInOrderBy() throws SQLException

Return True, if expressions in ORDER BY lists are supported

False, if expressions in ORDER BY lists are not supported


Syntax public boolean supportsExtendedSQLGrammar() throws SQLException

Return True, if the ODBC extended SQL grammar is supported

False, if the ODBC extended SQL grammar is not supported


Syntax public boolean supportsFullOuterJoins() throws SQLException

Return True, if full nested outer joins are supported

False, if full nested outer joins are not supported



supportsGroupBy()

Function: Determines if some form of GROUP BY clause is supported.

supportsGroupByBeyondSelect()

Function: Determines if a GROUP BY clause can add columns not in the SELECT provided it specifies all the columns in the SELECT.

supportsGroupByUnrelated()

Function: Determines if a GROUP BY clause can use columns not in the SELECT.

supportsIntegrityEnhancementFacility()

Function: Determines if the SQL Integrity Enhancement Facility is supported.


Syntax public boolean supportsGetGeneratedKeys() throws SQLException

Return True, if auto-generated keys can be retrieved after a statement has been executed

False, if otherwise


Syntax public boolean supportsGroupBy() throws SQLException

Return True, if some form of GROUP BY clause is supported

False, if some form of GROUP BY clause is not supported


Syntax public boolean supportsGroupByBeyondSelect() throws SQLException

Return 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


Syntax public boolean supportsGroupByUnrelated() throws SQLException

Return 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



supportsLikeEscapeClause()

Function: Determines if the escape character in LIKE clauses is supported.

supportsLimitedOuterJoins()

Function: Determines if there is limited support for outer joins.

supportsMinimumSQLGrammar()

Function: Determines if the ODBC minimum SQL grammar is supported.


Syntax public boolean supportsIntegrityEnhancementFacility() throws SQLException

Return True, if the facility is supported

False, if the facility is not supported


Syntax public boolean supportsLikeEscapeClause() throws SQLException

Return True, if the escape character in LIKE clauses is supported



Syntax public boolean supportsLimitedOuterJoins() throws SQLException

Return 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.


Syntax public boolean supportsMinimumSQLGrammar() throws SQLException

Return 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: Determines if the database treats mixed case unquoted SQL identifiers as case-sensitive and as a result stores them in mixed case.

supportsMixedCaseQuotedIdentifiers()

Function: Determines if the database treats mixed case quoted SQL identifiers as case-sensitive and as a result stores them in mixed case.

supportsMultipleOpenResults()

Function: Determines if it is possible to have multiple ResultSet objects returned from a CallableStatement object simultaneously.

supportsMultipleResultSets()

Function: Determines if multiple ResultSets from a single execute are supported.


Syntax public boolean supportsMixedCaseIdentifiers() throws SQLException

Return 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.


Syntax public boolean supportsMixedCaseQuotedIdentifiers() throws SQLException

Return 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


Syntax public boolean supportsMultipleOpenResults() throws SQLException

Return • True, if a CallableStatement object can return multiple ResultSet objects simultaneously

• False, if otherwise



supportsMultipleTransactions()

Function: Determines if multiple transactions can be open at once (on different connections).

supportsNonNullableColumns()

Function: Determines if columns can be defined as non-nullable.

supportsOpenCursorsAcrossCommit()

Function: Determines if cursors can remain open across commits.

supportsOpenCursorsAcrossRollback()

Function: Determines if cursors can remain open across rollbacks.


Syntax public boolean supportsMultipleResultSets() throws SQLException

Return True, if multiple ResultSets from a single execute are supported

False, if multiple ResultSets from a single execute are not supported


Syntax public boolean supportsMultipleTransactions() throws SQLException

Return True, if multiple transactions can be open at once (on different connections)

False, if multiple connections cannot be open at once (on different connections)


Syntax public boolean supportsNonNullableColumns() throws SQLException

Return True, if columns can be defined as non-nullable.



Syntax public boolean supportsOpenCursorsAcrossCommit() throws SQLException

Return True, if cursors can remain open across commits

False, if cursors cannot remain open across commits



supportsOpenStatementsAcrossCommit()

Function: Determines if statements remain open across commits.

supportsOpenStatementsAcrossRollback()

Function: Determines if statements can remain open across rollbacks.

supportsOrderByUnrelated()

Function: Determines if an ORDER BY clause can use columns not in the SELECT statement.

supportsOuterJoins()

Function: Determines if some form of outer join is supported.


Syntax public boolean supportsOpenCursorsAcrossRollback() throws SQLException

Return True, if cursors can remain open across rollbacks

False, if cursors cannot remain open across rollbacks


Syntax public boolean supportsOpenStatementsAcrossCommit() throws SQLException

Return True, if statements always remain open across commits

False, if statements might not remain open across commits


Syntax public boolean supportsOpenStatementsAcrossRollback() throws SQLException

Return True, if statements always remain open across rollback

False, if statements might not remain open across rollbacks


Syntax public boolean supportsOrderByUnrelated() throws SQLException

Return 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



supportsPositionedDelete()

Function: Determines if positioned DELETE is supported.

supportsPositionedUpdate()

Function: Determines if positioned UPDATE is supported.

supportsResultSetConcurrency(int type, int concurrency)

Function: Determines if the database supports the concurrency type in combination with the given ResultSet type.


Syntax public boolean supportsOuterJoins() throws SQLException

Return True, if some form of outer join is supported

False, if some form of outer join is not supported


Syntax public boolean supportsPositionedDelete() throws SQLException

Return True, if positioned DELETE is supported

False, if positioned DELETE is not supported


Syntax public boolean supportsPositionedUpdate() throws SQLException

Return True, if positioned UPDATE is supported

False, if positioned UPDATE is not supported


Syntax public boolean supportsResultSetConcurrency(int type, int concurrency) throws SQLException


• type is the ResultSet type, such as TYPE_XXX

• concurrency is the type defined in java.sql.ResultSet

Return True, if the database supports the concurrency type in combination with the ResultSet type

False, if the database does not support the concurrency type in combination with the ResultSet type



supportsResultSetHoldability(int holdability)

Function: Retrieves whether this database supports the given result set holdability.

supportsResultSetType(int type)

Function: Determines if the database supports the given ResultSet type.

supportsSchemasInDataManipulation()

Function: Determines if a schema name can be used in a data manipulation statement.

supportsSchemasInIndexDefinitions()

Function: Determines if a schema name can be used in an index definition statement.


Syntax public boolean supportsResultSetHoldability(int holdability) throws SQLException

where the parameter holdability is 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.


Syntax public boolean supportsResultSetType(int type) throws SQLException


Return True, if the database supports the ResultSet type

False, if the database does not support the ResultSet type


Syntax public boolean supportsSchemasInDataManipulation() throws SQLException

Return 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


Syntax public boolean supportsSchemasInIndexDefinitions() throws SQLException



supportsSchemasInPrivilegeDefinitions()

Function: Determines if a schema name can be used in a privilege definition statement.

supportsSchemasInProcedureCalls()

Function: Determines if a schema name can be used in a procedure call statement.

supportsSchemasInTableDefinitions()

Function: Determines if a schema name can be used in a table definition statement.

supportsSelectForUpdate()

Function: Determines if the SELECT for UPDATE function is supported.

Return True, if a schema name can be used in an index definition statement

False, if a schema name cannot be used in an index definition statement


Syntax public boolean supportsSchemasInPrivilegeDefinitions() throws SQLException

Return 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


Syntax public boolean supportsSchemasInProcedureCalls() throws SQLException

Result True, if a schema name can be used in a procedure call

False, if a schema name cannot be used in a procedure call


Syntax public boolean supportsSchemasInTableDefinitions() throws SQLException

Return 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


Syntax public boolean supportsSelectForUpdate() throws SQLException




supportsStoredProcedures()

Function: Determines if stored procedure calls using the stored procedure escape syntax are supported.

supportsSubqueriesInComparisons()

Function: Determines if subqueries in comparison expressions are supported.

supportsSubqueriesInExists()

Function: Determines if subqueries in exists expressions are supported.

supportsSubqueriesInIns()

Function: Determines if subqueries in in statements are supported.

Return True, if the function is supported

False, if the function is not supported


Syntax public boolean supportsStoredProcedures() throws SQLException

Return 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


Syntax public boolean supportsSubqueriesInComparisons() throws SQLException

Return True, if subqueries in comparison expressions are supported



Syntax public boolean supportsSubqueriesInExists() throws SQLException

Return True, if subqueries in exists expressions are supported





supportsSubqueriesInQuantifieds()

Function: Determines if subqueries in quantified expressions are supported.

supportsTableCorrelationNames()

Function: Determines if table correlation names are supported.

supportsTransactionIsolationLevel(int level)

Function: Determines if the database supports the given transaction isolation level.


Syntax public boolean supportsSubqueriesInIns() throws SQLException

Return True, if subqueries in in statements are supported



Syntax public boolean supportsSubqueriesInQuantifieds() throws SQLException

Return True, if subqueries in quantified expressions are supported



Syntax public boolean supportsTableCorrelationNames() throws SQLException

Return True, if table correlation names are supported

False, if table correlation names are not supported



Syntax public boolean supportsTransactionIsolationLevel(int level) throws SQLException

where the level parameter is the value defined in the java.sql.Connection method

Return True, if the database supports the transaction level

False, if the database does not support the transaction level



supportsTransactions()

Function: Determines if transactions are supported.

supportsUnion()

Function: Determines if SQL UNION is supported.

supportsUnionAll()

Function: Determines if SQL UNION ALL is supported.

updatesAreDetected(int type)

Function: Determines if a visible row update can be detected by calling the method ResultSet.rowUpdated.


Syntax public boolean supportsTransactions() throws SQLException

Return True, if the database supports the transaction level

False, if the database does not support the transaction level


Syntax public boolean supportsUnion() throws SQLException

Return True, if SQL UNION is supported

False, if SQL UNION is not supported


Syntax public boolean supportsUnionAll() throws SQLException

Return True, if SQL UNION ALL is supported

False, if SQL UNION ALL is not supported


Syntax public boolean updatesAreDetected(int type) throws SQLException


Return True, if changes are detected by the ResultSet type

False, if changes are not detected by the ResultSet type

Note: Returns False, because updatable ResultSets are not supported.


Chapter 3: JDBC MethodsDataSource Methods

usesLocalFilePerTable()

Function: Determines if the database uses a local file for each table.

usesLocalFiles()

Function: Determines if the database stores tables in a local file.

DataSource Methods

Description

A DataSource object is a factory for Connection objects. An object that implements the DataSource interface is typically registered with a JNDI service provider. A JDBC driver that is accessed using the DataSource API does not automatically register itself with the DriverManager.

Methods

getConnection()

Function: Attempts to establish a database connection. The DriverManager attempts to connect to a database.

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 boolean usesLocalFilePerTable() throws SQLException

Return True, if the database uses a local file for each table

False, if the database does not use a local file for each table


Syntax public boolean usesLocalFiles() throws SQLException

Return True, if the database stores tables in a local file

False, if the database does not store tables in a local file



Return A connection to a database data source is returned.


Chapter 3: JDBC MethodsDataSource Methods

getLoginTimeout()

Function: Gets the maximum time in seconds that this data source can wait while attempting to connect to a database.

getLogWriter()

Function: Gets the log writer for this data source.


Function: Sets the maximum time in seconds that this data source will wait while attempting to connect to a database.


Syntax public Connection getConnection(String username, String password) throws SQLException




Return A connection to the database data source is returned.


Syntax public int getLoginTimeout() throws SQLException

Return DataSource login timeout value is returned.

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: DataSource Method setLoginTimeout(int seconds).


Syntax public PrintWriter getLogWriter() throws SQLException

Return The log writer for this data source is returned; 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: DataSource Method setLogWriter(PrintWriter out).


Chapter 3: JDBC MethodsDriverManager Methods

setLogWriter(PrintWriter out)

Function: Sets the log writer for this data source.

DriverManager Methods

Description

The DriverManager provides a basic service for managing a set of JDBC drivers.

As part of its initialization, the DriverManager class attempts 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 the ~/.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 attempts to locate a suitable driver from among those loaded at initialization and those loaded explicitly using the same classloader as the current applet or application.


Syntax public void setLoginTimeout(int seconds) throws SQLException

where the seconds parameter is the data source login time limit.

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: DataSourceMethod getLoginTimeout().


Syntax public void setLogWriter(PrintWriter out) throws SQLException

where the out parameter is the new log writer; to disable logging, set to null.

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: DataSource Method getLogWriter().



Methods

The following subsections provide a brief description of each supported DriverManager method.

deregisterDriver(Driver driver)

Function: Drops a driver from the DriverManager list.

Applets can only deregister drivers from their own classloader.

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.

getConnection(String url, Properties info)




Syntax public static void deregisterDriver(Driver driver) throws SQLException

where the driver parameter is the JDBC driver to drop.


Syntax public static Connection getConnection(String url) throws SQLException

where the url parameter is a database URL of the form:

jdbc:subprotocol:subname

Return A connection to the URL is returned.


Syntax public static Connection getConnection(String url, Properties info) throws SQLException


• url is a database URL of the form:


• info is a list connection argument string tag/value pairs. At a minimum, the user and password properties should be included.

Return A connection to the URL is returned.



getConnection(String url, String user, String password)



getDriver(String url)

Function: Attempts to locate a driver that understands the given URL.


getDrivers()

Function: Returns an enumeration with all of the currently loaded JDBC drivers that the current caller has access.


Syntax public static Connection getConnection(String url, String user, String password) throws SQLException


• url is a database URL of the form:


• user is the database user on whose behalf the connection is being made

• password is the password for the user

Return The password for the user is returned.


Syntax public static Driver getDriver(String url) throws SQLException

where the url parameter is a database URL of the form:


Return A driver object representing a driver that can connect to the URL is returned.


Syntax public static Enumeration getDrivers()

Return The list of JDBC drivers loaded by the caller’s class loader is returned.

Note: The classname of a driver can be found using:

d.getClass().getName()



getLoginTimeout()

Function: Finds the maximum time that a driver can wait to login to the database.

getLogStream()

Function: [DEPRECATED] Gets the logging/tracing PrintStream that is used by the DriverManager and all drivers.

printIn(String message)

Function: Prints a message to the current JDBC log stream.

registerDriver(Driver driver)

Function: A newly loaded driver class calls registerDriver to make itself known to the DriverManager.


Function: Sets the maximum time that a driver will wait to connect to the database.


Syntax public static int getLoginTimeout()

Return The driver login time limit in seconds is returned.


Syntax public static PrintStream getLogStream()

Return The logging/tracing PrintStream is returned.

If disabled, null is returned.


Syntax public static void println(String message)

where the message parameter is a log or tracing message.


Syntax public static void registerDriver(Driver driver) throws SQLException

where the driver parameter is the new JDBC driver registered with the DriverManager.


Chapter 3: JDBC MethodsParameterMetaData Methods

setLogStream(PrintStream out)

Function: Sets the logging/tracing PrintStream that is used by the DriverManager and all drivers.

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: Retrieves the number of parameters in the PreparedStatement object for which this ParameterMetaData object contains information.

isNullable(int param)

Function: Retrieves whether null values are allowed in the designated parameter.


Syntax public static void setLoginTimeout(int seconds)

where the seconds parameter is the time allowed to wait in seconds.


Syntax public static void setLogStream(PrintStream out) throws SecurityException

where the out parameter is the new logging/tracing PrintStream. To disable, set to null.

Note: 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.


Syntax public int getParameterCount() throws SQLException

Return The number of parameters is returned.



isSigned(int param)

Function: Retrieves whether values for the designated parameter can be signed numbers.

getPrecision(int param)

Function: Retrieves the designated parameter’s number of decimal digits.

getScale(int param)

Function: Retrieves the designated parameter’s number of digits to the right of the decimal point.


Syntax public int isNullable(int param) throws SQLException

where the param parameter is the parameter to check–the first parameter is 1, the second parameter is 2, and so on.

Return The nullability status of the given parameter is returned; one of:

ParameterMetaData.parameterNoNullsParameterMetaData.parameterNullableParameterMetaData.parameterNullableUnknown.


Syntax public boolean isSigned(int param) throws SQLException


Return True, if so; False, otherwise


Syntax public int getPrecision(int param) throws SQLException


Return precision.Zero is returned if precision is not applicable to the parameter


Syntax public int getScale(int param) throws SQLException

where the param parameter is the parameter is check–the first parameter is 1, the second parameter is 2, and so on.

Return scale.Zero is returned if scale is not applicable to the parameter.



getParameterType(int param)

Function: Retrieves the designated parameter’s SQL type.

getParameterTypeName(int param)

Function: Retrieves the designated parameter’s database-specific type name.

getParameterClassName(int param)

Function: Retrieves the fully qualified name of the Java class whose instances should be passed to the method PreparedStatement.setObject.

getParameterMode(int param)

Function: Retrieves the designated parameter’s mode.


Syntax public int getParameterType(int param) throws SQLException

where the param parameter is the parameter to check–the first parameter is 1, the second parameter is 2, and so on

Return SQL type from java.sql.Types. java.sql.Types.NULL will be returned if the parameter type cannot be determined.


Syntax public String getParameterTypeName(int param) throws SQLException


Return type, the name used by the databaseIf the parameter type is a user-defined type, then a fully qualified type name is returned.

null is returned if the parameter typeName cannot be determined.


Syntax public String getParameterClassName(int param) throws SQLException

where the param parameter is the parameter to check–the first parameter is 1, the second is 2, and so on.

Return 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 is returned. This is the class name used for custom mapping.

null is returned if the Class name cannot be determined.


Chapter 3: JDBC MethodsPooledConnection 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.

close()

Function: Close the physical connection

getConnection()

Function: Create an object handle for the physical connection. The object returned is a temporary handle used by application code to refer to a physical connection that is being pooled.


Syntax public int getParameterMode(int param) throws SQLException

where the param parameter is the parameter to check–the first parameter is 1, the second is 2, and so on.

Return Mode of the parameter is returned; one of:

ParameterMetaData.parameterModeInParameterMetaData.parameterModeInOutParameterMetaData.parameterModeUnknown


Syntax public void addConnectionEventListener(ConnectionEventListener listener)

where the listener parameter is the object added as a listener to the event.




Chapter 3: JDBC MethodsPreparedStatement Methods

removeConnectionEventListener(ConnectionEventListener listener)

Function: Remove an event listener

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.

addBatch()

Function: This method adds a set of parameters to the PreparedStatement object’s batch of commands.

clearParameters()

Function: Clears the current parameter values immediately



Return A Connection object, a handle to the pooled connection object is returned.


Syntax public void removeConnectionEventListener(ConnectionEventListener listener)

where the listener parameter is the object removed from being a listener to the event.


Syntax public void addBatch() throws SQLException

Note: It is recommended to use this method with auto-commit disabled.



execute()

Function: Executes any kind of SQL statement

executeQuery()

Function: Executes the SQL query in the PreparedStatement object

executeUpdate()

Function: Executes the SQL INSERT, UPDATE, or DELETE statement in this PreparedStatement object.


Syntax public void clearParameters() throws SQLException

Note: 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.


Syntax public boolean execute() throws SQLException

Note: Some prepared statements return multiple results. The execute method handles these complex statements as well as the simple form of statement handled by the executeQuery and executeUpdate methods.


Syntax public ResultSet executeQuery() throws SQLException

Return The ResultSet that contains the date produced by the query is returned. 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()”.


Syntax public int executeUpdate() throws SQLException



getMetaData()

Function: Retrieves the number, types, and properties of a ResultSet object’s columns

getParameterMetaData()

Function: Retrieves the number, types, and properties of this PreparedStatement object’s parameters.

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

Return 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()”.


Syntax public ResultSetMetaData getMetaData() throws SQLException

Return The description of a ResultSet’s columns is returned.


Syntax public ParameterMetaData getParameterMetaData() throws SQLException

Return A ParameterMetaData object is returned. An exception is thrown if ParameterMetaData is not available.




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.

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 setAsciiStream(int parameterIndex, InputStream x, int length) throws SQLException


• parameterIndex is the parameter specification. The first parameter is 1, the second parameter is 2, and so on

• x is the Java input stream that contains the ASCII parameter value

• length is the number of bytes in the stream

Note: When a very large ASCII value is input to a LONGVARCHAR parameter, it may be more practical to send it using 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.


Syntax public void setBigDecimal(int parameterIndex, BigDecimal x) throws SQLException



• x is the parameter value


Syntax public void setBinaryStream(int parameterIndex, InputStream x, int length) throws SQLException



• x is the Java input stream that contains the binary parameter value

• length is the number of bytes in the stream



setBlob(int i, Blob x)

Function: Sets the parameter number to a Blob object

setBoolean(int parameterIndex, boolean x)

Function: Sets the designated parameter to a Java boolean value. The driver converts this to an SQL BIT value and sends it to the database.

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.

Note: When a very large binary value is input to a LONGVARBINARY parameter, it may be more practical to send it using a java.io.InputStream.

JDBC will read the data from the stream as needed, until it reaches end-of-file.



Syntax public void setBlob(int i, Blob x) throws SQLException


• i is the parameter specification; the first parameter is 1, the second parameter is 2, and so on

• x is a BLOB object that maps an SQL BLOB value


public void setBoolean(int parameterIndex, boolean x) throws SQLException


• parameterIndex is the parameter specification; the first parameter is 1, the second parameter is 2, and so on



Syntax public void setByte(int parameterIndex, byte x) throws SQLException







setBytes(int parameterIndex, byte[ ] x)

Function: 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.

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

setClob(int i, Clob x)

Function: Sets the parameter number in a CLOB object


Syntax public void setBytes(int parameterIndex, byte[] x) throws SQLException





Syntax public void setCharacterStream(int parameterIndex, Reader reader, int length) throws SQLException



• reader is the java reader that contains the UNICODE data

• length is the number of characters in the stream

Note: When a very large UNICODE value is input to a LONGVARCHAR parameter, it may be more practical to send it using 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.



Syntax public void setClob(int i, Clob x) throws SQL exception


• i is the parameter specification; the first parameter is 1, the second parameter is 2, and so on

• x is a CLOB object that maps an SQL CLOB value



setDate(int parameterIndex, Date x)

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.

setDate(int parameterIndex, Date x, Calendar cal)

Function: Sets the designated parameter to a java.sql.Date value, using the given Calendar object

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 setDate(int parameterIndex, Date x) throws SQLException





Syntax public void setDate(int parameterIndex, Date x, Calendar cal) throws SQLException





Note: 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.


Syntax public void setDouble(int parameterIndex, double x) throws SQLException






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.

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.

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.

setNull(int parameterIndex, int sqlType)

Function: Sets the designated parameter to SQL NULL.


Syntax public void setFloat(int parameterIndex, float x) throws SQLException





Syntax public void setInt(int parameterIndex, int x) throws SQLException





Syntax public void setLong(int parameterIndex, long x) throws SQLException






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:

• STRUCT

• DISTINCT

• JAVA_OBJECT

• named array types


Syntax public void setNull(int parameterIndex, int sqlType) throws SQLException



• sqlType is the SQL type code defined in java.sql.Types

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.


Syntax public void setNull(int paramIndex, int sqlType, String typeName) throws SQLException



• sqlType is the SQL type code defined in java.sql.Types

• typeName is the fully qualified name of an SQL user-named type, ignored if the parameter is not a user-named type or REF

Note: To be portable, applications must give the SQL type code and the fully qualified SQL 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.

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.



setObject(int parameterIndex, Object x)

Function: Sets the value of a parameter using an object. Use the java.lang equivalent objects for integral values.

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.

setObject(int parameterIndex, Object x, int targetSqlType, int 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) throws SQLException



• x is the object containing the input parameter value

Note: 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.


Syntax public void setObject(int parameterIndex, Object x, int targetSqlType) throws SQLException




• targetSqlType is the SQL type (as defined in java.sql.Types) to be sent to the database



setShort(int parameterIndex, short x)

Function: Sets the designated parameter to a Java short value.

setString(int parameterIndex, String x)

Function: Sets the designated parameter in 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 setObject(int parameterIndex, Object x, int targetSqlType, int scale) throws SQLException




• targetSqlType is the SQL type (as defined in java.sql.Types) to be sent to the database. The scale argument may further qualify this type.

• scale is the number of digits after the decimal point–for java.sql.Types.DECIMAL or java.sql.Types.NUMERIC types. For all other types, this value is 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.


Syntax public void setShort(int parameterIndex, short x) throws SQLException






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.

setTime(int parameterIndex, Time x, Calendar cal)

Function: Sets the designated parameter to a java.sql.Time value, using the given Calendar object.

setTimestamp(int parameterIndex, Timestamp x)

Function: Sets the designated parameter to a java.sql.Timestamp value


Syntax public void setString(int parameterIndex, String x) throws SQLException





Syntax public void setTime(int parameterIndex, Time x) throws SQLException





Syntax public void setTime(int parameterIndex, Time x, Calendar cal) throws SQLException




• cal is the Calendar object the driver will use to construct the time

Note: 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.




The driver converts this to an SQL TIMESTAMP value when it sends it to the database.

setTimestamp(int parameterIndex, Timestamp x, Calendar cal)

Function: Sets the designated parameter to a java.sql.Timestamp value, using the given Calendar object.

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 setTimestamp(int parameterIndex, Timestamp x) throws SQLException





Syntax public void setTimestamp(int parameterIndex, Timestamp x, Calendar cal) throws SQLException




• cal is the Calendar object the driver will use to construct the time

Note: The driver uses the Calendar object to construct an SQL TIMESTAMP, which the driver then sends to the database.

With a Calendar object, the driver can calculate the timestamp taking into account a custom timezone and locale.



Syntax public void setUnicodeStream(int parameterIndex, InputStream x, int length) throws SQLException



• x is the java input stream containing the UNICODE parameter value

• length is the bytes in the input stream


Chapter 3: JDBC MethodsResultSet Methods

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 JDBC Driver 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.

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 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.

absolute(int row)

Function: The cursor is moved to the row number in the ResultSet object.



afterLast()

Function: The cursor is moved to just after the last row of the ResultSet object.

beforeFirst()

Function: The cursor is moved to just before the first row of the ResultSet object.

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.


Syntax public int absolute(int row) throws SQLException

where the row parameter 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.

Result True, if the cursor is located on the ResultSet

False, if it is not

Note: Throws the SQLException if a database access error occurs, or if the ResultSetType is TYPE_FORWARD_ONLY.

A call absolute(1) is the same as calling first()

A call absolute(-1) is the same as calling last()


Syntax public void afterLast() throws SQLException

Note: If the ResultSet contains no rows, this method has no effect.

Throws the SQLException if a database access error occurs, or if the ResultSetType is TYPE_FORWARD_ONLY.


Syntax public void beforeFirst() throws SQLException

Note: If the ResultSet contains no rows, this method has no effect.

Throws the SQLException if a database access error occurs, or if the ResultSetType is TYPE_FORWARD_ONLY.



clearWarnings()

Function: Clears all warnings reported on this ResultSet object. After this call, getWarnings returns null until a new warning is reported for this ResultSet.

close()

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.

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.

findColumn(String columnName)

Function: Maps a Resultset column name to a ResultSet column index.

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.





Note: A ResultSet is automatically closed by the statement that generated it when that statement is closed, re-executed, or used to retrieve the next result from a sequence of multiple results. A ResultSet is also automatically closed when it is garbage collected.


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



first()

Function: Moves the cursor to the ResultSet object first row.

getAsciiStream(int columnIndex)

Function: 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.

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 int findColumn(String columnName) throws SQLException

where the columnName parameter is the name of the column

Return The column index of columnName is returned.


Syntax public boolean first() throws SQLException

Return True, if the location of the cursor is a valid row

False, if there are no rows in the ResultSet

Note: Throws the SQLException if a database access error occurs, or if the ResultSetType is TYPE_FORWARD_ONLY.


Syntax public InputStream getAsciiStream(int columnIndex) throws SQLException

where the columnIndex parameter is the column specification. The first column is 1, the second column is 2, and so on

Return 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.



getBigDecimal(int columnIndex)

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.

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 InputStream getAsciiStream(String columnName) throws SQLException

where the columnName parameter is the SQL name of the column

Return 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.


Also, a stream may return 0 when the method available is called whether there is data available or not.


Syntax public BigDecimal getBigDecimal(int columnIndex) throws SQLException


Return The column value is returned.

Note: If the value is sQL NULL, the result is NULL.

Note: If the value is sQL NULL, the result is NULL.


Syntax public BigDecimal getBigDecimal(int columnIndex, int scale) throws SQLException


• columnIndex is the column specification; the first column is 1, the second column is 2, and so on


Return 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.

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.

getBinaryStream(int columnIndex)

Function: 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.


Syntax public BigDecimal getBigDecimal(String columnName) throws SQLException



Note: If the value is SQL NULL, the result is NULL.


Syntax public BigDecimal getBigDecimal(String columnName, int scale) throws SQLException


• columnName is the SQL name of the column



Note: If the value is SQL NULL, the result is NULL.


Syntax public InputStream getBinaryStream(int columnIndex) throws SQLException


Return A Java input stream that delivers the database column value as a stream of uninterpreted bytes is returned.

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.

getBlob(int i)

Function: Returns the value of the designated column in the current row of this ResultSet object as a Blob object in the Java programming language.

getBlob(String colName)

Function: Returns the value of the designated column in the current row of this ResultSet object as a Blob object in the Java programming language.


Syntax public InputStream getBinaryStream(String columnName) throws SQLException


Return A Java input stream that delivers the database column value as a stream of uninterpreted bytes is returned. If the value is SQL NULL, then the result is null.

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.


Syntax public Blob getBlob(int i) throws SQLException

where the i parameter is the column specification. The first column is 1, the second column is 2, and so on

Return Returns a Blob object representing the SQL BLOB value in the specified column.


Syntax public Blob getBlob(String colName) throws SQLException

where the colName parameter is the name of the column from which to retrieve the value

Return Returns a Blob object representing the SQL BLOB value in the specified column.



getBoolean(int columnIndex)

Function: Gets the value of a column designated by columnIndex in the current row of the ResultSet as a Java boolean.

getBoolean(String columnName)

Function: Gets the value of a column designated by columnName in the current row of the ResultSet as a Java boolean.

getByte(int columnIndex)

Function: Gets the value of a column designated by columnIndex in the current row as a Java byte.

getByte(String columnName)

Function: Gets the value of a column designated by columnName in the current row as a Java byte.


Syntax public boolean getBoolean(int columnIndex) throws SQLException


Return The value of the designated column is returned.

Note: If the value is SQL NULL, the result is false.


Syntax public boolean getBoolean(String columnName) throws SQLException



Note: If the value is SQL NULL, the result is false.


Syntax public byte getByte(int columnIndex) throws SQLException



Note: If the value is SQL NULL, the result is 0.



getBytes(int columnIndex)

Function: Gets the value of a column designated by columnIndex in the current row as a Java byte array.

getBytes(String columnName)

Function: Gets the value of a column designated by columnName in the current row as a Java byte array.

getCharacterStream(int columnIndex)

Function: Gets the value of a column designated by columnIndex in the current row as a java.io.Reader.


Syntax public byte getByte(String columnName) throws SQLException



Note: If the value is SQL NULL, the result is 0.


Syntax public byte[] getBytes(int columnIndex) throws SQLException



Note: If the value is SQL NULL, the result is null.


Syntax public byte[] getBytes(String columnName) throws SQLException



Note: If the value 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.

getClob(int i)

Function: Returns the value of the designated column in the current row of this ResultSet object as a Clob object in the Java programming language.

getClob(String colName)

Function: Returns the value of the designated column in the current row of this ResultSet object as a Clob object in the Java programming language.


Syntax public Reader getCharacterStream(int columnIndex) throws SQLException


Return The value in the specified column as a java.io.Reader is returned.

Note: If the column value returned is SQL NULL, the result is null.


Syntax public Reader getCharacterStream(String columnName) throws SQLException


Return The value in the specified column as a java.io.Reader is returned.



Syntax public Clob getClob(int i) throws SQLException

where the i parameter is the column specification. The first column is 1, the second column is 2, and so on

Return Returns a Clob object representing the SQL CLOB value in the specified column.


Syntax public Blob getClob(String colName) throws SQLException

where the colName parameter is the name of the column from which to retrieve the value



getConcurrency()

Function: Retrieves the concurrency mode of this ResultSet object. The concurrency used is determined by the Statement object that created the result set.

getDate(String columnIndex)

Function: Gets the value of the column designated by columnIndex in the current row of the ResultSet object as a java.sql.Date object.

getDate(String columnName)

Function: Gets the value of the column designated by columnName in the current row of the ResultSet object as a java.sql.Date object.

Return Returns a Clob object representing the SQL CLOB value in the specified column.


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.

Characteristic Return

Syntax public Date getDate(String columnIndex) throws SQLException





Syntax public Date getDate(String columnName) throws SQLException







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.

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.

getDouble(int columnIndex)

Function: Gets the value of a column designated by columnIndex in the current row as a Java double.


Syntax public Date getDate(String columnIndex, Calendar cal) throws SQLException


• columnIndex is the column specification. The first column is 1, the second column is 2, and so on

• cal is the calendar to use in constructing the date



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.


Syntax public Date getDate(String columnName, Calendar cal) throws SQLException


• columnName is the SQL name of the column from which to retrieve the value

• cal is the calendar to use in constructing the date

Return The column value as a java.sql.Date.object is returned.


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.



getDouble(String columnName)

Function: Gets the value of the column designated by columnName in the current row of this ResultSet as a Java double.

getFloat(int columnIndex)

Function: Gets the value of a column designated by columnIndex in the current row of this ResultSet object as a Java float.

getFetchDirection()

Function: Gets the fetch direction of the current ResultSet.


Syntax public double getDouble(int columnIndex) throws SQLException



Note: If the column value returned is SQL NULL, the result is 0.


Syntax public double getDouble(String columnName) throws SQLException





Syntax public float getFloat(int columnIndex) throws SQLException





Syntax public float getFetchDirection() throws SQLException

Return The current fetch direction for the ResultSet is returned.



getFetchSize()

Function: Gets the fetch size of the current ResultSet.

getFloat(String columnName)

Function: Gets the value of a column designated by columnName in the current row of this ResultSet

as a Java float.

getInt(int columnIndex)

Function: Gets the value of the column designated by columnIndex in the current row of this ResultSet

as a Java int.

getInt(String columnName)

Function: Gets the value of a column designated by columnName in the current row of this ResultSet as a Java int.


Syntax public int getFetchSize() throws SQLException

Return The current fetch size for the ResultSet is returned.


Syntax public float getFloat(String columnName) throws SQLException





Syntax public int getInt(int columnIndex) throws SQLException





Syntax public int getInt(String columnName) throws SQLException





getLong(int columnIndex)

Function: Gets the value of a column designated by columnIndex in the current row of this ResultSet

as a Java long.

getLong(String columnName)

Function: Gets the value of a column designated by columnName in the current row of this ResultSet

as a Java long.

getMetaData()

Function: Provides the number, types, and properties of columns in a ResultSet.

getObject(int columnIndex)

Function: Gets the value of the column designated by columnIndex in the current row of this ResultSet as a Java object.



Syntax public long getLong(int columnIndex) throws SQLException





Syntax public long getLong(String columnName) throws SQLException





Syntax public ResultSetMetaData getMetaData() throws SQLException

Return The description of ResultSet object’s columns is returned.




getObject(String columnName)

Function: Gets the value of the column designated by columnName in the current row of this ResultSet as a Java object.

getRow()

Function: Returns the current row number.


Syntax public Object getObject(String columnIndex) throws SQLException


Return A java.lang.Object holding the column value is returned.

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 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())


Syntax public Object getObject(String columnName) throws SQLException


Return A java.lang.Object holding the column value is returned.

Note: A java.lang.Object holding the column value is returned.

You can also use this method to read database-specific abstract data types.

When the 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())


Syntax public int getRow() throws SQLException

Return If there is a current row, returns the row number. The first row number is 1.

If there is no current row, returns 0.




getShort(int columnIndex)

Function: Gets the value of a column designated by columnIndex in the current row of this ResultSet as a Java short.

getShort(String columnName)

Function: Gets the value of a column columnName in the current row of this ResultSet as a Java short.

getStatement()

Function: Returns the Statement that produced this ResultSet object.

getString(int columnIndex)

Function: Gets the value of a column designated by columnIndex in the current row of the ResultSet as a Java String.


Syntax public short getShort(int columnIndex) throws SQLException





Syntax public short getShort(String columnName) throws SQLException





Syntax public Statement getStatement() throws SQLException

Return The Statement that produced the ResultSet or null if the ResultSet was produced some other way is returned.

Note: If the ResultSet was generated some other way, such as by a DatabaseMetaData method, this method returns null.



getString(String columnName)

Function: Gets the value of a column designated by columnName in the current row of this ResultSet as a Java String.

getTime(int columnIndex)

Function: Gets the value of the column designated by columnIndex in the current row of this ResultSet as a java.sql.Time object.

getTime(String columnName)

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 String getString(int columnIndex) throws SQLException

where the columnIndex parameter is the column specification. The first column is 1, the second is 2, and so on




Syntax public String getString(String columnName) throws SQLException





Syntax public Time getTime(int columnIndex) throws SQLException





Syntax public Time getTime(String columnName) throws SQLException




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.

getTime(String columnName, Calendar cal)

Function: Gets the value of the column designated by columnName in the current row of this ResultSet as a jva.sql.Time object.




Syntax public Time getTime(int columnIndex, Calendar cal) throws SQLException



• cal is the calendar to use in constructing the time.

Return The value of the designated column as a java.sql.Time object is returned.


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 and 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.


Syntax public Time getTime(String columnName, Calendar cal) throws SQLException



• cal is the calendar to use in constructing the time.

Return The value of the designated column as a java.sql.Time object is returned.




getTimestamp(int columnIndex)


ResultSet as a java.sql.Timestamp object.

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.

getTimestamp(int columnIndex, Calendar cal)


ResultSet as a java.sql.Timestamp object.


This method uses the given calendar to construct an appropriate millisecond value for the Time if the underlying database does not store timezone.





Syntax public Timestamp getTimestamp(int columnIndex) throws SQLException





Syntax public Timestamp getTimestamp(String columnName) throws SQLException







getTimestamp(String columnName, Calendar cal)

Function: Gets the value of a column in the current row as a java.sql.Timestamp object.

getType()

Function: Returns the ResultSet object type. The Statement object that created the ResultSet determines the ResultSet type.


Syntax public Timestamp getTimestamp(int columnIndex, Calendar cal) throws SQLException



• cal is the calendar to use in constructing the timestamp

Return The value of the designated column as a java.sql.TimeStamp object is returned.


This method uses the given calendar to construct an appropriate millisecond value for the Timestamp if the underlying database does not store timezone information.





Syntax public Timestamp getTimestamp(String columnName, Calendar cal) throws SQLException



• cal is the calendar to use in constructing the timestamp

Return The value of the designated column as a java.sql.TimeStamp object is returned.


This method uses the given calendar to construct an appropriate millisecond value for the Timestamp if the underlying database does not store timezone information.






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).

getUnicodeStream(String columnName)

Function: [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.


Syntax public int getType() throws SQLException

Return ResultSet.TYPE_FORWARD_ONLY

ResultSet.TYPE_SCROLL_INSENSITIVE, or

ResultSet.TYPE_SCROLL_SENSITIVE



Syntax public InputStream getUnicodeStream(int columnIndex) throws SQLException


Return A Java input stream that delivers the database column value as a stream of two-byte Unicode characters is returned.


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.


Also, a stream may return 0 when the method available is called, whether there is data available or not.



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.

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.


Syntax public InputStream getUnicodeStream(String columnName) throws SQLException

where columnName is the SQL name of the column

Return A Java input stream that delivers the database column value as a stream of two-byte Unicode characters is returned.


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.


Also, a stream may return 0 when the method available is called, whether there is data available or not.



Return The first SQLWarning or null is returned.

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.


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: Determines whether the cursor in the ResultSet Object is located after the last row and

returns the result.

isBeforeFirst()

Function: Determines whether the cursor in the ResultSet Object is located before the first row and

returns the result.

isFirst()

Function: Determines whether the cursor in the ResultSet Object is located on the first row and

returns the result.

isLast()

Function: Determines whether the cursor in the ResultSet Object is located on the last row and returns

the result.


Syntax public boolean isAfterLast() throws SQLException

Return 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



Syntax public boolean isBeforeFirst() throws SQLException

Return 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



Syntax public boolean isFirst() throws SQLException

Return 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




last()

Function: Repositions the cursor to the last row.

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.

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.


Syntax public boolean isLast() throws SQLException

Return 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


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.


Syntax public boolean last() throws SQLException

Return 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

Note: Throws the SQLException if a database access error occurs, or if the ResultSet type is TYPE_FORWARD_ONLY.


Syntax public void moveToCurrentRow() throws SQLException

Note: Throws the SQLException if a database access error occurs or the result set is not updatable.



next()

Function: Repositions the cursor down one row from its current position.

previous()

Function: Repositions the cursor to the previous row in the ResultSet object.

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.


Syntax public void moveToInsertRow() throws SQLException

Note: Throws the SQLException if a database access error occurs or the result set is not updatable.


Syntax public boolean next() throws SQLException

Result 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.


Syntax public boolean previous() throws SQLException

Return True, if the row where the cursor is repositioned is valid

False, if the cursor is repositioned off the ResultSet

Note: Throws the SQLException if a database access error occurs, or if the ResultSet type is TYPE_FORWARD_ONLY.



relative(int rows)

Function: Repositions the cursor within the ResultSet a relative number of rows forward or backward from the current position.

rowDeleted()

Function: Detects and indicates if a row was deleted.

rowInserted()

Function: Detects and indicates if insertions were made into the current row.


Syntax public void refreshRow() throws SQLException



Syntax public boolean relative(int rows) throws SQLException

where the rows parameter is an integer that specifies the number of rows to move from the current position. To move forward, specify a positive number. Although 0 is valid, the cursor position will not change.

Return True, if the row where the cursor is repositioned is valid

False, if otherwise

Note: Throws the SQLException if a database access error occurs, if there is no current row, or if the ResultSet type is TYPE_FORWARD_ONLY.


Syntax public boolean rowDeleted() throws SQLException

Return 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.


Syntax public boolean rowInserted() throws SQLException



rowUpdated()

Function: Detects and indicates if updates were made to the current row.

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.

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

Return 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.


Syntax public boolean rowUpdated() throws SQLException

Return 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.


Syntax public void updateAsciiStream(int columnIndex, InputStream x, int length) throws SQLException


• 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





do not update the underlying database; instead the updateRow or insertRow methods are called to update the database.

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.

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.


Syntax public void updateAsciiStream(String columnName, InputStream x, int length) throws SQLException


• columnName is the name of the column





Syntax public void updateBigDecimal(int columnIndex, BigDecimal x) throws SQLException






Syntax public void updateBigDecimal(String columnName, BigDecimal x) throws SQLException







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.

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.

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.


Syntax public void updateBinaryStream(int columnIndex, InputStream x, int length) throws SQLException







Syntax public void updateBinaryStream(String columnName, InputStream x, int length) throws SQLException








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.

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.


Syntax public void updateBlob(int columnIndex, Blob x) throws SQLException






Syntax public void updateBlob(String columnName, Blob x) throws SQLException






Syntax public void updateByte(int columnIndex, byte x) throws SQLException







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.

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.

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.


Syntax public void updateByte(String columnName, byte x) throws SQLException






Syntax public void updateBytes(int columnIndex, byte[] x) throws SQLException







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.

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.


Syntax public void updateBytes(String columnName, byte[] x) throws SQLException






Syntax public void updateCharacterStream(int columnIndex, Reader x, int length) throws SQLException







Syntax public void updateCharacterStream(String columnName, Reader x, int length) throws SQLException








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.

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.

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.


Syntax public void updateClob(int columnIndex, Clob x) throws SQLException






Syntax public void updateClob(String columnName, Clob x) throws SQLException







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.

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.


Syntax public void updateDate(int columnIndex, Date x) throws SQLException






Syntax public void updateDate(String columnName, Date x) throws SQLException






Syntax public void updateDouble(int columnIndex, double x) throws SQLException







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.

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.

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.


Syntax public void updateDouble(String columnName, double x) throws SQLException






Syntax public void updateFloat(int columnIndex, float x) throws SQLException







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.

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.


Syntax public void updateFloat(String columnName, float x) throws SQLException






Syntax public void updateInt(int columnIndex, int x)throws SQLException






Syntax public void updateInt(String columnName, int x) throws SQLException







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.

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.

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.


Syntax public void updateLong(int columnIndex, long x) throws SQLException






Syntax public void updateLong(String columnName, long x) throws SQLException






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



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.

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.

updateObject(int columnIndex, Object x, int scale)




Syntax public void updateNull(String columnName)throws SQLException

where the parameter columnName is the name of the column



Syntax public void updateObject(int columnIndex, Object x)throws SQLException








updateObject(String columnName, Object x)


updateObject(String columnName, Object x, int scale)



Syntax public void updateObject(int columnIndex, Object x, int scale)throws SQLException




• 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.



Syntax public void updateObject(String columnName, Object x)throws SQLException






Syntax public void updateObject(String columnName, Object x, int scale) throws SQLException




• 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.



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.

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.

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.



Syntax public void updateRow()throws SQLException



Syntax public void updateShort(int columnIndex, short x)throws SQLException






Syntax public void updateShort(String columnName, short x)throws SQLException







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.

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.

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.



Syntax public void updateString(int columnIndex, String x)throws SQLException






Syntax public void updateString(String columnName, String x)throws SQLException








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.

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.


Syntax public void updateTime(int columnIndex, Time x)throws SQLException






Syntax public void updateTime(String columnName, Time x)throws SQLException






Syntax public void updateTimestamp(int columnIndex, Timestamp x)throws SQLException






Chapter 3: JDBC MethodsStatement Methods

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.

wasNull()

Function: A column may have the value of SQL NULL. The wasNull method reports whether the last column read had this special value.

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.


Syntax public void updateTimestamp(String columnName, Timestamp x)throws SQLException






Syntax public boolean wasNull() throws SQLException

Return 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.



addBatch(String sql)

Function: Adds an SQL command to the current batch of commands for this Statement object.

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 are urged to 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 are urged to avoid using the cancel method in the problematic situations.

clearBatch()

Function: Makes the set of commands in the current batch empty.

clearWarnings()

Function: Clears all the warnings reported on this statement. After this call, getWarnings returns null until a new warning is reported for this Statement.


Syntax public void addBatch(String sql) throws SQLException

where the sql parameter is any SQL statement


Syntax public void cancel() throws SQLException


Syntax public void clearBatch() throws SQLException



close()

Function: In many cases, it is desirable to immediately release a Statement’s database and JDBC resources instead of waiting for this to happen when it is automatically closed. The close method provides this immediate release.

execute(String sql)

Function: Executes an SQL statement that may return multiple results.

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:





Return A Statement is automatically closed when it is garbage collected. When a Statement is closed, its current ResultSet, if one exists, is also closed.


Syntax public boolean execute(String sql) throws SQLException

where the sql parameter is any SQL statement

Return 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, this can be ignored, unless a stored procedure that is known to return multiple results is executing, or an unknown SQL string is dynamically executing.

The execute, getMoreResults, getResultSet, and getUpdateCount methods allow navigation through multiple results. The execute method executes an SQL statement and indicates the form of the first result. Then, to retrieve the result, use getResultSet or getUpdateCount; to move to any subsequent results, use getMoreResults.

See also “getResultSet()” on page 264, “getUpdateCount()” on page 265, and “getMoreResults()” on page 263.



• A number greater than or equal to 0–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

• 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.

• A value -3–indicates that the command failed to execute successfully

execute(String sql, int autoGeneratedKeys)

Function: Executes the given SQL statement, which may return multiple results, and signals the driver to make any auto-generated keys available for retrieval. The driver ignores 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:

• Executing a stored procedure that you know may return multiple results; or

• Dynamically executing an unknown SQL string

The execute method executes an SQL statement and indicates the form of the first result. Then, to retrieve the result, use getResultSet or getUpdateCount; to move to any subsequent results, use getMoreResults.


Syntax public int[] executeBatch() throws SQLException

Return 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().


Syntax public boolean execute(String sql, int autogeneratedKeys) throws SQLException


• sql is any SQL statement

• autoGeneratedKeys is 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

Return True, if the first result is a ResultSet object

False, if it is an update count or there are no results



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 ignores the array if the given SQL statement is not an INSERT statement.





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 ignores the array if the given SQL statement is not an INSERT statement.


Note: 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.


Syntax public boolean execute(String sql, int[] columnIndexes) throws SQLException



• columnIndexes is 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

Return True, if the first result is a ResultSet object

False, if it is an update count or there are no results

Note: 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.







executeQuery(String sql)

Function: Executes an SQL statement that returns a single ResultSet.

executeUpdate(String sql)

Function: Executes an SQL INSERT, UPDATE, or DELETE statement. In addition, SQL statements that return nothing, such as DDL statements, can be executed.


Syntax public boolean execute(String sql, String[] columnNames) throws SQLException



• columnNames is 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

Return True, if the next result is a ResultSet object

False, if it is an update count or there are no more results

Note: Throws an SQLException if a database access error occurs or the elements in the String array passed to this method are not valid column names.


Syntax public ResultSet executeQuery(String sql) throws SQLException

where the sql parameter is, typically, a static SQL SELECT statement

Return A ResultSet that contains the data produced by the query–never null–is returned.


Syntax public int executeUpdate(String sql) throws SQLException

where the sql parameter is any SQL INSERT, UPDATE, or DELETE statement, or an SQL statement that returns nothing

Return Either the row count for INSERT, UPDATE, or DELETE is returned; or 0 for SQL statements that return nothing is returned.



executeUpdate(String sql, int autoGeneratedKeys)

Function: Executes an SQL INSERT, UPDATE, or DELETE statement. In addition, SQL statements that return nothing, such as DDL statements, can be executed.

executeUpdate(String sql, int[] columnIndexes)

Function: 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 ignores the array if the SQL statement is not an INSERT statement.

executeUpdate(String sql, String[] columnNames)

Function: 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 ignores the array if the SQL statement is not an INSERT statement.


Syntax public int executeUpdate(String sql, int autogeneratedKeys) throws SQLException


• sql is any SQL INSERT, UPDATE, or DELETE statement, or an SQL statement that returns nothing

• autoGeneratedKeys is a flag indicating whether auto-generated keys should be made available for retrieval; one of the following constants:Statement.RETURN_GENERATED_KEYS or Statement.NO_GENERATED_KEYS


Note: 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.


Syntax public int executeUpdate(String sql, int[] columnIndexes) throws SQLException


• sql is an SQL INSERT, UPDATE, or DELETE statement or an SQL statement that returns nothing, such as an SQL DDL statement

• columnIndexes is an array of column indexes indicating the columns that should be returned from the inserted row


Note: Throws an SQLException if a database access error occurs, the given 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.



getConnection()

Function: Gets the connection object that produced statement.

getGeneratedKeys()

Function: 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.

getMaxFieldSize()

Function: Returns the maxFieldSize limit in bytes.


Syntax public int executeUpdate(String sql, String[] columnNames) throws SQLException


• sql is an SQL INSERT, UPDATE, or DELETE statement or an SQL statement that returns nothing

• columnNames is an array of names of the columns that should be returned from the inserted row


Note: Throws an SQLException if a database access error occurs, the given 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.



Return Gets the connection object that produced this statement object.


Syntax ResultSet getGeneratedKeys() throws SQLException

Return A ResultSet object containing the auto-generated key(s) generated by the execution of this Statement object is returned.


Syntax public int getMaxFieldSize() throws SQLException

Return The current maximum column size limit is returned. Zero means unlimited.



getMaxRows()

Function: Returns the maxRows limit.

getMoreResults()

Function: Moves to a Statement’s next result. It returns true if this result is a ResultSet.

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.

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.


Syntax public int getMaxRows() throws SQLException

Return The current maximum row limit is returned. 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.


Syntax public boolean getMoreResults() throws SQLException

Return 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: Statement Method execute(String sql).


Syntax public boolean getMoreResults(int current) throws SQLException

where the current parameter 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




getQueryTimeout()

Function: Retrieves the query Timeout limit. The limit is the number of seconds the driver will wait for a Statement to execute.

getResultSet()

Function: Returns the current result as a ResultSet. This method should only be called once per result.

Return • 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(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);

Beginning with Teradata Database 12.0, when the application requests the ResultSet type to be ResultSet.TYPE_SCROLL_INSENSITIVE, then the Teradata JDBC Driver 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.

The application must request scrollable result sets to obtain the improved performance when skipping to the next result. If the application requests forward-only result sets, then cursor positioning is not used, and the Teradata JDBC Driver must fetch all rows of the current result set in order to advance to the next result.


Syntax public int getQueryTimeout() throws SQLException

Return The current query timeout limit in seconds is returned. Zero means unlimited.

Note: If the limit is exceeded, an SQLException is thrown.


Syntax public ResultSet getResultSet() throws SQLException

Return The current result as a ResultSet is returned. Null, if the result is an update count or there are no more results.




getResultSetConcurrency()

Function: Retrieves the result set concurrency for ResultSet objects generated by this Statement object.

getResultSetHoldability()

Function: Retrieves the result set holdability for ResultSet objects generated by this Statement object.

getUpdateCount()

Function: Returns the current result as an update count.

It should only be called once per result.

getWarnings()

Function: The first warning reported by calls on this Statement is returned.

Note: See also: Statement Method execute(String sql).


Syntax public int getResultSetConcurrency() throws SQLException

Return Either ResultSet.CONCUR_READ_ONLY or ResultSet.CONCUR_UPDATABLE is returned.



Syntax public int getResultSetHoldability() throws SQLException

Return The default holdability, ResultSet.HOLD_CURSORS_OVER_COMMIT, is returned.

Note: Teradata JDBC Driver currently does not support ResultSet.CLOSE_CURSORS_AT_COMMIT.


Syntax public int getUpdateCount() throws SQLException

Return The current result as an update count is returned. A -1 is returned if it is a ResultSet or there are no more results.

Note: See also “execute(String sql)” on page 257.




setMaxFieldSize(int max)

Function: Sets the maxFieldSize limit in bytes.

setMaxRows(int max)

Function: Sets the maxRows limit.

setQueryTimeout(int seconds)

Function: Sets the queryTimeout limit.



Return The first SQL Warning or null is returned.

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.


Syntax public void setMaxFieldSize(int max) throws SQLException

where the max parameter is the new maximum column size limit. Zero means unlimited.

Note: 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.


Syntax public void setMaxRows(int max) throws SQLException

where the max parameter is the new maximum rows limit. Zero means unlimited number of rows.

Note: MaxRows is set to limit the number of rows that any ResultSet can contain. If the limit is exceeded, the excess rows are dropped.


Chapter 3: JDBC MethodsTeraDataSource Methods

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 41.

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:

• Database

• Collation

• Character Set


• Dateform

• Timezone

• Default date format


Syntax public void setQueryTimeout(int seconds) throws SQLException

where the seconds parameter is the new query timeout limit in seconds. Zero means an unlimited number of seconds.

Note: The queryTimeout limit is the number of seconds the driver will wait for a Statement to execute. If the limit is exceeded, an SQLException is thrown.



Methods

getACCOUNT()

Function: Gets the accountId. It returns the name of the account to be charged.

getCharSet()getCHARSET()

Function: Get the session character set.

getCOMPAT_DBS()

Function: Get the COMPAT_DBS value.

getCOMPAT_GETSCHEMA()

Function: Get the COMPAT_GETSCHEMA value.

getCOMPAT_GETTABLE()

Function: Get the COMPAT_GETTABLE value.


Syntax public String getACCOUNT()

Note: The getAccount and getAccountId methods are deprecated. Use the getACCOUNT method instead.


Syntax public java.lang.String getCharSet()

Return The character set is returned.


Syntax public java.lang.String getCOMPAT_DBS()

Return The COMPAT_DBS value is returned.


Syntax public java.lang.String getCOMPAT_GETSCHEMA()

Return The COMPAT_GETSCHEMA value is returned.



getCOMPAT_ISAUTOINC()

Function: Get the COMPAT_ISAUTOINC value.

getCOMPAT_ISCURRENCY()

Function: Get the COMPAT_ISCURRENCY value

getCOMPAT_ISDEFWRIT()

Function: Get the COMPAT_ISDEFWRIT value.

getCOMPAT_ISREADONLY()

Function: Get the COMPAT_ISREADONLY value.

getCOMPAT_ISSEARCH()

Function: Get the COMPAT_ISSEARCH value.


Syntax public java.lang.String getCOMPAT_GETTABLE()

Return The COMPAT_GETTABLE value is returned.


Syntax public java.lang.String getCOMPAT_ISAUTOINC()

Return The COMPAT_ISAUTOINC value is returned.


Syntax public java.lang.String getCOMPAT_ISCURRENCY()

Return The COMPAT_ISCURRENCY value is returned.


Syntax public java.lang.String getCOMPAT_ISDEFWRIT()

Return The COMPAT_ISDEFWRIT value is returned.


Syntax public java.lang.String getCOMPAT_ISREADONLY()

Return The COMPAT_ISREADONLY value is returned.



getCOMPAT_ISSIGNED()

Function: Get the COMPAT_ISSIGNED value.

getCOMPAT_ISWRITABLE()

Function: Get the COMPAT_ISWRITABLE value.

getConnection()

Function: Attempt to establish a database connection.

getConnection(java.lang.String username, java.lang.String password)

Function: Attempt to establish a database connection.


Syntax public java.lang.String getCOMPAT_ISSEARCH()

Return The COMPAT_ISSEARCH value is returned.


Syntax public java.lang.String getCOMPAT_ISSIGNED()

Return The COMPAT_ISSIGNED value is returned.


Syntax public java.lang.String getCOMPAT_ISWRITABLE()

Return The COMPAT_ISWRITABLE value is returned.


Syntax public java.sql.Connection getConnection()throws java.sql.SQLException

Return A connection to the database is returned.



getDatabase()getdatabase()getDATABASE()

Function: Get the Default Database name. This returns the name of the default database that will be set at logon time.

getdatasourceName()

Function: Get the name of this datasource.

getDBS_PORT()

Function: Get the DBS_PORT value. This specifies the TCP/IP port used to access the Teradata Database.

getdescription()

Function: Get the description of the DataSource.


Syntax public java.sql.Connection getConnection(java.lang.String username, java.lang.String password)throws java.sql.SQLException




Return A connection to the database is returned.


Syntax public java.lang.String getDatabase()

Return The default database name is returned.


Syntax public java.lang.String getdatasourceName()

Return The datasource name or null is returned.


Syntax public java.lang.String getDBS_PORT()

Return The DBS_PORT value is returned.



getDSName()

Function: Get the Database Server name. This returns the name of the server running the Teradata Database.

getENCRYPTDATA()

Function: Get the EncryptData flag.

getFetchRows()

Function: Get the Fetch Rows value used in Row Caching.

getLOB_SUPPORT()

Function: Get the LOB_SUPPORT value.


Syntax public java.lang.String getdescription()

Return A description is returned.


Syntax public java.lang.String getDSName()

Return The Database Server name is returned.


Syntax public java.lang.String getENCRYPTDATA()

Return ON–When set to ON, data sent between the Teradata JDBC Driver and the Teradata Database are encrypted. This provides greater security, although performance will be affected.

OFF–When set to OFF, data sent between the Teradata JDBC Driver 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.


Syntax public java.lang.String getFetchRows()

Return The Fetch Rows value is returned.



getLOB_TEMP_TABLE()

Function: Gets the LOB_TEMP_TABLE value.

getLOG()

Function: Get the LOG value.

getLoginTimeout()

Function: Get the Login Timeout.

getLOGDATA()

Function: Get the LogData value.

getLOGMECH()

Function: Get the Logon Mechanism value.


Syntax public java.lang.String getLOB_SUPPORT()

Return The LOB_SUPPORT value is returned.


Syntax public java.lang.String getLOB_TEMP_TABLE()

Return The tableName used for Updatable Lobs is returned.


Syntax public java.lang.String getLOG()

Return The LOG value is returned.


Syntax public int getLoginTimeout()throws java.sql.SQLException

Return The login timeout is returned.


Syntax public java.lang.String getLOGDATA()

Return The LogData value or null is returned.



getLogWriter()

Function: Get the Log File name.

getpassword()

Function: Get the password used for DBS access.

getportNumber()

Function: 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.

getReference()

Function: Get a Reference to the TeraDataSource.


Syntax public java.lang.String getLOGMECH()

Return The Logon Mechanism or null is returned.


Syntax public java.io.PrintWriter getLogWriter()

Return The log file name is returned.


Syntax public java.lang.String getpassword()

Return The password is returned.


Syntax public java.lang.String getportNumber()

Return The port number is returned.


Syntax public javax.naming.Reference getReference()throws javax.naming.NamingException

Return A Reference to the TeraDataSource is returned.



getServerName()

Function: This function has been deprecated. Get the Teradata JDBC gateway Server name. getServerName will log an error message, but will not throw an exception.

getSP_SPL()

Function: Get the SP_SPL value.

getspl()

Function: This function has been deprecated. Get the value of Stored Procedure spl option.

getTransactMode()getTMODE

Get the Transaction Mode value.

getTNANO()

Function: Get the TNANO value.


Syntax public java.lang.String getServerName()

Return The server name is returned.


Syntax public java.lang.String getSP_SPL()

Return The SP_SPL value is returned.


Syntax public java.lang.String getspl()

Return The value of Stored Procedure spl option is returned.

Note: Use the connection URL Parameter SP_SPL described in “Making a Teradata Database Connection” on page 41.


Syntax public java.lang.String getTransactMode()

Return The Transaction Mode value is returned.



getTSNANO()

Function: Get the TSNANO value.

getuser()

Function: Get the user name used for DBS access.

getUSEXVIEWS()

Function: Gets the USEXVIEWS value.

setACCOUNT(String accountId)

Function: Sets the accountId.


Syntax public java.lang.String getTNANO()

Return The TNANO value is returned.


Syntax public java.lang.String getTSNANO()

Return The TSNANO value is returned.


Syntax public java.lang.String getuser()

Return The user name is returned.


Syntax public java.lang.String getUSEXVIEWS()

Return The USEXVIEWS value is returned.


Syntax public void setACCOUNT(String accountId)

where 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: Set the session character set.

setCOMPAT_DBS()

Function: Set the COMPAT_DBS value.

setCOMPAT_GETSCHEMA()

Function: Set the COMPAT_GETSCHEMA value.

setCOMPAT_GETTABLE()

Function: Set the COMPAT_GETTABLE value.

setCOMPAT_ISAUTOINC()

Function: Set the COMPAT_ISAUTOINC value.


Syntax public void setCharSet(java.lang.String CharSet)

where the CharSet parameter is ASCII, KANJISJIS_OS, or KANJIEUC_0U


Syntax public void setCOMPAT_DBS(java.lang.String compatVal)

where the compatValue parameter is COMPAT_DBS value


Syntax public void setCOMPAT_SCHEMA(java.lang.String compatVal)

where the compatValue parameter is COMPAT_SCHEMA value


Syntax public void setCOMPAT_GETTABLE(java.lang.String compatVal)

where the compatValue parameter is GETTABLE value


Syntax public void setCOMPAT_ISAUTOINC(java.lang.String compatVal)

where the compatValue parameter is COMPAT_ISAUTOINC value



setCOMPAT_ISCURRENCY()

Function: Set the COMPAT_ISCURRENCY value.

setCOMPAT_ISDEFWRIT()

Function: Set the COMPAT_ISDEFWRIT value.

setCOMPAT_ISREADONLY()

Function: Set the COMPAT_ISREADONLY value.

setCOMPAT_ISSEARCH()

Function: Set the COMPAT_ISSEARCH value.

setCOMPAT_ISSIGNED()

Function: Set the COMPAT_ISSIGNED value.


Syntax public void setCOMPAT_ISCURRENCY(java.lang.String compatVal)

where the compatValue parameter is COMPAT_ISCURRENCY value


Syntax public void setCOMPAT_ISDEFWRIT(java.lang.String compatVal)

where the compatValue parameter is COMPAT_ISDEFWRIT value


Syntax public void setCOMPAT_ISREADONLY(java.lang.String compatVal)

where the compatValue parameter is COMPAT_ISREADONLY value


Syntax public void setCOMPAT_ISSEARCH(java.lang.String compatVal)

where the compatValue is COMPAT_ISSEARCH value


Syntax public void setCOMPAT_ISSIGNED(java.lang.String compatVal)

where the compatValue parameter is COMPAT_ISSIGNED value



setCOMPAT_ISWRITABLE()

Function: Set the COMPAT_ISWRITABLE value.

setDatabase(java.lang.String database)setdatabase(java.lang.String database)setDATABASE(java.lang.String database)

Function: Set the Default Database name. This sets the name of the default database that will be set at logon time.

setdatasourceName(java.lang.String datasourceName)

Function: Set the name of this datasource.

setDBS_PORT(java.lang.String dbsport)

Function: Set the DBS_PORT value.

setdescription(java.lang.String description)

Function: Set the description of the DataSource.


Syntax public void setCOMPAT_ISWRITABLE(java.lang.String compatVal)

where the compatValue parameter is COMPAT_ISWRITABLE value


Syntax public void setDatabase(java.lang.String database)

where the database parameter is the name of database to access at logon


Syntax public void setdatasourceName(java.lang.String datasourceName)

where the datasourceName parameter is name of datasource to access at logon


Syntax public void setDBSPORT(java.lang.String dbsport)

where the dbsport parameter is TCP/IP port number of the Teradata Database



setDSName(java.lang.String DSName)

Function: Set the Database Server name. This sets the name of the server running the Teradata Database.

setENCRYPTDATA(java.lang.String encryptData)

Function: Set the EncryptData flag. This flag determines whether data is encrypted on this connection.

setFetchRows(java.lang.String FetchRows)

Function: Set the Fetch Rows.

setLOB_SUPPORT(java.lang.String lobSupport)

Function: Set the LOB_SUPPORT value.


Syntax public void setdescription(java.lang.String description)

where the description parameter is the description of DataSource


Syntax public void setDSName(java.lang.String DSName)

where the DSName parameter is the Database Server name


Syntax public void setENCRYPTDATA(java.lang.String encryptData)

where the encryptData parameter is:

ON–When set to ON, data sent between the Teradata JDBC Driver and the Teradata Database are encrypted. This provides greater security, although performance will be affected.

OFF–When set to OFF, data sent between the Teradata JDBC Driver 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) method determines whether or not data is encrypted on the connection.


Syntax public void setFetchRows(java.lang.String FetchRows)

where the FetchRows parameter is the new fetch row value



setLOB_TEMP_TABLE(java.lang.String)

Function: Set the LOB_TEMP_TABLE value.

setLOG(java.lang.String lobSupport)

Function: Set the LOG value.

setLOGDATA(java.lang.String logData)

Function: 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.


Syntax public void setLOB_SUPPORT(java.lang.String lobSupport)

where the lobSupport parameter is the lobSupport value


Syntax public void setLOB_TEMP_TABLE(java.lang.String lobTempTable)

where the lobTempTable parameter is the tableName or databaseName.tableName used for Updatable Lobs


Syntax public void setLOG(java.lang.String logValue)

where the logValue parameter is the LOG value–ERROR, INFO, or DEBUG


Syntax public void setLOGDATA(java.lang.String LogData)

where the LogData parameter is 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=teradata,dc=com password=secret’




Function: Set the Login Timeout.

setLOGMECH(java.lang.String LogMech)

Function: Set the Logon Mechanism. The mechanism determines the level of security used on the connection and whether or not Single Sign-on is supported.

setLogWriter(java.io.PrintWriter out)

Function: Set the Log File name.

setpassword(java.lang.String password)

Function: Set the password used for DBS access.

setportNumber(java.lang.String portNumber)

Function: 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.


Syntax public void setLoginTimeout(int seconds)throws java.sql.SQLException

where the seconds parameter is the Login Timeout value


Syntax public void setLOGMECH(java.lang.String LogMech)

where the LogMech parameter is 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


Syntax public void setLogWriter(java.io.PrintWriter out)throws java.sql.SQLException

where the out parameter is the log file name


Syntax public void setpassword(java.lang.String password)

where the password parameter is the password for DBS user.



setServerName(java.lang.String serverName)

Function: This function has been deprecated. Set the Teradata JDBC gateway Server name. setServerName will log an error message, but will not throw an exception.

setSpl(java.lang.String spl)

Function: This function has been deprecated. Set the value of Stored Procedure spl option.

setSP_SPL(java.lang.String splVal)

Function: Set the value of Stored Procedure spl option.

seTMODE(java.lang.String TransactMode)

Function: Set the TMODE value.


Syntax public void setportNumber(java.lang.String portNumber)

where the portNumber parameter is the port number used by the gateway


Syntax public void setServerName(java.lang.String serverName)

where the ServerName parameter is the Server name


Syntax public void setspl(java.lang.String spl)

where the spl parameter is SPL or NOSPL

Note: Use the connection URL Parameter SP_SPL described in “Making a Teradata Database Connection” on page 41.


Syntax public void setSP_SPL(java.lang.String splVal)

where the splVal parameter is the SPL value


Syntax public void setTMODE(java.lang.String tmodeVal)

where the tmodeVal parameter is the TMODE value



setTNANO(java.lang.String tnanoVal)

Function: Set the TNANO value.

setTransactMode(java.lang.String TransactMode)seTMODE(java.lang.String TransactMode)

Function: Set the Transaction Mode.

setTSNANO(java.lang.String tsnanoVal)

Function: Set the TSNANO value.

setuser(java.lang.String user)

Function: Set the user name used for DBS access.

setUseXVIEWS(java.lang.String useXviews)

Function: Configures the Connection to use or not use X_views when retrieving Database Metadata.


Syntax public void setTNANO(java.lang.String tnanoVal)

where the tnanoVal parameter is the TNANO value


Syntax public void setTransactMode(java.lang.String TransactMode)

where the TransactMode parameter is ANSI, TERA, or DEFAULT


Syntax public void setTSNANO(java.lang.String tsnanoVal)

where the tsnanoVal is the TSNANO value


Syntax public void setuser(java.lang.String user)

where the user parameter is the user name for DBS access.




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.


APPENDIX A

Supported JDBC Methods

This appendix contains a synopsis of the JDBC methods supported by the Teradata JDBC Driver. 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


Appendix A: Supported JDBC MethodsSupported Methods

• “Yes**” in the Supported column of the table indicates that the method is supported by the Teradata JDBC Driver when connected to Teradata Database V2R6.2.

• “Yes***” in the Supported column of the table indicates that the method is supported by the Teradata JDBC Driver, but is not supported by the Teradata Database.

JDBC BLOB Interface Methods

JDBC CLOB Interface Methods

Table 31: 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

Table 32: JDBC CLOB Interface Methods

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



JDBC CallableStatement Methods

Table 33: 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



JDBC Connection Methods

Table 34: JDBC Connection Methods

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



JDBC ConnectionEvent Methods

JDBC ConnectionEventListener Methods

JDBC ConnectionPoolDataSource Methods

JDBC DatabaseMetaData Methods

Table 35: JDBC ConnectionEvent Methods

ConnectionEvent Methods Supported

ConnectionEvent(PooledConnection con) Yes

ConnectionEvent(PooledConnection con, SQLException ex) Yes

getSQLException() Yes

Table 36: JDBC ConnectionEventListener Methods

ConnectionEvent Listener Methods Supported

connectionClosed(ConnectionEvent event) Yes

connectionErrorOccurred(ConnectionEvent event) Yes

Table 37: 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

Table 38: JDBC DatabaseMetaData Methods

DatabaseMetaData Methods Supported

allProceduresAreCallable() Yes

allTablesAreSelectable() Yes

dataDefinitionCausesTransactionCommit() Yes



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 primaryTable, String foreignCatalog, String foreignSchema, String foreignTable)

Yes

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

Table 38: JDBC DatabaseMetaData Methods (continued)




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





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***





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





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





JDBC DataSource Methods

JDBC DriverManager Methods

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



Table 39: JDBC DataSource Methods

DataSource Methods Supported

getConnection() Yes

getConnection(String username, String password) Yes


getLogWriter() Yes


setLogWriter(PrintWriter out) Yes

Table 40: JDBC DriverManager Methods

DriverManager Methods Supported

deregisterDriver(Driver driver) Yes

getConnection(String url) Yes



JDBC ParameterMetaData Methods

getConnection(String url, Properties info) Yes

getConnection(String url, String user, String password) Yes

getDriver(String url) Yes

getDrivers() Yes


getLogStream() [DEPRECATED] Yes

getLogWriter() No

printIn(String message) Yes

registerDriver(Driver driver) Yes


setLogStream(PrintStream out) [DEPRECATED] Yes

setLogWriter(PrintWriter out) No

Table 40: JDBC DriverManager Methods (continued)

DriverManager Methods Supported

Table 41: JDBC ParameterMetadata Methods

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



JDBC PooledConnection Methods

JDBC PreparedStatement Methods

Table 42: JDBC PooledConnection Methods

PooledConnection Methods Supported

addConnectionEventListener(ConnectionEventListener listener) Yes

close() Yes

getConnection() Yes

removeConnectionEventListener(ConnectionEventListener listener) Yes

Table 43: 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



JDBC ResultSetMetadata Methods

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

Table 43: JDBC PreparedStatement Methods (continued)

PreparedStatement Methods Supported

Table 44: JDBC ResultSetMetadata Methods

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



JDBC ResultSet Methods

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**

Table 44: JDBC ResultSetMetadata Methods (continued)

ResultSetMetadata Methods Supported

Table 45: 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



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

Table 45: JDBC ResultSet Methods (continued)




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





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

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





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





JDBC Statement Methods

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



Table 46: JDBC Statement Methods

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



TeraDataSource Methods

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

Table 46: JDBC Statement Methods (continued)

Statement Methods Supported

Table 47: 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



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


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

Table 47: TeraDataSource Methods (continued)




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


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





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




APPENDIX B

Troubleshooting

This appendix provides information for troubleshooting the following operating system and client software problems associated with Teradata JDBC Driver 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

• 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 FastExport

• Troubleshooting JDBC Monitor

• USEXViews=ON Performance

• Slow Logon on Linux

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”.


Appendix B: TroubleshootingNumeric 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 JDBC Driver. 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 JDBC Driver 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 JDBC Driver 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 JDBC Driver 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

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


Appendix B: TroubleshootingTransaction Isolation, Concurrency, and Deadlock

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:


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.teradata.jdbc.jdbc_4.util.JDBCException:[Teradata Database]: 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.teradata.jdbc.jdbc_4.util.JDBCException:[Teradata Database]: 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.

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.



Appendix B: TroubleshootingLarge Object Interface

com.teradata.jdbc.jdbc_4.util.JDBCException:[Teradata Database]: 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 JDBC Driver 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 JDBC Driver 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: HY000Message: [Teradata Database] : 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.

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.


Appendix B: TroubleshootingLarge Object Interface

• 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 exception-handling, 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 41.

The Teradata JDBC Driver 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 JDBC Driver; 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 JDBC Driver 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:

[Teradata Database] : Parcel kind or ordering is invalid.


Appendix B: TroubleshootingChecking the Environment Parameters

Checking the Environment Parameters

CLASSPATH

If you receive a ClassNotFoundException for “com.teradata.jdbc.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 “UserFile parameter null” error, then the problem might be due to the classpath not being set, or the classpath being set incorrectly such that tdgssconfig.jar cannot be found. The tdgssconfig.jar file must be listed on the classpath.

If you receive one of the following exceptions:

• NullPointerException at com.teradata.tdgss.jtdgss.TdgssConfigApi.GetMechanisms

• IllegalArgumentException “InputStream cannot be null” at javax.xml.parsers.DocumentBuilder.parse, at com.teradata.tdgss.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 JDBC Driver must include:

• terajdbc4.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.

• 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.


Appendix B: TroubleshootingImproving Performance

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 re-execute 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 JDBC Driver 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 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");


Appendix B: TroubleshootingImproving Performance

Using the setBytes method with a CAST expression forces the Teradata JDBC Driver 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 JDBC Driver 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

• Character Set


• Dateform

• Timezone


Appendix B: TroubleshootingJava HotSpot Server Virtual Machine Error on Linux Platform

• 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 JDBC Driver 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.

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


Appendix B: TroubleshootingTroubleshooting Security

• 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

(Mechanism level: Failed to find any Kerberos Ticket)

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:

com.sun.security.jgss.initiate{ com.sun.security.auth.module.Krb5LoginModule sufficient useTicketCache=true; };

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.


Appendix B: TroubleshootingTroubleshooting Security

LDAP Authentication Not Supported on z/OS

LDAP does not support Teradata JDBC Driver logon from z/OS.

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

[Teradata Database]: 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

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"


Appendix B: TroubleshootingTroubleshooting JDBC FastLoad

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: [Teradata Database]: The UserId, Password or Account is invalid.

UserId, Password, or Account is Invalid

Error Message: [Teradata Database] : 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 {

SQLWarning w = con.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();}// using JDBC FastLoadw = pstmt.getWarnings();

} finally {pstmt.close();

}


Appendix B: TroubleshootingTroubleshooting JDBC FastExport

} 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 97. 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 found in the SQLWarning of a connection, which might be part of a chain of SQL warnings. To get the complete picture of the cause for the SQLWarning, it is necessary to scroll through the whole chain of SQL warnings.

Information on why JDBC FastLoad was not activated also 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 FastExport

If an SQLException is encountered during JDBC FastExport, it might 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 FastExport, it might be part of a chain of SQL warnings. To get the 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("SELECT ... FROM ...");try {

// using JDBC FastExportSQLWarning w = pstmt.getWarnings();while (w != null) {


Appendix B: TroubleshootingTroubleshooting JDBC Monitor

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();}


}} 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());


}

Information on why JDBC FastExport was not activated can be found in an SQLWarning of a Connection, which might contain a chain of SQL warnings. To get the complete picture of the cause for the SQLWarning, it is necessary to walk through the whole chain of SQL warnings.

Information on why JDBC FastExport was not activated can also be obtained by specifying “LOG=INFO” in the URL connection string.

• The following sample LOG output shows that JDBC FastExport was not activated:

Cannot FastExport because statement is not a SELECT!

• The following sample LOG output shows that JDBC FastExport was activated:

FastExport found 2 AMP(s) in anmpc2 and created 2 FastExportConnection(s) and 2 FastExportPreparedStatement(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();


Appendix B: TroubleshootingUSEXViews=ON Performance

while (w != null)StringWriter sw = new StringWriter();w.printStackTrace(new PrintWriter(sw,true));System.out.printIn(“SQL State = ” + w.getSQLState() +

“, Error Code = ” + w.getErrorCode() +“\n” + sw.toString());

w = w.getNextWarning();}


}} 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());


}

USEXViews=ON Performance

When the connection parameter USEXVIEWS=ON is specified, DatabaseMetaData methods might perform slowly. Slow performance of queries against Data Dictionary X-Views can sometimes be due to a lack of accurate, up-to-date statistics.

It is recommended that the Teradata Database administrator execute the following SQL commands on a regular basis to collect statistics on certain Data Dictionary columns and indexes relevant to Data Dictionary X-Views:

drop stats on dbc.tvm;drop stats on dbc.owners;drop stats on dbc.dbase;drop stats on dbc.accessrights;drop stats on dbc.tvfields

collect stats on dbc.tvm column (tvmId);collect stats on dbc.tvm INDEX ( DatabaseId ,TVMNameI );collect stats on dbc.tvm column (DatabaseId );collect stats on dbc.owners INDEX (ownerId);collect stats on dbc.dbase INDEX ( DatabaseId );collect stats on dbc.dbase column(JournalId);collect stats on dbc.accessrights INDEX ( UserId ,DatabaseId );collect stats on dbc.accessrights INDEX ( TVMId );collect stats on dbc.accessrights column ( UserId ,TVMId);collect stats on dbc.accessrights column (DatabaseId );collect stats on dbc.tvfields column (DatabaseId)collect stats on dbc.tvfields column (FieldId)collect stats on dbc.tvfields column (tableId)


Appendix B: TroubleshootingSlow Logon on Linux

Slow Logon on Linux

JDBC users might experience a slow logon process when running on a Linux system, varying from several additional seconds to several minutes. This occurs when using the TD2 mechanism, which is the default mechanism for a Teradata JDBC connection. The cause is underlying problems with random number generation, and is documented by the following Java bugs:

http://bugs.sun.com/bugdatabase/view_bug.do?id=6202721

http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6366924

Note that the presence of these problems does not guarantee that every logon is slow. Test programs that recreate the problem can run successfully for many iterations before the problem appears. Run the following java program if you suspect this problem.

If there are no problems, the program should finish in a few seconds. If the slow logon problem is present, then it may take several minutes for the program to run. The program prints iteration count for each test run and thus slow progress can be determined by pauses in the program’s output.

//// This program tests to see if there are delay problems associated the// use of// SecureRandom

import java.security.SecureRandom;import java.util.*;import java.math.*;

class secRandomPrb {public static void main(String args[]) throws Exception {

System.out.println();System.out.println("Pass 1: getInstance:");runit(true);System.out.println();System.out.println("Pass 2: secureRandom:");runit(false);

}

public static void runit(boolean secRand) {

SecureRandom srand;BigInteger x;int ctr = 0;try {for (ctr = 0; ctr < 1000; ctr++) {

if (secRand == true)srand = SecureRandom.getInstance("SHA1PRNG");

elsesrand = new SecureRandom();

byte[] seed = srand.generateSeed(8);srand.setSeed(seed);x = new BigInteger(512, srand);int i = x.intValue();


http://bugs.sun.com/bugdatabase/view_bug.do?id=6202721

http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6366924


System.out.print(ctr + " ");}

}catch (Exception ex) {System.out.println("Exception: " + ex);

}}

}

If the slow logon problem is present, it can be resolved by specifying “/dev/./urandom”, as a link for /dev/random or as the securerandom.source.

This can be done by “Using a Command Line Argument” or “Changing /dev/random to be a symbolic link”.

Using a Command Line Argument

The recommended workaround is to specify a command line argument for starting Java JVM. This allows the change to be made only to java programs that may encounter this problem. The command line setting of:

-Djava.security.egd=file:/dev/./urandom

will fix the problem. Note the extra “.” directory between dev and urandom. This is required. The above test program can be run with this setting as follows:

java -Djava.security.egd=file:/dev/./urandom secRandomPrb

Note that this same property is available in the security file in $JAVA_HOME/jre/lib/security/java.security file. Though normally, a change to the java.security file should provide the same effect, our testing has shown that changes to that file will not resolve the problem when using JDK 5.0.

Changing /dev/random to be a symbolic link

This change requires root permission and will change the setting of /dev/random for ALL programs on your system. You can log in as root and execute the following commands:

mv /dev/random /dev/random.realIn -s /dev/./urandom /dev/random

After this change is made, the slow logon problem will be fixed. Verify this by running the test program provided above.


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 48 describes, in alphabetic order, the metadata features and functions of the Teradata JDBC Driver software.

Table 48: 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:

• Data manipulation statement?

• Index definition statement?

• Privilege definition statement?

• Procedure call statement?

• Table definition statement?

No–Catalog names are not supported

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


Appendix C: Metadata Features and FunctionsIssues and Answers

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 because 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

What is the URL for this database? jdbc:teradata

Is the database in read-only mode? No

Table 48: 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


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?

30 characters


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.teradata.jdbc.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


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 Quick Reference

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


Topic/Issue Answer



Subqueries

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 they be different from the names of the tables?

Yes

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


Topic/Issue Answer



Can multiple transactions on different connections be open at the same time?

Yes

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 There is no function that returns the user name, but a variable called user (ex. select user;)


Topic/Issue Answer


APPENDIX D

Data Type Conversions

This appendix provides a table for Data Type Conversions.

Data Type Conversions Table

Table 49 lists the data type conversions that are supported by the Teradata JDBC Driver.

Table 49: Data Type Conversions Table

Teradata Data Types BYEI

NTSM

ALLI

NTIN

TEGE

Rn/

an/

an/

aDO

UBLE

PRE

CISI

ONDE

CIMA

LNU

MERI

Cn/

an/

aCH

ARVA

RCHA

RLO

NG V

ARCH

ARBY

TEVA

RBYT

EVA

RBYT

E(64

00)

DATE

TIME

TIME

STAM

PCL

OBBL

OBn/

an/

an/

an/

an/

a

JDBC Data Types TINY

INT

SMAL

LINT

INTE

GER

BIGI

NTRE

ALFL

OAT

DOUB

LEDE

CIMA

LNU

MERI

CBI

TBO

OLEA

NCH

ARVA

RCHA

RLO

NGVA

RCHA

RBI

NARY

VARB

INAR

YLO

NGVA

RBIN

ARY

DATE

TIME

TIME

STAM

PCL

OBBL

OBAR

RAY

REF

DATA

LINK

STRU

CTJA

VA O

BJEC

T

ResultSet Methods

PreparedStatement 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

getDouble setDouble X X X X X X X


Appendix D: Data Type ConversionsData Type Conversions Table

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 X X X

getDate setDate X X X X

getTime setTime X X X X

getTimestamp setTimestamp X X X X

getAsciiStream setAsciiStream X X X

getBinaryStream

setBinaryStream

X X X

getCharacterStream

setCharacterStream

X X X

getClob setClob X

getBlob setBlob X

getArray setArray

getRef setRef

getURL setURL

Table 49: Data Type Conversions Table (continued)


NTSM

ALLI

NTIN

TEGE

Rn/

an/

an/

aDO

UBLE

PRE

CISI

ONDE

CIMA

LNU

MERI

Cn/

an/

aCH

ARVA

RCHA

RLO

NG V

ARCH

ARBY

TEVA

RBYT

EVA

RBYT

E(64

00)

DATE

TIME

TIME

STAM

PCL

OBBL

OBn/

an/

an/

an/

an/

a


INT

SMAL

LINT

INTE

GER

BIGI

NTRE

ALFL

OAT

DOUB

LEDE

CIMA

LNU

MERI

CBI

TBO

OLEA

NCH

ARVA

RCHA

RLO

NGVA

RCHA

RBI

NARY

VARB

INAR

YLO

NGVA

RBIN

ARY

DATE

TIME

TIME

STAM

PCL

OBBL

OBAR

RAY

REF

DATA

LINK

STRU

CTJA

VA O

BJEC

T



getObject->String

X X X

getObject->BigDecimal

X X

getObject->Boolean

getObject->Integer

X X X

getObject->Long

getObject->Float

getObject->Double

X X

getObject->byte[]

X X X

getObject->java.sql.Date

X

getObject->java.sql.Time

X

getObject->java.sql.Timestamp

X

getObject->java.sql.Clob

X

getObject->java.sql.Blob

X

getObject->java.sql.Array



NTSM

ALLI

NTIN

TEGE

Rn/

an/

an/

aDO

UBLE

PRE

CISI

ONDE

CIMA

LNU

MERI

Cn/

an/

aCH

ARVA

RCHA

RLO

NG V

ARCH

ARBY

TEVA

RBYT

EVA

RBYT

E(64

00)

DATE

TIME

TIME

STAM

PCL

OBBL

OBn/

an/

an/

an/

an/

a


INT

SMAL

LINT

INTE

GER

BIGI

NTRE

ALFL

OAT

DOUB

LEDE

CIMA

LNU

MERI

CBI

TBO

OLEA

NCH

ARVA

RCHA

RLO

NGVA

RCHA

RBI

NARY

VARB

INAR

YLO

NGVA

RBIN

ARY

DATE

TIME

TIME

STAM

PCL

OBBL

OBAR

RAY

REF

DATA

LINK

STRU

CTJA

VA O

BJEC

T



getObject->java.sql.Struct

getObject->java.sql.Ref

getObject->java.net.URL

getObject->other class

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

setObject(byte[])

X X X



NTSM

ALLI

NTIN

TEGE

Rn/

an/

an/

aDO

UBLE

PRE

CISI

ONDE

CIMA

LNU

MERI

Cn/

an/

aCH

ARVA

RCHA

RLO

NG V

ARCH

ARBY

TEVA

RBYT

EVA

RBYT

E(64

00)

DATE

TIME

TIME

STAM

PCL

OBBL

OBn/

an/

an/

an/

an/

a


INT

SMAL

LINT

INTE

GER

BIGI

NTRE

ALFL

OAT

DOUB

LEDE

CIMA

LNU

MERI

CBI

TBO

OLEA

NCH

ARVA

RCHA

RLO

NGVA

RCHA

RBI

NARY

VARB

INAR

YLO

NGVA

RBIN

ARY

DATE

TIME

TIME

STAM

PCL

OBBL

OBAR

RAY

REF

DATA

LINK

STRU

CTJA

VA O

BJEC

T



setObject(java.sql.Date)

X X X X

setObject(java.sql.Time)

X X X X

setObject(java.sql.Timestamp)

X X X X

setObject(java.sql.Clob)

X

setObject(java.sql.Blob)

X

setObject(java.sql.Array)

setObject(java.sql.Struct)

setObject(java.sql.Ref)

setObject(java.net.URL)

setObject(other class)



NTSM

ALLI

NTIN

TEGE

Rn/

an/

an/

aDO

UBLE

PRE

CISI

ONDE

CIMA

LNU

MERI

Cn/

an/

aCH

ARVA

RCHA

RLO

NG V

ARCH

ARBY

TEVA

RBYT

EVA

RBYT

E(64

00)

DATE

TIME

TIME

STAM

PCL

OBBL

OBn/

an/

an/

an/

an/

a


INT

SMAL

LINT

INTE

GER

BIGI

NTRE

ALFL

OAT

DOUB

LEDE

CIMA

LNU

MERI

CBI

TBO

OLEA

NCH

ARVA

RCHA

RLO

NGVA

RCHA

RBI

NARY

VARB

INAR

YLO

NGVA

RBIN

ARY

DATE

TIME

TIME

STAM

PCL

OBBL

OBAR

RAY

REF

DATA

LINK

STRU

CTJA

VA O

BJEC

T


APPENDIX E

SQL Data Types Mapping

This appendix provides information about how data is mapped between SQL and Java Stored Procedure parameters.

SQL Data Types Mapping Table

The following table defines how data is mapped between SQL and Java Stored Procedure parameters. The SQL data type is converted to or converted from corresponding Java data type, based on the type of parameter mapping. Simple mapping is the default. Use the External Name clause to specify object mapping.

SQL Data Type

IN Parameter OUT Parameter INOUT Parameter

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.BigDecimal

– java.math.BigDecimal[]


DECIMAL – 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[]


Appendix E: SQL Data Types MappingSQL Data Types Mapping Table

TIME – java.sql.Time – java.sql.Time[] – java.sql.Time[]

TIMESTAMP – java.sql.Timestamp

– 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[]

VARGRAPHIC

– – – – – –

GRAPHIC – – – – – –

INTERVAL – java.lang.String – java.lang.String[] – java.lang.String[]

UDT** – – – – – –

SQL Data Type

IN Parameter OUT Parameter INOUT Parameter





Glossary

A

ANSI: American National Standards Institute. ANSI maintains a standard for SQL. For information about Teradata compliance with ANSI SQL, see the SQL 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.


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 binary-based 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: A session is a single connection with the Teradata Database.

SPL: 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 general-purpose 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.


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.


Glossary


Index

Aabsolute(int row) 212ACCOUNT= 42addBatch() 199addBatch(String sql) 256addConnectionEventListener(ConnectionEventListener

listener) 198afterLast() 213AIX 22allProceduresAreCallable() 135allTablesAreSelectable() 135ALTER TABLE statements 329architecture

JDBC 26three-tier 21

BbeforeFirst() 213BLOB Interface Methods 106bytes) 107bytes, int offset, int len) 107

CCallableStatement Methods 111cancel() 256cancelRowUpdates() 213catalogs 329character literals 330characters 329CHARSET 42checking

hosts file entries 316clearBatch() 256clearParameters() 199clearWarnings() 119, 214, 256CLOB Interface Methods 108close() 119, 198, 214, 257column aliases 330columnIndexes) 125, 259, 261columnNames) 126, 259, 261columns 330commit() 119COMPAT_DBS 42COMPAT_GETSCHEMA 42COMPAT_GETTABLE 42

COMPAT_ISAUTOINC 42COMPAT_ISCURRENCY 42COMPAT_ISDEFWRIT 42COMPAT_ISREADONLY 42COMPAT_ISSEARCH 42COMPAT_ISSIGNED 42COMPAT_ISWRITABLE 42connection

parameters 43Connection Methods 119connectionClosed(ConnectionEvent event) 131connectionErrorOccurred(ConnectionEvent event) 132ConnectionEvent Methods 130ConnectionEvent(PooledConnection con) 130ConnectionEvent(PooledConnection con, SQLException ex)

130ConnectionEventListener Methods 131ConnectionPoolDataSource Methods 132CONVERT functions 330createStatement() 120createStatement(int resultSetType, int resultSetConcurrency)

120cursors 330

Ddata definitions 331data manipulation statements 331DATABASE 42database connection parameters 43

ACCOUNT 43ACCOUNTID 43CHARSET 44COMPAT_DBS 45COMPAT_GETSCHEMA 47COMPAT_GETTABLE 47COMPAT_ISAUTOINC 45COMPAT_ISCURRENCY 45COMPAT_ISDEFWRIT 47COMPAT_ISREADONLY 46COMPAT_ISSEARCH 46COMPAT_ISSIGNED 46COMPAT_ISWRITABLE 46DATABASE 47DBS_PORT 47DEBUG 48ENCRYPTDATA 48


Index

featureProps 48GOVERN 48LOB_SUPPORT 48LOB_TEMP_TABLE 49LOG 49LOGDATA 49LOGMECH 50NEW_PASSWORD 51PARTITION 51SESSIONS 52SP_SPL 52TMODE 52TNANO 52TSNANO 52TYPE 53USEXVIEWS 53

database connections 331DatabaseMetaData Methods 134databases 330dataDefinitionCausesTransactionCommit() 135dataDefinitionIgnoredInTransactions() 136DataSource Methods 189date function 335Date, Time, Timestamp Values and Time Zones 60DBS_PORT 42delete statements 331deleteRow() 214deletesAreDetected(int type) 136deregisterDriver(Driver driver) 192doesMaxRowSizeIncludeBlobs() 136Driver Requirements 22DriverManager Methods 191

EENCRYPTDATA 43execute() 200execute(String sql) 257execute(String sql, int autoGeneratedKeys) 258executeBatch() 257executeQuery() 200executeQuery(String sql) 260executeUpdate() 200executeUpdate(String sql) 260executeUpdate(String sql, int autoGeneratedKeys) 261External Stored Procedures 67

FfindColumn(String columnName) 214first() 215

GgetACCOUNT() 268

getAsciiStream( ) 108getAsciiStream(int columnIndex) 215getAsciiStream(String columnName) 215getAttributes(String catalog, String schemaPattern, String

typeNamePattern, String attributeNamePattern) 136getAutoCommit() 120getBestRowIdentifier(String catalog, String schema, string

table, int scope, boolean nullable) 138getBigDecimal(int columnIndex) 216getBigDecimal(int columnIndex, int scale) 216getBigDecimal(int parameterIndex) 111getBigDecimal(int parameterIndex, int scale) 111getBigDecimal(String columnName) 217getBigDecimal(String columnName, int scale) 217getBinaryStream( ) 106getBinaryStream(int columnIndex) 217getBinaryStream(String columnName) 218getBlob(int i) 218getBlob(String colName) 218getBoolean(int columnIndex) 219getBoolean(int parameterIndex) 112getBoolean(String columnName) 219getByte(int columnIndex) 219getByte(int parameterIndex) 112getByte(String columnName) 219getBytes(int columnIndex) 220getBytes(int parameterIndex) 112getBytes(long pos, integer length) 106getBytes(String columnName) 220getCatalog() 120getCatalogs() 139getCatalogSeparator() 140getCatalogTerm() 140getCharacterStream( ) 108getCharacterStream(int columnIndex) 220getCharacterStream(String columnName) 221getCharSet(), getCHARSET() 268getClob(int i) 221getClob(String colName) 221getColumnPrivileges(String catalog, String schema, String

tableName, String columnNamePattern) 140getColumns(String catalog, String schemaPattern, String

tableNamePattern, String columnNamePattern) 141getCOMPAT_DBS() 268getCOMPAT_GETSCHEMA() 268getCOMPAT_GETTABLE() 268getCOMPAT_ISAUTOINC() 269getCOMPAT_ISCURRENCY() 269getCOMPAT_ISDEFWRIT() 269getCOMPAT_ISREADONLY() 269getCOMPAT_ISSEARCH() 269getCOMPAT_ISSIGNED() 270getCOMPAT_ISWRITABLE() 270getConcurrency() 222


Index

getConnection() 143, 189, 198, 262, 270getConnection(java.lang.String username, java.lang.String

password) 270getConnection(String url) 192getConnection(String url, Properties info) 192getConnection(String url, String user, String password) 193getConnection(String username, String password) 189getCrossReference(String primaryCatalog, String

primarySchema, String primaryTable, String foreignCatalog, String foreignSchema, String foreignTable) 143

getDatabase(), getdatabase(), getDATABASE() 271getDatabaseMajorVersion() 145getDatabaseMinorVersion() 145getDatabaseProductName() 146getDatabaseProductVersion() 146getdatasourceName() 271getDate(int parameterIndex) 113getDate(int parameterIndex, Calendar cal) 113getDate(String columnIndex) 222getDate(String columnIndex, Calendar cal) 223getDate(String columnName) 222getDate(String columnName, Calendar cal) 223getDBS_PORT() 271getDefaultTransactionIsolation() 146getdescription() 271getDouble(int parameterIndex) 113getDouble(String columnName) 224getDoublle(int columnIndex) 223getDriver(String url) 193getDriverMajorVersion() 146getDriverMinorVersion() 147getDriverName() 147getDrivers() 193getDriverVersion() 147getDSName() 272getENCRYPTDATA() 272getExtraNameCharacters() 147getFetchDirection() 224getFetchRows() 272getFetchSize() 225getFloat(int columnIndex) 224getFloat(int parameterIndex) 113getFloat(String columnName) 225getGeneratedKeys() 262getHoldability() 121getIdentifierQuoteString() 148getIndexInfo(String catalog, String schema, String table,

boolean unique, boolean approximate) 148getInt(int columnIndex) 225getInt(int parameterIndex) 114getInt(String columnName) 225getLOB_SUPPORT() 272getLOB_TEMP_TABLE() 273, 308

getLobData() 114getLOG() 273getLOGDATA() 273getLoginTimeout() 132, 190, 194, 273getLOGMECH() 273getLogStream() 194getLogWriter() 132, 190, 274getLong(int columnIndex) 226getLong(int parameterIndex) 114getLong(String columnName) 226getMaxBinaryLiteralLength() 149getMaxCatalogNameLength() 150getMaxCharLiteralLength() 150getMaxColumnNameLength() 150getMaxColumnsInGroupBy() 150getMaxColumnsInIndex() 150getMaxColumnsInOrderBy() 151getMaxColumnsInSelect() 151getMaxColumnsInTable() 151getMaxConnections() 151getMaxCursorNameLength() 152getMaxFieldSize() 262getMaxIndexLength() 152getMaxProcedureNameLength() 152getMaxRows() 263getMaxRowSize() 152getMaxSchemaNameLength() 153getMaxStatementLength() 153getMaxStatements() 153getMaxTableNameLength() 153getMaxTablesInSelect() 154getMaxUserNameLength() 154getMetaData() 121, 201, 226getMoreResults() 263getMoreResults(int current) 263getNumericFunctions() 154getObject(int columnIndex) 226getObject(int parameterIndex) 114getObject(String columnName) 227getParameterClassName(int param) 197getParameterCount() 195getParameterMetaData() 201getParameterMode(int param) 197getParameterType(int param) 197getParameterTypeName(int param) 197getpassword() 274getPooledConnection() 133getPooledConnection(String username, String password)

133getportNumber() 274getPrecision(int param) 196getPrimaryKeys(String catalog, String schema, String table)

154getProcedureColumns(String catalog, String schemaPattern,


Index

String procedureNamePattern, String columnNamePattern) 155

getProcedures(String catalog, String schemaPattern, String procedureNamePattern) 157

getProcedureTerm() 157getQueryTimeout() 264getReference() 274getResultSet() 264getResultSetConcurrency() 265getResultSetHoldability() 158, 265getRow() 227getScale(int param) 196getSchemas() 158getSchemaTerm() 158getSearchStringEscape() 158getServerName() 275getShort(int columnIndex) 228getShort(int parameterIndex) 115getShort(String columnName) 228getSP_SPL() 275getspl() 275getSQLException() 131getSQLKeywords() 159getStatement() 228getString(int columnIndex) 228getString(int parameterIndex) 115getString(String columnName) 229getStringFunctions() 159getSubString(long pos, int length) 109getSystemFunctions() 159getTablePrivileges(String catalog, String schemaPattern,

String tableNamePattern) 159getTableTypes() 161getTime(int columnIndex) 229getTime(int columnIndex, Calendar cal) 230getTime(int parameterIndex) 115getTime(int parameterIndex, Calendar cal) 116getTime(String columnName) 229getTime(String columnName, Calendar cal) 230getTimeDateFunctions() 162getTimestamp(int columnIndex) 231getTimestamp(int columnIndex, Calendar cal) 231getTimestamp(int parameterIndex) 116getTimestamp(int parameterIndex, Calendar cal) 116getTimestamp(String columnName) 231getTimestamp(String columnName, Calendar cal) 232getTNANO() 275getTransactionIsolation() 121getTransactMode(), getTMODE 275getTSNANO() 276getType() 232getTypeInfo() 162getTypeMap() 122getUnicodeStream(int columnIndex) 233

getUnicodeStream(String columnName) 233getUpdateCount() 265getURL() 164getuser() 276getUserName() 165getUSEXVIEWS() 276getVersionColumns(String catalog, String schema, string

table) 165getWarnings() 122, 234, 265Glossary 345GOVERN= 43GROUP BY clauses 331

HHP-UX 22

Iindexes 331insertRow() 234insertsAreDetected(int type) 166isAfterLast() 235isBeforeFirst() 235isCatalogAtStart() 166isClosed() 122isFirst() 235isLast() 235isNullable(int param) 195isReadOnly() 122, 167isSigned(int param) 196

JJava 21

applications 24classes 26database connectivity 21, 24language 26programs 21

Java Development Kit 22Java External Stored Procedures 86java.sql.Blob 24Java.sql.CallableStatement 25java.sql.Clob 24java.sql.Connection JDBC interface 24java.sql.DatabaseMetaData JDBC interface 24java.sql.DataSource 24java.sql.DriverManager JDBC interface 24java.sql.ParameterMetaData 24java.sql.PreparedStatement JDBC interface 25java.sql.ResultSet JDBC interface 25java.sql.ResultSetMetaData JDBC interface 25java.sql.Statement JDBC interface 25javax.sql.ConnectionEventListener 25


Index

javax.sql.ConnectionPoolDataSource 25javax.sql.PooledConnection 25JDBC

architecture 26interface

list of 24JDBC Driver

Type 2 26JDBC FastExport 98JDBC FastLoad 96JDBC Monitor 100JdbcRowSetImpl 75JDK 22joins 332

KKRB5 49

Llast() 236LDAP 49length()

BLOB 106CLOB 109

LOB_SUPPORT 43LOB_TEMP_TABLE= 43LOG 43LOGDATA 43LOGMECH 43

Mmath functions 332metadata features and functions 329moveToCurrentRow() 236moveToInsertRow() 236multiple

result sets 332Multi-Statement Requests 67Multi-threading on AIX 5.1 74

NnativeSQL(String sql) 123NEW_PASSWORD= 43next() 237null values 332nullPlusNonNullIsNull() 167nullsAreSortedAtEnd() 167nullsAreSortedAtStart() 167nullsAreSortedHigh() 167nullsAreSortedLow() 168

OORDER BY clauses 332othersDeletesAreVisible(int type) 168othersInsertsAreVisible(int type) 168othersUpdatesAreVisible(int type) 169ownDeletesAreVisible(int type) 169ownInsertsAreVisible(int type) 169ownUpdatesAreVisible(int type) 169

PParameterMetaData Methods 195parameters

database connection 43PARTITION= 43PooledConnection Methods 198prepareCall(String sql) 123prepareCall(String sql, int resultSetType, int

resultSetConcurrency) 123PreparedStatement Methods 199prepareStatement(String sql) 124prepareStatement(String sql, int autogeneratedKeys) 127prepareStatement(String sql, int resultSetType, int

resultSetConcurrency) 127previous() 237printIn(String message) 194procedures 332product names 333product version numbers 3

QQuery Banding 37

syntax 39

RrefreshRow() 237registerDriver(Driver driver) 194registerOutParameter(int parameterIndex, int sqlType) 117registerOutParameter(int parameterIndex, int sqlType, int

scale) 117registerOutParameter(int parameterIndex, int sqlType,

String typename) 118relative(int rows) 238removeConnectionEventListener(ConnectionEventListener

listener) 199ResultSet Methods 212rollback() 128rowDeleted() 238rowInserted() 238rows 333RowSet

rows 75rowUpdated() 239


Index

Sschemas 333SELECT statements 333Session Defaults Warning 54Session Parameters 54Session Time Zone 63SESSIONS= 43setACCOUNT(String accountId) 276setAsciiStream(int parameterIndex, InputStream x, int

length) 201setAsciiStream(long pos) 110setAutoCommit(boolean autoCommit) 128setBigDecimal(int parameterIndex, BigDecimal x) 202setBinaryStream(int parameterIndex, InputStream x, int

length) 202setBinaryStream(long pos) 107setBlob(int i, Blob x) 203setBoolean(int parameterIndex, boolean x) 203setByte(int parameterIndex, byte x) 203setCatalog(String catalog) 129setCharacterStream(int parameterIndex, Reader reader, int

length) 204setCharacterStream(long pos) 110setCharSet(java.lang.String CharSet),

setCHARSET(java.lang.String CharSet) 277setClob(int i, Clob x) 204setCOMPAT_DBS() 277setCOMPAT_GETSCHEMA() 277setCOMPAT_GETTABLE() 277setCOMPAT_ISAUTOINC() 277setCOMPAT_ISCURRENCY() 278setCOMPAT_ISDEFWRIT() 278setCOMPAT_ISREADONLY() 278setCOMPAT_ISSEARCH() 278setCOMPAT_ISSIGNED() 278setCOMPAT_ISWRITABLE() 279setDatabase(java.lang.String database),

setdatabase(java.lang.String database), setDATABASE(java.lang.String database) 279

setdatasourceName(java.lang.String datasourceName) 279setDate(int parameterIndex, Date x) 205setDate(int parameterIndex, Date x, Calendar cal) 205setDBS_PORT(java.lang.String dbsport) 279setdescription(java.lang.String description) 279setDouble(int parameterIndex, double x) 205setDSName(java.lang.String DSName) 280setENCRYPTDATA(java.lang.String encryptData) 280setFetchRows(java.lang.String FetchRows) 280setFloat(int parameterIndex, float x) 206setInt(int parameterIndex, int x) 206setLOB_SUPPORT(java.lang.String lobSupport) 280setLOB_TEMP_TABLE(java.lang.String lobTempTable) 309setLOB_TEMP_TABLE(java.lang.String) 281

setLOG(java.lang.String lobSupport) 281setLOGDATA(java.lang.String logData) 281setLoginTimeout(int seconds) 133, 190, 194, 282setLOGMECH(java.lang.String LogMech) 282setLogStream(PrintStream out) 195setLogWriter(java.io.PrintWriter out) 282setLogWriter(PrintWriter out) 134, 191setLong(int parameterIndex, long x) 206setMaxFieldSize(int max) 266setMaxRows(int max) 266seTMODE(java.lang.String TransactMode) 283setNull(int parameterIndex, int sqlType) 206setNull(int paramIndex, int sqlType, String typeName) 207setObject(int parameterIndex, Object x) 208setObject(int parameterIndex, Object x, int targetSqlType)

208setObject(int parameterIndex, Object x, int targetSqlType, int

scale) 208setpassword(java.lang.String password) 282setportNumber(java.lang.String portNumber) 282setQueryTimeout(int seconds) 266setServerName(java.lang.String serverName) 283setShort(int parameterIndex, short x) 209setSP_SPL(java.lang.String splVal) 283setSpl(java.lang.String spl) 283setString(int parameterIndex, String x) 209setString(long pos, String str) 109setString(long pos, String str, int offset, int len) 110setTime(int parameterIndex, Time x) 210setTime(int parameterIndex, Time x, Calendar cal)) 210setTimestamp(int parameterIndex, Timestamp x) 210setTimestamp(int parameterIndex, Timestamp x, Calendar

cal) 211setTNANO(java.lang.String tnanoVal) 284setTransactionIsolation(int level) 129setTransactMode(java.lang.String TransactMode),

seTMODE(java.lang.String TransactMode) 284setTSNANO(java.lang.String tsnanoVal) 284setTypeMap(Map>map) 130setUnicodeStream(int parameterIndex, InputStream x, int

length) 211setuser(java.lang.String user) 284setUseXVIEWS(java.lang.String useXviews) 284Slow logon on Linux 326software releases

supported 3SP_SPL 43SQL and Java data mapping 343SQL statements 334Statement Methods 255Stored Procedure Dynamic Result Set 95storesLowerCaseIdentifiers() 170storesLowerCaseQuotedIdentifiers() 170storesMixedCaseIdentifiers() 170


Index

storesMixedCaseQuotedIdentifiers() 171storesUpperCaseIdentifiers() 171storesUpperCaseQuotedIdentifiers() 171strings 334subqueries 335Sun Solaris SPARC 22supportsAlterTableWithAddColumn() 172supportsAlterTableWithDropColumn() 172supportsANSI92EntryLevelSQL() 172supportsANSI92FullSQL() 172supportsANSI92IntermediateSQL() 173supportsBatchUpdates() 173supportsCatalogsInDataManipulation() 173supportsCatalogsInIndexDefinitions() 173supportsCatalogsInPrivilegeDefinitions() 174supportsCatalogsInProcedureCalls() 174supportsCatalogsInTableDefinitions() 174supportsColumnAliasing() 174supportsConvert() 175supportsConvert(int fromType, int toType) 175supportsCoreSQLGrammar() 175supportsCorrelatedSubqueries() 176supportsDataDefinitionAndDataManipulationTransactions(

) 176supportsDataManipulationTransactionsOnly() 176supportsDifferentTableCorrelationNames() 176supportsExpressionsInOrderBy() 177supportsExtendedSQLGrammar() 177supportsFullOuterJoins() 177supportsGetGeneratedKeys() 177supportsGroupBy() 178supportsGroupByBeyondSelect() 178supportsGroupByUnrelated() 178supportsIntegrityEnhancementFacility() 178supportsLikeEscapeClause() 179supportsLimitedOuterJoins() 179supportsMinimumSQLGrammar() 179supportsMixedCaseIdentifiers() 180supportsMixedCaseQuotedIdentifiers() 180supportsMultipleOpenResults() 180supportsMultipleResultSets() 180supportsMultipleTransactions() 181supportsNonNullableColumns() 181supportsOpenCursorsAcrossCommit() 181supportsOpenCursorsAcrossRollback() 181supportsOpenStatementsAcrossCommit() 182supportsOpenStatementsAcrossRollback() 182supportsOrderByUnrelated() 182supportsOuterJoins() 182supportsPositionedDelete() 183supportsPositionedUpdate() 183supportsResultSetConcurrency(int type, int concurrency)

183supportsResultSetHoldability(int holdability) 184

supportsResultSetType(int type) 184supportsSchemasInDataManipulation() 184supportsSchemasInIndexDefinitions() 184supportsSchemasInPrivilegeDefinitions() 185supportsSchemasInProcedureCalls() 185supportsSchemasInTableDefinitions() 185supportsSelectForUpdate() 185supportsStoredProcedures() 186supportsSubqueriesInComparisons() 186supportsSubqueriesInExists() 186supportsSubqueriesInIns() 186supportsSubqueriesInQuantifieds() 187supportsTableCorrelationNames() 187supportsTransactionIsolationLevel(int level) 187supportsTransactions() 188supportsUnion() 188supportsUnionAll() 188system functions 335

Ttable correlation names 335tables 335TD1 49TD2 49Teradata 26Teradata Database Macros 67Teradata JDBC Driver 26Teradata terminology 335TeraDataSource Methods 267three-tier architecture 21TIME and TIMESTAMP INOUT Parameters 66time function 335TMODE 43transactions 335troubleshooting 311truncate(long len) 108, 111TSNANO 43TYPE= 43types) 160, 163

UUpdatable Result Set 91UPDATE statements 336updateArray(int columnIndex, Array x) (JDBC 3.0) 304updateArray(String columnName, Array x) (JDBC 3.0) 304updateAsciiStream(int columnIndex, InputStream x, int

length) 239updateAsciiStream(String columnName, InputStream x, int

length) 239updateBigDecimal(int columnIndex, BigDecimal x) 240updateBigDecimal(String columnName, BigDecimal x) 240updateBinaryStream(int columnIndex, InputStream x, int

length) 241


Index

updateBinaryStream(String columnName, InputStream x, int length) 241

updateBlob(int columnIndex, Blob x) 241updateBlob(String columnName, Blob x) 242updateBoolean(int columnIndex, boolean x) (JDBC 2.0) 304updateBoolean(String columnName, boolean x) (JDBC 2.0)

304updateByte(int columnIndex, byte x) 242updateByte(String columnName, byte x) 243updateCharacterStream(int columnIndex, Reader x, int

length) 244updateCharacterStream(String columnName, Reader x, int

length) 244updateClob(int columnIndex, Clob x) 245updateClob(String columnName, Clob x) 245updateDate(int columnIndex, Date x) 245updateDate(String columnName, Date x) 246updateDouble(int columnIndex, double x) 246updateDouble(String columnName, double x) 247updateFloat(int columnIndex, float x) 247updateFloat(String columnName, float x) 247updateInt(int columnIndex, int x) 248updateInt(String columnName, int x) 248updateLong(int columnIndex, long x) 249updateLong(String columnName, long x) 249updateNull(int columnIndex) 249updateNull(String columnName) 250updateObject(int columnIndex, Object x) 250updateObject(int columnIndex, Object x, int scale) 250updateObject(String columnName, Object x) 251updateObject(String columnName, Object x, int scale) 251updateRef(int columnIndex, Ref x) (JDBC 3.0) 305updateRef(String columnName, Ref x) (JDBC 3.0) 305updateRow() 252updatesAreDetected(int type) 188updateShort(int columnIndex, short x) 252updateShort(String columnName, short x) 252updateString(int columnIndex, String x) 253updateString(String columnName, String x) 253updateTime(int columnIndex, Time x) 253updateTime(String columnName, Time x) 254updateTimestamp(int columnIndex, Timestamp x) 254updateTimestamp(String columnName, Timestamp x) 255user names 335, 336User-Defined Functions 67usesLocalFilePerTable() 189usesLocalFiles() 189USEXVIEWS= 43USEXViews=ON Performance 325

Vversion numbers 3

WwasNull() 118Windows 22

Xx) 204, 243


Teradata JDBC Driver User Guide

Documents

Transcript of Teradata JDBC Driver User Guide