TTU8.2 TeraJDBC.03.04.00.06 Readme

tnolan — Thu, 09 Apr 2009 12:38:10 GMT

Teradata JDBC Driver 3.4.0.6

Part of the Teradata Tools and Utilities 8.2 product suite

System Requirements
-------------------

This release of the Teradata JDBC Driver requires JDK/JRE 1.4, 5.0, or 6.0.

Note that IBM WebSphere Application Server 5.0 is not supported, because
WebSphere 5.0 uses JDK 1.3.1.

This release of the Teradata JDBC Driver supports Teradata Database V2R5.0,
V2R5.1, V2R6.0, V2R6.1, V2R6.2, 12.0, and 13.0.

What's New
----------

- User Defined Functions (UDFs), User Defined Methods (UDMs), Java Stored
Procedures, and other External Stored Procedures (XSPs) can now be created
from resources on the client classpath.

- Teradata Database 13.0 supports Java User-Defined Functions (UDFs).

- Support for Java Stored Procedures with Teradata Database 12.0 and later.

- JDBC FastLoad enables efficient loading of large amounts of data into an
empty destination table.

- JDBC Monitor provides a method for accessing and using standard performance
monitoring and production control functions contained within the Teradata
Database.

- Teradata Database TIME values may be defined with as many as six fractional
digits, but java.sql.Time objects are capable of millisecond precision (three
fractional digits at most). Previously, fractional seconds of TIME values were
not returned. Now, fractional seconds of TIME values are returned from the
database by the following methods, with truncation to millisecond precision,
if necessary:
- ResultSet.getTime
- ResultSet.getObject
- CallableStatement.getTime
- CallableStatement.getObject

- Support for the SQL data type BIGINT with Teradata Database V2R6.2 and later.

- PreparedStatement.setLong
- PreparedStatement.setObject with java.lang.Long
- ResultSet.getLong
- ResultSet.getObject returns java.lang.Long for BIGINT

- Support for up to 38 digits of precision with the DECIMAL data type with
Teradata Database V2R6.2 and later.

- Support for JDBC 3.0 ParameterMetaData interface and APIs with Teradata
Database V2R6.2 and later. This includes support of the following methods:

- PreparedStatement.getParameterMetaData()
- ParameterMetaData.getParameterClassName(int)
- ParameterMetaData.getParameterCount()
- ParameterMetaData.getParameterMode(int)
- ParameterMetaData.getParameterType(int)
- ParameterMetaData.getParameterTypeName(int)
- ParameterMetaData.getPrecision(int)
- ParameterMetaData.getScale(int)
- ParameterMetaData.isNullable(int)
- ParameterMetaData.isSigned(int)

- Support the retrieval of auto-generated keys from INSERT statements. This
includes support of the following methods:

- Connection.prepareStatement(String sql, int autoGeneratedKeys)
- Connection.prepareStatement(String sql, int[] columnIndexes)
- Connection.prepareStatement(String sql, String[] columnNames)
- 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)
- Statement.getGeneratedKeys()

- User Defined Type (UDT) metadata information is now returned by
DatabaseMetaData methods for Teradata Database V2R6.1 and later UDTs.

- More accurate information is now provided from the ResultSetMetadata
getColumnTypeName method with Teradata Database V2R6.2 and later.

Accurate type name provided with Type name provided with earlier
Teradata Database V2R6.2 and later Teradata Database releases
---------------------------------- -------------------------------
BYTEINT TINYINT
BYTE BINARY
VARBYTE VARBINARY
TIME WITH TIME ZONE TIME
TIMESTAMP WITH TIME ZONE TIMESTAMP
INTERVAL YEAR CHAR
INTERVAL YEAR TO MONTH CHAR
INTERVAL MONTH CHAR
INTERVAL DAY CHAR
INTERVAL DAY TO HOUR CHAR
INTERVAL DAY TO MINUTE CHAR
INTERVAL DAY TO SECOND CHAR
INTERVAL HOUR CHAR
INTERVAL HOUR TO MINUTE CHAR
INTERVAL HOUR TO SECOND CHAR
INTERVAL MINUTE CHAR
INTERVAL MINUTE TO SECOND CHAR
INTERVAL SECOND CHAR

Accurate type name information is also provided from the
ParameterMetaData getParameterTypeName method, which is available
with Teradata Database V2R6.2 and later.

- More accurate information is now provided for INTERVAL values from the
ResultSetMetadata getColumnType method with Teradata Database V2R6.2 and later.
For the INTERVAL types listed below, the ResultSetMetadata getColumnType
method returns java.sql.Types.OTHER with Teradata Database V2R6.2 and later.
ResultSetMetadata getColumnType returns java.sql.Types.CHAR with earlier
Teradata Database releases.

