2516 071a

Teradata Parallel Transporter
Application Programming Interface

Programmer Guide
Release 14.00
B035-2516-071A
June 2012
The product or products described in this book are licensed products of Teradata Corporation or its affiliates.
Teradata, Active Enterprise Intelligence, Applications-Within, Aprimo, Aprimo Marketing Studio, Aster, BYNET, Claraview, DecisionCast,
Gridscale, Managing the Business of Marketing, MyCommerce, Raising Intelligence, Smarter. Faster. Wins., SQL-MapReduce, Teradata Decision
Experts, "Teradata Labs" logo, "Teradata The Best Decision Possible" logo, "Teradata Raising Intelligence" logo, Teradata Source Experts,
WebAnalyst, and Xkoto are trademarks or registered trademarks of Teradata Corporation or its affiliates in the United States and other countries.
Adaptec and SCSISelect are trademarks or registered trademarks of Adaptec, Inc.
AMD Opteron and Opteron are trademarks of Advanced Micro Devices, Inc.
Axeda is a registered trademark of Axeda Corporation. Axeda Agents, Axeda Applications, Axeda Policy Manager, Axeda Enterprise, Axeda
Access, Axeda Software Management, Axeda Service, Axeda ServiceLink, and Firewall-Friendly are trademarks and Maximum Results and
Maximum Support are servicemarks of Axeda Corporation.
Data Domain, EMC, PowerPath, SRDF, and Symmetrix are registered trademarks of EMC Corporation.
GoldenGate is a trademark of Oracle.
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 is a registered trademark 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.
NetVault is a trademark or registered trademark of Quest Software, Inc. in the United States and/or other countries.
Novell and SUSE are registered trademarks of Novell, Inc., in the United States and other countries.
Oracle, Java, and Solaris are registered trademarks of Oracle and/or its affiliates.
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.
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 registered trademark of Unicode, Inc. in the United States and other countries.
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 email: teradata-books@lists.teradata.com.
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 2005 - 2012 by Teradata Corporation. All Rights Reserved.
Teradata Parallel Transporter Application Programming Interface Programmer Guide 3
Preface
Purpose
This book provides information about Teradata Parallel Transporter Application
Programming Interface (Teradata PT API) Programmer Guide, a Teradata
Tools and Utilities

product. Teradata Tools and Utilities is a group of products designed to work with Teradata
Database.
Teradata PT API is a set of application programming interfaces used to load data in, and
export data from, the Teradata Database.
This book describes how to set up the interface, error reporting, checkpoint and restart, and
other relevant topics and includes coding examples.
Audience
This book is intended for use by:
Database administrators
Relational database developers
Field engineers
Test engineers
Supported Releases
This book supports the following releases:
Teradata Database 14.0
Teradata Tools and Utilities 14.00
Teradata Parallel Transporter Application Programming Interface 14.00
Teradata PT ICU Library
Note: To verify the Teradata Parallel Transporter Application Programming Interface
driver version number review these events:
For the Load driver, see TD_Evt_Version on page 85 and TD_TRACE_LEVEL on
page 81.
For the Update driver, see TD_Evt_Version on page 104 and TD_TRACE_LEVEL on
page 100.
Preface
Prerequisites
4 Teradata Parallel Transporter Application Programming Interface Programmer Guide
For the Stream driver, see TD_Evt_Version on page 132 and TD_TRACE_LEVEL on
page 128.
For the Export driver, see TD_Evt_Version on page 155 and TD_TRACE_LEVEL on
page 153.
The Teradata Tools and Utilities 14.10 version of the following products are required for
Teradata Parallel Transporter Application Programming Interface:
Teradata International Components for Unicode (Teradata ICU)
Teradata Generic Security Services (TeraGSS)
Teradata Call Level Interface, Version 2 (Teradata CLI V2)
Teradata Parallel Transporter Operator Support Library
Teradata Parallel Transporter Export Operator (if used)
Teradata Parallel Transporter Load Operator (if used)
Teradata Parallel Transporter Update Operator (if used)
Teradata Parallel Transporter Stream Operator (if used)
See Appendix A: Platform Compilers for the supported versions and releases of the platform
compilers.
To locate detailed supported-release information:
1 Go to http://www.info.teradata.com/.
2 Under Online Publications, click General Search.
3 Type 3119 in the Publication Product ID box.
4 Under Sort By, select Date.
5 Click Search.
6 Open the version of the Teradata Tools and Utilities ##.# Supported Platforms and
Product Versions spreadsheet associated with this release.
The spreadsheet includes supported Teradata Database versions, platforms, and product
release numbers.
Prerequisites
The following prerequisite knowledge is required for this product:
Computer technology and terminology
Teradata Database
Relational database management systems
Connectivity software, such as ODBC
Microsoft

Windows

2000, Windows XP, Oracle Solaris running on a SPARC system,
Solaris running on an AMD Opteron system, IBM AIX, LINUX, HP-UX, and IBM z/OS
operating systems
Preface
Changes to This Book
Utilities that load and export data
Changes to This Book
The following changes were made to this book in support of the current release. Changes are
marked with change bars. For a complete list of changes to the product, see the Teradata Tools
and Utilities Release Definition associated with this release.
Date and Release Description
June 2012
14.00
The Load, Update, Stream, and Export drivers support 64-bit row count
variables.
Documented the optional attribute TD_MARCROCHARSET for the
Stream Operator.
The Stream driver supports Rate and Periodicity options.
Clarified reference to Teradata Replication Services using Oracle
GoldenGate.
The Load Driver and the Update Drivers support TD_Evt_ApplyCount64.
Removed documentation of the "TD_NONE" DataType.
The Export Driver supports the TD_RETN_ACT_DATATYPE (Return
Actual Data Type) attribute.
Added TPTAPI sample program (Export_To_Load) to chapter 6 (Export
Driver).
November 2011
14.00
Documented limitations on NoSpool mode for the Export driver.
Teradata PT API supports NUMBER data type.
Teradata PT API supports DBS Array data type.
Teradata PT API can automatically disable sending events to TMSM.
Teradata PT API precompiled platform-specific applications enable users to
validate that Teradata PT was installed properly.
Teradata PT API sends a response to the user application when the Teradata
Database is down.
Teradata PT API provides platform-specific quick start validation scripts
that execute Teradata PT quick start job scripts.
Added appendix D (Teradata PT Publications).
Preface
Additional Information
Additional information that supports this product and the Teradata Tools and Utilities is
available at the following web sites.
August 2011
14.00
The Export operator supports the dynamic schema feature for multiple
instance jobs.
The Stream operator supports an attribute for keeping or dropping macros.
Teradata PT API applications can load the TELAPI library dynamically
during runtime.
Teradata PT API supports infrastructure trace.
Teradata PT API code samples revised.
Teradata PT API supports a GetEvent query to retrieve an operators
version information.
Available exported functions have been documented.
References to TD_NO_OPERATOR removed.
VARBYTE data with length less than or equal to the defined length in the
DEFINE SCHEMA statement is allowed.
A new sample application showing how to use the dynamic schema feature
is available in the mnode_dynschema directory.
Date and Release Description
Type of Information Description Source
Release overview
Late information
Use the Release Definition for the following
information:
Overview of all 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 support center
2 Under Online Publications, click General Search
3 Type 2029 in the Publication Product ID box.
4 Click Search.
5 Select the appropriate Release Definition from
the search results.
Preface
Additional product
information
Use the Teradata Information Products web
site to view or download specific manuals
that supply related or additional
information to this manual.
2 Under the Online Publications subcategory,
Browse by Category, click Data Warehousing.
3 Do one of the following:
For a list of Teradata Tools and Utilities
documents, click Teradata Tools and Utilities,
and then select an item under Releases or
Products.
Select a link to any of the data warehousing
publications categories listed.
Specific books related to Teradata PT are as follows:
Teradata Tools and Utilities Access Module
Programmer Guide
B035-2424
Teradata Tools and Utilities Access Module
Reference
B035-2425
Teradata Parallel Transporter Application
Programming Interface Programmer Guide
B035-2516
Teradata Parallel Transporter Operator
Programmer Guide
B035-2435
Teradata Parallel Transporter Quick Start Guide
B035-2501
Teradata Parallel Transporter Reference
B035-2436
Teradata Parallel Transporter User Guide
B035-2445
Teradata Tools and Utilities Installation Guide for
IBM z/OS
B035-3128
Microsoft Windows
B035-2407
Red Hat Enterprise Linux
B035-3121
SUSE Linux
B035-3122
IBM s390x Linux
B035-3123
HP-UX
B025-3124
Preface
IBM AIX
B035-3125
Oracle Solaris on AMD Opteron Systems
B035-3126
Oracle Solaris on SPARC Systems
B035-3127
CD-ROM images Access a link to a downloadable CD-ROM
image of all customer documentation for
this release. Customers are authorized to
create CD-ROMs for their use from this
image
2 Under the Online Publications subcategory,
Browse by Category, click Data Warehousing.
3 Click CD-ROM Images.
4 Follow the ordering instructions.
Ordering
information for
manuals
Use the Teradata Information Products web
site to order printed versions of manuals.
2 Under Print & CD Publications, click How to
Order.
3 Follow the ordering instructions.
General information
about Teradata
The Teradata home page provides links to
numerous sources of information about
Teradata. Links include:
Executive reports, case studies of
customer experiences with Teradata,
and thought leadership
Technical information, solutions, and
expert advice
Press releases, mentions and media
resources
Go to Teradata.com/t/resources.
Select a link.
Table of Contents
Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
Supported Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4
Changes to This Book. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5
Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
Chapter 1:
Coding a Teradata PT Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Scripting and Teradata API Environments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Coding Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Build a Teradata PT Database Connection Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Initiate a Teradata PT Database Connection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Load Data into or Export Data from the Teradata Database. . . . . . . . . . . . . . . . . . . . . . . 27
Interpret Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Add Checkpoint and Restart. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Query Run-Time Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Modify Job after Initiate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Utilize Serialization with the Stream Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Utilize Use Lists with DML Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Terminate the Teradata PT Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Special Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Reusing a Teradata PT Connection Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Query Banding Teradata Database Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Using the UTF16 Session Character Set. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Using the Export Drivers Dynamic Schema Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Enabling Teradata PT API Infrastructure-Specific Tracing. . . . . . . . . . . . . . . . . . . . . . . . 40
Available Teradata Parallel Transporter Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Validating that Teradata PT Quick Start Job Scripts Execute . . . . . . . . . . . . . . . . . . . . . . 41
Table of Contents
Chapter 2:
Interface Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
Connection Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
Schema Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54
DML Group Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59
Teradata PT Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
DML Option. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
TD_Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64
TD_DataType. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65
TD_Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67
TD_OperatorType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67
TD_TRACE_LEVEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .68
Teradata PT Status Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .68
Dynamic Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70
Extern C Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70
DynamicLibrary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71
Chapter 3:
Load Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
Attribute Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
Required Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
Optional Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74
GetEvent Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82
Programming Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85
Error Tables and Error Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .86
Limiting Insertion Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .86
Dropping Tables During a Load. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .86
Required Privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87
Session Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87
Space Requirements and Limitations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87
Checkpoint and Restart Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87
Code Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87
Chapter 4:
Update Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91
Attribute Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91
Table of Contents
Required Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Optional Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
GetEvent Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Programming Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Error Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Using DELETE in Import Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Using Delete Task. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Dropping Tables During a Load. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Required Privileges. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Session Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Offline AMPs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Nonparticipant AMPs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Single-AMP Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Space Requirements and Limitations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Checkpoint and Restart Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Code Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Chapter 5:
Stream Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Attribute Definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Required Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Optional Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
GetEvent Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
PutEvent Modifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Programming Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Stream Driver Private Logs for TD_Evt_UserCommand . . . . . . . . . . . . . . . . . . . . . . . . 134
Error Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Reusing Stream Driver Table Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Limiting Errors in the Stream Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Dropping Tables During a Load. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Required Privileges. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Session Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Obtaining the Row Count Using TD_Evt_ApplyCount . . . . . . . . . . . . . . . . . . . . . . . . . 137
Space Requirements and Limitations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Tuning the Pack Factor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Using DELETE in Import Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Stream Driver Macro Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Using the MacroCharSet Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Checkpoint and Restart Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Code Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Table of Contents
Chapter 6:
Export Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145
Attribute Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145
Required Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145
Optional Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .147
GetEvent Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .154
PutEvent Modifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155
Programming Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155
SELECT REQUESTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155
Session Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .157
Performance Factors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .157
Checkpoint and Restart Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .158
NoSpool Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .158
Code Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .159
Sample Export_To_Load Program for Returning the Actual Data Type . . . . . . . . . . . . . . . .161
Chapter 7:
Parallelism Enabling Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175
Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .176
Parallel Communication Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .176
Parallel Processing Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .176
Special Parallel Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .177
Parallel Checkpoint and Restart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .178
Parallel Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .178
Parallel Run-Time Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .178
Code Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .179
Chapter 8:
Using Teradata PT in an External Stored Procedure . . . . . . . . . .187
Coding a Teradata PT External Stored Procedure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .187
Building a Teradata PT External Stored Procedure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .187
Installing a Teradata PT External Stored Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .188
Installing the Teradata PT onto the Teradata Database . . . . . . . . . . . . . . . . . . . . . . . . . . .188
Configuring the Teradata Databases Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .188
Using the CREATE PROCEDURE SQL Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .190
Table of Contents
Executing a Teradata PT External Stored Procedure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
Getting Started with the External Stored Procedure Example . . . . . . . . . . . . . . . . . . . . . . . . 192
Notes on Using the above SQL CALL Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
Chapter 9:
Converting TIME, TIMESTAMP, and INTERVAL Data Types. 197
ANSI/SQL DateTime Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Appendix A:
Platform Compilers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
Appendix B:
Code Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Solaris Running on a SPARC System, Solaris Running on an AMD Opteron System, HP-UX,
and AIX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
IBM z/OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Appendix C:
Compiling and Linking Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Appendix D:
Teradata PT Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Table of Contents
List of Figures
Figure 1: Typical Utility Integration Architecture for Customer Applications . . . . . . . . . . . . 22
Figure 2: Teradata PT Integration Architecture for Customer Applications . . . . . . . . . . . . . 22
Figure 3: Schema Definition for a Multiple Table Select Statement. . . . . . . . . . . . . . . . . . . . . 25
Figure 4: Data Buffer Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Figure 5: Bytes Illustrating Indicator-Mode Input Data Format . . . . . . . . . . . . . . . . . . . . . . . 33
Figure 6: Layout of Data Buffer returned by the TD_Evt_ApplyCount Method . . . . . . . . . 138
Figure 7: Master and Slave Parallel Relationships during Load and Export . . . . . . . . . . . . . 175
List of Figures
List of Tables
Table 1: Function Call Guide for the Teradata PT Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Table 2: Connection Class Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Table 3: Schema Class Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Table 4: DMLGroup Class Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Table 5: DML Group Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Table 6: Schema Object AddColumn Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Table 7: TD_Encoding Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Table 8: TD_SYSTEM-OPERATOR Attribute Constants. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Table 9: TD_TRACE_LEVEL Attribute Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Table 10: Teradata PT Status Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Table 11: Load Driver Required Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Table 12: Load Driver Optional Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Table 13: Load Driver Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Table 14: TD_ERRORLIMIT Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Table 15: Update Driver Required Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Table 16: Update Driver Optional Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Table 17: Update Driver Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Table 18: Update Driver Error Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Table 19: Update Driver ERRORLIMIT Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Table 20: Offline AMP Conditions and Effects on Update Driver Tasks . . . . . . . . . . . . . . . 108
Table 21: Nonparticipant AMP Conditions and Effects on Update Driver Tasks . . . . . . . . 109
Table 22: Stream Driver Required Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Table 23: Stream Driver Optional Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Table 24: Stream Driver Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Table 25: Stream Driver PutEvent Modifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Table 26: Stream Driver ERRORLIMIT Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Table 27: Export Driver Required Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Table 28: Export Driver Optional Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Table 29: Export Driver Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Table 30: PutEvent Modifier Expected Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Table 31: Export Driver SELECT Requests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Table 32: Synchronization Return Code Combinations and Suggested Actions . . . . . . . . . 177
List of Tables
Table 33: ANSI/SQL DateTime Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .197
Table 34: Teradata PT Platform Compilers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .203
Table 35: Required Software Dependencies for Teradata PT . . . . . . . . . . . . . . . . . . . . . . . . . .207
Table 36: TPT Datasets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .212
Table 37: TPT Application Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .213
Table 38: TPT Sample Library PDS Member Naming Standards . . . . . . . . . . . . . . . . . . . . . .213
Table 39: SDK *.H. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .213
Table 40: Dynamic DDL SDK *.H. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .214
Table 41: Generic Driver *.CPP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .214
Table 42: Generic Driver *.H. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .214
Table 43: Generic Driver JCL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .214
Table 44: Generic Driver Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .214
Table 45: Dynamic DLL Generic Driver *.CPP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .215
Table 46: Dynamic DLL Generic Driver *.H . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .215
Table 47: Dynamic DLL Generic Driver JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .215
Table 48: Multi Node Master *.CPP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .216
Table 49: Multi Node Master *.H . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .216
Table 50: Multi Node Master JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .216
Table 51: Multi Node Master Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .216
Table 52: Dynamic DLL Multi Node Master *.CPP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .217
Table 53: Dynamic DLL Multi Node Master *.H. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .217
Table 54: Dynamic DLL Multi Node Master JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .217
Table 55: Multi Node Slave *.CPP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .218
Table 56: Multi Node Slave *.H. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .218
Table 57: Multi Node Slave JCL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .218
Table 58: Multi Node Slave Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .219
Table 59: Dynamic DLL Multi Node Slave *.CPP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .219
Table 60: Dynamic DLL Multi Node Slave *.H . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .219
Table 61: Dynamic DLL Multi Node Slave JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .219
Table 62: Parallel Thread *.CPP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .220
Table 63: Parallel Thread *.H. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .220
Table 64: Parallel Thread JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .221
Table 65: Parallel Thread Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .221
Table 66: Dynamic DLL Parallel Thread *.CPP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .221
Table 67: Dynamic DLL Parallel Thread *.H . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .222
Table 68: Dynamic DLL Parallel Thread JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .222
List of Tables
Table 69: Standard JCL Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
List of Tables
CHAPTER 1
Coding a Teradata PT Application
As a set of application programming interfaces used to load into, and export data from, the
Teradata Database, Teradata PT enables an application to access the Teradata Database using
proprietary Teradata load and export protocols, including:
Teradata FastLoad
Teradata FastExport
Teradata Multiload
Scripting and Teradata API Environments
Unlike the Teradata utilities and Teradata Parallel Transporter that are driven by scripts,
Teradata PT is a functional library that is part of your applications. This allows the
applications to have more control during the load and export processes.
The advantages for using Teradata PT are:
Open standard reduces research and development costs to integrate with the Teradata
Database
Robust API facilitates easier access to key Teradata Database functions
Better control of the runtime environment simplifies the management processes
Figure 1 and Figure 2 illustrate the difference between the environments from an application
enterprise overview.
In the existing script environment, the partner application and a Teradata utility must run
as two separate jobs.
In the API environment, the transform, load, export, and other functions can be
integrated into one application and run as one job.
Chapter 1: Coding a Teradata PT Application
Scripting and Teradata API Environments
Figure 1: Typical Utility Integration Architecture for Customer Applications
Figure 2: Teradata PT Integration Architecture for Customer Applications
Log Files
Stdout
Teradata Database
Teradata
Utilities
Utility Environment
Flat Files
Named-Pipes
Scripts
Export
Transform
Schedule/Monitor
Metadata Services
Load
Customer Application
2516C001
Notify
Call Level Interface
Teradata Database
Export
Transform
Schedule/Monitor
Metadata Services
Load
Customer Application
2516C002
A
P
I
C
a
l
l
L
e
v
e
l
T
e
r
a
d
a
P
T
I
n
t
e
r
f
a
c
e
Coding Steps
Coding Steps
To connect to the Teradata Database and perform related tasks, review the information in each
of these steps:
1 Build a Teradata PT Database Connection Object
2 Initiate a Teradata PT Database Connection
3 Load Data into or Export Data from the Teradata Database
4 Interpret Errors
5 Add Checkpoint and Restart
6 Query Run-Time Statistics
7 Modify Job after Initiate
8 Utilize Serialization with the Stream Driver
9 Utilize Use Lists with DML Groups
10 Terminate the Teradata PT Connection
Build a Teradata PT Database Connection Object
In order to establish a connection with the Teradata Database, users must create an object that
will manage all of that connections important attributes. In Teradata PT, this object is called a
Connection object.
There are two steps involved in building a Connection object:
1 Create a Connection Object
The Connection object is defined as a C++ class. A Connection object can be created by
calling the Connection class constructor.
usi ng namespace t er adat a: : cl i ent : : API ;
Connect i on* conn = new Connect i on( ) ;
2 Add Parameters
The Connection object is used to house parameters for a database connection. There are
three types of parameters:
a attributes
b schemas
c DML Groups
Attributes
There are various types of options that can be set using attributes. Each driver has a set of
required attributes and optional attributes. Depending on the attribute, there can be multiple
values for that attribute. These are called array attributes. The following is an example of
adding attributes and array attributes:
conn- >AddAt t r i but e( TD_MAX_SESSI ONS, 4) ;
conn- >AddAr r ayAt t r i but e( TD_WORK_TABLE, 2, " t est a_wt ", " t est b_wt " , NULL) ;
Coding Steps
Set the value(s) for an attribute in a single call to either the AddAttribute function or the
AddArrayAttribute function. Once an attribute has been set, the value(s) of the attribute
cannot be changed and additional values cannot be added to it.
Set all attributes prior to calling the Initiate function. After a Connection object has been
initiated, no additional attributes may be set.
Schemas
A schema object defines the format of the data being used in the load and export tasks. A
schema consists of one or more columns, and the format of each columns data. The schema
lets the driver know what data to expect.
Unlike an attribute, a schema is defined as an external C++ class. When creating a schema
object using the class constructor, the schema must be designated as an input or output
schema. This means the task will involve either loading, updating data, or exporting data. The
following is an example of creating a schema object:
Schema * schema = new Schema( " i nput " ) ;
Columns are added to the schema object one at a time using the TD_DataType constants to
designate the data type of the column. The following are examples of adding a column to a
schema object:
schema- >AddCol umn( " Associ at e_Name" , TD_CHAR, 25) ;
schema- >AddCol umn( " Sal ar y" , TD_FLOAT, 8) ;
Figure 3 depicts the coding lines for a two-table select statement and how the data is brought
together in the answer set.
Coding Steps
Figure 3: Schema Definition for a Multiple Table Select Statement
When all columns have been added to the schema object, the schema object is then passed to
the Connection class. The following is an example of adding a schema object to a Connection
object:
conn- >AddSchema( schema) ;
Working with Schemas
When working with schemas, note the following:
Every driver requires a schema except when using either the Update driver's Delete Task
with no variable substitution or the Export drivers dynamic schema feature.
A Connection object may have only one schema.
The column names defined in the schema do not have to match the actual names of the
columns in the target table(s) as they can be renamed in the SQL statements used for the
job. The column names in the schema must match the names used in the jobs SQL
statements.
The column data types defined in the schema do not have to match the actual data types of
the columns in the target table(s) since they can be cast into other data types in the SQL
statements used. The column data type in the schema must, however, match the data types
used in the jobs SQL statements.
A B C
0 0 0 0 S 0 0
1 C B 1 1
2 2 2 Z Q 2 2
3 3 M 3 2 3 3
4 4 4 R 7
A B D E
5 5 5 T 5 5 5 5 5
6 6 6 9 6 6 6 6 6
7 7 0 0 7 7 7 7 7
8 8 W 8 B 8 8 8 8
9 9 9 T F 9 9 9 9
0 0 0 Y 0 0 0 0 0
1 1 C 1 1 1 1 1 1
A B
0 0 0 0 S
1 1 1 C B
2 2 2 Z Q
4 4 4 R 7
5 5 5 T 5
6 6 6 9 6
7 7 0 0 7
8 8 W 8 B
9 9 9 T F
0 0 0 Y 0
1 1 C 1 1
Schema schema = new Schema ("OUTPUT");
*
schema AddColumn ("A", TD_Char, 2);
schema AddColumn ("B", TD_Char, 3);
TABLE 1 TABLE 2
2516A006
connection AddAttrbute(TD_SELECT_STMT,
"Select A,B from TABLE1; Select A,B from TABLE2;");
4 4
Export Driver
Answer Set
3 3 M 3 2
1 1
Connection AddSchema(schema);
Coding Steps
The order of the columns defined in the schema does not have to match the actual order of
the columns in the target table(s) as the order can be changed in the SQL statements used.
The order of the columns in the schema must, however, match the order of the columns in
the jobs SQL statements.
When loading multiple tables using the Update or Stream driver, the input schema defined
for the job is a superset of the columns in all of the tables being loaded. One or more of the
columns in the schema must correlate to the columns being loaded in each of the target
tables.
VARCHAR and VARBYTE data with a length less than or equal to the defined length in the
SCHEMA object is allowed.
Examples of Schema Definitions
If the Export driver is being used to export data from Table 1 which has columns A, B, and C,
and the SELECT statement is:
SELECT A FROM Tabl e 1
then the output schema is defined as one column with a data type matching column As
definition in Table 1. If column A is defined as a variable character with a length of 50, then
the column in the output schema is defined as TD_VARCHAR with a length of 50.
Schema* schema = new Schema( " out put " ) ;
schema- >AddCol umn( " A" , TD_VARCHAR, 50) ;
Heres another example using the same table. If the select statement is changed to:
SELECT A( CHAR( 100) ) FROM Tabl e 1
then the column in the output schema is defined as TD_CHAR with a length of 100.
Schema* schema = new Schema( " out put " ) ;
schema- >AddCol umn( " A" , TD_CHAR, 100) ;
DML Groups
DMLGroup objects are used to store sets of DML statements and DML options which can
later be applied when loading or updating data. A DMLGroup is defined as an external C++
class.
The following is an example of creating a DMLGroup object:
DMLGr oup * dml Gr = new DMLGr oup( ) ;
Each DML statement is stored as a character string within the DMLGroup object. DML
statements can be added one at a time to the DMLGroup object using the AddStatement
function. More than one DML statements can be added to the same DMLGroup object but
each DML statement must be added in a separate call to the AddStatement function. The
following is an example of adding a statement to a DMLGroup object:
dml Gr - >AddSt at ement ( " I NSERT I NTO t est 1( : Associ at e_I d, : Sal ar y ) ; " ) ;
Along with DML statements, a series of DML options can be set for a DMLGroup object using
the TD_DMLOption parameters. The following is an example of setting DML options for a
DMLGroup object:
dml Gr - >AddDMLOpt i on( MARK_DUPLI CATE_ROWS) ;
Coding Steps
A DMLgroup is added to the Connection class by using the AddDMLGroup function. The
AddDMLGroup function takes two parameters:
A pointer to the DML group being added
a pointer to a TD_Index object through which the function will return the index reference
for the DML group. This index is used later with the UseDMLGroups function.
The following is an example of adding a DML group to the Connection class:
TD_I ndex i ndex;
TD_St at usCode r et ur nVal ue = conn- >AddDMLGr oup( dml Gr , &i ndex) ;
Initiate a Teradata PT Database Connection
After defining a Teradata PT Connection object with parameters, initiate a connection to the
Teradata Database by using the Connection objects Initiate method:
/ * I ni t i at e a connect i on wi t h t he dat abase */
TD_St at usCode r et ur nVal ue = conn- >I ni t i at e( ) ;
Load Data into or Export Data from the Teradata Database
After establishing a connection, load or export data from the Teradata Database. Data can be
loaded on a row by row basis using the PutRow function or as a block by using the PutBuffer
function which is available to the Load, Update, and Stream drivers. Likewise, data can be
exported one row at a time using the Export drivers GetRow function or multiple rows can be
exported together in a buffer using the Export drivers GetBuffer function.
Data can be loaded into or exported from all of the columns in a table or from a subset of the
columns in a table. When loading data into a subset of the columns in a table, default values
must be specified for the columns not being loaded. In each case, only the columns being
loaded or exported from should be defined in the schema.
For example, Table1 has columns A, B, and C. Columns A and B are defined as integers and
column C is a variable character column with a length of 25. To load data into column A only,
a valid insert statement would be
I NSERT I NTO Tabl e1 ( A, B, C) VALUES ( : A, 0, NULL) ;
where zero is the default value for B and NULL is the default value for column C. The input
schema for this example would be defined as only having column A.
Row by Row Loading into the Teradata Database
There are three parts to loading data into the Teradata Database using Teradata PT:
Load rows
Inform Teradata PT that acquisition is complete
Apply rows to the Teradata Database
Data is loaded using the Connection objects PutRow function. The PutRow function accepts
as its arguments a pointer to a single row of data in null-indicator mode format, and the
length of the data row (including the length of the null-indicator bytes). See Figure 5 for an
illustration of the indicator-mode input data format.
Coding Steps
The PutRow length is the total length of all the column values (including the length bytes for
variable-length values) plus the number of indicator bytes. See Data Format for information
on how to determine the number of indicator bytes in a row.
whi l e ( ! endOf Dat a) {
/ * Assembl e a r ow i n nul l - i ndi cat or f or mat */
. . .
/ * Pass a r ow t o t he Ter adat a Dat abase */
conn- >Put Row( buf f er , l engt h) ;
}
Although the application passes a row at a time, the Load, Update, and Stream drivers
accumulate the rows in the CLIv2 buffer and then send them to the DBS by the buffer load.
Once all data has been loaded, the acquisition method is completed by calling the Connection
objects EndAcquisition function. This must be done before the data can be applied.
conn- >EndAcqui si t i on( ) ;
When the acquisition method has been completed, the data is applied in the Teradata
Database by using the Connection objects ApplyRows method. This method should only be
called when using the Load or Update driver. The Stream driver automatically applies the
changes which means the ApplyRows method should not be called when using the Stream
driver.
conn- >Appl yRows( ) ;
Load Rows into a Teradata Database using PutBuffer
The Teradata PT PutBuffer function is available for the Load, Update and Stream drivers.
Using PutBuffer for the Update and Stream drivers will only provide performance
improvement if the function call overhead to PutRow is costly. If that is not the case, continue
to use PutRow for the Update and Stream drivers.
There are five steps to using this method:
1 Set the buffer mode attribute
2 Query the buffer layout
3 Load the buffers
4 Inform Teradata PT that acquisition is complete
5 Apply rows to the database (except when using the Stream driver)
Before Initiate is called, set the buffer mode attribute to Yes in the Connection object as
follows:
conn- >AddAt t r i but e( TD_BUFFER_MODE, " Yes") ;
In order to buffer the data for block loading, query the Connection object using the event
method to obtain the layout for the data buffer. The event method should be queried using the
TD_Evt_BufferLayout parameter as follows:
r et ur nVal ue = conn- >Get Event ( TD_Evt _Buf f er Layout , &dat apt r , &dat al en) ;
The layout returned by the event method for the buffer event contains four 4-byte unsigned
integers corresponding to the maximum buffer size, the row header size, the row length size,
and the buffer trailer size.
Coding Steps
Note: These layout values will change depending on the user environment and may be
defined differently in future releases. Always obtain these values from the event method before
buffering data.
Figure 4 is a diagram representing the layout of the Load driver data buffer.
Figure 4: Data Buffer Format
When constructing the data buffer, the user is responsible for filling in the row length for each
row and the row data. The row length is two bytes for Load and Update operator and it is four
bytes for Stream driver. The beginning of the row header and the buffer trailer should be left
blank as they will be filled in by Teradata PT. The total size of the buffer cannot exceed the
maximum buffer size returned by the buffer layout event.
Buffers of data are loaded using the Connection objects PutBuffer method. The PutBuffer
method accepts as its arguments a pointer to a buffer of data, the length of the data buffer, and
an indicator informing Teradata PT whether the data in the buffer is in indicator mode (a
value of one) or in non-indicator mode (a value of zero). Data for the Update and Stream
drivers must be in indicator mode (a value of one).
whi l e ( ! endOf Dat a) {
/ * Assembl e a buf f er of r ows i n nul l - i ndi cat or f or mat */
. . .

/ * Pass a buf f er t o t he Ter adat a Dat abase */
conn- >Put Buf f er ( buf f er , l engt h, 1) ;
}
Once all data has been loaded, the acquisition method is completed by calling the Connection
objects EndAcquisition method. This must be done before the data can be applied.
conn- >EndAcqui si t i on( ) ;
When the acquisition method has been completed, the data is applied in the Teradata
Database by using the Connection objects ApplyRows method. This is not needed when using
the Stream driver.
conn- >Appl yRows( ) ;
Note: When using the Load, Stream, or Update drivers, the PutBuffer and PutRow features
can not be used in the same job.
2516A004
Row
Length
Row Data
Row
Length
Row Data
Row
Length
Row Data Buffer Trailer
Row Header
Coding Steps
Export Data from a Teradata Database using GetRow
Data can be exported one row at a time using the Connection objects GetRow function. The
GetRow function accepts as its arguments a pointer to an allocated buffer with enough room
for one row of data and a pointer to a TD_Length object for storing the length of the data
exported.
whi l e ( r et ur nVal ue ! = TD_END_Met hod ) {
/ * Ret r i eve r ow f r omt he Ter adat a Dat abase */
r et ur nVal ue = conn- >Get Row( &buf f er , &l engt h) ;
}
The GetRow function will return the TD_Success value when a row of data has been
successfully retrieved. The TD_End_Method value will be returned when all rows have been
retrieved and the data acquisition process is complete.
Export Data from a Teradata Database using GetBuffer
Multiple rows can be exported together in a buffer using the Connection objects GetBuffer
function. Exporting an entire buffer full of rows using the GetBuffer function rather than one
row at a time using the GetRow function improves performance by reducing the amount of
data movement required. The GetBuffer function accepts as its arguments a pointer to an
unallocated character buffer and a pointer to a TD_Length variable. The GetBuffer function
uses these two arguments to return a pointer to a data buffer and to return the total length of
that data buffer.
conn- >Get Buf f er ( &buf f er , &l engt h) ;
The GetBuffer function returns the TD_Success value when a buffer of data is successfully
retrieved. The buffer of data returned by the GetBuffer function must be immediately either
copied or processed. The buffer used to return the data is overwritten on the next GetBuffer
function call, and the buffer is destroyed when the Connection object is deleted. The
GetBuffer function returns the TD_END_Method value when all rows have been retrieved
and the data acquisition process is complete.
In order to use the GetBuffer feature, set the TD_BUFFER_MODE attribute to Yes (or Y)
before initiating the Connection object. The GetRow function cannot be called if the
GetBuffer feature is enabled.
Specify the size and format of the data buffer returned by the GetBuffer function by setting
one or more of the following buffer layout attributes:
TD_BUFFER_MAX_SIZE
TD_BUFFER_HEADER_SIZE
TD_BUFFER_LENGTH_SIZE
TD_BUFFER_TRAILER_SIZE
These attributes correspond to the total maximum size of the data buffer, the row header size
allocated for each row in the data buffer, the row length size used for each row in the data
buffer, and the trailer size allocated for the data buffer. See Figure 4 on page 29 for a
description of the format of the data buffer and Table 27 for a detailed description of each of
the four buffer layout attributes and their default values.
Coding Steps
The layout of the data buffer returned by GetBuffer can alternatively be set by using the
Export drivers TD_Evt_BufferLayout modifier along with the PutEvent function. The Export
drivers TD_Evt_BufferLayout modifier can be used to set the data buffer layout any time after
the Export driver has been initialized up until the first call to the Export drivers GetBuffer
function. The modifier returns TD_Unavailable if called after the first call to the GetBuffer
function. See PutEvent Modifiers on page 155 for more information on how to use the
Export drivers TD_Evt_BufferLayout modifier.
Transfer Data Using GetBuffer and PutBuffer
Data exported using the Connection objects GetBuffer function can be directly loaded using
the Connection objects PutBuffer function. This feature improves performance when data
transfer is needed and no data transformation is required.
To directly transfer data from the Export drivers GetBuffer function to the Load, Update, or
Stream drivers PutBuffer function, the Export drivers buffer layout attributes must be set
using the buffer layout values returned by the event method for the Load, Update, or Stream
drivers. This causes the Export driver to format the data returned by the GetBuffer function so
that it will match the buffer layout required by the Load, Update, or Stream drivers PutBuffer
function. The following steps describe how to accomplish this transfer.
To transfer data using GetBuffer and PutBuffer functions (non-dynamic schema
transfer)
1 Create a Load, Update, or Stream driver and enable the PutBuffer feature by setting the
TD_BUFFER_MODE attribute to Yes (or Y).
2 Initiate the Load, Update or Stream driver.
3 Create an Export driver and enable the GetBuffer feature by setting the
TD_BUFFER_MODE attribute to Yes (or Y).
4 Use the GetEvent function to query the TD_Evt_BufferLayout event for the Load, Update,
or Stream driver and use the buffer layout values returned by this event to set the following
attributes for the Export driver:
TD_BUFFER_MAX_SIZE
After completing these steps, the Export driver can be initiated and the data retrieved by the
Export drivers GetBuffer function can be directly loaded using the Load, Update, or Stream
drivers PutBuffer function.
When using the Export drivers dynamic feature and sharing the dynamic schema between
drivers, the Export driver must be initiated first instead of last. In this situation, use the
following alternative procedure.
Coding Steps
Transferring Data using the Dynamic Schema Feature with
GetBuffer and PutBuffer Functions
To implement the Export drivers dynamic schema feature while using GetBuffer and
PutBuffer to transfer data, follow these steps:
1 Create an Export driver and enable the GetBuffer feature by setting the
TD_BUFFER_MODE attribute to Yes (Y).
2 Create a Load, Update, or Stream driver and enable the PutBuffer feature by setting the
TD_BUFFER_MODE to Yes (Y).
3 Initiate the Export driver.
4 Initiate the Load, Update, or Stream driver.
5 Use the GetEvent function to query the TD_Evt_BufferLayout event for the Load, Update,
or Stream driver.
6 Use the PutEvent function to pass the event data returned by the Load, Update, or Stream
drivers TD_Evt_BufferLayout event directly into the Export drivers
TD_Evt_BufferLayout modifier.
At this point, data can be retrieved from the Export driver using the GetBuffer function and
loaded directly using the Load, Update, or Stream drivers PutBuffer function.
Note: The buffer layout values for the Load, Update, or Stream drivers change depending on
the user environment and may be defined differently in future releases. Always obtain these
values from the event method when transferring data between the Export drivers GetBuffer
function and the Load, Update, and Stream drivers PutBuffer function.
Data Format
The Teradata PT PutRow and GetRow methods currently only support the indicator-mode
input data format:
A variable-length indicator bytes field
A variable-length input data field
The positions of the indicator bits correspond to the fields of the loading and exporting row.
There is one bit for each column in the table. The first bit in the first byte is the indicator for
the first field in the record. If an indicator bit is set to one, the Teradata Database nulls the
corresponding field when the record is loaded. If the indicator bit is set to zero, the Teradata
Database loads the data specified for that field.
For example, when there are less than 9 columns, there is a 1-byte indicator-byte length.
Between 9 and 16 columns, there is a 2-byte indicator-byte length. There is a 3-byte
indicator-byte length between 17 and 24 columns, etc.
Coding Steps
Figure 5: Bytes Illustrating Indicator-Mode Input Data Format
Find more information about the indicator byte in Teradata FastLoad Reference. See
Additional Information on page 6.
When using the Teradata PT PutBuffer function with the Load driver, the input data can be in
indicator mode or in non-indicator mode format. When using the PutBuffer function with
the Update or Stream driver, the input data must be in indicator mode format.
Interpret Errors
When the user application receives an error, find more information about the error by using
the Connection objects GetErrorInfo function. The GetErrorInfo function takes two
arguments: a pointer to a character buffer for returning the error message string associated
with the error and a pointer to a TD_ErrorType variable for returning the type of error.
conn- >Get Er r or I nf o( &er r or St r i ngBuf f er , &er r or Type ) ;
If GetErrorInfo is called and no error has occurred, then the message string will be set to
NULL and the error type will be a value of 1.
Some errors which occur during the acquisition method may require the user application to
end the acquisition method before error information can be returned to the user application.
In these cases, the status code TD_Call_EndAcq will be returned and the user application
must proceed to call the EndAcquisition function. The EndAcquisition function will return an
error code for the problem which caused the acquisition method to be aborted. At this time,
additional error information relating to this error code will be available through the use of the
GetErrorInfo function.
Add Checkpoint and Restart
To prevent the loss of work done due to an execution error, Teradata PT has Checkpoint and
Restart functions which establish locations in the data to return to if an error occurs. Both
functions are part of the Connection object and can be called at any point after the connection
has been initialized. The Checkpoint and Restart functions are available for the Load, Update,
and Stream drivers. If an Export driver job fails, the job must start over from the beginning.
Set Checkpoints
The Checkpoint function takes two arguments which are used to return checkpoint data to
the user application: a pointer to an unallocated data buffer (the checkpoint data storage area)
and a pointer to a TD_Length variable that stores the length of the checkpoint data.
conn- >Checkpoi nt ( &buf f er , &l engt h) ;
01001000
2516B003
00000000 F1 F2 F3 F4 F5 F6 F7 F8 F16
These fields are nulled
Coding Steps
The Checkpoint function returns the TD_END Method return value when the end of the
Checkpoint method has been reached and a successful checkpoint has been taken. At this
point, the Checkpoint function also passes checkpoint data to the user application. This is the
only point at which valid checkpoint data is returned. For all other return values, no valid
checkpoint data will be returned.
Once the Checkpoint function has successfully completed and has returned valid checkpoint
data to the user application, the user application must make a copy of the checkpoint data and
store it for later use. The character buffer used to pass the checkpoint data to the user
application will be overwritten the next time the Checkpoint function is called and will be
destroyed when the Connection object is deleted. It is recommended that an external file or
table be used to store the checkpoint data to guard against the user application failing.
The user application determines at what interval to call the Checkpoint function. If the
Checkpoint function returns an error then the data was not successfully checkpointed and no
valid checkpoint data will be returned.
Note: No checkpoint data is returned by the Checkpoint function for the Load driver and no
valid checkpoint data is required by the Restart function for the Load driver. Still, it is highly
recommended that user applications using the Load driver be prepared to store and retrieve
valid checkpoint data when using the Checkpoint and Restart functions in case this feature is
required in future releases.
Perform a Restart
Here are the main tasks to restarting a Teradata PT operation:
1 Terminate the connection in which the error occurred.
2 Resolve the issue which caused the error to occur.
3 Create a new connection instance with the same parameters as the original connection
which failed.
4 Set the TD_RESTARTMODE attribute with a value of one.
5 Call the Initiate function.
6 Call the Restart function using the checkpoint data from the last successful checkpoint.
The Restart function takes two arguments: a pointer to a character buffer containing the latest
checkpoint data and a pointer to a TD_Length variable containing the length of the
checkpoint data.
conn- >Rest ar t ( buf f er , l engt h) ;
The Restart function requires that valid checkpoint data be specified. The checkpoint data
used to restart must be a copy of the checkpoint data returned by the last successful
checkpoint in order to avoid losing any data. If invalid data is given to the Restart function,
error code 21044 will be returned, indicating that invalid arguments have been specified.
If no successful checkpoint was taken prior to the job failing, the job cannot be restarted. In
this case all error tables, log tables, and work tables must be dropped and the job must start
over from the beginning.
Coding Steps
Resubmit the Data
If the job failed during the acquisition phase, then resubmit rows starting from the row after
the last successful checkpoint. The user application keeps track of when the last successful
checkpoint was taken.
Query Run-Time Statistics
You can use the GetEvent function to query the driver for run-time statistics. The GetEvent
function takes four arguments:
Type of event
A pointer for the output data buffer
A pointer for the output data buffer length
A target table index. The target table index argument is only used by the Update and
Stream drivers.
conn- >Get Event ( event Type, event Dat a, &event Dat aLen, t abl eI ndex) ;
Call the GetEvent method after the driver initiates and before it terminates. Some events
require the job to reach a certain point before their data becomes available. If the job has not
yet reached this point, the GetEvent method returns TD_Unavailable.
Modify Job after Initiate
The PutEvent function can be used to modify certain aspects of a job after the driver has
already been initiated. The PutEvent function takes four arguments:
Type of modifier
A pointer to the buffer containing the input data for the modifier
The length of the buffer containing the input data for the modifier
A target table index. The target table index argument is not currently used by any modifier.
conn- >Put Event ( modi f er Type, Modi f i er Dat a, modi f i er Dat aLen, t abl eI ndex) ;
The PutEvent function can be called after the driver initiates and before it terminates. Some
modifiers require that the job reach a certain point before they can be used to modify a job
while others are available right after the driver initiates but become unavailable later in the job.
TD_Unavailable is returned when a modifier cannot be used.
Utilize Serialization with the Stream Driver
In certain uses of the Stream driver it is possible to have multiple changes to one row in the
same job. For instance, the row may be inserted and then updated during the job or it may be
updated and then deleted. In any case, the correct ordering of these operations is very
important. By using the serialization feature, the Stream driver can guarantee that this
ordering of operations is maintained correctly.
The serialization feature works by hashing each data record based upon a set of columns to
determine which session transmits the record to the Teradata Database. Thus there is extra
overhead in the application derived from the mathematical operation of hashing and from the
Coding Steps
extra amount of buffering necessary to save data rows when a request is already pending on
the session chosen for transmission.
The serialization feature greatly reduces the potential frequency of Teradata Database
deadlock. Deadlocks can occur when requests for the application happen to effect row(s) that
use the same hash code within the Teradata Database. Although deadlocks are handled by the
Teradata Database and by Teradata PT correctly, the resolution process is time consuming and
adds additional overhead to the application because it must re-execute requests which roll
back due to deadlock.
In Teradata PT, serialization is enabled through the DMLGroup object. The DMLGroup
object has an AddSerializeOn function which takes two arguments: the number of columns in
the column set and a list of column names terminated by a NULL value.
dml Gr - >AddSer i al i zeOn( 2, " Associ at e_I d" , " Associ at e_Name" , NULL) ;
The intent of the column set parameter is to allow the user to specify the column(s)
corresponding to the primary index of the target table. If there is more than one target table
specified in the DML statements of the DMLGroup, then it is up to the user to make sure the
primary indexes of all the tables match when using the serialize feature.
Each DMLGroup object has a single list of columns to use for serialization. Columns can be
added to this list in one call or through a series of multiple calls to the AddSerializeOn
function. For example, two columns can be added to a serialization list one at a time using
separate calls to the AddSerializeOn function:
dml Gr - >AddSer i al i zeOn( 1, Associ at e_I d, NULL) ;
dml Gr - >AddSer i al i zeOn( 1, Associ at e_Name, NULL) ;
Or the two columns can be added in the same call:
dml Gr - >AddSer i al i zeOn( 2, Associ at e_I d, Associ at e_Name, NULL) ;
Utilize Use Lists with DML Groups
When the SQL statement(s) in a DML group are executed during the application process,
there are cases when not all columns of data are needed. In such cases, it is wasteful to use all
columns.
In Teradata PT, use lists allow the user to define which columns will be needed by the SQL
statements in a DML group. The DMLGroup object has an AddUseList method which takes
two arguments: the number of columns in the column set and a list of column names followed
by a NULL value.
dml Gr - >AddUseLi st ( 3, " Associ at e_I d" , " Associ at e_Name" , " Sal ar y" , NULL) ;
A DMLGroup object has a maximum of one use list. Columns can be added to this use list in
one call or through a series of multiple calls to the AddUseList function. For example, three
columns can be added to a use list in separate calls to the AddUseList function:
dml Gr - >AddUseLi st ( 1, Associ at e_I d, NULL) ;
dml Gr - >AddUseLi st ( 2, Associ at e_Name, Sal ar y, NULL) ;
Or three columns can be added in the same call:
dml Gr - >AddUseLi st ( 3, Associ at e_I d, Associ at e_Name, Sal ar y, NULL) ;
Special Topics
Terminate the Teradata PT Connection
Once a Teradata PT driver task completes, the connection must be terminated. Do this with
the Connection objects Terminate method.
conn- >Ter mi nat e( ) ;
The Terminate method closes all sessions associated with the connection and ends the drivers
processing environment.
Your program should always call Terminate whenever any program fails prematurely, so that
Teradata PT can do cleanup tasks such as releasing storage and logging off all DBS sessions. If
your program cannot call Terminate and has stopped, you may be able to submit a restart job.
If you submit a restart job and get errors, wait until the DBS logs off all orphan sessions (the
default time is 20 minutes) and then submit the restart job again.
Note: If you are making direct calls to CLIv2, do not call the DBCHCLN function until all
initiated Teradata PT drivers within the same process have been terminated. In addition to
freeing shared CLIv2 structures, the DBCHCLN method disconnects all currently connected
CLIv2 sessions within the same address space. If you call DBCHCLN while a Teradata PT
driver in the same process is still active, the drivers session will prematurely disconnect and
the job will fail.
Special Topics
As part of your coding a Teradata PT API application, review the following special topics:
Reusing a Teradata PT Connection Object
Query Banding Teradata Database Feature
Using the UTF16 Session Character Set
Using the Export Drivers Dynamic Schema Feature
Enabling Teradata PT API Infrastructure-Specific Tracing
Validating that Teradata PT Quick Start Job Scripts Execute
Note: Two other special topics are discussed in Chapter 7: Parallelism Enabling Protocol,
and Chapter 8: Using Teradata PT in an External Stored Procedure.
Reusing a Teradata PT Connection Object
An instance of the Connection object can be reused multiple times to perform the same task.
The following restrictions apply:
The Connection object must be terminated before re-initiating.
No new attributes, schemas, or DML groups can be added after the first time the
Connection object is initiated.
Existing attributes, schemas, or DML groups cannot be changed.
Special Topics
Query Banding Teradata Database Feature
Available with the V12.0 Teradata Database, the query banding feature provides a user-defined
query band expression that is set for every SQL session connected by the Teradata PT driver. A
query band expression is a set of name-value pairs that identify a querys originating source. In
the expression, each name-value pair is separated by a semicolon and the expression ends with
a semicolon. The following is an example of a valid query band expression:
a=1; b=2; c=3; d=4;
If the TD_QUERY_BAND_SESS_INFO is set, the following request will be sent by every SQL
session connected by the Teradata PT driver:
SET QUERY_BAND = <User-Defined Query Band Expression> FOR SESSI ON;
Setting the TD_QUERY_BAND_SESS_INFO attribute in jobs running against non-supported
versions of the Teradata Database causes a non-fatal error. No error code is returned to the
user during initiation and the job is allowed to proceed. The log table will not be dropped at
the end of the job and the TD_Evt_ExitCode event returns a warning value of four instead of
the normal success value of zero if queried. In this case, error information can be found in the
trace file.
Using the UTF16 Session Character Set
Setting the TD_CHARSET optional attribute to UTF16 allows users to load and export
UTF-16 data to and from Teradata systems. The TD_CHARSET attribute is available for each
driver. Teradata PT applications that use the UTF16 session character set must be aware of the
differences in the expected sizes for CHAR and VARCHAR columns in the Schema object. The
Schema objects AddColumn method expects different sizes for CHAR and VARCHAR
columns when the session character set is UTF16 or UTF8 than it does when the session
character set is ASCII.
Note: On channel-attached z/OS platforms, only the UTF8 and UTF16 session character sets
are not supported.
For example, a table is created with a column defined for data in unicode format:
cr eat e t abl e ut f 16_t bl ( c1 VARCHAR( 100) char act er set uni code) ;
If a Teradata PT application wanted to load or export ASCII data into this table then column
c1 would be added to the Schema object in the following way:
schema>AddCol umn( c1, TD_VARCHAR, 100) ;
However, if a Teradata PT application wanted to load or export UTF-16 data into this table
then column c1 would have to be added to the Schema object in this way:
The size parameter in the AddColumn method refers to the size of the column in bytes. Valid
UTF-16 data in a Teradata Database contains two bytes per character, which is why 200 bytes
is specified instead of 100 bytes. The same principle is true when the session character set is
UTF8 because UTF-8 characters can be up to three bytes in length. Therefore, if a Teradata PT
application wanted to load or export UTF-8 data into the table defined above then column c1
would be added to the Schema object in the following way:
Special Topics
Using the UTF16 Encoding for Teradata PT Objects and Messages
User attributes, DML statements, and column names can be in the UTF-16 encoding when the
session character set is UTF16. Teradata PT applications have the choice of passing in these
values in UTF-16 or in UTF-8 when the session character set is UTF16. To accommodate this
option, the Connection, Schema, and DML Group objects can be instantiated with an
encoding parameter instead of the default void parameter. UTF-8, which is an ASCII-based
encoding for Unicode characters, is the default encoding for all Connection, Schema, and
DML Group objects.
Note: On channel-attached z/OS platforms, the use of UTF-16 or UTF-8 encoding is not
supported because EBCDIC encoding is always used.
If users specify all Connection attributes in the UTF-16 encoding then their Connection
objects must be instantiated in the following way:
Connect i on*conn = new Connect i on( TD_UTF16_ENCODI NG) ;
If users specify all column names passed to the Schema object methods in the UTF-16
encoding then their Schema objects must be instantiated in the following way:
Schema*schema=new Schema( TD_UTF16_ENCODI NG) ;
If users specify all column names and DML statements passed to their DMLGroup object
methods in the UTF-16 encoding then their DMLGroup objects must be instantiated in the
following way:
DMLGr oup*dml gr = new DMLGr oup( TD_UTF16_ENCODI NG) ;
If an object is instantiated with TD_UTF16_ENCODING then Teradata PT will treat all
character strings passed in to any of that objects methods as being in the UTF-16 encoding.
Also, all UTF-16 character strings passed to the Connection, Schema, or DMLGroup object
methods must be NULL-terminated. This means that the last two bytes of the UTF-16 string
must be zero. This is important so Teradata PT can accurately determine the length of the
UTF-16 string passed to any of the Connection, Schema, or DMLGroup object methods.
An option also exists for the Teradata PT application to receive messages between itself and
Teradata PT in UTF-8 or UTF-16 when the session character set is UTF16. The optional
attribute TD_MSG_ENCODING will dictate the behavior of Teradata PT in this regard.
Messages that are passed between Teradata PT and the calling application include Teradata
CLIv2 errors, Teradata Database errors, and table or macro or database names found in the
buffer for the Stream drivers ApplyCount event. The value for the TD_MSG_ENCODING
attribute can only be TD_UTF8_ENCODING (the default) or TD_UTF16_ENCODING. This
optional attribute should only be used when the session character set attribute,
TD_CHARSET, is set to UTF16.
The following cases will result in errors reported by Teradata PT:
If the TD_MSG_ENCODING attribute is used and has a value of
TD_UTF16_ENCODING but the TD_CHARSET attribute is not set to UTF16.
If a Connection object is instantiated with TD_UTF16_ENCODING but the
TD_CHARSET attribute is not set to UTF16.
Special Topics
If a Schema object is instantiated with TD_UTF16_ENCODING but the TD_CHARSET
attribute is not set to UTF16.
If a DMLGroup object is instantiated with TD_UTF16_ENCODING but the
TD_CHARSET attribute is not set to UTF16.
Additionally, all invalid character errors detected in any UTF-16 attribute, column name, or
DML statement will be treated as terminating errors.
Using the Export Drivers Dynamic Schema Feature
The Export drivers dynamic schema feature provides the option of having the Export driver
dynamically generate the output schema based on the SELECT statement. This feature frees
the user application from having to provide a predefined output schema.
Enable this feature by not adding a schema to the Export driver prior to initialization. When
the Export driver detects that no user-defined output schema has been added, the Export
driver will create an output schema based on the user-provided SELECT statement and the
job will continue as normal.
Sharing the Dynamic Schema with Other Drivers
Follow these steps to share the Export drivers dynamically generated output schema with
other drivers:
1 Create an instance of the Export driver and add all necessary attributes. Enable the
dynamic schema feature by not adding a schema to the Export driver.
2 Initialize the Export driver.
3 Retrieve the dynamically generated schema from the Export driver through the use of the
GetSchema function:
Schema* dynami cSchema;
r et ur nVal ue = expor t Connect i on- >Get Schema( &dynami cSchema) ;
4 Pass the dynamically generated schema to the other drivers by using the AddSchema
function:
l oadConnect i on- >AddSchema( dynami cSchema) ;
5 Initialize the other drivers.
Note: The Export drivers dynamic schema feature is also available with multiple instance
Export jobs.
For an example using the dynamic schema feature with a multi-instance Teradata PT API
application, see the TPTAPI mnode_dynschema sample application provided with the
TPTAPI package. To run a TPTAPI multi-instance application using the dynamic schema
feature, the user application must set the TEST_TO_RUN to TEST_EXPORT_TO_LOAD /
TEST_EXPORT_TO_STREAM / TEST_EXPORT_TO_UPDATE in master_input.txt and
slave_input.txt to run with LOAD / STREAM / UPDATE operators, respectively.
Enabling Teradata PT API Infrastructure-Specific Tracing
The environment variable TPTAPIDEBUG enables and disables the following Teradata API
infrastructure debug messages:
Special Topics
TELAPIDBG
TELAPIDBG_ENTER
TELAPIDBG_EXIT
TELAPIDBG_TIME
TELAPIDBG_BANNER
If TPTAPIDEBUG=TRC_ALL, all the Teradata PT API infrastructure trace logs would be
displayed at the standard output.
If TPTAPIDEBUG=TRC_ON, the first 100 rows of the GET or PUT row messages would be
displayed along with the rest of the logs at the standard output.
If TPTAPIDEBUG=number, then GET or PUT row messages would be displayed per the
specified number along with the rest of the logs at the standard output.
Available Teradata Parallel Transporter Functions
Table 1 gives an overall view of which functions are available to each Teradata PT driver.
Validating that Teradata PT Quick Start Job Scripts Execute
To run the quick start validation scripts:
Create a database user name and password.
cd $TWB_ROOT/sample/validate
On Unix: run the following script:
. / t pt val i dat e. ksh TdpId UserName Password
where:
Table 1: Function Call Guide for the Teradata PT Drivers
Load Update Stream Export
Standard
with
Pause
Acquisition Standard
with
Delete
Task
with
Pause
Acquisition Standard Standard
Initiate Yes Yes Yes Yes Yes Yes Yes
PutRow Yes Yes Yes No Yes Yes No
PutBuffer Yes Yes Yes No Yes Yes No
GetRow No No No No No No Yes
GetBuffer No No No No No No Yes
EndAcquisiti
on
Yes Yes Yes No Yes Yes No
ApplyRows Yes No Yes Yes No No No
Terminate Yes Yes Yes Yes Yes Yes Yes
Special Topics
TdpId is a database name Id.
UserName is database user name.
Password is database user password.
The script executes the following Teradata PT job scripts in the quickstart directory:
qsetup.txt
qstart1.txt
qstart4.txt
qcleanup.txt.
On Windows: run the following script:
t pt val i dat e. bat TdpId UserName Password
where:
TdpId is a database name Id.
UserName is a database user name.
Password is a database user password.
The script executes the following Teradata PT quick start job scripts in the quickstart
directory:
qsetup.txt
qstart1.txt
qstart4.txt
qcleanup.txt
CHAPTER 2
Interface Specifications
The following tables list objects and their functions within each class. The syntax of the
function and all possible return codes are also listed. This chapters main sections cover:
Connection Class
Schema Class
DML Group Class
Teradata PT Constants
DML Option
TD_Attribute
TD_Encoding
TD_DataType
TD_OperatorType
TD_TRACE_LEVEL
Teradata PT Status Messages
Dynamic Loading
Connection Class
The Connection class manages all of the attributes required to connect to the Teradata
Database. These attributes store attribute, schema and DML Group objects.
Note: On channel-attached z/OS platforms, connection.h is located in TWB.H(CONNECTI).
Notes have been made for the following syntax examples to use #include connecti.h instead
of connection.h.
Chapter 2: Interface Specifications
Connection Class
Table 2: Connection Class Objects
Object Name and
Function Syntax and Notes Return Codes
AddArrayAttribute
Adds a connection
attribute with more than
one value.
#i ncl ude connect i on. h
Voi d
AddAr r ayAt t r i but e(
TD_At t r i but e attribute,
TD_Count count,
Char * value, . . . ,
NULL) ;
Voi d
AddAr r ayAt t r i but e(
TD_Count count,
TD_I nt Val ue value, . . . ,
NULL ) ;
where these parameters specify:
attribute Input for the type of attribute
being added.
count Input for the number of values.
value Input for the values of attributes
terminated by NULL.
On channel-attached z/OS platforms,
connection.h is located in
TWB.H(CONNECTI). Use #include
connecti.h instead of connection.h.
None
AddAttribute
Adds a connection
attribute.
Voi d
AddAt t r i but e(
Char * value) ;
Voi d
AddAt t r i but e(
TD_I nt Val ue value) ;
attribute Input for the type of attribute
being added.
value Input for the value of the
attribute.
None
Connection Class
AddDMLGroup
Adds a DMLGroup
object to the connection.
TD_St at usCode
AddDMLGr oup(
DMLgr oup* dml gr oup,
TD_I ndex* i ndex) ;
dmlgroup Input pointer to the
DmlGroup object.
index Output for the index number of
the DMLGroup.
TD_Error, TD_Success
See Teradata PT Status
Messages on page 68 for
more information.
AddSchema
Adds a schema object to
the connection.
A schema is the
definition of the columns
in a table or data source.
An input schema defines
the fields in a record of
input data.
voi d
AddSchema(
Schema* schema) ;
where the schema parameter is input for
the pointer to the schema object.
None
AddSchema
Adds schema to the
connection object
retrieved via GetSchema
(char **schema_buff,
TD_Count *numCols,
TD_Length *length)
Returns a schema object
in a schema pointer.
AddSchema( Schema **schema, char
*col I nf o, TD_Lengt h numCol s) ;
where:
colInfo contains the schema buffer.
schema contains the new schema.
numCols contains the number of
columns.
This method is capable of adding the
schema to the connection object before the
initiate phase is complete.
The method is only used for the dynamic
schema feature with multiple instances.
None
AddValue (char*)
Adds character value to
the attribute.
#i ncl ude "connect i on. h"
voi d AddVal ue( char * val ue) ;
* On Channel-attached z/OS platforms,
TWB.H(CONNECT). Use #include
"connecti.h" instead of "connection.h"
None
Table 2: Connection Class Objects (continued)
Object Name and
Connection Class
AddValue (int)
Adds integer value to the
attribute.
#i ncl ude " connect i on. h"
voi d AddVal ue( i nt val ue) ;
* On Channel-attached z/OS platforms
None
ApplyRows
Applies the data loaded
in the acquisition phase.
(Load and Update only).
TD_St at usCode
Appl yRows( ) ;
TD_Error,
TD_END_Method
TD_SYNC_Barrier,
TD_SYNC_TELINFO
more information.
Checkpoint
Tells the driver to
perform a checkpoint.
TD_St at usCode
Checkpoi nt (
char **dat a,
TD_Lengt h* l engt h ) ;
Data Output buffer for the checkpoint
data.
Length Output for the length of the
checkpoint buffer.
The checkpoint method currently returns
NULL with a data length of zero. These
Checkpoint parameters are reserved for
future expansion.
See Add Checkpoint and Restart on
page 33 for more information.
TD_Call_EndAcq,
TD_END_Method,
TD_Error,
TD_SYNC_Barrier,
TD_SYNC_TELINFO
more information.
Class Constructor
Returns the Connection
class instance.
usi ng namespace
t er adat a: : cl i ent : : API ;
Connect i on* Connect i on( ) ;
None
Object Name and
Connection Class
Class Constructor
Specifies encoding for the
Connection class and
returns the Connection
class instance.
usi ng namespace
Connect i on* Connect i on( TD_Encodi ng) ;
Valid values are TD_UTF8_ENCODING
(the default) and
TD_UTF16_ENCODING.
This Class Constructor is not supported on
channel-attached z/OS platforms.
None
EndAcquisition
Informs the driver that
the data acquisition
phase is completed.
This function must be
called before the data can
be applied.
TD_St at usCode
EndAcqui si t i on( ) ;
TD_END_Method,
TD_Error,
TD_SYNC_Barrier,
TD_SYNC_TELINFO
more information.
GetBuffer
Retrieves a buffer full of
rows from the Teradata
Database.
Exporting by the buffer
provides a performance
improvement over
exporting one row at a
time.
Data is in null indicator
mode. See Load Data
into or Export Data from
the Teradata Database
on page 27 for more
information.
TD_St at usCode
Get Buf f er (
char ** dat a, TD_Lengt h* l engt h) ;
Data Output for the buffer of data.
Length Output parameter that contains
the length (in bytes) of the data buffer.
TD_END_Method,
TD_Error,
TD_SYNC_Barrier,
TD_SYNC_TELINFO,
TD_Success
more information.
GetCheckPointInterval
Returns the checkpoint
interval.
i nt
Connect i on: : Get CheckPoi nt I nt er val ( )
Returns the integer
holding the check point
interval.
GetCount
Gets the count of the
attributes.
i nt Get Count ( ) ;
Returns an integer
holding the count of
attributes.
Object Name and
Connection Class
GetEncoding
Returns the character set
encoding type
TD_Encodi ng Connect i on: : Get Encodi ng
( )
TD_UTF8_ENCODING
TD_UTF16_
ENCODING
TD_EBCDIC_
ENCODING
GetErrorInfo
Retrieves detailed
information about the
last error received.
Voi d
Get Er r or I nf o(
Char * er r or Msg,
TD_Er r or Type* er r or Type) ;
errorMsg Output error string message
associated with the last received error.
Set to NULL if no error has occurred.
errorType Output error type associated
with the last received error (A value of
zero for Teradata PT errors, a value of
one for DBS errors, a value of two for
CLIv2 errors and a value of minus one
when no errors have occurred.)
None
GetEvent
Retrieves runtime
statistics from the driver.
TD_St at usCode
Get Event (
TD_Event Type event Type,
char ** event Dat a,
TD_Lengt h* event Dat aLen,
TD_I ndex event I ndex = 0) ;
eventType Input for the name of the
event to retrieve statistics for.
eventData Output pointer to the
appropriate expected return data for the
event.
eventDataLen Output parameter that
contains the length (in bytes) of the data
for the event.
eventIndex Input Target table index for
the desired event data. This optional
parameter only applies to a few events
with the default value being 0.
TD_END_Method,
TD_Error,
TD_SYNC_Barrier,
TD_SYNC_TELINFO,
TD_Unavailable
more information.
Object Name and
Connection Class
GetName
Gets the name of the
attribute.
#i ncl ude "" connect i on. h"
char * Get Name( ) ;
Returns the character
pointer holding the
attribute name.
GetRow
Retrieves a row of data
from the Teradata
Database.
Data is in null indicator
mode.
TD_St at usCode
Get Row(
Byt e** dat a,
TD_Lengt h* l engt h) ;
Data Output for the buffer of data.
Length Output for the length of the data
buffer.
TD_END_Method,
TD_Error, TD_Success,
TD_SYNC_Barrier,
TD_SYNC_TELINFO
more information.
GetSchema
Retrieves the schema.
TD_St at usCode
Get Schema( Schema** schema) ;
where schema is the output schema pointer.
TD_Error, TD_Success,
TD_Unavailable
more information.
GetSchema
Retrieves schema in a
buffer in encrypted form
TD_St at usCode
Get Schema ( char **schema_buf f ,
TD_Count *numCol s, TD_Lengt h
*l engt h)
where:
Schema is put in schema_buff.
numCols getd the number of columns.
length has the length of the schema
buffer.
These values are only meaningful to
AddSchema (Schema **schema, char
*colInfo, TD_Length numCols); method.
This method is only used for the dynamic
schema feature with multiple instances.
TD_Success
TD_Unavailable
TD_Error
Object Name and
Connection Class
GetTELINFO
Retrieves the TELINFO
area from the master
instance in a
multi-instance
environment.
TD_St at usCode
Get TELI NFO(
Char ** TELI NFO,
TD_Lengt h* l engt h) ;
TELINFO Output pointer to the buffer
containing the TELINFO area.
Length Output for the length of the
TELINFO area.
more information.
GetType
Gets the attribute type.
i nt Get Type( ) ;
TWB.H(CONNECT).Use #include
Returns the integer
holding the attribute
type:
1 mType = 0 (if non-
array or non-
multivalue)
2 mType = 1 (if array or
multivalue)
3 mType = 2 (if integer)
GetUpperValue
Change the attribute
from lower case to upper
case.
char * Get Upper Val ue( i nt i ndex = 0) ;
pointer holding the
attribute in upper case.
GetValue
Gets the specific
attribute.
char * Get Val ue( i nt i ndex = 0) ;
pointer holding the
specific attribute.
Initiate
Processes the Connection
class attributes, schemas,
and DML groups;
initializes the driver and
SQL.
Teradata FastLoad,
Teradata FastExport, and
Teradata MultiLoad
sessions are connected by
the driver.
TD_St at usCode
I ni t i at e( ) ;
TD_END_Method,
TD_Error,
TD_SYNC_Barrier,
TD_SYNC_TELINFO
more information.
Object Name and
Connection Class
MakeArray
Consolidates attribute
values into array values
and sets the array
attribute properties.
voi d MakeAr r ay( char spaceVal ues) ;
None
PutBuffer
Sends a buffer of data to
the Teradata Database.
Eliminates the extra data
movement to the CLIv2
Data or IndicData.
See Load Data into or
Export Data from the
Teradata Database for
more information.
TD_St at usCode
Put Buf f er (
Char * dat a,
TD_Lengt h l engt h,
TD_Bool ean i ndi cat or ) ;
Data Input for the buffer of data.
Length Input for the length of the data
buffer.
Indicator Input parameter that equals
one if the data is in indicator mode or
equals zero if in non-indicator mode.
Must be set to one when used with the
Update and Stream drivers.
TD_Call_EndAcq,
more information.
PutEvent
Modifies the driver at
runtime.
TD_St at usCode
Put Event (
TD_Event Type modi f i er Type,
char * modi f i er Dat a,
TD_Lengt h modi f i er Dat aLen,
TD_I ndex modi f i er I ndex = 0) ;
modifierType Input used for the
modifier name. Specifies which
modifier receives information.
modifierData Input pointer for the
appropriate expected modifier data
modifierDataLen Input parameter
specifying the length (in bytes) for the
modifier data.
modifierIndex Input Target table index
for the desired event. This optional
parameter is not currently used by any
modifier.
TD_EndMethod,
TD_Error,
TD_SYNC_Barrier,
TD_SYNC_TELINFO,
TD_Unavailable
more information.
Object Name and
Connection Class
PutRow
Sends a row of data to the
Teradata Database.
Data must be in null
indicator mode format.
TD_St at usCode
Put Row(
Char * dat a,
TD_Lengt h l engt h ) ;
Data Input for the buffer containing a
row of data.
Length Input for the length of the data
buffer. The length is the total length of
all the column values (including the
length bytes for variable-length values)
plus the number of indicator bytes. See
Data Format on page 32 for
information on how to determine the
number of indicator bytes.
TD_Call_EndAcq,
more information.
PutTELINFO
Used by the slave to store
the TELINFO area passed
from the master in a
multi-instance
environment.
TD_St at usCode
Put TELI NFO(
Char * TELI NFO,
TD_Lengt h l engt h) ;
TELINFO Input to the buffer
containing the TELINFO area.
Length Input for the length of the
TELINFO buffer.
more information.
Restart
Causes the driver to
restart at the point of the
last checkpoint.
TD_St at usCode
Rest ar t (
char *dat a,
TD_Lengt h l engt h ) ;
Data Input buffer for the checkpoint
data.
Length Input for the length of the
checkpoint buffer.
TD_END_Method,
TD_Error,
TD_SYNC_Barrier,
TD_SYNC_TELINFO
more information.
Object Name and
Connection Class
SetCount
Sets the count of the
attributes.
voi d Set Count ( i nt c) ;
None
SetValue
Sets the character value
to a specific attribute.
voi d Set Val ue( char * val ue, i nt i ndex
= 0) ;
""connecti.h"" instead of ""connection.h
None
SetValue
Sets the integer value to a
specific attribute.
voi d Set Val ue( i nt val ue, i nt i ndex =
0) ;
TWB.H(CONNECT). Use #include"
connecti.h" instead of "connection.h"
None
SetType
Sets the attribute type.
voi d Set Type( i nt t ) ;
None
Terminate
Closes the driver and
disconnects all sessions.
TD_St at usCode
Ter mi nat e( ) ;
TD_END_Method,
TD_Error,
TD_SYNC_Barrier,
TD_SYNC_TELINFO
more information.
UseDMLGroups
Designates which DML
group to use.
TD_St at usCode
UseDMLGr oups(
TD_I ndex* i ndex,
TD_Count count ) ;
Index Input pointer to an array of
indexes. Each index refers to a DML
group added using the AddDMLGroup
function.
Count Input for the number of indexes
in the index array.
more information.
Object Name and
Schema Class
Schema Class
The schema class of attributes contains information about the format of the data used in the
task. This information is used by the drivers to process the data being loaded and exported.
When loading data with the Load, Update, or Stream drivers, ensure that the row data is
consistent with the layout defined in the input schema. Discrepancies in the length of the row
data could result in data corruption. If the row data is longer than defined in the input schema
during PutRow or PutBuffer, Teradata PT will terminate with an error.
of connection.h.
Table 3: Schema Class Objects
Object Name and Function Structure and Notes Return Codes
AddColumn
Defines a column variable
within the schema.
Used to specify the name and
type for a field in input and
output data. Similar to the
DEFINE command in
Teradata FastLoad Reference
and the FIELD command in
Teradata MultiLoad Reference,
Teradata Parallel Data Pump
Reference, and Teradata
FastExport Reference.
For example, the calls to
schema->AddColumn() map to
the DEFINE fields in the
Teradata FastLoad script file.
Voi d
AddCol umn(
Char * col Name,
TD_Dat aType dat at ype,
TD_Col umnSi ze
si ze = 0,
TD_Col umnPr eci si on
pr eci si on = 0,
TD_Col umnScal e
scal e = 0) ;
colName Input for column
name.
dataType Input for the
columns SQL data type.
size Input for column size.
precision Input for Column
precision (Only applicable to
decimal and period types).
scale Input for Column scale
(Only applicable to decimal
type).
On channel-attached z/OS
platforms, connection.h is located
in TWB.H(CONNECTI). Use
#include connecti.h instead of
connection.h.
None
Schema Class
AddColumn
Specifies the column class and
adds the column.
Voi d
AddCol umn( Col umn*) ;
where Parameter Column is the
input of type vector.
* On Channel-attached z/OS
in TWB.H(CONNECT). Use
#include "connecti.h" instead of
"connection.h"
None
Class Constructor
Returns Schema class
instance.
usi ng namespace
Schema*
Schema(
Char * st ype) ;
where stype is the input parameter
for the type of schema (input or
output).
connection.h.
None
Class Constructor
Specifies the Schema class and
returns the instance.
usi ng namespace
Schema: : Schema( const Schema&
s)
where s is the type of the
Parameter schema.
"connection.h"
None
Class Constructor
Schema class and returns the
Schema class instance.
usi ng namespace
Schema*
Schema(
TD_Encodi ng encoding) ;
where encoding is the input
parameter for the type of encoding
for this class. Valid values are
TD_UTF8_ENCODING (the
default) and
TD_UTF16_ENCODING.
This Class Constructor is not
supported on channel-attached z/
OS platforms.
None
Table 3: Schema Class Objects (continued)
Schema Class
Column
Specifies the column class and
returns the instance.
Col umn( const Col umn& c) ;
in TWB.H(CONNECT).Use
#include ""connecti.h"" instead of
""connection.h
None
GetColumn
Gets the specific column and
returns the column vector.
Col umn* Schema: : Get Col umn( I nt
i ndex)
where index is for the specific
column
"connection.h"
Returns the vector holding
the particular column.
GetColumns
Returns the column vector.
vect or <Col umn*>
Schema: : Get Col umns( )
"connection.h"
Returns the vector holding
the columns.
GetColumnCount
Returns the number of
columns.
TD_Count
Schema: : Get Col umnCount ( )
in TWB.H(CONNECT).
Use #include "connecti.h" instead
of "connection.h"
Returns the integer holding
the column count.
GetDataType
Returns the column data type.
i nt Get Dat aType( ) ;
"connection.h"
data type of TD_INTEGER
and TD_CHAR. See
TD_DataType on page 65.
GetEncoding
Gets encoding return the
TD_ENCODING.
TD_Encodi ng
Schema: : Get Encodi ng( )
"connection.h"
TD_UTF8_ENCODING
TD_EBCDIC_ENCODING
TD_UTF16_ENCODING
Schema Class
GetName
Returns the table name.
st r i ng Schema: : Get Name( )
"connection.h"
Returns the string holding
the table name.
GetName
Gets the column name.
char * Get Name( ) ;
"connection.h"
Returns the character pointer
holding the column name.
GetOffset
Returns the offset of the
column.
i nt Get Of f set ( ) ;
"connection.h"
offset of the column.
GetPrecision
Returns the precision of the
decimal column.
i nt Get Pr eci si on( ) ;
""connection.h"
the decimal precision.
GetScale
Returns the scale of the
decimal column.
i nt Get Scal e( ) ;
platforms,connection.h is located
"connection.h"
the scale precision.
GetSchemaType
Returns the schema type.
PX_SchemaType
Schema: : Get SchemaType( )
""connection.h"
PX_NoSchema,
PX_InputSchema,PX_Input
SchemaAny,
PX_OutputSchema,PX_Out
putSchemaAny
PX_InputOutputSchema
PX_InputOutputSchemaAny
Schema Class
GetSize
Returns the column size.
i nt Get Si ze( ) ;
"connection.h"
the size of the column.
IsNullable
Returns the boolean value.
bool I sNul l abl e( ) ;
"connection.h
False (or) True
SetName
Sets the table name.
#i ncl ude " " connect i on. h"
voi d Schema: : Set Name( st r i ng
name)
where name is the table name
input to the Set name
""connection.h
None
SetNullable
Sets the boolean value to the
column.
#i ncl ude " " connect i on. h"
voi d Set Nul l abl e( ) ;
"connection.h"
None
SetOffset
Sets the offset of the column.
voi d Set Of f set ( i nt of f set ) ;
"connection.h"
None
SetType
Sets the schema type (input or
output).
voi d
Set Type(
Char * st ype) ;
where stype is an input parameter
for the type of schema (input or
output).
connection.h.
None
DML Group Class
DML Group Class
Each DMLGroup has one or more DML Statements along with a set of DML Options which is
used to load or update data.
of connection.h.
Table 4: DMLGroup Class Objects
Object Name and Function Syntax Return Codes
AddArraySupport
Enables array support for the
DMLGroup.
Voi d
AddAr r aySuppor t (
char * ar r aysupor t ) ;
where arraysupport is on or off.
None
AddDMLOption
Sets a DML option to be used
with the DMLGroup.
Voi d
AddDMLOpt i on(
DMLOpt i on opt i on) ;
where option is an input parameter for the
DML Option constant.
None
AddSerializeOn
Designates which column(s) to
serialize when using the Stream
driver.
Voi d
AddSer i al i zeOn(
I nt ar gcount , . . . , NULL) ;
argcount Input for the number of
values.
column(s) (...) Input for the name(s) of
column(s) as defined in the table.
None
DML Group Class
AddStatement
Adds a DML statement to the
DMLGroup.
Voi d
AddSt at ement (
Char * st at ement ) ;
where statement is an input parameter for
the DML statement.
None
AddUseList
Designates which column(s) to
use when executing the SQL
statements in a DML group
during the application process.
Voi d
AddUseLi st (
I nt ar gcount ,
. . . , NULL) ;
argcount Input for the number of
values.
column(s) (...)Input for the name(s) of
column(s) as defined in the table.
None
Class Constructor
Returns DMLGroup class
instance.
#i ncl ude DMLGr oup. h
usi ng namespace
DMLGr oup* DMLGr oup( ) ;
None
Class Constructor
DMLGroup class and returns
the DMLGroup class instance.
#i ncl ude DMLGr oup. h
usi ng namespace
DMLGr oup* DMLGr oup( TD_Encodi ng
encoding) ;
where encoding is the input parameter for
the type of encoding for this class. Valid
values are TD_UTF8_ENCODING (the
default) and TD_UTF16_ENCODING.
This Class Constructor is not supported
on channel-attached z/OS platforms.
None
DMLGroup
Specifies the DMLgroup class
and returns the instance.
DMLGr oup: : DMLGr oup( const DMLGr oup&
g)
None
Table 4: DMLGroup Class Objects (continued)
DML Group Class
GetArraySupport
Returns the array support on
(or) off.
Char * DMLGr oup: : Get Ar r aySuppor t ( )
Returns the
character pointer
holding the "On"
and "Off ".
GetDmlStatements
Returns the DML Statements.
vect or <char *>
DMLGr oup: : Get Dml St at ement s( )
Returns the vector
of the char pointer
holding the DML
statements.
GetEncoding
Gets the DMLGroup encoding.
TD_Encodi ng DMLGr oup: : Get Encodi ng( )
TD_UTF8_
ENCODING
TD_UTF16_
ENCODING
TD_EBCDIC_
ENCODING
GetName
Gets the DML group name.
st r i ng DMLGr oup: : Get Name( )
"connecti.h" instead of "connection.h "
Returns the string
holding the
DMLgroup name.
GetOptions
Returns the DML options
TD_Count DMLGr oup: : Get Opt i ons( )
Returns the integer
holding the
options count.
GetSerializeColumn
Specifies the index and returns
the serialize column from the
vector serialize list.
Char *
DMLGr oup: : Get Ser i al i zeCol umn( TD_I n
dex i ndex)
where index is the referring to the serialize
column from the Serialize List
Returns the
character pointer
holding the
serialize column.
GetSerializeCount
Returns the serialize count.
TD_Count
DMLGr oup: : Get Ser i al i zeCount ( )
"connecti.h" instead of "connection.h
Returns the integer
holding the
serialize count.
DML Group Class
GetSerializeList
Returns the serialize List.
vect or <char *>
DMLGr oup: : Get Ser i al i zeLi st ( )
onnection.h is located in
Returns the vector
of the char pointer
holding the
Serialize List.
GetStatement
Specifies the index and returns
the particular statement.
Char *
DMLGr oup: : Get St at ement ( TD_I ndex
i ndex)
where the index is to get the statement
from the statement list
Returns character
pointer holding
the statement.
GetStatementCount
Returns the statement count.
TD_Count
DMLGr oup: : Get St at ement Count ( )
Returns the integer
holding the
statement count.
GetUseColumn
Specifies the index and GetUse
column from the vector use
column list
Char *
DMLGr oup: : Get UseCol umn( TD_I ndex
i ndex)
where index is referring to the index from
the use list
Returns the
character pointer
holding the
GetUse Column.
GetUseCount
Returns the GetUse count.
TD_Count DMLGr oup: : Get UseCount ( )
Returns the integer
holding the get use
count.
GetUseList
Returns the GetUseList.
vect or <char *>
DMLGr oup: : Get UseLi st ( )
Returns the vector
of the char pointer
holding the
GetUseList.
For use with the AddDMLOption function in the DMLGroup object. This section describes
options to use with the DML statements in the DML group. Default settings are indicated in
the description column. These options apply only to the Update and Stream drivers.
DML Option
SetName
Sets the DML group name.
voi d DMLGr oup: : Set Name( st r i ng nm)
where nm is the parameter of char type
None
Table 5: DML Group Options
Constant Description
IGNORE_DUPLICATE_ROWS Duplicate rows for both insert and update
operations are ignored.
IGNORE_DUPLICATE_INSERT_ROWS Duplicate rows for insert operations are ignored.
IGNORE_DUPLICATE_UPDATE_ROWS Duplicate rows for update operations are
ignored.
IGNORE_EXTRA_DELETE_ROWS Rows that effect more than one row in the target
table for delete operations are ignored. This
option is supported only by the Stream driver.
IGNORE_EXTRA_ROWS Rows that effect more than one row in the target
table for delete or update operations are ignored.
This option is supported only by the Stream
driver.
IGNORE_EXTRA_UPDATE_ROWS Rows that effect more than one row in the target
table for update operations are ignored. This
IGNORE_MISSING_ROWS Missing rows for update and delete operations
are ignored.
IGNORE_MISSING_DELETE_ROWS Missing rows for delete operations are ignored.
IGNORE_MISSING_UPDATE_ROWS Missing rows for update operations are ignored.
TD_Attribute
For use with the AddAttribute and AddArrayAttribute functions in the Connection object.
Once an attribute is set in the connection object, it cannot be reset to a different value in the
same connection.
For the Load driver, see Attribute Definitions on page 73.
For the Update driver, see Attribute Definitions on page 91.
For the Stream driver, see Attribute Definitions on page 115.
For the Export driver, see Attribute Definitions on page 145.
INSERT_FOR_MISSING_UPDATE_ROWS This option applies only when the DML group
consists of a single update statement, followed by
a single insert statement.
MARK_DUPLICATE_ROWS Duplicate rows for both insert and update
operations are placed in error table. This is the
default setting.
MARK_DUPLICATE_INSERT_ROWS Duplicate rows for insert operations are placed
in error table. This is the default setting.
MARK_EXTRA_DELETE_ROWS Rows that effect more than one row in the target
table for delete operations are placed in the error
table. This is the default setting. This option is
supported only by the Stream driver.
MARK_EXTRA_ROWS Rows that effect more than one row in the target
table for delete or update operations are placed
in the error table. This is the default setting. This
MARK_EXTRA_UPDATE_ROWS Rows that effect more than one row in the target
table for update operations are placed in the
error table. This is the default setting. This
MARK_MISSING_DELETE_ROWS Missing rows for delete operations are placed in
error table. This is the default setting.
MARK_MISSING_ROWS Missing rows for update and delete operations
are placed in error table. This is the default
setting.
MARK_MISSING_UPDATE_ROWS Missing rows for update operations are placed in
MARK_MISSING_UPDATE_ROWS Missing rows for update operations are placed in
Table 5: DML Group Options (continued)
TD_DataType
For use with the AddColumn function in the schema object. The following table defines data
type for each column in the schema. See SQL Data Types and Literals for detailed information
on each data type including an explanation of precision and scale for the decimal type and
length and precision for the period data type.
On Specifying Data Types
Note the following when specifying data types:
Table 6: Schema Object AddColumn Constants
Constant Data Type
TD_BIGINT big integer
TD_BYTE byte
TD_BYTEINT byte integer
TD_CHAR character
TD_DATE date
TD_DATE_ANSI ANSI date
TD_DECIMAL decimal
TD_FLOAT float
TD_GRAPHIC graphic
TD_INTEGER integer
TD_LONGVARCHAR long variable length character
TD_LONGVARGRAPHIC long variable length graphic
TD_NUMBER fixed / floating point decimal
TD_PERIOD_DATE period(date)
TD_PERIOD_TIME period(time)
TD_PERIOD_TIME_TZ period(time with time zone)
TD_PERIOD_TS period(time stamp)
TD_PERIOD_TS_TZ period(time stamp with time zone)
TD_SMALLINT small integer
TD_VARBYTE variable length byte
TD_VARCHAR variable length character
TD_VARGRAPHIC variable length graphic
The length of any CHAR or VARCHAR column should be an even number when using the
UTF16 session character set. If the length for either one of these data types is an odd
number when using the UTF16 session character set then an error will be returned by the
Initiate method.
Do not use the TD_LONGVARCHAR data type when the server storage character set or
the client session character set is a multibyte character set. KANJISJIS_OS, UTF8, and
UTF16 are examples of multibyte character sets.
The PERIOD data types that support the date and time are in the form:
PERIOD(DATE)
PERIOD(TIME(n))
PERIOD(TIME(n) WITH TIME ZONE)
PERIOD(TIMESTAMP(n))
PERIOD(TIMESTAMP(n) WITH TIME ZONE)
The (n) corresponds to the precision of the column. The precision of these columns can be
an integer from zero to six. Six is the default if no precision is specified. The
PERIOD(DATE) data type has no precision.
PERIOD(DATE), PERIOD(TIME(n)) and PERIOD(TIME(n)) WITH TIME ZONE) are
fixed length.
PERIOD(TIMESTAMP(n)) and PERIOD(TIMESTAMP(n)) WITH TIME ZONE) are
variable length.
When using the TIME, TIMESTAMP, and INTERVAL data types, see Teradata Parallel
Transporter Reference.
The NUMBER data type, compatible with Oracle's NUMBER data type, stores both fixed
and floating point decimal numbers. NUMBER data type can be specified up to 38 digits.
The following are the different possible syntax for the NUMBER data type:
NUMBER
NUMBER(*)
NUMBER(*,scale)
NUMBER(precision)
NUMBER(precision,scale)
The NUMBER data type is a variable length numeric column with the following external
specification:
<1-byte Length><2-bytes Scale><1 to 17 bytes 2's complement representation of the
unscaled value in the client-appropriate endianness>
User applications should add the length of the NUMBER type as '18' bytes
(recommended) while defining the schema. For example:
schema - > AddCol umn( " Number _dt " , TD_NUMBER, 18, 5, 2) ; Lengt h = 18,
Pr eci si on = 5, Scal e = 2.
For the Number(*) type, a precision of -128 should be added to the schema
Number ( *, 4) i s r epr esent ed as schema - > AddCol umn( " Number _dt ",
TD_NUMBER, 18, - 128, 4) ; Lengt h = 18, Pr eci si on = - 128, Scal e = 4
If the precision is greater than 18, then the attribute TD_MAX_DECIMAL_DIGITS
should be set.
In Teradata PT API, the Array data type, a Teradata UDT, is implemented as a VARCHAR.
To implement the Array type in Teradata PT API:
Create ARRAY data type as follows:
CREATE TYPE pnumAS CHAR( 10) ARRAY[ 2] ;
Create target table as follows:
Cr eat e t abl e emp( Associ at e_I d i nt eger , phone_nums pnum) ;
Add the column to the schema in Teradata PT API application:
schema - > AddCol umn( " phone_nums" , TD_VARCHAR, 47) ;
Note: The insert statement for the Array data type is:
I NSERT I NTO t ar get _t abl e ( : Associ at e_I d, : phone_nums ) ;
TD_Encoding
Note: The default setting for all drivers is TD_UTF8_ENCODING. On channel-attached z/
OS platforms, only EBCDIC encoding is supported and is automatically selected.
TD_OperatorType
For use with the AddAttribute function as values for the TD_SYSTEM_OPERATOR attribute.
The following tables designate which driver to use with the connection.
If NUMBER is... Precision Passed to Operator is... Scale Passed to Operator is...
NUMBER -255 -255
NUMBER(*) -128 -128
NUMBER(*,scale) -128 scale
NUMBER(precision) precision -255
NUMBER(precision,
scale
precision scale
Table 7: TD_Encoding Constants
TD_UTF8_ENCODING UTF-8 encoding
TD_UTF16_ENCODING UTF-16 encoding
TD_TRACE_LEVEL
For use with the AddArrayAttribute as values for the TD_TRACE_LEVEL attribute. Defines
levels of tracing for both the driver level and infrastructure level. Customers should normally
set tracing to OFF unless Customer Support or development requires this option to be
enabled for debugging purposes.
Table 10 contains all the possible status messages that can be returned by the Teradata PT. The
set of possible status messages returned by a specific Teradata PT function varies. See the
Return Code column in Table 2, Table 3, and Table 4 for the possible status messages returned
by each function.
Table 8: TD_SYSTEM-OPERATOR Attribute Constants
TD_EXPORT Export driver
TD_LOAD Load driver
TD_STREAM Stream driver
TD_UPDATE Update driver
Table 9: TD_TRACE_LEVEL Attribute Constants
TD_OPER Enables tracing for driver specific activities.
TD_OFF Tracing is disabled.
TD_OPER_ALL Enables all driver level tracing.
TD_OPER_CLI Enables tracing for activities involving CLIv2.
TD_OPER_NOTIFY Enables tracing for activities involving the Notify
feature.
TD_OPER_OPCOMMON Enables tracing for activities involving the
operator common library.
Table 10: Teradata PT Status Messages
Message Status
CLI Error A CLIv2 error has occurred. Values range from
300 to 500.
DBS Error A Teradata Database error has occurred. Values
range from 2,000 to 8,000.
TPTAPI Error A Teradata PT specific error has occurred. Values
range from 10000 and up.
TD_Call_EndAcq The Teradata PT driver is signaling to the user
application that the acquisition method needs to
be aborted due to an error. The application must
immediately call the EndAcquisition function. In
a multiple instance environment, if the master or
one or more slave instances receives this status
code, all instances must immediately proceed to
call the EndAcquisition function.
TD_END_Method The calling application may move on to the next
method. In export jobs, this status also signifies
end of data when returned by the GetRow or
GetBuffer functions.
In a multiple instance environment, the
following must be done:
Each instance waits until all instances have
returned the end method code.
Each instance enters the next method.
See Parallel Processing Return Codes in
Chapter 7 for more information.
TD_Error An error has occurred. When an error occurs,
the return value is equal to or greater than
TD_Error. TD_Error is a generic error code. See
error types included in this table for specific
numeric error code ranges.
TD_Success The function has completed successfully.
TD_SYNC_Barrier Used in a multiple instance environment.
Signifies that the following must be done:
Each instance waits until all instances return
the barrier code.
Each instance then recalls the method that
returned the barrier code.
Table 10: Teradata PT Status Messages (continued)
Message Status
Dynamic Loading
Dynamic Loading
Teradata PT applications can load the TELAPI library dynamically during the runtime.
Three virtual C++ classes, derived from existing classes to maintain backward compatibility to
existing applications, provide dynamic loading:
ConnectionX (derived from Connection)
SchemaX (derived from Schema)
DMLGroupX (derived from DMLGroup)
Because these classes act as wrapper classes, they have the same set of public methods as that
of the classes from which they are derived.
Extern C Functions
Since a C++ function can dynamically load a function with a C-linked symbol name, which
can in turn instantiate a C++ object and return a pointer to it, the extern C functions are
provided in each new class. These extern C functions serve as entry points in the shared
Teradata PT API library when the library is dynamically loaded. They ensure that objects that
are instantiated inside a dynamically loaded library must be deleted inside the same library.
On many UNIX and UNIX-like systems, such as Linux, the application first opens the library,
using the dlopen() function and then retrieves the desired symbol with the dlsym() function.
When dlsym() finds the symbol, it returns a function pointer that can be used to call the
loaded function.
TD_SYNC_TELINFO Used in a multiple instance environment.
Signifies that the following must be done:
Each instance waits until all instances return
the barrier code.
Get the TELINFO area from the master
instance using the GetTELINFO function.
Pass a copy of the masters TELINFO area to
each of the slave instances.
Store the masters TELINFO area within each
slave instance using the PutTELINFO
function.
Each instance then recalls the method that
returned the barrier code.
TD_Unavailable The data for an event is currently unavailable.
Table 10: Teradata PT Status Messages (continued)
Message Status
Dynamic Loading
Below is the list of these extern C entry functions to the Teradata PT API library:
ConnectionX* newConnectionX();
ConnectionX* newConnectionXEncoding (TD_Encoding encoding);
ConnectionX* copyConnectionX (ConnectionX *dest, ConnectionX *src);
void delConnectionX (ConnectionX *object);
SchemaX* newSchemaX(Char *stype);
SchemaX* newSchemaXEncoding (TD_Encoding encoding);
SchemaX* copySchemaX (SchemaX *dest, SchemaX *src);
void delSchemaX (SchemaX *object);
DMLGroupX* newDMLGroupX();
DMLGroupX* newDMLGroupXEncoding (TD_Encoding encoding);
DMLGroupX* copyDMLGroupX (DMLGroupX *dest, DMLGroupX *src);
void delDMLGroupX (DMLGroupX * object);
DynamicLibrary
A dynamic library wrapper class, called DynamicLibrary, encapsulates the loading of the
Teradata PT API library and the loading of objects from the shared library, hiding all of the
low-level details from the rest of the application. The class is implemented as a singleton class
to ensure that the library is dynamically loaded once and to provide a global point of access to
the loaded library.
The following is the class interface:
/ / To l oad TPTAPI l i br ar y
st at i c Dynami cLi br ar y* I nst ance ( ) ;
/ / Cr eat e obj ect s out of t he l oaded l i br ar y
Connect i onX* newConnect i onX ( ) ;
Connect i onX* newConnect i onX ( TD_Encodi ng encodi ng) ;
DMLGr oupX* newDMLGr oupX ( ) ;
DMLGr oupX* newDMLGr oupX ( TD_Encodi ng encodi ng) ;
SchemaX* newSchemaX ( char * st ype) ;
SchemaX* newSchemaX ( TD_Encodi ng encodi ng) ;
/ / Del et e obj ect s cr eat ed out of t he l oaded l i br ar y
voi d del Connect i onX ( Connect i onX*) ;
voi d del DMLGr oupX ( DMLGr oupX*) ;
voi d del SchemaX ( SchemaX*) ;
A DynamicLibrary object is created through the static method DynamicLibrary::Instance(),
which loads the Teradata PT API library and all the entry function pointers available in the
library. Once the library has been loaded, the DynamicLibrary can be used to create new
objects of the class ConnectionX, DMLGroupX, and SchemaX by calling the appropriate
function (for example, newConnectionX(), new DMLGroupX, new SchemaX).
After an object is created, simply call any available methods on the object via its pointer. The
loaded library is closed when the DynamicLibrary object is deleted. The DynamicLibrary
destructor handles closing the loaded library.
Dynamic Loading
The following code snippet shows how easily dynamic loading can be implemented in an
application:
Dynami cLi br ar y *l i b_hdl ;
l i b_hdl = Dynami cLi br ar y: : I nst ance( ) ; / / Load t he l i br ar y
/ / Cr eat e Connect i onX obj ect
Connect i onX *conn = l i b_hdl - >newConnect i onX( ) ;
/ / Cr eat e SchemaX obj ect
SchemaX *schema = l i b_hdl >newSchemaX( "i nput " ) ;
/ / Cr eat e DMLGr oupX obj ect
DMLGr oupX * dml Gr = l i b_hdl - >newDMLGr oupX( ) ;
l i b_hdl - >del Connect i onX( conn) ; / / Del et e Connect i onX obj ect
l i b_hdl - >del DMLGr oupX( dml Gr ) ; / / Del et e DMLGr oupX obj ect
l i b_hdl - >del SchemaX( schema) ; / / Del et e SchemaX obj ect
. . . . . . . . . . . .
conn- >AddAt t r i but e( TD_SYSTEM_OPERATOR, TD_LOAD) ;
schema- >AddCol umn( " Associ at e_I d" , TD_I NTEGER, 4, 1, 1) ;
dml Gr - >AddSt at ement ( dml _st at ment ) ;
. . . . . . . . . . . . . . .
del et e( l i b_hdl ) ; / / Unl oad t he l i br ar y
CHAPTER 3
Load Driver
The Load driver uses Teradata FastLoad Reference protocols to load a large volume of data at
high speed into an empty table on the Teradata Database. Besides being empty, the target table
on the Teradata Database can not have defined secondary indexes. Main topics on the Load
driver include:
Attribute Definitions
Table 11 and Table 12 define the required and optional attributes needed to code an
application.
Required Attributes
Attribute Definitions Reusing Table Names
Required Attributes Dropping Tables During a Load
Optional Attributes Required Privileges
GetEvent Queries Session Limits
Programming Considerations Space Requirements and Limitations
Error Tables and Error Reporting Checkpoint and Restart Operations
Limiting Insertion Errors Code Example
Duplicate Records
Table 11: Load Driver Required Attributes
Attribute and Type Type Description
TD_BUFFER_MODE varchar Indicates which type of Load method is used.
Valid Settings:
Default value is No.
Must be set to Yes when using the PutBuffer feature.
Chapter 3: Load Driver
Optional Attributes
TD_INSTANCE_NUM integer Provides the instance number of the current instance. Required only
when using multiple instances of the same driver in a master-slave
environment.
If the current instance is the master instance, then the instance number
is one.
If the current instance is a slave instance, then the instance number
should be a value greater than one.
TD_LOG_TABLE varchar Provides the name of the restart log table for restart information.
Note: If the restart log table name is not fully qualified, it is created under
the users default (logon) database. Alternately, a working database can be
specified using the TD_WORKINGDATABASE attribute. If the
TD_WORKINGDATABASE attribute is used, the restart log table name
must be fully qualified, even if the restart log table is going to reside in the
default (logon) database.
TD_MAX_INSTANCES integer Required only if using multiple instances of the same driver in a master-
slave environment. Provides the total number of instances (master and
slaves).
TD_RESTARTMODE integer Required only before restarting. Must be set to 1 before performing a
restart.
TD_SYSTEM_OPERATOR varchar Provides the type of driver being used (in this case TD_LOAD).
TD_TARGET_TABLE varchar Provides the name of the Load target table.
TD_USER_NAME varchar Provides the name of the user for the Load driver logon sessions.
TD_USER_PASSWORD varchar Provides the password associated with the user name.
Table 11: Load Driver Required Attributes (continued)
Table 12: Load Driver Optional Attributes
TD_ACCOUNT_ID varchar Specifies the account associated with the specified user name. When
omitted, this attribute defaults to the account identifier of the
immediate owner database.
TD_AUTORESTART varchar Teradata PT APT notifies the user application, once Teradata Database
restarts, that the database crashed.
Valid values are:
Yes (Y) = The user application receives a response about the
database crash once thee database is online (default).
No (N) = The user application receives the CLI 220 error message
when the database is down during the acquisition phase of Teradata
PT API.
TD_BUFFER_SIZE integer Specifies the output buffer size, in kilobytes, used for sending Load
parcels to the Teradata Database.
The output buffer size and the size of the rows in the Load table
determine the maximum number of rows included in each parcel to
the Teradata Database. A larger buffer size reduces processing
overhead by including more data in each parcel.
The allowable values are 1 through 64. However, if you specify a
value of 64, the actual buffer size is set to 64260.
The default buffer size is the maximum size allowed, which depends
on the Teradata Database and CLI version. The maximum buffer
size on V2R6.0 and later is 64K bytes.
If you specify a value less than one, the Load driver issues an error
message and terminates the job. Any other value specified is
evaluated when the connection to the Teradata Database is made.
Because some Teradata Database versions support buffer sizes of
32K only, specifying a value of 64K would be invalid, but the driver
does not know this until it connects to the Teradata Database and
queries its version.
If the supplied buffer size is too large, the Load driver scales it back
to the maximum allowable size.
TD_CHARSET varchar Character Set is the name of the session character set used for the job.
On channel-attached z/OS platforms, only EBCDIC encoding is
supported and is automatically selected. For the list of supported
session character sets, see Extended Character Sets in Teradata
Parallel Transporter Reference.
In a multi-instance environment the master and all the slave instances
should have the same session character set. Also, the data for each
instance should be in the same character set as the session character set.
If the master instances does not use the TD_CHARSET attribute then
the slave instance(s) should not use the attribute. If the master instance
specifies a different session character set than any of its slave instances
then the Load, Export, and Update drivers will use the master instances
session character set for the entire job. The Stream driver, however, will
let each instance use its own session character set for the job.
Also, note that the session character set for all instances should not
change if a restart occurs. If any instance specified a value for
TD_CHARSET before the restart then that instance needs to specify the
same value for TD_CHARSET when the connection is initiated again
and then restarted.
TD_DATA_ENCRYPTION varchar Makes full security encryption of SQL requests, responses, and data
available.
Off = No encryption occurs. This is the default setting.
On = All SQL requests, responses, and data are encrypted.
TD_DATE_FORM varchar Specifies the DATE data type for the Load driver job.
IntegerDate = Integer DATE data type. This is the default setting.
AnsiDate = ANSI fixed-length CHAR(10) DATE data type.
Table 12: Load Driver Optional Attributes (continued)
TD_DROPERRORTABLE varchar Directs the Load driver to drop the existing error tables at the end of the
job. By default, the Load driver drops the error tables at the end of a job
if the error tables are empty.
If the error tables are not dropped at the end of a successfully
terminating job and the same error table names are used in a
subsequent Load job then the Teradata Database will return an error on
those subsequent Load jobs, even if those error tables are empty.
Valid values are:
Yes (Y) = Drop the error table if it is empty at the end of the job.
This is the default setting.
No (N) = Do not drop the existing error table.
TD_DROPLOGTABLE varchar Directs the Load driver to drop the existing restart log table at the end
of the job. By default, the Load driver drops the restart log table at the
end of a job only if the job completes successfully.
If the restart log table is not dropped at the completion of a successful
job and the same restart log table name is provided in a subsequent
Load job then the results will be unpredictable. This unpredictability is
due to the nature of the Teradata FastLoad protocol, where the existence
of a restart log table implies the job is a restart and the Load driver may
attempt to restart the job at a point in time as dictated by the contents
of the restart log table.
The Load driver will try to detect whether this situation has occurred
and will attempt to terminate the job with a meaningful error message
but this attempt is dependent upon the contents of the restart log table.
Valid values are:
Yes (Y) = Drop the restart log table if the job completed
successfully. This is the default setting.
No (N) = Do not drop the existing restart log table.
TD_ERROR_LIMIT integer Specifies the maximum number of records stored in one of the error
tables before the Load driver job is terminated. The ErrorLimit
specification applies to each instance of the Load driver.
Specifying an invalid value causes the Load driver to terminate. By
default, ErrorLimit value is unlimited.
The ErrorLimit specification must be greater than zero.
TD_ERROR_TABLE_1 varchar Specifies the name of the first error table. This must be a new table
name. You cannot use a name that duplicates the name of an existing
table unless you are restarting a paused Load driver job.
ErrorTable1 is for containing records rejected during the acquisition
phase of the Load driver job because of:
Data conversion errors
Constraint violations
AMP configuration changes
The default name for ErrorTable1 is ttname_ET.
For more information on the error table format and the procedure to
correct errors, see FastLoad Errors in Teradata FastLoad Reference.
TD_ERROR_TABLE_2 varchar Specifies the name of the second error table. This must be a new table
name. You cannot use a name that duplicates the name of an existing
table unless you are restarting a paused Load driver job.
ErrorTable2 contains records that violated the unique primary index
constraint.
These types of errors occur during the acquisition phase of the Load
driver job.
The default name for ErrorTable2 is ttname_UV.
For more information on the error table format and the procedure to
correct errors, see FastLoad Errors in Teradata FastLoad Reference.
TD_LOGSQL varchar Directs the Load driver to output the full Teradata SQL request in the
trace output file when the drivers trace is enabled.
Valid values:
Yes ('Y') = Output the full Teradata SQL in the trace output file
when the drivers trace is enabled. The maximum length of the
Teradata SQL is 1 megabyte.
No ('N') = Do not output the Teradata SQL in the trace output file.
Note: When the drivers trace is disabled, TD_LOGSQL has no effect.
TD_LOGON_MECH varchar Specifies which logon mechanism to use.
See your site security administrator for specific mechanism names.
For a list of available mechanisms, see Security Administration.
The job terminates if the attribute exceeds eight bytes.
TD_LOGON_MECH_DATA varchar Passes additional logon mechanism data.
See your site security administrator for specific mechanism data. For
more information, see Security Administration.
TD_MAX_SESSIONS integer Specifies the maximum number of sessions to log on.
The default is one session per available AMP. The maximum value
cannot be more than the number of AMPS available.
The MaxSessions value must be greater than one. Specifying a value
less than one terminates the job.
The MaxSessions value must be greater than or equal to the value of
TD_MAX_INSTANCES.
TD_MIN_SESSIONS integer Specifies the minimum number of sessions required for the Load driver
job to continue.
The default is one session.
The MinSessions value must be greater than zero and less than or
equal to the maximum number of Load driver sessions. Specifying a
value less than one terminates the Load driver.
TD_MSG_ENCODING TD_
Encoding
Specifies the encoding for the messages passed between Teradata PT
and a Teradata PT application.
TD_NOTIFY_EXIT varchar Specifies the name of the user-defined notify exit routine with an entry
point named _dynamn.
If no name is supplied, the following default names are used:
libnotfyext.dll for Windows
libnotfyext.sl for HP-UX platforms
libnotfyext.so for Linux and all other UNIX platforms
For detailed information on the Notify feature, see Load Operator in
Teradata Parallel Transporter Reference.
TD_NOTIFY_LEVEL varchar Indicates the level at which certain events are reported.
The valid settings are:
Off = No notification of events is provided. This is the default
setting.
Low = Notification is provided for these events:
Initialize
CLIv2/DBS error
Exit
Medium = Notification is provided for all the events except for Error
Table 1 and Error Table 2.
High = Notification is provided for all events.
TD_NOTIFY_METHOD varchar Specifies the method for reporting events.
The methods are:
None = No event logging is done. This is the default method.
Msg = This method sends the events to a log.
Exit = This method sends the events to a user-defined notify exit
routine.
On Windows, the events are sent to the EventLog that can be viewed
using the Event Viewer. The messages are sent to the application log.
On AIX, HP-UX, Linux, and Solaris platforms, the destination of
the events is specified in the /etc/syslog.conf file.
TD_NOTIFY_STRING varchar Provides a user-defined string that precedes all messages sent to the
system log. This string is also sent to the user-defined notify exit
routine.
The maximum length of the string is:
80 bytes, if the NotifyMethod is Exit.
16 bytes, if the NotifyMethod is Msg.
TD_PAUSE_ACQ varchar Specifies whether to pause the Load job after the acquisition phase or
enter the application phase.
Valid values are:
No (or N) for normal Load driver jobs, to distribute all of the rows
sent to the Teradata Database during the acquisition phase to their
final destination on the AMPs. This is the default value.
Yes (or Y) to pause after the completion of the acquisition phase and
skip the application phase. Specifying any other value terminates the
job.
The absence of any value means that the Load driver job executes
both the acquisition phase and the application phase without
pausing. This distributes all of the rows sent to the Teradata
Database during the acquisition phase to their final destination on
the AMPs.
TD_TMSMSUPPORT varchar Enables and disables sending events to TMSM.
Valid values are:
Y]es] = enables sending events to TMSM (default)
N[o] = disables sending events to TMSM
TD_QUERY_BAND_SESS_INFO varchar Provides a user-defined query band expression that is set for every SQL
session connected by the Teradata PT driver. The following is an
example of a valid query band expression:
a=1; b=2; c=3; d=4;
If the TD_QUERY_BAND_SESS_INFO is set, the following request will
be sent by every SQL session connected by the Teradata PT Load driver:
SET QUERY_BAND = <User-Defined Query Band
Expression> FOR SESSI ON;
Setting the TD_QUERY_BAND_SESS_INFO attribute in jobs running
against non-supported versions of the Teradata Database causes a non-
fatal error. No error code is returned to the user during initiation and
the job is allowed to proceed. The log table will not be dropped at the
end of the job and the TD_Evt_ExitCode event returns a warning value
of four instead of the normal success value of zero if queried. In this
case, error information can be found in the trace file.
TD_TDP_ID varchar Specifies the name of the Teradata Database machine.
The dbcname can be up to 256 characters and can be a domain
server name.
TDP stands for Teradata Director Program and is specified for
mainframe z/OS platforms.
If you do not specify the value for the TdpId attribute, the driver
uses the default TdpId established for the user by the system
administrator.
TD_TENACITY_HOURS integer Specifies the number of hours that the Load driver continues trying to
log on when the maximum number of Load and export operations are
already running on the Teradata Database.
The default value is four hours. To make the tenacity feature
available, the hours value must be greater than zero.
Specifying a value of zero will disable the tenacity feature.
Specifying a value of less than zero terminates the Load driver.
TD_TENACITY_SLEEP integer Specifies the number of minutes the Load driver pauses before retrying
to log on when the maximum number of Load or Export operations are
The minutes value must be greater than zero. If you specify a value
less than one, the Load driver responds with an error message and
terminates the job.
The default is six minutes.
TD_TRACE_LEVEL
Note: The TraceLevel attribute is
an internal diagnostic aid. Use only
if instructed to by Teradata
support. TD_OFF should always
be specified.
integer Specifies the types of diagnostic messages written by each instance of
the driver to an external log file. The diagnostic trace function provides
more detailed information in the log file (including the version
number) to aid in problem tracking and diagnosis.
Use the AddArray attribute method to specify the two types of tracing
levels: driver tracing and infrastructure tracing.
TD_OFF is the default setting for both driver tracing and infrastructure
tracing. No external log file is produced unless this default is changed.
Specifying TD_OFF for both driver tracing and infrastructure tracing is
the same as disabling tracing.
If the TraceLevel is set to any value other than TD_OFF, an external log
file is created for each instance of the driver.
The trace levels for driver tracing are:
TD_OFF = Disables driver tracing.
TD_OPER = Activates the tracing function for driver specific
activities.The absence of any value for the PauseAcq attribute means
that the Load driver job will execute both the acquisition phase and
the application phase without pausing. This will distribute all of the
rows that were sent to the Teradata Database during the acquisition
phase to their final destination on the AMPs. Table 1 on page 41 lists
which drivers have the Pause Acquisition attribute.
TD_OPER_CLI = Activates the tracing function for CLIv2-related
activities (interaction with the Teradata Database).
TD_OPER_NOTIFY = Activates the tracing function for activities
related to the Notify feature.
TD_OPER_OPCOMMON = Activates the tracing function for
activities involving the opcommon library.
TD_OPER_ALL = Activates tracing for all of the above activities.
The trace levels for infrastructure tracing should only be used when you
are directed to by Teradata support. TD_OFF, which disables
infrastructure tracing, should always be specified.
TD_TRACE_OUTPUT varchar Specifies the name of the external file used for trace messages.
The default setting creates a new file name using the name of the driver
followed by a time stamp.
Note: If a file with the specified name already exists, then the file is
overwritten.
GetEvent Queries
GetEvent Queries
All events must be queried after the driver is initiated and before it terminates. Events queried
before their data is available return TD_Unavailable. The following table lists events used with
the Connection objects GetEvent function to retrieve runtime statistics from the Load driver.
TD_WILDCARDINSERT varchar Builds an INSERT statement from the table definition.
Valid values are:
No (or N) = No activity. This is the default value.
Yes (or Y) = Builds an INSERT statement.
If you set this attribute to Yes and a valid fully supported INSERT
statement already exists, an error results.
To be valid, the table name must match the name of the table used in
the TargetTable attribute and a semicolon must be the last non-space
character in the supplied DML statement as follows:
I NS[ ERT] [ I NTO] <t abl ename>;
TD_WORKINGDATABASE varchar Specifies the name of the database used in a Teradata SQL DATABASE
statement that the Load driver sends to the Teradata Database
immediately after connecting the two SQL sessions. Use this attribute to
specify a default database other than the logon database.
Table 13: Load Driver Events
Event Returned Value
TD_Evt_ApplyCount64 One 8-byte unsigned integer for the number of rows
inserted into the DBS. Query this event after ApplyRows.
For a multi-instance job, query this number only in the
master instance. The master instance returns the total
number of rows applied to the target table from all
instances.
TD_Evt_CLIError One 4-byte integer for the CLIv2 error number and a
255-byte character buffer for the CLIv2 error text. Query
this event at any time.
TD_Evt_DBSError One 4-byte integer for the DBS error number and a
255-character buffer for the Teradata Database error text.
Query this event at any time.
GetEvent Queries
TD_Evt_BufferLayout Four 4-byte unsigned integers corresponding to the
maximum buffer size, the row header size, the row length
size, and the buffer trailer size. Use this information to
format the buffer required for block loading.
Note: These layout values will change depending on the
user environment and may be defined differently in
future releases. Always obtain these values from the event
method before buffering data.
TD_Evt_ConnectStatus Three 4-byte integers corresponding to the number of
sessions requested, the number of sessions connected,
and the number for any CLIv2 error number that
occurred during the connect process. Query this event at
any time.
TD_Evt_CPUTime One 8-byte double for the CPU time of the instance in
seconds. Query this event at any time.
TD_Evt_OperVersion A pointer to a character string containing the driver
version. Query this event only after the driver has been
initiated.
TD_Evt_RowCounts Three 4-byte unsigned integers corresponding to the
number of rows received, sent, and applied. This event
can be queried any time before EndAcquisition to get the
current number of rows received. The rest of the data for
this event is available after ApplyRows. If rows are being
loaded using PutRow, the data for this event will not be
available until enough rows have been loaded to fill one
internal buffer or until the Checkpoint function has been
called.
The rows-applied count returned by this event does not
take into consideration rows that are rejected by the
database during the application phase. Query the
TD_Evt_ApplyCount event to get the final count of rows
that have been applied to the target table.
Table 13: Load Driver Events (continued)
GetEvent Queries
TD_Evt_RowCounts64 Three 8-byte unsigned integers corresponding to the
can be queried anytime before EndAcquisition to get the
this event is available after ApplyRows.
If rows are being loaded using PutRow, the data for this
event will not be available until enough rows have been
loaded to fill one internal buffer or until the Checkpoint
function has been called.
TD_Evt_RowsCheckpointed One 4-byte unsigned integer corresponding to the total
number of rows that have been received and
checkpointed for the entire job. Query this event any
time after initiating a Teradata PT database connection
in a single-instance job. This event will return
TD_Unavailable when queried in a job containing
multiple instances; this event is invalid if multiple
instances are used.
Note that the event data returned by this event can be
used as a replacement for the checkpoint data that must
be passed into the Restart method during a restart job. It
is recommended to always save the checkpoint data from
the last successful call to the CheckPoint method in a
potential restart job. However, if the checkpoint data is
not saved then the event data returned by this event can
be passed into the Restart method instead. This alternate
method of performing checkpoint/restarts will only work
with single-instance jobs.
Programming Considerations
The following sections describe the items you should consider when coding a Load
application.
TD_Evt_RowsCheckpointed64 One 8-byte unsigned integer corresponding to the total
checkpointed for the entire job. Query this event anytime
after initiating a Teradata PT API database connection in
a single-instance job. This event will return
instances are used.
not saved, then the event data returned by this event can
TD_Evt_ApplyCount One 4-byte unsigned integer for the number of rows
inserted into the DBS. Query this event after ApplyRows.
For a multi-instance job, only query this number in the
master instance.
The master instance returns the total number of rows
applied to the target table from all instances.
TD_Evt_ErrorTable1 One 4-byte unsigned integer for the number of rows in
error table 1. Query this event after the first call to
PutRow or PutBuffer.
error table 2. Query this event after ApplyRows.
TD_Evt_ExitCode One 2-byte integer for the driver exit code. Query this
event right before the driver terminates.
TD_Evt_Version A pointer to a character string containing the Teradata
PT version followed by a pointer to a character string
containing the operator version. Query this event at any
time. The Teradata PT version is available any time. The
operator version is available only after the driver has
been initiated.
Error Tables and Error Reporting
Duplicate Records
The Teradata Database ignores duplicate records and they are not inserted in either error
table.
Reusing Table Names
Error tables with one or more rows are not dropped from the Teradata Database at the end of
a Load driver job. To reuse the names specified for the error tables, use the DROP TABLE
statement from BTEQ to remove the tables from the Teradata Database.
Limiting Insertion Errors
Use the TD_ERROR_LIMIT attribute to limit the number of insertion errors captured in
ErrorTable1 during the acquisition phase of a Load job.
The ErrorLimit specification applies to each instance of the Load driver, not to all instances
combined. For example, you set the limit to 10,000 rows. A single instance must detect that
10,000 rows were inserted into the first error table to terminate the job, and those 10,000 rows
must be controlled by the sessions managed by that instance.
Dropping Tables During a Load
Some tables are created during the execution of a Load job, and others must be created before
the job begins. Target tables must exist and be empty when a Load driver job executes, unless
the job is attempting to continue a paused or restarted job. A log table is created automatically
when you run the Load job script. Error tables are created by the Teradata Database. Error
tables are dropped by the Load driver during the cleanup phase if no errors were detected
during the acquisition phase or the application phase. The log table is dropped by the Load
driver after the job completes successfully. If a Load job terminates abnormally, then the log
and error tables are not dropped. If you want to restart the Load job from scratch, you need to
manually drop these tables.
Processing terminates when the number of errors encountered reaches the error limit.
If, for example, you expect no errors in the input data, set the error limit value to one. In this
case, the job terminates when any record causes an error. Note, however, that when the
specified error limit is reached, the Load driver continues processing until each session
completes its current data block. This continued processing can cause the total number of
error rows captured in the first error table to exceed the ErrorLimit specification.
Table 14: TD_ERRORLIMIT Values
Load Driver Job Quality ERRORLIMIT Value
No errors or very few errors low
Many errors that are considered allowable high
Code Example
Required Privileges
The user ID used by a Load application must have:
SELECT and INSERT privileges on the Load target table
SELECT and INSERT privileges on the error tables, and DROP privileges on the database
containing the error tables.
SELECT, INSERT, and DELETE privileges on the restart log table, and DROP privileges on
the database containing the restart log table.
Session Limits
The values you specify using the TD_MIN_SESSIONS and TD_MAX_SESSIONS attributes
are not the only factors limiting the number of sessions the Load driver establishes with the
Teradata Database. When the Load driver executes, the actual session limit is determined by
whichever limiting factor is encountered first.
The other limiting factors are:
The Teradata Database limit of one session per AMP.
The platform limit on the maximum number of sessions per application. This value is
defined in the COP Interface software file, CLISPB.DAT, under the max_num_sess
variable. You can use the TDP SET MAXSESSIONS command to specify a platform limit.
The default TDP MAXSESS value is 1024 sessions.
The limit of the network protocol software on network-attached systems.
Space Requirements and Limitations
Always estimate the final size of the Load target table, and make sure that the destination
database on the Teradata Database has enough space to accommodate the Load job. If the
destination database runs out of space, the Teradata Database returns an error message and
the Load driver pauses the Load job. When this happens, you must allocate more space to the
database before you can restart the job.
Checkpoint and Restart Operations
The Load driver is fully checkpoint restartable. See the checkpoint and restart discussion in
Add Checkpoint and Restart on page 33.
Code Example
#i ncl ude " schema. h"
#i ncl ude " DMLGr oup. h"
i nt r et ur nVal ue = 0;
char * er r or Msg = NULL;
TD_Er r or Type er r or Type;
cout << "*** Load Dr i ver Exampl e ***" << endl ;
Code Example
Connect i on *conn = new Connect i on( ) ;
/ **********************************************
* Set Oper at or Type and Tr ace/ Log Level s
**********************************************/
conn- >AddAt t r i but e( TD_SYSTEM_OPERATOR, TD_LOAD) ;
/ / conn- >AddAt t r i but e( TD_TRACE_OUTPUT, " l oad. t xt " ) ;
/ / conn- >AddAr r ayAt t r i but e( TD_TRACE_LEVEL, 2, TD_OPER, TD_OFF, NULL) ;
/ **********************************************
* Add At t r i but es
**********************************************/
conn- >AddAt t r i but e( TD_USER_NAME, "user " ) ;
conn- >AddAt t r i but e( TD_USER_PASSWORD, " passwor d" ) ;
conn- >AddAt t r i but e( TD_TARGET_TABLE, " t dl oad" ) ;
conn- >AddAt t r i but e( TD_TDP_I D, " dat abase" ) ;
conn- >AddAt t r i but e( TD_LOG_TABLE, "t dl oad_l og" ) ;
/ **********************************************
* Add Schema
**********************************************/
schema- >AddCol umn( " Associ at e_I d" , TD_I NTEGER, 4) ;
schema- >AddCol umn( " DOJ " , TD_DATE, 4) ;
schema- >AddCol umn( " Desi gnat i on" , TD_VARCHAR, 25) ;
schema- >AddCol umn( " Loan_Amount " , TD_DECI MAL, 4, 5, 2) ;
schema- >AddCol umn( " Mar t i al _St at us" , TD_CHAR, 1) ;
schema- >AddCol umn( " No_Of _Dependent s" , TD_BYTEI NT, 1) ;
/ / del et e schema;
/ **********************************************
* Add DMLGr oups
**********************************************/
TD_I ndex dml Gr oupI ndex = 0;
DMLGr oup* dml Gr = new DMLGr oup( ) ;
dml Gr - >AddSt at ement ( " I NSERT I NTO t dl oad( : Associ at e_I d, : Associ at e_Name, : Sal ar y,
: DOJ , : Desi gnat i on, : Loan_Amount , : Mar t i al _St at us, : No_Of _Dependent s) ; " ) ;
conn- >AddDMLGr oup( dml Gr , &dml Gr oupI ndex) ;
/ **********************************************
* I ni t i at e
**********************************************/
r et ur nVal ue = conn- >I ni t i at e( ) ;
cout << "Dr i ver I ni t i at ed wi t h st at us " << r et ur nVal ue << endl ;
i f ( r et ur nVal ue < TD_Er r or )
{
/ **********************************************
* Acqui si t i on
**********************************************/
char r owBuf f er [ 78] ; / * must i ncl ude t he EOL byt e */
i nt l oadSt at us = 0;
TD_Lengt h byt es;
i nt count = 0;
whi l e( l oadSt at us ! = - 1 )
{
/ / user f unct i on - r eads i n a
/ / r ow of dat a f r oma f i l e
/ / r et ur ns - 1 when end of f i l e
/ / r eached
l oadSt at us = Get RowDat a( r owBuf f er , 78) ;
i f ( l oadSt at us ! = - 1 )
{
/ * pi ck up t he f i r st 2 byt es as t he r ow l engt h of t he i ndi cat or mode r ecor d
*/
byt es = *( ( unsi gned shor t *) r owBuf f er ) ;
r et ur nVal ue = conn- >Put Row( r owBuf f er + 2 , byt es) ;
i f ( r et ur nVal ue >=TD_Er r or )
{
cout << " Put Row f ai l ed on r ow " << count +1;
cout << " wi t h st at us " << r et ur nVal ue << endl ;
l oadSt at us = Get RowDat a( NULL, 0) ; / / user f unct i on - cl oses f i l e
}el se{
count ++;
}
}
Code Example
}
{
cout << " Sent " << count << " r ows" << endl ;
/ **********************************************
* End Acqui si t i on
**********************************************/
r et ur nVal ue = conn- >EndAcqui si t i on( ) ;
cout << " Acqui si t i on compl et ed wi t h st at us " << r et ur nVal ue << endl ;
{
/ **********************************************
* Appl i cat i on
**********************************************/
r et ur nVal ue = conn- >Appl yRows( ) ;
cout << " Rows Appl i ed wi t h st at us " << r et ur nVal ue << endl ;
{
cout << " Load compl et ed successf ul l y" << endl ;
}el se{
/ / Get Er r or I nf or mat i on
cout << " Er r or occur ed dur i ng Appl i cat i on" << endl ;
conn- >Get Er r or I nf o( &er r or Msg, &er r or Type) ;
i f ( er r or Msg ! = NULL ) {
cout << er r or Msg << endl ;
cout << " Type: " << er r or Type << endl ;
}el se{
cout << " No Er r or I nf o Avai l abl e" << endl ;
}
}
}el se{
cout << " Er r or occur ed dur i ng EndAcqui si t i on" << endl ;
}el se{
}
}
}el se{
cout << " Er r or occur ed dur i ng Acqui si t i on" << endl ;
}el se{
}
}
}el se{
cout << " Er r or occur ed dur i ng I ni t i at e" << endl ;
}el se{
}
}
/ **********************************************
* Ter mi nat e
**********************************************/
r et ur nVal ue = conn- >Ter mi nat e( ) ;
Code Example
cout << "Dr i ver Ter mi nat ed wi t h st at us " << r et ur nVal ue << endl ;
i f ( r et ur nVal ue >= TD_Er r or )
{
cout << "Er r or occur ed dur i ng Ter mi nat e" << endl ;
cout << "Type: " << er r or Type << endl ;
}el se{
cout << "No Er r or I nf o Avai l abl e" << endl ;
}
}
/ **********************************************
* Cl ean Up
**********************************************/
cout << "Del et i ng obj ect s" << endl ;
del et e dml Gr ;
del et e schema;
del et e conn;
cout << "*** Load Compl et e ***" << endl ;
CHAPTER 4
Update Driver
The Update driver uses Teradata MultiLoad Reference protocols to load a large volume of data
at high speed on the Teradata Database, using multiple sessions to perform highly scalable and
parallel inserts, updates, deletes, and upserts into up to five new or existing tables in a single
pass. Main topics on the Update driver include:
Table 15 defines the Update drivers required attributes, and Table 16 the optional attributes.
This information will help you code your application.
Required Attributes
Required Attributes
Optional Attributes
GetEvent Queries
Error Tables
Using DELETE in Import Tasks
Using Delete Task
Required Privileges
Session Limits
Offline AMPs
Nonparticipant AMPs
Single-AMP Systems
Table 15: Update Driver Required Attributes
TD_BUFFER_MODE varchar Indicates which type of Update method is used.
Valid Settings:
Must be set to Yes when using the block Update feature.
TD_INSTANCE_NUM integer Specifies the instance number of the current instance. Required only when
using multiple instances of the same driver in a master-slave environment.
should be one.
Chapter 4: Update Driver
Optional Attributes
TD_LOG_TABLE varchar Provides the name of the restart log table for restart information.
Note: If the restart log table name is not fully qualified, it is created under
the users default (logon) database. Alternately, a working database can be
specified using the TD_WORKINGDATABASE attribute. If the
TD_WORKINGDATABASE attribute is used, the restart log table name
must be fully qualified, even if the restart log table is going to reside in the
TD_MAX_INSTANCES integer Specifies the total number of instances (master and slaves). Required only
environment.
TD_RESTARTMODE integer Required only before restarting and must be set to one.
TD_SYSTEM_OPERATOR varchar Specifies the type of driver being used (in this case TD_UPDATE).
TD_TARGET_TABLE varchar Provides the name of the update target table.
TD_USER_NAME varchar Provides the name of the user for the update driver logon sessions.
TD_USER_PASSWORD varchar Specifies the password associated with the user name.
Table 15: Update Driver Required Attributes (continued)
Table 16: Update Driver Optional Attributes
TD_ACCOUNT_ID varchar Specifies the account associated with the specified user name. When
omitted, this attribute defaults to the account identifier of the
TD_AUTORESTART varchar Teradata PT APT notifies the user application, once Teradata
Database restarts, that the database crashed.
Valid values are:
No (N) = The user application receives the CLI 220 error
message when the database is down during the acquisition phase
of Teradata PT API.
TD_AMP_CHECK varchar Specifies the update driver response to an offline AMP condition.
Valid settings are:
Apply = Inhibits the Update driver job from entering or exiting
the application phase when an AMP is offline. This is the default
setting.
All = Pauses the Update driver job when an AMP is offline.
None = Allows the Update job to start, restart, or continue as
long as no more than one AMP is offline in a cluster.
TD_BUFFER_SIZE integer Specifies the output buffer size, in kilobytes, used for sending
Update parcels to the Teradata Database.
The output buffer size and the size of the rows in the Update
table determine the maximum number of rows included in each
parcel to the Teradata Database. A larger buffer size reduces
processing overhead by including more data in each parcel.
The allowable values are 1 through 64. However, if you specify a
value of 64, the actual buffer size is set to 64260.
The default buffer size is the maximum size allowed, which
depends on the Teradata Database and CLI version. The
maximum buffer size on V2R6.0 and later is 64K bytes.
If you specify a value less than one, the Update driver issues an
error message and terminates the job. Any other value specified
is evaluated when the connection to the Teradata Database is
made. Because some Teradata Database versions support buffer
sizes of 32K only, specifying a value of 64K would be invalid, but
the driver does not know this until it connects to the Teradata
Database and queries its version.
If the supplied buffer size is too large, the Update driver scales it
back to the maximum allowable size.
TD_CHARSET varchar Specifies the name or code of the character set to be used for the job.
For the list of supported character sets, see Extended Character
Sets in Teradata Parallel Transporter Reference. On
channel-attached z/OS platforms, only EBCDIC encoding is
supported and is automatically selected.
TD_DATA_ENCRYPTION varchar Activates full security encryption of SQL requests, responses and
data.
Valid values are:
Off = No encryption occurs. This setting is the default.
TD_DATE_FORM varchar Specifies the DATE data type for the Update driver job.
Valid settings are:
IntegerDate = Integer DATE data type. This is the default setting.
ANSIDate = ANSI fixed-length CHAR(10) DATE data type.
Table 16: Update Driver Optional Attributes (continued)
TD_DELETE_TASK varchar Specifies whether to perform the delete task to delete data from a
single Teradata Database table. The Delete Task removes rows much
more quickly than a DELETE SQL statement.
You cannot use a delete task on a view.
Valid settings for option are:
Yes (or Y) = Perform the delete task.
No (or N) = Do not perform the delete task.
Specifying any other value results in an error. The absence of any
value is the same as a No value; the Update driver executes an
IMPORT task, and none of the above rules apply.
If the Delete Task attribute processing is enabled, other relevant
optional attributes are:
TD_TENACITY_HOURS
TD_TENACITY_SLEEP
TD_AMP_CHECK
TD_DROPERRORTABLE varchar Directs the Update driver to drop the existing error tables at the end
of the job. By default, the Update driver drops the error tables at the
end of a job if the error tables are empty.
If the error tables are not dropped at the end of a
successfully-terminating job and the same error table names are
used in a subsequent Update job then the Teradata Database will
return an error on those subsequent Update jobs, even if those error
tables are empty.
Valid values are:
Yes (Y) = Drop the error tables if they are empty at the end of
the job. This is the default setting.
No (N) = Do not drop the existing error tables.
TD_DROPLOGTABLE varchar Directs the Update driver to drop the existing restart log table at the
end of the job. By default, the Update driver drops the restart log
table at the end of a job only if the job completes successfully.
If the restart log table is not dropped at the completion of a
successful job and the same restart log table name is provided in a
subsequent Update job then the results will be unpredictable. This
unpredictability is due to the nature of the Teradata MultiLoad
protocol, where the existence of a restart log table implies the job is
a restart and the Update driver may attempt to restart the job at a
point in time as dictated by the contents of the restart log table.
The Update driver will try to detect whether this situation has
occurred and will attempt to terminate the job with a meaningful
error message but this attempt is dependent upon the contents of
the restart log table.
Valid values are:
Yes (Y) = Drop the restart log table if the job completed
successfully. This is the default setting.
No (N) = Do not drop the existing restart log table.
TD_DROPWORKTABLE varchar Directs the Update driver to drop the existing work tables at the end
of the job. By default, the Update driver drops the work tables at the
end of a job if the job completed successfully.
If the work tables are not dropped at the end of a
successfully-terminating job and the same work table names are
used in a subsequent Update job then the Teradata Database will
return an error on those subsequent Update jobs.
Valid values are:
Yes (Y) = Drop the work tables if the job completes successfully.
No (N) = Do not drop the existing work tables.
TD_ERROR_LIMIT integer Specifies the maximum number of records that can be stored in an
error table before the Update driver job is terminated. The
ErrorLimit specification applies to each instance of the Update
driver.
The ErrorLimit specification must be greater than zero.
Specifying an invalid value terminates the Update driver. By default,
ErrorLimit value is unlimited.
TD_ERROR_TABLE_1 varchar Specifies the name of the first error table. This must be a new table
name. You cannot use the name of an existing table unless you are
restarting a paused Update driver job.
ErrorTable1 contains records that were rejected during the
acquisition phase of the Update driver job because of:
The default name for ErrorTable1 is ttname_ET.
For more information on the error table format and the procedure
to correct errors, see FastLoad Errors in Teradata FastLoad
Reference.
TD_ERROR_TABLE_2 varchar Specifies the name of the second error table. This must be a new
table name. You cannot use the name of an existing table unless you
are restarting a paused Update driver job.
ErrorTable2 contains records that violated the unique primary
index constraint. This type of error occurs during the application
phase of the Update driver job.
The default name for ErrorTable2 is ttname_UV.
For more information on the error table format and the procedure
to correct errors, see FastLoad Errors in Teradata FastLoad
Reference.
TD_LOGON_MECH varchar Specifies which logon mechanism is used. The job terminates if the
attribute exceeds eight bytes.
See your site security administrator for specific mechanism names.
For a list of available mechanisms, see Security Administration.
TD_LOGON_MECH_DATA varchar Passes additional logon mechanism data. See your site security
administrator for specific mechanism data. For more information,
see Security Administration.
TD_LOGSQL varchar Directs the Update driver to output the full Teradata SQL request in
the trace output file when the drivers trace is enabled.
Valid values:
Yes ('Y') = Output the full Teradata SQL in the trace output file
when the drivers trace is enabled. The maximum length of the
No ('N') = Do not output the Teradata SQL in the trace output
file. This is the default setting.
Note: When the drivers trace is disabled, TD_LOGSQL has no
effect.
TD_MAX_SESSIONS integer Specifies the maximum number of sessions to log on. The default is
one session per available AMP. The maximum value cannot be more
than the number of AMPS available.
The MaxSessions value must be greater than zero. Specifying a value
less than one causes the job to terminate.
The MaxSessions value must be greater than or equal to the value of
TD_MAX_INSTANCES.
TD_MIN_SESSIONS integer Specifies the minimum number of sessions required for the Update
driver job to continue. The default is one session.
The MinSessions value must be greater than zero and less than or
equal to the maximum number of Update driver sessions.
Specifying a value less than 1 will cause the Update driver to
terminate.
TD_MSG_ENCODING TD_
Encoding
Specifies the encoding for the messages passed between Teradata PT
and a Teradata PT application.
TD_NOTIFY_EXIT varchar Specifies the name of the user-defined notify exit routine with an
entry point named _dynamn.
If no name is supplied, the following default names are used:
setting.
Initialize
CLIv2/DBS error
Exit
Delete Init
Delete Exit
Medium = Notification is provided for all the events except:
Checkpoint
Error Table 1
Error Table 2
AMPS offline
Import Begin
Import End
High = Notification is to be provided for all events.
For detailed information on the Notify feature, see Update
Operator in Teradata Parallel Transporter Reference.
The methods are:
None = No event logging is done. This is the default.
Exit = This method sends the events to a user-defined notify exit
routine and to the system log.
On Windows, the events are sent to the EventLog that can be
viewed using the Event Viewer. The messages are sent to the
application log.
On AIX, HP-UX, Linux, and Solaris, platforms the destination of
the events is specified in the /etc/syslog.conf file.
TD_NOTIFY_STRING varchar Provides a user-defined string to precede all messages sent to the
system log. This string is also sent to the user-defined notify exit
routine.
80 bytes, if NotifyMethod is Exit.
16 bytes, if NotifyMethod is Msg.
TD_PAUSE_ACQ varchar Specifies whether to pause the Update driver job after the
acquisition phase or enter the application phase.
Valid values are:
No (or N) = Do not pause. This is the default setting.
Yes (or Y) = Pause the Update driver job after the acquisition
phase.
Specifying any other value terminates the job. The absence of any
value causes the Update driver job to execute both the acquisition
phase and the application phase without pausing. This distributes
all rows sent to the Teradata Database during the acquisition phase
to their final destination on the AMPs.
TD_QUERY_BAND_SESS_INFO varchar Provides a user-defined query band expression that is set for every
SQL session connected by the Teradata PT driver. The following is
an example of a valid query band expression:
a=1; b=2; c=3; d=4;
If the TD_QUERY_BAND_SESS_INFO is set, the following request
will be sent by every SQL session connected by the Teradata PT
Update driver:
Setting the TD_QUERY_BAND_SESS_INFO attribute in jobs
running against non-supported versions of the Teradata Database
causes a non-fatal error. No error code is returned to the user
during initiation and the job is allowed to proceed. The log table
will not be dropped at the end of the job and the TD_Evt_ExitCode
event returns a warning value of four instead of the normal success
value of zero if queried. In this case, error information can be found
in the trace file.
TD_REPLICATION_OVERRIDE varchar Overrides the normal replication services controls. The default is
not to send any SET SESSI ON OVERRI DE REPLI CATI ON
statement to the database.
The following valid values are not case sensitive:
On = Sends SET SESSI ON OVERRI DE REPLI CATI ON ON
to the database. Normal replication services controls are
overridden.
Off = Sends SET SESSI ON OVERRI DE REPLI CATI ON
OFF to the database. Normal replication services controls are not
overridden.
For detailed information on replication services components, see
Teradata Replication Services Using Oracle GoldenGate and the SQL
Data Definition Language.
server name.
If you do not specify the value for the TdpId attribute, the driver
uses the default TdpId established for the user by the system
administrator.
TD_TENACITY_HOURS integer Specifies the number of hours that the Update driver attempts to log
on when the maximum number of load and export operations are
The default value is four hours. To enable the tenacity feature, the
hours value must be greater than zero.
Specifying a value of zero will disable the tenacity feature.
Specifying a value of less than zero terminates the Update driver.
TD_TENACITY_SLEEP integer Specifies the number of minutes the Update driver pauses before
retrying to log on when the maximum number of load and export
operations are already running on the Teradata Database.
The minutes value must be greater than zero. If you specify a value
less than one, the Update driver responds with an error message and
terminates the job.
Valid values are:
TD_TRACE_LEVEL
Note: The TraceLevel attribute is an
internal diagnostic aid. Use only if
instructed to by Teradata support.
TD_OFF should always be specified.
integer Specifies the types of diagnostic messages written by each instance
of the driver to an external log file. The diagnostic trace function
provides more detailed information (including the version number)
in the log file to aid in problem tracking and diagnosis.
Use the AddArray attribute method to specify the two types of
tracing levels: driver tracing and infrastructure tracing.
TD_OFF is the default setting for both driver tracing and
infrastructure tracing. No external log file is produced unless this
default is changed. Specifying TD_OFF for both driver tracing and
infrastructure tracing is the same as disabling tracing.
If the TraceLevel is set to any value other than TD_OFF, an external
log file is created for each instance of the driver.
activities.The absence of any value for the PauseAcq attribute
means that the Update driver job will execute both the
acquisition phase and the application phase without pausing.
This will distribute all of the rows that were sent to the Teradata
Database during the acquisition phase to their final destination
on the AMPs. Table 1 on page 41 lists which drivers have the
Pause Acquisition attribute.
TD_OPER_CLI = Activates the tracing function for
CLIv2-related activities (interaction with the Teradata Database).
TD_OPER_NOTIFY = Activates the tracing function for
activities related to the Notify feature.
TD_OPER_ALL = Activates tracing for all of the above activities.
The trace levels for infrastructure tracing should only be used when
you are directed to by Teradata support. TD_OFF, which disables
infrastructure tracing, should always be specified.
GetEvent Queries
GetEvent Queries
All events must be queried after the driver is initiated and before it is terminated. Events
queried before their data is available return TD_Unavailable. The following table lists events
used with the Connection objects GetEvent function to retrieve run time statistics from the
Update driver.
TD_TRACE_OUTPUT varchar Specifies the name of the external file used for tracing messages. The
default setting creates a new file name with the name of the driver
followed by a time stamp.
Note: If a file with the specified name already exists, the file is
overwritten.
TD_WORK_TABLE varchar Specifies the name of the work table. This must be a new table
name. You cannot use an existing table name unless you are
restarting a paused Update driver job.
If the name is not supplied, it is created by the Update driver. The
name of the created table is appended with an identifying
ttname_WT, ensuring uniqueness.
TD_WORKINGDATABASE varchar Specifies the name of the database used in a Teradata SQL
DATABASE statement that the Update driver sends to the Teradata
Database immediately after connecting the two SQL sessions. Use
this attribute to specify a default database other than the logon
database.
Table 17: Update Driver Events
TD_Evt_ApplyCount64 Three 8-byte unsigned integers: one 8-byte unsigned
integer for the number of rows inserted into the DBS,
followed by one 8-byte unsigned integer for the number
of rows updated, followed by one 8-byte unsigned integer
for the number of rows deleted.
Query this event after ApplyRows. For a multi-instance
job, only query these numbers in the master instance.
inserted, updated, and deleted to the target table from all
instances.
TD_Evt_CLIError One 4-byte integer for the CLIv2 error number and a 255
byte character buffer for the CLIv2 error text. Query this
event at any time.
GetEvent Queries
format the buffer required for block updating.
user environment and may be defined differently in
future releases. Always obtain these values from the event
TD_Evt_DBSError One 4-byte integer for the Teradata Database error
number and a 255 byte character buffer containing the
error text. This event can be queried at any time.
and any CLIv2 error number that occurred during the
connect process. Query this event at any time.
number of rows received, sent, and applied. Query this
event before EndAcquisition to get the current number
of rows received. However, the rest of the data for this
event is available only after ApplyRows.
that have been applied to the target table(s).
number of rows received, sent, and applied. Query this
event anytime before EndAcquisition to get the current
number of rows received. The rest of the data for this
event is available after ApplyRows.
Table 17: Update Driver Events (continued)
GetEvent Queries
TD_Evt_ApplyCount Three 4-byte unsigned integers corresponding to the
number of rows inserted, updated, and deleted. This
event must be called with a table index greater than or
equal to one to signify which target table the desired data
is for. Query this event after ApplyRows.
For a multi-instance job, only query this number in the
master instance.
applied to the target table from all instances.
error table 1. This event must be called with a table index
greater than or equal to one to signify the desired datas
target table. Query this event after ApplyRows.
error table 2. This event must be called with a table index
greater than or equal to one to signify the desired datas
target table. Query this event after ApplyRows.
TD_Evt_ExitCode One 2-byte integer for the exit code of the driver. Query
this event right before the driver terminates.
initiated.
checkpointed for the entire job. Query this event any
time after initiating a Teradata PT database connection
in a single-instance job. This event will return
instances are used.
not saved then the event data returned by this event can
The following information discusses the items you should consider when coding an Update
application.
Error Tables
The Update driver uses two error tables for each target table:
checkpointed for the entire job. Query this event anytime
after initiating a Teradata PT API database connection in
a single-instance job. This event will return
instances are used.
TD_Evt_Version A pointer to a character string containing the Teradata
PT version followed by a pointer to a character string
time. The operator version is available only after the
driver has been initiated.
Table 18: Update Driver Error Tables
Error Table Contents
ErrorTable1 = et1name Records rejected because of:
ErrorTable2 = et2name Records that violate the unique primary index
constraint.
Reusing Table Names
When an error table has one or more rows, it is not dropped from the Teradata Database at the
end of an Update driver job. Use the DROP TABLE statement from BTEQ to remove the tables
from the Teradata Database so that you can reuse the names specified for the error tables.
Limiting Insertion Errors
Use the TD_ERROR_LIMIT attribute to restrict the number of insertion errors captured in
the ErrorTable1 during the acquisition phase of an Update job.
The ErrorLimit specification applies to each instance of the Update driver, not to all instances
combined. For example, you set the limit to 10,000 rows. A single instance must detect that
10,000 rows were inserted into the first error table to terminate the job, and those 10,000 rows
must be controlled by the sessions managed by that instance.
If you expect no errors in the input data, set the error limit value to one. In this case, the job
terminates when any record causes an error. However, when the specified error limit is
reached, the Update driver continues processing until each session completes its current data
block. This continued processing can cause the total number of error rows captured in the first
error table to exceed the ErrorLimit specification.
DELETE is a Teradata SQL statement that removes rows from a table or view that was
previously identified as a target table through the use of the TD_TARGET_TABLE attribute.
The rules for using the DELETE statement in an Update import tasks are:
Apply the DELETE statements to either a table or a view, provided that the view does not
specify a join
The number of input data records is unlimited
The equality values must be specified for all the primary index columns in the WHERE
clause of a DELETE statement. Greater than and Less than operators cannot be used to
specify a range of rows.
Do not use the OR construct in the WHERE clause of a DELETE statement. Instead, use
two separate DELETE statements.
The procedure for using the DELETE statement in an Update import task is:
1 Add a DELETE statement to a DML group
2 Add the DML group to the Connection object
3 initiate the Connection object
Table 19: Update Driver ERRORLIMIT Values
IF you expect your Update job to encounter... THEN specify an ERRORLIMIT value that is...
4 Set the DML group containing the DELETE statement using the UseDMLGroups function
Note: If the DML group only contains a DELETE statement, then no data will be loaded as
a result of the PutRow function call.
5 Make at least one call to the PutRow function
6 Call the ApplyRows function
7 Terminate the Connection object
Note: If no row in the target table matches the DELETE statement, then the row of data sent
with the DELETE statement will be put into the application error table.
Using Delete Task
Use the Update drivers Delete Task with or without variable substitution. If variable
substitution is used, the Update driver requires a schema. The following sections give an
overview of the steps needed to use the Update Delete Task.
Using DELETE in Delete Tasks
Deleting rows in a Delete Task is faster than deleting rows in an import task. The rules for
using the DELETE statement in Delete tasks are:
Only one special session can be connected
Only one instance may be specified
Only one DML group may be specified
Only one DML statement in the DML group may be specified
Only one target table may be specified
The first error table is not used and is ignored
Only one data record is provided if using variable substitution in the WHERE clause.
There can be no calls to the EndAcquisition function.
The procedure for using the Update Delete Task without variable substitution is:
1 Set the TD_DELETE_TASK attribute to Yes
2 Add one DELETE statement to a DML group
4 Initiate the Connection object
5 call the ApplyRows function
Note: Do not add a schema to the Connection object.
The procedure for using the Update Delete Task with variable substitution is:
1 Set the TD_DELETE_TASK attribute to Yes
2 Add the schema corresponding to the variable substitution to the Connection object.
3 Add one DELETE statement to a DML group
6 Use PutRow to pass in variable substitution data (one call only)
7 call the ApplyRows function
Some tables are created during the execution of a job, but others must be created by you
before the job begins. Target tables must exist on the Teradata Database when an Update
driver job is executed. The log table is created automatically when you run the Update job
script. Error tables and work tables are created by the Teradata Database. Error tables are
dropped by the Update driver during the cleanup phase if no errors were detected during the
acquisition phase or the application phase. The work table is dropped by the Update driver
during the cleanup phase if no errors were detected during the acquisition or the application
phase. The log table is dropped by the Update driver after the job completes successfully.
When a job terminates abnormally, the log, error, and work tables may not be dropped
depending on where in the job the termination occurred. If you want to restart the job from
the beginning, you need to manually drop these tables by running a BTEQ script.
Caution: Care must be taken when you manually drop the target tables using a BTEQ script. If
something goes wrong with an Update job and you drop the target tables manually, when you
try to rerun the job, you may lose the original data. Because all rows are held in work tables
until the Update job reaches the application phase (when they are copied to the target tables),
you risk losing the original data.
Required Privileges
The user ID used by the Update driver to connect to the Teradata Database must have:
SELECT and INSERT privileges on the Update target table
SELECT and INSERT privileges on the error tables
DROP privileges on the database that contains the error tables.
SELECT, INSERT, and DELETE privileges on the restart log table
DROP privileges on the database that contains the restart log table.
Session Limits
The values you specify with the Update drivers TD_MIN_SESSIONS and
TD_MAX_SESSIONS attributes are not the only factors limiting the number of sessions the
Update driver can establish with the Teradata Database. When the Update driver executes, the
actual session limit is determined by whichever limiting factor is encountered first.
The Teradata Database limit of one session per AMP. This value is defined in the COP
Interface software file, CLISPB.DAT, under the max_num_sess variable. You can use the
TDP SET MAXSESSIONS command to specify a platform limit. The default TDP
MAXSESS value is 1024 sessions.
The limit of the network protocol software on network-attached systems.
Offline AMPs
The impact of offline AMPs on the Update driver depends on:
The number of offline AMPs in a cluster, either logically or physically
The operational phase of the Update tasks when the offline AMP condition occurs
Whether the target tables are fallback or nonfallback
The table below describes the impact of offline AMPs on Update driver tasks on fallback and
nonfallback tables.
Nonparticipant AMPs
There are three ways for an AMP to become nonparticipant for an Update driver task:
Table 20: Offline AMP Conditions and Effects on Update Driver Tasks
If... And... Then...
All of the target
tables are fallback
Not more than one
AMP is offline
Update driver tasks continue to run as long as
there is not more than one AMP offline in a
cluster, either logically or physically.
The offline AMP does not participate in the
application phase if:
The AMP goes offline before the Update
tasks enter the application phase, and the
AmpCheck attribute is set to None.
Certain I/O errors occur during the
application phase.
Two or more AMPs are
offline
Update driver tasks do not run or terminate if
two or more AMPs are offline in a cluster, either
logically or physically.
Note: In the application phase, if AMPs are
offline to the extent that data on the disk is
corrupted, then you must restore the affected
tables.
One or more of the
target tables is
nonfallback
One or more AMPs are
offline
Update driver tasks terminate and you cannot
restart until all of the AMPs are online.
Note: The Update driver also terminates if
I/O errors corrupt the target tables in the
application phase.
The Update driver treats a nonparticipant AMP as if it is an offline AMP. The Update driver
does not execute if a cluster has any combination of more than one AMP that is:
Offline
Nonparticipant
If more than one AMP in a cluster becomes a nonparticipant during the application phase, the
Update driver tasks do not continue; the target tables are considered unusable, and must be
recovered from archives.
Single-AMP Systems
The Update driver cannot run on a single-AMP Teradata Database system or on a multi-AMP
system configured with single-AMP clusters. Any attempt to run the Update driver in this
environment causes the Teradata Database to immediately reject the request, abort the job,
and issue a diagnostic message stating that a single-AMP system is not supported.
Always estimate the final size of the Update target table, and make sure the destination
database on the Teradata Database has enough space to accommodate the Update job. If the
database that owns the Update target table, log table, error tables, or work table runs out of
space, the Teradata Database returns an error message and the Update driver pauses the
Update job. When this happens, you must allocate more space to the database before you can
restart the job.
Table 21: Nonparticipant AMP Conditions and Effects on Update Driver Tasks
When...
Then the associated AMP becomes a
nonparticipant...
Any AMP is down at the end of the acquisition
phase or the beginning of the application phase
If the TD_AMP_CHECK None option is
specified. Because the Update driver does not
run after the acquisition phase if an AMP is
offline and the target table is nonfallback, an
AMP can become a nonparticipant only if the
target table is defined as having fallback
protection. The TD_AMP_CHECK Apply and
All options would prevent the occurrence of
nonparticipant AMPs in this situation.
I/O errors occur in certain Update driver tables
during the application phase, a head/disk
assembly (HDA) fails during the application
phase
When the I/O recovery operation stops the
Update task.
A head/disk assembly (HDA) fails during the
application phase
But it returns after the disk is replaced and the
Disk Copy and Table Rebuild utilities are run.
Code Example
The Update driver is fully checkpoint restartable. See the checkpoint and restart discussion in
Code Example
cout << "*** Updat e Dr i ver Exampl e ***" << endl ;
/ **********************************************
**********************************************/
conn- >AddAt t r i but e( TD_SYSTEM_OPERATOR, TD_UPDATE) ;
/ / conn- >AddAt t r i but e( TD_TRACE_OUTPUT, " updat e. t xt " ) ;
/ / conn- >AddAr r ayAt t r i but e( TD_TRACE_LEVEL, 2, TD_OPER_ALL, TD_OFF, NULL) ;
/ **********************************************
**********************************************/
conn- >AddAt t r i but e( TD_USER_NAME, "user " ) ;
conn- >AddAt t r i but e( TD_LOG_TABLE, "t dupdat e_l og" ) ;
conn- >AddAr r ayAt t r i but e( TD_TARGET_TABLE, 2, " t dupdat eA" , " t dupdat eB" , NULL) ;
conn- >AddAr r ayAt t r i but e( TD_WORK_TABLE , 2, " t dupdat eA_wt " , " t dupdat eB_wt " , NULL) ;
conn- >AddAr r ayAt t r i but e( TD_ERROR_TABLE_1, 2, " t dupdat eA_e1" , " t dupdat eB_e1" , NULL) ;
conn- >AddAr r ayAt t r i but e( TD_ERROR_TABLE_2, 2, " t dupdat eA_e2" , " t dupdat eB_e2" , NULL) ;
/ **********************************************
* Add Schema
**********************************************/
schema- >AddCol umn( " Mar t i al _St at us" , TD_CHAR, 1) ;
/ **********************************************
* Set DMLGr oups
**********************************************/
TD_I ndex dml Gr oupI ndex[ 2] ;
dml Gr - >AddSt at ement ( " I NSERT I NTO t dupdat eA( : Associ at e_I d, : Associ at e_Name, : Sal ar y,
dml Gr - >AddDMLOpt i on( MARK_DUPLI CATE_ROWS) ;
r et ur nVal ue = conn- >AddDMLGr oup( dml Gr , &dml Gr oupI ndex[ 0] ) ;
del et e dml Gr ;
dml Gr = new DMLGr oup( ) ;
dml Gr - >AddSt at ement ( " I NSERT I NTO t dupdat eB( : Associ at e_I d, : Associ at e_Name, : Sal ar y,
dml Gr - >AddDMLOpt i on( I GNORE_DUPLI CATE_ROWS) ;
r et ur nVal ue = conn- >AddDMLGr oup( dml Gr , &dml Gr oupI ndex[ 1] ) ;
del et e dml Gr ;
cout << "DMLGr oups added wi t h st at us " << r et ur nVal ue << endl ;
{
Code Example
/ **********************************************
* I ni t i at e
**********************************************/
cout << " Dr i ver I ni t i at ed wi t h st at us " << r et ur nVal ue << endl ;
{
/ **********************************************
* Acqui si t i on
**********************************************/
TD_Lengt h byt es;
/ / Get A Row of Dat a f or I nser t i on
l oadSt at us = Get RowDat a( r owBuf f er , 78) ; / / user f unct i on - r eads i n a
/ / r eached
i f ( l oadSt at us ! = - 1 ) {
/ / I nser t t he r ow t wi ce usi ng each DML gr oup
f or ( i nt i = 0; i < 2 ; i ++ ) {
r et ur nVal ue = conn- >UseDMLGr oups( &dml Gr oupI ndex[ i ] , 1) ;
i f ( r et ur nVal ue >= TD_Er r or ) {
br eak;
}
cout << " Sendi ng Fi r st Row" << endl ;
br eak;
}
cout << " Sendi ng Dupl i cat e Row" << endl ;
br eak;
}
}
}
cout << " Rows sent wi t h st at us " << r et ur nVal ue << endl ;
l oadSt at us = Get RowDat a( NULL, 0) ; / / user f unct i on - cl ose f i l e
{
/ **********************************************
**********************************************/
cout << " Acqui si t i on compl et ed wi t h st at us " << r et ur nVal ue << endl ;
{
/ **********************************************
* Appl i cat i on
**********************************************/
r et ur nVal ue = conn- >Appl yRows( ) ;
cout << " Appl i cat i on compl et ed wi t h st at us " << r et ur nVal ue << endl ;
{
cout << " Updat e compl et ed successf ul l y" << endl ;
Code Example
}el se{
}el se{
}
}
}el se{
}el se{
}
}
}el se{
cout << " Er r or occur ed dur i ng Acqui si t i on" << endl ;
}el se{
}
}
}el se{
cout << "Er r or occur ed dur i ng I ni t i at e" << endl ;
}el se{
}
}
}el se{
cout << "Er r or occur ed dur i ng AddDMLGr oups" << endl ;
}el se{
}
}
/ **********************************************
* Ter mi nat e
**********************************************/
{
}el se{
}
}
/ **********************************************
* Cl ean Up
Code Example
**********************************************/
cout << "Del et i ng Obj ect s" << endl ;
del et e schema;
del et e conn;
cout << "*** Updat e Compl et e ***" << endl ;
Code Example
CHAPTER 5
Stream Driver
The Stream driver uses Teradata TPump protocol to perform high-speed DML transactions in
a near-real-time mode on tables while the tables are being queried.
Using multiple sessions to load data, the Stream driver allows parallel inserts, updates, deletes,
and upserts to empty or preexisting Teradata Database tables.
The Stream driver provides an alternative to the Update driver for the maintenance of large
databases under control of a Teradata Database. Unlike the Update driver, the Stream driver
allows access to the database and does not lock the target tables being updated so that
interactive read and write activities can be performed concurrently.
The Stream driver also uses standard SQL/DML to maintain data in up to 128 tables at a time.
Row level locking, as used in the Stream driver SQL transactions, allows constant load
operations in the background during normal system use without locking target tables. It has
the same restart ability, portability, and scalability as the Update driver. Learn more about the
Stream driver in this chapters main sections:
Required attributes are listed in Table 22, and optional attributes are defined in Table 23.
Required Attributes
Optional Attributes
GetEvent Queries
Error Tables
Reusing Stream Driver Table Names
Limiting Errors in the Stream Driver
Required Privileges
Session Limits
Obtaining the Row Count Using
TD_Evt_ApplyCount
Tuning the Pack Factor
Stream Driver Macro Support
Code Example
Chapter 5: Stream Driver
Required Attributes
Table 22: Stream Driver Required Attributes
TD_BUFFER_MODE varchar Indicates which type of Stream method is used.
Valid Settings:
Must be set to Yes when using the block Stream
feature.
TD_INSTANCE_NUM integer Provides the instance number of the current
instance. Required when using multiple instances
of the same driver in a master-slave environment.
If the current instance is the master instance,
then the instance number should be one.
If the current instance is a slave instance, then
the instance number should be a value greater
than one.
TD_LOG_TABLE varchar Provides the name of the restart log table for
restart information. Each Stream driver job needs
to use its own restart log table if multiple Stream
driver jobs are executed concurrently.
Note: If the restart log table name is not fully
qualified, it is created under the users default
(logon) database. Alternately, a working database
can be specified using the
TD_WORKINGDATABASE attribute. If the
TD_WORKINGDATABASE attribute is used, the
restart log table name must be fully qualified,
even if the restart log table is going to reside in the
TD_MAX_INSTANCES integer Provides the total number of instances (master
and slaves). Required when using multiple
instances of the same driver in a master-slave
environment.
TD_RESTARTMODE integer Required only before restarting and must be set to
one before performing a restart.
TD_SYSTEM_OPERATOR varchar Specifies the type of driver being used (in this case
TD_STREAM).
TD_USER_NAME varchar Provides the name of the user for the Stream
driver logon sessions.
TD_USER_PASSWORD varchar Specifies the password associated with the user
name.
Optional Attributes
Table 23: Stream Driver Optional Attributes
TD_ACCOUNT_ID varchar Specifies the account associated with the
specified user name. When omitted, this
attribute defaults to the account identifier of the
TD_AUTORESTART varchar Teradata PT APT notifies the user application,
once Teradata Database restarts, that the
database crashed.
Valid values are:
Yes (Y) = The user application receives a
response about the database crash once thee
database is online (default).
No (N) = The user application receives the
CLI 220 error message when the database is
down during the acquisition phase of
Teradata PT API.
TD_APPENDERRORTABLE varchar Directs the Stream driver to use the existing
error table that is specified in the
TD_ERROR_TABLE attribute. By default, if the
specified error table already exists, the Stream
driver terminates the job with an error message.
Note: Set the Stream drivers
TD_DROPERRORTABLE attribute to align the
Stream driver default setting.
Valid values are:
No (N) = Do not use the existing error
table. This is the default setting.
Yes (Y) = Use the existing error table. The
Stream driver will create the error table if the
error table does not exist. If the error table
does exist, the Stream driver will display the
number of rows already in the error table in
the trace file for the job if one exists (see
TD_TRACE_LEVEL on page 128 and
TD_TRACE_OUTPUT on page 129). If
the structure of the existing error table is not
compatible with the error table the Stream
driver creates, the job terminates with an
error message at the first attempt to insert or
update to the existing error table.
TD_ARRAYSUPPORT varchar Specifies default array support option for all
DMLGroups. Each DMLGroup can modify this
setting through the AddArraySupport
function.
Valid values are:
On = Array support is turned on. This is the
default setting if the Teradata Database
supports the array support functionality. An
error will be returned and the job terminated
if Array support is turned on for a Teradata
Database that does not support this feature.
Off = Array support is turned off. This is the
default setting if the Teradata Database does
not support the array support functionality.
Note: Performance will improve when Array
Support is enabled.
TD_BUFFERS integer Specifies whether to increase the number of
request buffers.
The range of values has a lower limit of two and
no upper limit. The default value is three.
The maximum number of request buffers you
can allocate is the number of buffers multiplied
by the number of connected sessions.
Because request buffers are a global resource,
buffers are assigned to any session as needed
and then returned to a free pool.
At any point in time, the number of request
buffers assigned to a session can vary from zero
to the maximum number you allocate.
TD_CHARSET varchar Specifies the name or code of the character set
to be used for the job. On channel-attached z/
OS platforms, only EBCDIC encoding is
supported and is automatically selected.
For the list of supported character sets, see
Extended Character Sets in Teradata Parallel
TD_DATA_ENCRYPTION varchar Provides full security encryption of SQL
requests, responses and data.
Valid values are:
Off = No encryption occurs. This is the
default setting.
On = All SQL requests, responses, and data
are encrypted.
Table 23: Stream Driver Optional Attributes (continued)
TD_DATE_FORM varchar Specifies the DATE data type for the Stream
driver job.
Valid settings are:
IntegerDate = Integer DATE data type. This is
the default setting.
ANSIDate = ANSI fixed-length CHAR(10)
DATE data type.
TD_DROPERRORTABLE varchar Directs the Stream driver to drop the existing
error table at the end of the job. By default, the
Stream driver drops the error table at the end of
a job if the error table is empty.
Note: Use the TD_APPENDERRORTABLE
attribute to direct the Stream driver to continue
using the existing error table.
Valid values are:
Yes (Y) = Drop the error table if it is empty
at the end of the job. This is the default
setting.
No (N) = Do not drop the existing error
table.
TD_DROPMACRO varchar Specifies whether to keep or drop the macro
created during the current Stream job.
Valid values are:
Yes (Y) = Drop the macro. This is the
default setting.
No (N) = Keep the macro.
TD_ERROR_LIMIT integer Specifies the maximum number of records
stored in one of the error tables before the
Stream driver job is terminated. By default, the
ErrorLimit value is unlimited.
The ErrorLimit specification must be greater
than zero.
Specifying an invalid value terminates the
Stream driver.
The ErrorLimit specification applies to each
instance of the Stream driver.
TD_ERROR_TABLE varchar Specifies the name of the error table. ErrorTable
must be a new table name. You cannot use the
name of an existing table unless you are
restarting a Stream driver job. If the name is not
supplied, it will be created by the Stream driver.
The Error Table contains information
concerning:
and other error conditions
It is acceptable, and even good practice, to
prefix the error table with a database name as a
qualifier. This means that because the database
may have a lot of PERM space, which space will
not have to be increased for all databases with
tables involved in the load.
If the database for the error table is not
specified, the table is placed in the database
associated with the user logon.
See Reading TPump Error Tables in Teradata
Parallel Data Pump Reference for information
on the error table format and the procedure to
correct errors.
TD_LOGON_MECH varchar Specifies which logon mechanism is used.
See your site security administrator for
specific mechanism names. For a list of
available mechanisms, see Security
Administration.
The job terminates if the attribute exceeds
eight bytes.
TD_LOGON_MECH_DATA varchar Passes along additional logon mechanism data.
See your site security administrator for specific
mechanism data. For more information, see
Security Administration.
TD_LOGSQL varchar Directs the Stream driver to output the full
Teradata SQL request in the trace output file
with the drivers trace is enabled. By default,
when the drivers trace is enabled, the Stream
driver outputs the Teradata SQL request, up to
32 kilobytes, in the trace output file.
Valid values:
Yes ('Y') = Output the full Teradata SQL in
the trace output file when the drivers trace is
enabled. The maximum length of the
No ('N') = Do not output the Teradata SQL
in the trace output file.
Note: When the drivers trace is disabled,

TD_LOGSQL has no effect.
TD_MACROCHARSET varchar Enables or disables the MacroCharSet feature. If
the TD_MACROCHARSET attribute is
enabled, you can specify the column
MacroCharSet name for character columns. The
value is discarded for other column types.
Valid values:
Yes ('Y') = Enables the MacroCharSet feature
No ('N') = Disables the MacroCharSet
feature
For syntax to enable TD_MACROCHARSET
and the AddColumn syntax when
TD_MACROCHARSET is enabled, see Using
the MacroCharSet Feature on page 140.
TD_MACRODATABASE varchar Specifies the database that contains any macros
used by the Stream driver. The default macro
database is the restart log table database.
TD_MAX_SESSIONS integer Specifies the maximum number of sessions to
log on. The default is one session per available
AMP. The maximum value cannot be more than
the number of AMPS available.
The MaxSessions value must be greater than
zero. Specifying a value less than one causes the
job to terminate.
The MaxSessions value must be greater than or
equal to the value of TD_MAX_INSTANCES.
TD_MIN_SESSIONS integer Specifies the minimum number of sessions
required for the Stream driver job to continue.
The default is one session.
The MinSessions value must be greater than
zero and less than or equal to the maximum
number of Stream driver sessions. Specifying a
value less than one terminates the Stream driver.
TD_MSG_ENCODING TD_
Encoding
Specifies the encoding for the messages passed
between Teradata PT and a Teradata PT
application.
TD_NOTIFY_EXIT varchar Specifies the name of the user-defined notify
exit routine with an entry point named
_dynamn.
If no name is supplied, the following default
names are used:
libnotfyext.so for Linux and all other UNIX
platforms
For detailed information on the Notify feature,
see Stream Operator in Teradata Parallel
TD_NOTIFY_LEVEL varchar Indicates the level at which certain events are
reported.
Off = No notification of events will be
provided. This is the default setting.
Low = Notification is provided for these
events:
Initialize
CLIv2/DBS error
Exit
Medium = Notification is provided for all the
events except:
Checkpoint Begin
Import Begin
Import End
Error Table
Checkpoint End
Interim Run Statistics
High = Notification is provided for all
events.
TD_NOTIFY_METHOD varchar Indicates the method used for reporting events.
The methods are:
None = No event logging is done. This is the
default method.
Exit = This method sends the events to a
user-defined notify exit routine and to the
system log.
On Windows, the events are sent to the
EventLog that can be viewed using the Event
Viewer. The messages are sent to the
application log.
On AIX, HP-UX, Linux, and Solaris
platforms, the destination of the events is
dependent upon the setting specified in the
file called /etc/syslog.conf.
TD_NOTIFY_STRING varchar Provides a user-defined string to precede all
messages sent to the system log. This string is
also sent to the user-defined notify exit routine.
TD_PACK integer Specifies the number of statements to pack into
a multiple-statement request. The default value
is 20. The maximum value is 600.
TD_PACKMAXIMUM varchar Triggers the Stream driver to dynamically
determine the maximum possible pack factor
for the current Stream job.
Valid values are:
No (or N) Use the default pack factor. This is
the default setting.
Yes (or Y) Determine maximum possible
pack factor.
TD_PERIODICITY integer Specifies that the DML statements sent by the
Stream driver to the Teradata Database be as
evenly distributed as possible over each one
minute interval. The periodicity value sets the
number of sub-intervals per minute. The TPT
API user needs to pass the user's command for
the Periodicity option to TPT API. TPT API
needs to pass the user's command to the Stream
driver.
For example, if the rate is 1600 and the
periodicity is 10, then the maximum number of
statements submitted is 160 (1600/10) every 6
(60/10) seconds.
Valid values are between 1 and 600. The default
value is 4, that is, four 15-second intervals per
minute. If the statement rate is unlimited, the
periodicity value is ignored.
TD_QUERY_BAND_SESS_INFO varchar Provides a user-defined query band expression
that is set for every SQL session connected by
the Teradata PT driver. The following is an
example of a valid query band expression:
a=1; b=2; c=3; d=4;
If the TD_QUERY_BAND_SESS_INFO is set,
the following request will be sent by every SQL
session connected by the Teradata PT Stream
driver:
SET QUERY_BAND = <User-Defined
Query Band Expression> FOR
SESSI ON;
Setting the TD_QUERY_BAND_SESS_INFO
attribute in jobs running against non-supported
versions of the Teradata Database causes a non-
fatal error. No error code is returned to the user
during initiation and the job is allowed to
proceed. The log table will not be dropped at
the end of the job and the TD_Evt_ExitCode
event returns a warning value of four instead of
the normal success value of zero if queried. In
this case, error information can be found in the
trace file.
TD_RATE integer
character
Specifies the maximum number of DML
statements per minute that the Stream driver
can submit to the Teradata Database per
minute. The user needs to pass the command
for the Rate option to TPT API. TPT API needs
to pass the user command to the Stream driver.
When a job step contains multiple occurrences
of the Stream driver with differing Rate values,
Teradata PT automatically uses the lowest Rate
value for all instances.
Values for TD_RATE must be one of the
following:
Integer value > zero
Character string value 'unlimited' (default)
'unlimited' tells the Stream driver to send as
many DML statements to the Teradata
Database as the user specified.
TD_REPLICATION_OVERRIDE varchar Overrides the normal replication services
controls. The default is not to send any SET
SESSI ON OVERRI DE REPLI CATI ON
statement to the database.
The following valid values are not case sensitive:
On = Sends SET SESSI ON OVERRI DE
REPLI CATI ON ONto the database.
Normal replication services controls are
overridden.
Off = Sends SET SESSI ON OVERRI DE
REPLI CATI ON OFF to the database.
Normal replication services controls are not
overridden.
For detailed information on replication services
components, see Teradata Replication Services
Using Oracle GoldenGate and SQL Data
Definition Language.
TD_ROBUST varchar Specifies whether or not to use robust restart
logic for recovery and restart operations.
In robust mode, one database row is written in
the log restart table for every request issued.
These rows are the request log. Because the
Teradata Database completely finishes or rolls
back, a the request log always accurately reflects
the completion status of an import.
Valid values are:
Yes (or Y) = Use robust restart logic. This is
the default setting. In the robust mode, a
number of partial checkpoint rows are
written to the request log between
checkpoints for each packed request. The
rows are deleted each time a checkpoint is
written.
In Robust recovery mode, the Stream driver
must next ascertain how much processing
has been completed since the last logged
checkpoint. This is accomplished by reading
back a set of Partial Checkpoints from the
Teradata Database, sorting them and then
reprocessing all transactions that were left
incomplete when the job was interrupted.
No (or N) = Use simple restart logic. Restarts
begin where the last checkpoint occurred in
the job. Any processing completed after that
checkpoint is redone, which could lead to
duplicate rows being sent to the target table.
This method eliminates the extra overhead
of the additional database writes used in the
robust mode, and it is adequate for DML
statements that can be repeated without
changing the results of the operation.
If you are not sure about using robust restart
logic, it is always safe to set the robust attribute
to Yes.
TD_TDP_ID varchar Specifies the name of the Teradata Database
machine.
The dbcname can be up to 256 characters
and can be a domain server name.
TDP stands for Teradata Director Program
and is specified for mainframe z/OS
platforms.
If you do not specify a value for the
TD_TDP_ID attribute, the Stream driver
uses the default TDPID established for the
user by the system administrator.
TD_TENACITY_HOURS integer Specifies the number of hours that the Stream
driver continues trying to log on when the
maximum number of load and export
operations are already running on the Teradata
Database.
The default value is four hours. To enable the
tenacity feature, the hours value must be
greater than zero.
Specifying a value of zero will disable the
tenacity feature.
Specifying a value of less than zero will cause
the Stream driver to terminate.
TD_TENACITY_SLEEP integer Specifies the number of minutes that the Stream
driver pauses before retrying to log on when the
maximum number of load and export
operations are already running on the Teradata
Database.
The minutes value must be greater than zero.
If you specify a value less than one, the
Stream driver responds with an error
message and terminates the job.
Valid values are:
Y]es] = enables sending events to TMSM
(default)
TD_TRACE_LEVEL
TD_OFF should always be
specified.
integer Specifies the types of diagnostic messages
written by each instance of the driver to an
external log file. The diagnostic trace function
provides more detailed information in the log
file (including the version number) to aid in
problem tracking and diagnosis.
Use the AddArray attribute method to specify
the two types of tracing levels: driver tracing
and infrastructure tracing.
TD_OFF is the default setting for both driver
tracing and infrastructure tracing. No external
log file is produced unless this default is
changed. Specifying TD_OFF for both driver
tracing and infrastructure tracing is the same as
disabling tracing. If the TraceLevel is set to any
value other than TD_OFF, an external log file is
created for each instance of the driver.
TD_OPER = Activates the tracing function
for driver specific activities.The absence of
any value for the PauseAcq attribute means
that the Stream driver job will execute both
the acquisition phase and the application
phase without pausing. This will distribute
all of the rows that were sent to the Teradata
Database during the acquisition phase to
their final destination on the AMPs. Table 1
on page 41 lists which drivers have the Pause
Acquisition attribute.
TD_OPER_CLI = Activates the tracing
function for CLIv2-related activities
(interaction with the Teradata Database).
TD_OPER_NOTIFY = Activates the tracing
function for activities related to the Notify
feature.
TD_OPER_OPCOMMON = Activates the
tracing function for activities involving the
opcommon library.
TD_OPER_ALL = Activates tracing for all of
the above activities.
The trace levels for infrastructure tracing should
only be used when you are directed to by
Teradata support. TD_OFF, which disables
infrastructure tracing, should always be
specified.
GetEvent Queries
GetEvent Queries
All events must be queried after the driver has initiated and before it has terminated. Events
queried before their data is available return TD_Unavailable.
The following table lists events that may be used with the Connection objects GetEvent
function to retrieve run time statistics from the Stream driver.
TD_TRACE_OUTPUT varchar Specifies the name of the external file to use for
tracing messages.
The default setting creates a new file name with
the name of the driver followed by a time stamp.
Note: If a file with the specified name already
exists then the file will be overwritten.
TD_WORKINGDATABASE varchar Specifies the name of the database used in a
Teradata SQL DATABASE statement that the
Stream driver sends to the Teradata Database
immediately after connecting the two SQL
sessions. Use this attribute to specify a default
database other than the logon database.
GetEvent Queries
Table 24: Stream Driver Events
TD_Evt_ApplyCount A buffer containing the concatenation of these fields in
the following order:
1 a 4-byte unsigned integer that represents the statement
number in the DML Group.
2 a 1-byte character that represents the type of DML
statement. Valid values are I (insert), U (update), or D
(delete).
3 a 4-byte unsigned integer representing the length of
the database name in bytes.
4 n -byte character string for the database name (where
n is the length of the database name in bytes).
5 a 4-byte unsigned integer representing the length of
the table or macro name.
6 n-byte character string for the table or macro name
(where n is the length of the table or macro name in
bytes).
7 a 4-byte unsigned integer for the number of rows
inserted, updated, or deleted. If the type was I (see field
2) then this number is the number of rows inserted.
For more information on using TD_Evt_ApplyCount to
get the number of rows inserted, updated, or deleted for
each DML Group in the job, see Obtaining the Row
Count Using TD_Evt_ApplyCount on page 137.
event at any time.
format the buffer required for block streaming.
user environment and may be defined differently in future
releases. Always obtain these values from the event
TD_Evt_DBSError One 4-byte integer for the DBS error number and a 255
byte character buffer for the DBS error text. Query this
event at any time.
sessions requested, the number of sessions connected, and
any CLIv2 error number that may have occurred during
the connect process. Query this event at any time.
GetEvent Queries
TD_Evt_PackFactor A pointer to an integer containing the value of the pack
factor.
Query this event only after initiating connection and
before terminating a connection to return the pack factor
for the Stream driver.
initiated.
number of rows received, rows sent, and rows that caused
DBS errors. Query this event before EndAcquisition to get
the current number of rows received. The rest of the data
for this event, however, will only be available after
EndAcquisition.
can be queried anytime before EndAcquisition to get the
this event is available after ApplyRows.
TD_Evt_Runstats Five 4-byte unsigned integers corresponding to the
number of SQL statements sent to the DBS, requests sent
to the DBS, rows received, rows sent, and rows that caused
DBS errors. Query this event before EndAcquisition to get
the current number of rows received. The rest of the data
for this event, however, will only be available after
EndAcquisition.
TD_Evt_RunStats64 Five 8-byte unsigned integers corresponding to the
number of SQL statements sent to the Teradata Database,
the requests sent to the Teradata Database, the rows
received, the rows sent, and the rows that caused Teradata
Database errors. Query this event before EndAcquisition
to get the current number of rows received. The rest of the
data for this event, however, will only be available after
EndAcquisition.
Table 24: Stream Driver Events (continued)
GetEvent Queries
PutRow or PutBuffer.
TD_Evt_ErrorTable1_64 One 8-byte unsigned integer for the number of rows in
PutRow or PutBuffer
TD_Evt_ExitCode One 2-byte integer for the exit code of the driver. Query
this event right before the driver terminates.
number of rows that have been received and checkpointed
for the entire job. Query this event any time after
initiating a Teradata PT database connection in a single-
instance job. This event will return TD_Unavailable when
queried in a job containing multiple instances; this event
is invalid if multiple instances are used.
is recommended to save the checkpoint data from the last
successful call to the CheckPoint method in a potential
restart job. However, if the checkpoint data is not saved
then the event data returned by this event can be passed
into the Restart method instead. This alternate method of
performing checkpoint/restarts will only work with
single-instance jobs.
number of rows that have been received and checkpointed
for the entire job. Query this event anytime after initiating
a Teradata PT API database connection in a single-
instance job. This event will return TD_Unavailable when
queried in a job containing multiple instances; this event
is invalid if multiple instances are used.
TD_Evt_Version A pointer to a character string containing the Teradata PT
version followed by a pointer to a character string
PutEvent Modifiers
PutEvent Modifiers
All PutEvent modifiers must be used after the Stream driver has initiated and before it has
terminated. TD_Unavailable is returned when a modifier cannot be used.
The following table lists modifiers that are used with the PutEvent function of the Connection
object to modify the Rate and Periodicity values of the Stream driver in the middle of the
stream job.
TD_Evt_MacroNames Returns a block of data for each statement in the DML
group. The block of data for each DML statement
contains a 4-byte unsigned integer representing the length
of the macro name, and n 1-byte characters of the macro
name(n is length of macro name).
To return the macro names for the Stream driver, query
this event after initiating a connection and before
terminating the connection.
The following information discusses special topics to consider when coding a Stream
application.
Stream Driver Private Logs for TD_Evt_UserCommand
Example 1
When the user provides a valid user command to change the rate and periodicity, the Stream
driver displays the following message in the private log for the Stream driver:
" New Rat e: %d st at ement s per Mi nut e" " New Per i odi ci t y: %d per Mi nut e"
as shown below:
Table 25: Stream Driver PutEvent Modifiers
Event Expected Input Data
TD_Evt_UserCommand A character buffer containing 9 bytes of data used to pass
the user command.
User Command Syntax
RATE=value
where value must be an integer greater than 0 or
unlimited (for character-string).
PERIODICITY=value
where value must be an integer between 0 and 600.
RATE=value, PERIODICITY=value
PERIODICITY=value, RATE=value
The commands and values are case-insensitive.
Invalid user commands or specified values:
RATE=unknown
RATE=0
RATE=-1
PERIODICITY=0
PERIODICITY=-1
PERIODICITY=600
PERIODICITY=601
Invalid multiple RATE or PERIODICITY commands:
RATE=10, RATE=200
PERIODICITY=10, PERIODICITY=20
For usage examples of the TD_Evt_UserCommand, see
Stream Driver Private Logs for TD_Evt_UserCommand
on page 134.
PARSI NGUSERCOMMAND: pCmd: ' RATE = 200, PERI ODI CI TY = 9' STREAM_OPERATOR:
New Rat e: 200 st at ement s per Mi nut e **** 13: 33: 40 New Rat e: 200
st at ement s per Mi nut e STREAM_OPERATOR: New Per i odi ci t y: 9 per Mi nut e
**** 13: 33: 40 New Per i odi ci t y: 9 per Mi nut e
Example 2
When the user provides an error in the user command, the Stream driver ignores the
command, displays an error message in the private log for the Stream driver, and continues
the job with the previous Rate and Periodicity values, as shown below in the following sample
private logs:
PARSI NGUSERCOMMAND: pCmd: ' RATE = - 10, PERI ODI CI TY = 15' STREAM_OPERATOR:
I nval i d Rat e at t r i but e val ue ( - 10) . Command i s i gnor ed. STREAM_OPERATOR:
Cont i nui ng wi t h Rat e: 200 st at ement s per Mi nut e STREAM_OPERATOR:
Cont i nui ng wi t h Per i odi ci t y: 9 per Mi nut e
===================================
PARSI NGUSERCOMMAND: pCmd: ' RATE = 15, PERI ODI CI TY = 605' STREAM_OPERATOR:
I nval i d Per i odi ci t y at t r i but e val ue ( 605) . Command i s i gnor ed.
STREAM_OPERATOR: Cont i nui ng wi t h Rat e: 200 st at ement s per Mi nut e
STREAM_OPERATOR: Cont i nui ng wi t h Per i odi ci t y: 9 per Mi nut e
Error Tables
The Stream driver uses a single error table that contains records rejected because of data
conversion, constraint, or other errors. The APPLY statement for a load operation provides
DML attributes and error option attributes that tell the Stream driver what it should do with
errors. These attributes define a label and error treatment options for one or more
immediately following INSERT, UPDATE, or DELETE statements. These options allow you to
mark or ignore error conditions, such as duplicate rows and missing rows, etc. Marked error
conditions can be directed to the error table.
These MARK/IGNORE options are:
DUPLICATE INSERT ROWS
DUPLICATE UPDATE ROWS
MISSING UPDATE ROWS
MISSING DELETE ROWS
Reusing Stream Driver Table Names
If an error table has one or more rows, it is not dropped from the Teradata Database at the end
of a Stream driver job. To reuse the names specified for the error tables, use the BTEQ utilitys
DROP TABLE statement to remove the tables from the Teradata Database.
Limiting Errors in the Stream Driver
Use the ErrorLimit attribute to limit the number of errors captured in the error table during
the Stream job.
Note: The ErrorLimit specification applies to each instance of the Stream application, not to
all instances combined. If, for example, you set the limit to 10,000, then a single instance
would have to detect that 10,000 rows were inserted into the first error table in order to
terminate the job, and those 10,000 rows would have to be controlled by the sessions managed
by that instance.
Processing terminates when the number of errors encountered reaches the error limit. If, for
example, you expect no errors in the input data, set the error limit value to one. In this case,
the job terminates when any record causes an error.
Some tables are created by the Teradata Database during the execution of a job, and others
must be created by the user before the job begins. When a job is run, the log table and error
table are created automatically. The error table is dropped during the Cleanup phase if no
errors were detected during the job. The log table is dropped after the job completes
successfully.
If a job terminates abnormally, then the log and error tables are not dropped. If you want to
restart the job from scratch, you need to manually drop these tables by running a BTEQ script
to drop and recreate the tables.
Caution: Care must be taken dropping the target tables manually using a BTEQ script. If something
goes wrong with a Stream job, and you drop the target table manually and then try to rerun
the job, you may lose the original data.
Required Privileges
The user ID that is logged in by the Stream driver must have:
SELECT, INSERT, UDATE, and DELETE privileges on the Stream target tables.
SELECT and INSERT privileges on the error tables, and CREATE and DROP privileges on
the database that contains the error tables.
SELECT, INSERT, and DELETE privileges on the restart log table, and CREATE and
DROP privileges on the database that contains the restart log table.
Session Limits
The values that you specify with the Stream driver TD_MIN_SESSIONS and
TD_MAX_SESSIONS attributes are not the only factors that limit the number of sessions that
the Stream driver establishes with the Teradata Database.
Table 26: Stream Driver ERRORLIMIT Values
IF you expect your Stream job to encounter... THEN specify an ERRORLIMIT value that is...
defined in the COP Interface software file, CLISPB.DAT, under the max_num_sess
variable.
You can use the TDP SET MAXSESSIONS command to specify a platform limit. The
default TDP MAXSESS value is 1024 sessions.
The limit of the network protocol software on network-attached systems. When the
Stream driver executes, the actual session limit is determined by whichever limiting factor
is encountered first.
Obtaining the Row Count Using TD_Evt_ApplyCount
The event TD_Evt_ApplyCount can be used to query the Stream driver for the number of
inserts, updates, and deletes performed by each DML Group in the job. The index parameter
in the GetEvent method is used to indicate the datas DML Group. The index that is passed to
the GetEvent method is the same index that is returned by the AddDMLGroup method for the
desired DML Group. This is different from the way the Update driver returns the number of
rows inserted, updated, and deleted. The Update driver uses the index parameter in the
GetEvent method to signify the datas target table. However, just like the data returned by the
Update drivers TD_Evt_ApplyCount event, the data for this event only applies to the instance
making the GetEvent call.
The TD_Evt_ApplyCount event can be queried at any time during the job after Initiate and
before Terminate. The data returned will correspond to the number of rows inserted, updated
or deleted since the last checkpoint was taken. If no checkpoint was taken during the job then
the data returned will not be meaningful until after EndAcquisition is called. The final
statistics for the number of rows inserted, updated, or deleted will always be available after the
EndAcquisition method returns with a TD_END_Method. This event returns a block of data
for each statement in the DML Group.
The eventData parameter provided to the GetEvent method points to a concatenation of these
data blocks if the method returns with TD_END_Method. If the method does not return with
TD_END_Method then the eventData pointer is not correct. Each DML statement only has
one data block filled with the information described above as long as the statement is not an
upsert or merge statement, in which case there would be two data blocks filled with
information. For example, any insert statement only has a data block returned with
information about the number of rows inserted. This is true for update and delete statements
as well. Upsert and merge DML statements have two data blocks filled with information: one
for the number of updates and one for the number of inserts.
Figure 6 depicts the buffer returned by the TD_Evt_ApplyCount event. For a description of
the format of the fields, see the Returned Value column in TD_Evt_ApplyCount on
page 130.
Figure 6: Layout of Data Buffer returned by the TD_Evt_ApplyCount Method
Based on this information and the length (in bytes) provided in eventDataLen after the
GetEvent method returns, the number of rows inserted, updated, and deleted can be obtained
for each DML statement in the DML Group.
Always estimate the final size of the Stream target table, and make sure that the destination
database on the Teradata Database has enough space to accommodate the Stream job. If the
database that owns the Stream target table, log table, or error table runs out of space, the
Teradata Database returns an error message and the Stream driver terminates the Stream job.
When this happens, more space must be allocated to the database before the job can be
restarted.
Tuning the Pack Factor
Packing multiple-statement requests improves network/channel efficiency by reducing the
number of sends and receives between the application and the Teradata Database.
To determine the ideal pack factor to specify in the Pack attribute, first use the PackMaximum
attribute by setting it to Yes. Setting this attribute to Yes on the first job run sets up iterative
interactions with the Teradata Database to heuristically determine the maximum possible
pack factor.
At the end of the run, this value is displayed in the Stream drivers logged output. The value
determined should then be specified in the Pack attribute on subsequent runs and
PackMaximum should be set to No.
Alternatively, query the TD_Evt_PackFactor event after initiating a connection and before
terminating it to retrieve the pack factor currently in use.
DELETE is a Teradata SQL statement that removes rows from a table or view that was
previously identified as a target table through the use of the TD_TARGET_TABLE attribute.
The rules for using the DELETE statement in Stream import tasks are:
You can apply DELETE statements to either a table or a view, provided that the view does
not specify a join
The number of input data records is unlimited
You must specify equality values for all the primary index columns in the WHERE clause
You cannot use the OR construct in the WHERE clause of a DELETE statement. Instead,
use two separate DELETE statement.
Statement #
2516A007
Type DB Name Activity Statement #
This Whole Structure Repeats
DB Name
Length
Table/Macro
Name Length
Table/Macro
Name
The procedure for using the DELETE statement in a Stream import task is:
1 Add a DELETE statement to a DML group
4 Set the DML group containing the DELETE statement using the UseDMLGroups function
5 Make at least one call to the PutRow function
If the DML group only contains a DELETE statement, then no data will be loaded as a
result of the PutRow function call.
6 Call the EndAcquisition function
Note: If no row in the target table matches the DELETE statement, then the row of data
sent with the DELETE statement will be put into the error table.
Stream Driver Macro Support
Teradata PT supports executing macros using the Stream driver. Adhering to Teradata Parallel
Data Pump protocols that are documented in the Teradata Parallel Data Pump Reference, note
the following guidelines:
The macro specified in the EXECUTE statement must reside on the RDBMS prior to the
start of the job. For more information on creating a macro, see SQL Data Manipulation
Language.
The database user defined for the Stream driver job must have the EXECUTE privilege for
the macro specified in the EXECUTE statement.
The EXECUTE statement used in the DML group must follow the format documented in
the Teradata Parallel Data Pump Reference. This is the EXECUTE or EXEC command
followed by the name of the macros (the database can be specified using the dot notation
database.macro) followed by one of the key words, depending on what kind of statement is
executed by the macro.
The key words are:
INSERT
UPDATE
DELETE
UPSERT
The EXECUTE statement cannot include a parameter list. The parameter list is
automatically generated by the Stream driver based on the provided schema.
The macro must have one or more parameters. The Stream driver does not support
executing macros that do not have parameters.
Executing a macro in a Stream driver job
1 Add the EXECUTE statement to a DML group. See Stream Driver Macro Support on
page 139 for guidelines.
2 Define the schema based on the macros parameter list.
3 Add the DML group and Schema to the Connection object.
4 Set the DML group containing the EXECUTE statement using the UseDMLGroups
function.
5 Call the PutRow function. The row data provided to PutRow will be used to fill out the
macros parameter list and the macro will be executed.
6 Call the End Acquisition function.
7 Terminate the Connection object.
Code Example
The following macro was defined prior to execution:
cr eat e macr o i ns_r ow
(
p1 i nt eger ,
p2 var char ( 32000)
) as(
i nser t i nt o t abl e1
( col 1, col 2)
val ues( : p1, : p2) ;
) ;
For the Stream driver, add this EXECUTE statement to the DML group:
EXECUTE i ns_r ow I NSERT;
And this schema is built:
Schema * st r Schema=new Schema( i nput ) ;
st r Schema- >AddCol umn( col 1, TD_I NTEGER, 4) ;
st r Schema- >AddCol umn( col 2, TD_VARCHAR, 32000) ;
st r Conn- >AddSchema( st r Schema) ;
Using the MacroCharSet Feature
Use the following syntax to enable TD_MACROCHARSET:
conn - > AddAt t r i but e( TD_MACROCHARSET, "Yes" ) ;
Note: You can also specify Y, yes, or y in the syntax shown above.
Use the following AddColumn syntax when TD_MACROCHARSET is enabled.
Schema- > AddCol umn( char *, TD_Dat aType, char *, TD_Col umnSi ze,
TD_Col umnPr eci si on, TD_Col umnScal e)
For example:
schema - > AddCol umn( " Associ at e_Name" , TD_CHAR, " UNI CODE" , 25) ;
Code Example
The column MacroCharSet name for any character column only accepts values from the
follow set of values:
"LATIN"
"UNICODE"
"KANJI1"
"KANJISJIS"
"GRAPHIC"
The Stream driver is fully checkpoint restartable. See the checkpoint and restart discussion in
Code Example
cout << "*** St r eamDr i ver Exampl e ***" << endl ;
/ **********************************************
**********************************************/
conn- >AddAt t r i but e( TD_SYSTEM_OPERATOR, TD_STREAM) ;
/ / conn- >AddAt t r i but e( TD_TRACE_OUTPUT, " st r eam. t xt " ) ;
/ **********************************************
**********************************************/
conn- >AddAt t r i but e( TD_USER_NAME, " user " ) ;
conn- >AddAt t r i but e( TD_LOG_TABLE, " t dl oad_l og" ) ;
conn- >AddAt t r i but e( TD_ERROR_TABLE, " t dl oad_e1" ) ;
conn- >AddAt t r i but e( TD_MAX_SESSI ONS, 4) ;
conn- >AddAt t r i but e( TD_MI N_SESSI ONS, 1) ;
conn- >AddAt t r i but e( TD_TENACI TY_HOURS, 2) ;
conn- >AddAt t r i but e( TD_TENACI TY_SLEEP, 3) ;
conn- >AddAt t r i but e( TD_ROBUST, " No" ) ;
/ **********************************************
* Add Schema
**********************************************/
schema- >AddCol umn( " Associ at e_Name", TD_CHAR, 25) ;
schema- >AddCol umn( " Mar t i al _St at us", TD_CHAR, 1) ;
/ **********************************************
* Add DMLGr oups
**********************************************/
Code Example
dml Gr - >AddSt at ement ( " I NSERT I NTO t dl oad( : Associ at e_I d, : Associ at e_Name, : Sal ar y,
dml Gr - >AddSer i al i zeOn( 8, " Associ at e_I d" , " Associ at e_Name" , " Sal ar y" , " DOJ " ,
" Desi gnat i on" , " Loan_Amount " , " Mar t i al _St at us" , " No_Of _Dependent s" , NULL) ;
dml Gr - >AddUseLi st ( 8, " Associ at e_I d" , " Associ at e_Name" , "Sal ar y" , " DOJ " , " Desi gnat i on" ,
" Loan_Amount " , " Mar t i al _St at us" , " No_Of _Dependent s" , NULL) ;
r et ur nVal ue = conn- >AddDMLGr oup( dml Gr , &dml Gr oupI ndex) ;
/ **********************************************
* I ni t i at e
**********************************************/
{/ **********************************************
* Acqui si t i on
**********************************************/
TD_Lengt h byt es;
i nt count = 0;
whi l e( l oadSt at us ! = - 1 )
{
l oadSt at us = Get RowDat a( r owBuf f er , 78) ; / / user f unct i on - r eads i n a
/ / r eached
i f ( l oadSt at us ! = - 1 )
{
/ * pi ck up t he f i r st 2 byt es as t he r ow l engt h of t he i ndi cat or mode
r ecor d */
i f ( r et ur nVal ue >=TD_Er r or )
{
cout << " Put Row f ai l ed on r ow " << count +1;
l oadSt at us = Get RowDat a( NULL, 0) ; / / user f unct i on - cl ose f i l e
}el se{
count ++;
}
}
}
{
cout << "Sent " << count << " r ows" << endl ;
/ **********************************************
**********************************************/
cout << "Acqui si t i on compl et ed wi t h st at us " << r et ur nVal ue << endl ;
}el se{
}el se{
}
}
}el se{
cout << "Er r or occur ed dur i ng Acqui si t i on" << endl ;
Code Example
}el se{
}
}
}el se{
cout << " Er r or occur ed dur i ng I ni t i at e" << endl ;
}el se{
}
}
/ **********************************************
* Ter mi nat e
**********************************************/
{
cout << " Er r or occur ed dur i ng Ter mi nat e" << endl ;
}el se{
}
}
/ **********************************************
* Cl ean Up
**********************************************/
del et e dml Gr ;
del et e schema;
del et e conn;
cout << "*** St r eamCompl et e ***" << endl ;
Code Example
CHAPTER 6
Export Driver
Using Teradata FastExport Reference protocols, the Export driver is designed to use multiple
Export sessions to export large volumes of data at high speed from the Teradata Database to a
client application.
For a sorted answer set, redistribution of the rows occurs over the BYNET. This allows for easy
recombination of the rows and data blocks when they are returned to the client in sorted
order. The main topics of this chapter are:
Table 27 and Table 28 define the Export drivers required and optional attributes. This
information is helpful when coding your application.
Required Attributes
Required Attributes
Optional Attributes
GetEvent Queries
SELECT REQUESTS
Session Limits
Performance Factors
Code Example
Sample Export_To_Load Program for Returning the
Actual Data Type
Table 27: Export Driver Required Attributes
TD_BUFFER_MODE varchar Indicates which type of export method is used.
Valid values are:
No (N) = Exporting will be on a row by row basis. This is the default
value.
Yes (Y) = The GetBuffer feature will be used to export. See Export
Data from a Teradata Database using GetBuffer on page 30 for more
information.
Chapter 6: Export Driver
TD_INSTANCE_NUM integer Specifies the instance number of the current instance.
should be one. Required only when using multiple instances of the same
driver in a master-slave environment.
TD_LOGSQL varchar Directs the Export driver to output the full Teradata SQL request in the
trace output file with the drivers trace is enabled. By default, when the
drivers trace is enabled, the Export driver outputs the Teradata SQL
request, up to 32 kilobytes, in the trace output file.
Valid values:
Yes ('Y') = Output the full Teradata SQL in the trace output file when
the drivers trace is enabled. The maximum length of the Teradata
SQL is 1 megabyte.
No ('N') = Do not output the Teradata SQL in the trace output file.
Note: When the drivers trace is disabled, TD_LOGSQL has no effect.

TD_MAX_INSTANCES integer Specifies the total number of instances (master and slaves). Required only
environment.
TD_RESTARTMODE integer Required only before restarting and must be set to one.
TD_SELECT_STMT varchar Specifies a Teradata SQL SELECT statement or statements.
See Teradata SQL reference documentation for your operating system,
and enter one or more valid Teradata SQL SELECT statements for this
SelectStmt attribute.
Each statement or group of statements must be enclosed in single quotes
and must be terminated with a semicolon. Multiple statements cannot be
added using the AddArray Attribute function. If you have multiple SQL
SELECT statements, put them together in a single string with semicolons
separating the statements and use this string as the value in the Add
Attribute function.
TD_SYSTEM_OPERATOR varchar Specifies the type of driver being used (in this case TD_EXPORT).
TD_USER_NAME varchar Provides the user name for the Export driver logon sessions.
TD_USER_PASSWORD varchar Specifies the password associated with the user name.
Table 27: Export Driver Required Attributes (continued)
Optional Attributes
Table 28: Export Driver Optional Attributes
TD_ACCOUNT_ID varchar Specifies the account associated with the specified user name.
When omitted, this attribute defaults to the account identifier of
the immediate owner database.
TD_AUTORESTART varchar Teradata PT APT notifies the user application, once Teradata
Database restarts, that the database crashed.
Valid values are:
No (N) = The user application receives the CLI 220 error
message when the database is down during the acquisition
phase of Teradata PT API.
TD_BLOCK_SIZE integer Specifies the block size in bytes used when returning data to the
client.
The minimum is 256 bytes. The default and maximum are 64330
bytes for Teradata Database V2R6.0 and later.
Note: This value cannot be larger than the row size supported by
the Teradata Database.
TD_BUFFER_HEADER_SIZE integer Specifies the row header size allocated for each row in the data
buffer returned by the GetBuffer function.
The row header size must be greater than or equal to the value for
the TD_BUFFER_LENGTH_SIZE attribute. The default row
header size is 2. For more information on using the GetBuffer
function, see Export Data from a Teradata Database using
GetBuffer on page 30.
TD_BUFFER_LENGTH_SIZE integer Specifies the row length size allocated for each row in the data
buffer returned by the GetBuffer function.
Valid row length size values are:
4 = Each rows length value to be returned as an integer value.
2 = Each rows length value to be returned as a short value.
This is the default value.
0 = Causes no row length value to be returned for each row.
For more information on using the GetBuffer function, see
Export Data from a Teradata Database using GetBuffer on
page 30.
TD_BUFFER_MAX_SIZE integer Specifies the total maximum size for the data buffer returned by
the GetBuffer function. The total maximum size of the data buffer
must be large enough to hold at least one row of data including
the row header, the actual row of data, and the buffer trailer.
When exporting variable length data, the largest row size possible
is used when calculating the minimum total maximum size of the
data buffer. The default total maximum size of the data buffer is
64,260 (roughly 64k).
page 30.
TD_BUFFER_TRAILER_SIZE integer Specifies the size of the buffer trailer allocated for the data buffer
returned by the GetBuffer function. The default buffer trailer size
is zero.
page 30.
TD_CHARSET varchar Specifies the name or code of the character set to be used for the
job. On channel-attached z/OS platforms, only EBCDIC
encoding is supported and is automatically selected. For the list of
supported character sets, see Extended Character Sets in
Teradata Parallel Transporter Reference.
TD_DATA_ENCRYPTION varchar Activates full security encryption of SQL requests, responses and
data.
Valid values are:
Off = No encryption occurs. This is the default value.
TD_DATE_FORM varchar Specifies the DATE data type for the Export driver job.
Valid values are:
IntegerDate = Integer DATE data type. This is the default
value.
ANSIDate = ANSI fixed-length CHAR(10) DATE data type.
Table 28: Export Driver Optional Attributes (continued)
TD_IGNORE_MAX_DECIMAL_
DIGITS
varchar Signals to the Export driver whether to ignore the
TD_MAX_DECIMAL_DIGITS attribute and continue the job if
the Large Decimal feature is not supported by the Teradata
Database or Teradata CLIv2. This attribute has no impact when
used with V2R6.2 or later Teradata Database.
Valid values are:
No (or N) = The Export Driver will use the
TD_MAX_DECIMAL_DIGITS attribute. The Export job
terminates with an error if the TD_MAX_DECIMAL_DIGITS
attribute is used and the Teradata Database level is V2R6.1 or
older. This is the default value.
Yes (or Y) = The Export driver will ignore the
TD_MAX_DECIMAL_DIGITS attribute if the Large Decimal
feature is not supported by the Teradata CLIv2 or the Teradata
Database. If the Large Decimal feature is not supported then
the Export driver continues processing and returns an exit
code of four instead of zero to indicate a warning when the
TD_Evt_ExitCode event is queried.
TD_LOGON_MECH varchar Specifies which logon mechanism to use.
See your site security administrator for specific mechanism
names. For a list of available mechanisms, see Security
Administration. The job terminates if the attribute exceeds eight
bytes.
TD_LOGON_MECH_DATA varchar Passes additional logon mechanism data. See your site security
administrator for specific mechanism data. For more
information, see Security Administration.
TD_MAX_DECIMAL_DIGITS integer Specifies the maximum number of decimal digits (a value for the
maximum precision) to be returned by the database. Valid values
range from 1 to 38 inclusive. The default value is 18.
TD_MAX_SESSIONS integer Specifies the maximum number of sessions to log on.
This MaxSessions value must be greater than one. Specifying a
value less than one terminates the job.
The default is one session per available AMP. The maximum value
cannot be more than the number of AMPS available.
The MaxSessions value must be greater than or equal to the value
of TD_MAX_INSTANCES.
TD_MIN_SESSIONS integer Specifies the minimum number of sessions required for the
Export driver job to continue. The default is one session.
The MinSessions value must be greater than one and less than or
equal to the maximum number of Export driver sessions.
Specifying a value less than one terminates the Export driver.
TD_MSG_ENCODING TD_
Encoding
Specifies the encoding for the messages passed between Teradata
PT and a Teradata PT application.
TD_NOTIFY_EXIT varchar Specifies the name of the user-defined notify exit routine.
When no name is supplied, the following default names are used:
For detailed information on the Notify feature, see Export
Operator in Teradata Parallel Transporter Reference.
setting.
Initialize
CLIv2/DBS Error
Exit
Medium = Notification is provided for all the events except for:
File or OUTMODE Open
Statement Fetch Begin and End
High = Notification is to be provided for all events.
Valid methods are:
None = No event logging is done. This is the default method.
Exit = This method sends the events to a user-defined notify
exit routine and to the system log.
On Windows, the events are sent to an EventLog that can be
viewed using the Event Viewer. The messages are sent to the
application log.
On AIX, HP-UX, Linux, and Solaris platforms, the destination
of the events is specified in the /etc/syslog.conf file.
TD_NOTIFY_STRING varchar Specifies a user-defined string that precedes all messages sent to
the system log. This string is also sent to the user-defined notify
exit routine.
TD_OUTLIMIT integer Limits the number of rows that the Export driver exports.
Default setting is:
No limit
Valid values are:
Any non-negative integer value
Note: In a multiple instance environment, this limit applies only
to the particular instance on which it is set, and not to the overall
job.
For example, in an Export job with one master instance and one
slave instance, if the out limit for both the master and the slave is
set to 10 rows, then the master instance stops after exporting 10
rows and the slave instance stops after exporting 10 rows.
TD_QUERY_BAND_SESS_INFO varchar Provides a user-defined query band expression that is set for every
SQL session connected by the Teradata PT driver. The following is
an example of a valid query band expression:
a=1; b=2; c=3; d=4;
If the TD_QUERY_BAND_SESS_INFO is set, the following
request will be sent by every SQL session connected by the
Teradata PT Export driver:
Setting the TD_QUERY_BAND_SESS_INFO attribute in jobs
running against non-supported versions of the Teradata Database
causes a non-fatal error. No error code is returned to the user
during initiation and the job is allowed to proceed. The log table
will not be dropped at the end of the job and the
TD_Evt_ExitCode event returns a warning value of four instead
of the normal success value of zero if queried. In this case, error
information can be found in the trace file.
TD_RETN_ACT_DATATYPE varchar Enables or disables returning the actual column data type.
Valid vales are:
Y[es] = the Export Driver returns the actual data type.
N[o] = the Export Driver returns the CHAR data type for
TIMESTAMP, TIME, and INTERVAL data types (default).
For a sample TPTAPI program to implement Return Actual Data
Type, see Sample Export_To_Load Program for Returning the
Actual Data Type on page 161.
For conversion information, see Chapter 9: Converting TIME,
TIMESTAMP, and INTERVAL Data Types.
TD_SPOOLMODE varchar Specifies whether to use spool or not while running the current
Export job.
Valid values are:
Spool = Use Spool. This is the default setting.
NoSpool = Do not use Spool.
Note: This value is valid only if DBS supports NoSpool. If DBS
does not support NoSpool, it uses Spool instead.
NoSpoolOnly = Do not use Spool in any case.
Note: If the DBS does not support NoSpool, it terminates the
job with an error.
server name.
If you do not specify the value for the TdpId attribute, the
driver uses the default TdpId established for the user by the
system administrator.
TD_TENACITY_HOURS integer Specifies the number of hours the Export driver attempts to log
on when the maximum number of load and export operations are
The default value is four hours. To enable the tenacity feature,
this value must be greater than zero.
Specifying a value of zero will disables the tenacity feature.
Specifying a value less than zero terminates the Export driver.
TD_TENACITY_SLEEP integer Specifies the number of minutes the Export driver pauses before
attempting to log on when the maximum number of load and
export operations are already running on the Teradata Database.
This value must be greater than one. If you specify a value less
than one, the Export driver responds with an error message and
terminates the job.
Valid values are:
TD_TRACE_LEVEL
TD_OFF should always be
specified.
integer Specifies the types of diagnostic messages written by each instance
of the driver to an external log file. The diagnostic trace function
provides more detailed information in the log file (including the
version number) to aid in problem tracking and diagnosis.
Use the AddArray attribute method to specify the two types of
tracing levels: driver tracing and infrastructure tracing.
TD_OFF is the default setting for both driver tracing and
infrastructure tracing. No external log file is produced unless this
default is changed. Specifying TD_OFF for both driver tracing
and infrastructure tracing is the same as disabling tracing.
If the TraceLevel is set to any value other than TD_OFF, an
external log file is created for each instance of the driver.
activities.The absence of any value for the PauseAcquisition
attribute means that the Export driver job will execute both
the acquisition phase and the application phase without
pausing. This will distribute all of the rows that were sent to
the Teradata Database during the acquisition phase to their
final destination on the AMPs. Table 1 lists which drivers have
the Pause Acquisition attribute.
TD_OPER_CLI = Activates the tracing function for
CLIv2-related activities (interaction with the Teradata
Database).
TD_OPER_NOTIFY = Activates the tracing function for
activities related to the Notify feature.
TD_OPER_ALL = Activates tracing for all of the above
activities.
The trace levels for infrastructure tracing should only be used
when you are directed to by Teradata support. TD_OFF, which
disables infrastructure tracing, should always be specified.
TD_TRACE_OUTPUT varchar Specifies the name of the external file used for tracing messages.
The default setting creates a new file name with the name of the
driver followed by a time stamp.
Note: If a file with the specified name already exists, that file will
be overwritten.
TD_WORKINGDATABASE varchar Specifies the name of the database used in the Teradata SQL
DATABASE statement sent by the Export driver to the Teradata
Database immediately after connecting the two SQL sessions. Use
this attribute to specify a default database other than the logon
database.
GetEvent Queries
GetEvent Queries
All events must be queried after the driver has initiated and before it has terminated. Events
queried before their data is available yet will return TD_Unavailable. The following table lists
events that may be used with the Connection objects GetEvent function to retrieve run time
statistics from the Export driver.
Table 29: Export Driver Events
Event Return Value
TD_Evt_BlockCount One 4-byte integer for the total number of blocks
returned from all of the SELECT requests. Query this
event after the first call to GetRow has returned
TD_Success.
event at any time.
and any CLIv2 error number that may have occurred
during the connect process. Query this event at any time.
TD_Evt_DBSError One 4-byte integer for the DBS error number and a 255
byte character buffer for the DBS error text. Query this
event at any time.
TD_Evt_ExitCode One 2-byte integer for the driver exit code. Query this
event right before the driver terminates.
TD_Evt_ExportCount One 4-byte unsigned integer for the total number of rows
exported so far. Query this event any time after the first
call to GetRow has returned TD_Success. If this event is
queried after GetRow has returned TD_END_Method
then the integer represents the total number of rows
exported for the job.
TD_Evt_ExportCount64 One 8-byte unsigned integer for the total number of rows
exported so far. Query this event anytime after the first
call to GetRow has returned TD_Success.
If this event is queried after GetRow has returned
TD_END_Method then the integer represents the total
number of rows exported for the job.
initiated.
PutEvent Modifiers
PutEvent Modifiers
All PutEvent modifiers must be used after the driver has initiated and before it has terminated.
TD_Unavailable is returned when a modifier cannot be used. The following table lists
modifiers that are used with the Connection objects PutEvent function to modify the Export
driver.
These sections discuss the items you should consider when coding an Export application.
SELECT REQUESTS
Session Limits
Performance Factors
A Code Example follows these topics.
SELECT REQUESTS
A SELECT request is one or more Teradata SQL SELECT statements that may be optionally
preceded by a LOCKING modifier. A SELECT request can have multiple SELECT statements.
TD_Evt_Version A pointer to a character string containing the Teradata PT
version followed by a pointer to a character string
Table 29: Export Driver Events (continued)
Event Return Value
Table 30: PutEvent Modifier Expected Data
PutEvent Modifier Expected Input Data
TD_Evt_BufferLayout Buffer containing four 4-byte unsigned integers corresponding to
the maximum buffer size, the row header size, the row length size,
and the buffer trainer size.
Values are used to format the buffer of data returned by the
Export drivers GetBuffer function. This modifier can be used
anytime up until the first call to the GetBuffer function.
Note: Event data returned by the Load, Update, and Stream
drivers TD_Evt_BufferLayout event can be directly passed in for
this modifier.
When creating SELECT requests for an Export job:
SELECT Request Restrictions
Export SELECT requests cannot:
Table 31: Export Driver SELECT Requests
IF your SELECT request... THEN...
Has multiple SELECT statements The Teradata Database may execute them in parallel,
but still returns the response data for the first statement
first, then the response data for the second, and so on. If
the response rows have a different structure, the Export
driver responds with an error message and terminates.
For example, Table1 has columns A, B, and C. Table2
has columns A, B, D, and E. You require data from
columns A and B in Table1 and columns A and B in
Table2.
The following statement is not a valid multi-SELECT
statement for the Export driver.
SELECT A, B f r omTabl e1; SELECT A f r omTabl e2;
However,
SELECT A, B f r omTabl e1; SELECT A, B FROM
Tabl e2;
would be valid for the Export driver. The corresponding
output schema is required to be defined with columns A
and B.
Uses a LOCKING modifier The specified lock remains in effect during the
execution of all statements within the request
containing the modifier.
The Teradata Database:
Implements all resource locks for the entire request
before executing any of the statements in the request.
Maintains the locks until all of the response data for
the request has been moved to spool tables.
Note: The Teradata Database removes the resource
locks before returning the data to your client system.
The following is an example of a valid SELECT
request using the LOCKING modifier:
LOCKI NG TABLE MYTABLE FOR ACCESS SELECT
COL1, COL2 FROM MYTABLE;
Note that the LOCKING modifier is allowed to
precede the SELECT statement.
Uses an ORDER BY clause You must specify one Export instance.
The following is an example of a valid ORDER BY
clause:
SELECT COL1, COL2 FROM MYTABLE ORDER BY
COL1;
Specify a USING modifier
Access non-data tables, such as SELECT DATE or SELECT USER.
Be satisfied by a single AMP, such as SELECT statement with a constraint containing an
equality condition on the primary index or unique secondary index columns of a table.
Contain character large object (CLOB) or binary large object (BLOB) data type.
Use a WITH option to generate total or subtotal response rows. This option is used for
report generation, and it produces response rows for the aggregations that are not in the
same format as the detail rows.
Utilize variable substitution
Other than these restrictions, the Teradata Database parses and processes SELECT statements
from the Export driver as it would from any other data access facility. For a complete
description of the SELECT statement, see Teradata SQL reference documentation for your
operating system.
Session Limits
The values that are specified with the Export driver TD_MAX_SESSIONS and
TD_MIN_SESSIONS attributes are not the only factors limiting the number of sessions that
the Export driver establishes with the Teradata Database.
The Teradata Database limit of one session per AMP.
defined in the COP Interface software file, clispb.dat, under the max_num_sess variable.
You can use the TDP SET MAXSESSIONS command to specify a platform limit. The
default TDP MAXSESS value is 1024 sessions.
The limit of the network protocol software on network-attached systems. When the
Export driver executes, the actual session limit is determined by whichever limiting factor
is encountered first.
Note: The Export driver will terminate with an error message if one or more instance cannot
log on.
Performance Factors
Performance can vary depending on the number of sessions that the Export driver is using.
Using too few sessions can limit the data throughput; using too many sessions involves
increased session management overhead which can slow down the job. The latter can occur
when running against a large Teradata Database configuration as the Export drivers default
setting is to have one session per AMP.
There is no general method to determine the optimal number of sessions to use since there are
several factors to consider such as the performance and workload of the Teradata Database,
the network performance, and the volume of data being processed. In many cases, using two
or four sessions will result in the best performance, but users are encouraged to experiment
with several different session configurations to determine the best setting for each Teradata
Database configuration.
The checkpoint and restart operations are not useful for the Export applications. See the
checkpoint and restart discussion in Add Checkpoint and Restart.
NoSpool Mode
The NoSpool mode exports the contents of a table as fast as possible without reading the table
into a spool file or distributing the file to all AMPs before extracting it. Three options for
spooling are:
(Default) SPOOL the data.
Use the NOSPOOLONLY mode, but return an error if NOSPOOL is not supported.
Use the NOSPOOL mode when possible; otherwise spool the data in Teradata Database.
Limitations and Functionality
NOSPOOL mode applies only to simple SELECT statements. The following are not
supported:
Access to nondata tables, such as SELECT DATE or SELECT USER
USING modifier; instead, define restraint parameters by using a FastExport IMPORT
command with supporting FIELD and FILLER commands
Contains a SORT (ORDER BY), HAVING, or WITH clauses
Joins
Aggregations (Explain shows SUM step)
TABLE functions
Ordered-analytic (OLAP) functions
Multiple SELECT statements or multistatement requests
Statements with zero or more than one, retrieve or sampling step
NOSPOOL mode only retrieves data from a single table, but the SELECT statement can be
selective about which columns are exported and can constrain the job to a subset of rows.
Scalar expressions/functions are allowed.
The Sample and partition eliminating constraints are supported.
The Activity Count returned for a regular spooled job indicates the number of affected
blocks; however, for non-spooled jobs, the number of blocks is unknown, so the response
message contains ActivityType (instead of Activity Count) to indicate the NOSPOOL
process.
Disadvantages of the NOSPOOL Mode
Locks are maintained during the entire export process.
Data conversion errors previously detected during the spooling phase will not be detected
until the block is read, which could occur during any time during the export.
Code Example
Row order (because of the absence of the ORDER BY clause) may or may not be consistent
between runs; therefore, NOSPOOL mode offers no guarantee of consistency.
See information on Spool/NoSpool mode, Teradata FastExport Reference.
Code Example
cout << "*** Expor t Dr i ver Exampl e ***" << endl ;
/ **********************************************
**********************************************/
conn- >AddAt t r i but e( TD_SYSTEM_OPERATOR, TD_EXPORT) ;
/ / conn- >AddAt t r i but e( TD_TRACE_OUTPUT, " expor t . t xt " ) ;
/ **********************************************
**********************************************/
conn- >AddAt t r i but e( TD_USER_NAME, " user " ) ;
conn- >AddAt t r i but e( TD_SELECT_STMT, " sel Associ at e_Name f r omt dl oad; " ) ;
/ **********************************************
* Add Schema
**********************************************/
Schema * schema = new Schema( " out put " ) ;
schema- >AddCol umn( " Associ at e_Name", TD_CHAR, 25) ;
/ **********************************************
* I ni t i at e
**********************************************/
{
/ **********************************************
* Acqui si t i on
**********************************************/
i nt count = 0;
char * dat a;
TD_Lengt h dat aLen = 0;
i nt expor t St at us = 0;
whi l e( expor t St at us ! = - 1) {
r et ur nVal ue = conn- >Get Row( &dat a, &dat aLen) ;
{
cout << " Get Row f ai l ed on r ow " << count +1;
expor t St at us = Wr i t eRowDat a( NULL, 0) ; / / user f unct i on - cl ose f i l e
/ / r et ur ns - 1 when cl osed
Code Example
}el se i f ( r et ur nVal ue == TD_END_Met hod ) {
cout << " End of Dat a Reached" << endl ;
expor t St at us = Wr i t eRowDat a( NULL, 0) ; / / user f unct i on - cl ose f i l e
/ / r et ur ns - 1 when cl osed
count ++;
}el se{
expor t St at us = Wr i t eRowDat a( dat a, dat aLen) ; / / user f unct i on wr i t es
/ / dat a t o ext er nal f i l e
/ / r et ur ns 0 i f successf ul l
count ++;
}
}
cout << "Expor t compl et ed wi t h st at us " << r et ur nVal ue << endl ;
{
cout << "Expor t compl et ed successf ul l y" << endl ;
}el se{
cout << "Er r or occur ed dur i ng Expor t " << endl ;
}el se{
}
}
}el se{
cout << "Er r or occur ed dur i ng I ni t i at e" << endl ;
}el se{
}
}
/ **********************************************
* Ter mi nat e
**********************************************/
{
}el se{
}
}
/ **********************************************
* Cl ean Up
**********************************************/
del et e schema;
del et e conn;
cout << "*** Expor t Compl et e ***" << endl ;
Sample Export_To_Load Program for Returning the Actual Data Type
Sample Export_To_Load Program for Returning
the Actual Data Type
***********************************************************************
* Copyr i ght 2006- 2009, 2011 by Ter adat a Cor por at i on.
* Al l Ri ght s Reser ved.
* TERADATA CONFI DENTI AL AND TRADE SECRET
*
* Thi s copyr i ght ed mat er i al i s t he Conf i dent i al , Unpubl i shed
* Pr oper t y of t he Ter adat a Cor por at i on. Thi s copyr i ght not i ce and
* any ot her copyr i ght not i ces i ncl uded i n machi ne r eadabl e
* copi es must be r epr oduced on al l aut hor i zed copi es.
*
***********************************************************************/
#i ncl ude " Gener i cDr i ver . h"
#i ncl ude " Opt i onsManager . h"
#i ncl ude <st di o. h>
#i ncl ude <st dl i b. h>
#i ncl ude <t i me. h>
#i ncl ude " st r i ng. h"
#i ncl ude <vect or >
#def i ne MAX 10
Gener i cDr i ver : : Gener i cDr i ver ( Opt i onsManager * om)
{
i nput St r eam= NULL;
out put St r eam= NULL;
i nput Fi l eName = NULL;
out put Fi l eName = NULL;
m_om= om;
}
Gener i cDr i ver : : ~Gener i cDr i ver ( voi d)
{
i f ( i nput Fi l eName ! = NULL )
{
f r ee( i nput Fi l eName) ;
}
i f ( out put Fi l eName ! = NULL )
{
f r ee( out put Fi l eName) ;
}
}
/ ***************************************************/
/ * t est Load */
/ * */
/ * Test s t r ansf er r i ng dat a f r omExpor t ' s Get Buf f er */
/ * t o Load' s Put Buf f er . Uses t he f ol l owi ng st eps: */
/ * */
/ * 1. Set up and I ni t i at e Load dr i ver */
/ * 2. Quer y buf f er l ayout f r omLoad */
/ * 3. Pass Load buf f er l ayout t o Expor t dr i ver */
/ * 4. I ni t i at e Expor t dr i ver */
/ * 5. Tr ansf er buf f er s f r omGet Buf f er t o Put Buf f er */
/ * 6. Cal l Load' s EndAcqui si t i on & Appl yRows */
/ * 7. Ter mi nat e Load and Expor t */
/ ***************************************************/
voi d Gener i cDr i ver : : t est Expor t ToLoad( )
{
t i me_t now;
t i me( &now) ;
i nt l dSt at us = 0;
i nt expSt at us = 0;
i nt quer ySt at us = 0;
char *er r or Msg = NULL;
RowCount s l dCount ; / * RowCount s st r uct def i ned i n Get Buf f er . h */
char *dat apt r ;
TD_Lengt h dat al en;
char *msg = ( char *) mal l oc( 256) ;
/ **********************************************
* Ret r i eve Opt i ons Fr omOpt i on Fi l e
**********************************************/
i nt numSessi ons = m_om- > get NumSessi ons( ) ;
char *t dp_i d = st r dup( m_om- > get TdpI d( ) . c_st r ( ) ) ;
char *user _name = st r dup( m_om- > get User Name( ) . c_st r ( ) ) ;
char *user _passwor d = st r dup( m_om- > get User Passwor d( ) . c_st r ( ) ) ;
char *t ar get _t abl e = st r dup( m_om- > get Tar get Tabl e( ) . c_st r ( ) ) ;
char *t ar get _t abl e_expor t = st r dup( m_om- >
get Tar get Tabl eExpor t ( ) . c_st r ( ) ) ;
char *l og_t abl e = st r dup( m_om- > get LogTabl e( ) . c_st r ( ) ) ;
char *er r or _t abl e_1 = st r dup( m_om- > get Er r or Tabl e1( ) . c_st r ( ) ) ;
char *er r or _t abl e_2 = st r dup( m_om- > get Er r or Tabl e2( ) . c_st r ( ) ) ;
char *i ns_st at ement = ( char *) mal l oc( 1024) ;
char *sel _st at ement = ( char *) mal l oc( 1024) ;
spr i nt f ( i ns_st at ement , " I NSERT I NTO %s; " , t ar get _t abl e) ;
/ / spr i nt f ( i ns_st at ement , "I NSERT I NTO %s( : col 1,
: col 2) ; " , t ar get _t abl e) ;
spr i nt f ( sel _st at ement , " SELECT * FROM %s; " , t ar get _t abl e_expor t ) ;

cout << " ######################### OUTPUT START
#########################" \
<< endl ;
cout << " \ nTest Descr i pt i on : Gener i cDr i ver sampl e" << endl ;
cout << " Dat e : " << ct i me( &now) ;
Connect i on *l dConn = new Connect i on( ) ; / * Load */
Connect i on *expConn = new Connect i on( ) ; / * Expor t */
/ **********************************************
**********************************************/
l dConn - > AddAt t r i but e( TD_SYSTEM_OPERATOR, TD_LOAD) ;
expConn - > AddAt t r i but e( TD_SYSTEM_OPERATOR, TD_EXPORT) ;
expConn - > AddAt t r i but e( TD_TRACE_OUTPUT, " expor t L. t xt " ) ;
expConn - > AddAr r ayAt t r i but e( TD_TRACE_LEVEL, 2, TD_OPER_ALL, \
TD_GENERAL, NULL) ;

l dConn - > AddAt t r i but e( TD_TRACE_OUTPUT, " l oad. t xt " ) ;
l dConn - > AddAr r ayAt t r i but e( TD_TRACE_LEVEL, 2, TD_OPER_ALL, \
TD_GENERAL, NULL) ;
/ **********************************************
**********************************************/
l dConn - > AddAt t r i but e( TD_TDP_I D, t dp_i d) ;
l dConn - > AddAt t r i but e( TD_USER_NAME, user _name) ;
l dConn - > AddAt t r i but e( TD_USER_PASSWORD, user _passwor d) ;
l dConn - > AddAt t r i but e( TD_TARGET_TABLE, t ar get _t abl e) ;
l dConn - > AddAt t r i but e( TD_LOG_TABLE, l og_t abl e) ;
l dConn - > AddAt t r i but e( TD_ERROR_TABLE_1, er r or _t abl e_1) ;
l dConn - > AddAt t r i but e( TD_ERROR_TABLE_2, er r or _t abl e_2) ;
l dConn - > AddAt t r i but e( TD_MAX_SESSI ONS, numSessi ons) ;
l dConn - > AddAt t r i but e( TD_MI N_SESSI ONS, numSessi ons) ;
l dConn - > AddAt t r i but e( TD_WI LDCARDI NSERT, " Yes" ) ;
/ / l dConn - > AddAt t r i but e( TD_CHARSET, " UTF8" ) ;
/ / l dConn - > AddAt t r i but e( TD_CHARSET, " UTF16" ) ;
expConn - > AddAt t r i but e( TD_TDP_I D, t dp_i d) ;
expConn - > AddAt t r i but e( TD_USER_NAME, user _name) ;
expConn - > AddAt t r i but e( TD_USER_PASSWORD, user _passwor d) ;
expConn - > AddAt t r i but e( TD_SELECT_STMT, sel _st at ement ) ;
expConn - > AddAt t r i but e( TD_MAX_SESSI ONS, numSessi ons) ;
expConn - > AddAt t r i but e( TD_MI N_SESSI ONS, numSessi ons) ;
expConn - > AddAt t r i but e( TD_RETN_ACT_DATATYPE, " FOO" ) ;
/ / expConn - > AddAt t r i but e( TD_CHARSET, " UTF8" ) ;
/ / expConn - > AddAt t r i but e( TD_CHARSET, " UTF16" ) ;
/ **********************************************
* Add Schema
**********************************************/
Schema* schema = NULL;

cout << " \ n%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%" << endl ;
cout << " EXPORT OPERATOR CONNECTI ON I NFO " << endl ;
cout << " %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%" << endl ;
cout << " Oper at or t ype : EXPORT" << endl ;
cout << " TDP I D : " << t dp_i d << endl ;
cout << " TDP user name : " << user _name << endl ;
cout << " TDP passwor d : <not di spl ayabl e>" << endl ;
cout << " Tar get Tabl e : " << t ar get _t abl e_expor t << endl ;
cout << " DML St at ement : " << sel _st at ement << endl ;
/ **********************************************
* I ni t i at e Expor t Dr i ver
**********************************************/
cout << " \ n%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%" << endl ;
cout << " I NI TI ATE PHASE " << endl ;
cout << " %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%" << endl ;
expSt at us = expConn - > I ni t i at e( ) ;
i f ( expSt at us >= TD_Er r or )
{
cout << " Er r or occur ed dur i ng Expor t I ni t i at e" << endl ;
expConn - > Get Er r or I nf o( &er r or Msg, &er r or Type) ;
i f ( er r or Msg ! = NULL )
{
}
el se
{
}
}
el se
{
cout << " Expor t Dr i ver i ni t i at ed Successf ul l y" << endl ;
/ **********************************************
* Add Schema f or l oad
**********************************************/
cout << " \ n%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%" << endl ;
cout << " COLUMN I NFO " << endl ;
cout << " %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%" << endl ;
Schema* dynami cSchema;
i nt r et ur nVal ue = expConn - > Get Schema( &dynami cSchema) ;
l dConn - > AddSchema( dynami cSchema) ;
i f ( r et ur nVal ue < TD_Er r or && r et ur nVal ue ! = TD_Unavai l abl e )
{
i nt Count = dynami cSchema - > Get Col umnCount ( ) ;
vect or <Col umn*> col umn( MAX) ;
cout << " Col umn Count : " << Count << endl ;
f or ( vect or <Col umn*>: : si ze_t ype i =0; i < Count ; i ++)
{
col umn[ i ] = dynami cSchema - > Get Col umn( i ) ;
char * Name = col umn[ i ] - > Get Name( ) ;
TD_Dat aType dat aType = ( TD_Dat aType) col umn[ i ] - > Get Dat aType( ) ;
i nt pr eci si on = col umn[ i ] - > Get Pr eci si on( ) ;
i nt scal e = col umn[ i ] - > Get Scal e( ) ;
cout << endl ;
cout << "Col umn: " << i +1 << " I nf o" <<endl ;
cout << "Name: " << Name << endl ;
cout << "Dat aType: " << dat aType << endl ;
cout << "Pr eci si on: " << pr eci si on << endl ;
cout << "scal e: " << scal e << endl ;
}
}
el se
{
pr i nt f ( " Get Schema f ai l ed wi t h st at us ! = %d" , r et ur nVal ue) ;
}
/ **********************************************
* Quer y Ver si on Number
**********************************************/
quer ySt at us = expConn - > Get Event ( TD_Evt _Ver si on, &dat apt r , &dat al en) ;
cout << " \ n%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%" << endl ;
cout << " VERSI ON I NFO " << endl ;
cout << " %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%" << endl ;
i f ( quer ySt at us < TD_Er r or && quer ySt at us ! = TD_Unavai l abl e )
{
cout << " TPTAPI Ver si on : " ;
cout << *( ( char **) dat apt r ) << endl ;
cout << " Oper at or Ver si on: " ;
cout << *( ( char **) ( dat apt r +si zeof ( char **) ) ) << endl ;
}
el se
{
pr i nt St at us( " TD_Evt _Ver si on event f ai l ed wi t h st at us " , quer ySt at us) ;
}
/ **********************************************
* Add DMLGr oups
**********************************************/
DMLGr oup *dml Gr = new DMLGr oup( ) ;
dml Gr - > AddSt at ement ( i ns_st at ement ) ;
l dConn - > AddDMLGr oup( dml Gr , &dml Gr oupI ndex) ;
cout << " \ n%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%" << endl ;
cout << " LOAD OPERATOR CONNECTI ON I NFO " << endl ;
cout << " %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%" << endl ;
cout << " Oper at or t ype : LOAD" << endl ;
cout << " TDP I D : " << t dp_i d << endl ;
cout << " TDP user name : " << user _name << endl ;
cout << " TDP passwor d : <not di spl ayabl e>" << endl ;
cout << " Tar get Tabl e : " << t ar get _t abl e << endl ;
cout << " DML St at ement : " << i ns_st at ement << endl ;
/ **********************************************
* I ni t i at e Load Dr i ver
**********************************************/
cout << " \ n%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%" << endl ;
cout << " I NI TI ATE PHASE " << endl ;
cout << " %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%" << endl ;
l dSt at us = l dConn - > I ni t i at e( ) ;
i f ( l dSt at us < TD_Er r or )
{
cout << " Load Dr i ver i ni t i at ed Successf ul l y" << endl ;

/ **********************************************
* Quer y Ver si on Number
**********************************************/
quer ySt at us = l dConn - > Get Event ( TD_Evt _Ver si on, &dat apt r , &dat al en) ;
cout << " \ n%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%" << endl ;
cout << " VERSI ON I NFO " << endl ;
cout << " %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%" << endl ;

{
cout << " TPTAPI Ver si on : " ;
cout << *( ( char **) dat apt r ) << endl ;
cout << " Oper at or Ver si on: " ;
cout << *( ( char **) ( dat apt r +si zeof ( char **) ) ) << endl ;
}
el se
{
pr i nt St at us( " TD_Evt _Ver si on event f ai l ed wi t h st at us " ,
quer ySt at us) ;
}
/ **********************************************
* Acqui si t i on
**********************************************/
cout << " \ n%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%" << endl ;
cout << " ACQUI SI TI ON PHASE " << endl ;
cout << " %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%" << endl ;
char * dat aBuf f er ;
TD_Lengt h dat aLen = 0;
i nt count = 0;
i nt t r ansf er Done = 0;
whi l e( ! t r ansf er Done)
{
/ * Get a buf f er f r omExpor t */
expSt at us = expConn - > Get Row( &dat aBuf f er , &dat aLen) ;
{
spr i nt f ( msg, " Get Buf f er f ai l ed on buf f er %d wi t h st at us " ,
count +1) ;
pr i nt St at us( msg, expSt at us) ;
t r ansf er Done = 1;
}
el se i f ( expSt at us == TD_END_Met hod )
{
cout << "End of Dat a Reached" << endl ;
}
el se
{
/ * Pass Buf f er t o Load */
l dSt at us = l dConn - > Put Row( dat aBuf f er , dat aLen) ;
i f ( l dSt at us ! = TD_Success )
{
spr i nt f ( msg, " Put Buf f er f ai l ed on buf f er %d wi t h st at us " ,
count +1) ;
pr i nt St at us( msg, l dSt at us) ;
}
el se
{
count ++;
/ * Get Load Row Count s */
}
}
}
i f ( l dSt at us < TD_Er r or && expSt at us < TD_Er r or )
{
/ **********************************************
**********************************************/
l dSt at us = l dConn - > EndAcqui si t i on( ) ;
{
cout << "Acqui si t i on compl et ed Successf ul l y" << endl ;
/ * Get Load Row Count s */
quer ySt at us = l dConn - > Get Event ( TD_Evt _RowCount s, &dat apt r , \
&dat al en) ;
{
l dCount = *( ( RowCount s*) dat apt r ) ;
cout << " Rows Recei ved : " ;
cout << l dCount . RowsRecei ved << endl ;
cout << " Rows Sent : " ;
cout << l dCount . RowsSent << endl ;
cout << " Rows Appl i ed : " ;
cout << l dCount . RowsAppl i ed << endl ;
}
el se
{
cout << " TD_Evt _RowCount s I nf o Not Avai l abl e" << \
quer ySt at us << endl ;
}
/ **********************************************
* Appl i cat i on
**********************************************/
cout << "\ n%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%" << endl ;
cout << " APPLI CATI ON PHASE " << endl ;
cout << "%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%" << endl ;
l dSt at us = l dConn - > Appl yRows( ) ;
{
cout << " Rows Appl i ed Successf ul l y" << endl ;
cout << " Tr ansf er compl et ed successf ul l y" << endl ;
cout << " Tr ansf er r ed " << count << " buf f er s" << endl ;
/ * Get Expor t Row Count */
quer ySt at us = expConn - > Get Event ( TD_Evt _Expor t Count , \
&dat apt r , &dat al en) ;
{
cout << " TD_Evt _Expor t Count : " ;
cout << *( ( i nt *) dat apt r ) << endl ;
}
el se
{
pr i nt St at us( " TD_Evt _Expor t Count event f ai l ed wi t h st at us",
\
quer ySt at us) ;
}
/ * Get Load Appl y Count */
quer ySt at us = l dConn - > Get Event ( TD_Evt _Appl yCount , &dat apt r ,
\
&dat al en) ;
{
cout << "TD_Evt _Appl yCount : " ;
cout << *( ( i nt *) dat apt r ) << endl ;
}
el se
{
pr i nt St at us( " TD_Evt _Appl yCount event f ai l ed wi t h st at us" , \
quer ySt at us) ;
}
}
el se
{
l dConn - > Get Er r or I nf o( &er r or Msg, &er r or Type) ;
{
}
el se
{
}
}
}
el se
{
{
}
el se
{
}
}
}
el se
{
i f ( l dSt at us >= TD_Er r or )
{
cout << " Load Er r or occur ed dur i ng Acqui si t i on" << endl ;
{
}
el se
{
}
}
{
cout << " Expor t Er r or occur ed dur i ng Acqui si t i on" << endl ;
{
}
el se
{
}
}
}
}
el se
{
cout << " Er r or occur ed dur i ng Load I ni t i at e" << endl ;
{
}
el se
{
}
}
/ * Ter mi nat e Dr i ver s
**********************************************/
cout << " \ n%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%" << endl ;
cout << " TERMI NATE PHASE " << endl ;
cout << " %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%" << endl ;

l dSt at us = l dConn - > Ter mi nat e( ) ;
expSt at us = expConn - > Ter mi nat e( ) ;
i f ( l dSt at us >= TD_Er r or | | expSt at us >= TD_Er r or )
{
/ * Get Er r or I nf or mat i on */
i f ( l dSt at us >= TD_Er r or )
{
cout << " Er r or occur ed dur i ng Load Ter mi nat e" << endl ;
{
}
el se
{
}
}
el se
{
cout << " Load Ter mi nat ed Successf ul l y" << endl ;
}
{
cout << " Er r or occur ed dur i ng Expor t Ter mi nat e" << endl ;
{
}
el se
{
}
}
el se
{
cout << " Expor t Ter mi nat ed Successf ul l y" << endl ;
}
}
/ **********************************************
* Cl ean Up
**********************************************/
cout << " Del et i ng obj ect s" << endl ;

del et e dml Gr ;
del et e dynami cSchema;
del et e l dConn;
del et e expConn;
f r ee( user _name) ;
f r ee( user _passwor d) ;
f r ee( t ar get _t abl e) ;
f r ee( t ar get _t abl e_expor t ) ;
f r ee( t dp_i d) ;
f r ee( l og_t abl e) ;
f r ee( er r or _t abl e_1) ;
f r ee( er r or _t abl e_2) ;
f r ee( i ns_st at ement ) ;
f r ee( sel _st at ement ) ;
f r ee( msg) ;

cout << " *** Expor t t o Load Compl et e ***" << endl ;
cout <<" \ n######################## OUTPUT END ####################"
<< endl ;
}
}
/ *************************** Ut i l i t y Funct i ons
*******************************/
/ ***********************************************
* Funct i on pr i nt s st r i ng ver si on of st at us code
************************************************/
voi d Gener i cDr i ver : : pr i nt St at us( char * msg, i nt code)
{
cout << msg;
swi t ch( code)
{
case TD_Success:
cout << " TD_Success" ;
br eak;
case TD_SYNC_Bar r i er :
cout << " TD_SYNC_Bar r i er " ;
br eak;
case TD_SYNC_TELI NFO:
cout << " TD_SYNC_TELI NFO" ;
br eak;
case TD_END_Met hod:
cout << " TD_END_Met hod" ;
br eak;
case TD_Unavai l abl e:
cout << " TD_Unavai l abl e" ;
br eak;
case TD_Er r or :
cout << " Er r or Code: TD_Er r or " ;
br eak;
def aul t :
cout << " Er r or Code: " << code;
br eak;
}
cout << endl ;
}
/ ***************************************
* Funct i on set s i nput f i l e name
***************************************/
voi d Gener i cDr i ver : : set I nput ( char * f name)
{
i f ( i nput Fi l eName ! = NULL )
{
del et e i nput Fi l eName;
}
i nput Fi l eName = st r dup( f name) ;
}
/ ***************************************
* Funct i on set s out put f i l e name
***************************************/
voi d Gener i cDr i ver : : set Out put ( char * f name)
{
i f ( out put Fi l eName ! = NULL )
{
del et e out put Fi l eName;
}
out put Fi l eName = st r dup( f name) ;
}
/ ***************************************
* Funct i on r eads i n a r ow of dat a
***************************************/
i nt Gener i cDr i ver : : Get RowDat a( char * r owBuf f er , si ze_t r owLengt h)
{
unsi gned shor t r l engt h;
/ / Cl ose Fi l e i f End Si gnal Recei ved
i f ( r owLengt h <= 0 )
{
i f ( i nput St r eam! = NULL )
{
f cl ose( i nput St r eam) ;
}
r et ur n - 1;
}
/ / Open Fi l e i f not al r eady open
i f ( i nput St r eam== NULL )
{
i nput St r eam= f open( i nput Fi l eName, " r b" ) ;
i f ( i nput St r eam== NULL )
{
cout << " Er r or openi ng f i l e " << i nput Fi l eName << endl ;
r et ur n - 1;
}
}
/ / Read t he l enght of each r ecor d. . r ead f i r st t wo byt es
si ze_t r ecLen =f r ead( r owBuf f er , 1, ( si ze_t ) 2, i nput St r eam) ;
i f ( r ecLen < 1 )
{
i f ( f eof ( i nput St r eam) )
{
cout << " End of f i l e r eached" << endl ;
{
}
r et ur n - 1;
}
el se
{
/ * r et ur n some r ead er r or her e and exi t */
cout << " r ead er r or " << endl ;
{
}
r et ur n - 1;
}
}
/ / r ead r ow of dat a wi t h si ze r l engt h
memcpy( &r l engt h, r owBuf f er , si zeof ( unsi gned shor t ) ) ; / * DR124305 */
si ze_t r ecoLen = f r ead( r owBuf f er +2, 1, ( si ze_t ) r l engt h+1, i nput St r eam) ;
r et ur n 0;
}
/ *****************************************************
* Funct i on wr i t es out a r ow of dat a i n i ndi cat or mode
******************************************************/
i nt Gener i cDr i ver : : Wr i t eRowDat a( char * dat a, TD_Lengt h dat aLen)
{
i f ( dat a ! = NULL )
{
i f ( out put St r eam== NULL )
{
out put St r eam= f open( out put Fi l eName, " wb" ) ;
{
cout << " Er r or openi ng f i l e " << out put Fi l eName << endl ;
r et ur n - 1;
}
}
unsi gned l ong i = 0;
unsi gned shor t shor t dat aLen = ( unsi gned shor t ) dat aLen;
char * r owBuf f er = ( char *) mal l oc( dat aLen+20) ;
memcpy( r owBuf f er , &shor t dat aLen, 2) ;
f or ( i = 0; i < dat aLen; i ++)
{
r owBuf f er [ i +2] = dat a[ i ] ;
}
r owBuf f er [ i +2] = 0x0a;
/ / f pr i nt f ( st r eam, " %s\ n" , r owBuf f er +1) ; / / account f or i ndi cat or byt e
f wr i t e( r owBuf f er , dat aLen+3, 1, out put St r eam) ;
f r ee( r owBuf f er ) ;
}
el se
{
i f ( out put St r eam! = NULL )
{
f cl ose( out put St r eam) ;
}
r et ur n - 1;
}
r et ur n 0;
}
/ *****************************************************
* Funct i on wr i t es out a buf f er of dat a i n i ndi cat or mode
******************************************************/
i nt Gener i cDr i ver : : Wr i t eBuf f er Dat a( char * dat a, TD_Lengt h dat aLen)
{
i f ( dat a ! = NULL )
{
{
out put St r eam= f open( out put Fi l eName, " wb" ) ;
{
cout << " Er r or openi ng f i l e " << out put Fi l eName << endl ;
r et ur n - 1;
}
}
f wr i t e( dat a, dat aLen, 1, out put St r eam) ;
}
el se
{
{
f cl ose( out put St r eam) ;
}
r et ur n - 1;
}
r et ur n 0;
}
CHAPTER 7
Parallelism Enabling Protocol
The Teradata PT parallelism-enabling protocol can be used in multi-node, multi-process, and
multi-threaded applications. This chapter describes a Teradata PT Load parallel application in
these main sections:
Overview
Teradata PT allocates the sessions as evenly as possible among the master and the slave
instances. Each instance is connected with the number of sessions equaling the max-session
value divided by the number of instances. Multiple parallel instances are used to load and
export rows to and from the Teradata Database target tables. For example, Teradata PT load
parallel applications can load data into the same table on different nodes, as shown in the
following illustration:
Figure 7: Master and Slave Parallel Relationships during Load and Export
Overview
Application
Parallel Communication Area
Parallel Processing Return Codes
Special Parallel Parameters
Parallel Checkpoint and Restart
Parallel Errors
Parallel Run-Time Statistics
Code Example
Target tables
in
Teradata Database
2516A005
Teradata PT API slave
application running
on node 2
TELINFO
Teradata
PT
API
Teradata PT API master
application running
on node 1
Teradata PT API slave
application running
on node 3
Data Pipe 2 Data Pipe 1 Data Pipe 3
Teradata
PT
API
Teradata
PT
API TELINFO TELINFO
Chapter 7: Parallelism Enabling Protocol
Application
Note: Multiple threads should not share the same Teradata PT Connection object.
The same parallelism-enabling protocol is supported in all four Teradata PT drivers to provide
a consistent application interface. However, since the Stream driver does not require the
Teradata Database to lock the target tables that are being updated, the choice can be made to
run multiple parallel Stream application jobs instead of multiple instances in multi-node,
multi-process, and multi-threaded applications.
The master and the slaves must run on the client machines that have the same endian mode
(big-endian mode or little-endian mode). For channel-attached z/OS platforms, the master
and slaves must all run on channel-attached z/OS platforms.
Application
All master and slave applications must be synchronized:
After receiving a TD_SYNC_Barrier or TD_SYNC_TELINFO status code.
All instances should enter and exit the same following methods together:
Initiate
Checkpoint/Restart
EndAcquisition
ApplyRows
Terminate
Because of the synchronization, the instance on the slower machine will affect the instance on
the faster machine. It is strongly recommended that you run all of your instances on machines
that have the same power throughput.
Parallel Communication Area
The Teradata PT communication area, referred to as TELINFO, should be used for
communication across nodes, among processes, and threads. It contains session information
for linking the parallel instances into one job.
The master application also needs to distribute the Teradata PT communication area
(TELINFO) to the slave applications or copy it to the slave memory.
Parallel Processing Return Codes
Teradata PT supplies the following return codes for two types of synchronization:
TD_SYNC_TELINFO - Synchronize the TELINFO communication area from the master
to the slave instances, and do not proceed until all instances reach this barrier.
TD_SYNC_Barrier - Do not proceed until all instances reach this barrier.
The Teradata PT parallel synchronization is master driven. All slave instances will receive the
same synchronization return code in the same phase. The master, however, may receive a
different synchronization return code. In these cases, the action taken should follow the
Application
synchronization code returned by the master. Table 32 lists possible synchronization return
code combinations and the proper action to take.
Usage Notes
The master instance job must be started before starting the slave instance jobs
The CLIv2 environment variable THREADONOFF must be set to one for running the
Teradata PT multi-threaded application. See Teradata Call-Level Interface Version 2
Reference for Network-Attached Systems for details about this variable.
Special Parallel Parameters
The following attributes are required for both the master and slave instances in addition to the
normally required attributes:
TD_INSTANCE_NUM
TD_MAX_INSTANCES
Table 32: Synchronization Return Code Combinations and Suggested Actions
Received by Master Received by Slave Suggested Action
TD_SYNC_Barrier TD_SYNC_Barrier Call the method again which returned the
barrier code after all instances reach this
barrier.
TD_SYNC_Barrier TD_END_Method Master calls the method again which
returned the barrier code. Slave(s) wait to
call the next method until Master receives
TD_END_Method.
TD_SYNC_TELINFO TD_SYNC_Barrier Master calls the GetTELINFO function to
get the TELINFO area and passes a copy of
the TELINFO area to each of the slaves.
Slave(s) call the PutTELINFO function to
process the masters TELINFO area. Master
and slave(s) call the method again which
returned the barrier code after all instances
reach this barrier and after TELINFO area
has been synchronized.
TD_SYNC_TELINFO TD_SYNC_TELINFO Master calls the GetTELINFO function to
get the TELINFO area and passes a copy of
the TELINFO area to each of the slaves.
Slave(s) call the PutTELINFO function to
process the masters TELINFO area. Master
and slave(s) call the method again which
returned the barrier code after all instances
reach this barrier and after TELINFO area
has been synchronized.
TD_END_Method TD_END_Method Proceed to next method after all instances
receive TD_END_Method.
Application
The masters value for TD_INSTANCE_NUM is one and the slaves values for
TD_INSTANCE_NUM starts at two and increments with each new slave. An instances
number is used to access its designated area within the TELINFO area. No two instances can
have the same value for TD_INSTANCE_NUM. The value for TD_INSTANCE_NUM cannot
be greater than the value for TD_MAX_INSTANCES.
In a multiple instance environment, only the master uses the TD_MAX_SESSIONS and
TD_MIN_SESSIONS attributes. The master instance will distribute the sessions amongst
itself and the slave instances. The number of sessions needs to be greater than or equal to the
number of instances. If no session preferences are specified, the default will be one session per
instance.
Beyond these attributes, all other attributes, schemas, and DML groups must be the same for
both the master and the slave instances.
Parallel Checkpoint and Restart
All instances must call the Checkpoint function in unison. While only the master instance will
issue the actual checkpoint to the database, all the slave instances must call the Checkpoint
function at the same time to ensure that all rows loaded using the PutRow function or the
PutBuffer function are sent to the database prior to the Checkpoint.
Checkpoint data for each instance must be copied and stored separately. Each instance must
use its own checkpoint data when restarting. See Add Checkpoint and Restart on page 33 for
more information.
Parallel Errors
Errors can be reported by both master and slave instances. If an error occurs, the instance
which discovered the error is responsible for calling the GetErrorInfo function to retrieve the
detailed error information. If one or more instances fail, then all instances need to terminate
immediately.
If any of the instances, master or slave, receive the TD_Call_EndAcq status code, all instances
should immediately proceed to call the EndAcquisition function. The TD_Call_EndAcq status
code indicates that there is an error which requires that the acquisition method be aborted.
Upon completing the calls to the EndAcquisition function, the instance(s) which received the
TD_Call_EndAcq status code will be returned an error code for the problem which caused the
acquisition method to abort. At this time, these instances will be able to retrieve additional
error information relating to this error code through the use of the GetErrorInfo function.
After calling the EndAcquisition function and retrieving error information, all instances
should proceed to call the Terminate function and end the job.
Parallel Run-Time Statistics
The run-time statistics returned by the GetEvent function pertain only to that particular
instance and not to the overall job. The master and slave instances may call the GetEvent
method asynchronously.
Code Example
Code Example
The following is a simple example of how to utilize Teradata PT in a parallel environment. The
code is not intended for actual use but rather to highlight the keys to the Teradata PT parallel
process. The architecture of the example could be implemented in either a multi-threaded or
multi-process environment.
This is a multi-instance example using the Load driver. The structure of the example involves
two components: a master component and a slave component.
The master component has two responsibilities: handling its designated portion of the
workload (loading a subset of the total rows) and maintaining the synchronization between all
of the instances.
The following is the main execution method for the master instance component:
usi ng t er adat a: : cl i ent : : API ;
Connect i on* mConnect i on = new Connect i on( ) ;
/ **********************************************
* Add Connect i on Par amet er s
**********************************************/
mConnect i on- >AddAt t r i but e( TD_SYSTEM_OPERATOR, TD_LOAD) ;
/ * Add At t r i but es */
/ / Mast er I nst ance Speci f i c At t r i but es
/ / TD_I NSTANCE_NUM: Mast er i s al ways 1
/ / TD_MAX_I NSTANCES: Tot al number of i nst ances i ncl udi ng mast er
/ / TD_MAX_SESSI ONS: Number of sessi ons ar e di vi ded bet ween mast er
/ / and sl aves
/ / TD_MI N_SESSI ONS
/ * Add Schema */
/ * Add DMLGr oups */
/ / Not e: Except f or t he speci al at t r i but es l i st ed above, bot h mast er
/ / and sl ave i nst ances shoul d have exact l y t he same Connect i on
/ / Par amet er s.
/ **********************************************
* I ni t i at e
**********************************************/
r et ur nVal ue = mConnect i on- >I ni t i at e( ) ;
swi t ch ( r et ur nVal ue ) {
/ / 1) Wai t f or al l sl aves t o si gnal bar r i er
/ / 2) Tel l sl aves t o pr oceed
/ / 3) Cont i nue
br eak;
/ / 2) Use Get TELI NFO t o r et r i eve TELI NFO ar ea
/ / 3) Pass copy of TELI NFO ar ea t o sl aves
/ / 5) Cont i nue
br eak;
Code Example
/ / Met hod i s Compl et e
br eak;
def aul t :
/ / When er r or s occur :
/ / 1) Tel l sl aves t o cal l Ter mi nat e al l i nst ances
/ / must Ter mi nat e synchr onousl y. See Ter mi nat e
/ / set up bel ow.
/ / 2) Af t er Ter mi nat e, get er r or i nf o
/ / 3) Qui t or r est ar t
r et ur n TD_ERROR;
}
}
/ / Wai t f or sl aves t o f i ni sh, t hen cont i nue
/ **********************************************
* Acqui si t i on
**********************************************/
char r owBuf f er [ 256] ;
unsi gned shor t r owLengt h = 0;
bool doneExpor t i ng = f al se;
r cget r ow = 0;
r et ur nVal ue = 0;
whi l e ( ! doneExpor t i ng) {
/ / Get Row For Load
r cGet r ow = get Row( r owBuf f er ) ;
i f ( r cGet r ow ! = TD_END_Met hod) {
/ / Load Row
r owLengt h = *( ( unsi gned shor t *) r owBuf f er ) ;
r et ur nVal ue = Put Row( r owBuf f er +2, r owLengt h ) ;
case TD_Success:
/ / Cont i nue t o Next Row
br eak;
def aul t :
/ / set up bel ow.
r et ur n TD_ERROR;
}
}el se {
/ * End Acqui si t i on Phase */
doneExpor t i ng = t r ue;
r et ur nVal ue = mConnect i on- >EndAcqui si t i on( ) ;
/ / 3) Cont i nue
br eak;
/ / 5) Cont i nue
br eak;
/ / Acqui si t i on Compl et e
br eak;
Code Example
def aul t :
/ / set up bel ow.
r et ur n TD_ERROR;
}
}
}
/ **********************************************
* Appl i cat i on
**********************************************/
r et ur nVal ue = mConnect i on- >Appl yRows( ) ;
/ / 3) Cont i nue
br eak;
/ / 5) Cont i nue
br eak;
br eak;
def aul t :
/ / set up bel ow.
r et ur n TD_ERROR;
}
}
/ **********************************************
* Ter mi nat e
**********************************************/
r et ur nVal ue = mConnect i on- >Ter mi nat e( ) ;
/ / 3) Cont i nue
br eak;
/ / 5) Cont i nue
br eak;
br eak;
Code Example
def aul t :
/ / set up bel ow.
r et ur n TD_ERROR;
}
}
/ **********************************************
* Cl ean Up
**********************************************/
/ / del et e Schema obj ect s
/ / del et e DMLGr oup obj ect s
del et e mConnect i on;
r et ur n r et ur nVal ue;
The slave instance has two responsibilities: handling its designated workload (loading a subset
of the total rows) and reporting synchronization codes to the master and following the
masters instructions.
The following is the main execution method of the slave component:
usi ng t er adat a: : cl i ent : : API ;
Connect i on* mConnect i on = new Connect i on( ) ;
/ **********************************************
* Add Connect i on Par amet er s
**********************************************/
mConnect i on- >AddAt t r i but e( TD_SYSTEM_OPERATOR, TD_LOAD) ;
/ * Add At t r i but es */
/ / Sl ave I nst ance Speci f i c At t r i but es
/ / TD_I NSTANCE_NUM: Sl ave number must be gr eat er t han 1 and
/ / no sl ave can have same i nst ance number as anot her i nst ance.
/ / TD_MAX_I NSTANCES: Tot al number of i nst ances i ncl udi ng mast er
/ / Thi s must be set cor r ect l y as t he sl ave wi l l
/ / use t hi s when accessi ng TELI NFO ar ea.
/ * Add Schema */
/ * Add DMLGr oups */
/ / Not e: Except f or t he speci al at t r i but es l i st ed above, bot h mast er
/ / and sl ave i nst ances shoul d have exact l y t he same Connect i on
/ / Par amet er s.
/ **********************************************
* I ni t i at e
**********************************************/
r et ur nVal ue = mConnect i on- >I ni t i at e( ) ;
/ / 1) Si gnal bar r i er t o mast er
/ / 2) Wai t f or mast er si gnal
/ / 3) Cont i nue
br eak;
/ / 2) Use Put TELI NFO t o set t he TELI NFO
/ / ar ea passed by t he mast er .
/ / 5) Cont i nue
br eak;
Code Example
br eak;
def aul t :
/ / 1) Si gnal er r or t o mast er al l i nst ances
/ / set up bel ow.
r et ur n TD_ERROR;
}
}
/ / Wai t f or mast er t o f i ni sh, t hen cont i nue
/ **********************************************
* Acqui si t i on
**********************************************/
char r owBuf f er [ 256] ;
unsi gned shor t r owLengt h = 0;
bool doneExpor t i ng = f al se;
r cget r ow = 0;
whi l e ( ! doneExpor t i ng) {
/ / Get Row For Load
r cGet r ow = get Row( r owBuf f er ) ;
i f ( r cGet r ow ! = TD_END_Met hod) {
/ / Load Row
r owLengt h = *( ( unsi gned shor t *) r owBuf f er ) ;
r et ur nVal ue = Put Row( r owBuf f er +2, r owLengt h ) ;
case TD_Success:
/ / Cont i nue t o Next Row
br eak;
def aul t :
/ / set up bel ow.
r et ur n TD_ERROR;
}
}el se {
/ * End Acqui si t i on Phase */
doneExpor t i ng = t r ue;
r et ur nVal ue = mConnect i on- >EndAcqui si t i on( ) ;
/ / 3) Cont i nue
br eak;
/ / 5) Cont i nue
br eak;
/ / Acqui si t i on Compl et e
br eak;
Code Example
def aul t :
/ / set up bel ow.
r et ur n TD_ERROR;
}
}
}
/ **********************************************
* Appl i cat i on
**********************************************/
r et ur nVal ue = mConnect i on- >Appl yRows( ) ;
/ / 3) Cont i nue
br eak;
/ / 5) Cont i nue
br eak;
br eak;
def aul t :
/ / set up bel ow.
r et ur n TD_ERROR;
}
}
/ **********************************************
* Ter mi nat e
**********************************************/
r et ur nVal ue = mConnect i on- >Ter mi nat e( ) ;
/ / 3) Cont i nue
br eak;
/ / 5) Cont i nue
br eak;
br eak;
Code Example
def aul t :
/ / must Ter mi nat e synchr onousl y.
r et ur n TD_ERROR;
}
}
/ **********************************************
* Cl ean Up
**********************************************/
/ / del et e Schema obj ect s
/ / del et e DMLGr oup obj ect s
del et e mConnect i on;
r et ur n r et ur nVal ue;
Code Example
CHAPTER 8
Using Teradata PT in an External Stored
Procedure
Teradata PT can be called from within an external stored procedure (XSP). An XSP is a code
module, written in C or C++, which resides on the Teradata Database and is executed using
the SQL CALL statement. Using Teradata PT in an XSP provides a potential performance
improvement by minimizing data transfer between the client and the database server.
Calling the Teradata PT from within an XSP is only supported when using a 12.0 or later
version of the Teradata Database. Using the Teradata PT in a user-defined function (UDF) is
not currently supported.
Topics include:
Coding a Teradata PT External Stored Procedure
Building a Teradata PT External Stored Procedure
Installing a Teradata PT External Stored Procedure
Executing a Teradata PT External Stored Procedure
Getting Started with the External Stored Procedure Example
Coding a Teradata PT External Stored
Procedure
There are no special coding steps for calling the Teradata PT from an XSP. As in all
applications currently using Teradata PT, the XSP must include the Teradata PT header files
and follow the standard Teradata PT coding conventions described in this programmer guide.
Detailed instructions on how to code an XSP are in the External Stored Procedure chapter of
SQL External Routine Programming. See Additional Information on page 6 for more
information on obtaining this Teradata publication.
Building a Teradata PT External Stored
Procedure
The dynamic library containing the Teradata PT XSP should be built before installing the
Teradata PT XSP on the Teradata Database. The Teradata PT package must be installed prior
to building an XSP which uses the Teradata PT.
Chapter 8: Using Teradata PT in an External Stored Procedure
Installing a Teradata PT External Stored
Procedure
The following sections provide an overview and make reference to other documentation to
help with the tasks for installing a Teradata PT XSP onto a Teradata Database.
Installing the Teradata PT onto the Teradata Database
Configuring the Teradata Databases Environment
Using the CREATE PROCEDURE SQL Statement
Installing the Teradata PT onto the Teradata Database
Using the Teradata PT in an XSP requires that the Teradata PT product and all its
dependencies be installed on the machine running the Teradata Database. See the Teradata
Tools and Utilities installation guides for more details.
Configuring the Teradata Databases Environment
To call the Teradata PT from an XSP, configure the Teradata Databases environment to
register the necessary Teradata PT libraries. Depending on the operating system that the
Teradata Database is running on, this may involve relocating specific Teradata PT libraries as
well as setting runtime environment variables using the Cufconfig utility. For more
information on using the Cufconfig utility, see Utilities.
Configuring the Teradata Database on Linux
Before using the CREATE PROCEDURE SQL statement to create a Teradata PT XSP, the
following libraries from the Teradata PT package must be moved into the /usr/tdbms/lib
directory:
libtelapi.so
libpxicu.so
If the default Teradata PT installation is used, these libraries can be found in the
/opt/teradata/client/tbuild/14.00.01/lib64 directory.
After using the CREATE PROCEDURE SQL statement to create a Teradata PT XSP, configure
the Teradata Databases environment to allow the XSP to run. If it is possible to restart the
Teradata Database, use the Cufconfig utility to set the CLIEnvFile variable to register a file with
the following environment variable settings:
NLSPATH=/ OPT/ TERADATA/ CLI ENT/ TBUI LD/ 14. 00. 01/ MSG64/ %N
/ * Def aul t l ocat i on of oper msgs. cat */
COPERR=/ usr / l i b64
COPLI B=/ usr / l i b64
LD_LI BRARY_PATH=/ opt / t er adat a/ cl i ent / t bui l d/ 14. 00. 01/ l i b64
/ * Def aul t l ocat i on of t he dr i ver l i br ar i es */
Add the location of the dynamic library containing the user created XSP to the
LD_LIBRARY_PATH in the environment variable settings file. After setting the CLIEnvFile
variable using the Cufconfig utility, the Teradata Database must be restarted to allow the
database to register the new runtime environment settings.
If it is not possible to restart the Teradata Database, move the following Teradata PT libraries
into the /usr/tdbms/lib directory:
libopcommon.so
libexportop.so (If using the Export driver)
libloadop.so (If using the Load driver)
libstreamop.so (If using the Stream driver)
libupdateop.so (If using the Update driver)
If the default Teradata PT installation is used, these libraries can be found in the following
directory:
/opt/teradata/client/tbuild/14.00.01/lib64
Move the opermsgs.cat message catalog into the / (root) directory. If the default Teradata PT
installation is used, find this catalog in the following directory:
/opt/teradata/client/tbuild/14.00.01/msg64
Lastly, place the dynamic library containing the user created XSP in the /usr/tdbms/lib
directory.
Configuring the Teradata Database on Windows
After installing the Teradata PT package and its dependencies, restart the Teradata Database to
register the changes to the system path. Do this before using the CREATE PROCEDURE SQL
statement to create a Teradata PT XSP. Add the location of the dynamic library containing the
XSP to the system path before restarting the Teradata Database or place the library in a
directory currently included in the Teradata Databases search path.
If restarting the Teradata Database is not possible, move the following Teradata PT libraries to
a directory which is currently included in the Teradata Databases search path:
telapi.lib
telapi.dll
pxicu.dll
opcommon.dll
exportop.dll (If using the Export driver)
loadop.dll (If using the Load driver)
streamop.dll (If using the Stream driver)
updateop.dll (If using the Update driver)
If the default Teradata PT installation is used, find these libraries in the following directory on
32-bit systems:
C:\Program Files\Teradata\Client\14.00.01\Teradata Parallel Transporter\bin
and in the following directory on 64-bit systems:
C:\Program Files\Teradata\Client\14.00.01\Teradata Parallel Transporter\bin64
Move the opermsgs.cat message catalog into a directory which is currently included in the
Teradata Databases search path. If the default Teradata PT installation is used, find this
catalog in the following directory on 32-bit systems:
C:\Program Files\Teradata\Client\14.00.01\Teradata Parallel Transporter\msg
and in the following directory on 64-bit systems:
C:\Program Files\Teradata\Client\14.00.01\Teradata Parallel Transporter\msg64
Lastly, place both the .dll and .lib files containing the user created XSP in a directory currently
included in the Teradata Databases search path.
Using the CREATE PROCEDURE SQL Statement
The CREATE PROCEDURE SQL statement is used to link the dynamic library containing the
user created XSP to the Teradata Database. The Teradata Database user must have the
CREATE EXTERNAL PROCEDURE permission to be able to issue the CREATE
PROCEDURE SQL statement.
The following is an example of a CREATE PROCEDURE SQL statement for an XSP which
uses the Teradata PT:
Executing a Teradata PT External Stored Procedure
CREATE PROCEDURE t pt api xsp
(
I N oper at or t ype VARCHAR( 64) ,
I N CONFI GFI LENAME var char ( 64) ,
I N dat af i l ename VARCHAR( 64)
)
LANGUAGE CPP
MODI FI ES SQL DATA
EXTERNAL NAME
' SP! CLI ! SP! / xspt est / xspt est . so! F! t pt api xsp'
PARAMETER STYLE
SQL;
For more information on using the CREATE PROCEDURE SQL statement, see SQL External
Routine Programming.
Executing a Teradata PT External Stored
Procedure
External Stored Procedures are executed using the SQL CALL statement. For more
information on using the SQL CALL statement to execute an XSP, see SQL External Routine
Programming.
CREATE PROCEDURE
Name of this XSP is tptapixsp.
The procedure has 3 VARCHAR
inputs.
LANGUAGE CPP
Language clause specifies if the XSP is written in
C or C++. This example specifies C++.
MODIFIES SQL DATA (ACCESS CLAUSE)
This clause specifies whether SQL statements are contained
in the XSP.
For XSPs using Teradata PT, the value of the SQL data
access clause is always MODIFIES SQL DATA.
EXTERNAL NAME
Specifies the name and location of all the components needed to
create the XSP.
The Teradata PT requires CLIv2 so the CLI package is always
specified in the external name clause.
In this example xsptest.so is the name of the XSP library location and
its absolute path is specified. On Windows, the name and location of
the XSP .lib file should be specified instead of the .dll file.
The name of the XSPs function is also specified inside the external
name clause. The name of the function is this example is tptapixsp.
LANGUAGE CPP
The parameter style clause indicates the convention to be used
when passing parameters to the XSP. In this example, the SQL
parameter style is being used.
To create a Teradata PT diagnostic log file when using the Teradata PT in an XSP, the XSP
must have write access to the directory when the log file is generated. On Linux, this requires
write access being given to the others group.
Getting Started with the External Stored
Procedure Example
To run the example external stored procedure example
Follow these steps to build, install, and run this example:
1 Install the Teradata PT package.
Install the Teradata PT package on the Teradata Databases machine or on a client
machine. If installed on a client machine, the machine needs to be the same platform as
the Teradata Database machine.
2 Build the Example External Stored Procedure Library.
Go to the Teradata PT sample directory and build the example XSP library using the
makefiles provided or the Visual Studio project file. On Linux, if the default Teradata PT
installation is used, the files for the sample XSP will be located in the following directory:
/opt/teradata/client/tbuild/14.00.01/tptapi/sample/xsp
Building the example XSP will require two files from the Teradata Database: the
sqltypes_td.h header file and the udf library (udf.so on Linux, udf.lib on Windows). See
Database Administration for the location of these two files.
3 Move example External Stored Procedure Files onto the Teradata Database machine.
Note: If the Teradata Database machine was used to build the example XSP library, this
step can be skipped.
Move the example XSP library into any directory on the Teradata Database machine. On
the Linux platform, the example XSP library produced in step 2 is named xsp.so. On
Windows platforms, both the xsp.lib and xsp.dll library files will be needed.
In addition to the example XSP library, the following input files will be needed in order to
run the example:
input.exp
input.lod
input.stm
input.upd
infile.littleEndian
4 Install all required Teradata PT packages on the Teradata Database.
See the beginning section of Appendix B: Code Samples for the list of packages which
are mandatory to run the Teradata PT samples. Install all of these packages on the Teradata
Database machine.
5 Configure the Teradata Database to run the CREATE PROCEDURE SQL statement.
Depending on which platform the Teradata Database is running on, follow the above
instructions for configuring the Teradata Databases environment so that the CREATE
PROCEDURE SQL statement can be used to create the example Teradata PT XSP.
For a Teradata Database running on Linux, move the following files into the /usr/tdbms/
lib directory:
libtelapi.so
libpxicu.so
If the default Teradata PT installation is used, these libraries can be found in the
/opt/teradata/client/tbuild/14.00.01/lib64 directory.
6 Issue the CREATE PROCEDURE SQL statement.
Issue the following CREATE PROCEDURE SQL statement to the Teradata Database using
a database user account that has the CREATE EXTERNAL PROCEDURE permission:
CREATE PROCEDURE xspt est
(
I N oper at or t ype VARCHAR( 64) ,
I N conf i gf i l ename var char ( 64) ,
I N ext r aconf i gf i l ename VARCHAR( 64) ,
I N dat af i l ename VARCHAR( 64) ,
I N updat et i me VARCHAR( 64)
)
LANGUAGE CPP
MODI FI ES SQL DATA
EXTERNAL NAME ' SP! CLI ! SP! / xspt est / xsp. so! F! xspt est '
PARAMETER STYLE SQL;
Note that for this example CREATE PROCEDURE SQL statement /xsptest/xsp.so
should be replaced with the name and current location of the example external stored
procedure library.
7 Configure the Teradata Database for running Teradata PT external stored procedures.
Depending on the Teradata Database platform, follow the above instructions for
configuring the Teradata Databases environment for running Teradata PT External Stored
Procedures.
For a Teradata Database Linux installation, create a file with the following environment
variable settings:
NLSPATH=/ OPT/ TERADATA/ CLI ENT/ TBUI LD/ 14. 00. 01/ MSG64/ %N
/ * Def aul t l ocat i on of oper msgs. cat */
COPERR=/ usr / l i b64
COPLI B=/ usr / l i b64
LD_LI BRARY_PATH=/ opt / t er adat a/ cl i ent / t bui l d/ 14. 00. 01/ l i b64
/ * Def aul t l ocat i on of t he dr i ver l i br ar i es */
Add the current location of the example XSP library to the above LD_LIBRARY_PATH
definition.
Next, create another file with the following information:
CLI EnvFi l e: / <l ocat i on and name of t he f i r st f i l e cr eat ed above>
Then use the Cufconfig utility to set the CLIEnvFile variable:
cuf conf i g - f / <l ocat i on and name of t he second f i l e cr eat ed above>
Restart the Teradata Database so that the new configuration takes effect.
8 Create tables for the external stored procedure examples
Use the following SQL commands to create the tables used in the example XSP:
CREATE SET TABLE t dexpor t , NO FALLBACK,
NO BEFORE J OURNAL,
NO AFTER J OURNAL,
CHECKSUM = DEFAULT
(
Associ at e_I d I NTEGER,
Associ at e_Name CHAR( 25) CHARACTER SET LATI N NOT CASESPECI FI C,
Sal ar y FLOAT,
DOJ dat e f or mat YY/ MM/ DD ,
Desi gnat i on VARCHAR( 25) CHARACTER SET LATI N NOT CASESPECI FI C,
Loan_Amount DECI MAL( 5, 2) ,
Mar t i al _St at us CHAR( 1) CHARACTER SET LATI N NOT CASESPECI FI C,
No_Of _Dependent s BYTEI NT,
updat e_dat e TI MESTAMP( 6)
)
PRI MARY I NDEX ( Associ at e_I d) ;
CREATE SET TABLE t dexpor t A, NO FALLBACK,
NO BEFORE J OURNAL,
NO AFTER J OURNAL,
CHECKSUM = DEFAULT
(
Associ at e_Name CHAR( 25) CHARACTER SET LATI N NOT CASEPECI FI C,
Sal ar y FLOAT,
DOJ DATE FORMAT YY/ MM/ DD ,
Desi gi nat i on VARCHAR( 25) CHARACTER SET LATI N NOT CASESPECI FI C,
)
CREATE SET TABLE t dexpor t B, NO FALLBACK,
NO BEFORE J OURNAL,
NO AFTER J OURNAL,
CHECKSUM = DEFAULT
(
Associ at e_Name CHAR( 25) CHARACTER SET LATI N NOT CASEPECI FI C,
Sal ar y FLOAT,
DOJ DATE FORMAT YY/ MM/ DD ,
Desi gi nat i on VARCHAR( 25) CHARACTER SET LATI N NOT CASESPECI FI C,
)
Create the tables on the same database that the example XSP is running on or on any other
database. For the example scenarios which transfer data between multiple tables, the tables
to export data from (source tables) can be on one database and the tables to load data into
(target tables) can be on a different database.
9 Issue the SQL CALL statement.
Use one of the following SQL CALL statements to run the example XSP:
Use the Load driver to load data from infile.litleEndian into the database:
CALL xspt est ( ' TD_LOAD' , ' i nput . l od' , nul l , ' i nf i l e. l i t t l eEndi an' , nul l ) ;
Use the Update driver to load data from infile.litleEndian into the database:
CALL xspt est ( ' TD_UPDATE' , ' i nput . upd' , nul l , ' i nf i l e. l i t t l eEndi an' , nul l ) ;
Use the Stream driver to load data from infile.litleEndian into the database:
CALL xspt est ( ' TD_STREAM' , ' i nput . st m' , nul l , ' i nf i l e. l i t t l eEndi an' , nul l ) ;
Use the Export driver to export data from the database into a file:
CALL xspt est ( ' TD_EXPORT' , ' i nput . exp' , nul l , ' out f i l e. l i t t l eEndi an' , nul l ) ;
Use the Export and Load drivers to transfer data between two tables:
CALL xspt est ( ' TD_EXPORT2LOAD' , ' i nput . exp' , ' i nput . l od' , nul l , nul l ) ;
Use the Export and Update drivers to transfer data from one table into two tables. The
timestamp is used to determine which rows to transfer. In this example, only rows with
timestamps newer than '2007-03-03 10:30:00' will transfer:
CALL xspt est
( ' TD_EXPORT2UPDATE' , ' i nput . exp2' , ' i nput . l od' , nul l , ' 2007- 03- 03 10: 30: 00' ) ;
Use the Export and Stream drivers to transfer data between two tables. The timestamp
is used to determine which rows to transfer. In this example, only rows with
timestamps newer than '2007-03-03 10:30:00' will be transferred.
CALL xspt est
( ' TD_EXPORT2STREAM' , ' i nput . exp2' , ' i nput . st m' , nul l , ' 2007- 03- 03 10: 30: 00) ;
Notes on Using the above SQL CALL Statements
When issuing the above SQL CALL statements, always specify the full path for any
necessary input or output file. In the above statements infile.littleEndian,
outfile.littleEndian, input.lod are examples of input and output files for which the full path
should be specified.
Read access is required for all input files and the directories in which they are located. On
Linux, this requires giving read access to the others group.
Write access is required for all output files and the directories where they will be located.
On Linux, this requires giving write access to the others group.
All examples using the Export driver require that there be pre-existing data in the table
from which data will be exported.
See the input.exp input file for instructions on how to create the input.exp2 input file.
CHAPTER 9
Converting TIME, TIMESTAMP, and
INTERVAL Data Types
This chapter contains conversion information for TIME, TIMESTAMP, and INTERVAL data
types for Teradata PT.
ANSI/SQL DateTime Specifications
In Teradata PT, the TIME, TIMESTAMP and INTERVAL data types are not part of the syntax
as they are in SQL. No Teradata PT data type exists for TIME or TIMESTAMP. Therefore, to
load or export data, manually convert the desired data type to the ANSI/SQL DateTime data
types by specifying the appropriate fixed CHAR column in the schema as specified in Table 33.
Table 33: ANSI/SQL DateTime Specifications
Specification
TIME
TIME (n)
Where n is the number of digits after the decimal point, 0 through 6. (Default = 6.)
Convert to:
Format (n = 0):
Example:
Format: (n = 4):
Example:
CHAR(8 + n + (1 if n > 0, otherwise 0))
hh:mm:ss
11:37:58
hh:mm:ss.ssss
11:37:58.1234
TIMESTAMP
TIMESTAMP (n)
Convert to:
Format (n = 0):
Example:
Format (n = 4):
Example:
yyyy-mm-dd hh:mm:ss
1998-09-04 11:37:58
yyyy-mm-dd hh:mm:ss.ssss
1998-09-04 11:37:58.1234
TIME WITH TIME ZONE
TIME (n) WITH TIME ZONE
Chapter 9: Converting TIME, TIMESTAMP, and INTERVAL Data Types
Convert to:
Format (n = 0):
Example:
Format (n = 4):
Example:
hh:mm:ss{}hh:mm
11:37:58-08:00
hh:mm:ss.ssss {} hh:mm
11:37:58.1234-08:00
TIMESTAMP WITH TIME ZONE
TIMESTAMP (n) WITH TIME ZONE
Convert to:
Format (n = 0):
Example
Format (n = 4):
Example:
yyyy-mm-dd hh:mm:ss{}hh:mm
1998-09-24 11:37:58+07:00
yyyy-mm-dd hh:mm:ss.ssss{}hh:mm
1998-09-24 11:37:58.1234+07:00
INTERVAL YEAR
INTERVAL YEAR (n)
Where n is the number of digits, 1 through 4. (Default = 2.) Results include one leading blank space
(for positive values) or a minus sign (for negative values).
Convert to:
Format (n = 2):
Example:
Format (n = 4):
Example:
CHAR(n+1)
yy
98
yyyy
1998
INTERVAL YEAR TO MONTH
INTERVAL YEAR (n) TO MONTH
Convert to:
Format (n = 2):
Example:
Format (n = 4):
Example:
CHAR(n + 3)
yy-mm
98-12
yyyy-mm
1998-12
INTERVAL MONTH
INTERVAL MONTH (n)
Convert to:
Format (n = 2):
Example:
Format (n = 4):
Example:
CHAR(n)
mm
12
mmmm
0012
Table 33: ANSI/SQL DateTime Specifications (continued)
Specification
INTERVAL DAY
INTERVAL DAY (n)
Convert to:
Format (n = 2):
Example:
Format (n = 4):
Example:
CHAR(n)
dd
31
dddd
0031
INTERVAL DAY TO HOUR
INTERVAL DAY (n) TO HOUR
Convert to:
Format (n = 2):
Example:
Format (n = 4):
Example:
CHAR(n + 3)
dd hh
31 12
dddd hh
0031 12
INTERVAL DAY TO MINUTE
INTERVAL DAY (n) TO MINUTE
Convert to:
Format (n = 2):
Example:
Format (n = 4):
Example:
CHAR(n + 6)
dd hh:mm
31 12:59
dddd hh:mm
0031 12:59
INTERVAL DAY TO SECOND
INTERVAL DAY (n)
TO SECOND
INTERVAL DAY TO SECOND (m)
INTERVAL DAY (n) TO SECOND (m)
Where:
n is the number of digits, 1 through 4. (Default = 2.)
m is the number of digits after the decimal point, 0 through 6. (Default = 6.)
Results include one leading blank space (for positive values) or a minus sign (for negative values).
Convert to:
Format (n = 2, m = 0):
Example:
Format (n = 4, m = 4):
Example:
CHAR(n + 9 + m + (1 if m > 0, 0 otherwise))
dd hh:mm:ss
31 12:59:59
dddd hh:mm:ss.ssss
0031 12:59:59:59.1234
Specification
INTERVAL HOUR
INTERVAL HOUR (n)
Convert to:
Format (n = 2):
Example:
Format (n = 4):
Example:
CHAR(n)
hh
12
hhhh
0012
INTERVAL HOUR TO MINUTE
INTERVAL HOUR (n) TO MINUTE
Convert to:
Format (n = 2):
Example:
Format (n = 4):
Example:
CHAR(n + 3)
hh:mm
12:59
hhhh:mm
0012:59
INTERVAL HOUR TO SECOND
INTERVAL HOUR (n) TO SECOND
INTERVAL HOUR TO SECOND (m)
INTERVAL HOUR (n) TO SECOND (m)
Where:
Convert to:
Format (n = 2, m = 0):
Example:
Format (n = 4, m = 4):
Example:
hh:mm:ss
12:59:59
hhhh:mm:ss.ssss
0012:59:59.1234
INTERVAL MINUTE
INTERVAL MINUTE (n)
Convert to:
Format (n = 2):
Example:
Format (n = 4):
Example:
CHAR(n)
mm
59
mmmm
0059
Specification
INTERVAL MINUTE TO SECOND
INTERVAL MINUTE (n) TO SECOND
INTERVAL MINUTE TO SECOND (m)
INTERVAL MINUTE (n) TO SECOND (m)
Where:
Convert to:
Format (n = 2, m = 0):
Example:
Format (n = 4, m = 4):
Example:
mm:ss
59:59
mmmm:ss.ssss
0059:59.1234
INTERVAL SECOND
INTERVAL SECOND (n)
INTERVAL SECOND (n, m)
Where:
Convert to:
Format (n = 2, m = 0):
Example:
Format (n = 4, m = 4):
Example:
CHAR(n + m + (1 if m > 0, 0 otherwise))
ss
59
ssss.ssss
0059.1234
Specification
APPENDIX A
Platform Compilers
Table 34: Teradata PT Platform Compilers
Operating System Platform Version Compiler Version
AIX Power PC AIX 5.3 VisualAge C++ Professional/C for
AIX Compiler, V5
Using the compilers default STL
HP-UX PA-RISC HP-UX 11v1 (11.11)
PA-RISC HP-UX 11v2 (11.23)
PA-RISC HP-UX 11v3 (11.31)
Itanium 64-bit HP-UX 11iv2 (11.23)
Itanium 64-bit HP-UX 11iv3 (11.31)
HP ANSI C++ B3910B X.03.37.01
for PA-RISC
HP aC++/ANSI C B3910B A.05.50
[Jan. 06 2003] for Itanium
Linux x86 32-bit Red Hat Linux Advanced Server 3.0
x86 32-bit Red Hat Linux Advanced Server 4.0
x86 32-bit Red Hat Linux Advanced Server 5.0
EM64T/Opteron 32-bit Red Hat Linux Advanced
Server 4.0
Server 5.0
Server 4.0
Server 5.0
x86 32-bit SUSE LINUX Enterprise 9 SP1, SP2, and
SP3
x86 32-bit SUSE LINUX Enterprise 10 SP1
EM64T/Opteron 32-bit SUSE LINUX Enterprise 9
SP1, SP2, and SP3
SP1, SP2, and SP3
SP1
SP1
For 32-bit:
g++ version 3.3.3 (V3.3.3)
g++ 4.1 (V4.1.2)
For 64-bit:
g++ version 3.3.3 (V3.3.3)
g++ 4.1 (V4.1.2)
Note: Build 32-bit user applications
with the g++ version 3.3.3 compiler if
the g++ 3.3.3 version of the Teradata PT
library was installed.
Appendix A: Platform Compilers
z/Linux Red Hat Enterprise Linux on zSeries
32-bit TTU on RHEL 5.0
64-bit TTU on RHEL 5.0
Novell SUSE Enterprise Linux on zSeries
32-bit TTU on SUSE 10
64-bit TTU on SUSE 10
For 32-bit, g++ version 4.1
For 64-bit, g++ 4.1
Solaris running on
an AMD Opteron
system
32-bit Opteron running 64-bit Oracle Solaris 10
64-bit Opteron running 64-bit Solaris 10
Sun C++ 5.8 2005/10/13
(libCstd)
Note: Applications linked with the
STLport version of the STL library
are incompatible with the Teradata
PT libraries. Link user applications
with the default STL library instead.
Solaris running on
a SPARC system
SPARC system running on Solaris 8,9,10 Sun WorkShop 6 update 2 C++ 5.3
(libCstd)
Note: Applications linked with the
STLport version of the STL library
are incompatible with the Teradata
PT libraries. Link user applications
with the default STL library instead.
Windows x86 2000 Professional Server Advanced Server SP4
x86 32-bit WS 2008 Enterprise Edition Standard
Edition
x86 32-bit XP Professional SP2
EM64T/Opteron 32-bit XP Professional SP2
EM64T/Opteron 64-bit XP Professional x64 Edition
SP2
x86 32-bit WS 2003 Enterprise Edition Standard
Edition Original and SP2
EM64T/Opteron 32-bit WS 2003 Enterprise Edition
Standard Edition Original and SP2
EM64T/Opteron 32-bit WS 2008 Enterprise Edition
Standard Edition
EM64T/Opteron 64-bit WS 2003 Enterprise x64
Edition Standard x64 Edition Original and SP2
EM64T/Opteron 64-bit WS 2008 Enterprise x64
Edition Standard x64 Edition
EM64T/Opteron 32-bit Vista Enterprise edition
EM64T/Opteron 64-bit Vista Enterprise edition
EM64T/Opteron x64 Vista Enterprise edition
MSVC_7. and MSVC_8.0 for 32-bit
MSVC_8.0 for 64-bit
Table 34: Teradata PT Platform Compilers (continued)
z/OS z/OS 1.7
z/OS 1.8
z/OS 1.9
V1.7 z/OS XL C++
Table 34: Teradata PT Platform Compilers (continued)
APPENDIX B
Code Samples
Table 35 lists the Teradata Tools and Utilities 14.00 version of the following products that are
required to run the code samples for Teradata PT.
It is preferred that the products listed in the table be installed in the order listed; however, each
product states its prerequisites at install time.
Note: For Teradata Tools and Utilities 14.00 products, the full version number for packages is
14.00.00.xx. The last two numbers in the version string denote the e-fix version with the latest
release having the greatest e-fix number. Before using an e-fix version of a product, review the
corresponding e-fix ReadMe file for fix information and for documentation on any resulting
usage changes.
For the Teradata PT default installation directory and the environment variables that need to
be set before using Teradata PT, see appropriate Teradata installation guides at http://
www.info.teradata.com/.
See Appendix A: Platform Compilers, for the supported versions and releases of the
platform compilers.
Windows
The following outlines the steps entailed in accessing Windows code samples.
Table 35: Required Software Dependencies for Teradata PT
Product Package Name
Teradata International Components for Unicode (Teradata ICU) tdicu
Teradata Generic Security Services (TeraGSS) TeraGSS
Teradata Call Level Interface Version 2 (Teradata CLIv2) cliv2
Teradata PT Export Operator (if used) pexpda00
Teradata PT Load Operator (if used) plodda00
Teradata PT Update Operator (if used) pupdda00
Teradata PT Stream Operator (if used) pstmda00
Teradata PT papida00
Appendix B: Code Samples
Windows
1 After you install Teradata PT, you should see the following directory structure:
\ bi n ( cont ai ns 32- bi t . l i b and . dl l f i l es)
\ bi n64 ( cont ai ns 64- bi t . l i b and . dl l f i l es)
\ bi n\ vc7 ( cont ai ns 32- bi t . l i b and . dl l f i l es f or vc7. 1)
\ t pt api
\ i nc ( cont ai ns . h f i l es)
\ sampl e
\ bl ockl oadi ng ( Shows how t o l oad r ows i n buf f er mode wi t h t he l oad dr i ver )
\ checkpoi nt ( Shows how checkpoi nt / r est ar t wor ks wi t h t he st r eamdr i ver )
\ common ( Cont ai ns shar ed f i l es used by al l sampl es)
\ gener i c ( Shows how each dr i ver wor ks)
\ get buf f er ( Shows how t o expor t t he dr i ver s Get Buf f er f eat ur e)
\ i nc ( Cont ai ns shar ed . h f i l es used by al l sampl es)
\ mul t i pl e ( Shows how t o use mul t i pl e dr i ver s i n t he same appl i cat i on)
\ mul t i _node ( Shows how t o use t he mul t i - node pr ot ocol )
\ t hr eads ( Shows how t o wr i t e mul t i - t hr eaded appl i cat i ons)
\ xsp ( Shows how t o use Ter adat a PT API i n an XSP)
\ r unsamp ( Cont ai ns pr ecompi l ed TPTAPI appl i cat i ons
compat i bl e f or Wi ndows pl at f or ms)
\ r unsamp_vc7_WI N_32. exe ( 32 bi t TPTAPI appl i cat i on bui l t wi t h VC7. 1)
Note: The 64-bit .lib and .dll files will only be in the 64-bit Windows package and the
32-bit .lib and .dll files will only be in the 32-bit Windows package.
2 Become familiar with the Teradata PT methods in the sample programs (.cpp files).
3 In each sample solution file, you can see the following settings.
Build the 32-bit samples in Visual Studio V7.1 or V8.0 and the 64-bit samples in Visual
Studio V8.0.
C/C++ Additional Include Directories:
. . \ i nc; . \ i nc; . . \ common
Linker Additional Library Directories
. . \ . . \ . . \ bi n\ TELAPI . l i b ( 32- bi t sampl es)
. . \ . . \ . . \ bi n64\ TELAPI . l i b ( 64- bi t sampl es)
Note: Edit the makefile and modify the values of the C++C and CC variables to the
location of the compilers on your system.
4 Put the sample executable, data file, and all Teradata PT dlls in the same directory or
specify the Teradata PT directory in the PATH environment variable.
For example, the following directories should be appended to the PATH environment
variable if they are not already there:
C: \ Pr ogr amFi l es\ Ter adat a\ Cl i ent \ 14. 00. 01\ Ter adat a Par al l el Tr anspor t er \ bi n ( 32-
bi t ver si on)
C: \ Pr ogr amFi l es\ Ter adat a\ Cl i ent \ 14. 00. 01\ Ter adat a Par al l el Tr anspor t er \ msg ( 32-
bi t ver si on)
C: \ Pr ogr amFi l es\ Ter adat a\ Cl i ent \ 14. 00. 01\ Ter adat a Par al l el Tr anspor t er \ bi n64 ( 64-
bi t ver si on)
C: \ Pr ogr amFi l es\ Ter adat a\ Cl i ent \ 14. 00. 01\ Ter adat a Par al l el Tr anspor t er \ msg64 ( 64-
bi t ver si on)
C: \ Pr ogr amFi l es\ Ter adat a\ Cl i ent \ 14. 00. 01\ Ter adat a Par al l el Tr anspor t er \ bi n\ vc7
( 32- bi t ver si on f or vc7. 1)
Note: All 32-bit executables run with 32-bit dlls and all 64-bit executables run with 64-bit
dlls.
5 Change the DBS machine name, DBS user name, and DBS user password in the BTEQ
scripts setupTables.bteq and cleanupTables.bteq for each sample.
6 Run the BTEQ script setupTables.bteq to set up the tables for the current sample.
7 Execute the sample.
Solaris Running on a SPARC System, Solaris Running on an AMD Opteron System, HP-UX, and AIX
8 Run the BTEQ script cleanupTables.bteq to clean up the tables used by the current sample.
Note: To execute TPTAPI samples using VS2003 (vc7.1), copy libraries from the /bin/vc7
folder to /bin.
To execute the precompiled TPTAPI applications available in \sample\runsamp directory:
Open a Windows command prompt.
Change your working directory to <TPTAPI install directory>\sample\runsamp.
Run the executable that is available in this directory.
For example, to run a 32-bit TPTAPI application built with VC 8.0, issue the following
command at the windows command prompt:
r unsamp_vc8_WI N_32. exe tdpid userid password
Solaris Running on a SPARC System, Solaris
Running on an AMD Opteron System, HP-UX,
and AIX
The following outlines the steps entailed in accessing Solaris running on a SPARC system,
Solaris running on an AMD Opteron system, HP-UX, and AIX code samples.
1 After you install Teradata PT you should see the following directory structure:
\ l i b ( cont ai ns 32- bi t . so/ . sl f i l es)
\ l i b64 ( cont ai ns 64- bi t . so/ . sl f i l es)
\ t pt api
\ i nc ( cont ai ns . h f i l es)
\ sampl e
\ r unsamp ( ( Cont ai ns pr ecompi l ed TPTAPI appl i cat i ons)
\ r unsamp_ai x_32( 32- bi t TPTAPI appl i cat i on bui l t f or AI X PPC)
\ r unsamp_ai x_64 ( 64- bi t TPTAPI appl i cat i on bui l t f or AI X PPC)
\ r unsamp_hpi a_64 ( 64- bi t TPTAPI appl i cat i on bui l t f or HPUX I t ani um)
\ r unsamp_hpux_32 ( 32- bi t TPTAPI appl i cat i on bui l t f or HPUX PARI SC)
\ r unsamp_hpux_64 ( 64- bi t TPTAPI appl i cat i on bui l t f or HPUX PARI SC)
\ r unsamp_sol _o_32 ( 32- bi t TPTAPI appl i cat i on bui l t f or Sol ar i s Opt er on)
\ r unsamp_sol _o_64 ( 64- bi t TPTAPI appl i cat i on bui l t f or Sol ar i s Opt er on)
\ r unsamp_sol _s_32 ( 32- bi t TPTAPI appl i cat i on bui l t f or Sol ar i s Spar c)
\ r unsamp_sol _s_64 ( 64- bi t TPTAPI appl i cat i on bui l t f or Sol ar i s Spar c)
Note: The 32-bit and 64-bit .so/.sl files are in the Solaris, HP-UX PA RISC, and AIX
packages. Only the 64-bit .so files are in the HP-UX IA64 package.
2 Becomes familiar with the Teradata PT methods in the sample programs (.cpp files).
3 In the sample makefile, you can see the following settings:
. . / i nc ( Ter adat a PT common header s)
. / i nc ( sampl e- onl y header )
. . / common ( sampl e shar ed f i l es)
Solaris Running on a SPARC System, Solaris Running on an AMD Opteron System, HP-UX, and AIX
Linker Additional Library Directories:
- l t el api
Run the makefile to build the samples.
location of the compilers on your system. Use a GNU compatible version of make
when building the samples on AIX.
Before running the makefile, verify that the directory containing the Teradata PT ICU
Library (libpxicu.so/libpxicu.sl) is in the LD_LIBRARY_PATH environment variable
(SHLIB_PATH for HP-UX AND LIBPATH for AIX).
4 Set environment variables, if necessary.
Put the sample executable, data file, and all Teradata PT .so or.sl files in the same directory.
Or specify the Teradata PT directories in the PATH variables.
Run all 32-bit executables with 32-bit .so or .sl files and run all 64-bit executables with
64-bit .so or .sl files.
For example on Solaris running on a SPARC system and Solaris running on an AMD
Opteron system:
a export LD_LIBRARY_PATH = < library path>:$LD_LIBRARY_PATH
expor t LD_LI BRARY_PATH=/ opt / t er adat a/ cl i ent / 14. 00. 01/ t bui l d/
l i b: $LD_LI BRARY_PATH ( 32- bi t )
expor t LD_LI BRARY_PATH=/ opt / t er adat a/ cl i ent / 14. 00. 01/ t bui l d/
l i b64: $LD_LI BRARY_PATH ( 64- bi t )
b export NLSPATH=<directory path of the catalog>/%N:$NLSPATH
expor t NLSPATH=opt / t er adat a/ cl i ent / 14. 00. 01/ t bui l d/ msg/ %N: $NLSPATH ( 32- bi t )
expor t NLSPATH=opt / t er adat a/ cl i ent / 14. 00. 01/ t bui l d/ msg64/ %N: $NLSPATH ( 64- bi t )
Note: On HP-UX set the SHLIB_PATH and the NLSPATH environment variables.
On AIX set the LIBPATH and the NLSPATH environment variables.
On an IBM AIX, when the LANG and LC_FASTMSG environment variables are set to "C"
and "true", respectively, the following messages will appear after running a Teradata PT job
using the tbuild command:
Message Catalog Error: Message 4000 was not found
Message Catalog Error: Message 2007 was not found
Cause: Environment variable settings
Corrective Action: Use one of the following actions to solve the error messages: change the
value for the LANG environment variable to "en_US" or the value for the LC_FASTMSG
environment variable to "false". Then rerun the Teradata PT job.
Configuration Data: TPT v12 and TPT v13
5 Set the CLIv2 environment variable THREADONOFF to 1 to run the Teradata PT multi-
threaded application.
Linux
Note: To execute the precompiled TPTAPI applications available in \sample\runsamp
directory:
Change your working directory to <TPTAPI install directory>\sample\runsamp
For example, to run a 64-bit TPTAPI application built on Solaris Sparc, issue this
command at the command prompt:
. / r unsamp_sol _s_64 tdpid userid password
Linux
The following outlines the steps entailed in accessing Linux code samples.?
1 After you install Teradata PT, you should see the following directory structure:
\ l i b ( cont ai ns 32- bi t . so f i l es)
\ l i b64 ( cont ai ns 64- bi t . so f i l es)
\ l i b\ gcc_3. x ( cont ai ns TPTAPI gcc_3. x 32- bi t . so f i l es)
\ l i b64\ gcc_3. x ( cont ai ns TPTAPI gcc_3. x 64- bi t . so f i l es)
\ i nc ( cont ai n . h f i l es)
\ sampl e
\ xsp ( Shows how t o use Ter adat a PT i n an XSP)
\ r unsamp ( Cont ai ns pr ecompi l ed TPTAPI appl i cat i ons)
\ r unsamp_l i nux_32 ( 32- bi t TPTAPI appl i cat i on bui l t f or Li nux wi t h
gcc 4. 1)
\ r unsamp_l i nux_64 ( 64- bi t TPTAPI appl i cat i on bui l t f or Li nux wi t h
gcc 4. 1)
\ r unsamp_l i nux_390_32 ( 32- bi t TPTAPI appl i cat i on bui l t f or z/ Li nux
wi t h gcc 4. 1)
\ r unsamp_l i nux_390_64 ( 64- bi t TPTAPI appl i cat i on bui l t f or z/ Li nux
wi t h gcc 4. 1)
2 Become familiar with the Teradata PT methods in the sample programs (.cpp files).
3 In the sample makefile, you can see the following settings. Run the makefile to build the
samples.
. . / i nc ( Ter adat a PT common header s)
. / i nc ( sampl e- onl y header )
. . / common ( sampl e shar ed f i l es)
Linker Additional Library Directories:
- l t el api
location of the compilers on your system.
Before running the makefile, verify that the directory containing the Teradata PT ICU
Library (libpxicu.so) is in the LD_LIBRARY_PATH environment variable.
4 Set the following environment variables, if necessary.
IBM z/OS
Put the sample executable, data file, Teradata PT .so file in the same directory. Or specify
the Teradata PT directory in the PATH variables. Run all 32-bit executables with 32-bit .so
files and run all 64-bit executables with 64-bit .so files. For example:
a export LD_LIBRARY_PATH = < library path>:$LD_LIBRARY_PATH
expor t LD_LI BRARY_PATH=
=/ opt / t er adat a/ cl i ent / 14. 00. 01/ t bui l d/ l i b: $LD_LI BRARY_PATH ( 32- bi t )
expor t LD_LI BRARY_PATH=
=/ opt / t er adat a/ cl i ent / 14. 00. 01/ t bui l d/ l i b64/ : $LD_LI BRARY_PATH ( 64- bi t )
b export NLSPATH=<directory path of the catalog>/%N:$NLSPATH
expor t NLSPATH=
=/ opt / t er adat a/ cl i ent / 14. 00. 01/ t bui l d/ msg/ %N: $NLSPATH ( 32- bi t )
expor t NLSPATH=
=/ opt / t er adat a/ cl i ent / 14. 00. 01/ t bui l d/ msg64/ %N: $NLSPATH ( 64- bi t )
5 Set the CLIv2 environment variable THREADONOFF to one to run the Teradata PT
multi-threaded application.
Note: To execute the precompiled TPTAPI applications available in \sample\runsamp
directory:
Change your working directory to <TPTAPI install directory>\sample\runsamp.
For example, to run a 32-bit TPTAPI application built on Linux, issue this command at the
command prompt:
. / r unsamp_l i nux_32 tdpid userid password
IBM z/OS
The following outlines the steps entailed in accessing IBM z/OS code samples.
1 After installation, the TPTAPI samples reside in the following datasets where <TTU> is
the installation prefix:
The application libraries are as follows:
Table 36: TPT Datasets
Database Name Description
<TTU>.SAMPLIB TTU Sample Library (includes TPT and TPTAPI)
<TTU>.TPT.H TPTAPI SDK and Sample .H files
IBM z/OS
The TPT Sample Library PDS Member Naming Standards are as follow (8 bytes):
PT t aaaaa
where:
2 Become familiar with the Teradata API methods in the sample programs.
The SDK consists of the following components:
Table 37: TPT Application Libraries
Dataset Name Description
<TTU>.TPTLOAD TPT/TPTAPI Application Load Library
<TTU>.APPLOAD TTU/CLI Application Load Library
<TTU>.SDSNMACS TPTAPI Definition Side Deck Import Library
Table 38: TPT Sample Library PDS Member Naming Standards
This Variable... Defines the...
PT TPT product identifier
t Type of the item
Possible values include:
$ = JCL item
# = JCL PROC item
@ = TPT Job Variables
B = BTEQ Script
S = TPT Script
C = C or C++ Program Sample
T = Text Document
I = Program Input
H = Program Header File
X = Notify Exit
aaaaa Unique item identifier
Table 39: SDK *.H
Unix Name z/OS Name
connection.h CONNECTI
DMLGroup.h DMLGROUP
schema.h SCHEMA
IBM z/OS
The Generic Driver example consists of the following components:
Table 40: Dynamic DDL SDK *.H
Unix Name z/OS Name
connectionX.h CONNECTX
DMLGroupX.h DMLGROUPX
schemaX.h SCHEMAX
Table 41: Generic Driver *.CPP
Unix Name z/OS Name Description
main.cpp PTCMAIN Main Entry Point Console for the
Generic Driver
OptionsManager.cpp PTCOPTMA Options Manager
GenericDriver.cpp PTCGENDR Generic Driver Example
Table 42: Generic Driver *.H
Unix Name z/OS Name
DMLGroup.h DMLGROUP
schema.h SCHEMA
GenericDriver.h PTCGENDR
OptionsManager.h PTCOPTMA
Table 43: Generic Driver JCL
n/a PT$CMVS Compile and Bind the Generic
Driver
n/a PT$MVSGO Generic Drive Execution
Table 44: Generic Driver Configuration Files
n/a PTIGENDR Generic Drive Input
IBM z/OS
The Dynamic DLL Generic Driver Example consists of the following components:
The Multi Node Master consists of the following components:
setupTables.bteq PTBGDSET BTEQ script to set up generic
driver test
cleanupTables.bteq PTBGDREM BTEQ script to delete generic
driver tables
Table 45: Dynamic DLL Generic Driver *.CPP
main.cpp PTCMAIN Main Entry Point Console for the
Generic Driver
GenericDriver.cpp PTCGENDD Generic Driver Example
dynlib.cpp PTCDLLIB Dynamically Loads DLL
Table 46: Dynamic DLL Generic Driver *.H
Unix Name z/OS Name
DMLGroupX.h DMLGRPX
schemaX.h SCHEMAX
GenericDriver.h PTCGENDR
dynlib.h PTCDLLIB
Table 47: Dynamic DLL Generic Driver JCL
n/a PT$CMVSD Compile and Bind the Generic
Driver
n/a PT$MVSDG Generic Drive Execution
Table 44: Generic Driver Configuration Files
IBM z/OS
Table 48: Multi Node Master *.CPP
fileio.cpp PTCFILIO File Input and Output for the
multi-node Master and Slave
master.cpp PTCMASTR Main Master for the multi-node
example
multitest.cpp PTCMULTI Multi-node routines
synchronize.cpp PTCSYNCR Multi-node synchronization
routines
Table 49: Multi Node Master *.H
Unix Name z/OS Name
DMLGroup.h DMLGROUP
schema.h SCHEMA
fileio.h PTCFILIO
synchronize.h PTCSYNCR
multitest.h PTCMULTI
Table 50: Multi Node Master JCL
n/a PT$CMNMS Compile and Bind the Multi-Node
Master
n/a PT$MNMSG Execution JCL for the Multi-Node
Master
Table 51: Multi Node Master Configuration Files
n/a PTIMNMST Input for the Multi-Node Master
setupTables.bteq PTBMNSET BTEQ script to set up multi-
node test
IBM z/OS
The Dynamic DLL Multi Node Master consists of the following components:
cleanupTables.bteq PTBMNREM BTEQ script to delete multi-
node tables
Table 52: Dynamic DLL Multi Node Master *.CPP
master.cpp PTCMASTD Main Master for the multi-node
example
multitest.cpp PTCMULTD Multi-node routines
synchronize.cpp PTCSYNCD Multi-node synchronization
routines
dynlib.cpp PTCDLLIB Dynamically Loads the DLL
Table 53: Dynamic DLL Multi Node Master *.H
Unix Name z/OS Name
DMLGroupX.h DMLGRPX
schemaX.h SCHEMAX
fileio.h PTCFILIO
synchronize.h PTCSYNCD
multitest.h PTCMULTD
dynlib.h PTCDLLIB
Table 54: Dynamic DLL Multi Node Master JCL
n/a PT$CMNMD Compile and Bind the Multi-Node
Master
Table 51: Multi Node Master Configuration Files
IBM z/OS
The Multi Node Slave consists of the following components:
n/a PT$MNMDG Execution JCL for the Multi-Node
Master
Table 55: Multi Node Slave *.CPP
slave.cpp PTCSLAVE Slave for the multi-node example
multitest.cpp PTCMULTI Multi-node routines
synchronize.cpp PTCSYNCR Multi-node synchronization
routines
Table 56: Multi Node Slave *.H
Unix Name z/OS Name
schema.h SCHEMA
DMLGroup.h DMLGROUP
fileio.h PTCFILIO
synchronize.h PTCSYNCR
multitest.h PTCMULTI
Table 57: Multi Node Slave JCL
n/a PT$CMNS Compile and Bind the Multi-Node
Slave
n/a PT$MNSLG Execution JCL for the Multi-Node
Slave
Table 54: Dynamic DLL Multi Node Master JCL
IBM z/OS
The Dynamic DLL Multi Node Slave consists of the following components:
Table 58: Multi Node Slave Configuration Files
n/a PTIMNS Input for the Multi-Node Slave
Table 59: Dynamic DLL Multi Node Slave *.CPP
fileio.cpp PTCFILIO File Input and Output for the multi-
node Master and Slave
slave.cpp PTCSLAVD Slave for the multi-node example
multitest.cpp PTCMULTD Multi-node routines
synchronize.cpp PTCSYNCD Multi-node synchronization
routines
Table 60: Dynamic DLL Multi Node Slave *.H
Unix Name z/OS Name
schemaX.h SCHEMAX
DMLGroupX.h DMLGRPX
fileio.h PTCFILIO
synchronize.h PTCSYNCD
multitest.h PTCMULTD
dynlib.h PTCDLLIB
Table 61: Dynamic DLL Multi Node Slave JCL
n/a PT$CMNSD Compile and Bind the Multi-Node Slave
n/a PT$MNSDG Execution JCL for the Multi-Node Slave
IBM z/OS
The Parallel Thread Example consists of the following components:
Table 62: Parallel Thread *.CPP
PerfTestMessage.cpp PTCPERFT Performance Test Messages for
the Thread Example
TelapiThreadTest.cpp PTCTELTH Thread Test Main Console
Application
TestBase.cpp PTCBASET Thread Test: TestBase
TestExport.cpp PTCEXPRT Thread Test: TestExport
TestLoad.cpp PTCLOADT Thread Test: TestLoad
TestSim.cpp PTCSIMT Thread Test: TestSim
TestStream.cpp PTCSTRMT Thread Test: Test Stream
TestUpdate.cpp PTCUPDAT Thread Test: Test Update
ThreadTestParameters.cpp PTCTHDPA Thread Test Parameters
ThreadTest.cpp PTCTHDTE Thread Test
Synchronizer.cpp PTCTSYNC Thread Synchronizer
Table 63: Parallel Thread *.H
Unix Name z/OS Name
common.h COMMON
schema.h SCHEMA
DMLGroup.h DMLGROUP
PerfTestMessage.h PTCPERFT
TestBase.h PTCBASET
TestExport.h PTCEXPRT
TestLoad.h PTCLOADT
TestSim.h PTCSIMT
TestStream.h PTCSTRMT
TestUpdate.h PTCUPDAT
IBM z/OS
The Dynamic DLL Parallel Thread example consists of the following components:
ThreadTestParameters.h PTCTHDPA
ThreadTest.h PTCTHDTE
Synchronizer.h PTCTSYNC
Table 64: Parallel Thread JCL
n/a PT$CTHD Compile and Bind the Parallel Thread
Example
n/a PT$THDGO Execution JCL for the Parallel Thread
Example
Table 65: Parallel Thread Configuration Files
n/a PTIPAR
Input for the Parallel Thread
Example
setupTables.bteq PTBTHSET BTEQ script to set up the
Parallel Thread Example
cleanupTables.bteq PTBTHREM BTEQ script to delete Parallel
Thread Tables
Table 66: Dynamic DLL Parallel Thread *.CPP
PerfTestMessage.cpp PTCPERTD Performance Test Messages for the
Thread Example
TelapiThreadTest.cpp PTCTELTD Thread Test Main Console
Application
TestBase.cpp PTCBASTD Thread Test: TestBase
TestExport.cpp PTCEXPTD Thread Test: TestExport
TestLoad.cpp PTCLODTD Thread Test: TestLoad
TestSim.cpp PTCSIMTD Thread Test: TestSim
TestStream.cpp PTCSTRTD Thread Test: Test Stream
Table 63: Parallel Thread *.H
Unix Name z/OS Name
IBM z/OS
TestUpdate.cpp PTCUPDTD Thread Test: Test Update
ThreadTestParameters.cpp PTCTHTPD Thread Test Parameters
ThreadTest.cpp PTCTHDTD Thread Test
Synchronizer.cpp PTCTSYND Thread Synchronizer
Table 67: Dynamic DLL Parallel Thread *.H
Unix Name z/OS Name
common.h COMMOND
schemaX.h SCHEMAX
DMLGroupX.h DMLGRPX
PerfTestMessage.h PTCPERTD
TestBase.h PTCBASTD
TestExport.h PTCEXPTD
TestLoad.h PTCLODTD
TestSim.h PTCSIMTD
TestStream.h PTCSTRTD
TestUpdate.h PTCUPDTD
ThreadTestParameters.h PTCTHTPD
ThreadTest.h PTCTHDTD
Synchronizer.h PTCTSYND
dynlib.h PTCDLLIB
Table 68: Dynamic DLL Parallel Thread JCL
n/a PT$CTHDD Compile and Bind the Parallel Thread
Example
Table 66: Dynamic DLL Parallel Thread *.CPP
IBM z/OS
3 Add a Job Card and update the JCL variables to match the Installation Development
Environment for the following JCL members:
PT$CMNMS: Compile the Multi Node Master Example
PT$CMNS: Compile the Multi Node Slave Example
PT$CMVS: Compile the Generic Driver Example
PT$CTHD: Compile the Parallel Thread Example
Dynamic DLL
PT$CMNMD: Compile the Multi Node Master Example
PT$CMNSD: Compile the Multi Node Slave Example
PT$CMVSD: Compile the Generic Driver Example
PT$CTHDD: Compile the Parallel Thread Example
The JCL uses the following standard JCL Variables (these should be updated to reflect the
customer's requirements).
4 Execute the compile jobs.
n/a PT$THDDG Execution JCL for the Parallel Thread
Example
Table 69: Standard JCL Variables
Name Default Value Description
TTUPREF none (must be provided by
customer)
The installation dataset prefix
SAMPLIB &TTUPREF..SAMPLIB The TTU sample library
HFILES &TTUPREF..TPT.H The TPTAPI .H files
DEVPREF none (must be provided by
customer)
The prefix for the developers private
datasets
OBJLIB &DEVPREF..OBJLIB The OBJECT library for the Compile
JOBS
SAMPLOAD &DEVPREF..LOADLIB The LOAD library for the Compile
JOBS
TPTLOAD &TTUPREF..TPTLOAD The TPT application Load Library
APPLOAD &TTUPREF..APPLOAD The TTU/CLI application Load
Library
TPTDATA &TTUPREF..TPT.H The TPTAPI data is located in the .H
Library
Table 68: Dynamic DLL Parallel Thread JCL
IBM z/OS
5 Change the DBS machine name (TDP), DBS user name, and DBS user password in the
following files:
PTBGDSET: Set up the Generic Driver Example
PTBGDREM: Tear down the Generic Driver Example
PTBMNSET: Set up the Multi Node Example
PTBMNREM: Tear down the Multi Node Example
PTBTHSET: Set up the Parallel Thread Example
PTBTHREM: Tear down the Parallel Thread Example
6 Change the DBS machine name (TDP), DBS user name, and DBS user password in the
following files:
PTIGENDR: The Generic Driver configuration parameters
PTIMNMST: The Multi Node Master configuration parameters
PTIMNS: The Multi Node Slave configuration parameters
PTIPAR: The Parallel Thread configuration parameters
7 Add JOB cards and update the JCL variables in the test jobs:
PT$MNMSG: The Multi Node Master example
PT$MNSLG : The Multi Node Slave example
PT$MVSGO: The Generic Driver example
PT$THDGO: The Parallel Thread example
Dynamic DLL:
PT$MNMDG: The Multi Node Master example
PT$MNSDG: The Multi Node Slave example
PT$MVSDG: The Generic Driver example
PT$THDDG: The Parallel Thread example
8 Execute the test jobs
The JOB outputs should look something like the following:
1) Mul t i Node Mast er Out put :
Wai t i ng f or 1 sl aves
Accept ed cl i ent 0
Recei ved TD_SYNC_Bar r i er
Recei ved TD_SYNC_TELI NFO
Sendi ng TELI NFO of si ze 2288
TELI NFO sync f i ni shed
Swi t chi ng t o bar r i er 1
Connect i on I ni t i at e f i ni shed
Sent 50 r ows
Connect i on EndAcqui si t i on compl et e
IBM z/OS
Connect i on Appl yRows compl et e
Connect i on t er mi nat ed
Test compl et ed
Pr ess any key t o cont i nue
2) Mul t i Node Sl ave Out put
Connect i ng t o 127. 0. 0. 1
Connect i on accept ed
Recei ved TD_SYNC_TELI NFO
Recei vi ng TELI NFO of si ze 2288
TELI NFO sync f i ni shed
Connect i on I ni t i at e f i ni shed
Sent 50 r ows
Connect i on EndAcqui si t i on compl et e
Connect i on Appl yRows compl et e
Connect i on t er mi nat ed
Test compl et ed
Pr ess any key t o cont i nue
3) Gener i c Dr i ver Out put
*** Load Dr i ver Exampl e ***
Dr i ver I ni t i at ed wi t h st at us 3
max r ec l engt h i s 251
End of f i l e r eached
Sent 10 r ows
Acqui si t i on compl et ed wi t h st at us 3
Rows Appl i ed wi t h st at us 3
Load compl et ed successf ul l y
Dr i ver Ter mi nat ed wi t h st at us 3
Del et i ng obj ect s
*** Load Compl et e ***
4) Par al l el Thr ead Out put
Mul t i - Thr eaded Load Test
[ Manager ] Cr eat i ng Thr ead 0/ 4
obj l ocat i on: f ec2298
IBM z/OS
obj l ocat i on: f ec23f 8
[ Thr ead 4] Bar r i er Message
[ Thr ead 4] Wai t i ng f or manager [ 0]
[ Manager ] Bar r i er Reached
[ Thr ead 4] TELI NFO Message
[ Manager ] TELI NFO Bar r i er Reached
[ Manager ] Synchr oni zi ng TELI NFO
[ Manager ] TELI NFO Synchr oni zed
[ Thr ead 4] End of Met hod
[ Thr ead 4] Dr i ver I ni t i at ed
[ Thr ead 4] Sent r ow 0: 41634
[ Thr ead 4] Sent r ow 1: 1286818
[ Thr ead 4] Sent r ow 2: 3908258
[ Thr ead 4] Sent r ow 3: 6529698
[ Thr ead 4] Sent r ow 4: 2400930
[ Thr ead 4] Sent r ow 5: 6398626
[ Thr ead 4] Sent r ow 6: 1024674
[ Thr ead 4] Sent r ow 7: 4891298
IBM z/OS
[ Thr ead 4] Sent r ow 8: 3515042
[ Thr ead 4] Sent r ow 9: 2007714
[ Thr ead 2] Sent r ow 1: 1155746
[ Thr ead 2] Sent r ow 2: 2269858
[ Thr ead 2] Sent r ow 4: 2138786
[ Thr ead 2] Sent r ow 6: 3383970
[ Thr ead 2] Sent r ow 8: 3252898
[ Thr ead 2] Sent r ow 9: 1876642
[ Thr ead 3] Sent r ow 0: 2663074
[ Thr ead 3] Sent r ow 1: 5284514
[ Thr ead 3] Sent r ow 2: 3777186
[ Thr ead 3] Sent r ow 3: 3646114
[ Thr ead 3] Sent r ow 4: 6267554
[ Thr ead 3] Sent r ow 5: 4760226
[ Thr ead 3] Sent r ow 7: 1483426
[ Thr ead 3] Sent r ow 8: 4104866
[ Thr ead 3] Sent r ow 9: 2597538
[ Thr ead 1] Sent r ow 0: 4039330
[ Thr ead 1] Sent r ow 1: 2532002
[ Thr ead 1] Sent r ow 2: 5153442
[ Thr ead 1] Sent r ow 3: 5022370
[ Thr ead 1] Sent r ow 4: 6136482
[ Thr ead 1] Sent r ow 5: 1745570
[ Thr ead 1] Sent r ow 7: 1614498
[ Thr ead 1] Sent r ow 9: 2859682
IBM z/OS
[ Thr ead 4] Checkpoi nt Taken
[ Thr ead 4] Checkpoi nt dat a: NULL, l engt h: 0
[ Thr ead 4] TD_Evt _RowCount s r epor t s 10 r ows r ecei ved
[ Thr ead 4] TD_Evt _RowCount s r epor t s 10 r ows sent
[ Thr ead 4] TD_Evt _RowCount s r epor t s 10 r ows appl i ed
[ Thr ead 4] Sent r ow 10: 6005410
[ Thr ead 4] Sent r ow 11: 4629154
[ Thr ead 4] Sent r ow 12: 3121826
[ Thr ead 4] Sent r ow 13: 2990754
[ Thr ead 4] Sent r ow 14: 5612194
[ Thr ead 4] Sent r ow 15: 959138
[ Thr ead 4] Sent r ow 16: 2073250
[ Thr ead 4] Sent r ow 17: 1942178
[ Thr ead 4] Sent r ow 18: 4563618
[ Thr ead 4] Sent r ow 19: 434850
[ Thr ead 2] Sent r ow 10: 5874338
[ Thr ead 2] Sent r ow 11: 4498082
[ Thr ead 2] Sent r ow 12: 5743266
[ Thr ead 2] Sent r ow 13: 4367010
[ Thr ead 2] Sent r ow 14: 4235938
[ Thr ead 2] Sent r ow 15: 5481122
[ Thr ead 2] Sent r ow 16: 5350050
[ Thr ead 2] Sent r ow 17: 1090210
[ Thr ead 2] Sent r ow 18: 2204322
[ Thr ead 2] Sent r ow 19: 696994
[ Thr ead 3] Sent r ow 10: 2466466
[ Thr ead 3] Sent r ow 11: 5087906
[ Thr ead 3] Sent r ow 12: 2335394
[ Thr ead 3] Sent r ow 13: 3580578
[ Thr ead 3] Sent r ow 14: 6202018
[ Thr ead 3] Sent r ow 15: 828066
[ Thr ead 3] Sent r ow 16: 3449506
[ Thr ead 3] Sent r ow 17: 6070946
[ Thr ead 3] Sent r ow 18: 3318434
[ Thr ead 3] Sent r ow 19: 1811106
IBM z/OS
[ Thr ead 1] Sent r ow 10: 107170
[ Thr ead 1] Sent r ow 11: 2728610
[ Thr ead 1] Sent r ow 12: 1352354
[ Thr ead 1] Sent r ow 13: 3973794
[ Thr ead 1] Sent r ow 14: 1221282
[ Thr ead 1] Sent r ow 15: 5218978
[ Thr ead 1] Sent r ow 16: 3842722
[ Thr ead 1] Sent r ow 17: 6464162
[ Thr ead 1] Sent r ow 18: 3711650
[ Thr ead 1] Sent r ow 19: 6333090
[ Thr ead 4] Sent r ow 20: 3056290
[ Thr ead 4] Sent r ow 21: 5677730
[ Thr ead 4] Sent r ow 22: 1548962
[ Thr ead 4] Sent r ow 23: 5546658
[ Thr ead 4] Sent r ow 24: 1417890
[ Thr ead 4] Sent 25 Rows
[ Thr ead 2] Sent r ow 20: 4694690
[ Thr ead 2] Sent r ow 21: 3187362
[ Thr ead 2] Sent r ow 22: 5808802
[ Thr ead 2] Sent r ow 23: 4301474
[ Thr ead 2] Sent r ow 24: 4170402
IBM z/OS
[ Thr ead 3] Sent r ow 20: 4432546
[ Thr ead 3] Sent r ow 21: 303778
[ Thr ead 3] Sent r ow 22: 2925218
[ Thr ead 3] Sent r ow 23: 2794146
[ Thr ead 3] Sent r ow 24: 5415586
[ Thr ead 1] Sent r ow 20: 4956834
[ Thr ead 1] Sent r ow 21: 4825762
[ Thr ead 1] Sent r ow 22: 5939874
[ Thr ead 1] Sent r ow 23: 565922
[ Thr ead 1] Sent r ow 24: 1680034
[ Thr ead 2] Acqui si t i on compl et e
IBM z/OS
[ Thr ead 2] Appl i cat i on compl et e
[ Thr ead 2] Cal l i ng Ter mi nat e
[ Thr ead 2] Ret ur ned f r omTer mi nat e
[ Thr ead 2] Dr i ver Ter mi nat ed
[ Thr ead 2] Tot al Number of Rows Sent : 25
[ Thr ead 2] Number of Checkpoi nt s Taken: 2
[ Manager ] I nst ance 2 Ter mi nat ed
[ Thr ead 2] Unr ead Msg: Thr ead Exi t i ng
[ Thr ead 2] Unr ead Msg: Load Successf ul
IBM z/OS
[ Thr ead 2] Unr ead Msg: Load Thr ead Exi t ed
[ Manager ] 3 t hr eads r emai ni ng
*** Appl i cat i on Compl et e ***
APPENDIX C
Compiling and Linking Options
Of note for this release:
TheTeradata PT header files were changed. Applications built with previous versions of
Teradata PT must be recompiled with the updated header files.
All Teradata PT applications must explicitly link with the Teradata PT ICU library using
the -lpxicu option.
See the following solution files or makefiles.
32-bit Application for Windows
See generic.sln in sample\generic.
See generic_vc7.sln in sample\generic for vc7.1
For multi_threaded applications, see TelapiThreadTest.sln in sample\threads.
64-bit Application for Windows
See generic64.sln in sample\generic.
For multi_threaded applications, see TelapiThreadTest64.sln in sample\threads.
32-bit and 64-bit Applications for Solaris running on an AMD Opteron system
See makedriver.sol_o in sample\generic
For multi_threaded applications, see makeparallel.sol_o in sample\threads.
32-bit and 64-bit Applications for Solaris running on a SPARC system
See makedriver.sol_s in sample\generic
For multi_threaded applications, see makeparallel.sol_s in sample\threads.
32-bit and 64-bit Applications for HP_UX
See makedriver.hpux in sample\generic
For multi_threaded applications, see makeparallel.hpux in sample\threads.
32-bit and 64-bit Applications for AIX
See makedriver.aix in sample\generic.
For multi_threaded applications, see makeparallel.aix in sample\threads.
32-bit and 64-bit Applications for LINUX
See makedriver.linux in sample\generic.
For multi_threaded applications, see makeparallel.linux in sample\threads.
Appendix C: Compiling and Linking Options
32-bit and 64-bit Applications for z/Linux
See makedriver.linux_390 in sample\generic.
For multi-threaded applications, see makeparallel.linux_390 in sample\threads.
z/OS platforms
See STV.TIxxAPP.TWB.SAMP(MVSSMPBN) for the JCL to invoke the generic sample
compilation PROC libraries. Additional details can be found in
STV.TIxxAPP.TWB.SAMP(CBCC) and STV.TIxxAPP.TWB.SAMP(SBCXB).
APPENDIX D
Teradata PT Publications
User documentation for Teradata PT is distributed among the following books.
Publication Contents
Teradata Parallel Transporter Quick
Start Guide
B035-2501
Provides getting-started information for using Teradata PT.
Includes Teradata PT job examples for:
Reading data from a flat file and loading it into a Teradata
Database target table.
Exporting data from a Teradata Database source table and
writing it to a flat file.
Exporting data from a Teradata Database source table and
loading it to a Teradata Database target table.
Teradata Parallel Transporter User
Guide
B035-2445
Detailed strategies for planning, implementing, and
debugging Teradata PT.
The book includes chapters on:
Writing Teradata PT template job scripts, the kind of job
scripts illustrated in the Teradata Parallel Transporter
Quick Start Guide
Writing Teradata PT defined schema job scripts that:
Move data to and from data targets
Move data within the Teradata environment
Describing individual Teradata PT operators and access
modules
Launching, managing, and troubleshooting a Teradata PT
job
Reference (this book)
B035-2436
A reference book that defines:
Teradata PT command line utility commands.
Object definition statements that make up the declarative
section of a Teradata PT job script.
The APPLY statement that makes up the executable
section of a Teradata PT job script.
Syntax for each Teradata PT operator.
Appendix D: Teradata PT Publications
Application Programming Interface
Programmer Guide
B035-2435
Provides information about:
Setting up the interface.
Coding.
Error reporting.
Checkpointing and restarting.
Operator Programmer Guide
B035-2435
Provides information on developing custom operators,
including all interface functions that allow communication
between the Teradata PT operators and the Teradata PT
infrastructure.
Publication Contents
Glossary
A
administrator A special user responsible for allocating resources to a community of users.
Access Module Processor (AMP) A virtual processor that receives steps from a parsing
engine (PE) and performs database functions to retrieve or update data. Each AMP is
associated with one virtual disk, where the data is stored. An AMP manages only its own
virtual disk and not the virtual disk of any other AMP.
access rights See privilege.
AMP See Access Module Processor (AMP).
ANSI American National Standards Institute. ANSI maintains a standard for SQL. Go to
http://www.info.teradata.com for information about Teradata compliance with ANSI
standards.
application A complete, self-contained program that performs a specific function directly
for the user. Contrast this to system software (two examples of system software are operating
system kernels and libraries) which exists to support applications.
Application Programming Interface (API) An interface (calling conventions) by which an
application accesses an operating system and other services. An API is defined at source code
level and provides a level of abstraction between the application and the kernel (or other
privileged utilities) to ensure the portability of the code.
An API can also provide an interface between a high-level language and lower-level utilities
and services written without consideration for the calling conventions supported by compiled
languages. In this case, the API may translate the parameter lists from one format to another
and interpret call-by-value and call-by-reference arguments in one or both directions.
B
Basic Teradata Query (BTEQ) A CLI application program used to interact with the
Teradata Relational Database Management System (RDBMS). BTEQ commands are used for
controlling sessions, submitting Teradata SQL requests, formatting results, and handling
output data. BTEQ may also be used to verify the installation of Teradata client utilities.
C
Call-Level Interface Version 2 (CLIv2) Specifically for network-attached clients, a
collection of callable service routines that provide an interface to the Teradata Database.
Specifically, CLI is the interface between the application program and the Micro Teradata
Directory Program (for network-attached clients). CLI builds parcels that MTDP packages for
Glossary
sending to the Teradata Database using the Micro Operating System Interface (MOSI) and
provides the application with a pointer to each of the parcels returned from the Teradata
Database.
column In the relational model of Teradata SQL, databases consist of one or more tables. In
turn, each table consists of fields, organized into one or more columns by zero or more rows.
All of the fields of a given column share the same attributes.
cost This is the outlay of database resources used by a given query.
D
data definition The statements and facilities that manipulate database structures and the
Data Dictionary information kept about these structures. These statements include CREATE,
DROP, ALTER, and MODIFY.
Data Definition Language (DDL) In Teradata SQL, the statements and facilities that
manipulate database structures (such as CREATE, MODIFY, DROP, GRANT, REVOKE, and
GIVE) and the dictionary information kept about those structures. In the typical, pre-
relational data management system, data definition and data manipulation facilities are
separated, and the data definition facilities are less flexible and more difficult to use than in a
relational system.
Data Dictionary In the Teradata Database, the information automatically maintained about
all tables, views, macros, databases, and users known to the Teradata Database system. It
includes information about ownership, space allocation, accounting, and access right
relationships between those objects. Data Dictionary information is updated automatically
during the processing of Teradata SQL data definition statements. It is used by the parser to
obtain information needed to process all Teradata SQL statements.
database A related set of tables that share a common space allocation and owner. A
collection of objects that provide a logical grouping for information. The objects include,
tables, views, macros, triggers, and stored procedures.
DBS Acronym for Database System or Database Software.
DBS Control information DBS Control information is a group of fields used by Teradata
Database for debugging and diagnostic purposes, establishing known global system values,
and conducting performance tuning.
driver In Teradata PT, the term that refers to combination of the operators from the
Teradata PT product and application programming interface program code.
E
endianness The byte ordering convention of data that is represented with multiple bytes.
Big-endian is an order in which the big end (most significant value in the sequence) is
stored first (at the lowest storage address). Little-endian is an order in which the little end
(least significant value in the sequence) is stored first. For example, in a big-endian computer,
Glossary
the number 256 is indicated as 0x01 0x00. In a little-endian computer, the number 256 is
indicated as 0x00 0x01.
export This refers to extracting or transferring system information from the tables and
views of a given Teradata Database and saving it so it can be manipulated or pulled into
another system.
Extended Binary Coded Decimal Interchange Code (EBCDIC) A character encoding used
on IBM mainframe systems.
F
field The basic unit of information stored in the Teradata Database. A field is either null, or
has a single numeric or string value. Also see column, row, and table.
I
ICU An acronym for a library of routines that handle Unicode UTF16/UTF8 session
character sets.
import The process of pulling system information into a program. To add system
information from an external source to another system. The system receiving the data must
support the internal format or structure of the data.
J
join A SELECT operation that combines information from two or more tables to produce a
result.
L
log A record of events. A file that records events. Many programs produce log files. Often
you will look at a log file to determine what is happening when problems occur. Log files have
the extension .log.
M
macro A set of Teradata SQL statements stored by the Teradata Database and executed by a
single EXECUTE statement. Each macro execution is implicitly treated as a transaction.
N
name A word supplied by the user that refers to an object, such as a column, database,
macro, table, user, or view.
null The absence of a value for a field.
Glossary
O
object In object-oriented programming, a unique instance of a data structure defined
according to the template provided by its class. Each object has its own values for the variables
belonging to its class and can respond to the messages, or methods, defined by its class.
object definition The details of the structure and instances of the objects used by a given
query. Object definitions are used to create the tables, views, and macros, triggers, join
indexes, and stored procedures in a database.
operator The term used in the Teradata Parallel Transporter (Teradata PT) product to
describe the modules of code responsible for handling particular tasks usually relating to one
of the Teradata Database protocols. These operators reside in dynamically-linked libraries.
Open Database Connectivity (ODBC) Under ODBC, drivers are used to connect
applications with databases. The ODBC driver processes ODBC calls from an application, but
passes SQL requests to the Teradata Database for processing.
P
parameter A variable name in a macro for which an argument value is substituted when the
macro is executed.
privilege In Teradata SQL, a users right to perform the Teradata SQL statements granted to
him or her against a table, database, user, macro, or view. Also know as access right.
production system A Teradata Database used in a live environment. A system that is actively
used for day to day business operations. This differs from a test or development system that is
used to create new queries or test new features before using them on the production system.
R
random AMP sample (RAS) An arbitrary sample from an Access Module Processor (AMP).
These are samples of the tables in a query or all of the tables in a given database. Also known as
RAS.
Relational Database Management System (RDBMS) A database management system in
which complex data structures are represented as simple two-dimensional tables consisting of
columns and rows. For Teradata, RDBMS is referred to as Teradata Database.
request In host software, a message sent from an application program to the Teradata
Database.
result The information returned to the user to satisfy a request made of the Teradata
Database.
row The fields that represent one entry under each column in a table. The row is the smallest
unit of information operated on by data manipulation statements.
Glossary
S
session Also called a Teradata Database session. A session begins when the user logs on to
Teradata Database and ends when the user logs off Teradata Database. In client software, a
logical connection between an application program on a host and Teradata Database. The
connection permits the application program to send one request at a time to and receive one
response at a time from Teradata.
statement A request for processing by the Teradata Database that consists of a keyword verb,
optional phrases, and operands. It is processed as a single entity.
statistics These are the details of the processes used to collect, analyze, and transform the
database objects used by a given query.
Standard Template Library (STL) Standard Template Library is a software library of C++
algorithms, container classes and iterators. It is available on most platforms. Teradata PT uses
features in the STL. The C++ Standard Library is defined by ISO/IEC 14882.
Structured Query Language Call-Level Interface (SQL/CLI) A programming interface
designed to support SQL access to databases from shrink-wrapped application programs.
SQL/CLI provides and international standard implementation-independent CLI to access
SQL databases. Client-server tools can easily access database through dynamic link libraries. It
supports and encourages a rich set of client-server tools.
stored procedure A combination of SQL statements and control and conditional handling
statements that run using a single call statement. Teradata Version 2 Release 4 and later
supports stored procedures. Combinations of procedural and non-procedural statements run
using a single call statement.
T
table A two-dimensional structure made up of one or more columns with zero or more
rows that consist of fields of related information. See also target table.
test system A Teradata Database where you want to import Optimizer-specific information
to emulate a target system and create new queries or test new features.
target table For the Load, Update, and Stream drivers, the target table is the table on a
Teradata Database which will receive the data and/or contains data to be modified. For the
Export driver, the target table is the table from which the data will be extracted.
Teradata Extract and Load Application Programming Interface (TELAPI) This is the
former name of Teradata PT.
Teradata Parallel Data Pump (TPump) A utility that provides an alternative to MultiLoad
for the low volume batch maintenance of large databases under control of a Teradata
Database. TPump enables acquisition of all data from the client with low processor utilization.
test system A Teradata Database where you want to import Optimizer-specific information
to emulate a target system and create new queries or test new features.
Glossary
trigger One or more Teradata SQL statements associated with a table and executed when
specified conditions are met.
U
user A database associated with a person who uses the Teradata Database. The database
stores the persons private information and accesses other Teradata Databases.
V
view An alternate way of organizing and presenting information in the Teradata Database. A
view, like a table, has rows and columns. However, the rows and columns of a view are not
directly stored by the Teradata Database. They are derived from the rows and columns of
tables (or other views) whenever the view is referenced.
Index
A
AddArrayAttribute 44
AddAttribute 44
AddColumn 54
AddDMLGroup 45
AddDMLOption 59
AddSchema 45
AddSerializeOn
arguments 36
syntax 59
AddStatement 60
AddUseList 60
used with DMLGroup object 36
AIX
code samples 209
reporting events
Export driver 150
Load driver 79
Update driver 98
AMPS
nonparticipant during Update tasks 108
offline during Update tasks 108
Single-AMP Systems 109
ANSI/SQL DateTime data type
specifications, table of 197
ApplyRows 46
array attributes
defined 23
array support
AddArraySupport DMLGroup class object 59
default settings 118
B
BTEQ
DROP TABLE statement 86, 105
restarting the Update job 107
scripts used with code samples
Linux 212
Solaris, HP-UX and AIX 210
Windows 208
C
CALL, SQL statement
examples 194
usage notes 195
CD-ROM images 8
checkpoint and restart
checkpoint arguments 33, 34
Checkpoint, Connection class object 46
Load driver event (rows checkpointed) 84
setting in the Connection object 33
Stream driver event (rows checkpointed) 132
Update driver event (rows checkpointed) 103
Class Constructor
Connection class 46
DMLGroup class 60
Schema class 55, 60
CLIEnvFile, CLIv2 variable 188
CLISPB.DAT 87, 107, 137, 157
CLIv2
buffer contents 28
CLI Error status message 68
CLIEnvFile variable
on Linux 188
GetErrorInfo 48
making direct calls 37
required levels 4, 207
TD_BUFFER_SIZE
Load driver attribute 75
Update driver attribute 93
TD_Evt_CLIError 82, 154
Stream driver event 130
Update driver event 101
TD_Evt_ConnectStatus 83
TD_NOTIFY_LEVEL settings 78
TD_OPER_CLI, TD_TRACE_LEVEL attribute 68
TD_TRACE_LEVEL setting 81
Connection class objects
AddArrayAttribute 44
AddAttribute 44
AddDMLGroup 45
AddSchema 45
ApplyRows 46
Checkpoint 46
EndAcquisition 47
GetBuffer 47
GetErrorInfo 47, 48
GetEvent 48
GetRow 49
GetSchema 49
GetTELINFO 50
Initiate 50
Index
PutBuffer 51
PutEvent 51
PutRow 52
PutTELINFO 52
Restart 52
Terminate 53
UseDMLGroups 53
Connection object
creating 23
initiating the connection 27
macro support (Stream driver) 139
parameters 23
reusing 37
terminating 37
z/OS support 43, 54, 59
converting
TIMESTAMP and INTERVAL data types 197
CREATE PROCEDURE, SQL statement
code samples 191, 193
configuring DBS 193
linking libraries 190
On Linux 188
On Windows 189
CREATE SET TABLE, SQL statement 194
Cufconfig utility 188, 189, 193
D
DateTime specifications, table of 197
DBCHCLN, CLI function 37
deadlocks, Teradata Database 36
DMLGroup class objects
AddDMLOption 59
AddSerializeOn 59
AddStatement 60
AddUseList 60
Class Constructor 60
dynamic loading 70
E
EndAcquisition 47
endian modes 176
error codes
21044, invalid restart argument values 34
no error return values 33
using GetErrorInfo 33
error tables
duplicate records 86
reusing table names 86
Load driver 86
Stream driver 135
Update driver 105
using existing tables
Load driver 76
Stream driver 117, 119
Update driver 94
external stored procedure See XSP
F
FastExport 54
FastLoad
column definitions for schema 54
protocols effect on restart log table
Load driver 76
Update driver 95
G
general information about Teradata 8
GetBuffer
object defined 47
GetErrorInfo 48
GetEvent
Export driver events 154
Load driver events 82
object defined 48
Stream driver events 129
Update driver events 101
using for run-time statistics 35
using in PutBuffer loading 28
GetRow 49
GetTELINFO, Connection class object 50
H
header files 233
HP-UX
code sample 209
notify exit routine default name
Load driver 78
Stream driver 122
Update driver 97
I
IBM z/OS
code samples 212
ICU
specifying directories in Linux PATH variables 212
IGNORE_DUPLICATE_INSERT_ROWS, DML Group
option 63
IGNORE_DUPLICATE_ROWS, DML Group option 63
IGNORE_DUPLICATE_UPDATE_ROWS, DML Group
option 63
IGNORE_EXTRA_DELETE_ROWS, DML Group option 63
IGNORE_EXTRA_ROWS, DML Group option 63
IGNORE_EXTRA_UPDATE_ROWS, DML Group option 63
IGNORE_MISSING_DELETE_ROWS, DML Group option
Index
63
IGNORE_MISSING_ROWS, DML Group option 63
IGNORE_MISSING_UPDATE_ROWS, DML Group option
63
indicator bytes
how length is determined 32
indicator-mode data format 32
when using PutBuffer 33
Information Products web site 8
Initiate 50
input Schema object using AddSchema 45
INSERT_FOR_MISSING_UPDATE_ROWS, DML Group
option 64
insertion errors
Load driver 86
Update driver 105
INTERVAL data type
converting 197
definition 197
L
Linux
code samples 211
compiling and linking options 233
supported platforms and compilers 203
M
macro support, Stream driver 139
MARK_DUPLICATE_INSERT_ROWS, DML Group option
64
MARK_DUPLICATE_ROWS, DML Group option 64
MARK_EXTRA_DELETE_ROWS, DML Group option 64
MARK_EXTRA_ROWS, DML Group option 64
MARK_EXTRA_UPDATE_ROWS, DML Group option 64
MARK_MISSING_DELETE_ROWS, DML Group option 64
MARK_MISSING_ROWS, DML Group option 64
MARK_MISSING_UPDATE_ROWS, DML Group option 64
master instance
communication with slave instances 176
endian mode 176
error reporting 178
Export driver required attributes 146
GetTELINFO object 50
Load driver required attributes 74, 92
parallel synchronization 176
PutTELINFO object 52
session distribution 178
Stream driver required attributes 116, 146
synchronization with slaves 176
TD_SYNC_TELINFO status message 70
timing issues 177, 178
Update driver required attributes 91
MultiLoad 54
O
ordering publications 8
P
performance considerations, factors of, 157
PERIOD data type
specifying for the schema 54
product version numbers 4
PutBuffer 51
arguments 29
method of loading rows 28
PutEvent
arguments 35
modifier data 155
PutRow 51, 52
PutTELINFO, Connection class object 52
Q
query banding optional attribute
defined 38
Export driver 151
Load driver 80
Stream driver 124
Update driver 99
R
required attributes
Stream driver 116
required privileges
Load driver 87
Stream driver 136
Update driver 107
restart log table
using existing restart log table
Load driver 76
Update driver 95
Restart, Connection class object 52
return codes 68, 176
run-time statistics 35
S
Schema object
AddColumn 54
AddColumn data types
TD_BIGINT 65
TD_BYTE 65
TD_BYTEINT 65
TD_CHAR 65
TD_DATE 65
TD_DATE_ANSI 65
TD_DECIMAL 65
Index
TD_FLOAT 65
TD_GRAPHIC 65
TD_INTEGER 65
TD_LONGVARCHAR 65
TD_LONGVARGRAPHIC 65
TD_PERIOD_DATE 65
TD_PERIOD_TIME 65
TD_PERIOD_TIME_TZ 65
TD_PERIOD_TS 65
TD_PERIOD_TS_TZ 65
TD_SMALLINT 65
TD_VARBYTE 65
TD_VARCHAR 65
TD_VARGRAPHIC 65
AddSchema function 45
Class Constructor 55, 60
defined 24
designating as input or output 24
SetType 58
using to specify macro parameters 139
serialization
enabling with DMLGroup object 36
using with Stream driver 35
session limits
Export driver 157
Load driver 87
Stream driver 136
Update driver 107
SetType 58
software releases
supported 3
Solaris running on a SPARC system and Solaris running on
an AMD Opteron system
code samples 209
reporting events
Export driver 150
Load driver 79
Stream driver 123
Update driver 98
specific tracing 40
status messages
CLI Error 68
DBS Error 69
TD_Call_EndAcq 69
TD_END_Method 69
TD_Error 69
TD_Success 69
TD_SYNC_Barrier 69
TD_SYNC_TELINFO 70
TD_Unavailable 70
TPTAPI Error 69
STL (Standard Template Library) 204, 241
T
TD_ACCOUNT_ID
Export driver 147
Load driver 74
Stream driver 117, 118
TD_AMP_CHECK
settings for nonparticipant AMPs 109
using with TD_DELETE_TASK 94
TD_APPENDERRORTABLE
Stream driver 117
TD_Attribute 64
TD_BLOCK_SIZE
Export driver 147
Export driver 147
Export driver 147
TD_BUFFER_MAX_SIZE
Export driver 148
TD_BUFFER_MODE
Load driver 73
Stream driver 116
TD_BUFFER_SIZE
Load driver 75
Stream driver 118
Update driver 93
Export driver 148
TD_CHARSET
Export driver 148
Load driver 75
Stream driver 118
Update driver 93
TD_DATA_ENCRYPTION
Export driver 148
Stream driver 118
Update driver 93
TD_DataType 65
for AddColumn function in the Schema object 65
using in the Schema object 24
TD_DATE_FORM
Export driver 148
Load driver 75
Stream driver 119
Update driver 93
TD_DELETE_TASK
Update driver 94
TD_DROPERRORTABLE
Load driver 76
Stream driver 119
Update driver 94
TD_DROPLOGTABLE
Load driver 76
Index
Update driver 95
TD_DROPMACRO
Stream driver 119
TD_DROPWORKTABLE
Update driver 95
TD_ERROR_LIMIT
Load driver 76
Stream driver 119
Update driver 95
TD_ERROR_TABLE
Stream driver 120
TD_ERROR_TABLE_1
Load driver 77
Update driver 96
TD_ERROR_TABLE_2
Load driver 77
Update driver 96
TD_Evt_ApplyCount
Load driver 85
Stream driver 130
Update driver 103
TD_Evt_BlockCount
Export driver 154
TD_Evt_BufferLayout
Load driver 83
Stream driver 130
Update driver 102
TD_Evt_CLIError
Export driver 154
Load driver 82
Stream driver 130
Update driver 101
TD_Evt_ConnectStatus
Export driver 154
Load driver event 83
Stream driver 130
Update driver 102
TD_Evt_CPUTime
Export driver 154
Load driver 83
Stream driver 131
Update driver 102
TD_Evt_DBSError
Export driver 154
Load driver 82
Stream driver 130
Update driver 102
TD_Evt_ErrorTable1
Load driver 85
Stream driver 132
Update driver 103
TD_Evt_ErrorTable2
Load driver 85
Update driver 103
TD_Evt_ExitCode
Export driver 154
Load driver 85
Stream driver 132
Update driver 103
TD_Evt_ExportCount
Export driver 154
TD_Evt_MacroNames
Stream driver 133
TD_Evt_OperVersion
Export driver 154
Stream driver 131
TD_Evt_RowCounts
Load driver 83
Stream driver 131
Update driver 102
TD_Evt_RowsCheckpointed
Load driver 84
Stream driver 132
Update driver 103
TD_Evt_Runstats
Stream driver 131
TD_Evt_Version
Export driver 155
Load driver 85
Stream driver 132
Update driver 104
TD_IGNORE_MAX_DECIMAL_DIGITS
Export driver 149
TD_INSTANCE_NUM
Export driver 145, 146
Load driver 74
Stream driver 116
TD_LOG_TABLE
Load driver 74
Stream driver 116
Update driver 92
TD_LOGON_MECH
Export driver 149
Load driver 77
Stream driver 120
Update driver 96
TD_LOGON_MECH_DATA
Export driver 149
Stream driver 120
Update driver 96
TD_LOGSQL
Export Driver 146
Load Driver 77
Stream Driver 121
Update Driver 96
TD_MACRODATABASE
Stream driver 121
TD_MAX_DECIMAL_DIGITS
Index
Export driver 149
TD_MAX_INSTANCES
Export driver 146
Load driver 74
Stream driver 116
TD_MAX_SESSIONS
Export driver 149
Load driver 78
Stream driver 121
Update driver 97
Update driver values 107
TD_MIN_SESSIONS
Export driver 149
Load driver 78
Stream driver 122
Update driver 97
Update driver values 107
TD_MSG_ENCODING
Export driver 149
Load driver 78
TD_NOTIFY_EXIT
Export driver 150
Load driver 78
Stream driver 122
Update driver 97
TD_NOTIFY_LEVEL
Export driver 150
Load driver 78
Stream driver 122
Update driver 97
TD_NOTIFY_METHOD
Export driver 150
Load driver 79
Stream driver 123
Update driver 98
TD_NOTIFY_STRING
Export driver 150
Load driver 79
Stream driver 123
Update driver 98
TD_OperatorType
TD_EXPORT 68
TD_LOAD 68
TD_STREAM 68
TD_UPDATE 68
TD_PACK
Stream driver 123
TD_PACKMAXIMUM
Stream driver 123
TD_PAUSE_ACQ
Load driver 79
Update driver 98
TD_QUERY_BAND_SESS_INFO
Export driver 151
Load driver 80
Stream driver 124
Update driver 99
TD_REPLICATION_OVERRIDE
Stream driver 125
TD_RESTARTMODE
Export driver 146
Load driver 74
Stream driver 116
TD_ROBUST
Stream driver 126
TD_SELECT_STMT
Export driver 146
TD_SYSTEM_OPERATOR
Export driver 146
Load driver 74
Stream driver 116
TD_TARGET_TABLE
Load driver 74
TD_TDP_ID
Export driver 152
Load driver 80
Stream driver 126
TD_TENACITY_HOURS
Export driver 152
Load driver 80
Stream driver 127
use with TD_DELETE_TASK 94
TD_TENACITY_SLEEP
Export driver 152
Load driver 80
Stream driver 127
use with TD_DELETE_TASK 94
TD_TRACE_LEVEL
Export driver 153
Load driver 81
Stream driver 128
Update driver 100
TD_TRACE_LEVEL attributes
TD_OFF 68
TD_OPER 68
TD_OPER_ALL 68
TD_OPER_CLI 68
TD_OPER_NOTIFY 68
TD_OPER_OPCOMMON 68
TD_TRACE_OUTPUT
Export driver 153
Load driver 81
Stream driver 129
Update driver 101
TD_USER_NAME
Export driver 146
Load driver 74
Stream driver 116
Index
TD_USER_PASSWORD
Export driver 146
Load driver 74
Stream driver 116
TD_WILDCARDINSERT
Load driver 82
TD_WORK_TABLE
Update driver 101
TD_WORKINGDATABASE
Export driver 153
Stream driver 129
Update driver 101
Teradata ICU 4, 207
Teradata PT API
building the connection object 23
parameters 63
status messages 68
TeraGSS 4, 207
Terminate
connection 37
specifications 53
TIMESTAMP data type
converting 197
definition 197
TPump 54, 115
U
UNIX
code samples 209
Load driver 78
Stream driver 122
Update driver 97
reporting events
Export driver 150
Load driver 79
Update driver 98
use lists, DMLGoup object 36
UseDMLGroups 53
UTF16
Connection Class 47
DMLGroup Class 60
encoding objects and messages 39
errors 39
Schema Class constructor 55
schema considerations 38
setting TD_CHARSET 38
TD_MSG_ENCODING attribute 39
UTF8
as Unicode default 39
Connection Class 47
DMLGroup Class 60
Schema Class 55
schema considerations 38
using TD_MSG_ENCODING 39
V
version numbers 4
W
Windows
code samples 207
Load driver 78
Stream driver 122
Update driver 97
prerequisites for understanding Teradata PT API 4
reporting events
Export driver 150
Load driver 79
Update driver 97, 98
work tables
TD_WORK_TABLE attribute 101
Update driver
using existing tables 95
workspace errors 109
usage 107
X
XSP
configuring on
Linux 188
Windows 189
defined
software dependencies 188
Z
z/OS
code samples 212
Index

2516 071a

Uploaded by

Copyright:

Available Formats

2516 071a

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

2516 071a

Uploaded by

Copyright:

Available Formats

Teradata Parallel Transporter

Application Programming Interface

Tools and Utilities

Note: When the drivers trace is disabled,

Note: When the drivers trace is disabled, TD_LOGSQL has no effect.

You might also like