NAME

DBD::Teradata Lite - Perl DBI Driver for Teradata

Last updated September 27, 2004

SYNOPSIS


     use DBI;
     my $dbh = DBI->connect(
          "dbi:Teradata:some.host.com",
          "user",
          "passwd")
          or die "Cannot connect\n";
     # more DBI calls...

DESCRIPTION

'Lite' version of the Perl DBI driver for Teradata (See DBI for details).
BE ADVISED: This is a 'Lite' version of the driver, provided with limited functionality and maintenance, and subject to change at the whim of the author. While every effort has been made to assure conformance to DBI-1.13, some peculiarities of Teradata may not be 100% compatible. In addition, some niceties of Teradata not found in DBI have been included to make this library useful for common Teradata tasks (MACRO and multistatement request support, support for summary rows, etc.). Look here for information regarding the fully functional and maintained version.

This driver is 100% pure Perl, and requires no CLI, ODBC, or other interface libraries, other than

NOTE:Due to numerous functional issues, PM/API, FASTLOAD, and EXPORT connection support have been removed from this "lite" version. The commercial version available at www.presicient.com retains that functionality, as well as supporting:

CURRENT VERSION

Release 1.20

CHANGE HISTORY

Release 1.20

Release 1.13:

DRIVER-SPECIFIC BEHAVIOR

DATA-SOURCE NAME

The dsn string passed to DBI->connect() must be of the following form:

     dbi:Teradata:host[:port]

where

Note that this driver will NOT perform the random selection algorithm for resolving the hostname(via the "hostnameCOPN" convention) when multiple paths are available. You should either use the full explicit hostname (e.g., "DBCCOP1"), the numeric IP address (e.g., "1.2.3.4"), create an alias for the explicit hostname, or, better still, use bind(3) the way God intended.

CONNECTIONS, SESSIONS AND TRANSACTIONS

Multiple connections (aka sessions) to a Teradata database are supported.

This Lite version of the driver supports only Teradata mode (i.e., *not* ANSI mode). That means that DDL statements and multistatement requests implicitly finish a transaction, and AUTOCOMMIT is the default. We don't flag any non-ANSI SQL, either. See the Teradata SQL documents for all the differences between ANSI and Teradata behavior. The commercial version does support ANSI mode.

RunStartup execution is not supported.

Cursor SQL syntax (i.e., ...WHERE CURRENT OF...) is not supported in this Lite version, but is supported in the commercial version.

Session reconnection is not supported.

Teradata account strings can be provided by simply appending a single comma, followed by the single-quoted account string, to the password string, e.g.,

     use DBI;
     my $dbh = DBI->connect(
          "dbi:Teradata:some.host.com",
          "user",
          "passwd,'\$H&Lmyaccount'")
          or die "Cannot connect\n";
     # more DBI calls...
HELP statements are not supported, due to an apparent bug in the data returned by the DBMS in RECORD mode.

DATA TYPES

The following list maps DBI defined data types to their Teradata equivalent (if applicable):

DBI
Data Type		Teradata
Data Type
SQL_CHAR CHAR
SQL_NUMERIC DECIMAL
SQL_DECIMAL DECIMAL
SQL_INTEGER INTEGER
SQL_SMALLINT SMALLINT
SQL_FLOAT FLOAT
SQL_REAL FLOAT
SQL_DOUBLE FLOAT
SQL_VARCHAR VARCHAR
SQL_DATE DATE
SQL_TIME TIME
SQL_TIMESTAMP TIMESTAMP
SQL_LONGVARCHAR LONG VARCHAR
SQL_BINARY BYTE
SQL_VARBINARY VARBYTE
SQL_LONGVARBINARY LONG VARBYTE
SQL_BIGINT N/A
SQL_TINYINT BYTEINT
SQL_WCHAR N/A
SQL_WVARCHAR N/A
SQL_WLONGVARCHAR N/A
SQL_BIT N/A

NOTE: INTERVAL types are not yet supported.

CAUTION: Floating point and DECIMAL support within the Teradata DBMS requires specific knowledge of the client platform. Platforms this driver currently knows about are:

This driver attempts to auto-detect the platform on which it is running as follows:

Character
Set		Integer formatAssumed
Platform
ASCIInot network-order
(MSB last)		Intel
ASCIInetwork-order
(MSB first)		SPARC/MOTOROLA