- INTERVAL YEAR
- INTERVAL YEAR TO MONTH
- INTERVAL MONTH
- INTERVAL DAY
- INTERVAL DAY TO HOUR
- INTERVAL DAY TO MINUTE
- INTERVAL DAY TO SECOND
- INTERVAL HOUR
- INTERVAL HOUR TO MINUTE
- INTERVAL HOUR TO SECOND
- INTERVAL MINUTE
- INTERVAL MINUTE TO SECOND
- INTERVAL SECOND

The ParameterMetaData getParameterType method, which is available only
with Teradata Database V2R6.2 and later, also returns java.sql.Types.OTHER for
the INTERVAL types listed above.

- DatabaseMetaData getDatabaseProductVersion returns a string that begins with
Teradata Database and that includes V2R for supported database releases prior to
12.0, but does not include V2R for 12.0.

- DatabaseMetaData getDatabaseMajorVersion returns 12 for Teradata Database 12.0
and returns 2 for supported V2R6.x releases prior to 12.0.

- DatabaseMetaData getDatabaseMinorVersion returns 0 for Teradata Database 12.0
and returns 6 for supported V2R6.x releases prior to 12.0.

Release Notes
-------------

This section highlights issues that you should be aware of when upgrading to
the 3.4.0.6 release of the Teradata JDBC Driver. Please refer to the Teradata
JDBC Driver User Guide for more information about the driver.

This release includes changes to address the following DRs:

DR 131684 add JDBC FastLoad support for EJB transactions with multiple PreparedStatements

This release includes changes to address the following DRs, originally included
in release 3.4.0.5:

DR 131418 support DBS_PORT connection parameter with TYPE=FASTLOAD and FASTEXPORT

This release includes changes to address the following DRs, originally included
in release 3.4.0.4:

DR 115170 avoid sending Continue/Cancel with RPO=S if Resp/BigResp was sent and EndRequest was received
DR 121130 getParameterMetaData() fails with multi-statement macro and multi-statement requests
DR 121952 avoid SQLException from Statement.close if connection is already closed
DR 122425 JDBC Driver sent Abort request message for completed request while subsequent ET request was in progress

This release includes changes to address the following DRs, originally included
in release 3.4.0.3:

DR 96980 GtwConfigParcel could fail when new gateway features added
DR 97103 improve correlation of TDSession objects with log messages
DR 98176 avoid sending cancel request if RESP/BIGRESP is used and ENDREQUEST received
DR 100090 modify driver to avoid DBS crash when using LOB_SUPPORT=off and large result set
DR 106708 add LOG=TIMING measurements
DR 112978 accommodate 12m DBS DR 110445 change to DBC.Columns.ColumnName value 'RETURN' is now 'RETURN0'
DR 114154 CallableStatement batch support to execute CALL sequentially to work within DBS restriction of single CALL at a time
DR 114470 TTU 8.1 Teradata JDBC Driver 3.3 to support TD 12.0 (backport DR 108390)
DR 115269 improve JDBC FastLoad exception handling of PreparedStatement.executeBatch and Connection.rollback
DR 115914 Customer gets errors on jdbc connection attempts originating from TdgssConfigApi (shipped with tdgssjava 6.2.2.19)
DR 118571 WebSphere DataSource custom property CHARSET not working for PreparedStatement.setString non-ASCII characters
DR 118851 Java TDGSS_6.1.1.93_GCA fails against a 12.00.00.04 DBS for Kerberos (shipped with tdgssjava 6.2.2.22)
DR 119000 ResultSetMetaData.isAutoIncrement should return true for identity column
DR 119320 Add ActivityType 123 for REPLACE UDF
DR 120597 force connection failure for invalid response message header
DR 120929 DatabaseMetaData.getColumns returns incorrect information when using UTF8 session character set

This release includes changes to address the following DRs, originally included
in release 3.4.0.2:

DR 107900 support ambiguous data type for ResultSet columns with SIP-enabled prepare of select-list parameter markers
DR 110436 provide consistency for ACCOUNT connection parameter
DR 112806 PreparedStatement: treat Types.FLOAT & Types.REAL as Types.DOUBLE in setObject and preserve float precision in setFloat
DR 113069 executeQuery may return error 1182 if URL param CLIENT_CHARSET is set and the DBS is running V2R6.1 or earlier

This release includes changes to address the following DRs, originally included
in release 3.4.0.1:

