Download OLE DB Provider for Teradata User Guide

OLE DB Provider for Teradata
User Guide
Release 13.10
B035-2498-020A
February 2010
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, and z/OS 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 are 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 © 2001-2010 by Teradata Corporation. All Rights Reserved.
Preface
Purpose
This book provides information about OLE DB Provider for Teradata, which is a Teradata®
Tools and Utilities product. Teradata Tools and Utilities is a group of products designed to
work with Teradata Database.
Applications that use the OLE DB API can access Teradata Database using OLE DB Provider
for Teradata.
Audience
This book is intended for use by:
•
System and application programmers
•
System administrators
•
Users of OLE DB applications
Supported Releases
This book supports the following releases:
•
Teradata Database 13.10
•
Teradata Tools and Utilities 13.10
•
OLE DB Provider for Teradata 13.10
Note: See “Determining the Current Version” on page 20 to verify the OLE DB Provider
for Teradata version number.
To locate detailed supported-release information:
1
Go to http://www.info.teradata.com/.
2
Click General Search under Online Publications.
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.
OLE DB Provider for Teradata User Guide
3
Preface
Prerequisites
The spreadsheet includes supported Teradata Database versions, platforms, and product
release numbers.
Prerequisites
The following prerequisite knowledge is required for this product:
•
Teradata Database
•
Microsoft Windows operating system for your hardware platform
Changes to This Book
The following changes were made to this book in support of the current release. Changes are
marked with change bars. For a complete list of changes to the product, see the Teradata Tools
and Utilities Release Definition associated with this release.
Date and Release
Description
February 2010
Teradata Tools and
Utilities 13.10
• Moved installation information from this manual to the Teradata Tools
and Utilities Installation Guide for Microsoft Windows, B035-2407mmyx. Renamed this manual.
• Updated to reflect support for IPv6.
August 2008
Teradata Tools and
Utilities 13.0
• Added a new option to the Connection dialog box that offers a choice
between returning column titles or column names.
• Added instructions about stopping all applications that use OLE DB
Provider for Teradata before the DECIMAL separator character is
changed to avoid erroneous values being returned from OLE DB
Provider for Teradata. See “Provider Limitations” on page 112.
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.
4
OLE DB Provider for Teradata User Guide
Preface
Additional Information
Type of Information
Description
Access to Information
Release overview
Use the Release Definition for the following
information:
1 Go to http://www.info.teradata.com/.
• Overview of all of the products in the
release
• Information received too late to be
included in the manuals
• Operating systems and Teradata
Database versions that are certified to
work with each product
• Version numbers of each product and
the documentation for each product
• Information about available training
and the support center
3 Type 2029 in the Publication Product ID box.
Use the Teradata Information Products web
site to view or download specific manuals
that supply related or additional
information to this manual.
1 Go to http://www.info.teradata.com/.
Late information
Additional product
information
2 Click General Search under Online Publications.
4 Click Search.
5 Select the appropriate Release Definition from
the search results.
2 Click Data Warehousing under Online
Publications, Browse by Category
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.
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.
1 Go to http://www.info.teradata.com/.
2 Click Data Warehousing under Online
Publications, Browse by Category.
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.
1 Go to http://www.info.teradata.com/.
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:
1 Go to Teradata.com.
2 Select a link.
• Executive reports, case studies of
customer experiences with Teradata,
and thought leadership
• Technical information, solutions, and
expert advice
• Press releases, mentions, and media
resources
OLE DB Provider for Teradata User Guide
5
Preface
Additional Information
6
OLE DB Provider for Teradata User Guide
Table of Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
Supported Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4
Changes to This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4
Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4
Chapter 1:
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Object Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Configuration Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Operating System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Database Versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Determining the Current Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Dependent Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
19
19
20
20
20
Technical Assistance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Chapter 2:
Using OLE DB Provider for Teradata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Connecting to Teradata Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating the Data Source Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting the Data Source Object Required Properties Values . . . . . . . . . . . . . . . . . . . . . . .
Setting Teradata Database Session Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Methods of Connecting to the Teradata Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
21
22
22
23
23
Connecting Directly to Teradata Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Setting Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Initializing the Data Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
OLE DB Provider for Teradata User Guide
7
Table of Contents
Single Sign On . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26
Using DBPROP_AUTH_INTEGRATED . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26
Teradata Database Connection Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26
Password Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26
Connecting Using Teradata Connection Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27
Setting DBPROP_INIT_PROMPT Property Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27
Displaying Teradata Connection Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27
Logon Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30
User Entry Takes Precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31
Limitation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31
Preventing the Teradata Connection Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32
Connecting Using IDBPromptInitialize Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33
Connecting Using PromptDataSource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34
Selecting Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35
Connecting to a Data Source Using the PromptFileName Method . . . . . . . . . . . . . . . . . . . . .40
Setting Provider String Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
Value Limitation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
List of Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44
Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48
Changing Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49
Changing Data Using DML Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49
Changing Data Using Rowset Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
Comparing DML with IRowsetChange/IRowsetUpdate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54
Large Objects (LOBs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55
Using Storage Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55
BLOB/CLOB Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55
UTF8 and LOBs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56
Properties Associated with BLOBs and CLOBs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57
User-Defined Functions (UDFs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58
Creating UDFs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58
Program Listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59
User-Defined Types and User-Defined Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
Using UDTs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
Using UDMs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
Schema Rowsets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61
BIGINT and Large DECIMALs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61
8
OLE DB Provider for Teradata User Guide
Table of Contents
Chapter 3:
Programming Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Date, Time, and Timestamp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Precision . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Date Column Format Restriction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Work Around . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
63
63
63
64
INTEGER FORMAT ’99:99:99’ Columns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data Type Restriction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Work Around . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Remedy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
64
64
64
65
65
Using Multiple Parameter Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Required Actions Before ICommand::Execute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Unprepared Commands Required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Retrieving Column Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
66
66
66
66
Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Implementation of a Client-side DNS Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DNS Caching Problem with Windows 2000 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OLE DB Provider for Teradata String Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
67
68
68
68
Chapter 4:
Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Source, Format and Structure of Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Source of an OLE DB Error. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Structure of an OLE DB Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Retrieving the Error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SQLState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Native Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Teradata Database Error Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Teradata Database Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Error Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
71
71
71
72
73
74
74
75
75
Visual C++ Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Visual Basic with ADO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
OLE DB Provider for Teradata User Guide
9
Table of Contents
Chapter 5:
OLE DB Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .79
Unsupported Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .79
Supported Interfaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81
IAccessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82
IColumnsInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82
IColumnsRowset
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83
ICommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84
ICommandWithParameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85
IDBSchemaRowset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85
Fully Qualify Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85
Collation Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .86
Default Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .86
Supported Schema Rowsets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .86
Column Privileges Schema Rowset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87
Columns Schema Rowset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88
Foreign Keys Schema Rowset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89
Indexes Schema Rowset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90
Primary Keys Schema Rowset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90
Procedure Parameters Schema Rowset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91
Procedures Schema Rowset. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92
Schemata Schema Rowset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92
Tables Schema Rowset. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93
Provider Types Schema Rowset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94
IRowset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94
IRowsetChange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95
ITransaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96
ITransactionLocal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96
Isolation Level and Access Locking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97
Chapter 6:
Supported Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99
Encryption Property Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100
Initialization Property Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100
Session Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .103
Data Source Information Property Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104
10
OLE DB Provider for Teradata User Guide
Table of Contents
Rowset Property Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Session Property Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Chapter 7:
Programming Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Teradata Database Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
UTF8 and UTF16 Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Provider Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Logon Timeout Limitation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Teradata WITH Clause Limitation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Maximum Number of Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Intervals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Stored Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
DLL File Limitation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Appendix A:
OLE DB to Teradata
Data Type Mappings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Appendix B:
Using ADO with OLE DB Provider for Teradata . . . . . . . . . . . . . . . . 117
Making the Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Using a Connection String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Using the Properties Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Cursors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Client-Side Cursor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Server-Side Cursor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Recordset Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
ADO Dynamic Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Connection Dynamic Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Recordset Dynamic Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
OLE DB Provider for Teradata User Guide
11
Table of Contents
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .127
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131
12
OLE DB Provider for Teradata User Guide
List of Figures
Figure 1: Functional Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Figure 2: Object Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Figure 3: Teradata Database Connection Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Figure 4: Connection Dialog - Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Figure 5: OLE DB Error Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
OLE DB Provider for Teradata User Guide
13
List of Figures
14
OLE DB Provider for Teradata User Guide
List of Tables
Table 1: Setting Consumer Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Table 2: Property Sources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Table 3: Setting DBPROP_INIT_PROMPT Property Values. . . . . . . . . . . . . . . . . . . . . . . . . . 27
Table 4: Teradata Connection Dialog Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Table 5: Teradata Connection Options Dialog - Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Table 6: IDBPromptInitialize Interface Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Table 7: Data Link Properties Dialog Box Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Table 8: Provider String Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Table 9: Setting Rowset Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Table 10: Price Column . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Table 11: Rowset Return from ICommand::Execute. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Table 12: Table after Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Table 13: Rowset Return Using Primary Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Table 14: Deciding to Use DML Statements or IRowsetChange or IRowsetUpdate . . . . . . . 54
Table 15: Advantages of Using DML Statements or IRowsetChange or IRowsetUpdate . . . 54
Table 16: Export Width . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Table 17: BLOB and CLOB Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Table 18: UDT and UDM Visibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Table 19: Rowset (ServiceHistory Table) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Table 20: Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Table 21: String Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Table 22: SQLState Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Table 23: Custom Error Object Mapping to Teradata Database Error . . . . . . . . . . . . . . . . . . 77
Table 24: Unsupported Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Table 25: Supported Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Table 26: Supported Metadata Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Table 27: Column Privileges Schema Rowset. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Table 28: Columns Schema Rowset. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Table 29: Custom Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Table 30: Foreign Keys Schema Rowset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Table 31: Indexes Schema Rowset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Table 32: Primary Keys Schema Rowset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
OLE DB Provider for Teradata User Guide
15
List of Tables
Table 33: Procedure Parameters Schema Rowset. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91
Table 34: Procedures Schema Rowset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92
Table 35: Schemata Schema Rowset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92
Table 36: Tables Schema Rowset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93
Table 37: Provider Types Schema Rowset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94
Table 38: Upgrades to Isolation Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96
Table 39: Isolation Level and Access Locking. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97
Table 40: Initialization Property Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100
Table 41: Data Source Information Property Group. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104
Table 42: Rowset Property Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107
Table 43: Session Property Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .110
Table 44: OLE DB Provider for Teradata to Teradata Data Type Mappings . . . . . . . . . . . . .115
Table 45: Using the ADO Property String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117
Table 46: Recordset Methods. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120
Table 47: Connection ADO Dynamic Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121
Table 48: Recordset ADO Dynamic Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124
16
OLE DB Provider for Teradata User Guide
CHAPTER 1
Introduction
This chapter introduces the major concepts of OLE DB Provider for Teradata, and provides
general information about system requirements and technical assistance.
For installation instructions, see Teradata Tools and Utilities Installation Guide for Microsoft
Windows, B035-2407-mmyx.
•
Introduction
•
Configuration Requirements
•
Technical Assistance
Introduction
OLE DB Provider for Teradata allows many kinds of users to connect to Teradata Database.
The OLE DB database is a set of Component Object Model (COM) interfaces and objects that
provide applications with uniform, standard access to any data store. In this case, the data
store is in Teradata Database. OLE DB Provider for Teradata specifically allows access to data
stores that do not use Structured Query Language (SQL).
Using this product, an application requests database information from an intermediate
program, which in turn accesses Teradata Database. The intermediate program receives the
response from Teradata Database and returns a copy of the desired data to the application.
The following OLE DB terminology is used in this manual:
•
Consumer - Any application- or system-level program that invokes the component object
model (COM) objects that access a database.
•
Provider - Any program that:
•
Exposes COM objects to a consumer
•
Provides services that the consumer uses to connect, retrieve, and update a database.
OLE DB also introduces the notion of service providers. A service provider enhances the
functionality of a provider; for example, the Microsoft Cursor Service for OLE DB adds clientside cursor support to any provider. Figure 1 shows the functional relationships.
OLE DB Provider for Teradata User Guide
17
Chapter 1: Introduction
Introduction
Figure 1: Functional Relationships
Application/Consumer
Teradata
Service Provider
Provider
Objects
OLE DB Provider for Teradata exposes the following objects to consumers:
•
Data Source
•
Session
•
Transaction
•
Command
•
Rowset
•
Error and Custom Error
•
Multiple Results
OLE DB Provider for Teradata implements all the above objects. Consumers are able to use
these objects as described in the OLE DB specification to access Teradata Database. However,
there are some considerations and programming limitations when using the interfaces to
these objects. The following chapters discuss the differences and limitations:
•
Chapter 3: “Programming Considerations” contains several points to consider when using
OLE DB Provider for Teradata to develop a consumer application.
•
Chapter 5: “OLE DB Interfaces” discusses the interfaces that are supported by OLE DB
Provider for Teradata.
•
Chapter 7: “Programming Limitations” lists limitations of OLE DB Provider for Teradata.
For more information on OLE DB specification, refer to the Microsoft Developer’s Network
(MSDN) documentation on OLE DB Interfaces. See “Technical Assistance” on page 20.
18
•
MSDN Library - See http://msdn.microsoft.com/library/
•
OLE DB Programmer’s Guide
•
Part 4 OLE DB Reference
•
OLE DB Interfaces
OLE DB Provider for Teradata User Guide
Chapter 1: Introduction
Configuration Requirements
Object Hierarchy
The objects that OLE DB Provider for Teradata exposes to the consumer are organized in a
parent-child hierarchy. First, create the parent object, then create the child object. Use the
COM facilities to create the highest-level object, Data Source. Starting from the Data Source
object, each object has a built-in factory to create child objects. The following diagram shows
the hierarchy of some of these objects:
Figure 2: Object Hierarchy
Data Source
Session
Command
Rowset
For more information on the OLE DB architecture, refer to the MSDN Library. See “Technical
Assistance” on page 20.
•
MSDN Library - See http://msdn.microsoft.com/library/
•
OLE DB Programmer’s Guide
•
Part 1: Introduction to OLE DB
•
Chapter 1: Overview of OLE DB
Configuration Requirements
OLE DB Provider for Teradata requires the following hardware and software.
Operating System
The operating system must be one of the following:
•
Microsoft® Windows 2000
•
Microsoft Windows XP Professional
•
Microsoft Windows Server 2003
•
Microsoft Windows Vista
•
Windows Server 2008
•
Microsoft Windows 7
OLE DB Provider for Teradata User Guide
19
Chapter 1: Introduction
Technical Assistance
Database Versions
OLE DB Provider for Teradata works with the following versions of Teradata Database:
•
Teradata Database V2R6.x
•
Teradata Database 12.0
•
Teradata Database 13.0
•
Teradata Database 13.10
Determining the Current Version
To determine the currently installed version of OLE DB Provider for Teradata, select
Start > Control Panel > Add or Remove Programs, and verify the version number.
Dependent Components
OLE DB Provider for Teradata requires the following dependent products, all of which are
included with OLE DB Provider for Teradata package:
•
Shared ICU Libraries for Teradata 13.10 (TDICU)
•
Teradata Generic Security Services (TeraGSS) 13.10 client and server packages
•
Microsoft Data Access Components (MDAC) version 2.8 SP1 (required for Windows 2000
only)
Technical Assistance
Technical assistance is available from the Teradata Support Center Remote Services Center
(TSC-RSC). For contact information, see the Teradata Tools and Utilities Release Definition for
this release.
The Microsoft Developer Network (MSDN) Library is the source for documentation related
to working with OLE DB and MDAC. Search the MSDN Library at http://
msdn.microsoft.com/library/ for Mircosoft’s OLE DB Programmer’s Guide.
20
OLE DB Provider for Teradata User Guide
CHAPTER 2
Using OLE DB Provider for Teradata
This chapter describes how to design an application program that interfaces with OLE DB
Provider for Teradata to access and use a Teradata Data Warehouse.
For installation instructions, see Teradata Tools and Utilities Installation Guide for Microsoft
Windows, B035-2407-mmyx.
This chapter includes the following topics:
•
Connecting to Teradata Database
•
Connecting Directly to Teradata Database
•
Single Sign On
•
Password Encryption
•
Connecting Using Teradata Connection Dialog
•
Connecting Using IDBPromptInitialize Interface
•
Connecting Using PromptDataSource
•
Connecting to a Data Source Using the PromptFileName Method
•
Setting Provider String Attributes
•
Changing Data
•
Comparing DML with IRowsetChange/IRowsetUpdate
•
Large Objects (LOBs)
•
User-Defined Functions (UDFs)
•
User-Defined Types and User-Defined Methods
•
BIGINT and Large DECIMALs
Connecting to Teradata Database
To connect to Teradata Database
1
Create OLE DB Provider for Teradata Data Source object.
2
Set the Data Source Object required properties.
3
Set the Teradata Database session properties.
4
Connect to or initialize the Data Source Object.
OLE DB Provider for Teradata User Guide
21
Chapter 2: Using OLE DB Provider for Teradata
Connecting to Teradata Database
Creating the Data Source Object
To connect to the Teradata Database, a consumer must first create and initialize an instance of
a Data Source object for OLE DB Provider for Teradata.
Example – Visual C++
The following Visual C++ code fragment shows how to create a Data Source object for OLE
DB Provider for Teradata:
// Retrieving the class id
hr = CLSIDFromProgID(L"TDOLEDB", &clsid);
hr = CoCreateInstance(clsid,
NULL,
CLSCTX_INPROC_SERVER,
NULL,
IID_IDBInitialize,
(IUnknown **)&pIDBInitialize);
The Program ID for OLE DB Provider for Teradata is TDOLEDB.
•
This program uses TDOLEDB to retrieve the Class ID.
•
This program uses the Class ID to create the instance of the Data Source object.
Setting the Data Source Object Required Properties Values
After the consumer creates the Data Source object, the consumer must initialize the Data
Source object. To initialize the Data Source object, the consumer code assigns values to
properties in the DBPROPSET_DBINIT property set. The values must provide OLE DB
Provider for Teradata enough information to create a Teradata session.
The consumer must set the following required properties:
Table 1: Setting Consumer Properties
DBPROPSET_INIT Property
Function
DBPROP_AUTH_USERID
Teradata User ID
Although Teradata Database allows semicolons in the
username, OLE DB Provider for Teradata does not. If a
username contains a semicolon, the call to
IDBInitialize::Initialize returns a
DB_SEC_E_AUTH_FAILED error code and presents
the error message:
[Teradata Database]The UserId, Password,
or Account is Invalid
22
DBPROP_AUTH_PASSWORD
Teradata Password
DBPROP_INIT_DATASOURCE
Teradata Database name or IP address (either IPv6 or
IPv4)
OLE DB Provider for Teradata User Guide
Chapter 2: Using OLE DB Provider for Teradata
Connecting Directly to Teradata Database
Setting Teradata Database Session Properties
If a consumer requires specific characteristics for a Teradata session, the consumer can specify
provider string attributes using the DBPROP_INIT_PROVIDERSTRING property. For more
information about the provider string, see “Setting Provider String Attributes” on page 43.
Methods of Connecting to the Teradata Database
Using OLE DB Provider for Teradata, a consumer can connect to a Teradata Database in three
ways:
•
Connecting directly by setting the required properties, and then calling
IDBInitialize::Initialize
•
Using the Teradata Connection dialog
•
Using the IDBPromptInitialize interface
•
PromptDataSource method
•
PromptFileName method
Each of these methods sets the three required properties for establishing a Teradata Database
session:
•
User ID
•
Password
•
DBC Name
The following table shows the sources of the properties.
Table 2: Property Sources
Method
Property Settings Supplied By
Direct connection
consumer
Login screen
User via logon screen
IDBPromptInitialize Interface
User via interface
Connecting Directly to Teradata Database
Setting Properties
To directly connect to Teradata Database, the consumer calls IDBProperties::SetProperties to
set the three required properties listed in the earlier section “Setting the Data Source Object
Required Properties Values” on page 22.
The consumer can also set the property DBPROP_INIT_PROMPT to
DBPROMPT_NOPROMPT so the Teradata Connection dialog does not display. See section
“Connecting Using Teradata Connection Dialog” on page 27 for more details.
OLE DB Provider for Teradata User Guide
23
Chapter 2: Using OLE DB Provider for Teradata
Connecting Directly to Teradata Database
In addition, a consumer can set other properties in the Initialization Property Group. The
Initialization Property Group is named DBPROPSET_DBINIT. For example, some of the
other properties are:
•
DBPROP_INIT_PROVIDERSTRING
•
DBPROP_INIT_TIMEOUT
For more details, refer to “Initialization Property Group” on page 100.
Initializing the Data Source
After the consumer sets all the desired properties, the consumer calls IDBInitialize::Initialize
to initialize the Teradata Data Source.
Example – Visual C++
This Visual C++ example sets the properties needed to successfully initialize the Teradata Data
Source, and sets the provider string property DBPROP_INIT_PROVIDERSTRING.
#include
#include
#include
#include
<oledb.h>
<oledberr.h>
<msdasc.h>
<oleauto.h>
void main()
{
HRESULT
CLSID
hr;
clsid;
IDBInitialize
IDBProperties
DBPROPSET
DBPROP
*pIDBInitialize = NULL;
*pIDBProperties = NULL;
rgPropertySet[1];
rgProperties[4];
//*************************************************************
// Error handling is not included in this example.
//*************************************************************
// Retrieving the class id
hr = CLSIDFromProgID(L"TDOLEDB", &clsid);
// Creating an instance of TDOLEDB
hr = CoCreateInstance(clsid,
NULL,
CLSCTX_INPROC_SERVER,
NULL,
IID_IDBInitialize,
(IUnknown **)&pIDBInitialize);
hr = pIDBInitialize->QueryInterface(IID_IDBProperties,
void **)&pIDBProperties);
// Setting up the properties needed to initialize the Data Source
// Specifying the password
24
OLE DB Provider for Teradata User Guide
Chapter 2: Using OLE DB Provider for Teradata
Connecting Directly to Teradata Database
rgProperties[0].dwOptions = DBPROPOPTIONS_REQUIRED;
rgProperties[0].dwPropertyID = DBPROP_AUTH_PASSWORD;
rgProperties[0].dwStatus = 0;
rgProperties[0].colid = DB_NULLID;
V_VT(&(rgProperties[0].vValue)) = VT_BSTR;
V_BSTR(&(rgProperties[0].vValue)) =
SysAllocString(L"YourPassword");
// Specifying
the user name
rgProperties[1].dwOptions = DBPROPOPTIONS_REQUIRED;
rgProperties[1].dwPropertyID = DBPROP_AUTH_USERID;
rgProperties[1].dwStatus = 0;
rgProperties[1].colid = DB_NULLID;
V_VT(&(rgProperties[1].vValue)) = VT_BSTR;
V_BSTR(&(rgProperties[1].vValue)) = SysAllocString(L"YourUserId");
// Specifying the Data Source.
TDPID.
The Data Source refers to the
rgProperties[2].dwOptions = DBPROPOPTIONS_REQUIRED;
rgProperties[2].dwPropertyID = DBPROP_INIT_DATASOURCE;
rgProperties[2].dwStatus = 0;
rgProperties[2].colid = DB_NULLID;
V_VT(&(rgProperties[2].vValue)) = VT_BSTR;
V_BSTR(&(rgProperties[2].vValue)) =
SysAllocString(L"TERADATA1");
// Specifying provider string
rgProperties[3].dwOptions = DBPROPOPTIONS_REQUIRED;
rgProperties[3].dwPropertyID = DBPROP_INIT_PROVIDERSTRING;
rgProperties[3].dwStatus = 0;
rgProperties[3].colid = DB_NULLID;
V_VT(&(rgProperties[3].vValue)) = VT_BSTR;
V_BSTR(&(rgProperties[3].vValue)) =
SysAllocString(L"SessionMode=ANSI;Enable Parser=Yes;UseXViews=YES");
rgPropertySet->cProperties = 4;
rgPropertySet->guidPropertySet = DBPROPSET_DBINIT;
rgPropertySet->rgProperties = rgProperties;
// Setting the properties
hr = pIDBProperties->SetProperties(1, rgPropertySet);
// Initializing the Data Source
hr = pIDBInitialize->Initialize();
// This is just an example and we assume S_OK was returned.
//------------------------------------------------------------//
// REST OF PROGRAM …
//
//------------------------------------------------------------// Releasing all objects at end of program
OLE DB Provider for Teradata User Guide
25
Chapter 2: Using OLE DB Provider for Teradata
Single Sign On
gIDBProperties->Release();
pIDBInitialize->Release();
}
Single Sign On
The Single Sign On (SSO) feature enables customers to use Windows Integrated Security with
Teradata to log on to Teradata without specifying a Teradata username and password.
OLE DB Provider for Teradata will verify the user using the Security Support Provider
Interface (SSPI), then pass information to Teradata. Teradata will then determine whether a
valid user exists in the database.
Using DBPROP_AUTH_INTEGRATED
To enable Single Sign-on set the property DBPROP_AUTH_INTEGRATED to the “SSPI”.
To disable Single Sign-on, set DBPROP_AUTH_INTEGRATED to NULL (empty). The default
value of this property is NULL.
Teradata Database Connection Dialog
To enable Single Sign-on from the Teradata Database Connection dialog, select the “Use
Integrated Security” radio button. Then ensure the User ID and Password fields are empty,
otherwise, the provider will attempt to perform a third party sign-on.
When the OK button has been pressed, the provider will automatically set
DBPROP_AUTH_INTEGRATED to the “SSPI”.
To disable Single Sign-on, from the Teradata Database Connection dialog, deselect the “Use
Integrated Security” radio button.
Password Encryption
Logon encryption is used automatically if the server for the application supports the feature.
This is not a user-defined setting at the client level, but the feature can be set as a gateway
option using the GTW control utility.
For more information, see the Teradata Database documentation.
26
OLE DB Provider for Teradata User Guide
Chapter 2: Using OLE DB Provider for Teradata
Connecting Using Teradata Connection Dialog
Connecting Using Teradata Connection Dialog
Setting DBPROP_INIT_PROMPT Property Values
To allow a user to enter logon information, you can design the consumer to use the Teradata
Connection dialog. To display this screen, the consumer must set the property
DBPROP_INIT_PROMPT to one of the following values:
Table 3: Setting DBPROP_INIT_PROMPT Property Values
Value
Function
DBPROMPT_PROMPT
Always display the Teradata Connection dialog.
DBPROMPT_COMPLETE
Only display the Teradata Connection dialog
when more information is needed.
DBPROMPT_COMPLETEREQUIRED
Display the Teradata Connection dialog, but
only enable the fields that are not already filled.
DBPROMPT_NOPROMPT
Prevents the Teradata Connection dialog from
displaying.
Displaying Teradata Connection Dialog
The Teradata Connection dialog displays when the consumer calls the method
IDBInitialize::Initialize.
Figure 3: Teradata Database Connection Dialog
Control how the Teradata Connection dialog displays by:
•
The value for DBPROP_INIT_PROMPT.
OLE DB Provider for Teradata User Guide
27
Chapter 2: Using OLE DB Provider for Teradata
Connecting Using Teradata Connection Dialog
•
The properties set from the DBPROPSET_DBINIT Initialization. Property Group. For
more information, see “Initialization Property Group” on page 100.
The Teradata Connection dialog contains the following fields:
Table 4: Teradata Connection Dialog Fields
Field Name
Required/
Optional
Use Integrated Security
Optional
Enables Single Sign-on (SSO). See “Single Sign On”
on page 26 for more details.
Use Data Encryption
Optional
Enables data encryption.
DBC Name
Required
Name or IP address assigned to the Teradata Server.
Both IPv6 and IPv4 addresses are supported.
User ID
Required
Teradata User ID.
Purpose
Note: This field can be blank for Single Sign-on.
Password
Required
Password that corresponds to the User ID.
Note: This field can be blank for Single Sign-on.
Default Database
Optional
Database selected when creating the Teradata
session. For more information on the default
database, refer to the SQL Data Manipulation
Language manual, the DATABASE statement.
Account String
Optional
Account string that corresponds to the User ID. For
more information on the default database, refer to
the SQL Data Definition Language, the CREATE
USER statement.
Session Character Set
Optional
The session character set that you want used in
communications between OLE DB Provider for
Teradata and Teradata Database.
Options Dialog Box
When the Options button is clicked, several fields are added to the dialog box.
28
OLE DB Provider for Teradata User Guide
Chapter 2: Using OLE DB Provider for Teradata
Connecting Using Teradata Connection Dialog
Figure 4: Connection Dialog - Options
The following fields are added:
OLE DB Provider for Teradata User Guide
29
Chapter 2: Using OLE DB Provider for Teradata
Connecting Using Teradata Connection Dialog
Table 5: Teradata Connection Options Dialog - Fields
Field Name
Authentication
Mechanisms
Required/
Optional
Required
Purpose
Select the authentication mechanism specified by
your system administrator from the list of
authentication mechanisms provided in the drop
down list. The Authentication Mechanism identifies
the mechanism used for connections to the data
source.
Valid authentication mechanism values are:
• Empty - If no Authentication Mechanism is listed
in the drop down list, or if the Authentication
Mechanism selected is not supported, the
mechanism used is the system default.
• TD1 - Teradata 1 mechanism.
• TD2 - Teradata 2 mechanism.
• ldap - ldap mechanism.
• KRB5 - Kerberos mechanism.
• KRB5C - Kerberos Compatibility mechanism.
• NTLM - NT LAN Manager mechanism.
• NTLMC - NT LAN Manager Compatibility
mechanism.
• Other - user-defined mechanism.
Authentication
Mechanisms Data
Optional
Enter the parameters required by the selected
authentication mechanism. See your system
administrator.
Use As Column Name
Optional
Select either column titles or column names as the
value. For more information, see
“TDPROP_INIT_USEASCOLUMNNAME (cont.)”
on page 103.
Logon Sequence
To log on
30
1
In the Teradata Connection dialog box, enter data into the appropriate fields.
2
Click OK or Cancel.
OLE DB Provider for Teradata User Guide
Chapter 2: Using OLE DB Provider for Teradata
Connecting Using Teradata Connection Dialog
IF...
THEN...
the user clicks
OK,
1 OLE DB Provider for Teradata sets the corresponding properties with the
data that the user entered.
2 OLE DB Provider for Teradata attempts to initialize the Teradata Data
Source.
3 If the Teradata Data Source initialization succeeds, OLE DB Provider for
Teradata returns S_OK to the consumer.
4 If the Teradata initialization does not succeed, OLE DB Provider for
Teradata returns an error to the consumer.
the user clicks
Cancel,
OLE DB Provider for Teradata returns DB_E_CANCELLED to the consumer.
User Entry Takes Precedence
If the user enters a Default Database or an Account String, the user entry takes precedence
over attributes already specified in the provider string DBPROP_INIT_PROVIDERSTRING.
For more details on the provider string, see “Setting Provider String Attributes” on page 43.
The new user entries do not change the existing attributes in the provider string.
Example
Assume:
DBPROP_INIT_PROVIDERSTRING is:
SessionMode=ANSI;DefaultDatabase=defaultdb1;AccountString=SYSTEM ADMINISTRATOR
And assume:
The user enters into the Teradata Connection dialog, the values:
•
“db1”for the Default Database field
•
“User1”for the Account String field
Then:
The values from the Teradata Connection dialog initialize the Teradata Data Source. The user
logs on as User1 on database db1.
Limitation
The values for the DefaultDatabase and AccountString attributes do not change in the
provider string. DBPROP_INIT_PROVIDERSTRING remains as:
SessionMode=ANSI;DefaultDatabase=defaultdb1;AccountString=SYSTEM ADMINISTRATOR
This is a known limitation. In a future version, OLE DB Provider for Teradata will update the
provider string to reflect changed attributes.
OLE DB Provider for Teradata User Guide
31
Chapter 2: Using OLE DB Provider for Teradata
Connecting Using Teradata Connection Dialog
Preventing the Teradata Connection Dialog
To prevent the Teradata Connection dialog from displaying, the consumer sets
DBPROP_INIT_PROMPT to DBPROMPT_NOPROMPT.
If the consumer uses DBPROMPT_NOPROMPT and one or more of the three required
properties do not have valid data, then IDBInitialize::Initialize returns the error code
DB_SEC_E_AUTH_FAILED. The returned error message is:
[OLE DB Provider for Teradata]Not enough information to log on.
Example – Visual C++
This Visual C++ example uses the DBPROP_INIT_PROMPT property.
#include
#include
#include
#include
<oledb.h>
<oledberr.h>
<msdasc.h>
<oleauto.h>
void main()
{
HRESULT
CLSID
IDBInitialize
IDataInitialize
IDBProperties
DBPROPSET
DBPROP
hr;
clsid;
*pIDBInitialize = NULL;
*pIDataInitialize = NULL;
*pIDBProperties = NULL;
rgPropertySet[1];
rgProperties[2];
//*************************************************************
// Error handling is not included in this example.
// This is an exercise left to the user.
//*************************************************************
// Creating an instance of TDOLEDB
hr = CoCreateInstance(CLSID_MSDAINITIALIZE,
NULL,
CLSCTX_INPROC_SERVER,
IID_IDataInitialize,
(void **)&pIDataInitialize);
// Retrieving the class id
hr = CLSIDFromProgID(L"TDOLEDB", &clsid);
hr = pIDataInitialize->CreateDBInstance(clsid,
NULL,
CLSCTX_INPROC_SERVER,
NULL,
IID_IDBInitialize,
(IUnknown **)&pIDBInitialize);
hr = pIDBInitialize->QueryInterface(IID_IDBProperties,
(void **)&pIDBProperties);
// Setting up the properties needed to initialize the Data Source
32
OLE DB Provider for Teradata User Guide
Chapter 2: Using OLE DB Provider for Teradata
Connecting Using IDBPromptInitialize Interface
// Using the Teradata Connection dialog
rgProperties[0].dwOptions = DBPROPOPTIONS_REQUIRED;
rgProperties[0].dwPropertyID = DBPROP_INIT_PROMPT;
rgProperties[0].dwStatus = 0;
rgProperties[0].colid = DB_NULLID;
V_VT(&(rgProperties[0].vValue)) = VT_I2;
V_I2(&(rgProperties[0].vValue)) = DBPROMPT_PROMPT;
// Specifying provider string
rgProperties[1].dwOptions = DBPROPOPTIONS_REQUIRED;
rgProperties[1].dwPropertyID = DBPROP_INIT_PROVIDERTRING;
rgProperties[1].dwStatus = 0;
rgProperties[1].colid = DB_NULLID;
V_VT(&(rgProperties[3].vValue)) = VT_BSTR;
V_BSTR(&(rgProperties[3].vValue)) =
SysAllocString(L"SessionMode=ANSI;Enable Parser=Yes;UseXViews=YES");
rgPropertySet->cProperties = 2;
rgPropertySet->guidPropertySet = DBPROPSET_DBINIT;
rgPropertySet->rgProperties = rgProperties;
// Setting the properties
hr = pIDBProperties->SetProperties(1, rgPropertySet);
// Initializing the Data Source
// The Teradata Connection dialog displays when the program calls
IDBInitialize::Initialize.
hr = pIDBInitialize->Initialize();
// This is just an example and we assume S_OK was returned
//------------------------------------------------------------//
// REST OF PROGRAM …
//
//------------------------------------------------------------// Releasing all objects at end of program
pIDBInitialize->Release();
gIDBProperties->Release();
}
Connecting Using IDBPromptInitialize
Interface
The IDBPromptInitialize interface allows the consumer to either:
•
Display the Data Link Properties dialog box, or
•
Specify the path to a Universal Data Link (UDL) file
OLE DB Provider for Teradata User Guide
33
Chapter 2: Using OLE DB Provider for Teradata
Connecting Using PromptDataSource
The IDBPromptInitialize interface contains two methods:
Table 6: IDBPromptInitialize Interface Methods
Method
Operation
PromptDataSource
Users enter information through the Data Link Dialog boxes.
PromptFileName
Users specify a path to a UDL file that contains information that OLE DB
Provider for Teradata uses to connect to the Teradata Data Source.
For more information on the IDBPromptInitialize interface, refer to the MSDN Library. For
full directions, see Teradata Tools and Utilities Installation Guide for Microsoft Windows, B0352407-mmyx.
•
MSDN Library - See http://msdn.microsoft.com/library/
•
OLE DB Programmer’s Guide
•
Part 4: OLE DB Reference
•
OLE DB Interfaces
•
OLE DB Core Components Interfaces
•
IDBPromptInitialize
Connecting Using PromptDataSource
The PromptDataSource method allows the user to manually enter the required properties for
initializing the Teradata Data Source. When the consumer program calls the
PromptDataSource method, the Data Link Properties dialog box displays. The Data Link
Properties dialog box contains four tabs:
Table 7: Data Link Properties Dialog Box Tabs
34
Tab
Function
Provider
The user selects the provider program to use for the connection.
Connection
The user enters the information that initializes the Data Source.
Advanced
The user can modify settings that affect the connection to the Data Source.
All
Displays all of the information entered by the user in the other three tabs.
OLE DB Provider for Teradata User Guide
Chapter 2: Using OLE DB Provider for Teradata
Connecting Using PromptDataSource
Selecting Provider
To selecting an OLE DB provider
1
In the OLE DB Providers list, click OLE DB Provider for Teradata to highlight it.
2
Click Next.
The Connection tab opens.
OLE DB Provider for Teradata User Guide
35
Chapter 2: Using OLE DB Provider for Teradata
Connecting Using PromptDataSource
Entering Login Information
To enter login information
36
1
In the Data Source field, enter the system name of the system running Teradata Database.
2
In the User name field, enter the Teradata user ID.
3
In the Password field, enter the password for the Teradata user ID.
OLE DB Provider for Teradata User Guide
Chapter 2: Using OLE DB Provider for Teradata
Connecting Using PromptDataSource
Entering the Connection Timeout Value
To enter a Connection Timeout value
1
In the Data Link Properties box, click the Advanced tab.
2
In the Connect timeout field, enter the number of seconds for the connection timeout.
Note: Access permissions in this dialog box have no effect.
OLE DB Provider for Teradata User Guide
37
Chapter 2: Using OLE DB Provider for Teradata
Connecting Using PromptDataSource
Verifying Entries
To verify entries
1
In the Data Link Properties box, click the All tab.
2
Examine the initialization values to be sure they are all correct. Use the Edit Value button
to make changes.
Leave the Data Link Properties box open to enter the provider string.
Entering a Provider String
To enter a provider string
1
In the All tab of the Data Link Properties box, double click Extended Properties,
OR
Highlight Extended Properties and then click Edit Value.
The Edit Property Value dialog box appears.
2
38
In the Edit Property Value dialog box:
OLE DB Provider for Teradata User Guide
Chapter 2: Using OLE DB Provider for Teradata
Connecting Using PromptDataSource
a
Enter the provider string in the Property Value field.
b
Click OK.
The provider string appears in the All tab Extended Properties field.
3
Data Link Properties In the box, click OK.
The Data Link Properties box closes.
Example – Visual C++
This Visual C++ example uses the IDBPromptInitialize::PromptDataSource method.
#include
#include
#include
#include
<oledb.h>
<oledberr.h>
<msdasc.h>
<oleauto.h>
void main()
{
HRESULT
PCLSID
IDBPromptInitialize
IDBInitialize
ICommand
hr;
pclsid = NULL;
*pIDBPromptInitialize = NULL;
*pIDBInitialize = NULL;
*pICommand = NULL;
//*************************************************
// Error handling is not included in this example.
//**************************************************
hr = CoCreateInstance(CLSID_DataLinks,
NULL,
CLSCTX_INPROC_SERVER,
IID_IDBPromptInitialize,
(void **)&pIDBPromptInitialize);
// Getting the window handle so that it can be passed to the
// PromptDataSource method.
HWND
hwnd = GetDesktopWindow();
// Calling method to allow user to enter information needed to
OLE DB Provider for Teradata User Guide
39
Chapter 2: Using OLE DB Provider for Teradata
Connecting to a Data Source Using the PromptFileName Method
// initialize properties for initializing Data Source.
hr = pIDBPromptInitialize->PromptDataSource(NULL,
hwnd,
DBPROMPTOPTIONS_PROPERTYSHEET,
0,
NULL,
NULL,
IID_IDBInitialize,
(IUnknown **)&pIDBInitialize);
// Initialize the Data Source object.
hr= pIDBInitialize->Initialize();
//------------------------------------------------------------//
// REST OF PROGRAM …
//
//------------------------------------------------------------// At the end of the program the program must release all objects
pIDBInitialize->Release();
pIDBPromptInitialize->Release();
}
Connecting to a Data Source Using the
PromptFileName Method
To connect to a data source using the PromptFileName method
1
The consumer has previously saved the Data Link Properties dialog field information to a
Universal Data Link file by using IDataInitialize::WriteStringToStorage.
The Universal Data Link (.udl) file contains the complete provider string that OLE DB
Provider for Teradata uses to connect to the Data Source. Several .udl files can each
contain different parameters for connecting to different Data Sources.
For a description of the Data Link Properties dialog box, see “Connecting Using
PromptDataSource” on page 34.
40
2
The consumer calls the IDBPromptInitialize::PromptFileName method to obtain the path
to the .udl file.
3
The IDBPromptInitialize::PromptFileName method displays the Organize Data Link Files
dialog box.
OLE DB Provider for Teradata User Guide
Chapter 2: Using OLE DB Provider for Teradata
Connecting to a Data Source Using the PromptFileName Method
4
The user clicks on the .udl file associated with the desired Data Source.
The file name highlights.
5
The user clicks Open.
6
The IDBPromptInitialize::PromptFileName method passes the .udl file name and path to
the consumer. The consumer makes a method call to
IDataInitialize::LoadStringFromStorage.
7
The IDataInitialize::LoadStringFromStorage method retrieves the connection string from
the .udl file. The consumer makes a method call toIDataInitialize::GetDataSource.The
IDataInitialize::GetDataSource method retrieves the Data Source object that is based on
the connection string.
Example – Visual C++
This Visual C++ example uses the IDBPromptInitialize::PromptFileName method.
#include
#include
#include
#include
<oledb.h>
<oledberr.h>
<msdasc.h>
<oleauto.h>
void main()
{
HRESULT
CLSID
IDBInitialize
IDataInitialize
DBPROPSET
DBPROP
OLE DB Provider for Teradata User Guide
hr;
clsid;
*pIDBInitialize = NULL;
*pIDataInitialize = NULL;
rgPropertySet[1];
rgProperties[2];
41
Chapter 2: Using OLE DB Provider for Teradata
Connecting to a Data Source Using the PromptFileName Method
WCHAR
WCHAR
*pwszUDLFile = NULL;
*pwszInitString = NULL;
//*************************************************
// Error handling is not included in this example.
//*************************************************
hr = CoCreateInstance(CLSID_DataLinks,
NULL,
CLSCTX_INPROC_SERVER,
IID_IDBPromptInitialize,
(void **)&pIDBPromptInitialize);
HWND
hwnd = GetDesktopWindow();
// Getting the path to the UDL file
hr = pIDBPromptInitialize->PromptFileName(hwnd,
DBPROMPTOPTIONS_BROWSEONLY,
L"I:\\",
L"*.udl",
&pwszUDLFile);
// Need to query interface for IDataInitialize
hr = pIDBPromptInitialize->QueryInterface(IID_IDataInitialize, (void
**)&pIDataInitialize);
// Retrieving the connection string from the UDL file
hr = pIDataInitialize->LoadStringFromStorage(pwszUDLFile,
&pwszInitString);
// Retrieving the un-initialized Data Source that is based on
// the connection string
hr = pIDataInitialize->GetDataSource(NULL,
CLSCTX_INPROC_SERVER,
pwszInitString,
IID_IDBInitialize,
(IUnknown **)&pIDBInitialize);
// Initialize the Data Source object.
hr = pIDBInitialize->Initialize();
// This is just an example and we assume S_OK was returned
//------------------------------------------------------------//
// REST OF PROGRAM …
//
//------------------------------------------------------------// Releasing all objects at the end of the program.
42
OLE DB Provider for Teradata User Guide
Chapter 2: Using OLE DB Provider for Teradata
Setting Provider String Attributes
pIDBPromptInitialize->Release();
pIDataInitialize->Release();
pIDBInitialize->Release();
}
Setting Provider String Attributes
Consumers set the provider string through the DBPROP_INIT_PROVIDERSTRING
property. Consumers use this property to set specific attributes that affect:
•
How OLE DB Provider for Teradata returns data from Teradata Database
•
How OLE DB Provider for Teradata creates the Teradata session
The consumer sets DBPROP_INIT_PROVIDERSTRING using one of the following:
•
IDBProperties::SetProperty (For more information, see “Connecting Directly to Teradata
Database” on page 23)
•
The Data Links user interface (see “Connecting Using IDBPromptInitialize Interface” on
page 33)
•
An ADO connection string method (see “Appendix B Using ADO with OLE DB Provider
for Teradata” on page 117)
Format
The required format for the provider string is:
ATTRIBUTE1=valid value;ATTRIBUTE2=valid value;…
Example
Session Mode=ANSI;Enable Parser=NO;UseXViews=NO;
Spaces and mixed case letters are permitted in attributes.
For example:
Session Mode=ANSI
or
SessionMode=ANSI
Value Limitation
Although Teradata Database allows semicolons in an account string, OLE DB Provider for
Teradata uses semicolons as separators; therefore do not use semicolons in values when using
this product. This limitation applies to all attributes, including Account String, Default
Database, and any other free-form attribute, like New Password.
If you use a semicolon in an account string, the call to IDBProperties::SetProperties returns
DB_S_ERROROCCURRED. The status of DBPROP_INIT_PROVIDERSTRING will be
DBPROPSTATUS_BADVALUE.
OLE DB Provider for Teradata User Guide
43
Chapter 2: Using OLE DB Provider for Teradata
Setting Provider String Attributes
List of Attributes
A consumer can specify several custom Teradata Database attributes in the
DBPROP_INIT_PROVIDERSTRING. The following table shows attributes supported by OLE
DB Provider for Teradata, and the valid and default values for the attributes.
Table 8: Provider String Attributes
Attribute
Valid
Values
Account String
Default Value
Programming Considerations
Empty String
Identifies an individual user account, and is associated with a
specific User ID. The account identifier can be up to 30 characters
long.
If an invalid account string is specified, Teradata Database behaves
differently under the following circumstances:
1 If the consumer specifies an invalid account string without any
leading spaces, OLE DB Provider for Teradata returns
DB_E_SEC_AUTH_FAILED when IDBInitialize::Initialize is
called. The error message returned is:
[Teradata Database]Invalid logon account
2 If the account string is not valid and it has leading spaces, OLE
DB Provider for Teradata creates the session and initialize the
Data Source. However, the account assigned to the user is the
default account specified when the user was created in Teradata
Database. The default account is not reflected in the provider
string. The account that is not valid still appears in the provider
string when the consumer calls IDBProperties::GetProperties to
retrieve the contents of DBPROP_INIT_PROVIDERSTRING.
COP Down
Retry
Any number
greater than 0
Create
N
Procedure With P
Print
15
Defines the number of minutes that OLE DB Provider for Teradata
should wait before trying to connect to a server that is down.
N
Controls whether to use the print option when creating a stored
procedure.
Use this attribute to display a stored procedure on Screen 5 of the
Database Window.
N – Excludes the SPL PRINT statements from the compiled stored
procedure.
P – Includes the SPL PRINT statements in the compiled stored
procedure.
The P option includes in the compiled stored procedure object
code all the Stored Procedure Language (SPL) PRINT statements
specified in the stored procedure body. On executing the stored
procedure, the SPL PRINT statement goes to Screen 5 of the
Database Window.
For more information on stored procedures, see “Stored
Procedures” on page 114
44
OLE DB Provider for Teradata User Guide
Chapter 2: Using OLE DB Provider for Teradata
Setting Provider String Attributes
Table 8: Provider String Attributes (continued)
Attribute
Valid
Values
Create
YES
Procedure With
NO
SPL Text
Default Value
Programming Considerations
YES
Controls whether Teradata Database stores the SPL source text (all
the SQL and SPL statements comprising the stored procedure).
YES – Store SPL Text.
NO – Do not store SPL Text.
For more information on stored procedures, see “Stored
Procedures” on page 114
Default
Database
Name of an
existing database.
Empty
Indicates the database selected when creating the session.
If the provider string does not include Default Database, Teradata
Database uses the default database specified when the Teradata
user was created.
OLE DB Provider for Teradata will not trim the leading or trailing
spaces of the database name.
If Default Database specifies an invalid database, OLE DB Provider
for Teradata still creates the Teradata session and initializes the
Data Source. However, Teradata Database uses the database
specified when the user was created to set the session. The database
used is not reflected in the provider string. The invalid database
name still appears in the provider string when the consumer calls
IDBProperties::GetProperties to retrieve the contents of
DBPROP_INIT_PROVIDERSTRING.
EnableLOBSup
port
YES
Enable Parser
YES
NO
LOBs are supported. See “Large Objects (LOBs)” on page 55 for
more information.
YES
Indicates whether to parse the SQ.
NO
NO
YES – Parse SQL
NO – Do not parse SQL.
The purpose of the parser is to:
• Handle escape sequences specified in SQL statements.
• Add the locking modifier that corresponds to the Isolation level
specified when using ITransactionLocal::StartTransaction.
For more information, see “ITransactionLocal” on page 96.
When Enable Parser is “YES”, OLE DB Provider for Teradata parses
every SQL statement. This has a negative impact on performance.
If the consumer only generates Teradata-specific SQL it is not
necessary to parse the SQL. In this case, set the Enable Parser
attribute to “NO” to improve performance.
OLE DB Provider for Teradata User Guide
45
Chapter 2: Using OLE DB Provider for Teradata
Setting Provider String Attributes
Table 8: Provider String Attributes (continued)
Attribute
Map Call-EscSeq To Exec
Valid
Values
Default Value
Programming Considerations
YES
YES
Specifies the behavior of a CALL statement that is within an escape
clause:
NO
{CALL name(p1, p2,…)}
OLE DB Provider for Teradata uses this attribute to determine
whether to call a macro or a stored procedure.
YES – OLE DB Provider for Teradata considers the name in the
escape clause to be a macro and converts the clause to:
EXEC name(p1,p2…)
NO – OLE DB Provider for Teradata considers the name in the
escape clause to be a stored procedure and converts the clause to:
CALL name(p1,p2,…)
Refer to “Stored Procedures” on page 114 for information on
stored procedure limitations.
The parser is responsible for converting escape clauses into SQL
syntax. Therefore, if the Map Call-Esc-Seq To Exec attribute is YES,
the Enable Parser attribute must also be YES. If the parser is not
enabled, OLE DB Provider for Teradata sends the unparsed escape
clause to Teradata for processing, causing a database error.
The Map Call-Esc-Seq To Exec attribute does not have any impact
on the standard CALL statement:
CALL name(p1,p2,…)
OLE DB Provider for Teradata always considers the standard CALL
statement as a stored procedure execution.
Max Response
Size
46
400–65477
8192
Specifies the initial size of the buffers OLE DB Provider for
Teradata uses to contain responses from Teradata Database. The
value is adjusted higher dynamically if a response message exceeds
the specified size.
OLE DB Provider for Teradata User Guide
Chapter 2: Using OLE DB Provider for Teradata
Setting Provider String Attributes
Table 8: Provider String Attributes (continued)
Attribute
Valid
Values
New Password
Default Value
Programming Considerations
Empty
Specifies the secondary password to use when OLE DB Provider
for Teradata detects that the original password has expired.
When the original password expires, OLE DB Provider for
Teradata does the following:
1 Logs on to Teradata using the original password.
2 Resets the password using the new password.
3 Sets the property DB_AUTH_PASSWORD with the new
password.
4 Continues with the initialization of the Data Source.
The new password is in effect for as long as the Data Source exists.
To initialize a new Data Source, the new password must replace the
original password when setting the initialization property
DB_AUTH_PASSWORD.
If the provider string does not specify a new password and the
original password expires, IDBInitialize::Initialize returns the error
code DB_SEC_E_AUTH_FAILED and with this error message:
[Teradata Database]Password has expired, please
use MODIFY USER statement to generate a new
password.
When this error occurs, there are two options to log on to Teradata
Database:
• Specify the New Password attribute in the provider string.
• Use a Teradata data access utility, such as BTEQ or SQL
Assistant, to change the password.
Number
Of Cops
0 to n
Session
Character Set
ASCII
Defines that number of cops/notes contained in the Teradata
system, where n is the number of cops/nodes. See “Load
Balancing” on page 67 for more details.
None
Specifies the default character set for the session.
KANJISJIS_0S
The setting for single-byte character sets depends on the system:
(0 is zero, not letter
O.)
• For a Kanji session, set this attribute to KANJISJIS_0S.
• For a UTF8 session, set the attribute to UTF8.
• For a UTF16 session, set the attribute to UTF16.
See “TDPROP_INIT_SESSIONCHARACTERSET” on page 102.
UTF8
UTF16
OLE DB Provider for Teradata User Guide
47
Chapter 2: Using OLE DB Provider for Teradata
Setting Provider String Attributes
Table 8: Provider String Attributes (continued)
Attribute
Valid
Values
Default Value
Programming Considerations
Session Mode
ANSI
DEFAULT
Specifies the session mode on Teradata Database. The selected
mode applies for the duration of the session.
DEFAULT
DEFAULT is used to indicate that the system default will be used.
(See “Date, Time, and Timestamp” on page 63 for more
information.) To determine the default mode, ask your database
administrator.
TERADATA
Although Teradata Database implicitly starts a transaction when a
session is in ANSI mode, OLE DB Provider for Teradata
immediately commits each request submitted to the database. This
is the default behavior when creating a session and is required by
the OLE DB specification. Consumers start transactions explicitly
by calling ITransactionLocal::StartTransaction. For more
information about Teradata and ANSI modes, see SQL Request and
Transaction Processing.
The Teradata mode exists for backward compatibility. Over the
years, a significant number of applications have been developed
using Teradata SQL syntax; therefore, the recommendation for any
new applications is to set the session mode to ANSI.
Teradata Port
Number
1025
Specifies the TCP/IP port number that the provider uses to
connect to the Teradata Gateway.
You must coordinate changes to this value with accompanying
changes to the Gateway program.
Use As Column
Name
COLUMNNAME
COLUMNTITLE
Empty
See “TDPROP_INIT_USEASCOLUMNNAME (cont.)” on
page 103.
Use X Views
YES
YES
Specifies whether to use the X view or the standard view version of
the data dictionary table. For more information on X Views, see
the Data Dictionary.
NO
YES – Teradata Database uses X view database dictionary tables
DBC.TablesX and DBC.ProceduresX when retrieving information
for the schema rowsets: Tables, Procedures, and Schemata.
NO – Teradata Database uses the DBC.Tables and DBC.Procedures
data dictionary tables.
Normally, both versions of the data dictionary views are installed
on a Teradata system. However, a database administrator can
choose to install either version or both versions. Ask your
administrator which version is installed on your Teradata
Database.
Error Handling
If the provider string contains an invalid attribute or value, the call to
IDBProperties::SetProperties returns the DB_E_ERROROCCURRED error code, and OLE
DB Provider for Teradata sets the status corresponding to
DBPROP_INIT_PROVIDERSTRING to DBPROPSTATUS_BADVALUE.
48
OLE DB Provider for Teradata User Guide
Chapter 2: Using OLE DB Provider for Teradata
Changing Data
Changing Data
There are two ways to change data:
•
Using Data Manipulation Language (DML) statements (such as DELETE, INSERT, and
UPDATE)
•
Using Rowsets and the IRowsetChange or IRowsetUpdate interfaces.
Changing Data Using DML Statements
When using DML, the consumer does the following:
•
Generates the correct SQL statements
•
Specifies the correct data values
To change data using DML statements
After generating the SQL and specifying the data values, follows these steps:
1
(Optional) Start a transaction using ITransactionLocal::StartTransaction.
Note: If the consumer does not start a transaction, then OLE DB Provider for Teradata
automatically commits the work after each call to ICommand::Execute.
2
If parameters are used in the DML statement, create the Accessor using
IAccessor::CreateAccessor.
3
If parameters are used in the DML statement, bind the data values.
4
Set the command text using ICommandText::SetCommandText.
5
Prepare the command using ICommandPrepare::Prepare.
Note: Preparing the command, is also optional. A DML statement can be immediately
executed after the text of the command object has been set.
6
Execute the command using ICommand::Execute.
7
(Optional) Commit the transaction using ITransaction::Commit.
Note: If the consumer does not start a transaction, then OLE DB Provider for Teradata
automatically commits the work after each call to ICommand::Execute.
Performance Considerations
For optimal performance:
•
Prepare the request before execution. Teradata Database will parse the SQL request and
store this information in the request cache. When the consumer repeatedly calls
ICommand::Execute to process the same request but with different data values, the
Teradata Database reuses the cached request. For more information about the request
cache, see SQL Request and Transaction Processing.
•
Manually start a transaction by calling ITransactionLocal::StartTransaction. After
executing the statement with data for the last set of parameters, end the transaction by
OLE DB Provider for Teradata User Guide
49
Chapter 2: Using OLE DB Provider for Teradata
Changing Data
calling ITransaction::Commit. This prevents Teradata Database from performing a
commit after each call to ICommand::Execute.
Note: A more efficient way to insert, update, and delete multiple rows is to use Parameter Sets.
See “Using Multiple Parameter Sets” on page 66 for more information.
Changing Data Using Rowset Objects
A consumer can change data through rowset objects. OLE DB Provider for Teradata generates
the DELETE, INSERT or UPDATE statement that is used to modify the data of the underlying
table. The WHERE clause (for DELETE and UPDATE) identifies the rows.
After a consumer generates a rowset, the consumer changes the data through either the
IRowsetChange (immediate mode) or the IRowsetUpdate (deferred mode) interface.
Setting Rowset Properties
To update through a rowset under OLE DB Provider for Teradata, the consumer must set the
rowset properties as follows:
Table 9: Setting Rowset Properties
Property
Value
DBPROP_UPDATABILITY
DBPROPVAL_UP_CHANGE
DBPROPVAL_UP_DELETE
DBPROPVAL_UP_INSERT
DBPROP_IRowsetChange
TRUE
DBPROP_IRowsetUpdate
TRUE for deferred update mode
FALSE for immediate update mode
Unsearchable Columns
In order to update using a rowset object, searchable columns must exist in the rowset. Rowsets
that only contain columns that are unsearchable cannot be updated. Columns that are of the
following data types are unsearchable:
•
DOUBLE/FLOAT/REAL
•
BYTE
•
VARBYTE
If a rowset only contains columns that are unsearchable E_FAIL is returned when
IRowset::GetNextRows is called and the following error message is generated:
Query cannot be updated because it contains no searchable columns to use
as a key.
Rowset Restrictions
50
•
The rowset must have at least one searchable column.
•
The rowset must have been generated from a call to either:
OLE DB Provider for Teradata User Guide
Chapter 2: Using OLE DB Provider for Teradata
Changing Data
•
IOpenRowset::OpenRowset
•
ICommand::Execute
•
When ICommand::Execute is used, the specified SELECT statement must only contain
one table or view in the FROM clause. The SELECT statement can also contain a WHERE
clause.
•
A semicolon should not be used to terminate a SELECT statement that does not contain a
WHERE clause.
Example of proper format:
SELECT column1 from table1
•
If a semicolon terminates the SELECT statement, the call to IRowset::GetNextRows
returns the E_UNEXPECTED response with this error message:
[OLE DB Provider for Teradata]Query cannot be updated because FROM
clause is not a single simple table name.
•
Columns should not have alias names specified in the SELECT list. OLE DB Provider for
Teradata uses the alias as the column name when it generates the DML to update the
database. This causes an E_FAIL to be returned from a call to a method in the
IRowsetChange interface, and the following error message is generated:
[Teradata Database]Column/Parameter <column alias> does not exist.
For example, OLE DB Provider for Teradata is not able to update the rowset generated
from the following SELECT statement:
SELECT ItemNo, Description AS ItemDesc, PackageType AS PkgType FROM
ItemTable
FLOAT, REAL, DOUBLE Restriction
OLE DB Provider for Teradata does not use columns of type FLOAT, REAL, and DOUBLE in
the WHERE clause. This restriction might have unintended consequences.
When the desired rowset contains a column of type FLOAT, REAL or DOUBLE, include the
primary key of the underlying table in the SELECT statement. If you do not include the key,
several other rows can be affected unintentionally.
Example 1
In the Item table, the Price column is type FLOAT.
Table 10: Price Column
Item No
(INTEGER) PK
Description
(VARCHAR)
Package Type (VARCHAR)
Price
(FLOAT)
1
Peas
1 can
1.21
2
Carrots
1 can
1.30
3
Soda
6 pack
3.00
4
Potatoes
1 sack
2.40
5
Ham
1 can
6.54
OLE DB Provider for Teradata User Guide
51
Chapter 2: Using OLE DB Provider for Teradata
Changing Data
Table 10: Price Column (continued)
Item No
(INTEGER) PK
Description
(VARCHAR)
Package Type (VARCHAR)
Price
(FLOAT)
6
Soda
12 pack
5.50
The consumer submits the following SELECT statement that does not contain the primary key
column:
SELECT Description, Price FROM Item
The rowset that returns from ICommand::Execute is:
Table 11: Rowset Return from ICommand::Execute
Row Handle
Description
Price
0x1
Peas
1.21
0x2
Carrots
1.30
0x3
Soda
3.00
0x4
Potatoes
2.40
0x5
Ham
6.54
0x6
Soda
5.50
Assume the user wants to increase the price of a six-pack of Soda to $3.25.
The consumer uses IRowset::SetData to update the Price in the row containing Row Handle
0x3 from 3.00 to 3.25. The SQL that OLE DB Provider for Teradata submits to Teradata
Database is similar to:
UPDATE Item SET Price = ? WHERE Description = ?
Soda is bound to the Description column in the FROM clause, and 3.25 is bound to the Price
column.
The UPDATE statement has the following effect on the Item table:
Table 12: Table after Update
52
Item No
(INTEGER) PK
Description
(VARCHAR)
Package Type (VARCHAR)
Price
(FLOAT)
1
Peas
1 can
1.21
2
Carrots
1 can
1.30
3
Soda
6 pack
3.25
4
Potatoes
1 sack
2.40
5
Ham
1 can
6.54
OLE DB Provider for Teradata User Guide
Chapter 2: Using OLE DB Provider for Teradata
Changing Data
Table 12: Table after Update (continued)
Item No
(INTEGER) PK
Description
(VARCHAR)
Package Type (VARCHAR)
Price
(FLOAT)
6
Soda
12 pack
3.25
The intention was to only update the six-pack price in the row of ItemNo = 3. However,
because Soda is bound to the Description column, this SQL statement updates rows with Item
No 3 and 6 in the underlying table.
A usual practice is to specify Price in the UPDATE statement WHERE clause, to restrict the
update to the six-pack price. However, OLE DB Provider for Teradata did not include Price in
the WHERE clause because Price is type FLOAT in the underlying table. OLE DB Provider for
Teradata does not use columns of type FLOAT, REAL, and DOUBLE in the WHERE clause. To
solve this problem, you should always include the primary key in the SELECT statement that
creates the rowset:
SELECT ItemNo, Description, Price from Item
The rowset that returns from ICommand::Execute is:
Table 13: Rowset Return Using Primary Key
Row Handle
ItemNo
Description
Price
0x1
1
Peas
1.21
0x2
2
Carrots
1.30
0x3
3
Soda
3.00
0x4
4
Potatoes
2.40
0x5
5
Ham
6.54
0x6
6
Soda
5.50
The ItemNo primary key column is now available in the rowset. The unique ItemNo can
identify the row instead of the non-unique soda description.
The consumer uses IRowsetChange::SetData to update the Price in the row with the Row
Handle 0x3. OLE DB Provider for Teradata generates the UPDATE statement:
UPDATE Item SET Price = ? WHERE Description = ? and ItemNo = ?
This statement uniquely identifies the target row. Teradata Database only updates the six-pack
Soda price.
Recommendations
When you update rowsets, the following is recommended:
•
Always include the primary key in the rowset.
OLE DB Provider for Teradata User Guide
53
Chapter 2: Using OLE DB Provider for Teradata
Comparing DML with IRowsetChange/IRowsetUpdate
•
Avoid using columns of type FLOAT, REAL or DOUBLE if there is no primary key in the
rowset.
For more information on using IRowsetChange and IRowsetUpdate to change data, refer to
the Microsoft Developer’s Network (MSDN) documentation on Changing Data. See
“Technical Assistance” on page 20.
•
MSDN Library - See http://msdn.microsoft.com/library/
•
OLE DB Programmer’s Guide
•
Part 1: Introduction to OLE DB
•
Chapter 5: Updating Data in Russets
•
Changing Data
Comparing DML with IRowsetChange/
IRowsetUpdate
The decision to use DML statements or the IRowsetChange/IRowsetUpdate interface should
be based on the functionality the consumer requires. For example:
Table 14: Deciding to Use DML Statements or IRowsetChange or IRowsetUpdate
If the Consumer...
and the Consumer...
then the Consumer should use...
displays an interface that
shows rows from a single
table,
allows a user to specify what
rows to update or delete,
the IRowsetChange or
IRowsetUpdate interface.
generates data values,
inserts these values into
several different tables,
DML statements.
The following table lists the advantages and disadvantages of each approach. In the table,
“update” refers to inserting, updating, or deleting rows.
Table 15: Advantages of Using DML Statements or IRowsetChange or IRowsetUpdate
54
Using DML
Using IRowsetChange / IRowsetUpdate
The SQL is either hard coded or logic must exist
in the consumer to dynamically create the DML
statements.
OLE DB Provider for Teradata generates DML
statements.
There is possibly less overhead. The consumer
does not have to create a rowset before updating
the data.
The consumer must create a rowset before
updating the underlying table.
The consumer can generate several different
DML statements that update different tables or
views.
The rowset to be updated can only derive from a
single table or view. Therefore, the consumer can
update only the single underlying table or view.
OLE DB Provider for Teradata User Guide
Chapter 2: Using OLE DB Provider for Teradata
Large Objects (LOBs)
Table 15: Advantages of Using DML Statements or IRowsetChange or IRowsetUpdate (continued)
Using DML
Using IRowsetChange / IRowsetUpdate
The consumer is responsible for caching updates
to a table and then generating statements to
perform updates.
OLE DB Provider for Teradata caches updates
made to the rowset when methods in the
IRowsetUpdate interface are called. OLE DB
Provider for Teradata submits all the changes to
Teradata Database when IRowsetUpdate::Update
is called.
The consumer has total control of the DML
statements.
OLE DB Provider for Teradata is limited to the
columns included in the rowset when generating
the WHERE clause of the DML statement.
Columns of type FLOAT will not be included in
the WHERE clause. This may cause unexpected
rows to be updated. For more details, refer to
“FLOAT, REAL, DOUBLE Restriction” on page 51.
Large Objects (LOBs)
OLE DB Provider for Teradata and Teradata Database support large objects (LOBs), which
include:
•
Binary large objects (BLOBs)
•
Character large objects (CLOBs)
LOBs can be inserted, updated, or retrieved from a Teradata data source by using parameters
or storage objects.
Using Storage Objects
Storage objects can be specified in a parameter or rowset accessor. OLE DB Provider for
Teradata only supports the ISequentialStream interface.
BLOB/CLOB Limitations
The following is a list of BLOB and CLOB limitations.
•
LOB columns cannot be updated through rowset objects.
•
Random order is not supported (i.e. DBPROP_ACCESSORORDER cannot be set to
DBPROPVAL_AO_RANDOM).
•
For a rowset, only one LOB column can be bound to a storage object in an accessor.
•
If a LOB column in a rowset is to be bound to a storage object, it must be the highest
numbered ordinal in the binding of the accessor.
•
LOB columns are not searchable.
•
DB_E_BADSTORAGEFLAG when IRowset::GetData is called if a LOB column has been
bound with type defined as DBTYPE_IUNKNOWN, and IID_ISequentialStream specified
with write access.
OLE DB Provider for Teradata User Guide
55
Chapter 2: Using OLE DB Provider for Teradata
Large Objects (LOBs)
•
The IStream interface is not supported. Only the ISequentialStream interface is supported.
UTF8 and LOBs
OLE DB Provider for Teradata reports incorrect values for the sizes of columns of the
CHAR(n) data type when the session character set used is UTF8 and LOB support is not
enabled. To help alleviate this shortcoming, OLE DB Provider for Teradata automatically
enables LOB support when a connection is established (during processing of
IDBInitialize::Initialize()) when all of the following are true:
•
The selected session character set is UTF8.
•
The connection is to Teradata DatabaseV2R5.1 or greater.
•
The EnableLOBSupport provider string attribute has not been specified with a value of
NO.
An OLE DB provider rowset and command objects return column size information in the
ulColumnSize field of the DBCOLUMNINFO structures returned by
IColumnsInfo::GetColumnInfo() and in the DBCOLUMN_COLUMNSIZE column of the
“column metadata rowset” (created by calling IColumnsRowset::GetColumnsRowset()). For
columns of the CHAR(n) data type, this column size is n (the number of characters in the
column) so that is what should be returned.
However, when the UTF8 session character set is used and LOB support is not enabled,
instead of returning n, OLE DB Provider for Teradata returns the number of bytes in the
Teradata external representation of the data type. This value depends upon the server
character set type and the database's export width table ID as shown in the following table.
For more information on export width rules, see International Character Set Support:
Table 16: Export Width
Export Width Table ID
Data Type
0 (Expected Default)
1 (Compatibility Default)
2 (Maximum Default)
Char(n) Character SET UNICODE
3*n
3*n
3*n
Char(n) Character SET LATIN
2*n
2*n
3*n
Char(n) Character SET KANJISJIS
n
n
3*n
Char(n) Character SET GRAPHIC
3*n
3*n
3*n
56
OLE DB Provider for Teradata User Guide
Chapter 2: Using OLE DB Provider for Teradata
Large Objects (LOBs)
Properties Associated with BLOBs and CLOBs
Table 17: BLOB and CLOB Properties
Property
Comments
DBPROP_ACCESSORORDER
Current Setting:
READ-WRITE,
DBPROPVAL_AO_SEQUENTIALSTORAGEOBJE
CT
Used to specify the order in which columns must be
accessed by methods that operate on rowsets.
OLE DB Provider for Teradata only supports
DBPROPVAL_AO_SEQUENTIALSTORAGEOBJE
CT.
DBPROP_DELAYSTORAGEOBJECT
Current Setting:
READ-ONLY
VARIANT_FALSE
Determines whether LOBs can be used in deferred
update mode.
VARIANT_FALSE indicates that LOB columns will
be updated immediately even when in deferred
mode.
DBPROP_MULTPLESTORAGEOBJECTS
Current Setting:
READ-ONLY
VARIANT_FALSE
Determines whether multiple storage objects can
be opened at the same time.
VARIANT_FALSE indicates only one storage object
can be opened.
DBPROP_BLOCKINGSTORAGEOBJECT
Current Setting:
READ-ONLY
VARIANT_TRUE
Determines whether storage objects will prevent
the use of other methods on the rowset between the
time the object has been created and released.
VARIANT_TRUE indicates instantiated storage
objects might prevent the use of other methods on
the rowset.
DBPROP_UPDATABILITY
DBPROP_IRowsetChange
DBPROP_IRowsetUpdate
OLE DB Provider for Teradata User Guide
These properties control whether data in a rowset
can be updated. LOBs are not supported when
updating through a rowset object; therefore, these
properties have no affect on LOBs.
57
Chapter 2: Using OLE DB Provider for Teradata
User-Defined Functions (UDFs)
User-Defined Functions (UDFs)
OLE DB Provider for Teradata and Teradata Database support user-defined functions (UDFs),
including the execution of DDLs to create UDFs and DMLs that use UDFs.
For the full discussion of the syntax, format, and rules for creating and invoking UDFs, see the
SQL External Routine Programming manual.
Creating UDFs
The same restrictions described in the Teradata Database manuals apply to creating and using
UDFs with OLE DB Provider for Teradata.
Compilation Messages
When creating a UDF, several compilation messages are generated by OLE DB Provider for
Teradata, however, the method ICommand::Execute returns S_OK. The IErrorRecords
interface can be used to view these compilation messages.
Compilation Errors
Errors that occur when compiling a UDF are returned through the IErrorRecords interface.
These messages are mixed with the compilation messages. When a compilation error does
occur, ICommand::Execute returns an E_FAIL.
UDF Files
The file specified in the DDL used to create a UDF must reside on a Teradata node. If this file
is contained on a client machine, the call to the method ICommand::Execute returns an
E_FAIL.
Example of User-Defined Functions
The following example shows how to create, rename, and delete a UDF. The source code for
the function must exist in the server node. An error occurs if a local file is used.
For this example, the file udf01.c must exist in the /tmp directory on the server teradata1. It's
contents are:
void udf01(int i,int* result,char exception[6])
{
*result = i +1;
return ;
}
The DDL statements as described in Chapter 4 of the SQL External Routine Programming
manual are executed using ICommand::Execute. Any compilation errors can be retrieved
using the IErrorInfo, IErrorRecords, and ISQLErrorInfo interfaces.
58
OLE DB Provider for Teradata User Guide
Chapter 2: Using OLE DB Provider for Teradata
User-Defined Functions (UDFs)
Program Listing
//Create Statement
const WCHAR wszUDFCreateStmt[]=
L"REPLACE FUNCTION udf01(INTEGER) \
RETURNS INTEGER \
LANGUAGE C \
NO SQL \
PARAMETER STYLE SQL \
EXTERNAL NAME \
'SS!udf01!/tmp/udf01.c'";
//file must reside on server node
//Delete Statement
const WCHAR wszUDFDeleteStmt[] = L"DROP FUNCTION udf01; ";
//Rename Statement
const WCHAR wszUDFRenameStmt[] = L"RENAME function udf01 to udf0001; ";
void UDFOperations (ICommand *pICommand)
{
ICommandText*pICommandText = 0;
HRESULT hResult = S_OK;
//creating Command Text
pICommand->QueryInterface(IID_ICommandText, (void **)&pICommandText);
//-------------//
Going to CREATE the UDF
hResult = m_pICommandText->SetCommandText(DBGUID_DEFAULT, UDFCreateStmt);
if (hResult != S_OK)
goto CLEANUP;
hResult = m_pICommand->Execute(NULL, IID_NULL, NULL, &cRowsAffected, NULL);
if (hResult != S_OK)
goto CLEANUP;
//-------------//-------------//
Going to RENAME the UDF
hResult = m_pICommandText->SetCommandText(DBGUID_DEFAULT, UDFRenameStmt);
if (hResult != S_OK)
goto CLEANUP;
hResult = m_pICommand->Execute(NULL, IID_NULL, NULL, &cRowsAffected, NULL);
if (hResult != S_OK)
goto CLEANUP;
//-------------//-------------//
Going to DELETE the UDF
hResult = m_pICommandText->SetCommandText(DBGUID_DEFAULT, UDFDeleteStmt);
if (hResult != S_OK)
goto CLEANUP;
OLE DB Provider for Teradata User Guide
59
Chapter 2: Using OLE DB Provider for Teradata
User-Defined Types and User-Defined Methods
hResult = m_pICommand->Execute(NULL, IID_NULL, NULL, &cRowsAffected, NULL);
if (hResult != S_OK)
goto CLEANUP;
//-------------CLEANUP:
//--------------------------------------------------------// See Chapter 4 for more details about Error Messages
//--------------------------------------------------------if (pICommandText)
pICommandText->Release();
}
User-Defined Types and User-Defined Methods
User-defined types (UDTs) and user-defined methods (UDMs) are supported. For a full
discussion, see the SQL External Routine Programming manual.
Using UDTs
Each UDT has an associated external type, which is always a predefined Teradata Database
type. As the values of a UDT are transferred from Teradata Database to OLE DB Provider for
Teradata, the database automatically converts the UDT values to the external type.
For example:
Assume that a table named EMPLOYEE exists, and that the table has a column named
EmpSalary of type DOLLAR, where DOLLAR is a UDT with an associated external type of
DECIMAL(15,2). Then, if an OLE DB consumer has OLE DB Provider for Teradata execute a
command with text “SELECT EmpSalary FROM EMPLOYEE”, then the column in the
resulting rowset object will be of type DBTYPE_NUMERIC, not DBTYPE_UDT.
Also, when sending values for a UDT type from OLE DB Provider for Teradata to Teradata
Database, Teradata Database automatically converts the values from the external type.
While UDT values are transferred to and from Teradata Database using the external type,
UDTs are visible as UDTs in the OLE DB Provider for Teradata schema rowsets.
Using UDMs
Use UDMs in a similar fashion to user-defined functions. For more information, see “UserDefined Functions (UDFs)” on page 58.
Schema Rowsets
UDTs and UDMs are visible through OLE DB Provider for Teradata schema rowsets as shown
in the following table:
60
OLE DB Provider for Teradata User Guide
Chapter 2: Using OLE DB Provider for Teradata
BIGINT and Large DECIMALs
Table 18: UDT and UDM Visibility
Schema Rowset
Description
TABLES
Contains one row for each UDT.
These rows have the provider-specific value “TYPE” in the
TABLE_TYPE column and the name of the UDT in the
TABLE_NAME column.
COLUMNS
Rows corresponding to columns containing UDTs have the
DBTYPE_UDT type indicator in their DATA_TYPE column.
Also, the DBCOLUMNFLAGS_ISFIXEDLENGTH bit is not set in
the COLUMN_FLAGS column for these rows.
PROCEDURES
Contains one row for each UDM.
These rows have the PROCEDURE_TYPE column set to
DB_PT_FUNCTION.
PROCEDURE_PARAMETERS
Rows corresponding to UDTs have the DBTYPE_UDT type
indicator in their DATA_TYPE column.
Also, the name of the UDT is placed into the TYPE_NAME
column.
Restrictions
In order to create a UDM by issuing a DDL statement (such as a CREATE METHOD...)
through OLE DB Provider for Teradata, the file specified in the DDL (for example, the file
containing the source code to the UDM) must reside on the Teradata Database node. If this file
is instead located on a client system, then the call to ICommand::Execute() (to execute the
DDL) returns E_FAIL.
BIGINT and Large DECIMALs
Teradata Database supports a signed 64-bit integer data type known as BIGINT. The
maximum number of digits supported by Teradata Database for the DECIMAL data type is
38.
OLE DB Provider for Teradata supports these data type enhancements. When accessing
Teradata Database, a row appears in the PROVIDER_TYPES schema rowset for the BIGINT
data type. The COLUMN_SIZE and MAXIMUM_SCALE fields of the row for the DECIMAL
type contain 38.
IDBInfo::GetKeywords() returns "BIGINT" no matter which version of Teradata Database is
being accessed.
OLE DB Provider for Teradata User Guide
61
Chapter 2: Using OLE DB Provider for Teradata
BIGINT and Large DECIMALs
62
OLE DB Provider for Teradata User Guide
CHAPTER 3
Programming Considerations
This chapter describes some of the programming considerations that affect consumer design.
The topics are:
•
Date, Time, and Timestamp
•
INTEGER FORMAT ’99:99:99’ Columns
•
Using Multiple Parameter Sets
•
Load Balancing
Date, Time, and Timestamp
OLE DB Provider for Teradata uses the ANSI representation of the Date, Time, and
Timestamp. Therefore, if a consumer submits the following Data Definition Language (DDL)
statement:
CREATE TABLE Teradata1.DateTime_Test (
Ts TIMESTAMP,
Ti TIME,
Dt DATE
PRIMARY INDEX (Ts));
to Teradata Database through OLE DB Provider for Teradata, the table has the following
definitions in Teradata Database:
CREATE SET TABLE Teradata1.DateTime_Test ,NO FALLBACK ,
NO BEFORE JOURNAL,
NO AFTER JOURNAL
(
Ts TIMESTAMP(6),
Ti TIME(6),
Dt DATE FORMAT 'YYYY-MM-DD')
PRIMARY INDEX ( Ts ));
Precision
When the precision is not specified, Teradata Database defaults to creating the table with the
maximum precision for both TIME and TIMESTAMP.
Date Column Format Restriction
If the Dt column shown above has a format other than ‘YYYY-MM-DD’
for example, ‘YY-MM-DD’
OLE DB Provider for Teradata User Guide
63
Chapter 3: Programming Considerations
INTEGER FORMAT ’99:99:99’ Columns
and the consumer uses the following SELECT statement that does not have the format clause:
SELECT Ts, Ti, Dt FromTeradata1.DateTime_Test
and the consumer calls either:
•
IColumnsInfo::GetColumnsInfo
•
ColumnsRowset::GetColumnsRowset
then OLE DB Provider for Teradata reports that this column is of type DBTYPE_STR.
Tables that contain date columns with other date formats cannot be updated using
IRowsetChange or IRowsetUpdate. If the consumer uses any method of either interface, the
call returns the DB_E_ERRORSOCCURRED error code and OLE DB Provider for Teradata
presents the following error message:
[OLE DB Provider for Teradata]Multiple-step OLE DB operation generated
errors. Check each OLE DB status value. No work was done.
Work Around
If the purpose is to update a table, the consumer is responsible for either:
•
Generating the proper DML statement
•
Modifying the SELECT statement that created the rowset
Example:
SELECT Ts, Ti, Dt (FORMAT ‘YYYY-MM-DD’) FROM Teradata1.DateTImeTest
For more information on Teradata Date, Time and Timestamps, refer to SQL Data Types and
Literals.
INTEGER FORMAT ’99:99:99’ Columns
Data Type Restriction
If a table contains a column that has a data type of INTEGER with a format of ‘99:99:99’
(column definition is INTEGER FORMAT ‘99:99:99’), OLE DB Provider for Teradata
interprets the data type of this column as DBTYPE_DBTIME.
IRowsetChange is unable to update a rowset that contains a column defined as INTEGER
FORMAT ‘99:99:99’. OLE DB Provider for Teradata reports that this column is of type
DBTYPE_DBTIME. When one of the methods of IRowsetChange is called, the data for this
column is type cast to TIME. The actual data type of the column is INTEGER. This causes the
following Teradata error:
[Teradata Database]Invalid operation on an ANSI DateTime or Interval
value.
Example
Assume the rowset is:
64
OLE DB Provider for Teradata User Guide
Chapter 3: Programming Considerations
INTEGER FORMAT ’99:99:99’ Columns
Table 19: Rowset (ServiceHistory Table)
CustomerNo
(Integer
CarMaker
(CHAR(20))
CarModel
(CHAR(20))
DateLastServiced
(DATE)
TimeLastService
(INTEGER
FORMAT
99:99:99)
0001
Ford
Expedition
10/20/2001
10:10:45
0002
Chevrolet
Corvette
12/01/2001
09:43:10
0003
Toyota
Corolla
05/05/2001
11:34:32
0004
Honda
S2000
09/12/2001
15:32:22
If the consumer uses the method IRowsetChange::SetData to update the CarModel column
for Customer 0004, the generated SQL is as follows:
UPDATE ServiceHistory SET CarModel=’Accord’
WHERE CustomerNo=? AND CarMaker=? AND CarModel=? AND
DateLastServiced=cast (? AS DATE) AND TimeLastService=cast(? AS TIME)
Casting the parameter to TIME when compared against the TimeLastService column in the
WHERE clause causes Teradata to generate the above error message.
If IRowsetChange::DeleteRows is called, the same WHERE clause is generated for the DELETE
statement. This causes the same problem to occur.
When IRowsetChange::InsertRow is called the following SQL statement is generated:
INSERT INTO ServiceHistory (CustomerNo, CarMaker, CarModel,
DateLastServiced, TimeLastService)
VALUES (?, ?, ?, (? AS DATE), (? AS TIME))
In this case, casting the data to TIME in the VALUES clause also causes the above error to be
generated.
Work Around
To work around this problem, use the SQL statement (DELETE, INSERT, UPDATE) and the
ICommand, IAccessor, and ICommandWithParameter interfaces to update the table.
Remedy
When using time, take advantage of the Teradata TIME data type.
OLE DB Provider for Teradata User Guide
65
Chapter 3: Programming Considerations
Using Multiple Parameter Sets
Using Multiple Parameter Sets
Required Actions Before ICommand::Execute
Before Calling ICommand::Execute;
When using more than one parameter set, OLE DB Provider for Teradata requires the
consumer to perform the following steps before calling ICommand::Execute:
1
Set the text of the command object using ICommandText::SetCommandText.
2
Define the data types for each parameter using
ICommandWithParameters::SetParameterInfo.
3
Create the Accessor using IAccessor::CreateAccessor.
If the above steps are not followed, the call to ICommand::Execute returns the
DB_E_PARAMNOTOPTIONAL error code and OLE DB Provider for Teradata presents
the following error message:
[Teradata Database]There is a mismatch between the number of
parameters specified and the number of parameters
Unprepared Commands Required
When using multiple parameter sets, do not prepare commands before execution. If the
consumer calls the ICommandPrepare::Prepare method and then executes
ICommand::Execute, OLE DB Provider for Teradata returns the error code and error message
described above.
Retrieving Column Information
Because the command is not prepared, the consumer must wait until after command
execution to retrieve information about any columns returned. The consumer must query the
IColumnsInfo and IColumnsRowset interfaces from the Rowset object. If the consumer
queries these interfaces from the Command object after execution, any method the consumer
calls returns the DB_E_NOTPREPARED error code.
Retrieving Column Information
However, if it is necessary to process column information before executing the SQL, the
consumer can perform the following steps, which are in addition to the tasks listed previously
in “Required Actions Before ICommand::Execute” on page 66.
66
1
Prepare the command using ICommandPrepare::Prepare.
2
Query either IColumnsInfo or IColumnsRowset from the Command Object.
3
Retrieve the column information using methods contained in IColumnsInfo or
IColumnsRowset retrieved in step 2.
4
Unprepare the command using ICommandPrepare::UnPrepare.
OLE DB Provider for Teradata User Guide
Chapter 3: Programming Considerations
Load Balancing
Note: It is important to unprepare the command prior to execution. If this is not done,
ICommand::Execute returns the error code DB_E_PARAMNOTOPTIONAL.
Load Balancing
Load balancing is an attempt to distribute connections among all the COPs of a Teradata
server, rather than only using COP 1.
The basic scheme is:
•
If the data source is a specific IP address, then OLE DB Provider for Teradata will only use
that address for a connection. Both IPv6 and IPv4 addresses are supported.
•
If the data source is a specific COP, for example vadorcop1, OLE DB Provider for Teradata
will only try to connect to that COP. However, all of the IP addresses defined for that COP
(both IPv6 and IPv4) will be queried and all of those addresses will be used if necessary to
connect to the COP.
•
If the data source is the name of a Teradata server, then OLE DB Provider for Teradata's
actions are based on the setting of the NumberOfCOPs attribute:
Table 20: Load Balancing
IF the...
then...
NumberOfCOPs is not set
OLE DB Provider for Teradata attempts to connect to the data
source name, and if necessary, the server's first COP.
All of the known IP addresses (both IPv6 and IPv4) for those two
are used in trying to make a connection.
NumberOfCOPs > 0
OLE DB Provider for Teradata chooses a COP at random on the
first connection attempt; on successive connection attempts, it
chooses the next COP in sequence.
For each COP, only the first known IP address is used. If both
IPv6 and IPv4 addresses are known, only the first known IPv6
address is used.
If a COP is known to be down, it is skipped unless the time
period given by the COPDownRetry attribute has expired.
Note: The COP definitions is retained for the life of OLE DB
Provider for Teradata.
NumberOfCOPs is zero
Load balancing is disabled. OLE DB Provider for Teradata only
attempts to connect to the specified server name.
The specific COP names are not used, and all known IP
addresses (both IPv6 and IPv4) for the name are used in
attempting a connection.
Note: This option is more limited than not specifying
NumberOfCOPs; for that option OLE DB Provider for Teradata
also tries to use the name of the first COP.
OLE DB Provider for Teradata User Guide
67
Chapter 3: Programming Considerations
Load Balancing
The following issues occur when utilizing load balancing with DNS Round Robin on clients
running on Windows 2000 based (Professional, Server, Advanced Server and Datacenter
Server) systems:
•
Implementation of a client-side DNS cache
•
DNS caching problem with Windows 2000 and Windows Server 2003
Implementation of a Client-side DNS Cache
All Windows 2000 systems internally implement a client-side DNS cache, which in effect
defeats the external load balancing features of DNS round robin. They cache the IP addresses
rather than re-querying the DNS server for the target address. For more information on this
problem in Windows 2000, please reference Microsoft Knowledge Base Article 245437.
The fix mentioned in the article does not disable DNS caching, but only limits the time
interval for maintaining addresses within the cache to one second. If the change in the article
is made and if multiple requests for a system or node are made within the one second
timeframe, the same IP address(es) will be returned.
DNS Caching Problem with Windows 2000
There is a Microsoft problem in client-side DNS caching if the client is running a version of
Windows 2000 earlier than Service Pack 3. This problem is explained in Microsoft Knowledge
Base article 276324.
These problems do not appear in any other version of Windows.
OLE DB Provider for Teradata String Attributes
The following string attributes support load balancing:
68
OLE DB Provider for Teradata User Guide
Chapter 3: Programming Considerations
Load Balancing
Table 21: String Attributes
String Attribute.
Description
NumberOfCOPs
Valid values: any numeric value, 0 to n.
Default value: none
Specifies how many COPs are defined for the data source name being
connected. If this attribute is not given, OLE DB Provider for Teradata only
attempts to connect to the server or the server's first COP.
If multiple IP addresses (including both IPv6 and IPv4 addresses) exist for the
server or its first COP, OLE DB Provider for Teradata uses all of those
addresses in attempting to connect to the data source.
If a value of zero is given for this attribute, OLE DB Provider for Teradata only
attempts to connect to the given data source name.
If multiple IP addresses (including both IPv6 and IPv4) are known for the
name, all are used in the attempt to connect to the server.
If a value greater than zero is given, OLE DB Provider for Teradata assumes
there are that many COPs defined for the server.
On the first connection to the server, a random COP is chosen. For successive
connection attempts, the next COP numbers in sequence is used, with the
numbers wrapping around to one as needed.
COP Down Retry
Valid values: any numeric value, greater than zero.
Default value: 15
Specifies how many minutes OLE DB Provider for Teradata should wait before
trying to connect to a server that is down.
This attribute is only used when NumberOfCOPs > 0 and the data source is a
server name, not an IP address or the name of a specific COP.
OLE DB Provider for Teradata User Guide
69
Chapter 3: Programming Considerations
Load Balancing
70
OLE DB Provider for Teradata User Guide
CHAPTER 4
Error Messages
This chapter describes how to handle error messages. Topics included are:
•
Source of an OLE DB Error
•
Structure of an OLE DB Error
•
Retrieving the Error
•
SQLState
•
Native Error Codes
•
Teradata Database Error Format
•
Teradata Database Messages
•
Error Format
•
Visual C++ Example
•
Visual Basic with ADO
Source, Format and Structure of Error
Messages
Source of an OLE DB Error
OLE DB Provider for Teradata generated error messages can originate from two sources:
•
Teradata Database
•
Provider
Depending on where the message originated, the format of the message text is different.
Structure of an OLE DB Error
An OLE DB error has the following structure:
OLE DB Provider for Teradata User Guide
71
Chapter 4: Error Messages
Source, Format and Structure of Error Messages
Figure 5: OLE DB Error Structure
Error Object
Error Record 1
IErrorInfo
Error Record 1
IErrorRecords::GetCustomErrorObject
IErrorRecords
ISQLErrorInfo
Custom Error Object
Error Record N
SQLState
Native Error Code
KK01A001
A consumer can retrieve information about the error using the IError interface.
A consumer can retrieve errors returned from Teradata Database through the Custom Error
Object via the ISQLErrorInfo interface. Using methods of this interface, the consumer can
retrieve the SQLState and Native Error Code of the error generated by Teradata Database.
Retrieving the Error
To retrieving an error
A consumer can retrieve information about errors generated by Teradata Database or the
provider by performing these steps:
1
Call the automation method GetError. This returns an interface to IErrorInfo.
2
Use the interface to IErrorInfo to query the IErrorRecords Interface.
3
Loop through the records returned from IErrorRecords and make calls to the following
methods:
4
5
72
•
IErrorRecords::GetCustomErrorObjects. See step 4 and step 5.
•
IErrorRecords::GetBasicInfo. See step 6.
The call to IErrorRecords::GetCustomErrorObjects uses IID_ISQLErrorInfo as the
REFIID to return an interface to ISQLErrorInfo.
IF...
THEN...
an SQLState returns,
the error originated from Teradata Database.
no SQLState returns,
the error originated from OLE DB Provider for Teradata.
Use the interface to the ISQLErrorInfo interface to retrieve the SQLState and Native Error
Code.
OLE DB Provider for Teradata User Guide
Chapter 4: Error Messages
Source, Format and Structure of Error Messages
6
The call to IErrorRecords::GetBasicInfo returns basic information about the error:
•
Return code
•
Provider-specific error number
Perform corrective action based on the error condition.
For an example, refer to “Visual C++ Example” on page 75.
SQLState
The SQLState code describes the status of the SQL statement submitted to Teradata Database
for execution. The next table lists the SQLState five-character codes that can be returned.
Table 22: SQLState Codes
SQLState
Error
01000
General warning
01004
Fractional truncation
01S03
Cursor operation conflict
07001
COUNT field incorrect
22003
Non-character and non-binary data sent in pieces
22005
Invalid character value for cast specification
22008
Invalid datetime format
37000
Syntax error or access violation
70100
Server declined cancel request
HY009
Invalid use of null pointer
S0001
Base table or view already exists
S0002
Base table or view not found
S0011
Index already exists
S0012
Index not found
S0021
Column already exists
S0022
Column not found
S1000
General database error
S1001
Memory allocation error
S1002
Invalid descriptor index
S1003
Invalid application buffer type
S1004
Invalid SQL data type
S1008
Operation canceled
OLE DB Provider for Teradata User Guide
73
Chapter 4: Error Messages
Source, Format and Structure of Error Messages
Table 22: SQLState Codes (continued)
SQLState
Error
S1009
Invalid attribute value
S1010
Associated statement is not prepared
S1010
Function sequence error
S1011
Attribute cannot be set now
S1012
Invalid transaction operation code
S1090
Invalid string or buffer length
S1091
Invalid descriptor field identifier
S1092
Invalid attribute/option identifier
S1096
Invalid information type
S1097
Column type out of range
S1098
Scope type out of range
S1099
Nullable type out of range
S1100
Uniqueness option type out of range
S1101
Accuracy option type out of range
S1103
Invalid retrieval code
S1104
Invalid precision or scale value
S1105
Invalid parameter type
S1106
Fetch type out of range
S1107
Row value out of range
S1109
Invalid cursor position
S1110
Invalid driver completion
S1111
Invalid bookmark value
S1C00
Optional feature not implemented
S1T00
Timeout expired
Native Error Codes
Native Error Codes are listed in the Messages manual.
Teradata Database Error Format
If Teradata Database returns an error, the error message has the following format:
[Teradata Database]message text
74
OLE DB Provider for Teradata User Guide
Chapter 4: Error Messages
Visual C++ Example
The [Teradata Database] label shows that the error is from the database.
Example:
[Teradata Database]Table/view/trigger/procedure TABLE1 does not exist
Teradata Database Messages
For a complete list of Teradata Database error messages, refer to the Messages manual.
Error Format
Causes of Errors
Errors generated by the provider usually occur when:
•
Objects are not created in the correct order.
•
Invalid data is passed in as parameters.
•
The provider detects an internal problem.
If there is no custom error object associated with the error record, or if the custom error object
does not have a native error code, then the error is a provider error.
The message text retrieved using the IErrorInfo interface further describes the error.
Message Format
If the provider returns an error, the error message has the format:
[OLE DB Provider for Teradata]message text
Visual C++ Example
The following example uses Visual C++ to retrieve errors:
void DisplayError(HRESULT hr)
{
HRESULT
IErrorInfo
IErrorRecords
ISQLErrorInfo
BSTR
ERRORINFO
BSTR
long
unsigned long
hrError;
*pIErrorInfo;
*pIErrorRecords;
*pISQLErrorInfo;
bstrErrorDesc;
ErrorInfo;
bstrSQLState;
lNativeError;
cRecordCount;
//
//
//
//
//
//
//
interface pointer
interface pointer
interface pointer
Buffer for message
Error structure
Buffer for state
Native error
// Checking if return code is an error
if (hr != S_OK)
{
OLE DB Provider for Teradata User Guide
75
Chapter 4: Error Messages
Visual C++ Example
// Getting the Error message text
hrError = GetErrorInfo(0, &pIErrorInfo);
hrError = pIErrorInfo->GetDescription(&bstrErrorDesc);
hrError = pIErrorInfo->QueryInterface(IID_IErrorRecords, (void
**)&pIErrorRecords);
// Getting information on each Error record
hrError = pIErrorRecords->GetRecordCount(&cRecordCount);
//Going to retrieve errors generated by Teradata Database
for (int i = 0; i < cRecordCount; i++)
{
hrError = pIErrorRecords->GetCustomErrorObject(i,
IID_ISQLErrorInfo,
(IUnknown **)&pISQLErrorInfo);
hrError = pIErrorRecords->GetBasicErrorInfo(i, &ErrorInfo);
// Going to get the SQL STATE and Native Error Code
// from the error record
hrError = pISQLErrorInfo->GetSQLInfo(&bstrSQLState,
&NativeError);
if (bstrSQLState)
wprintf(L"\nErrorRecord: HResult: 0x%08x\nDescription: %s\n”
L”SQLErrorInfo: %s\n Native Error Code: %d\n",
ErrorInfo.hrError,
bstrErrorDesc,
bstrSQLInfo
NativeError);
else
wprintf(L"\nErrorRecord: HResult: 0x%08x\nDescription: %s\n”
ErrorInfo.hrError,
bstrErrorDesc);
}
// Releasing resources
SysFreeString(BstrErrorDesc);
If (!bstrSQLState)
SysFreeString(bstrSQLState);
pIErrorInfo->Release();
pIErrorRecords->Release();
pISQLErrorInfo->Release();
}
}
76
OLE DB Provider for Teradata User Guide
Chapter 4: Error Messages
Visual Basic with ADO
Visual Basic with ADO
Using ActiveX Data Objects (ADO), Teradata Database errors are mapped to the Custom
Error Object. See “ADO Dynamic Properties” on page 121.
The mapping between a Custom Error Object and a Teradata Database error is as follows:
Table 23: Custom Error Object Mapping to Teradata Database Error
Error Properties
Teradata Database Error Objects
Description
Description of error returned from Teradata Database
NativeError
Native Error Code returned from Teradata Database.
Number
Enumerated type of ErrorValueEnum. For more information, refer to the
MSDN Library search topic:
ErrorValueEnum enumerated constants
Source
Returns OLE DB Provider for Teradata.
SQLState
5-digit character code returned by OLE DB Provider for Teradata.
Example
The following code checks for errors using Visual Basic and ADO.
Dim
Dim
Dim
Dim
strTeraCnxn As String
TeraCnxn As ADODB.Connection
TeraObjCmd As New ADODB.Command
TeraObjRs As ADODB.Recordset
‘Setting up the ERROR HANDLER
On Error GoTo ADOError
' Going to Open Connection
strTeraCnxn = "Provider=TDOLEDB;Data Source=Teradata1" & _
"User Id=userid;Password=password;" & _
"Extended Properties=
””Session Mode=ANSI;Enable Parser=NO;DefaultDatabase=Project1;””;’
Set TeraCnxn = New ADODB.Connection
TeraCnxn.Open strTeraCnxn
TeraObjCmd.ActiveConnection = TeraCnxn
TeraObjCmd.CommandText = "SELECT f1, f2, f3 from table1"
TeraObjCmd.CommandType = adCmdText
Set TeraObjRs = TeraObjCmd.Execute
‘-------------------------------------------------------------‘ Continue Processing Records returned from command object
‘--------------------------------------------------------------
OLE DB Provider for Teradata User Guide
77
Chapter 4: Error Messages
Visual Basic with ADO
' Going to clean up objects
TeraObjRs.Close
Set objCmd = Nothing
TeraCnxn.Close
Set TeraCnxn = Nothing
Exit Sub
‘ This is the ERROR HANDLER
ADOError:
Dim TeraObjError As ADODB.Error
Dim strError As String
If TeraCnxn.Errors.Count > 0 Then
For Each TeraObjError In TeraCnxn.Errors
strError = strError & "Error #" & TeraObjError.Number & _
" " & TeraObjError.Description & vbCrLf & _
"NativeError: " & TeraObjError.NativeError & vbCrLf & _
"SQLState: " & TeraObjError.SQLState & vbCrLf & _
"Reported by: " & TeraObjError.Source
Next
MsgBox strError
End If
78
OLE DB Provider for Teradata User Guide
CHAPTER 5
OLE DB Interfaces
This chapter describes the OLE DB interfaces that OLE DB Provider for Teradata supports and
lists the unsupported OLE DB interfaces. The topics are:
•
Unsupported Interfaces
•
Supported Interfaces
•
IAccessor
•
IColumnsInfo
•
IColumnsRowset
•
ICommand
•
ICommandWithParameter
•
IDBSchemaRowset
•
IRowset
•
IRowsetChange
•
ITransaction
•
ITransactionLocal
Unsupported Interfaces
This table refers to programming limitations and considerations.
Table 24: Unsupported Interfaces
Unsupported Interfaces
IAlterIndex
IAlterTable
IBindResources
IChapteredRowset
ICommandPersist
ICommandStream
ICreateRow
IDataSourceAdmin
OLE DB Provider for Teradata User Guide
79
Chapter 5: OLE DB Interfaces
Unsupported Interfaces
Table 24: Unsupported Interfaces (continued)
Unsupported Interfaces
IDBAsynchStatus
IDBASynchNotify
IDBBinderProperties
IDBDataSourceAdmin
IGetRow
IIndexDefinition
IParentRowset
IRow
IRowChange
IRowsetChapterMembers
IRowsetCurrentIndex
IRowsetFind
IRowsetIndex
IRowsetLocate
IRowsetResynch
IRowsetScroll
IScopedOperations
ISourcesRowset
ITableCreation
ITableDefinition
ITableDefinitionWithConstraints
ITransactionJoin
ITransactionObject
IViewChapter
IViewFilter
IViewRowset
IViewSort
80
OLE DB Provider for Teradata User Guide
Chapter 5: OLE DB Interfaces
Supported Interfaces
Supported Interfaces
The Comments column in the next table refers to programming limitations and
considerations.
Table 25: Supported Interfaces
Supported Interface
Comments
IAccessor
See “IAccessor” on page 82.
IColumnsInfo
See “IColumnsInfo” on page 82.
IColumnsRowset
See “IColumnsRowset” on page 83.
ICommand
See “ICommand” on page 84.
ICommandPrepare
ICommandProperties
ICommandText
ICommandWithParameters
See “ICommandWithParameter” on page 85.
IConvertType
IDBCreateCommand
IDBCreateSession
IDBInfo
IDBInitialize
IDBProperties
IDBSchemaRowset
See “IDBSchemaRowset” on page 85.
IErrorInfo
IErrorLookup
IErrorRecords
IGetDataSource
IGetSession
IMultipleResults
IOpenRowset
IRowset
See “IRowset” on page 94.
IRowsetChange
See “IRowsetChange” on page 95.
IRowsetIdentity
IRowsetInfo
OLE DB Provider for Teradata User Guide
81
Chapter 5: OLE DB Interfaces
IAccessor
Table 25: Supported Interfaces (continued)
Supported Interface
Comments
IRowsetUpdate
IRowsetView
ISessionProperties
ISQLErrroInfo
ISupportErrorInfo
ITransaction
See “ITransaction” on page 96.
ITransactionLocal
See “ITransactionLocal” on page 96.
ITransactionOptions
For more information on interfaces, refer to the Microsoft Developer’s Network (MSDN)
documentation on OLE DB Interfaces. See “Technical Assistance” on page 20.
•
MSDN Library - See http://msdn.microsoft.com/library/
•
OLE DB Programmer’s Guide
•
Part 4 OLE DB Reference
•
OLE DB Interfaces
IAccessor
Programming Limitations
The provider currently does not optimize the accessor, and therefore ignores the
DBACCESSOR_OPTIMIZED flag.
Programming Considerations
The provider does not validate Accessors at the time of creation. Instead, the provider
validates Accessors when processing a database request using ICommand::Execute.
IColumnsInfo
Programming Limitations
None.
Programming Considerations
OLE DB Provider for Teradata supports the following DBCOLUMNFLAGS:
82
OLE DB Provider for Teradata User Guide
Chapter 5: OLE DB Interfaces
IColumnsRowset
•
DBCOLUMNFLAGS_ISFIXEDLENGTH
•
DBCOLUMNFLAGS_ISNULLABLE
•
DBCOLUMNFLAGS_MAYBENULL
•
DBCOLUMNFLAGS_WRITEUNKNOWN
For those flags that OLE DB Provider for Teradata does not support, the bit assigned to the
unsupported flags in the dwFlags element of the DBCOLUMNINFO structure is always set to
0.
For more information, refer to the Microsoft Developer’s Network (MSDN) documentation
on IColumnsInfo::GetColumnInfo. See “Technical Assistance” on page 20.
•
MSDN Library - See http://msdn.microsoft.com/library/
•
OLE DB Programmer’s Guide
•
Part 4 OLE DB Reference
•
OLE DB Interfaces
•
IColumnsInfo
•
IColumnsInfo::GetColumnInfo
For information about the values returned in the pwszName and columnid fields of the
DBCOLUMNINFO structures, see “TDPROP_INIT_USEASCOLUMNNAME (cont.)” on
page 103.
IColumnsRowset
Programming Limitations
The following programming limitations apply:
•
If the consumer uses a column alias, then OLE DB Provider for Teradata does not return
the corresponding column name of the underlying table in
DBCOLUMN_BASECOLUMNNAME.
Example:
SELECT CustomerNo as CustNo
CarMaker as CarManufacturer
CarModel
from ServiceHistory
In this case, the aliases CustNo and CarManufacturer are returned in the columns
DBCOLUMN_BASECOLUMN and DBCOLUMN_NAME.
•
Auto increment columns are not supported in Teradata. For the
DBCOLUMN_ISAUTOINCREMENT column, OLE DB Provider for Teradata returns a
value of FALSE.
•
For the DBCOLUMN_ISCASESENSITIVE column, OLE DB Provider for Teradata always
returns a value of FALSE.
OLE DB Provider for Teradata User Guide
83
Chapter 5: OLE DB Interfaces
ICommand
Programming Considerations
The provider does not support all the metadata columns returned in the rowset. The following
columns are currently supported. A NULL value is returned for those columns Teradata
Database does not support.
Table 26: Supported Metadata Columns
Supported Metadata Columns
Comments
DBCOLUMN_BASECOLUMNNAME
The data in this column is the same as
DBCOLUMN_NAME. For more details, see
“Programming Limitations” on page 83.
DBCOLUMN_DATETIMEPRECISION
DBCOLUMN_FLAGS
DBCOLUMN_IDNAME
For information, see
“TDPROP_INIT_USEASCOLUMNNAME
(cont.)” on page 103.
DBCOLUMN_ISAUTOINCREMENT
Always returns FALSE. For more details, see
“Programming Limitations” on page 83.
DBCOLUMN_ISCASESENSITIVE
Always returns FALSE. For more details, see
“Programming Limitations” on page 83.
DBCOLUMN_ISSEARCHABLE
DBCOLUMN_NAME
For information, see
“TDPROP_INIT_USEASCOLUMNNAME
(cont.)” on page 103.
DBCOLUMN_NUMBER
DBCOLUMN_OCTETLENGTH
DBCOLUMN_PRECISION
DBCOLUMN_SCALE
DBCOLUMN_SIZE
DBCOLUMN_TYPE
ICommand
Programming Limitations
None
84
OLE DB Provider for Teradata User Guide
Chapter 5: OLE DB Interfaces
ICommandWithParameter
Programming Considerations
In addition to returning the number of rows affected when a DELETE, INSERT, or UPDATE
statement is submitted, If the consumer submits a SELECT statement to Teradata Database via
a call to ICommand::Execute, then OLE DB Provider for Teradata returns the pcRowsAffected
parameter containing the number of rows retrieved.
ICommandWithParameter
Programming Limitations
None.
Programming Considerations
The following programming considerations apply:
•
Teradata Database does not return parameter information. Therefore, OLE DB Provider
for Teradata does not support GetParameterInfo unless the consumer describes the
parameter via SetParameterInfo.
•
Always set the information for a parameter via SetParameterInfo before calling
GetParameterInfo.
•
If the consumer has not called SetParameterInfo, then GetParameterInfo returns the
DB_E_PARAMUNAVAILABLE error code.
IDBSchemaRowset
Programming Limitations
Teradata does not support the concept of a catalog. OLE DB Provider for Teradata returns
Null values for the catalog column in each rowset returned.
Fully Qualify Restrictions
As a general rule, you should always fully qualify the restrictions. For example, when
restricting by Table_Name, always provide the Table_SCHEMA. When restricting by
COLUMN_NAME, then provide TABLE_SCHEMA and TABLE_NAME.
If the consumer does not set a restriction for the SCHEMA, then for most of the schema
rowsets, the default database assigned to the user is always used. Exceptions are the
SCHEMATA and Tables schema rowsets.
If the consumer has set a different database via the DATABASE command, then OLE DB
Provider for Teradata still uses the default database.
OLE DB Provider for Teradata User Guide
85
Chapter 5: OLE DB Interfaces
IDBSchemaRowset
Collation Sequence
According to the OLE DB specification, the data returned by each schema rowset must be
ordered by specified columns. Teradata allows changing the collation sequence which causes
the order of the rowset to change. For more information, see “Collation Sequences” in
Chapter 4 of SQL Data Definition Language.
Default Database
In the following discussions, default database refers to either:
•
The database specified in the default database attribute of the provider string, or
•
The default database specified when the user was created (if the default database is not
specified in the provider string)
By setting the database with the Teradata statement:
DATABASE databasename
the consumer does not change the default database used by IDBSchemaRowset.
IDBSchemaRowset uses either:
•
The database specified in the provider string, or
•
The default specified when the user was created
Supported Schema Rowsets
OLE DB Provider for Teradata supports the following schema rowsets. The following sections
describe each schema rowset.
•
“Column Privileges Schema Rowset” on page 87
•
“Columns Schema Rowset” on page 88
•
“Foreign Keys Schema Rowset” on page 89
•
“Indexes Schema Rowset” on page 90
•
“Primary Keys Schema Rowset” on page 90
•
“Procedure Parameters Schema Rowset” on page 91
•
“Procedures Schema Rowset” on page 92
•
“Schemata Schema Rowset” on page 92
•
“Sort Limitation” on page 88
•
“Provider Types Schema Rowset” on page 94
In the table, for each schema rowset, the column titled Supported Columns shows which of the
returned columns can contain data.
The rowset also contains other columns that Teradata does not support, and that contain
NULL values.
86
OLE DB Provider for Teradata User Guide
Chapter 5: OLE DB Interfaces
IDBSchemaRowset
Column Privileges Schema Rowset
Table 27: Column Privileges Schema Rowset
Default Sort Order
Supported Restrictions
Supported Columns
TABLE_SCHEMA
TABLE_SCHEMA
GRANTOR
TABLE_NAME
TABLE_NAME
GRANTEE
COLUMN_NAME
COLUMN_NAME
TABLE_SCHEMA
COLUMN_GUID
GRANTOR
TABLE_NAME
COLUMN_PROPID
GRANTEE
COLUMN_NAME
PRIVILEGE_TYPE
PRIVILEGE_TYPE
IS_GRANTABLE
Programming Considerations
If a privilege applies to all columns of a table, then OLE DB Provider for Teradata returns the
name “ALL” as the COLUMN_NAME.
Privilege Types
The types returned in the PRIVILEGE_TYPE column can consist of the following:
•
CRESPROC
Create Stored Procedure
•
CRETRIG
Create Trigger
•
CREVW
Create View
•
DELETE
•
DRROPTBL
•
DROPSPROC Drop Stored Procedure
•
DROPTRIG
Drop Trigger
•
DROPVW
Drop View
•
DUMP
•
EXSPPOC
•
INDEX
•
INSERT
•
REFERENCES
•
RESTORE
•
SELECT
•
UPDATE
Drop Table
Execute Stored Procedure
For more information, refer to Chapter 2 of SQL Data Definition Language.
OLE DB Provider for Teradata User Guide
87
Chapter 5: OLE DB Interfaces
IDBSchemaRowset
Columns Schema Rowset
Table 28: Columns Schema Rowset
Default Sort Order
Supported Restrictions
Supported Columns
TABLE_SCHEMA
TABLE_SCHEMA
TABLE_SCHEMA
TABLE_NAME
TABLE_NAME
TABLE_NAME
COLUMN_NAME
COLUMN_NAME
COLUMN_HASDEFAULT
COLUMN_FLAGS
IS_NULLABLE
DATA_TYPE
NUMERIC_PRECISION
NUMERIC_SCALE
DATETIME_PRECISION
DESCRIPTION
LABEL
FORMAT
CHAR_TYPE
CHARACTER_MAXIMUM_LEN
GTH
CHARACTER_OCTET_LENGTH
Specify Restrictions
The following restriction applies:
•
If the TABLE_SCHEMA is unrestricted, then OLE DB Provider for Teradata uses the
default database as described in the previous “Default Database” on page 86.
Privileges
If the consumer specifies a table that the user does not have privilege to access, then
IDBSchemaRowset::GetRowset returns the S_OK error code. However, no rows are returned.
COLUMN_HASDEFAULT Limitation
COLUMN_HASDEFAULT always returns FALSE for views whether or not the DEFAULT
clause has been specified for a column. This is a known limitation.
Sort Limitation
The data returned is not correctly sorted. The sort on TABLE_NAME is case insensitive.
Custom Columns
The LABEL, FORMAT, and CHAR_TYPE are custom columns. The data returned for each
column are as follows:
88
OLE DB Provider for Teradata User Guide
Chapter 5: OLE DB Interfaces
IDBSchemaRowset
Table 29: Custom Columns
Column
Data Returned
CHAR_TYPE
The character set specified for the column.
FORMAT
The text specified in the FORMAT clause
LABEL
The text specified in the TITLE clause
Foreign Keys Schema Rowset
Table 30: Foreign Keys Schema Rowset
Default Sort Order
Supported Restrictions
Supported Columns
FK_TABLE_SCHEMA
FK_SCHEMA_NAME
PK_TABLE_SCHEMA
FK_TABLE_NAME
FK_TABLE_NAME
PK_TABLE_NAME
PK_SCHEMA_NAME
PK_COLUMN_NAME
PK_TABLE_NAME
FK_TABLE_SCHEMA
FK_TABLE_NAME
FK_COLUMN_NAME
ORDINAL
Define Keys
OLE DB Provider for Teradata only returns a rowset if the consumer defines both:
•
Primary key of the PK_TABLE_NAME using the PRIMARY KEY clause, and
•
FK_TABLE_NAME using the REFERENCES clause
For example, if the consumer defines the foreign key relationship as follows, one row will be
returned.
CREATE TABLE PARENT1 (
P1 INTEGER NOT NULL PRIMARY KEY,
P2 INTEGER,
P3 INTEGER
);
CREATE TABLE CHILD1 (
C1 INTEGER,
C2 INTEGER,
C3 INTEGER REFERENCES PARENT1 (P1)
);
However, if the parent table were defined as follows, no rows are returned.
CREATE TABLE PARENT1 (
P1 INTEGER NOT NULL,
P2 INTEGER,
P3 INTEGER
) UNIQUE PRIMARY INDEX (P1);
OLE DB Provider for Teradata User Guide
89
Chapter 5: OLE DB Interfaces
IDBSchemaRowset
Indexes Schema Rowset
Table 31: Indexes Schema Rowset
Default Sort Order
Supported Restrictions
Supported Columns
UNIQUE
TABLE_SCHEMA
TABLE_SCHEMA
TYPE
TABLE_NAME
TABLE_NAME
INDEX_SCHEMA
INDEX_SCHEMA
INDEX_NAME
INDEX_NAME
ORDINAL_POSITION
UNIQUE
TYPE
NULL_COLLATION
ORDINAL_POSITION
COLUMN_NAME
COLLATION
PAGES
Specify Restrictions
The consumer must specify a restriction for the TABLE_NAME column, otherwise
IDBSchemaRowset::GetRowset returns the E_FAIL error code.
•
If the consumer has not specified a restriction for TABLE_SCHEMA, then OLE DB
Provider for Teradata searches the default database for indexes that correspond to the table
specified in TABLE_NAME.
•
If the consumer specifies a table as a restriction, and the user does not have privilege to
access the table, then IDBSchemaRowset returns the E_FAIL error code.
Sort Limitation
The rows are not correctly sorted. The sort on INDEX_NAME is case insensitive.
Primary Keys Schema Rowset
Table 32: Primary Keys Schema Rowset
Default Sort Order
Supported Restrictions
Supported Columns
TABLE_SCHEMA
TABLE_SCHEMA
TABLE_SCHEMA
TABLE_NAME
TABLE_NAME
TABLE_NAME
COLUMN_NAME
ORDINAL
PK_NAME
90
OLE DB Provider for Teradata User Guide
Chapter 5: OLE DB Interfaces
IDBSchemaRowset
PRIMARY KEY Clause Required
OLE DB Provider for Teradata only returns data on tables created using the PRIMARY KEY
clause.
Specify Restrictions
The consumer must specify a restriction for TABLE_NAME, otherwise an empty rowset is
returned.
Procedure Parameters Schema Rowset
Table 33: Procedure Parameters Schema Rowset
Default Sort Order
Supported Restrictions
Supported Columns
PROCEDURE_SCHEMA
PROCEDURE_SCHEMA
PROCEDURE_SCHEMA
PROCEDURE_NAME
PROCEDURE_NAME
PROCEDURE_NAME
PARAMETER_NAME
PARAMETER_TYPE
IS_NULLABLE
DATA_TYPE
NUMERIC_PRECISION
NUMERIC_SCALE
TYPE_NAME
CHARACTER_MAXIMUM_LENGTH
CHARACTER_OCTET_LENGTH
Macros
OLE DB Provider for Teradata also returns information on Teradata Database macros.
Specify Restrictions
•
If PROCEDURE_SCHEMA is unrestricted, then OLE DB Provider for Teradata returns
only parameters of stored procedures/macros from the user’s default database.
•
If the provider string attribute “Use X Views” is set to YES, and a database name has been
specified in PROCEDURE_SCHEMA, then OLE DB Provider for Teradata returns only
parameters of those stored procedures/ macros that the user has privilege to access.
•
If “Use X Views” is set to NO, and a database name has been specified in the
PROCEDURE_SCHEMA column, then OLE DB Provider for Teradata can return the
parameters of stored procedures/macros from any database.
OLE DB Provider for Teradata User Guide
91
Chapter 5: OLE DB Interfaces
IDBSchemaRowset
Procedures Schema Rowset
Table 34: Procedures Schema Rowset
Default Sort Order
Supported Restrictions
Supported Columns
PROCEDURE_SCHEMA
PROCEDURE_SCHEMA
PROCEDURE_SCHEMA
PROCEDURE_NAME
PROCEDURE_NAME
PROCEDURE_NAME
PROCEDURE_TYPE
DATE_CREATED
DATE_MODIFIED
Use X Views Limitation
Unlike the Procedure Parameters rowset, the provider string attribute Use X Views has no
effect on the Procedure rowset. This will be fixed in a later version, so that the Procedure
rowset behavior will be similar to the Procedure Parameters rowset behavior for Use X Views.
Because the settings of the provider string attribute Use X Views has no effect, OLE DB
Provider for Teradata has the following behavior when using the supported restrictions:
•
If PROCEDURE_SCHEMA is unrestricted, then TDOELDB returns only stored
procedures and macros from the user’s default database.
•
If the consumer specifies a database in PROCEDURE_SCHEMA, and the user does not
have privileges to access the database, then IDBSchemaRowset returns S_OK. However, no
rows are returned.
Search Multiple Databases Limitation
A procedure name cannot be searched across multiple databases. For example:
If the PROCEDURE_SCHEMA is null, and a name is entered in the PROCEDURE_NAME
column, then only the default database is searched.
Macros
OLE DB Provider for Teradata also returns information on Teradata macros.
Schemata Schema Rowset
Table 35: Schemata Schema Rowset
Default Sort Order
Supported Restrictions
Supported Columns
SCHEMA_NAME
SCHEMA_NAME
SCHEMA_NAME
SCHEMA_OWNER
SCHEMA_OWNER
SCHEMA_OWNER
Sort Limitation
The data sorting is case insensitive. Therefore, the data is not ordered according to the OLEDB specification.
92
OLE DB Provider for Teradata User Guide
Chapter 5: OLE DB Interfaces
IDBSchemaRowset
Tables Schema Rowset
Table 36: Tables Schema Rowset
Default Sort Order
Supported Restrictions
Supported Columns
TABLE_TYPE
TABLE_SCHEMA
TABLE_SCHEMA
TABLE_SCHEMA
TABLE_NAME
TABLE_NAME
TABLE_NAME
TABLE_TYPE
TABLE_TYPE
DESCRIPTION
DATE_CREATED
DATE_MODIFIED
Specify Restrictions
The following restrictions apply:
•
If the provider string attribute “Use X View” is set to YES (the default), and
TABLE_NAME is unrestricted, then only tables that the user has access to are returned.
•
In addition, if a table name has been specified, then a search is conducted only against
those tables that the user has privilege to access.
•
Or, if the provider string attribute “Use X View” is set to NO, and TABLE_NAME is
unrestricted, then all tables contained in the database are returned.
Table Types
The valid values for TABLE_TYPE are:
•
SYSTEM TABLE
•
TABLE
•
SYSTEM VIEW
•
VIEW
•
V (where “V” is VIEW or SYSTEM VIEW)
•
T (where “T” is TABLE or SYSTEM TABLE)
OLE DB Provider for Teradata User Guide
93
Chapter 5: OLE DB Interfaces
IRowset
Provider Types Schema Rowset
Table 37: Provider Types Schema Rowset
Default Sort Order
Supported Restrictions
Supported Columns
DATA_TYPE
TYPE_NAME
DATA_TYPE
COLUMN_SIZE
LITERAL_PREFIX
LITERAL_SUFFIX
CREATE_PARAMS
IS_NULLABLE
CASE_SENSITIVE
SEARCHABLE
UNSIGNED_ATTRIBUTE
FIXED_PREC_SCALE
AUTO_UNIQUE_VALUE
LOCAL_TYPE_NAME
MINIMUM_SCALE
MAXIMUM_SCALE
IS_LONG
IS_FIXEDLENGTH
Sort
OLE DB Provider for Teradata does not sort the rows returned.
IRowset
Programming Limitations
None.
Programming Considerations
SQL statements that contain parameters cannot be restarted.
If a statement that contains parameters has been executed, and the consumer calls
RestartPosition, then OLE DB Provider for Teradata returns a DB_E_CANNOTRESTART
error.
The provider does not support scrolling backwards. In other words, for the GetNextRows
method, a negative value cannot be specified for either the offset (lRowOffset), or the number
of rows to fetch parameter (crows).
94
OLE DB Provider for Teradata User Guide
Chapter 5: OLE DB Interfaces
IRowsetChange
If columns of an underlying table have changed, then any consumers that have rowsets based
on this table have to release all accessors, all row handles, and the rowset.
Next, the consumers must execute again the command used to create the rowset.
If this is not done, and a consumer calls IRowset::RestartPosition on the rowset, then OLE DB
Provider for Teradata returns the E_FAIL error code.
When this error occurs, OLE DB Provider for Teradata invalidates the rowset and allows
consumers to call only:
•
ReleaseRows
•
ReleaseAccessors
Calls to other methods fail.
IRowsetChange
Programming Limitations
None.
Programming Considerations
Special consideration must be given when a rowset contains a column declared as INTEGER
FORMAT ‘99:99:99’ (see section “INTEGER FORMAT ’99:99:99’ Columns” on page 64), or
FLOAT (see “Changing Data” on page 49).
OLE DB Provider for Teradata does not support IRowsetResynch.
•
Therefore, if the data of the underlying table of a rowset has been modified (delete, insert,
or update), then a IRowset::RestartPosition must be called for any changes to be reflected
in the rowset.
•
If a IRowset::RestartPosition is not executed, then the rowset contains the data that was
originally fetched from the table even though the data contained in the underlying table
has changed. This may cause problems when the consumer calls either:
•
IRowsetChange::SetData
•
IRowsetChange::Delete
For example, suppose a consumer retrieves a rowset from the table PRODUCTS. A second
consumer deletes a row from the PRODUCTS table that is included in the first consumer’s
rowset. If the first consumer makes a call to IRowsetChange::SetData to update the row that
was deleted by the second consumer, OLE DB Provider for Teradata returns the E_FAIL error
code and presents the following error message:
Query-based update failed because the row to update could not be found
For more information, refer to the Microsoft Developer’s Network (MSDN) documentation
on Changing Data. See “Technical Assistance” on page 20.
•
MSDN Library - See http://msdn.microsoft.com/library/
•
OLE DB Programmer’s Guide
OLE DB Provider for Teradata User Guide
95
Chapter 5: OLE DB Interfaces
ITransaction
•
Part 1: Introduction to OLE DB
•
Chapter 5: Updating Data in Rowsets
•
Changing Data
ITransaction
Programming Limitations
None.
Programming Considerations
The consumer can specify several different commit options from the ITransaction::Commit
method. However, OLE DB Provider for Teradata only supports XACTTC_SYNC.
For more information about how Teradata performs transaction processing, refer to
“Transaction Processing” in SQL Request and Transaction Processing.
ITransactionLocal
Programming Limitations
None.
Programming Considerations
•
OLE DB Provider for Teradata only supports the functionality provided by Teradata.
•
The ITransactionLocal::StartTransaction method supports many isolation levels. However,
OLE DB Provider for Teradata only supports the following isolation levels:
•
ISOLATIONLEVEL_READUNCOMMITTED
•
ISOLATIONLEVEL_SERIALIZED
The other isolation levels are either unsupported or are upgraded to one of the above levels.
The following chart shows the remaining isolation levels and the level to which they are
upgraded:
Table 38: Upgrades to Isolation Levels
Isolation Level
Upgraded To
ISOLATIONLEVEL_BROWSE
ISOLATIONLEVEL_READUNCOMMITTED
ISOLATIONLEVEL_CHAOS
ISOLATIONLEVEL_READUNCOMMITTED
ISOLATIONLEVEL_CURSORSTABILITY
ISOLATIONLEVEL_SERIALIZED
ISOLATIONLEVEL_ISOLATED
ISOLATIONLEVEL_SERIALIZED
96
OLE DB Provider for Teradata User Guide
Chapter 5: OLE DB Interfaces
ITransactionLocal
Table 38: Upgrades to Isolation Levels (continued)
Isolation Level
Upgraded To
ISOLATIONLEVEL_READCOMMITTED
ISOLATIONLEVEL_SERIALIZED
ISOLATIONLEVEL_REPEATABLEREAD
ISOLATIONLEVEL_SERIALIZED
ISOLATIONLEVEL_UNSPECIFIED
Not supported by OLE DB Provider for Teradata
Isolation Level and Access Locking
Table 39: Isolation Level and Access Locking
IF a transaction starts with the isolation level set to...
THEN OLE DB Provider for Teradata...
ISOLATIONLEVEL_READUNCOMMITTED,
adds an ACCESS locking modifier to SELECT statements
submitted during the transaction.
ISOLATIONLEVEL_SERIALIZED,
allows Teradata Database to determine the locking mode.
OLE DB Provider for Teradata User Guide
97
Chapter 5: OLE DB Interfaces
ITransactionLocal
98
OLE DB Provider for Teradata User Guide
CHAPTER 6
Supported Properties
This chapter describes the properties that OLE DB Provider for Teradata supports, for each of
the OLE DB property groups. The topics are:
•
Introduction
•
Initialization Property Group
•
Data Source Information Property Group
•
Rowset Property Group
•
Session Property Group
Introduction
OLE DB Provider for Teradata supports some provider-specific properties. These properties
comprise the TDPROPSET_TDINIT provider-specific property set which is part of the
Initialization Property Group. Definitions of the identifiers pertinent to this property set are
contained within the tdoledb.h file, which is installed with OLE DB Provider for Teradata. The
default location is:
%Program Files%\Teradata\Client\<version>\OLE DB Provider for Teradata.
Users of applications that use the Microsoft Data Links dialog to establish connections to data
sources can select values for provider-specific properties from the All tab of the dialog box.
When using a connection string (as an argument to IDataIntialize::GetDataSource()) to
establish a connection to a data source, values for provider-specific properties can be specified
by using the property description within the provider string.
The following sections describe the OLE DB properties that OLE DB Provider for Teradata
supports. Each property group has a table of properties. The columns show:
•
Property name
•
Default Value
•
Mode Read Write. The supported modes:
•
•
Read/Write (R/W)
•
Read Only (R)
Comments
Some of the programming limitations described in Chapter 7: “Programming Limitations”
have direct effects on the properties that OLE DB Provider for Teradata supports. For
OLE DB Provider for Teradata User Guide
99
Chapter 6: Supported Properties
Initialization Property Group
example, OLE DB Provider for Teradata does not support Bookmarks or the corresponding
properties:
•
DBPROP_BOOKMARKSKIPPED
•
DBPROP_BOOKMARKTPE
For more information about OLE DB properties, refer to the following Microsoft Developer’s
Network (MSDN) documentation. See “Technical Assistance” on page 20.
•
MSDN Library - See http://msdn.microsoft.com/library/
•
OLE DB Programmer’s Guide
•
Part 5: Appendixes
•
Appendix C
Encryption Property Set
The description of the TDPROP_INIT_DATAENCRYPTION property is “Data Encryption”,
the flags are:
•
DBPROPFLAGS_DBINIT
•
DBPROPFLAGS_READ
•
DBPROPFLAGS_WRITE
To enable encryption, set the type of the property to VT_BOOL. The property is set on the
ALL tab of the Data Links dialog box.
Initialization Property Group
Table 40: Initialization Property Group
Property
Default Value
Mode
Read Write
Comments
DBPROP_AUTH_INTEGRATED
Set by user
R/W
SSO
DBPROP_AUTH_PASSWORD
Set by user
R/W
Password
DBPROP_AUTH_PERSIST_SENSITIVE_AUTHINFO
No Default
R/W
DBPROP_AUTH_USERID
Set by user
R/W
User name
DBPROP_INIT_DATABASESOURCE
Set by user
R/W
DBC Name
DBPROP_INIT_GENERALTIMEOUT
No Default
R/W
No Effect
DBPROP_INIT_HWND
R/W
DBPROP_INIT_LCID
R/W
DBPROP_INIT_MODE
No Default
R/W
DBPROP_INIT_OLEDBSERVICES
-1
R/W
100
OLE DB Provider for Teradata User Guide
Chapter 6: Supported Properties
Initialization Property Group
Table 40: Initialization Property Group (continued)
Mode
Read Write
Property
Default Value
Comments
DBPROP_INIT_PROMPT
DBPROMPT_CO R/W
MPLETE
DBPROP_INIT_PROVIDERSTRING
Set by user
R/W
See “Setting Provider
String Attributes” on
page 43
DBPROP_INIT_TIMEOUT
20 seconds
R/W
Log in Time Out
TDPROP_INIT_DATAENCRYPTION
No default
R/W
When TRUE, all requests
and data are transferred in
encrypted format instead
of in clear text.
The description of the
TDPROP_INIT_DATAEN
CRYPTION property is
“Data Encryption.” The
flags are:
• DBPROPFLAGS_DBINIT
• R/W
To enable encryption, set
the type of the property to
VT_TRUE.
The property is set on the
ALL tab of the Data Links
dialog box.
TDPROP_INIT_OUTPUTPARAMETERLOCATION
OLE DB Provider for Teradata User Guide
BUFFER
R/W
This property is provided
only for backward
compatibility. In earlier
versions of OLE DB
Provider for Teradata, the
output parameters were
incorrectly returned inside
a rowset. This has been
corrected in the current
version and the output
parameters are returned in
the parameter buffer. For
backward compatibility,
returning output
parameters via a rowset is
still supported but the user
has to set the value of this
provider specific property
to “ROWSET”.
101
Chapter 6: Supported Properties
Initialization Property Group
Table 40: Initialization Property Group (continued)
Property
Default Value
Mode
Read Write
TDPROP_INIT_SESSIONCHARACTERSET
VT_EMPTY
R/W
Comments
The Session Character Set
property consists of a string
contained within the
TDPROPSET_TDINIT
property set. It is the name
of the session character set.
The property type is
VT_BSTR.
Supported values include:
• “ASCII”
• “KANJISJIS_0S”
• “UTF16”
• “UTF8”
For more information, see
“Session Character Sets” on
page 103.
TDPROP_INIT_USEASCOLUMNNAME
VT_EMPTY
R/W
The Use As Column Name
property type is VT_BSTR.
Valid string values are
COLUMNNAME and
COLUMNTITLE. The
value of this property
during initialization
determines the values
returned for column
metadata in the following
contexts:
• In the values referenced
by the pwszName and
columnid fields of the
DBCOLUMNINFO
structures returned by
IColumnsInfo::GetColu
mnInfo().
• In the values of the
DBCOLUMN_IDNAM
E and
DBCOLUMN_NAME
columns of the columns
metadata rowset
(returned by
IColumnsRowset::GetC
olumnsRowset()).
102
OLE DB Provider for Teradata User Guide
Chapter 6: Supported Properties
Initialization Property Group
Table 40: Initialization Property Group (continued)
Property
Default Value
Mode
Read Write
TDPROP_INIT_USEASCOLUMNNAME (cont.)
Comments
This property does the
following:
• If set to
COLUMNNAME,
column names are
returned.
• If set to
COLUMNTITLE,
column titles are
returned if these values
are available. (Column
names are used if
column titles are
unavailable.)
Note: If a column alias
is used in the command
text, the alias gets used
in these values
regardless of the setting
of
TDPROP_INIT_USEAS
COLUMNNAME. If a
consumer program
specifically needs either
column names or
column titles, explicitly
set the
TDPROP_INIT_USEAS
COLUMNNAME
property.
• If set to VT_EMPTY
(the default), the
behavior is the same as
for COLUMNTITLE.
Session Character Sets
During initialization, the following rules determine what session character set is actually used:
•
If a session character set name was written to
TDPROP_INIT_SESSIONCHARACTERSET, then that is used.
•
Otherwise, if a session character set name is specified for the Session Character Set
attribute in the string written to the extended properties
(DBPROP_INIT_PROVIDERSTRING), then that is used. See the Session Character Set
attribute in the “List of Attributes” on page 44.
OLE DB Provider for Teradata User Guide
103
Chapter 6: Supported Properties
Data Source Information Property Group
•
Otherwise, if the TDOLEDB_DEFAULT_SESSION_CHARACTER_SET environment
variable value (in the process in which this instance of the provider is running) is the name
of one of the four supported session character sets, then that is used.
•
Otherwise, if DBPROP_INIT_LCID contains the locale ID for a Japanese locale, then
KANJISJIS_0S is used.
•
Otherwise, ASCII is used.
When choosing a session character set consider the following:
•
The UTF16 and UTF8 session character sets are encodings of the Unicode character set.
The Unicode character set includes the characters needed for virtually all languages in
modern use.
The UTF16 and UTF8 session character sets support the identical set of characters. All
Unicode characters that do not require surrogate code points are supported. All supported
characters consume two bytes per character in the UTF16 session character set and one to
three bytes per character in the UTF8 session character set. The set of characters supported
by the UTF16 and UTF8 session character sets are supersets of the characters supported by
the ASCII and KANJISJIS_0S session character sets.
•
ASCII, UTF16, and UTF8 are permanently enabled session character sets supported by
Teradata Database. KANJISJIS_0S must be made active on Teradata Database in order to
be available for use.
•
When the VARCHAR data being accessed chiefly consists of ASCII characters,
performance may be better by using the UTF8 session character set (as opposed to UTF16)
because many of the characters will consume only a single byte. However, when using the
UTF8 session character set, communications of fixed-length character values (i.e.
CHAR(n)) between the database and OLE DB Provider for Teradata always reserve three
bytes per character, so when the data being access is chiefly CHAR(n), better performance
may be observed when using the UTF16 session character set.
•
When the ASCII session character set is used, OLE DB Provider for Teradata converts
character data using the application code page.
•
(e) When the KANJISJIS_0S session character set is used, OLE DB Provider for Teradata
converts character data using the Microsoft Windows code page 932 (Japanese Shift-JIS).
For more information on session character sets, see International Character Set Support.
Data Source Information Property Group
Table 41: Data Source Information Property Group
Property
Default Value
Mode
Read Write
Comments
DBPROP_ACTIVESESSIONS
200
R
No Effect
DBPROP_ASYNCTXNABORT
FALSE
R
104
OLE DB Provider for Teradata User Guide
Chapter 6: Supported Properties
Data Source Information Property Group
Table 41: Data Source Information Property Group (continued)
Property
Default Value
Mode
Read Write
DBPROP_ASYNCTXNCOMMIT
FALSE
R
DBPROP_BYREFACCESSORS
TRUE
R
DBPROP_CATALOGLOCATION
0
R
Not Supported
R
Not Supported
Not Supported
DBPROP_CATALOGTERM
Comments
DBPROP_CATALOGUSAGE
0
R
DBPROP_COLUMNDEFINITION
1
R
DBPROP_CONCATNULLBEHAVIOR
0
R
DBPROP_CONNECTIONSTATUS
DBPROPVAL_CS_INITIALIZED
R
DBPROP_DATASOURCENAME
Data Source specified in
DBPROP_INIT_DATASOURCE
R
DBPROP_DATASOURCEREADONLY
FALSE
R
DBPROP_DBMSNAME
Teradata
R
DBPROP_DBMSVER
Version of Teradata installed
R
DBPROP_DSOTHREADMODEL
DBPROVAL_RT_FREETHREAD
R
DBPROP_DSOTHREADINGMODEL
DBPROPVAL_FREETHREAD
R
DBPROP_GROUPBY
DBPROPVAL_GB_EQUALS_SELECT
R
DBPROP_HETEROGENEOUSTABLES
0
R
DBPROP_IDENTIFIERCASE
DBPROPVAL_IC_SENSITIVE
R
DBPROP_MAXINDEXSIZE
255
R
Maximum
number of bytes
allowed in an
index.
DBPROP_MAXROWSIZE
64256
R
Maximum size
of a single row
in a table
DBPROP_MAXROWSIZEINCLUDESBLOB
TRUE
R
DBPROP_MAXTABLESINSELECT
15
R
DBC Name
Teradata
Version
Maximum
number of
tables that can
be specified in a
select statement.
This number
can be ignored.
DBPROP_MULTIPLEPARAMSETS
OLE DB Provider for Teradata User Guide
TRUE
R
105
Chapter 6: Supported Properties
Data Source Information Property Group
Table 41: Data Source Information Property Group (continued)
Property
Default Value
Mode
Read Write
DBPROP_MULTIPLERESULTS
DBPROPVAL_MR_SUPPORTED
R
DBPROP_MULTIPLESTORAGEOBJECTS
FALSE
R
DBPROP_MULTITABLEUPDATE
FALSE
R
DBPROP_NULLCOLLATION
DBPROPVAL_NC_LOW
R
DBPROP_OLEOBJECTS
DBPROPVAL_OO_BLOB
R
DBPROP_OPENROWSETSUPPORT
DBPROPVAL_ORS_TABLE
R
DBPROP_ORDERBYCOLUMNSINSELECT
FALSE
R
DBPROP_OUTPUTPARAMETERAVAILABI
LITY
DBPROPVAL_OA_ATROWRELEASE
R
DBPROP_PERSISTENTIDTYPE
DBPROPVAL_PT_NAME
R
DBPROP_PREPAREABORTBEHAVIOR
DBPROPVAL_CB_PRESERVE
R
DBPROP_PREPARECOMMITBEHVIOR
DBPROPVAL_CB_PRESERVE
R
DBPROP_PROCEDURETERM
MACRO
R
Comments
PROCEDURE
DBPROP_PROVIDERFILENAME
TDOLEDB.DLL
R
DBPROP_PROVIDERFRIENDLYNAME
OLE DB Provider for Teradata
R
DBPROP_PROVIDEROLEDBVER
03.00
R
DBPROP_PROVIDERVER
01.00.00
R
DBPROP_QUOTEDIDENTIFIERCASE
DBPROPVAL_IC_SENSITIVE
R
DBPROP_ROWSETCONVERSIONONCOM
MAND
TRUE
R
DBPROP_ROWSETCONVERSIONSONCO
MMAND
TRUE
R
DBPROP_SCHEMATERM
DATABASE
R
DBPROP_SCHEMAUSAGE
DBPROPVAL_SU_DML_STATEMENTS
R
DBPROPVAL_SU_TABLE_DEFINITION
DBPROPVAL_SU_INDEX_DEFINITION
DBPROPVAL_SU_PRIVILEGE_DEFINITI
ON
DBPROP_SERVERNAME
106
Name specified in
DBPROP_DATASOURCENAME
R
TDPID
OLE DB Provider for Teradata User Guide
Chapter 6: Supported Properties
Rowset Property Group
Table 41: Data Source Information Property Group (continued)
Property
Default Value
Mode
Read Write
DBPROP_SQLSUPPORT
DBPROPVAL_ODBC_MINIMUM
R
Comments
DBPROPVAL_ODBC_CORE
DBPROPVAL_SQL_ANSI89_IEF
DBPROPVAL_ESCAPECLAUSES
DBPROP_STRUCTUREDSTORAGE
DBPROPVAL_SS_SQUENTIALSTREAM
R
DBPROP_SUBQUERIES
DBPROPVAL_SQ_CORRELATEDSUBQU
ERIES
R
DBRPOPVAL_SQ_COMPARISON
DBPROPVAL_EXISTS
DBPROPVAL_SQ_QUANTIFIED
DBPROP_SUPPORTEDTXNDDL
DBPROPVAL_TC_DML
R
DBPROP_SUPPORTEDTXNISORETAIN
0
R
DBPROP_SUPPORTEDTXNISQLEVELS
DBPROPVAL_TI_READUNCOMMITTE
D
R
DBPROPVAL_TI_SERIALIZABLE
DBPROP_TABLETERM
TABLE
R
DBPROP_USERNAME
User name specified in
DBPROP_AUTH_USERID
R
Transaction can
only contain
DML.
Type of Locking
Modifier
supported by
Teradata.
User Name
Rowset Property Group
Table 42: Rowset Property Group
Property
Default Value
Mode
Read Write
DBPROP_ABORTPRESERVE
TRUE
R
DBPROP_ACCESSORDER
DBPROPVAL_AO_SEQUENTIALST
ORAGEOBJECTS
R/W
DBPROP_BLOCKINGSTORAGEOBJECTS
TRUE
R
DBPROP_CHANGEINSERTEDROWS
TRUE
R
DBPROP_COLUMNRESTRICT
FALSE
R
OLE DB Provider for Teradata User Guide
Comments
107
Chapter 6: Supported Properties
Rowset Property Group
Table 42: Rowset Property Group (continued)
Property
Default Value
Mode
Read Write
DBPROP_COMMANDTIMEOUT
0
R/W
DBPROP_COMMITPRESERVE
TRUE
R
DBPROP_DELAYEDSTORAGEOBJECTS
FALSE
R
DBPROP_IAccessor
TRUE
R/W
DBPROP_IcolumnsInfo
TRUE
R/W
DBPROP_IColumnsRowset
TRUE
R/W
DBPROP_IconnectionPointContainer
FALSE
R/W
DBPROP_IConvertType
TRUE
R/W
DBPROP_IMultipleResults
FALSE
R/W
DBPROP_IRowset
TRUE
R
DBPROP_IRowsetChange
FALSE
R/W
DBPROP_IRowsetIdentity
FALSE
R/W
DBPROP_IRowsetInfo
TRUE
R/W
DBPROP_IRowsetUpdate
FALSE
R/W
DBPROP_ISupportErrorInfo
TRUE
R/W
DBPROP_ISequentialStream
FALSE
R/W
DBPROP_LITERALIDENTITY
TRUE
R
DBPROP_MAXOPENROWS
0
R
DBPROP_MAXPENDINGROWS
0
R
DBPROP_MAXROWS
0
R/W
DPROP_NOTIFICATIONGRANULARITY
DBPROPVAL_NT_SINGLEROW
R
DBPROP_NOTIFICATIONPHASES
31
R
DBPROP_NOTIFYCOLUMNSET
DBPROPVAL_NP_OKTODO
DBPROPVAL_NP_ABOUTTODO
R
DBPROP_NOTIFYROWDELETE
DBPROPVAL_NP_OKTODO
DBPROPVAL_NP_ABOUTTODO
R
DBPROP_NOTIFYROWFIRSTCHANGE
DBPROPVAL_NP_OKTODO
DBPROPVAL_NP_ABOUTTODO
R
108
Comments
Number of
seconds for
Teradata to
execute before
timing out. 0
indicates infinite.
OLE DB Provider for Teradata User Guide
Chapter 6: Supported Properties
Rowset Property Group
Table 42: Rowset Property Group (continued)
Mode
Read Write
Property
Default Value
DBPROP_NOTIFYROWINSERT
DBPROPVAL_NP_OKTODO
DBPROPVAL_NP_ABOUTTODO
R
DBPROP_NOTFIYROWSETFETCHPOSITION DBPROPVAL_NP_OKTODO
CHANGE
DBPROPVAL_NP_ABOUTTODO
R
DBPROP_NOTIFYROWSETRELEASE
DBPROPVAL_NP_OKTODO
DBPROPVAL_NP_ABOUTTODO
R
DBPROP_NOTIFYROWUNDOCHANGE
DBPROPVAL_NP_OKTODO
DBPROPVAL_NP_ABOUTTODO
R
DBPROP_NOTIFYROWUNDODELETE
DBPROPVAL_NP_OKTODO
DBPROPVAL_NP_ABOUTTODO
R
DBPROP_NOTIFYROWUNDOINSERT
DBPROPVAL_NP_OKTODO
DBPROPVAL_NP_ABOUTTODO
R
DBPROP_NOTIFYROWUPDATE
DBPROPVAL_NP_OKTODO
DBPROPVAL_NP_ABOUTTODO
R
DBPROP_NOTIFYROWSETRELEASE
DBPROPVAL_NP_OKTODO
DBPROPVAL_NP_ABOUTTODO
R
DBPROP_REENTRANTEVENTS
TRUE
R
DBPROP_REPORTMULTIPLECHANGES
FALSE
R
DBPROP_RETURNPENDINGINSERTS
FALSE
R
DBPROP_ROWRESTRICT
FALSE
R
DBPROP_ROWTHREADMODEL
DBPROPVAL_RT_FREETHREAD
R
DBPROP_STRONGIDENTITY
FALSE
R
DBPROP_TRANSACTEDOBJECT
FALSE
R
DBPROP_UPDATETABILITY
0
R/W
DBPROP_BLOCKINGSTORAGEOBJECTS
TRUE
R
DBPROP_CHANGEINSERTEDROWS
TRUE
R
DBPROP_COLUMNRESTRICT
FALSE
R
OLE DB Provider for Teradata User Guide
Comments
109
Chapter 6: Supported Properties
Session Property Group
Session Property Group
Table 43: Session Property Group
Property
Default Value
Mode
Read
Write
DBPROP_SESS_AUTOCOMMITISOLEVELS
DBPROPVAL_TI_ISOLATED
R/W
110
Comments
See “Isolation Level and
Access Locking” on
page 97.
OLE DB Provider for Teradata User Guide
CHAPTER 7
Programming Limitations
This chapter explains the limitations of using OLE DB Provider for Teradata, which does not
fully support the OLE DB specification. For additional information on limitations for each
interface, see “Chapter 5 OLE DB Interfaces” on page 79.
The topics are:
•
Teradata Database Limitations
•
UTF8 and UTF16 Limitations
•
Provider Limitations
•
Logon Timeout Limitation
•
Teradata WITH Clause Limitation
•
Maximum Number of Parameters
•
Intervals
•
Stored Procedures
•
DLL File Limitation
Teradata Database Limitations
Limitations that exist in Teradata Database also exist for OLE DB Provider for Teradata. The
limitations are:
•
No support for distributed transactions.
•
No support for more than 2048 columns in table.
•
No support for more than 255 characters in a string constant.
•
No support for nested transactions.
•
No support for catalogs. The Schema name is equivalent to the Database name in
Teradata.
•
Support for only Static cursors that move forward.
•
For Teradata Database, SQL is limited to 1048448 bytes.
•
If attempting an update or delete using a qualified character (CHAR or VARCHAR)
column with characters containing a WAVE DASH or MINUS, Teradata may not be able to
process the request correctly, since there are multiple Unicode character translations to
SJIS (as well as EUC and EBCDIC) WAVE DASH or MINUS.
•
OLE DB Provider for Teradata does not support Bookmarks.
OLE DB Provider for Teradata User Guide
111
Chapter 7: Programming Limitations
UTF8 and UTF16 Limitations
UTF8 and UTF16 Limitations
Limitations imposed for UTF8 and UTF16 are:
•
There may be unexpected (larger) string lengths when retrieving Unicode character
columns in the UTF8 or UTF16 session character set.
•
The UTF8 session character set may cause up to a three-fold expansion of character data,
which may cause a given row size to exceed the internal Teradata 64K row size limit.
•
The UTF16 session character set may cause up to a two-fold expansion of character data
which may cause a given row size to exceed the internal Teradata 64K row size limit.
•
Teradata SQL limitations in UTF8 and UTF16 may prevent the reference of Kanji based
objects in UTF8 or UTF16 session character sets.
•
Error messages from Teradata in UTF8 or UTF16 are returned in English. This may cause
some confusion, since provider based error messages may return in Japanese on Japanese
client systems.
•
Users should be aware of limitations in DBTYPE_WSTR if the selected Teradata session
character set is not Unicode-based (UTF8 or UTF16). If a character cannot be translated to
the Teradata session character set, a default character will be inserted in its place. This
translation can cause undesired corruption of data. For users who have this kind of data,
application, or environment, it is recommended that the user utilize the UTF8 or UTF16
Teradata session character set.
•
Users should be aware of limitations in DBTYPE_STR if the selected Teradata session
character set is not Unicode based (UTF8 or UTF16), or the local code page does not
match the selected Teradata session character set. In this scenario, if certain characters do
not map between the local code page and the Teradata session character set, it will be
replaced with a default character. This translation can cause undesired corruption of data.
For users who have this type of environment, it is recommended that the user utilize the
UTF8 or UTF16 Teradata session character set.
Provider Limitations
The following limitations imposed by OLE DB Provider for Teradata:
112
•
OLE DB Provider for Teradata does not support table names enclosed in quotes. This
affects IOpenRowset.
•
If the consumer uses IOpenRowset::OpenRowset to open a table that requires quotes
enclosing the name, then the consumer is responsible for adding the quotes to the name of
the table.
•
Do not change the DECIMAL separator character associated with the default locale while
OLE DB Provider for Teradata is in use because doing so can result in erroneous values
being returned from OLE DB Provider for Teradata. Instead, stop all applications that use
OLE DB Provider for Teradata, then change the DECIMAL separator of the default locale
of the user on a client system (Start>Settings>Control Panel>Regional Options).
OLE DB Provider for Teradata User Guide
Chapter 7: Programming Limitations
Logon Timeout Limitation
Logon Timeout Limitation
The property that controls the logon time out is DBPROP_INIT_TIMEOUT. The default for
this property is 20 seconds. When this property is set to 0, OLE DB Provider for Teradata
times out immediately when IDBInitialize::Initialize is called. OLE DB Provider for Teradata
returns the error message:
[OLE DB Provider for Teradata]Logon timeout expired
This is a known limitation and will be corrected in a later version.
With OLE DB Provider for Teradata it is not possible to set an infinite timeout period. To
prevent OLE DB Provider for Teradata from timing out, we recommend setting
DBPROP_INIT_TIMEOUT to a large enough number to allow for the worst logon time
scenario for your Teradata Database.
Teradata WITH Clause Limitation
The Teradata WITH… BY clauses on SELECT statements are not supported.
Maximum Number of Parameters
The number of parameters that can be bound is limited to the number supported by Teradata
Database. The current limit is 2048 parameters.
This total includes all elements contained in each parameter set. For example, if a command
contains four parameters, there can only be a maximum of 512 parameter sets (4 parameters *
512 sets = 2048 total parameters).
Intervals
The OLE DB specification does not contain a data type that is equivalent to the Teradata
Database INTERVAL types such as:
•
INTERVAL YEAR
•
INTERVAL DAY
•
INTERVAL YEAR TO MONTH
If a column in a table is defined as an INTERVAL type, then OLE DB Provider for Teradata
interprets the data type for this column as DBTYPE_BYTES.
Because OLE DB Provider for Teradata is unable to identify columns of type INTERVAL, the
consumer cannot use the interfaces IRowsetChange and IRowsetUpdate to update rowsets
that contain INTERVAL columns.
OLE DB Provider for Teradata User Guide
113
Chapter 7: Programming Limitations
Stored Procedures
If the consumer attempts to update a row using the SetData, InsertRow, or DeleteRow
methods, then Teradata Database returns the following error message:
[Teradata Database]Invalid operation on ANSI Datetime or Interval value
Stored Procedures
Stored Procedures have not been fully implemented in this version and are not supported.
However, if you must use Stored Procedure, please be aware of the following:
•
Out parameters cannot be retrieved using Storage Objects. Specifying
DBPARAMFLAGS_ISLONG for output parameters is not supported. However, the user
can retrieve Stored Procedure Out parameters as Storage Object via Rowset by setting
value of the provider specific property
TDPROP_INIT_OUTPUTPARAMETERLOCATION to “ROWSET”. Please be aware that
this property is only for backward compatibility. See “Initialization Property Group” on
page 100 for more information.
•
ICommand::Execute always returns SQL_SUCCESS when the DDL statements CREATE
PROCEDURE or REPLACE PROCEDURE are executed.
If the CREATE PROCEDURE or the REPLACE PROCEDURE fails, ICommand::Execute
should return an error code and the error messages should return to the consumer
through the IErrorRecords interface.
However, in this version of OLE DB Provider for Teradata, error messages generated while
compiling a stored procedure are returned as a rowset.
•
When executing a stored procedure, OLE DB Provider for Teradata is unable to derive
information about parameters.
When the consumer uses parameters, the consumer must call
ICommandWithParameters::SetParameters to set the information on parameters.
DLL File Limitation
The DLL file, tdoledb.dll, may not get registered during the upgrade/installation procedure.
This results in the error code REGDB_E_CLASSNOTREG. This could happen even when the
previous installation has been removed.
The workaround is to change directory to the TDOLEDB installation directory and execute
the command:
regsvr32 tdoledb.dll
114
OLE DB Provider for Teradata User Guide
APPENDIX A
OLE DB to Teradata
Data Type Mappings
This appendix describes the binding of OLE DB data types to Teradata data types.
Data Types
The following table specifies the binding of the OLE DB types to Teradata data types.
Table 44: OLE DB Provider for Teradata to Teradata Data Type Mappings
OLE DB Data Type Indicator
Teradata Data Type
DBTYPE_BYTES
BYTE
DBTYPE_BYTES
VARBYTE
DBTYPE_BYTES
INTERVAL
DBTYPE_BYTES
BLOB
DBTYPE_DBDATE
DATE
DBTYPE_DBTIME
TIME
DBTYPE_I1
BYTEINT
DBTYPE_I2
SMALLINT
DBTYPE_I4
INTEGER
DBTYPE_I8
BIGINT
DBTYPE_NUMERIC
DECIMAL
DBTYPE_R8
FLOAT
DBTYPE_STR, DBTYPE_WSTR*
CHAR
DBTYPE_STR, DBTYPE_WSTR*
VARCHAR
DBTYPE_STR, DBTYPE_WSTR*
CLOB
DBTYPE_TIMESTAMP
TIMESTAMP
OLE DB Provider for Teradata User Guide
115
Appendix A: OLE DB to Teradata Data Type Mappings
Data Types
* The type associated with CHAR, VARCHAR, and CLOB is DBTYPE_STR if the session
character set is ASCII, KANJIJIS_OS. If the session character set is either UTF8 or UTF16,
then the type associated is DBTYPE_WSTR.
116
OLE DB Provider for Teradata User Guide
APPENDIX B
Using ADO with OLE DB Provider for
Teradata
This appendix describes how to design applications using Visual Basic with ActiveX Data
Objects (ADO). This appendix contains the following sections:
•
Making the Connection
•
Cursors
•
Recordset Methods
•
ADO Dynamic Properties
Making the Connection
The consumer can make the connection to the data source by setting the required properties
in either of two ways:
•
Using a connection string
•
Using the properties collection
Using a Connection String
Using the ADO property name, the connection string can set the following properties:
Table 45: Using the ADO Property String
ADO Property
OLE DB Property
Comments
Data Source
DBPROP_INIT_DATASOURCE
Use Data Source from the connection string to
specify the Teradata Database name or IP address.
Both IPv6 and IPv4 addresses are supported.
User ID
DBPROP_AUTH_USERID
Use User Id from the connection string to specify
the user id.
Password
DBPROP_AUTH_PASSWORD
Use Password from the connection string to specify
the password.
Extended Properties
DBPROP_INIT_PROVIDERSTRING
This is an optional property. You only need to
specify Extended Properties if an application
requires one of the provider string attributes to be
set to a value different than the default. See “Setting
Provider String Attributes” on page 43.
OLE DB Provider for Teradata User Guide
117
Appendix B: Using ADO with OLE DB Provider for Teradata
Making the Connection
The connection string:
strTeraCnxn = “Provider=TDOLEDB;Data Source=TERADATA1;” & _
“User Id=userid;Password=password;” & _
“Extended Properties=””Session Mode=TERADATA;””;“
sets these four properties so that a successful connection can be completed. In addition, the
Extended Properties sets the provider string DBPROP_INIT_PROVIDERSTRING.
Example – Visual Basic
The following Visual Basic example connects to a Teradata Database data source using a
connection string:
Public Sub OpenTeradata()
Dim TeraCnxn As ADODB.Connection
Dim strTeraCnxn As String
' Going to Open Connection
strTeraCnxn = “Provider=TDOLEDB;Data Source=TERADATA1;” & _
“User ID=userid;Password=password;” & _
“Extended Properties=””Session Mode=ANSI;Enable Parser=NO;””;“
Set TeraCnxn = New ADODB.Connection
TeraCnxn.Open strTeraCnxn
‘ =================================
‘
‘ REST OF PROGRAM…
‘
‘==================================
TeraCnxn.Close
Set TeraCnxn = Nothing
End Sub
Using the Properties Collection
You can also set the required four properties using the properties collection. See the following
sample Visual Basic program:
Example – Visual Basic
Dim TeraCnxn As New ADODB.Connection
With TeraCnxn
.Provider = "TDOLEDB"
.Properties("Data Source") = "Teradata1"
.Properties("User Id") = "userid"
.Properties("Password") = "password"
.Properties(“Extended Properties”)= “SESSIONMODE=TERADATA;”
.Open
End With
118
OLE DB Provider for Teradata User Guide
Appendix B: Using ADO with OLE DB Provider for Teradata
Cursors
Cursors
Client-Side Cursor
The consumer specifies client-side cursors by setting the Cursor Location property of the
connection object to adUseClient.
When the consumer specifies a client-side cursor, ADO uses the Client Cursor Engine (CCE)
that is part of Microsoft Data Access Components (MDAC). The CCE is an OLE DB rowset
implementation.
For more information on the Client Cursor Engine, refer to the following Microsoft
Developer’s Network (MSDN) Library site. See “Technical Assistance” on page 20.
•
MSDN Library - Go to http://msdn.microsoft.com/library/
•
Data Access
•
Microsoft Data Access Components
•
Technical Articles
•
OLE DB
•
Optimistic Remote Updating in the Client Cursor Engine
Server-Side Cursor
The consumer specifies server-side cursors by setting the Cursor Location property of the
connection object to adUseServer.
The server side cursor is maintained by Teradata Database. As stated in “Teradata Database
Limitations” on page 111, Teradata supports only static cursors that only move forward.
Therefore, the only supported Cursor Type property value is adOpenForwardOnly. If the
Cursor Type property is any other value (adOpenKeyset, adOpenDynamic, adOpenStatic)
OLE DB Provider for Teradata uses adOpenFowardOnly instead. ADO does the
substitution. OLE DB Provider for Teradata does not return an error when the recordset
object is opened.
For information on CursorLocation and CursorType properties, refer to the following MSDN
site. See “Technical Assistance” on page 20.
•
MSDN Library - Go to http://msdn.microsoft.com/library/
•
Data Access
•
Microsoft Data Access Components
•
SDK Documentation
•
Microsoft ActiveX Data Objects (ADO)
•
ADO Programmer’s Guide
•
ADO API Reference
•
ADO Properties
OLE DB Provider for Teradata User Guide
119
Appendix B: Using ADO with OLE DB Provider for Teradata
Recordset Methods
Recordset Methods
The following table lists the Recordset Methods and shows whether client-side and server-side
cursors support the methods. The Restrictions column shows any restrictions that affect the
methods.
Table 46: Recordset Methods
Supported
Method
Client-Side
Server-Side
AddNew
Yes
Yes
Cancel
Yes
Yes
CancelBatch
Yes
Yes
CancelUpdate
Yes
Yes
Clone
No
No
Close
Yes
Yes
Delete
Yes
Yes
Restrictions
Client Side Cursors restriction:
Rows in a recordset that contains TIME or TIMESTAMP columns
can only be modified using the Update and Delete methods under the
following conditions:
• The Underlying table contains a UNIQUE PRIMARY INDEX.
• The columns of the unique primary index are included in the
recordset.
• The TIME or TIMESTAMP columns are not being modified. This
only applies when using the Update method.
• TIME or TIMESTAMP columns cannot be included in the
UNIIQUE PRIMARY INDEX.
If the consumer does not meet these conditions, and the consumer
attempts to Update or Delete a row in a recordset that contains a
TIME or TIMESTAMP column, the following error message is
generated by Teradata Database:
[Teradata Database]Invalid operation on an ANSI
Datetime or Interval value.
Server-Side Cursors do not have this restriction.
Find
Yes
No
Server-Side Cursors:
Although the Supports method indicates that Find is supported, OLE
DB Provider for Teradata does not support the Find method.
GetRows
Yes
Yes
Server-Side Cursors Restriction:
Rows can only be retrieved starting from the current position.
120
OLE DB Provider for Teradata User Guide
Appendix B: Using ADO with OLE DB Provider for Teradata
ADO Dynamic Properties
Table 46: Recordset Methods (continued)
Supported
Method
Client-Side
Server-Side
Restrictions
Move
Yes
Yes
Server-Side Cursors Restrictions:
• Cursor can only move forward. Therefore, the NumRecords
parameter can only be positive.
• Bookmarks are not supported.
MoveFirst
Yes
Yes
MoveLast
Yes
No
MoveNext
Yes
Yes
MovePrevious
Yes
No
NextRecordset
Yes
Yes
Notifications
Yes
Yes
Open
Yes
Yes
Requery
Yes
Yes
Resync
Yes
Yes
Seek
No
No
Supports
Yes
Yes
Update
Yes
Yes
See restrictions for the Delete method.
UpdateBatch
Yes
Yes
See restrictions for the Delete method.
ADO Dynamic Properties
ADO Dynamic properties group into two categories:
•
Connection Dynamic Properties
•
Recordset Dynamic Properties
The following two tables indicate the dynamic ADO properties that OLE DB Provider for
Teradata supports. For more information, refer to Chapter 6: “Supported Properties.”
Connection Dynamic Properties
Table 47: Connection ADO Dynamic Properties
ADO Property Name
OLE DB Property Name
ActiveSessions
DBPROP_ACTIVESESSIONS
OLE DB Provider for Teradata User Guide
121
Appendix B: Using ADO with OLE DB Provider for Teradata
ADO Dynamic Properties
Table 47: Connection ADO Dynamic Properties (continued)
ADO Property Name
OLE DB Property Name
Asynchable Abort
DBPROP_ASYNCTXNABORT
Asynchable Commit
DBPROP_ASYNCTNXCOMMIT
Autocommit Isolation Levels
DBPROP_SESS_AUTOCOMMITISOLEVELS
Catalog Location
DBPROP_CATALOGLOCATION
Catalog Term
DBPROP_CATALOGTERM
Column Definition
DBPROP_COLUMNDEFINITION
Connect Timeout
DBPROP_INIT_TIMEOUT
Current Catalog
DBPROP_CURRENTCATALOG
Data Source
DBPROP_INIT_DATASOURCE
Data Source Name
DBPROP_DATASOURCENAME
Data Source Object Threading Model
DBPROP_DSOTHREADMODEL
DBMS Name
DBPROP_DBMSNAME
DBMS Version
DBPROP_DBMSVER
Extended Properties
DBPROP_INIT_PROVIDERSTRING
GROUP BY Support
DBPROP_GROUPBY
Heterogeneous Table Support
DBPROP_HETEROGENEOUSTABLES
Identifier Case Sensitivity
DBPROP_IDENTIFIERCASE
Initial Catalog
DBPROP_INIT_CATALOG
Isolation Levels
DBPROP_SUPPORTEDTXNISOLEVELS
Isolation Retention
DBPROP_SUPPORTEDTXNISORETAIN
Locale Identifier
DBPROP_INIT_LCID
Location
DBPROP_INIT_LOCATION
Maximum Index Size
DBPROP_MAXINDEXSIZE
Maximum Row Size
DBPROP_MAXROWSIZE
Maximum Row Size Includes BLOB
DBPROP_MAXROWSIZEINCLUDESBLOB
Maximum Tables in SELECT
DBPROP_MAXTABLESINSELECT
Mode
DBPROP_INIT_MODE
Multiple Parameter Sets
DBPROP_MULTIPLEPARAMSETS
Multiple Results
DBPROP_MULTIPLERESULTS
Multiple Storage Objects
DBPROP_MULTIPLESTORAGEOBJECTS
122
OLE DB Provider for Teradata User Guide
Appendix B: Using ADO with OLE DB Provider for Teradata
ADO Dynamic Properties
Table 47: Connection ADO Dynamic Properties (continued)
ADO Property Name
OLE DB Property Name
Multi-Table Update
DBPROP_MULTITABLEUPDATE
NULL Collation Order
DBPROP_NULLCOLLATION
NULL Concatenation Behavior
DBPROP_CONCATNULLBEHAVIOR
OLE DB Services
DBPROP_INIT_OLEDBSERVICES
OLE DB Version
DBPROP_PROVIDEROLEDBVER
OLE Object Support
DBPROP_OLEOBJECTS
Open Rowset Support
DBPROP_OPENROWSETSUPPORT
ORDER BY Columns in Select List
DBPROP_ORDERBYCOLUMNSINSELECT
Output Parameter Availability
DBPROP_OUTPUTPARAMETERAVAILABILITY
Password
DBPROP_AUTH_PASSWORD
Pass By Ref Accessors
DBPROP_BYREFACCESSORS
Persistent ID Type
DBPROP_PERSISTENTIDTYPE
Persist Security Info
DBPROP_AUTH_PERSIST_SENSITIVE_AUTHINFO
Prepare Abort Behavior
DBPROP_PREPAREABORTBEHAVIOR
Prepare Commit Behavior
DBPROP_PREPARECOMMITBEHAVIOR
Procedure Term
DBPROP_PROCEDURETERM
Prompt
DBPROP_INIT_PROMPT
Provider Friendly Name
DBPROP_PROVIDERFRIENDLYNAME
Provider Name
DBPROP_PROVIDERFILENAME
Provider Version
DBPROP_PROVIDERVER
Read-Only Data Source
DBPROP_DATASOURCEREADONLY
Rowset Conversions on Command
DBPROP_ROWSETCONVERSIONSONCOMMAND
Schema Term
DBPROP_SCHEMATERM
Schema Usage
DBPROP_SCHEMAUSAGE
SQL Support
DBPROP_SQLSUPPORT
Structured Storage
DBPROP_STRUCTUREDSTORAGE
Subquery Support
DBPROP_SUBQUERIES
Table Term
DBPROP_TABLETERM
Transaction DDL
DBPROP_SUPPORTEDTXNDDL
User ID
DBPROP_AUTH_USERID
OLE DB Provider for Teradata User Guide
123
Appendix B: Using ADO with OLE DB Provider for Teradata
ADO Dynamic Properties
Table 47: Connection ADO Dynamic Properties (continued)
ADO Property Name
OLE DB Property Name
User Name
DBPROP_USERNAME
Window Handle
DBPROP_INIT_HWND
Recordset Dynamic Properties
Table 48: Recordset ADO Dynamic Properties
ADO Property Name
OLE DB Property Name
Access Order
DBPROP_ACCESSORDER
Blocking Storage Objects
DBPROP_BLOCKINGSTORAGEOBJECTS
Bookmarkable
DBPROP_IROWSETLOCATE
Bookmark Type
DBPROP_BOOKMARKTYPE
Change Inserted Rows
DBPROP_CHANGEINSERTEDROWS
Column Privileges
DBPROP_COLUMNRESTRICT
Column Set Notification
DBPROP_NOTIFYCOLUMNSET
Delay Storage Object Updates
DBPROP_DELAYSTORAGEOBJECTS
Fetch Backwards
DBPROP_CANFETCHBACKWARDS
Hold Rows
DBPROP_CANHOLDROWS
IAccessor
DBPROP_IAccessor
IColumnsInfo
DBPROP_IColumnsInfo
IColumnsRowset
DBPROP_IColumnsRowset
IConnectionPointContainer
DBPROP_IConnectionPointContainer
IConvertType
DBPROP_IConvertType
Immobile Rows
DBPROP_IMMOBILEROWS
IRowset
DBPROP_IRowset
IRowsetChange
DBPROP_IRowsetChange
IRowsetIdentity
DBPROP_IRowsetIdentity
IRowsetInfo
DBPROP_IRowsetInfo
IRowsetLocate
DBPROP_IRowsetLocate
IRowsetUpdate
DBPROP_IRowsetUpdate
ISequentialStream
DBPROP_ISequentialStream
ISupportErrorInfo
DBPROP_ISupportErrorInfo
124
OLE DB Provider for Teradata User Guide
Appendix B: Using ADO with OLE DB Provider for Teradata
ADO Dynamic Properties
Table 48: Recordset ADO Dynamic Properties (continued)
ADO Property Name
OLE DB Property Name
Literal Bookmarks
DBPROP_LITERALBOOKMARKS
Literal Row Identity
DBPROP_LITERALIDENTITY
Maximum Open Rows
DBPROP_MAXOPENROWS
Maximum Pending Rows
DBPROP_MAXPENDINGROWS
Maximum Rows
DBPROP_MAXROWS
Notification Granularity
DBPROP_NOTIFICATIONGRANULARITY
Notification Phases
DBPROP_NOTIFICATIONPHASES
Objects Transacted
DBPROP_TRANSACTEDOBJECT
Own Changes Visible
DBPROP_OWNUPDATEDELETE
Own Inserts Visible
DBPROP_OWNINSERT
Preserve on Abort
DBPROP_ABORTPRESERVE
Preserve on Commit
DBPROP_COMMITPRESERVE
Quick Restart
DBPROP_QUICKRESTART
Reentrant Events
DBPROP_REENTRANTEVENTS
Remove Deleted Rows
DBPROP_REMOVEDELETED
Report Multiple Changes
DBPROP_REPORTMULTIPLECHANGES
Return Pending Inserts
DBPROP_RETURNPENDINGINSERTS
Row Delete Notification
DBPROP_NOTIFYROWDELETE
Row First Change Notification
DBPROP_NOTIFYROWFIRSTCHANGE
Row Insert Notification
DBPROP_NOTIFYROWINSERT
Row Privileges
DBPROP_ROWRESTRICT
Row Resynchronization Notification
DBPROP_NOTIFYROWRESYNCH
Rowset Fetch Position Change Notification
DBPROP_NOTIFYROWSETFETCHPOSISIONCHANGE
Rowset Release Notification
DBPROP_NOTIFYROWSETRELEASE
Row Threading Model
DBPROP_ROWTHREADMODEL
Row Undo Change Notification
DBPROP_NOTIFYROWUNDOCHANGE
Row Undo Delete Notification
DBPROP_NOTIFYROWUNDODELETE
Row Undo Insert Notification
DBPROP_NOTIFYROWUNDOINSERT
Row Update Notification
DBPROP_NOTIFYROWUPDATE
Scroll Backwards
DBPROP_CANSCROLLBACKWARDS
OLE DB Provider for Teradata User Guide
125
Appendix B: Using ADO with OLE DB Provider for Teradata
ADO Dynamic Properties
Table 48: Recordset ADO Dynamic Properties (continued)
ADO Property Name
OLE DB Property Name
Skip Deleted Bookmarks
DBPROP_BOOKMARKSKIPPED
Strong Row Identity
DBPROP_STRONGITDENTITY
Unique Rows
DBPROP_UNIQUEROWS
Updatability
DBPROP_UPDATABILITY
Use Bookmarks
DBPROP_BOOKMARKS
126
OLE DB Provider for Teradata User Guide
Glossary
A
ActiveX Data Object (ADO) Microsoft library for accessing data sources through OLE DB.
Typically it is used to query or modify data stored in a relational database.
American National Standards Institute (ANSI) The private, non-profit organization
responsible for approving United States standards in many areas, including computers and
communications.
B
binary large object (BLOB) A large database object that can be anything that doesn’t
require character set conversion. This includes MIDI, MP3, PDF, graphics and much more.
BLOBS can be up to 2 GB in size.
C
Client Cursor Engine (CCE) When the consumer specifies a client-side cursor, ADO uses
the Client Cursor Engine that is part of Microsoft Data Access Components (MDAC). The
CCE is an OLE DB rowset implementation.
character large object (CLOB) A pure character-based large object in a database. It can be a
large text file. HTML, RTF or other character-based file. CLOBs can be up 2 GB in size. Also
see BLOB.
Component Object Model (COM) The Microsoft OLE object-oriented programing model
that defines a standard mechanism in Windows environments for creating program
components and for clients and components to interact. In COM, clients access a component
through a pointer to an interface on the component. Every COM component supports the
interface.
D
database administrator (DBA) A person responsible for the design and management of one
or more databases and for the evaluation, selection and implementation of database
management systems.
DBC
Acronym for Database Computer.
Database Manipulation Language (DML) In Teradata SQL, the statements and facilities
that manipulate or change the information content of the database. These statements include
INSERT, UPDATE, and DELETE.
OLE DB Provider for Teradata User Guide
127
Glossary
F
foreign key (FK) One or more table attributes that can uniquely identify a record in another
table. A foreign key is the primary key of another table.
I
Internet Protocol version 4 (IPv4) The dominant Internet layer protocol at the time of this
publication. IPv4 uses 32-bit addresses often represented in a textual format similar to
“153.65.20.48”.
Internet Protocol version 6 (IPv6) The designated successor to IPv4. IPv6 uses 128-bit
addresses, for example: 2001:db8:85a3::8a2e:370:7334.
L
large object (LOB) A database object that is large in size. LOBs can be up to 2 gigabytes.
There are two types of LOBs: CLOBs and BLOBs. CLOBs are character-based objects, BLOBs
are binary-based objects.
M
Massively Parallel Processing (MPP) A Massively Parallel Processing (MPP)
implementation of Teradata consists of multiple SMP nodes that work together. The nodes are
connected through the BYNET, a combination of hardware and software that allows the
vprocs (PEs and AMPs) to communicate with each other. Teradata is a linearly expandable
database system because as additional nodes and vprocs are added, the system capacity scales
in a linear fashion.
Microsoft Data Access Components (MDAC) Microsoft's umbrella term for their ActiveX
Data Objects (ADO), OLE DB, and Open Database Connectivity (ODBC) libraries. Together,
these provide access to a variety of data sources, both relational (SQL) and nonrelational.
MDAC is the technology that supports Universal Data Access, Microsoft's strategy for
providing access to information across the enterprise.
MSDN
Microsoft Developer’s Network.
O
OLE DB A set of component object model (COM) interfaces that provide applications with
uniform access to data stored in diverse information sources and that also provide the ability
to implement additional database services.
P
primary key (PK) A column in a table whose value uniquely identifies its row in the table. It
cannot be a NULL value.
128
OLE DB Provider for Teradata User Guide
Glossary
S
Single Sign On (SSO) An authentication option that allows Teradata Database on Windows
2000 users to access Teradata Database based on authorized network usernames and
passwords. This feature simplifies the procedure requiring users to enter an additional
username and password when logging on to Teradata Database using client applications.
Stored Procedure Language (SPL) Teradata provides SPL to create stored procedures. A
stored procedure contains SQL to access data from within Teradata and SPL to control the
execution of the SQL.
Structured Query Language (SQL) An industry-standard language for creating, updating,
and querying RDBMSs. IBM developed SQL in the 1970s for use in System R. It is the default
standard as well as being an ISO and an ANSI standard. It is often embedded in generalpurpose programming languages. A programming language used to communicate with
Teradata Database.
Symmetric Multi Processing (SMP) An SMP platform consists of a single Teradata node.
An SMP system has multiple CPUs that work together. All applications run under a single
operating system on the node. The AMPs and PEs on an SMP system communicate through
the BYNET software that handles the message queuing and flow control.
U
UDL
Universal Data Link.
OLE DB Provider for Teradata User Guide
129
Glossary
130
OLE DB Provider for Teradata User Guide
Index
A
account string 28, 44
example 31
if not valid 44
no semicolons 43
ADO dynamic properties 121
auto-incremented columns, not supported 83
B
backward scrolling 94
binary large objects. See BLOB
BLOB 55, 57
bookmarks, not supported 100, 111
C
CALL statement, in escape clause 46
catalog, not supported 85
changing data
via DML 49
via rowset objects 50
CHAR_TYPE column 89
character large objects. See CLOB
character sets 47
CLOBs 55, 57
collation sequence 86
IDBSchemaRowset 86
columns
aliases 51, 83
custom 88
names 30
privileges 87
schema rowset 88
titles 30
ColumnsRowset::GetColumnsRowset 64
compilation, errors and messages 58
connecting to Teradata Database 23, 117
directly 23
IDBPromptInitialize interface 33
login screen 27
PromptDataSource 34
PromptFileName 40
via connection string 117
via properties collection 118
connection
dynamic properties 121
OLE DB Provider for Teradata User Guide
required properties 23
COP 67
COP Down Retry 68, 69
create procedure
with print 44
with SPL text 45
creating UDFs 58
cursors, client and server 119
custom error object 77
D
Data Link Properties dialog 34–38
data source
initializing 24
object, required property values of 22
specifying 36
data type mappings, OLE DB to Teradata 115
Date data types 63
dates, restrictions 63
DB_AUTH_PASSWORD 47
DB_E_ERROROCCURRED 48
DB_E_ERRORSOCCURRED 64
DB_E_PARAMNOTOPTIONAL 67
DB_E_SEC_AUTH_FAILED 44
DB_S_ERROROCCURRED 43
DB_SEC_E_AUTH_FAILED 32, 47
DBACCESSOR_OPTIMIZED 82
DBC name 23, 28
DBCOLUMN_BASECOLUMN 83
DBCOLUMN_BASECOLUMNNAME 83, 84
DBCOLUMN_DATETIMEPRECISION 84
DBCOLUMN_FLAGS 84
DBCOLUMN_IDNAME 84
DBCOLUMN_ISAUTOINCREMENT 83, 84
DBCOLUMN_ISCASESENSITIVE 83, 84
DBCOLUMN_ISSEARCHABLE 84
DBCOLUMN_NAME 83, 84
DBCOLUMN_NUMBER 84
DBCOLUMN_OCTETLENGTH 84
DBCOLUMN_PRECISION 84
DBCOLUMN_SCALE 84
DBCOLUMN_SIZE 84
DBCOLUMN_TYPE 84
DBCOLUMNFLAGS 82
DBCOLUMNFLAGS_ISFIXEDLENGTH 83
DBCOLUMNFLAGS_ISNULLABLE 83
131
Index
DBCOLUMNFLAGS_MAYBENULL 83
DBCOLUMNFLAGS_WRITEUNKNOWN 83
DBCOLUMNINFO 83
DBPROMPT_COMPLETE 27
DBPROMPT_COMPLETEREQUIRED 27
DBPROMPT_NOPROMPT 27, 32
DBPROMPT_PROMPT 27
DBPROP_AUTH_PASSWORD 22
DBPROP_AUTH_USERID 22
DBPROP_BOOKMARKSKIPPED not supported 100
DBPROP_BOOKMARKTPE not supported 100
DBPROP_INIT_DATASOURCE 22
DBPROP_INIT_PROMPT 23, 27
DBPROP_INIT_PROVIDERSTRING 23, 24, 31, 43, 44
DBPROP_INIT_TIMEOUT 24
DBPROP_IRowsetChange 50
DBPROP_IRowsetUpdate 50
DBPROP_UPDATABILITY 50
DBPROPMPT_NOPROMPT 23
DBPROPSET_DBINIT 24, 28
properties 22
DBPROPSTATUS_BADVALUE 43, 48, 49
default account 44
default database 28, 45, 86
example 31
IDBSchemaRowset 86
not in provider string 45
not valid 45
deferred mode, IRowsetUpdate 50
DML statements 54
DNS Cache 68
DOUBLE type restriction 51
dwFlags 83
dynamic properties
ADO 121
connection 121
Recordset 124
E
E_FAIL 95
edit property value 39
enable parser 45
errors
code, native 72
information, retrieving 72
objects, Teradata Database 77
properties 77
provider messages 75
source messages 71
structure 71
Teradata messages 74
example
C++ retrieving errors 75
132
column alias and IColumnsRowset 83
connection string 118
DBPROP_INIT_PROMPT 32
FLOAT restriction 51
initializing data source 24
login screen entry precedence 31
PromptDataSource 39
PromptFileName 41
properties collection 118
provider string format 43
Teradata error message format 75
VB and ADO check for errors 77
F
FLOAT type restriction 51, 95
foreign keys schema rowset 89
FORMAT column 89
G
GetError 72
GetParameterInfo 85
GTW control utility 26
I
IAccessor 82
IAccessor::CreateAccessor 49
IColumnsInfo 82
IColumnsInfo::GetColumnsInfo 64
IColumnsRowset 83, 84
ICommand 84
ICommand::Execute 49, 51
ICommandPrepare::Prepare 49
ICommandText::SetCommandText 49
ICommandWithParameter 85
IDataInitialize::LoadStringFromStorage 41
IDataInitize::WriteStringToStorage 40
IDBInitialize::Initialize 24
IDBPromptInitialize 33
IDBPromptInitialize::PromptFileName 40
IDBProperties::SetProperties 23
IDBProperties::SetProperty 43
IDBSchemaRowset 85
IErrorInfo 72
IErrorRecords 72
IErrorRecords::GetBasicInfo 72
IErrorRecords::GetCustomErrorObjects 72
IID_ISQLErrorInfo 72
immediate mode, IRowsetChange 50
indexes schema rowset 90
initialization property group, properties table 100
initialization property group, setting properties 24
INTEGER FORMAT ’99:99:99’ 95
OLE DB Provider for Teradata User Guide
Index
interfaces
IAccessor 82
IColumnsInfo 82
IColumnsRowset 83
ICommand 84
ICommandWithParameter 85
IDBSchemaRowset 85
IRowset 94
IRowsetChange 95
ITransaction 96
ITransactionLocal 96
list of supported 81
list of unsupported 79
Internet Explorer, required version 20
Internet protocol 67
INTERVAL data type, limitations 113
IOpenRowset:: OpenRowset 51
IP addresses 67
IRowset 94
IRowset::RestartPosition 95
IRowset::SetData 52
IRowsetChange 49, 95
Delete 95
SetData 53, 95
IRowsetResynch not supported 95
IRowsetUpdate 49
isolation levels
access locking 97
upgrading 96
ISOLATIONLEVEL_READUNCOMMITTED 96
ISOLATIONLEVEL_SERIALIZED 96
ISQLErrorInfo 72
ITransaction 96
ITransaction::Commit 49, 50, 96
ITransactionLocal 96
ITransactionLocal::StartTransaction 48, 49, 50, 96
K
kanji character set 47
keys, defining foreign keys 89
L
LABEL column 89
large objects 55
limitations 111
client side cursors and TIME, TIMESTAMP 120
COLUMN_HASDEFAULT 88
DBCOLUMN_ISCASESENSITIVE 83
dll files 114
intervals 113
login timeout 113
provider 112
attribute values 31
OLE DB Provider for Teradata User Guide
search multiple databases 92
server side cursors
and Find 120
and GetRow 120
and Move 121
sort 88, 90, 92
stored procedures 114
use X views 92
WITH clause 113
load balancing 67
LOBs 55
login
screen
displaying 27
entry takes precedence 31
fields 28, 29
preventing display 32
provider string 31
sequence 30
timeout limitation 113
M
macros, Teradata Database 91, 92
map Call-Esc-Seq to exec 46
metadata columns, supported 84
multiple databases, search limitation 92
N
native error codes 72, 74
new password 47
NumberOfCOPs 67, 69
O
operating system requirements 19
Options dialog box 29
P
parameters
in SQL 94
maximum number 113
parser 45
and escape clause 46
password 23, 28
encryption 26
expired 47
secondary 47
specifying 36
PRIMARY KEY clause requirement 91
primary keys schema rowset 90
privileges 88
types, column privileges 87
133
Index
procedures
parameters, schema rowset 91
schema rowset 92
product version numbers 3
PromptDataSource 34
PromptFileName
connecting via 40
initializing 34
provider
selecting 35
string
attributes list 44
format 43
setting attributes 43
user entry 38
types, schema rowset 94
R
REAL type restriction 51
recordset methods 120
Recordset, dynamic properties 124
ReleaseAccessors 95
ReleaseRows 95
response size, maximum 46
restrictions
column schema rowset 88
IDBSchemaRowset 85
primary keys 91
rowset 50
schema rowset 90
tables schema rowset 93
type DOUBLE 51
type FLOAT 51
type REAL 51
rowset
properties
setting 50
values and modes 107
restrictions 50
S
schema rowsets
supported list 86
UDTs and UDMs 60
schemata schema rowset 92
scrolling backward 94
Security Support Provider Interface (SSPI) 26
session
character set 47, 103
mode 48
properties
chart of values and modes 110
setting 23
134
SetParameterInfo 85
setting property values 27
Single Sign On (SSO) 26
defined 129
software versions, minimum required 20
sort, not in provider types schema rowset 94
SQLState 72
start transaction
implicit/explicit 48
manually 50
stored procedures
limitations 114
print option 44
store SPL text 45
system requirements 19
T
TABLE_TYPE, values in tables schema rowset 93
technical assistance 20
Teradata Database Connection dialog 26
Teradata Database, required versions 20
Teradata port number 48
TIME data type 63
timeout, connection 37
TIMESTAMP data type 63
U
UDFs 58
UDL file, PromptFileName 40
UDMs 60
UDTs 60
Use As Column Name field 30
use X views 48, 93
user ID 23, 28, 36
user-defined methods. See UDMs
user-defined types. See UDTs
V
version numbers 3
W
WITH clause limitation 113
X
XACTTC_SYNC commit option 96
OLE DB Provider for Teradata User Guide