Autodetection can be overridden by setting the environment variable TDAT_PLATFORM_CODE to the appropriate platform code:

PlatformTDAT_PLATFORM_CODE
Value
Any Intel X86/Pentium8
Sun SPARC,
Motorola 68XXX,
ATT 3b2		7
VAX9
IBM 370/3903
AMDAHL UTS10
Honeywell4

If your platform's floating point (specifically, double-precision) format does not match that of one of those platforms, AVOID FLOATING POINT VALUES! Substituting DECIMAL or CHARACTER values will often work well, though loss of precision may be a problem.

For some platforms (notably VAXen and mainframes), Teradata returns DECIMALs as binary-coded decimal (BCD) values. For most workstation platforms (Intel and most RISC), DECIMAL is returned as a simple fix-point integer. Currently, DBD::Teradata only converts the latter format. BCD encoded values may eventually be supported if sufficient hue and cry is raised...but it's currently not a priority.

Finally, note that double-byte character sets (i.e, UNICODE, Kanji, etc.) are not supported in this Lite version, but are supported (via UTF8) in the commercial version

PARAMETERIZED SQL

This driver supports both USING clauses and placeholders to implement parameterized SQL; however, they cannot be mixed in the same request. Also, when using placeholders, all parameter datatypes are assumed to be VARCHAR(16) unless explicit datatypes are specified via a bind_param() call, or the environment variable TDAT_PH_SIZE has been defined to another value. However, the driver will adjust the parameter type declaration provided to the DBMS upon execute() so that parameters without explicit type specifications which exceed the VARCHAR(16) size, will be presented to the DBMS as VARCHAR(<actual-param-length>).

MULTI-STATEMENT AND MACRO REQUESTS

Multi-statement and MACRO execution requests are supported. Stored procedure support is available in the commercial version of this driver.

Reporting the results of multi-statement and MACRO requests presents some special problems. Refer to the DRIVER SPECIFIC ATTRIBUTES section below for detailed descriptions of relevant statement handle attributes. The driver behavior is augmented as follows:

An example of processing multi-SELECT requests:


$sth = $dbh->prepare('SELECT user; SELECT date; SELECT time;');
$names = $sth->{NAME};
$types= $sth->{TYPE};
$precisions = $sth->{PRECISION};
$scales = $sth->{SCALE};
$stmt_info = $sth->{'tdat_stmt_info'};

$sth->execute();
$currstmt = -1;
while ($rows = $sth->fetch_array()) {
	if ($currstmt != $sth->{'tdat_stmt_num'}) {
		print "\n\n";
		$currstmt = $sth->{'tdat_stmt_num'};
		$stmthash = $$stmt_info[$currstmt};
		$starts_at = $$stmthash{'StartsAt'};
		$ends_at = $$stmthash{'EndsAt'};
		for ($i = $starts_at; $i <= $ends_at; $i++) {
			print "$$names[$i] ";
		}
		print "\n";
	}
	for ($i = $starts_at; $i <= $ends_at; $i++) {
		print "$row[$i] ";
	}
}

SUMMARIZED SELECT REQUESTS

Like multi-statement and MACRO requests, reporting the results of summarized SELECT requests requires some special processing. Refer to the DRIVER SPECIFIC ATTRIBUTES section below for detailed descriptions of relevant statement handle attributes. The driver behavior is augmented as follows:

An example of processing summarized SELECT:


$sth = $dbh->prepare('SELECT Name FROM Employees WITH AVG(Salary), SUM(Salary)');
$names = $sth->{NAME};
$types= $sth->{TYPE};
$precisions = $sth->{PRECISION};
$scales = $sth->{SCALE};
$stmt_info = $sth->{'tdat_stmt_info'};