DR 100351 support the MONITOR partition
DR 100352 support the DBCCONS partition
DR 103835 return actual update count for MERGE insert, MERGE update, and MERGE mixed SQL statements
DR 104893 provide high-level JDBC FastLoad connection for automatic management of multiple low-level connections
DR 106917 CallableStatement.getObject fails for INOUT Clob parameter when input value was sent to 6.2 DBS as VARCHAR
DR 108500 ResultSetMetaData.getSchemaName to return database name with Teradata Database 6.2
DR 108926 enable JDBC Load and Export sessions to be identifiable by TASM
DR 109424 Make Elicit File protocol work with the JDBC driver and 64 bit Windows DBS
DR 109760 Change sample program T21400JD to demonstrate call to corrected UDF Judf01
DR 110059 Return correct values for getColumnDisplaySize for temporal data types
DR 110112 provide pre-V2R6.2 high-level JDBC FastLoad connection for automatic management of multiple low-level connections
DR 111254 JDBC FastLoad support for BIGINT and large DECIMAL, JDBC FastLoad support for EJB transactions

This release includes changes to address the following DRs, originally included
in release 3.4.0.0:

DR 58028 JDBC 3.0 ParameterMetaData methods.
DR 94704 RFC: Support the retrieval of auto-generated keys from an insert statement.
DR 95968 Add support for BIGINT and DECIMAL(38).
DR 96457 certify JDBC driver with Teradata Database on Windows x64.
DR 96467 update application server documentation for TTU 8.2 / JDBC 3.4 release.
DR 97514 ResultSetMetaData methods to use actual database values rather than COMPAT_xxx.
DR 97554 provide User Defined Type (UDT) information from DatabaseMetaData methods.
DR 99270 certify Solaris 10 64-bit on AMD64 with JDK 5.0 32-bit & 64-bit.
DR 99337 certify Red Hat AS 4.0 64-bit on AMD64 with JDK 5.0 32-bit & 64-bit.
DR 104782 setMaxFieldSize(small value) causes subsequent exceptions from getDate for ANSI date, getTime, and getTimestamp

This release includes changes to address the following DRs, originally included
in release 3.3.0.4:

DR 87473 getColumnDisplaySize returns number of bytes for Character columns
DR 104043 DatabaseMetaData.getTableTypes should return ResultSet ordered by TABLE_TYPE
DR 108939 User Guide must say setAsciiStream/setCharacterStream are not supported for binding data to BYTE or VARBYTE destinations
DR 109213 Encryption problem message may not display an argument
DR 109231 TYPE_SCROLL_INSENSITIVE used with execute method causes subsequent getMoreResults to hang or throw exception
DR 109294 Statement.executeBatch must clear the batch
DR 109615 DatabaseMetaData.getColumns throws exception

This release includes changes to address the following DRs, originally included
in release 3.3.0.3:

DR 101277 enable UDFs, XSPs, and UDMs to be created from resources on client using JDBC
DR 106841 improve SQLException from executeXXX when InputStream bound with setXxxStream is closed before executeXXX
DR 107345 TTU 8.1: Getting NullPointerException from tdgssjava (shipped with tdgssjava 6.2.0.4)
DR 107536 CallableStatement executeUpdate: error 6906 (iterated request disallowed) occurs after error 1184 (invalid parameter)
DR 107987 workaround for Java 2 security Sun Bug ID 6205384 - SocketPermission ignored for unknown host
DR 108260 restrict printed characters to 7-bit ASCII in debug log message dumps

This release includes changes to address the following DRs, originally included
in release 3.3.0.2:

DR 101381 scalar functions (TIMESTAMPADD, TIMESTAMPDIFF) need SQL_TSI_HOUR
DR 103411 Add support for inserting NULL, Unicode characters, and remaining data types to be supported by JDBC FastLoad
DR 103740 with CHARSET=UTF16, PreparedStatement.executeBatch should accept TIMESTAMP values w/varying number of fractional digits
DR 103772 send millisecond portion of java.sql.Time values to DBS with omitted TNANO connection parameter, & with TNANO=1 or more
DR 104020 getTime & getObject methods: return TIME values w/fractional seconds as java.sql.Time values w/milliseconds precision
DR 104370 throw SQLException when DBS says 'n' characters are coming but really only sends a fraction of 'n'
DR 104825 insert trailing zeros before TIME ZONE for TIME or TIMESTAMP values with varied precisions and no TNANO or TSNANO
DR 105073 Modify setBinary/Ascii/CharacterStream methods to determine when to send Deferred LOB/VARCHAR/VARBYTE values
DR 105265 Ensure driver is registered only once with DriverManager
DR 105633 non-prepared Statement.executeBatch is limited to fewer statements with V2R6.x than with V2R5.x
DR 105834 PreparedStatement.setAsciiStream drops trailing spaces
DR 106091 stream/reader from Clob.getAsciiStream/getCharacterStream should remain valid for Connection lifetime
DR 106115 Clob.getSubString truncates data when a multi-byte character set is used
DR 106116 cannot execute more than once a CallableStatement with OUT parameters on V2R6.0 and earlier
DR 106118 Incorrect data is returned if the ResultSet is closed while reading a Blob
DR 106136 A finalize statement needs to be implemented for LobStatement
DR 106243 ResultSet.getAsciiStream returns invalid data on mainframe z/OS USS

This release includes changes to address the following DRs, originally included
in release 3.3.0.1:

DR 58030 RFC: JDBC3.0: DatabaseMetaData methods (New in JDBC 3.0)
DR 58032 RFC: JDBC3.0: DatabaseMetaData methods (MODIFIED from JDBC2.0)
DR 96462 certify Teradata JDBC Driver with SAP Web Application Server 6.40
DR 97255 document Teradata JDBC Driver configuration with SAP Universal Data Connector
DR 98047 DatabaseMetaData.getProcedures returns ResultSet that differs from API javadoc
DR 98048 DatabaseMetaData.getProcedureColumns returns ResultSet differs from API javadoc
DR 98050 DatabaseMetaData.getColumns fails when a database name contains a quote
DR 98051 PreparedStatement.setCharacterStream and setAsciiStream drop trailing spaces
DR 98053 DatabaseMetaData.getColumns returns RS w/RSMD.getColumnTypeName null for all columns
DR 98055 DatabaseMetaData.getPrimaryKeys returns ResultSet that differs from API javadoc
DR 98855 setBigDecimal throw DataTruncation for >18 integral digits; & round frac. digits
DR 99578 implement JDBC 1.0 DatabaseMetaData methods
DR 99720 low-level FastLoad connection with PreparedStatement batch update
DR 99760 AppServer-HowTo HTML doc needs modification for JRun datasource definition
DR 100404 use 24-hour values rather than 12-hour for JDBC driver log message timestamps
DR 100902 automatic close of garbage-collected Statement and ResultSet objects
DR 101115 PreparedStatement.setLong to throw DataTruncation when long value has 19 digits
DR 101767 ResultSet.absolute fails for negative row numbers
DR 102405 thread deadlock for concurrent calls to Statement.executeQuery & ResultSet.close
DR 103173 securerandom.source and/or java.security.egd dont work in 1.5.0_05 (tdgssjava 6.1.0.18)

This release includes changes to address the following DRs, originally included
in release 3.3.0.0:

DR 50036 RFC: JDBC1.0: Escape syntax support
DR 83850 RFC: JDBC2.0: PreparedStatement.getMetaData()
DR 89445 ResultSetMetaData.getColumnClassName should return class name, not null
DR 89449 Need to add COMPAT_xxx URL parameters for three ResultSetMetaData methods
DR 91121 disallow specification of a username and password when LDAP or Kerberos is used
DR 91636 Implement Denial of services feature as documented in TRP 541-0004949
DR 91796 update application server documentation for TTU 8.1 / JDBC 3.3 release
DR 92136 Enable transaction isolation level TRANSACTION_READ_UNCOMMITTED
DR 92143 DatabaseMetaData: obtain DBS limits from Config Response parcel
DR 92146 obtain DBS version/release from new feature item in Config Response parcel
DR 92212 testing: support V2R6.1 feature: external security clause for sprocs/UDFs
DR 92216 J2SE 5.0 (JDK 1.5) certification
DR 92219 Solaris 10/SPARC 32-bit and 64-bit certification
DR 92221 AIX 5.3 32-bit and 64-bit certification
DR 92222 SuSE Linux 32-bit certification
DR 92223 WebSphere 6.0 Certification
DR 92228 WebLogic 8.1 with both Sun JVM and JRockit JVM Certification
DR 92230 ColdFusion MX 6.1 Certification
DR 92231 JBoss 4.0 Certification
DR 92449 Implement UTF16 support for tdgss as documented in TRP 541-0005061
DR 92450 eliminate HELP PROCEDURE before calls to sprocs with OUT params
DR 92648 translate new JDBC 3.3 error messages into Japanese
DR 92693 TTU 8.1 / JDBC 3.3 User Guide: no support for V2R6.1 User Defined Types (UDTs)
DR 92736 Include info for the sample files in samples.jar for MVS in the JDBC Users Guide
DR 92919 DatabaseMetaData APIs should support patterns containing single quotes
DR 93293 Single quote in comment throws invalid error via JDBC
DR 93890 getHoldability APIs should return HOLD_CURSORS_OVER_COMMIT, not throw exception
DR 94311 testing: support V2R6.1 feature: activity count overflow warning
DR 94816 JDBC User Guide section "Improving Performance": list use of PreparedStatement
DR 95061 TTU 8.1 JDBC User Guide addition: CALL statements not using Escape Syntax
DR 95334 corrections for JDBC User Guide Appendix D - Data Type Conversions
DR 95741 JDBC User Guide changes to Chapter 1 section "Support for Internationalization"
DR 95961 database error in TERA mode with autocommit off incorrectly turns autocommit on
DR 95969 incomplete update count array in TERA mode w/autocommit off for failed batch req
DR 96149 Provide warning message from SuccessParcel to Statement.getWarnings method
DR 96253 Package TdgssUserConfigFile.xml in a jar file
DR 96653 Revamp JDBC Connection Pool Orange Book as HTML docs in appserver-howto.jar
DR 96824 JDBC User Guide change: discontinued CASE_SENSITIVE connection parameter
DR 96914 TTU 8.1 JDBC User Guide addition: new section: "Planned Future Changes"
DR 97038 TTU 8.1 JDBC User Guide addition: new section: LogonSource Format
DR 97290 Large batch requests using LOB params, may fail to process all requests in batch
DR 97428 HPUX 11.23/Itanium-2 32-bit and 64-bit certification
DR 97550 corrections for COMPAT_GETSCHEMA and COMPAT_GETTABLE information in JDBC UG
DR 97585 TTU 8.1 JDBC User Guide: new contents for section: Response Limit Exceeded Error
DR 97723 fix sample programs T21301JD, T21302JD to use ConnectionPoolDataSource correctly
DR 97747 TTU8.1 JDBC Users Guide: need to add an explanation for DBS error 3926
DR 97816 DatabaseMetaData.getMaxStatements should return 16, not 1048500
DR 98089 TTU 8.1 JDBC User Guide changes: miscellaneous "Supported Methods" changes
DR 98110 TTU 8.1 JDBC UG: refer readers to appserver documentation in download package

This release includes changes to address the following DRs, originally included
in release 3.2.0.3:

DR 56133 Implement JDBC1.0 APIs DatabaseMetaData.getExportedKeys and getImportedKeys
DR 90532 PreparedStatement.setBigDecimal throws java.lang.ArithmeticException exception
DR 92609 Wrong value in the database when PreparedStatement.setBigDecimal is being used
DR 97022 PreparedStatement.executeBatch throws ClassCastException: java.util.ArrayList

This release includes changes to address the following DRs, originally included
in release 3.2.0.2:

DR 84637 RFC: Statement.execute() should not retrieve all the data before returning
DR 87267 JDBC error: ('0A'X) is not a valid Teradata SQL token
DR 89201 UT: NullPointerException for unbound prep stmt parameter (should be SQLException)
DR 90136 JDBC throws parameter error when ? occurs in 2nd quoted string
DR 91353 setNull does not work correctly when the sql type is a Boolean
DR 91951 CLIENT_CHARSET connection parameter
DR 92125 add LOG=TIMING connection parameter
DR 92294 JDBCException when creating UDF: Function 'Judf01' already exists
DR 92697 getTables() to get the table type, the resultset contains "T" instead of Table
DR 92918 map replication error code 6699 to SQLState 40001 (transaction rolled back)
DR 93054 Logon fails with 8019 from jdbc when ldap mechanism is used
DR 93156 Inserting null decimal datatypes not working when URL LOB_SUPPORT=OFF
DR 93157 Using PreparedStatement.setObject(int, Object) to set null value throws NPE
DR 93549 Type 4 driver Get-column-by-name from 2nd RS throws "column not found" exception
DR 94407 do not include class files in samples.jar
DR 94605 Statement.addBatch fails when SQL contains trailing space
DR 94923 row fetching too slow with >1000 rows in result set using 1MB response messages
DR 94970 PreparedStatement.getResultSet should return null for non-RS-returning statement
DR 95078 interoperability issue when Connection.close called while query is in progress
DR 95302 provide SQLState for V2R6.0.x retryable error codes 3231 and 3319
DR 95828 CLIENT_CHARSET DataSource property
DR 95943 DatabaseMetaData.getSQLKeywords for V2R5.0, V2R5.1, and V2R6.0

This release includes changes to address the following DRs, originally included
in release 3.2.0.1:

DR 85852 TeraLocalPrepared/CallableStatement.getResultSetType and other incorrect methods