$sth->execute();
$currstmt = -1;
while ($rows = $sth->fetchrow_array()) {
	if ($currstmt != $sth->{'tdat_stmt_num'}) {
#
#	new stmt, get its info
#
		print "\n\n";
		$currstmt = $sth->{'tdat_stmt_num'};
		$stmthash = $$stmt_info[$currstmt];
		$starts_at = $$stmthash{'StartsAt'};
		$ends_at = $$stmthash{'EndsAt'};
		$sumstarts = $$stmthash{'SummaryStarts'};
		$sumends = $$stmthash{'SummaryEnds'};
		$sumrow = $$stmthash{'IsSummary'};
		for ($i = $starts_at; $i <= $ends_at; $i++) {
			print "$$names[$i] ";	# print the column names
		}
		print "\n";
	}
	if (defined($sumrow)) {
#
#	got a summary row, space it
#	NOTE: this example uses simple tabs to space summary fields;
#	in practice, a more rigorous method to precisely align summaries with their
#	respective columns would be used
#
		$sumpos = $$stmthash{'SummaryPosition'};
		$sumposst = $$stmthash{'SummaryPosStart'};
		print "\n-----------------------------------------------------\n";
		for ($i = $$sumstart[$sumrow], $j = $$sumposst[$sumrow];
			$i <= $$sumend[$sumrow]; $i++, $j++) {
			print ("\t" x $$sumpos[$j]);	# tab each column for alignment
			print "$$names[$i]: $row[$i]\n";
		}
	}
	else {
#
#	regular row, just print the values
#
		for ($i = $starts_at; $i <= $ends_at; $i++) {
			print "$row[$i] ";
	}
}

UTILITY SUPPORT

Support for non-SQL connections has been removed from this version due to numerous bugs and functional limitations. The commercial version provides much improved support for these features, as well as adding multiload and remote console support.

DOUBLE BUFFERING

Double buffering (i.e., issuing a CONTINUE to the DBMS while the application is still fetching data from the last received set of rowdata) is supported, but not yet thoroughly tested. Use at your own risk by defining an environment variable TDAT_NO2BUFS=0.

ERROR HANDLING

DBI does not support the notion of warnings; therefore, the hashref provided by the driver specific statement handle attribute tdat_stmt_info provides a Warning attribute that can be queried to retrieve warning messages.

DIAGNOSTICS

DBI provides the trace() function to enable various levels of trace information. DBD::Teradata uses this trace level to report its internal operation, as well.

DRIVER-SPECIFIC ATTRIBUTES

There are some additional attributes that the user can either supply to various DBI calls, or query on database or statement handles:

CONFORMANCE

DBD::Teradata 1.20 requires a minimum Perl version of 5.6.0, and a minimum DBI version of 1.13.

The following DBI functions are not yet supported: 

DBI->data_sources()
$dbh->prepare_cached()
$sth->table_info()
$dbh->tables()
$dbh->type_info_all()
$dbh->type_info()
Also be advised that using either selectall_arrayref() or fetchall_arrayref() is probably a bad idea unless you know the number of rows returned is reasonably small.

SUPPORTED PLATFORMS

This driver have been successfully tested against both Teradata V2R5.0 and V2R5.1, running on Windows 2000. Prior versions have also been tested against V2R3.0 through V2R5.0 on MPRAS.

The following table lists the client platforms (hardware and O/S) for which successful reported use of this driver have been either tested or reported.
Hardware OS Perl Version DBD::Teradata
Version
Intel/AMD PC Win98 5.005
(ActivePerl)		 1.12
Intel PC WinNT 4.0 SP6 5.6
(ActivePerl)		 1.12
Intel PC Linux 5.?? 1.00
NCR 4XXX (Intel) MPRAS 5.005 1.10
iMac DV (PowerPC) LinuxPPC 5.005 1.12
Sun SPARC Solaris 4.3 5.005 1.10
IBM RS/6000 AIX 5.005 1.10
HP 9000 HP-UX 11.0 5.6.0 1.10
Intel PC FreeBSD 3.4-4.2 5.6.0 1.10

TIPS & TRICKS

REFERENCES

AUTHOR

Dean Arnold, Presicient Corp.

COPYRIGHT

Copyright (c) 2000, Dean Arnold, USA
Copyright (c) 2001-2004, Presicient Corp., USA

Permission is granted to use this software according to the terms of the Artistic License, as specified in the Perl README file, with the exception that commercial redistribution, either electronic or via physical media, as either a standalone package, or incorporated into a third party product, requires prior written approval of the author.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Presicient Corp. reserves the right to provide support for this software to individual sites under a separate (possibly fee-based) agreement.

Teradata® is a registered trademark of NCR Corporation.