This release includes changes to address the following DRs, originally included
in release 3.2.0.0:

DR 57921 RFC: JDBC Certification on Windows 2003 Server (32-bit/64-bit)
DR 63499 RFC: Make changes to files for JDBC to use JDK 1.4
DR 68162 RFC: JDBC2.0: PreparedStatement batch updates
DR 68625 RFC: Add more sample files to JDBC package
DR 68837 RFC: V2R6: 1 MB/APH Responses
DR 68844 RFC: V2R6: Security Improvements and Extensions
DR 69061 RFC: JDBC2.0: Scrollable ResultSets (bi-directional cursor positioning)
DR 84400 RFC: Certify Sun Microsystems RowSet implementation with JDBC driver
DR 84635 RFC: remove jdbc4.properties file - use connection attributes
DR 84672 RFC: Remove platform packaging for JDBC Type 4 driver
DR 84853 RFC: Test JDBC Driver with WebSphere 5.1
DR 84854 RFC: Test JDBC driver with WebLogic 8.1
DR 85123 RFC: JDBC Certification on 64-bit Linux
DR 85393 RFC: Remove Type 3 driver from product
DR 85397 RFC: Update values for DatabaseMetaData functions for V2R6
DR 85434 createStatement: Downgrade RS type and concurrency, and generate SQLWarning
DR 85536 RFC: Enable Type 4 driver to be built on Solaris
DR 85980 RFC: remove sample applets
DR 85981 DatabaseMetaData.getIndexInfo() is not implemented correctly
DR 86049 JDBC was not handling nulls in where clauses correctly in releases 3.1 & earlier
DR 86456 RFC: support LOBs as stored procedure output parameters
DR 86471 TRANSACTION_READ_UNCOMMITTED(1) is not supported
DR 87018 ResultSet.getConcurrency should return CONCUR_READ_ONLY
DR 87512 various ResultSetMetaData methods throw exceptions
DR 88400 RCI: Null Pointer dereference in ParcelFactory.java
DR 88403 RCI: Null Pointer Dereference in Statement.java
DR 88405 RCI: Resource leak of FileInputStream
DR 88409 RCI: Resource Leak ResultSets not being closed
DR 88581 Null Pointer exception in TDGSS interface code
DR 88763 Deprecate TeraStatement.getSpl and setSpl methods for TTU 8.0
DR 89173 STV: Statement.getXXX and PrepStmt.setXXX conversions must match User Guide

Troubleshooting Topics
----------------------

TIME and TIMESTAMP stored procedure parameters with V2R5.1 and UTF16
--------------------------------------------------------------------

The UTF16 session character set was introduced with Teradata Database V2R5.1,
but V2R5.1 does not support using the UTF16 session character set when
calling a stored procedure with question-mark parameters corresponding to
TIME and/or TIMESTAMP stored procedure parameters. The following exception
may be thrown:

ErrorCode=5404 SQLException: [NCR] [Teradata DBMS] : Datetime field overflow.

Solution:

Use a session character set other than UTF16 when using V2R5.1 and calling
stored procedures with TIME and/or TIMESTAMP parameters, or use Teradata
Database V2R6.0 or later releases, which do not have this limitation.

TNANO connection parameter now required with TIME(0) through TIME(2) columns
----------------------------------------------------------------------------

This release provides behavior originally introduced for JDBC DR 103772
("send millisecond portion of java.sql.Time values to DBS when TNANO
connection parameter is specified"). Using the PreparedStatement setTime
or setObject methods to insert java.sql.Time values into TIME(0) through
TIME(2) destination columns may throw the following exception:

ErrorCode=6758 SQLException: [NCR] [Teradata DBMS] : Invalid time.

Solution:

Specify the connection parameter TNANO=0, TNANO=1, or TNANO=2 as appropriate
for your destination TIME columns. You must specify a TNANO= value that
corresponds to the fewest fractional digits of all your destination TIME
columns. The Teradata JDBC Driver will limit the fractional seconds of all
TIME values sent to the database to what is specified by the TNANO connection
parameter.

Error 5666 when using PreparedStatement.setXxxStream with BYTE/CHAR/VARBYTE/VARCHAR column
------------------------------------------------------------------------------------------

This release provides behavior originally introduced for JDBC DR 105073
("Modify setBinary/Ascii/CharacterStream methods to determine when to send
Deferred LOB/VARCHAR/VARBYTE values"). An exception may be thrown by the
following PreparedStatement methods:
- setBinaryStream when the destination BYTE or VARBYTE column is used in an index
- setAsciiStream when the destination CHAR or VARCHAR column is used in an index
- setCharacterStream when the destination CHAR or VARCHAR column is used in an index

ErrorCode=5666 SQLException: [NCR] [Teradata DBMS] : LOBs are not allowed in indexes.

This problem is due to DBS DR 106661 ("Error 5666 is returned when inserting lobs into a
varbyte/varchar column when the column is an index").

Solution:

Use the setBytes method instead of setBinaryStream when the destination BYTE or VARBYTE
column is used in an index. Use the setString method instead of setAsciiStream or
setCharacterStream when the destination CHAR or VARCHAR column is used in an index.

setAsciiStream or setCharacterStream not supported with a destination BYTE or VARBYTE column
--------------------------------------------------------------------------------------------

The TTU 8.2 / JDBC 3.4 User Guide states in Appendix D that PreparedStatement.setAsciiStream
or setCharacterStream may be used with a destination BYTE or VARBYTE column. That is
incorrect -- setAsciiStream or setCharacterStream are not supported with a destination
BYTE or VARBYTE column.

In TERA transaction mode, the following exception may be thrown:

ErrorCode=3532 SQLException: [NCR] [Teradata DBMS] : Conversion between BYTE data and other types is illegal.

In ANSI mode, data corruption may occur due to DBS DR 106251 ("When inserting a CLOB value
into a VARBYTE/BYTE column in ANSI mode the data is truncated").

Solution:

Use the setBytes method for a destination BYTE or VARBYTE column.

Error 6705 when using Clob.getSubString with V2R5.1 and UTF8 or UTF16 session character set
-------------------------------------------------------------------------------------------

When using Teradata Database V2R5.1 with the UTF8 or UTF16 session character set, then
Clob.getSubString may throw an exception for CLOB values greater than 8026 characters in length.

ErrorCode=6705 SQLException: [NCR] [Teradata DBMS] : An illegally formed character string was encountered during translation.

This problem is due to DBS DR 106603 ("substr returns 6705 error when using a CLOB locator
and total length requested is > than 8026 & charset is UTF8/UTF16").

Solution:

Use a session character set other than UTF8 or UTF16 when using V2R5.1 and calling
Clob.getSubString, or use Teradata Database V2R6.0 or later releases, which do not have
this limitation.

Incorrect values from getColumnDisplaySize for CLOB columns
-----------------------------------------------------------
When using Teradata Database releases V2R06.00.02.00 through V2R06.00.02.07
or Teradata Database releases V2R06.01.00.00 through V2R06.01.00.08, you may
encounter the problem described by DBS DR 100397 ("PrepInfoX returns
incorrect Length for CLOB columns"), which may cause incorrect values to be
returned for CLOB columns from ResultSetMetaData.getColumnDisplaySize.

Solution:

If using Teradata Database releases V2R06.00.02.00 through V2R06.00.02.07,
then upgrade to release V2R06.00.02.08 or later, which contains the fix
for DR 100397.

If using Teradata Database releases V2R06.01.00.00 through V2R06.01.00.08,
then upgrade to release V2R06.01.00.09 or later, which contains the fix
for DR 100397.

Unable to connect to database when using HPUX 11.23 JDK 5.0
-----------------------------------------------------------

When attempting to connect to the Teradata Database when HPUX 11.23 JDK 5.0,
you may receive an exception similar to: TeraEncrypt: Error
tdgss-stack-trace-begin>>> GSSException: Failure unspecified at GSS-API
level (Mechanism level: Failure during key generation by algorithm layer.)

This is a known problem with HPUX 11.23 JDK 5.0. HP's web site states
the following:

SecureRandom engine implementation (11i HP Integrity and HP9000 PA-RISC)

Beginning with 5.0, Sun Microsystems' SecureRandom engine implementation
supports a new algorithm, NativePRNG, in addition to SHA1PRNG. NativePRNG
will only be available if /dev/random and /dev/urandom are installed in
your system. Because HP-UX does not support seeding entropy generating
devices such as /dev/random, applications that rely on this will not be
able to use NativePRNG. An attempt to seed the device will cause an
exception. This defect is expected to be fixed in a future release.

Solution:

No solution is available for this issue at the present time.

Modifying SQL Statements
------------------------

In the Teradata JDBC Driver, version 3.1 and earlier releases, the Teradata
JDBC Driver modified the SQL statement text of PreparedStatements, 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), then the Teradata JDBC driver would
change the SQL statement to:

select * from table1 where colid IS NULL

This was an incorrect procedure to use. The problem was fixed in the Teradata
JDBC Driver version 3.2, but the fix could change the output of some applications.

Solution:

Refer to the Teradata JDBC Driver User Guide for details on how to change
the application to work correctly with the Teradata JDBC Driver.

Calling Stored Procedures
-------------------------

In the Teradata JDBC Driver version 3.1 and earlier releases, the Teradata
JDBC Driver permitted stored procedures to be called using the PreparedStatement
interface, and the stored procedure's INOUT and OUT parameter output values
were returned as a single-row result set from the executeQuery method.

Note that the JDBC standard only supports calling stored procedures using the
CallableStatement interface. Also, because stored procedures do not return a
result set, only the execute and executeUpdate methods are supported for calling
a stored procedure. The JDBC 3.0 specification requires a JDBC driver to throw
a SQLException from executeQuery when that method is used to execute a SQL
statement that does not return a result set.

The Teradata JDBC Driver is evolving towards full compliance with that JDBC 3.0
specification requirement:

- This release of the Teradata JDBC Driver no longer returns a stored
procedure's INOUT and OUT parameter output values as a single-row result
set from the PreparedStatement.executeQuery method. Instead, an empty result
set is returned.

- A future release of the Teradata JDBC Driver will throw a SQLException from
executeQuery when that method is used to execute a SQL statement that does
not return a result set, such as a SQL CALL statement.

Applications using the PreparedStatement interface to call a stored procedure
may encounter the difference in behavior.

Solution:

Modify the application to call stored procedures by using the CallableStatement
interface, and either the execute or executeUpdate methods.

According to the JDBC standard, the proper sequence for calling a stored
procedure is as follows:
- Use Escape Syntax curly braces: {call storedproc(arg1, arg2, arg3)}
- Call Connection.prepareCall to use the CallableStatement interface.
- Prior to executing the statement, bind all input values for IN and INOUT
parameters using the CallableStatement setter methods setInt, setString, etc.
- Prior to executing the statement, register all stored procedure INOUT and OUT
parameters with the CallableStatement.registerOutParameter method.
- Use either the CallableStatement.execute or CallableStatement.executeUpdate
method to execute the SQL CALL statement.
- After executing the statement, use the CallableStatement getter methods such
as getInt, getString, etc. to obtain the stored procedure's INOUT and OUT
parameter output values.

Installation
------------

This release of the Teradata JDBC Driver is distributed as platform-independent
jar files. For downloading convenience, the platform-independent jar files are
bundled together and provided in both zip format and tar format.

TeraJDBC__indep_indep.03.04.00.06.zip and TeraJDBC__indep_indep.03.04.00.06.tar
both contain the same set of platform-independent files:

readme.txt - this file
terajdbc4.jar - the Teradata JDBC Driver
tdgssjava.jar - the Teradata security library
tdgssconfig.jar - the Teradata security configuration

Download either the zip file or the tar file, and unzip (or untar) the downloaded
file into a directory of your choice, and then set your classpath to refer to the
necessary jar files.

Your classpath must include:

terajdbc4.jar
tdgssjava.jar
tdgssconfig.jar

Your classpath must NOT include any jar files from any previous releases of
the Teradata JDBC Driver. It is recommended, but not required, that any
previous release of the Teradata JDBC Driver be uninstalled prior to
downloading and using this release of the Teradata JDBC Driver.

For systems running only Java applications that use the Teradata JDBC Driver,
the tdgssconfig.jar file replaces the TdgssUserConfigFile.xml file from the
previous release of the Teradata JDBC Driver. If the TdgssUserConfigFile.xml
file has not been customized for the site, then the TdgssUserConfigFile.xml
file is no longer needed and can be removed.

For systems running both C/C++ and Java applications that access the Teradata
Database, it is possible to share the TeraGSS security configuration. This is
appropriate if the TdgssUserConfigFile.xml file has been customized for the
site. To enable sharing, the Java classpath should include the TeraGSS
directory that contains the TdgssUserConfigFile.xml file, and the classpath
should not include the tdgssconfig.jar file.

Documentation
-------------

The Teradata JDBC Driver User Guide Release 03.04.00 is available online
at http://www.info.teradata.com/

Navigate to "Teradata Data Warehousing", then "Teradata Tools and Utilities",
then "Java Database Connectivity (JDBC)", and select the User Guide Release
03.04.00, which corresponds to this release of the Teradata JDBC Driver.

Documentation for how to use the Teradata JDBC Driver with supported application
servers is available on the http://www.teradata.com Teradata Download Center in
the Teradata JDBC Driver section.

Teradata Download Center / Teradata JDBC Driver / Teradata JDBC Driver 8.2

TTU8.2 TeraJDBC.03.04.00.06 Readme

TTU8.2 TeraJDBC.03.04.00.06 Download