Teradata Parallel Data Pump

Teradata Parallel Data Pump 

Reference 

Release 13.10 

B035-3021-020A 

February 2010

The product or products described in this book are licensed products of Teradata Corporation or its affiliates. 

Teradata, BYNET, DBC/1012, DecisionCast, DecisionFlow, DecisionPoint, Eye logo design, InfoWise, Meta Warehouse, MyCommerce, 

SeeChain, SeeCommerce, SeeRisk, Teradata Decision Experts, Teradata Source Experts, WebAnalyst, and You’ve Never Seen Your Business Like 

This Before are trademarks or registered trademarks of Teradata Corporation or its affiliates. 

Adaptec and SCSISelect are trademarks or registered trademarks of Adaptec, Inc. 

AMD Opteron and Opteron are trademarks of Advanced Micro Devices, Inc. 

BakBone and NetVault are trademarks or registered trademarks of BakBone Software, Inc. 

EMC, PowerPath, SRDF, and Symmetrix are registered trademarks of EMC Corporation. 

GoldenGate is a trademark of GoldenGate Software, Inc. 

Hewlett-Packard and HP are registered trademarks of Hewlett-Packard Company. 

Intel, Pentium, and XEON are registered trademarks of Intel Corporation. 

IBM, CICS, RACF, Tivoli, and z/OS are registered trademarks of International Business Machines Corporation. 

Linux is a registered trademark of Linus Torvalds. 

LSI and Engenio are registered trademarks of LSI Corporation. 

Microsoft, Active Directory, Windows, Windows NT, and Windows Server are registered trademarks of Microsoft Corporation in the United 

States and other countries. 

Novell and SUSE are registered trademarks of Novell, Inc., in the United States and other countries. 

QLogic and SANbox are trademarks or registered trademarks of QLogic Corporation. 

SAS and SAS/C are trademarks or registered trademarks of SAS Institute Inc. 

SPARC is a registered trademark of SPARC International, Inc. 

Sun Microsystems, Solaris, Sun, and Sun Java are trademarks or registered trademarks of Sun Microsystems, Inc., in the United States and other 

countries. 

Symantec, NetBackup, and VERITAS are trademarks or registered trademarks of Symantec Corporation or its affiliates in the United States 

and other countries. 

Unicode is a collective membership mark and a service mark of Unicode, Inc. 

UNIX is a registered trademark of The Open Group in the United States and other countries. 

Other product and company names mentioned herein may be the trademarks of their respective owners. 

THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROVIDED ON AN “AS-IS” BASIS, WITHOUT WARRANTY OF ANY KIND, EITHER 

EXPRESS OR IMPLIED, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR 

NON-INFRINGEMENT. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO THE ABOVE EXCLUSION 

MAY NOT APPLY TO YOU. IN NO EVENT WILL TERADATA CORPORATION BE LIABLE FOR ANY INDIRECT, DIRECT, SPECIAL, INCIDENTAL, 

OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS OR LOST SAVINGS, EVEN IF EXPRESSLY ADVISED OF THE POSSIBILITY OF 

SUCH DAMAGES. 

The information contained in this document may contain references or cross-references to features, functions, products, or services that are 

not announced or available in your country. Such references do not imply that Teradata Corporation intends to announce such features, 

functions, products, or services in your country. Please consult your local Teradata Corporation representative for those features, functions, 

products, or services available in your country. 

Information contained in this document may contain technical inaccuracies or typographical errors. Information may be changed or updated 

without notice. Teradata Corporation may also make improvements or changes in the products or services described in this information at any 

time without notice. 

To maintain the quality of our products and services, we would like your comments on the accuracy, clarity, organization, and value of this 

document. Please e-mail: 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 © 1996-2010 by Teradata Corporation. All Rights Reserved.

Preface 

Purpose 

This book provides information about Teradata TPump, which is a Teradata ® Tools and 

Utilities product. Teradata Tools and Utilities is a group of products designed to work with 

Teradata Database. 

Teradata TPump is a data loading utility that helps maintain (update, delete, insert, and 

atomic upsert) the data in Teradata Database. Teradata TPump uses standard Teradata SQL to 

achieve moderate to high data loading rates to Teradata Database. Multiple sessions and 

multi-statement requests are typically used to increase throughput. 

Audience 

This book is intended for use by: 

• System and application programmers 

• System administrators 

Supported Releases 

This book supports the following releases: 

• Teradata Database 13.10 

• Teradata Tools and Utilities 13.10 

• Teradata TPumpVersion 13.10 

Note: See “Teradata TPump Script Example” on page 72 to verify the Teradata TPump 

version number. 

To locate detailed supported release information: 

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

2 Under Online Publications, click General Search. 

3 Type 3119 in the Publication Product ID box. 

4 Under Sort By, select Date. 

5 Click Search. 

6 Open the version of the Teradata Tools and Utilities ##.##.## Supported Platforms and 

Product Versions spreadsheet associated with this release. 

Teradata Parallel Data Pump Reference 3

Preface 

Prerequisites 

The spreadsheet includes supported Teradata Database versions, platforms, and product 

release numbers. 

Prerequisites 

The following prerequisite knowledge is required for this product: 

• Basic computer technology 

• SQL and Teradata SQL 

• Teradata Database, database management systems 

• Teradata utilities that load and retrieve data 

Changes to This Book 

The following changes were made to this book in support of the current release. Changes are 

marked with change bars. For a complete list of changes to the product, see the Release 

Definition associated with this release. 

Date and Release 

February 2010 

Teradata Tools and 

Utilities 13.10 

April 2009 



Description 

• IBM C is used to develop Teradata TPump replacing SAS/C. 

• Teradata TPump is now supported on z/Linux, and discontinued on z/ 

VM and MP-RAS 

• Updated Compiling and Linking Routines. See Appendix C: “INMOD 

and Notify Exit Routine Examples”. 

• Updated sample outputs for all Invocation Examples. See Appendix B: 

“Teradata TPump Examples” 

• Teradata TPump supports Temporal Semantics. 

• To ensure data integrity when target tables have identity columns, use 

ROBUST ON in the BEGIN LOAD command 

• Added a section on how to avoid data errors. 

• The ACCEPT command now supports environment variables. 

• Added information on Loading No Primary Index (NoPI) tables in 

chapter 1. 

• Changed packing factor from 600 to 2430. 

4 Teradata Parallel Data Pump Reference

Preface 

Additional Information 

Date and Release 

August 2008 



Description 

• Included information about not using a semicolon in object names 

• Added Appendix D, User-Defined-Types and User-Defined-Methods 

• Updated IBM terminology 

• ACCEPT and SET commands can now be run before LOGON and 

LOGDATA 

• Added PERIOD data type 

• Made changes to the Decimal data type specifications 

• Described restrictions object names and semicolon(;) 

• Added Geospatial type information 

• Made changes concerning checkpoint specified as zero 

• Updated IBM and NCR naming 

• Updated troubleshooting exits with and error code 8 


Additional information that supports this product and Teradata Tools and Utilities is available 

at the web sites listed in the table that follows. In the table, mmyx represents the publication 

date of a manual, where mm is the month, y is the last digit of the year, and x is an internal 

publication code. Match the mmy of a related publication to the date on the cover of this book. 

This ensures that the publication selected supports the same release. 

Type of Information Description Access to Information 

Release overview 

Late information 

Use the Release Definition for the following 

information: 

• Overview of all of the products in the 

release 

• Information received too late to be 

included in the manuals 

• Operating systems and Teradata 

Database versions that are certified to 

work with each product 

• Version numbers of each product and 

the documentation for each product 

• Information about available training 

and the support center 


2 Under Online Publications, click General Search. 

3 Type 2029 in the Publication Product ID box. 

4 Click Search. 

5 Select the appropriate Release Definition from 

the search results. 


Preface 


Type of Information Description Access to Information 

Additional product 

information 

CD-ROM images 

Ordering 

information for 

manuals 

General information 

about Teradata 

Use the Teradata Information Products web 

site to view or download specific manuals 

that supply related or additional 

information to this manual. 

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. 

Use the Teradata Information Products web 

site to order printed versions of manuals. 

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 


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 TPump are as 

follows: 

• Introduction to Teradata B035-2425-mmyx 

• SQL Fundamentals, B035-1141-mmyx 

• SQL External Routine Programming, B035- 

1147-mmyx 

• Teradata Parallel Data Pump Reference 

B035-3021-mmyx 

• Teradata Tools and Utilities Command Summary 

B035-2401-mmyx 

• Teradata Tools and Utilities Access Module 

Programmer Guide B035-2425-mmyx 


2 Under the Online Publications subcategory, 

Browse by Category, click Data Warehousing. 

3 Click CD-ROM List and Images. 

4 Follow the ordering instructions. 


2 Under Print & CD Publications, click How to 

Order. 

3 Follow the ordering instructions. 

1 Go to Teradata.com. 

2 Select a link. 


Table of Contents 

Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 

Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 

Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 

Supported Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4 

Changes to This Book. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4 

Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5 

Chapter 1: 

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 

Teradata TPump Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 

Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 

Complementing MultiLoad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 

Teradata TPump Support Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 

What it Does. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 

How it Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 

Operating Features and Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 

Operating Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 

Input Data Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 

Client Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 

Data Conversion Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 

Checkpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 

Unicode Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 

Client Character Set/Client Type Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 

Teradata TPump Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 

Teradata TPump Command Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 

Teradata SQL Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 

The Teradata TPump Task. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 

Task Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 

DML Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 

Upsert Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 

Teradata TPump Macros. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 

Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 



Privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34 

Fallback vs. Nonfallback Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36 

Chapter 2: 

Using Teradata TPump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37 

Invoking Teradata TPump. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37 

Teradata TPump Support Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37 

File Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41 

IBM Mainframe Client-Based Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41 

UNIX- and Windows-based Systems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42 

Interactive Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42 

Batch Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43 

Run-time Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44 

Examples - Redirection of Inputs and Outputs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50 

Terminating Teradata TPump. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51 

Normal Termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51 

Abort Termination. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52 

After Terminating a Teradata TPump Job. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52 

Restart and Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52 

Basic Teradata TPump Recovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53 

Protection and Location of Teradata TPump Database Objects . . . . . . . . . . . . . . . . . . . . .53 

Reinitialize a Teradata TPump Job. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55 

Recover an Aborted Teradata TPump Job. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55 

Recover from Script Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56 

Program Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56 

Teradata TPump Command Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56 

Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58 

ANSI/SQL DateTime Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62 

Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63 

Specify a Character Set. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63 

Graphic Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66 

Graphic Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67 

Restrictions and Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67 

Termination Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .68 

Writing a Teradata TPump Job Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69 

Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69 

Script Writing Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69 

Procedure for Writing a Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71 

Teradata TPump Script Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .72 

View Teradata TPump Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74 



Teradata TPump Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 

Teradata TPump Options Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 

Logoff/Disconnect Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 

Progress Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 

Monitor Teradata TPump Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 

Monitor Interface Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 

Teradata TPump Monitor Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 

Teradata TPump Monitor Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 

Estimating Space Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 

Space Calculation Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 

Chapter 3: 

Teradata TPump Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 

Syntax Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 

Object Name Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 

Geospatial Data Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 

Large Decimal and BIGINT Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 

Teradata TPump Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 

Teradata TPump Teradata SQL Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 

ACCEPT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 

BEGIN LOAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 

DATABASE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 

DATEFORM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 

DELETE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 

DISPLAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 

DML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 

Serialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 

The Basic Upsert Feature. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 

Upsert. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 

The Atomic Upsert Feature. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 

END LOAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 

EXECUTE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 

FIELD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 

FILLER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 

IF, ELSE, and ENDIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 

IMPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 

INSERT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 

Temporal Semantics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 



LAYOUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160 

LOGDATA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .163 

LOGMECH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .164 

LOGOFF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .165 

LOGON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .167 

LOGTABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171 

NAME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .173 

PARTITION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175 

ROUTE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .179 

RUN FILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .181 

SET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .183 

SYSTEM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .185 

TABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .186 

UPDATE Statement and Atomic Upsert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .188 

Temporal Semantics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .189 

Chapter 4: 

Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .195 

Early Error Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .195 

Error Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .195 

Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .196 

Reading Teradata TPump Error Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .199 

Avoiding Data Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .200 

Acquisition Error Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .200 

Interpreting Error Table Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .201 

Teradata TPump Performance Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .202 

Chapter 5: 

Using INMOD and Notify Exit Routines. . . . . . . . . . . . . . . . . . . . . . . . . . .203 

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .203 

INMOD Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .203 

Notify Exit Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .204 

Programming Languages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .204 

Programming Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .205 

Routine Entry Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .205 

The Teradata TPump/INMOD Routine Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .206 



Teradata TPump/Notify Exit Routine Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 

Rules and Restrictions for Using Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 

Using INMOD and Notify Exit Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 

Teradata TPump-specific Restrictions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 

Teradata TPump/INMOD Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 

Preparing the INMOD Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 

INMOD Input Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 

INMOD Output Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 

Programming INMODs for UNIX-based Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 

Compiling and Linking a C INMOD on a UNIX-based Client. . . . . . . . . . . . . . . . . . . . 218 

Compiling and Linking a C INMOD on Sun Solaris SPARC . . . . . . . . . . . . . . . . . . . . . 219 

Compiling and Linking a C INMOD on a Sun Solaris Opteron . . . . . . . . . . . . . . . . . . . 220 

Compiling and Linking a C INMOD on HP-UX PA RISC . . . . . . . . . . . . . . . . . . . . . . . 221 

Compiling and Linking a C INMOD on HP-UX Itanium. . . . . . . . . . . . . . . . . . . . . . . . 222 

Compiling and Linking a C INMOD on IBM AIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 

Compiling and Linking a Notify Exit Routine on IBM AIX . . . . . . . . . . . . . . . . . . . . . . 223 

Compiling and Linking a C INMOD on a Linux Client . . . . . . . . . . . . . . . . . . . . . . . . . 225 

Compiling and Linking a C INMOD on a z/Linux Client . . . . . . . . . . . . . . . . . . . . . . . . 225 

Compiling and Linking a C INMOD on on IBM OS z/OS . . . . . . . . . . . . . . . . . . . . . . . 226 

Programming INMODs for a Windows Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227 

Compiling and Linking a C INMOD on a Windows Client . . . . . . . . . . . . . . . . . . . . . . 227 

Appendix A: 

How to Read Syntax Diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 

Syntax Diagram Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 

Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 

Multiple Legitimate Phrases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 

Sample Syntax Diagram. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 

Diagram Identifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 

Appendix B: 

Teradata TPump Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 

Simple Script Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 

Restarted Upsert Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239 

Example Using the TABLE Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 



Appendix C: 

INMOD and Notify Exit Routine Examples . . . . . . . . . . . . . . . . . . . . . . .247 

C INMOD - UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .247 

Sample Notify Exit Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .250 

Appendix D: 

User-Defined-Types 

and User-Defined-Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .257 

User-Defined-Types and User-Defined-Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .257 

User-Defined Types (UDTs). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .257 

User-Defined-Methods (UDMs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .258 

Creating UDTs with Teradata TPump. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .258 

Inserting and Retrieving UDTs with Client Products. . . . . . . . . . . . . . . . . . . . . . . . . . . . .258 

External Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .258 

Inserting UDTs with Teradata TPump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .259 

Retrieving UDTs with Teradata TPump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .259 

Retrieving UDT Metadata with Teradata TPump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .259 

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .261 

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .271 


List of Tables 

Table 1: Teradata TPump Data Formats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 

Table 2: Standard Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 

Table 3: Japanese Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 

Table 4: Chinese Character Sets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 

Table 5: Korean Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 

Table 6: General Guidelines for Choosing Client Character Sets . . . . . . . . . . . . . . . . . . . . . . . 27 

Table 7: Teradata TPump Command Input Activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 

Table 8: Teradata TPump Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 

Table 9: teradata SQL Statements in Teradata TPump . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 

Table 10: Comparison of Fallback and Nonfallback Target Tables . . . . . . . . . . . . . . . . . . . . . 36 

Table 11: Data Sets, Files and Input/Output Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 

Table 12: Run-time Parameters/Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 

Table 13: Teradata TPump Operators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 

Table 14: Teradata TPump Conditional Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 

Table 15: Predefined System Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 

Table 16: Ways to Either Specify a Character Set or Accept a Default Specification . . . . . . . 64 

Table 17: Character Set Specifications for AXSMOD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 

Table 18: Character Sets Impact on Teradata TPump Commands . . . . . . . . . . . . . . . . . . . . . 65 

Table 19: GRAPHIC Data Types for datadesc option in FIELD or FILLER Statement . . . . . 66 

Table 20: Restrictions and Limitations on Operational Features and Functions . . . . . . . . . . 67 

Table 21: Termination Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 

Table 22: Teradata TPump Statistics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 

Table 23: Monitor Interface Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 

Table 24: Teradata TPump Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 

Table 25: Teradata TPump Teradata SQL Statements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 

Table 26: Events that Create Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 

Table 27: DATEFORM Command Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 

Table 28: ANSI/SQL DateTime Specifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 

Table 29: Teradata TPump Error Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 

Table 30: Acquisition Error Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 

Table 31: INMOD Routines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 

Table 32: Programming Routines by Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 


List of Tables 

Table 33: Entry Points for INMOD Routines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .205 

Table 34: NOTIFY EXIT Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .206 

Table 35: Teradata TPump-to-INMOD Status Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .206 

Table 36: INMOD-to-Teradata TPump Interface Status Codes. . . . . . . . . . . . . . . . . . . . . . . .207 

Table 37: Events Passed to the Notify Exit Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .208 

Table 38: INMOD Input Return Code Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .216 

Table 39: INMOD Output Return Code Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .217 


CHAPTER 1 

Overview 

This chapter provides an introduction to Teradata TPump. Topics include: 

• Teradata TPump Utility 

• Operating Features and Capabilities 

• Teradata TPump Commands 

• The Teradata TPump Task 

Teradata TPump Utility 

The following information provides a general overview of the Teradata TPump utility. 

Description 

Teradata TPump is a data loading utility that helps maintain (update, delete, insert, and 

atomic upsert) the data in Teradata Database. Teradata TPump allows near-real time data to 

be achieved in the data warehouse. 

Teradata TPump uses standard Teradata SQL to achieve moderate to high data loading rates to 

Teradata Database. Multiple sessions and multistatement requests are typically used to 

increase throughput. 

Teradata TPump provides an alternative to Teradata MultiLoad for the low volume batch 

maintenance of large databases under control of a Teradata system. Instead of updating 

Teradata Databases overnight, or in batches throughout the day, Teradata TPump updates 

information in real time, acquiring data from the client system with low processor utilization. 

It does this through a continuous feed of data into the data warehouse, rather than through 

traditional batch updates. Continuous updates result in more accurate, timely data. 

Unlike most load utilities, Teradata TPump uses row hash locks rather than table level locks. 

This allows queries to be run while Teradata TPump is running. This also means that Teradata 

TPump can be stopped instantaneously. 

Teradata TPump provides a dynamic throttling feature that enables it to run “all out” during 

batch windows, but within limits when it may impact other business uses of Teradata 

Database. Operators can specify the number of statements run per minute, or may alter 

throttling minute-by-minute, if necessary. 

Teradata TPump’s main attributes are: 


Chapter 1: Overview 


Complementing MultiLoad 

• Simple, hassle-free setup – does not require staging of data, intermediary files, or special 

hardware. 

• Efficient, time-saving operation – jobs can continue running in spite of database restarts, 

dirty data, and network slowdowns. Jobs restart without intervention. 

• Flexible data management – accepts an infinite variety of data forms from an infinite 

number of data sources, including direct feeds from other databases. Teradata TPump is 

also able to transform that data on the fly before sending it to Teradata. SQL statements 

and conditional logic are usable within the utilities, making it unnecessary to write 

wrapper jobs around the utilities. 

Note: Full tape support is not available for any function in Teradata TPump for networkattached 

client systems. To import data from a tape, a custom access module needs to be 

written that interfaces with the tape device. Refer to Teradata Tools and Utilities Access Module 

Programmer Guide for information about how to write a custom access module. 

Teradata TPump uses MultiLoad-like syntax, which leverages MultiLoad knowledge and 

power, provides easy transition from MultiLoad to Teradata TPump, and supports the useful 

upsert feature. Teradata TPump shares much of its command syntax with MultiLoad, which 

facilitates conversion of scripts between the two utilities; however, there are substantial 

differences in how the two utilities operate. 

Teradata TPump complements MultiLoad in the following ways: 

• Economies of Scale 

• Concurrency 

• Resource Consumption 

Economies of Scale 

MultiLoad has an economy of scale and is not necessarily efficient when operating on really 

large tables when there are not many rows to insert or update. For MultiLoad to be efficient, it 

must touch more than one row per data block in Teradata Database. 

For example, to achieve efficient MultiLoad performance on a two billion, 65-byte row table, 

composed of 16KB blocks, more than 0.4% of the table (8,125,000 rows) must be affected. 

While 0.4% of a table is a small update, eight million records is probably more data than 

should be run through a BTEQ script. 

Concurrency 

MultiLoad is limited to a Teradata Database variable limit for the maximum number of 

instances running concurrently. Teradata TPump does not impose this limit. In addition, 

while MultiLoad uses table-level locks, Teradata TPump uses row-hash locks, making 

concurrent updates on the same table a possibility. 

Finally, because of the phased nature of MultiLoad, there are potentially inconvenient 

windows of time when MultiLoad cannot be stopped without losing access to the target tables. 




In contrast, Teradata TPump can always be stopped and all of its locks dropped with no ill 

effect. 

Resource Consumption 

MultiLoad is designed for the highest possible throughput, and uses any database and host 

resources that help to achieve this capability. There is no way to reduce MultiLoad's resource 

consumption—even if a longer run time for the job is acceptable. Teradata TPump, however, 

has a built-in resource governing facility. 

This allows the operator to specify how many updates occur (the statement rate) minute by 

minute, and then change the statement rate, while the job continues to run. Thus, this facility 

can be used to increase the statement rate during windows when Teradata TPump is running 

by itself, but then decrease the statement rate later on, if users log on for ad hoc query access. 

Teradata TPump Support Environment 

The data-handling functionality of Teradata TPump is enhanced by the Teradata TPump 

support environment. In addition to coordinating activities involved in Teradata TPump 

tasks, it provides facilities for managing file acquisition, conditional processing, and 

performing certain Data Manipulation Language (DML) and Data Definition Language 

(DDL) activities on Teradata Database. The Teradata TPump support environment enables an 

additional level of user control over Teradata TPump. 

For more information, see “Teradata TPump Support Environment” on page 37. 

What it Does 

Within a single invocation of Teradata TPump, one or more distinct Teradata TPump tasks 

can be executed in series with any Teradata TPump support commands. 

The Teradata TPump task provides the acquisition of data from client files for application to 

target tables through INSERT, UPDATE, or DELETE statements that specify the full primary 

index. Data is retrieved from the client, and sent as transaction rows to Teradata Database, 

which are immediately applied to the various target tables. 

Each Teradata TPump task can acquire data from one or many client files with similar or 

different layouts. From each source record, one or more INSERT, UPDATE, or DELETE 

statements can be generated and directed to any target table. 

The following concepts may improve how Teradata TPump is understood. 

• The language of Teradata TPump commands and statements is used to describe the task 

which needs to be accomplished. 

• Teradata TPump examines all commands and statements for a task, from the BEGIN 

LOAD command through the END LOAD command, before actually executing the task. 

• After all commands and statements involved in a given task have been processed and 

validated by Teradata TPump, the Teradata TPump task is executed as described in this 

and subsequent chapters. 




How it Works 

• Optionally, Teradata TPump supports data serialization for a given row, which guarantees 

that if a row insert is immediately followed by a row update, the insert is processed first. 

This is done by hashing records to a given session. 

• Teradata TPump supports bulletproof restartability using time-based checkpoints. Using 

frequent checkpoints provides a greater ease in restarting, but at the expense of the 

checkpointing overhead. 

• Teradata TPump supports upsert logic similar to MultiLoad. 

• Teradata TPump supports insert/update/delete statements in multiple-record requests. 

• Teradata TPump uses macros to minimize network overhead. Before Teradata TPump 

begins a load, it sends the statements to Teradata Database to create equivalent macros for 

every insert/update/delete statement used in the job script. The execute macro requests, 

rather than lengthy text requests, are then executed iteratively during a job run. 

• Teradata TPump supports interpretive, record manipulating and restarting features 

similar to MultiLoad. 

• Teradata TPump supports conditional apply logic, similar to MultiLoad. 

• Teradata TPump supports error treatment options, similar to MultiLoad. 

• Teradata TPump runs as a single process. 

• Teradata TPump supports Teradata Database internationalization features such as kanji 

character sets. 

• Up to 2430 operations can be packed into a single request for network efficiency. The limit 

of 2430 may vary as the overall limit for a request is one megabyte. Teradata TPump 

assumes that every statement is a one- or two- (for fallback) step request. 

Teradata TPump is a Teradata utility with functions similar to the MultiLoad utility. 

MultiLoad edits Teradata tables by processing insert, updates, and deletes, and so does 

Teradata TPump. This section provides insight into the important differences between 

MultiLoad and Teradata TPump. All of the information in this section is discussed in further 

detail later in this document, either explicitly or by implication. 

Methods of Operation 

MultiLoad performs Teradata Database updates in phases. During the first phase of operation, 

MultiLoad uses a special database and CLIv2 protocol for efficiently sending large (64 KB) 

data messages to the database. The data is stored in a temporary table. During the second 

phase of operation, the temporary table is sorted, then changes from it are applied to various 

target tables. In this phase, processing is entirely in the database while MultiLoad on the client 

waits to see if the job completes successfully. 

Teradata TPump performs Teradata Database updates asynchronously. Changes are sent in 

conventional CLIv2 parcels and applied immediately to target tables. To improve its efficiency, 

Teradata TPump builds multiple statement requests and provides the serialize option to help 

reduce locking overhead. 




Economy of Scale and Performance 

MultiLoad performance improves as change volume increases because, in phase two of 

MultiLoad, changes are applied to target tables in a single pass. All changes for any physical 

data block are effected using one read and one write of the block. Furthermore, the temporary 

table and the sorting process used by MultiLoad are additional overheads that must be 

“amortized” through the volume of changes. 

Teradata TPump, on the other hand, performs better for relatively low change volume because 

there is no temporary table overhead. Teradata TPump becomes expensive for large volumes 

of data because multiple updates to a physical data block will most likely result in multiple 

reads and writes of the block. 

Loading No Primary Index (NoPI) Tables 

A NoPI table has no primary index. These tables can be used as staging tables where data is 

always appended to the table, making population of the table generally faster than that of a 

traditional table containing a primary index. 

NoPI tables could increase performance for Teradata TPump Array INSERT. 

Multiple Statement Requests 

The most important technique used by Teradata TPump to improve performance over 

MultiLoad is the multiple statement request. Placing more statements in a single request is 

beneficial for two reasons. First, it reduces network overhead because large messages are more 

efficient than small ones. Secondly, (in ROBUST mode) it reduces Teradata TPump recovery 

overhead, which amounts to one extra database row written for each request. Teradata TPump 

automatically packs multiple statements into a request based upon the PACK specification in 

the BEGIN LOAD command. 

Macro Creation 

Teradata TPump uses macros to efficiently modify tables rather than actual DML commands. 

The technique of changing statements into equivalent macros before beginning the job greatly 

improves performance. 

Specifically, the benefits of using macros are: 

• The size of network (and channel) messages sent to the database by Teradata TPump are 

reduced. 

• Teradata Database parsing engine overhead is reduced because the execution plans (or 

steps) for macros are cached and re-used. This eliminates normal parser handling, where 

each request sent by Teradata TPump is planned and optimized. 

Because the space required by macros is negligible, the only issue regarding macros is where 

they are placed in the database. Macros are put into the database that contains the restart log 

table or the database specified using the MACRODB keyword in the BEGIN LOAD command. 

Locking and Transactional Logic 

In contrast to MultiLoad, Teradata TPump uses conventional row hash locking, which allows 

for some amount of concurrent read and write access to its target tables. At any point, 




Teradata TPump can be stopped while retaining full accessibility to the target tables. Note 

however, that if Teradata TPump is stopped, depending on the nature of the update process, 

the relational integrity of the data might be impaired. 

This differs from MultiLoad, which operates as a single logical update to one or more target 

tables. Once MultiLoad goes into phase two of its logic, the job is essentially irreversible and 

all target tables are locked for write access until the job completes. 

If Teradata TPump operates on rows that have associated triggers, the triggers are invoked as 

necessary. 

Recovery Logic and Overhead 

In Teradata TPump’s ROBUST mode, one database row is written in the log restart table for 

every request that it issues. This collection of rows in the restart log table can be referred to as 

the request log. Because a request is guaranteed by the database to either completely finish or 

completely rollback, the request log will always accurately reflect the completion status of a 

Teradata TPump import. Thus, the request log overhead for restart logic decreases as the 

number of statements packed per request increases. 

Teradata TPump also allows a checkpoint interval to be specified. During the checkpoint 

process Teradata TPump flushes all pending changes from the import file to the database and 

also cleans out the request log. The larger the checkpoint interval, the larger the request log 

(and its table) is going to grow. Upon an unexpected restart, Teradata TPump scans the 

import data source along with the request log in order to re-execute the statements not found 

in the request log. 

In Teradata TPump’s SIMPLE (non-ROBUST) mode, basic checkpoints are created. If a 

restart occurs between checkpoints, then some requests will likely be reprocessed. This is 

adequate protection under some circumstances. 

In contrast, phase one of MultiLoad uses checkpoints so restarts do not force a job to always 

restart from the beginning. During phase two, MultiLoad uses its temporary table as a 

repository of all changes to be applied. The database process of applying the changes 

guarantees that no changes are missed or applied more than once. 

Serialization of Changes 

In certain uses of Teradata TPump or MultiLoad, it is possible to have multiple changes to one 

row in a single job. For instance, a row might be inserted, then updated during the batch job, 

or it might be updated, then deleted. In any case, the correct ordering of these operations is 

obviously very important. MultiLoad automatically guarantees that this ordering of 

operations is maintained correctly. By using the serialization feature, Teradata TPump can 

accomplish the same ordering of operations, but to make it happen in Teradata TPump, a 

small amount of scripting work and utility overhead are required. 

The use of the serialize option on the BEGIN LOAD command guarantees that Teradata 

TPump will send each change for a data record of a given key in order. The KEY modifier to 

the FIELD command is how a script specifies that a given field is to be part of the serialization 

key. The intent of this feature is to allow specification of the key corresponding to the primary 

index of the target table. In fact, the TABLE command automatically qualifies the generated 




fields with the KEY modifier when the fields are part of the primary index of the table. If the 

DML statements in the Teradata TPump script specify more than one target table then it is up 

to the script author to make sure that primary indices of all the tables match when using the 

serialization feature. 

The serialization feature works by hashing each data record based upon its key to determine 

which session transmits the record to the database. Thus the extra overhead in the application 

is derived from the mathematical operation of hashing and from the 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 database deadlock. 

Deadlocks can occur when requests for the application happen to affect row(s) that use the 

same hash code within the database. Although deadlocks are handled by the database and by 

Teradata TPump correctly, the resolution process is time-consuming and adds additional 

overhead to the application because it must re-execute requests that roll back due to deadlock. 

In addition to using SERIALIZEON in the BEGIN LOAD command, the SERIALIZEON 

keyword can also be specified in the DML command. This lets serialization to be turned on for 

the fields specified. For more information on the DML-based serialization feature, refer to 

“DML” on page 115. 

Dual Database Strategy 

The serialization feature is intended to support a variety of other potential customer 

applications that go under the general heading dual database. These are applications that in 

some way take a live feed of inserts, updates, and deletes from another database and apply 

them without any preprocessing to Teradata Database. 

Both Teradata TPump and MultiLoad are potential parts of the dual database strategy. A dual 

database application will generate a DML stream which will be routed to Teradata TPump or 

MultiLoad through a paramod/inmod specific to the application. The choice between 

Teradata TPump or MultiLoad will depend on such things as the volume of data (with higher 

volumes favoring MultiLoad) and the concurrent access requirements (with greater access 

requirements favoring Teradata TPump). 

Resource Usage and Limitations 

A feature unique to Teradata TPump is the ability to constrain run-time resource usage 

through the statement rate feature. Teradata TPump provides control over the rate per minute 

at which statements are sent to the database and the statement rate correlates directly to 

resource usage on both the client and in the database. The statement rate can be controlled in 

two ways, either dynamically while the job is running, or it can be scripted into the job with 

the RATE keyword on the BEGIN LOAD command. Dynamic control over the statement rate 

is provided by updates to a table on the database. 

In contrast with Teradata TPump, MultiLoad always uses CPU and memory very efficiently. 

During phase one (assuming that the database is not a bottleneck), MultiLoad will probably 

bottleneck on the client, consuming significant network or channel resources. During phase 

two, MultiLoad uses very significant database disk, CPU, and memory resources. In fact, the 

database limits the number of concurrent MultiLoad, FastLoad, and FastExport jobs for the 



Operating Features and Capabilities 

very reason that they are so resource-intensive. Teradata TPump has no such databaseimposed 

limitation. 

Warning: 

Although Teradata Database imposes no limitation on the number of concurrent Teradata 

TPump jobs that are possible, an excessive number of small jobs causes contention on the 

Teradata Database system catalogue. The limit will vary from one installation to another, and 

each installation should determine its own capacity for running a multiplicity of Teradata TPump 

jobs to avoid potential deadlocks. 


The following section describes the operating modes; input data formats; and client, unicode, 

and site-defined character sets for Teradata TPump. For information about supported 

operating systems, refer to Teradata Tools and Utilities ##.##.## Supported and Certified 

Versions, B035-3119 for this release at http://www.info.teradata.com/. 

Operating Modes 

Teradata TPump runs in the following operating modes: 

• Interactive – Interactive processing involves the more or less continuous participation of 

the user. 

• Batch – Batch programs process data in discrete groups of previously scheduled 

operations, typically in a separate operation, rather than interactively or in real-time. 

Input Data Formats 

Table 1 lists the input data formats supported on UNIX and Windows platforms. Mainframes 

have standard records. 

Table 1: Teradata TPump Data Formats 

Data Format 

BINARY 

FASTLOAD 

TEXT 

UNFORMAT 

VARTEXT 

Description 

Specifies that each input record is a 2-byte integer, n, followed by n bytes of data. 

Specifies that each input record is a 2-byte integer, n, followed by n bytes of data, 

followed by an end-of-record marker, either X'0A' or X'0D'. 

Specifies that each input record is an arbitrary number of bytes followed by an endof-record 

marker, which is a: 

• Linefeed (X'0A') on UNIX platforms. 

• Carriage-return/linefeed pair (X'0D0A') on Windows platforms. 

Specifies that each input record is defined by FIELD commands of the specified 

layout. 

Specifies that each variable-length text record has each field separated by a 

delimiter character. 




Client Character Sets 

For a description of the supported input file formats, see the discussion of the FORMAT 

option for network-attached client systems in the IMPORT Command description in 

Chapter 3: “Teradata TPump Commands.” 

Standard Character Sets 

Table 2 lists the standard character sets which are supported by Teradata Database. 

Table 2: Standard Character Sets 

Standard Character Sets 

System Configuration 

Channel-Attached 

Network-Attached 

Name 

EBCDIC 

ASCII 

The terms ASCII and EBCDIC are often used in ambiguous ways, and this presents a difficulty 

for accented and non-Latin characters. The user should select a client character set that exactly 

matches the character set that the import data uses. 

If accented and non-Latin characters are used, do not use the ASCII or EBCDIC client 

character sets. Instead, load and use one of the other Teradata-supplied character sets, or a 

site-defined character set that exactly matches the application character set, such as: 

EBCDIC037_0E for channel-attached clients (for the United States or Canada), LATIN1_0A, 

LATIN9_0A (for Western European languages), LATIN1252_0A for Western European 

Microsoft ® Windows clients, or UTF-8 for UNIX clients. 

Japanese Characters Sets 

Table 3 lists the Japanese character sets which are supported by Teradata Database. 

Table 3: Japanese Character Sets 

Japanese Character Sets 



Character Set Name 

KATAKANAEBCDIC 

KANJIEBCDIC5026_0I 

KANJIEBCDIC5035_0I 


KANJIEUC_0U 

KANJISJIS_0S 

For more information on kanji character sets, refer to International Character Set Support. 




Caution: 

Teradata TPump statements do not accept object names specified in internal database 

hexadecimal form and do not display object names in hexadecimal form. 

Chinese and Korean Character Sets 

Chinese and Korean character sets are available for channel- and network-attached client 

systems. 

Table 4 lists the Chinese character sets: 

Table 4: Chinese Character Sets 

Chinese Character Sets 



Name 

SCHEBCDIC935_2IJ 

TCHEBCDIC937_3IB 


SCHGB2312_1T0 

TCHBIG5_1R0 

Table 5 lists the Korean character sets: 

Table 5: Korean Character Sets 

Korean Character Sets 




Name 

HANGULEBCDIC933_1II 

HANGULKSC5601_2R4 

Rules for Using Chinese and Korean Character Sets 

Certain rules apply when using Chinese and Korean character sets on channel- and networkattached 

platforms. 

• Object Names 

Teradata Database supports multi-byte characters in object names when the client session 

character set is UTF-8 or UTF-16. For a list of valid and non-valid characters when multibyte 

object names are used, see the Appendix of International Character Set Support. 

If multi-byte characters are used in object names in Teradata TPump script, they must be 

enclosed in double quotes. 

• Maximum String Length 

Teradata Database requires two bytes to process each of the Chinese or Korean characters. 

This limits both request size and record size. For example, if a record consists of one string, 

the length of that string is limited to a maximum of 32,000 characters or 64,000 bytes. 




Data Conversion Capabilities 

Teradata TPump can redefine the data type specification of numeric, character, and date input 

data so it matches the type specification of its destination column in the Teradata TPump 

table on Teradata Database. 

For example, if an input field with numeric type data is targeted for a column with a character 

data type specification, Teradata TPump can change the input data specification to character 

before inserting it into the table. 

The datadesc specification of the Teradata TPump FIELD command is used to convert input 

data to a different type before inserting it into a table on Teradata Database. 

The types of data conversions which can be specified are: 

• Numeric-to-numeric (for example integer-to-decimal) 

• Character-to-numeric 

• Character-to-date 

• Date-to-character 

Note: Redundant conversions, such as integer-to-integer, are legal and necessary to support 

the zoned decimal format. For more information about the zoned decimal format, data types, 

and data conversions, see SQL Data Types and Literals. 

Checkpoints 

Teradata TPump supports the use of checkpoints. Checkpoints are entries posted to a restart 

log table at regular intervals during the Teradata TPump data transfer operation. If processing 

stops while a Teradata TPump job is running, the job can be restarted at the most recent 

checkpoint. 

For example, assume 1,000,000 records are being loaded into a table and have specified 

checkpoints every 50,000 records. Then Teradata TPump pauses and posts an entry to the 

restart log table whenever multiples of 50,000 records are successfully sent to Teradata 

Database. 

If the job stops after record 60,000 has been loaded, the job can be restarted at the record 

immediately following the last checkpoint—record 50,001. 

To enable the checkpoint function, specify a checkpoint value in the BEGIN LOAD command. 

For more information, see “BEGIN LOAD” on page 96. 

Unicode Character Sets 

UTF-8 and UTF-16 are two of the standard ways of encoding Unicode character data. Teradata 

Database supports UTF-8 and UTF-16client character sets. The UTF-8 client character set 

supports UTF-8 encoding. Currently, Teradata Database supports UTF-8 characters that can 

consist of from one to three bytes. The UTF-16client character set supports UTF-16 encoding. 

Currently, Teradata Database supports the Unicode 5.0 standard, where each defined 

character requires exactly 16 bits. 




There are restrictions imposed by Teradata Database on using the UTF-8 or UTF-16 character 

set. Refer to International Character Set Support for restriction details. 

UTF-8 Character Sets 

Teradata TPump supports UTF-8 character set on network-attached platforms and IBM z/OS. 

On IBM z/OS, the job script must be in Teradata EBCDIC when using UTF-8 client character 

set. Teradata TPump will translate commands in the job script from Teradata EBCDIC to 

UTF-8 during the load. Be sure to examine the definition in International Character Set 

Support to determine the code points of any special characters which might be required in the 

job script. Different versions of EBCDIC do not always agree as to the placement of these 

characters. Refer to the mappings between Teradata EBCDIC and Unicode in Appendix E of 

International Character Set Support. 

Currently, UTF-8 Byte Order Mark (BOM) is not supported on the z/OS platform when using 

access modules or data files. 

See Chapter 3 for complete information on Teradata TPump commands. Refer to 

• parameters commands nullexpr 

• fieldexpr 

• VARTEXT format delimiter 

• WHERE condition 

• CONTINUEIF condition 

for additional information on using UTF-8 client character set on the mainframe. 

UTF-16 Character Sets 

Teradata TPump supports UTF-16 character set on network-attached platforms. In general, 

the command language and the job output should be the same as the client character set used 

by the job. However, for user’s convenience and because of the special property of Unicode, 

the command language and the job output are not required to be the same as the client 

character set when using UTF-16 character set. When using UTF-16 character set, the job 

script and the job output can either be in UTF-8 or UTF-16 character set. This is provided by 

specifying runtime parameters "-i" and "-u" when the job is invoked. 

For more reference information on runtime parameters “-i” and “-u”, see parameters 

-i scriptencoding and -u outputencoding on “-u outputencoding” on page 46. 

Also refer to parameters commands fieldexpr “fieldexpr” on page 135, nullexpr on “nullexpr” 

on page 134, WHERE condition on “WHERE condition” on page 111 and CONTINUEIF 

condition on “CONTINUEIF condition” on page 161 for additional information on using 

UTF-16 client character set. 

Client Character Set/Client Type Compatibility 

Table 6 is a general guideline for choosing client character sets that may work better for the 

client environment. 



Teradata TPump Commands 

Table 6: General Guidelines for Choosing Client Character Sets 

Client Type 

Best Client Character Sets 

Channel-attached • EBCDIC 

• EBCDIC037_0E 

• KANJIEBCDIC5026_0I 

• KANJIEBCDIC5035_0I 

• KATAKANAEBCDIC 

• SCHEBCDIC935_2IJ 

• TCHEBCDIC937_3IB 

• HANGULEBCDIC933_1II 

• UTF-8 

Network-attached running UNIX • ASCII 

• KANJIEUC_0U 

• LATIN1_0A 

• LATIN9_0A 

• UTF-8 

• UTF-16 

• SCHGB2312_1T0 

• TCHBIG5_1R0 

• HANGULKSC5601_2R4 

Network-attached running Windows • ASCII 

• KANJISJIS_0S 

• LATIN1252_0A 

• UTF-8 

• UTF-16 

• SCHGB2312_1T0 

• TCHBIG5_1R0 

• HANGULKSC5601_2R4 

Site-Defined Character Sets 

When the character sets defined by Teradata Database are not appropriate for a site, custom 

character sets can be defined. 

Refer to Teradata Database International Character Set Support for information on defining 

custom own character set. 


Teradata TPump accepts both Teradata TPump commands and a subset of Teradata SQL 

statements. These are described in the following sections: 




Teradata TPump Command Input 

Teradata TPump commands perform two types of activities, Support and Task. 

Table 7 provides a description of those activities and functions. 

Table 7: Teradata TPump Command Input Activities 

Activity 

Support 

Task 

Description 

Support commands establish the Teradata TPump sessions with Teradata Database and 

establish the operational support environment for Teradata TPump. 

Support commands are not directly involved in specifying a Teradata TPump task. 

The Teradata TPump task commands specify the actual processing that takes place for 

each MultiLoad task. 

The task commands, combined with Teradata SQL INSERT, UPDATE, and DELETE 

statements, are used to define Teradata TPump IMPORT and DELETE tasks. 

Table 8 lists the Teradata TPump commands that perform the support and task activities: 




Table 8: Teradata TPump Commands 

Activity 

Teradata 

TPump 

Command 

Function 

Support ACCEPT Allows the value of one or more utility variables to be accepted from either a file or an 

environment variable. 

DATEFORM 

DISPLAY 

ELSE (see 

IF, ELSE, and 

ENDIF) 

ENDIF (see 

IF, ELSE, and 

ENDIF) 

IF (see IF, 

ELSE, and 

ENDIF) 

LOGDATA 

LOGMECH 

LOGOFF 

LOGON 

LOGTABLE 

NAME 

ROUTE 

RUN FILE 

SET 

SYSTEM 

Lets the form of the DATE data type specifications be defined for the Teradata TPump job 

Writes messages to the specified destination 

Followed by commands and statements which execute when the preceding IF command is false 

Delimits the group of Teradata TPump commands and statements that were subject to previous 

IF or ELSE commands or both 

When followed by a conditional expression, initiates execution of subsequent commands and 

statements 

Supplies parameters to the LOGMECH command beyond those needed by the logon 

mechanism, such as user ID and password, to successfully authenticate the user 

Identifies the appropriate logon mechanism by name 

Disconnects all active sessions and terminates Teradata TPump support on the client 

Specifies the LOGON string to be used in connecting all sessions established by Teradata TPump 

Identifies the table to be used for journaling checkpoint information required for safe, automatic 

restart of the Teradata TPump support environment in the event of a client or Teradata Database 

hardware platform failure 

Sets the variable SYSJOBNAME to the jobname string specified. The jobname string can be up to 

16 bytes in length and can contain kanji characters 

Identifies the destination of output produced by the Teradata TPump support environment. 

Invokes the specified external source as the current source of commands and statements 

Assigns a data type and a value to a utility variable 

Suspends Teradata TPump to issue commands to the local operating system. 

Task BEGIN LOAD Specifies the kind of Teradata TPump task to be executed, the target tables to be used, and the 

parameters for executing the task 

FIELD 

DML 

END LOAD 

Defines a field of the data source record 

Used with LAYOUT command 

Defines a label and error treatment option(s) for the Teradata SQL DML statement(s) following 

the DML command 

Indicates completion of Teradata TPump command entries and initiates execution of the task 




Table 8: Teradata TPump Commands (continued) 

Activity 

Teradata 

TPump 

Command 

FILLER 

IMPORT 

LAYOUT 

PARTITION 

TABLE 

Function 

Defines a field in the data source that is not sent to Teradata Database. Used with LAYOUT 

command 

Identifies the data source, the layout, and the DML operation(s) to be performed, with optional 

conditions for performing these operations 

Introduces the record format of the data source to be used in the Teradata TPump task 

This command is followed by a sequence or combination of FIELD, FILLER, and TABLE 

commands. 

Establishes session partitions to transfer SQL requests to Teradata Database 

Identifies a table whose column names and data descriptions are used as the field names and data 

descriptions of the data source records 

Used with LAYOUT command 

Teradata SQL Statements 

Teradata SQL statements define and manipulate the data stored in Teradata Database. 

Teradata TPump supports a subset of Teradata SQL statements so other utilities do not have to 

be invoked to perform routine database maintenance functions before executing Teradata 

TPump utility tasks. For example, use the supported Teradata SQL statements to: 

• Create the table to load 

• Establish a database as an explicit table name qualifier 

• Add checkpoint specifications to a journal table 

The Teradata SQL statements supported by Teradata TPump are summarized in Table 9. 

Teradata TPump supports only the Teradata SQL statements listed in this table. To use any 

other Teradata SQL statements, they must be entered from another application, such as 

BTEQ. 

The subset of Teradata SQL supported by the Teradata TPump support environment excludes 

user-generated transactions (BEGIN TRANSACTION; END TRANSACTION;). 

Table 9 lists the Teradata SQL statements supported in Teradata TPump. 

Table 9: teradata SQL Statements in Teradata TPump 

Teradata SQL Statement 

ALTER TABLE 

CHECKPOINT 

COLLECT STATISTICS 

Function 

Changes the column configuration or options of an existing table 

Adds checkpoint entry to a journal table 

Collects statistical data for one or more columns of a table 




Table 9: teradata SQL Statements in Teradata TPump (continued) 

Teradata SQL Statement 

COMMENT 

CREATE DATABASE 

CREATE MACRO 

CREATE TABLE 

CREATE VIEW 

DATABASE 

DELETE 

DELETE DATABASE 

DROP DATABASE 

EXECUTE 

GIVE 

GRANT 

INSERT 

MODIFY DATABASE 

RENAME 

REPLACE MACRO 

REPLACE VIEW 

REVOKE 

SET QUERY_BAND 

Function 

Stores or retrieves a comment string associated with a database 

object 

Creates a new database, macro, table, or view 

Specifies a new default database for the current session 

Removes rows from a table 

Removes all tables, views, and macros from a database 

Removes an empty table from Teradata Database 

Specifies a user-created (predefined) macro for execution. The 

macro named in this statement resides in Teradata Database and 

specifies the type of DML statement (INSERT, UPDATE, DELETE, 

or UPSERT) being handled by the macro. 

Transfers ownership of a database to another user 

Grants privileges to a database object 

Inserts new rows to a table 

Changes the options of an existing database 

Changes the name of an existing table, view, or macro 

Redefines an existing macro or view 

Rescinds privileges to a database object 

Sets the query band for a session and transaction 

Note: The statement can be used in two ways: 

SET QUERY_BAND = 'Document=XY1234; 

Universe=East;' FOR SESSION; 

SET QUERY_BAND = NONE FOR SESSION; 

SET SESSION COLLATION 

SET SESSION OVERRIDE 

REPLICATION ON/OFF 

UPDATE Statement and Atomic 

Upsert 

Overrides the collation specification for the current session 

Turn on/off replication service 

Changes the column values of an existing row in a table 

Now that Teradata TPump supports termporal semantics, it scans up to the keywords in the 

above list only in the sense that it submits them to Teradata Database and deals with the 

success, failure, or error response. 



The Teradata TPump Task 

While restarting, only DATABASE and SET statements are reexecuted. The existence of a log 

table causes Teradata TPump on the client to execute its restart logic. 

Note that, although SET is in the list, the only SET statements truly supported are the Teradata 

SQL SET statements: SET SESSION COLLATION and SET SESSION DATABASE. Any other 

SET statement passed through to Teradata Database is rejected. 

Teradata SQL statements from the input command file are sent to Teradata Database for 

execution via CLIv2. Pertinent information returned in SUCCESS, FAILURE, or ERROR 

parcels is listed in the message destination. 

Caution: 

Do not issue a DELETE DATABASE statement to delete the database containing the restart log 

table because this terminates the Teradata TPump job. See “Reinitialize a Teradata TPump 

Job” on page 55 for restart instructions if the restart log table is accidentally dropped. 

Support environment statements may be executed between invocations of Teradata TPump 

tasks. These include DATABASE, CHECKPOINT, and CREATE TABLE statements. The 

BEGIN LOAD command then starts a Teradata TPump task script. 

The action of Teradata TPump may be directed by commands and DML statements retrieved 

from an external source. The data source for these commands and statements may be specified 

in the Teradata TPump RUN FILE command, if one is used. 

The Teradata TPump support environment parses lines that begin with a period as 

commands. The period distinguishes commands from Teradata SQL statements, which are 

passed to Teradata Database without parsing. More than one statement per line is not allowed 

but statements can span multiple lines. 

Teradata TPump follows the same rules as standard Teradata SQL for OPERATIONS on 

NULL. 

Refer to SQL Fundamentals for more information about using Teradata SQL statements. 


The Teradata TPump task is designed for the batch application of client data to one or more 

tables on Teradata Database via DML commands and statements (INSERT, UPDATE, or 

DELETE). Teradata TPump executes these DML statements in multiple-record requests. 

The following topics information provide information about the Teradata TPump task: 

• Task Limits 

• DML Commands 

• Upsert Feature 

• Teradata TPump Macros 

• Locks 

• Privileges 

• Fallback vs. Nonfallback Tables 




Task Limits 

Teradata TPump supports only single-row, primary index operations. Up to 2430 of these 

operations can be packed into a single request for network efficiency. The 2430 - statement 

upper limit is arbitrary and may actually be lower for statements associated with large data 

parcels that may exceed the overall limit of 64 KB for a request, or where a statement itself is 

very long. 

DML Commands 

Upsert Feature 

Teradata TPump Macros 

DML commands appear with their associated INSERT, UPDATE, or DELETE DML 

statements, together with the IMPORT commands that identify data to be read from the 

client. 

Teradata TPump DML statements support a conditional apply logic similar to MultiLoad, in 

which DML statements are applied based on record field contents. 

Specified DML statements following a DML command apply data from one or more separate 

data sources. The data sources contain a record for each table row to which one or more 

statements apply. Each IMPORT command identifies a separate data source, and references 

LAYOUT and DML commands. The IMPORT command matches records of the data source 

to the applicable DML statement or statements by means of its APPLY clauses. 

The LAYOUT command defines the layout of the records of a data source, using the 

parameters and a sequence of FIELD, FILLER, and TABLE commands. The DML command 

identifies an immediately following set of one or more DML statements. 

Each DML statement is converted into a macro and used for the duration of the import. 

As Teradata TPump reaches the end of one data source, as identified by the IMPORT 

command, it continues with the next IMPORT command. 

Teradata TPump’s upsert feature is a composite of UPDATE and INSERT functionality applied 

to a single row. Teradata TPump upsert logic is similar to that used in MultiLoad, the only 

other load utility with this feature. The DML statements required to execute each iteration of 

upsert are a single UPDATE statement, followed by a single INSERT statement. 

With upsert, if the UPDATE fails because the target row does not exist, Teradata TPump 

automatically executes the INSERT statement. This capability can save considerable loading 

time by completing this operation in a single pass instead of two. 

Before beginning a load, Teradata TPump creates equivalent macros on the database, based on 

the actual DML statements. That is, for every INSERT, UPDATE, DELETE, and UPSERT 

statement in the DML statement, Teradata TPump creates an equivalent macro for it. These 

macros are then executed iteratively, in place of the actual DML statement, when an import 

task begins, and are removed when all import tasks are complete. The use of macros in place 

of lengthy requests helps to minimize network and parsing overhead. 




For greater efficiency, Teradata TPump also supports the use of predefined macros, rather 

than creating macros from the actual DML statements. A predefined macro is created by the 

user and resides on the database before a Teradata TPump import task begins. When a 

predefined macro is used, Teradata TPump uses this macro directly instead of creating 

another macro. The use of predefined macros allows Teradata TPump to avoid the overhead of 

creating/dropping macros internally, and also to avoid modifying the data dictionary on 

Teradata Database during the job run. 

Teradata TPump uses the EXECUTE command to support predefined macros. For more 

information on using predefined macros, refer to the EXECUTE command in this manual. 

For more information about creating a macro, see SQL Data Definition Language. 

For more information about executing a macro, see SQL Data Manipulation Language. 

Locks 

Privileges 

Teradata TPump uses conventional row hash locking, which allows for some amount of 

concurrent read and write access to its target tables. At any point, Teradata TPump can be 

stopped, making the target tables fully accessible. If Teradata TPump is stopped, however, 

depending on the nature of the update process, the relational integrity of the data may be 

compromised. 

Although Teradata TPump always uses conventional row hash locking, based on the nature of 

SQL statements used in the Teradata TPump job and the status of the target tables, a Teradata 

TPump job may introduce other levels of locking in a job run. For example, if a target table of 

a Teradata TPump job has a trigger defined and this trigger uses table-level locking when it is 

triggered, this Teradata TPump job may cause a table level-locking if such a trigger is triggered 

during the run. The Teradata TPump script developer should be familiar with the property of 

the database on which the Teradata TPump job will run and be aware of such possibilities. 

Teradata TPump users must have privileges on the database containing the log restart table 

because Teradata TPump orchestrates the creation of macros to use during the task. 

Dropping the log table makes it impossible to restart a Teradata TPump job. Dropping the 

macros or the error table makes it very difficult to restart a Teradata TPump job. 

Teradata TPump does not have any special protections on database objects it creates. 

Therefore, it is the responsibility of Teradata TPump administrators and users to ensure that 

privileges on databases used by Teradata TPump have been established. 

Most of the privileges for Teradata TPump are intuitive. For example: 

• CREATE TABLE is required on the database where the log table is placed. 

• CREATE TABLE is required on the database where the error table is placed. 

• CREATE/DROP MACRO is required on the database where macros are placed. 

• EXECUTE MACRO is required on the database where the macros are placed. 




Macros 

The use of macros slightly complicates the privileges for Teradata TPump. The remaining 

privileges necessary to run a Teradata TPump job have two different scenarios: 

• When a Teradata TPump macro is placed in the same database as the table which it affects, 

required rights are INSERT/UPDATE/DELETE on the table affected, corresponding to the 

DML executed. 

• When a Teradata TPump macro is placed in a different database from the table it affects, 

required rights specify that the database where the macro is placed must have INSERT/ 

UPDATE/DELETE, WITH GRANT in the table affected, corresponding to the DML 

executed. The EXECUTE MACRO must also be located on the database where the macro 

is placed. 

Note that when the Teradata TPump job uses EXEC to directly specify a macro, the privileges 

scenarios are the same, except that the CREATE/DROP MACRO privilege is not required since 

the macro exists both before and after the job. 

Tables 

The corresponding INSERT, UPDATE, or DELETE privilege must exist for each table to be 

changed by the Teradata TPump task. Multiple tables can be targeted by a single Teradata 

TPump job. 

The BEGIN LOAD command invokes Teradata TPump to execute task processing. Any 

statement of this task applies each matching imported data record to each of its target table 

rows having the specified index value. Teradata TPump supports all table types. Unlike 

MultiLoad, there are no forbidden index types. Thus, the tables may be either empty or 

populated, as well as being either with or without secondary indices. 

All required data is imported; none is obtained from tables already existing in Teradata 

Database. No statement of an IMPORT task may make any reference to a table or row other 

than the one affected by the statement. 

All INSERT statements, when considered in conjunction with each applicable imported 

record, must explicitly specify values for all columns except those for which a default value 

(including null) is defined. All UPDATE and DELETE statements, when considered in 

conjunction with each applicable imported record, must explicitly specify values for all 

columns of the primary index. In order to fulfill this requirement for UPDATE and DELETE 

statements, a series of ANDed terms of either form must be supplied: 

or 

column_reference = colon_variable_reference 

column_reference = constant 

Teradata TPump does not process UPDATE and DELETE statements that contain ORed terms 

because Teradata TPump must hash the imported records with a value from the import file 

(or with a NULL). Any attempt to use an OR with these statements causes Teradata TPump to 

fail. To work around this, create two separate DML statements and apply them conditionally. 

Teradata TPump imposes some restrictions on the updates of an IMPORT task. It rejects 

updates that try to change the value of the primary index of a row, but accepts even reflexive 




updates of other columns. A reflexive update of a column computes the new value as the result 

of an expression that involves the current value of one or more columns. 

Teradata TPump processes and validates all statements from the BEGIN LOAD through the 

END LOAD statements. Teradata TPump control and processing sessions are established and 

Teradata SQL requests are transmitted to Teradata Database. Teradata TPump creates a single 

error table and a set of macros, one for each DML statement. Nothing protects target tables 

from concurrent access. 

Teradata TPump imports data, evaluating each record according to specified apply conditions. 

For each satisfied apply condition, a record is sent to Teradata Database. If the record causes 

an error, this sequence number is available in the error table so that the record can be 

identified. 

When the task completes, all locks are released, all macros dropped and, if empty, the error 

table is dropped. Statistics concerning the outcome of the IMPORT task are reported. 

Access logging can cause a severe performance penalty. If all successful table updates are 

logged, a log entry is made for each operation. The primary index of the access logging table 

may then create the possibility of row hash conflicts. 

Fallback vs. Nonfallback Tables 

Target tables can be either fallback or nonfallback. 

Table 10 lists the differences between, and characteristics of, these tables. 

Table 10: Comparison of Fallback and Nonfallback Target Tables 

Fallback Tables 

Teradata TPump task continues to execute even 

if AMPs are down, as long as there is not more 

than one AMP down, either logically or 

physically in a cluster. 

If two or more AMPs in a cluster are logically or 

physically down, or both, the task does not run, 

or terminates if running. 

During the task, if AMPs are down to the extent 

that data on the disk is corrupted, the affected 

tables must be restored. 

Not applicable. 

Not applicable. 

Nonfallback Tables 

If one or more AMPs are down prior to entering 

the task and if one or more target tables are 

nonfallback, Teradata TPump terminates. 

The Teradata TPump task may be restarted as 

soon as all AMPs are back up. 

If an AMP goes down once the task has started, 

the task cannot be restarted until all AMPs are 

back up. 

If more than one AMP in the same cluster is 

down, Teradata Database cannot come up. 

Certain I/O errors during the task corrupt the 

target table so that it must be restored. In this 

case, Teradata TPump terminates. 


CHAPTER 2 

Using Teradata TPump 

This chapter provides detailed information about using the Teradata TPump utility. Topics 

include: 

• Invoking Teradata TPump 

• Terminating Teradata TPump 

• Restart and Recovery 

• Program Considerations 

• Writing a Teradata TPump Job Script 

• View Teradata TPump Output 

• Monitor Teradata TPump Jobs 

• Estimating Space Requirements 

Invoking Teradata TPump 

Teradata TPump Support Environment 

This section describes those Teradata TPump functions that are invoked from the Teradata 

TPump support environment on the client system. The Teradata TPump support 

environment is a platform from which Teradata TPump and a number of standard Teradata 

SQL, DDL, and DML operations can be performed. This client program includes a facility for 

executing Teradata SQL and is separate from Teradata TPump tasks that run in Teradata 


Teradata TPump support environment functionality includes: 

• Providing access to the data manipulation and data definition functions of the Teradata 

SQL language. 

• User-defined variables and variable substitution. 

• System-defined variables (for example, date and time). 

• Conditional execution based on the value of return codes and variables. 

• Expression evaluation. 

• Redirection of command input. 

• Runtime parameters for Teradata TPump invocation, foreign language support, and error 

logging functions. 

• Character set selection options for IBM mainframe and UNIX client-based systems. 


Chapter 2: Using Teradata TPump 


The Teradata TPump support environment allows preparation for an initial invocation or 

resumption of a Teradata TPump task without having to invoke multiple distinct utilities. For 

example, the table that is to be loaded may need to be created, a database established as an 

implicit table-name qualifier, or the relevant permanent journal checkpointed. 

Any statement not preceded by a period (.) is assumed to be a Teradata SQL statement and is 

sent to Teradata Database to be processed. An object name in an Teradata SQL statement may 

contain Katakana or multibyte characters when the appropriate character set is used. 

The Teradata TPump support environment interprets the commands and statements that 

define the job. It also controls the execution of those commands and manages recovery from 

Teradata Database or client failures during processing. 

Those commands not directly involved in defining a Teradata TPump task, but providing 

supportive functions (routing output, for example), are considered Teradata TPump support 

commands. These are individually executed as they are encountered. 

The commands that define a single Teradata TPump task are processed by the client as a single 

unit. These are considered to be Teradata TPump task commands. The actual execution of the 

Teradata TPump task is deferred until all pertinent task commands have been considered and 

validated by the client program. 

Support Environment Input/Output 

Support environment Input/Output (I/O) appears in the following forms: 

• Command and statement input (default = SYSIN/stdin) 

• Accept command input from file 

• Command and statement output (default = SYSPRINT/stdout) 

• Display command output (default = SYSPRINT/stdout) 

• Error output (default = SYSPRINT/stdout) 

Note: For IBM statement input, the default is initially the user-provided invocation parameter 

(JCL PARM), if specified. After all commands and nested files in the parameter are processed, 

the default is SYSIN. 

SYSPRINT/stdout Output 

The characteristics of SYSPRINT output for z/OS and UNIX standard output (stdout) are: 

• The first five positions of each output line are reserved. They contain a statement number 

if the line is the beginning of a Teradata TPump statement. This also applies to comments 

preceding Teradata TPump statements. 

• If the output line is a Teradata TPump-generated message, the first five positions contain 

the string ****. 

• In all other cases, the first five positions are blank. 

• A message indicating the processing start date appears at the beginning of every job. 

• Teradata TPump-generated messages are preceded by a header displaying system time. 

This timestamp appears on the same line as the message and follows the **** string. 




================================ 

Example 

This example depicts each type of SYSPRINT/stdout output line noted in the previous list. 

======================================================================== 

= = 

= Teradata Parallel Data Pump Utility Release 13.10.00.000 = 

= Platform IBM-AIX = 

= = 

======================================================================== 

= = 

= Copyright 1997-2009 Teradata Corporation. ALL RIGHTS RESERVED. = 

= = 

======================================================================== 

**** 23:24:10 UTY2411 Processing start date: TUE OCT 06, 2009 

======================================================================== 

= = 

= Logon/Connection = 

= = 

======================================================================== 

0001 /************************************************************************ 

* This is a sample test for TPump. * 

************************************************************************/ 

.LOGTABLE TPLOG0044; 

0002 .LOGON ESTELSA/SUDHANSUDB,; 

**** 23:24:14 UTY8400 Teradata Database Release: 13.10g.00.53 

**** 23:24:14 UTY8400 Teradata Database Version: 13.10g.00.53 

**** 23:24:14 UTY8400 Default character set: ASCII 

**** 23:24:14 UTY8400 Current RDBMS has UDT support 

**** 23:24:14 UTY8400 Maximum supported buffer size: 1M 

**** 23:24:14 UTY8400 Upsert supported by RDBMS server 

**** 23:24:14 UTY8400 Data Encryption supported by RDBMS server 

**** 23:24:14 UTY8400 Array Support supported by RDBMS server 

**** 23:24:15 UTY6211 A successful connect was made to the RDBMS. 

**** 23:24:15 UTY6217 Logtable 'SUDHANSUDB.TPLOG0044' has been created. 

======================================================================== 

= = 

= Processing Control Statements = 

= = 

======================================================================== 

0003 .NAME TPUMP0044; 

0004 DROP TABLE TPTBL0044; 

**** 23:24:15 UTY1016 'DROP' request successful. 

0005 DROP TABLE TPERR0044; 

**** 23:24:15 UTY1008 RDBMS failure: 3807, Object 'TPERR0044' does not exist. 

0006 CREATE TABLE TPTBL0044, FALLBACK( 

F1 INTEGER, F2 CHAR(50), 

F3 VARCHAR(50)) 

UNIQUE PRIMARY INDEX (F1); 

**** 23:24:16 UTY1016 'CREATE' request successful. 

0007 .BEGIN LOAD CHECKPOINT 15 

SESSIONS 4 1 

TENACITY 2 

ERRORTABLE TPERR0044 

ROBUST OFF 

NOMONITOR 

PACK 500; 




0008 .LAYOUT LAY0044; 

0009 .FIELD FF1 * INTEGER; 

0010 .FIELD FF2 * CHAR(50); 

0011 .FIELD FF3 * VARCHAR(50); 

0012 .DML LABEL LABEL0044; 

0013 INSERT INTO TPTBL0044 VALUES ( :FF1, :FF2, :FF3); 

0014 .IMPORT INFILE ALLTYPE 

LAYOUT LAY0044 

APPLY LABEL0044; 

0015 .END LOAD; 

**** 23:24:16 UTY6609 Starting to log on sessions... 

**** 23:24:17 UTY6610 Logged on 4 sessions. 

======================================================================== 

= = 

= TPump Import(s) Beginning = 

= = 

======================================================================== 

**** 23:24:17 UTY6630 Options in effect for following TPump Import(s): 

. Tenacity: 2 hour limit to successfully connect load sessions. 

. Max Sessions: 4 session(s). 

. Min Sessions: 1 session(s). 

. Checkpoint: 15 minute(s). 

. Errlimit: No limit in effect. 

. Restart Mode: SIMPLE. 

. Serialization: OFF. 

. Packing: 500 Statements per Request. 

. StartUp Rate: UNLIMITED Statements per Minute. 

**** 23:24:28 UTY6608 Import 1 begins. 

**** 23:24:30 UTY6641 Since last chkpt., 100 recs. in, 100 stmts., 1 reqs 

**** 23:24:30 UTY6647 Since last chkpt., avg. DBS wait time: 2.00 

**** 23:24:30 UTY6612 Beginning final checkpoint... 



**** 23:24:30 UTY6607 Checkpoint Completes with 100 rows sent. 

**** 23:24:30 UTY6642 Import 1 statements: 100, requests: 1 

**** 23:24:30 UTY6643 Import 1 average statements per request: 100.00 

**** 23:24:30 UTY6644 Import 1 average statements per record: 1.00 

**** 23:24:30 UTY6645 Import 1 statements/session: avg. 25.00, min. 0.00, max. 100.00 

**** 23:24:30 UTY6646 Import 1 requests/session: average 0.25, minimum 0.00, maximum 1.00 

**** 23:24:30 UTY6648 Import 1 DBS wait time/session: avg. 0.50, min. 0.00, max. 2.00 

**** 23:24:30 UTY6649 Import 1 DBS wait time/request: avg. 0.50, min. 0.00, max. 2.00 

**** 23:24:30 UTY1803 Import processing statistics 

. IMPORT 1 Total thus far 

. ========= ============== 

Candidate records considered:........ 100....... 100 

Apply conditions satisfied:.......... 100....... 100 

Records logable to error table:...... 0....... 0 

Candidate records rejected:.......... 0....... 0 

** Statistics for Apply Label : LABEL0044 

Type Database Table or Macro Name Activity 

I SUDHANSUDB TPTBL0044 100 

**** 23:24:30 UTY0821 Error table SUDHANSUDB.TPERR0044 is EMPTY, dropping table. 

0016 .LOGOFF; 

======================================================================== 

= = 

= Logoff/Disconnect = 

= = 

======================================================================== 

**** 23:24:33 UTY6216 The restart log table has been dropped. 




**** 23:24:33 UTY6212 A successful disconnect was made from the RDBMS. 

**** 23:24:33 UTY2410 Total processor time used = '0.269692 Seconds' 

. Start : 23:24:10 - TUE OCT 06, 2009 

. End : 23:24:33 - TUE OCT 06, 2009 

. Highest return code encountered = '0'. 

File Requirements 

Certain files are required for invoking Teradata TPump. In addition to the input data source, 

Teradata TPump accesses four different data sets/files or input/output devices. 

Table 11 lists Teradata TPump data sets/files and input/output devices: 

Table 11: Data Sets, Files and Input/Output Devices 

Data Set/File or Device 

standard input 

standard output 

standard error 

configuration 

Provides 

Teradata TPump commands and Teradata SQL statements that 

make up a Teradata TPump job 

Destination for Teradata TPump output responses and messages 

Destination for Teradata TPump errors 

Optional specification of Teradata TPump utility default values 

When running Teradata TPump in interactive mode, the keyboard functions as the standard 

input device and the display screen is the standard output/error device. 

When running Teradata TPump in batch mode, specify a data set or file name for each of these 

functions. The method of doing this varies, depending on the configuration of the client 

system: 

• On network-attached client systems, use the standard redirection mechanism (< 

infilename and > outfilename) to specify the Teradata TPump files when the utility is 

invoked. 

• On channel-attached client systems, use standard z/OS JCL control statements (DD) to 

allocate and create the Teradata TPump data sets or files before the utility is invoked. 

IBM Mainframe Client-Based Systems 

Start Teradata TPump with a RUN FILE command, with optional invocation parameters, such 

as JCL PARM. These are interpreted as a string of Teradata TPump support environment 

commands, separated by, and ending with, semicolons. 

After invocation, the first two commands executed must be LOGON and LOGTABLE. These 

commands are required and are permitted only once. Either can be supplied in the command 

string invoking Teradata TPump, and the other (or both) can appear in the INPUT file, or in a 

file called with the RUN FILE command. No commands can precede the LOGON, 

LOGTABLE, or RUN FILE commands. 




If a RUN FILE command is not used to specify an initial source of commands and Teradata 

SQL statements, Teradata TPump defaults to the conventional source of control input, such as 

SYSIN. 

If a RUN FILE command is found in the parameter (PARM) input, the input source it 

identifies is used prior to SYSIN. Whether the input source is specified by RUN FILE, or by 

SYSIN, processing continues until a LOGOFF command, the end of control input, or a 

terminating error is encountered, whichever occurs first. If all input is exhausted without 

encountering a LOGOFF command, or if the program terminates because of an error, 

Teradata TPump automatically performs the LOGOFF function. 

The LOGON command establishes a Teradata SQL session that Teradata TPump uses for 

processing. The LOGTABLE command specifies a table to be used as the restart log in the 

event of failure. This table is placed in the default database unless otherwise specified. 

CREATE TABLE, INSERT, UPDATE, and SELECT rights must be on the database containing 

the restart log table. 

Preparatory statements, which are processed by the Teradata SQL-processing function of 

Teradata TPump, must be executed before beginning a Teradata TPump task. It is here that 

any desired DATABASE statement and any desired CREATE TABLE statements are specified. 

At this point, a BEGIN LOAD command initiates a Teradata TPump task. 

UNIX- and Windows-based Systems 

Interactive Mode 

Start the Teradata TPump utility on Teradata Database for UNIX and Windows with a UNIXstyle 

command format. 

The rules for invoking Teradata TPump under UNIX are the same as for IBM mainframe 

client-based systems described in the preceding section. The difference lies in UNIX syntax. 

The Windows syntax and the UNIX syntax are essentially the same, the main difference being 

that single quotes should be used on UNIX systems and double quotes should be used on 

Windows systems. 

To invoke Teradata TPump in interactive mode, enter tpump at the system command prompt: 

tpump 

Teradata TPump displays the following message to begin the interactive session: 

======================================================================== 

= = 


= Platform WIN32 = 

= = 

======================================================================== 

= = 


= = 

======================================================================== 

**** 11:54:53 UTY2411 Processing start date: WED NOV 18, 2009 

======================================================================== 




= = 


= = 

======================================================================== 

Batch Mode 

This section covers invoking Teradata TPump in batch mode on network-attached and 

channel-attached systems. 

For a description of how to read the syntax diagrams used in this book, see Appendix A: “How 

to Read Syntax Diagrams.” 

Batch Mode on Network-attached UNIX Systems 

Refer to the runtime parameter descriptions in Table 12 on page 45 and use the following 

syntax to invoke Teradata TPump on network-attached UNIX client systems: 

tpump 

-b 

c charactersetname 

-C filename 

-d periodicityvalue 

-e errorfilename 

-f numberofbuffers 

-m 

-r 'tpump command' 

-v 

-y 

-i scriptencoding 

-u outputencoding 

-t nn 

-V 

< infilename > outfilename 

3021E016 

Batch Mode on Network-attached Windows Systems 


syntax to invoke Teradata TPump on network-attached Windows client systems: 




tpump 

-b 

-c charactersetname 

-C filename 

-d periodicityvalue 

-e errorfilename 

-f numberofbuffers 

-m 

-r "tpumpcommand" 

-v 

-y 

-i scriptencoding 

-u outputencoding 

-t nn 

-V 

< infilename > outfilename 

3021E015 

Note: The Windows syntax is essentially the same as the UNIX system, the main difference 

being that single quotes should be used on UNIX systems and double quotes should be used 

on Windows systems. 

Batch Mode on Channel-attached z/OS Systems 


syntax to invoke Teradata TPump on channel-attached z/OS client systems. 

// EXEC TDSTPUMP 

PARM = , BRIEF 

, 

BUFFERS = numberofbuffers 

CHARSET = charactersetname 

CONFIG = filename 

ERRLOG = filename 

MACROS 

PRDICITY = periodicityvalue 

VERBOSE 

'tpump command' 

RTYTIMES = nn 

RVERSION 

3021D014 

Run-time Parameters 

Table 12 describes the run-time parameters used by Teradata TPump on channel-attached and 

network-attached systems. 




Table 12: Run-time Parameters/Systems 

Channel-attached Network-attached Description 

BRIEF -b Specifies reduced print output, which limits Teradata 

TPump printout to the minimal information required to 

determine the success of the job: 

• Header information 

• Logon/logoff information 

• Candidate records 

• Insert, update, and delete results 

• Error table counts 

BUFFERS = 

numberofbuffers 

CHARSET = 

charactersetname 

-f numberofbuffers Sets the number of request buffers. 

For Teradata Tools and Utilities 06.02.00 and earlier, the 

buffers runtime parameter can be set from 2 to a 

maximum of 10. The default value is 2. 

Beginning with Teradata Tools and Utilities 06.02.00.01, 

the buffers runtime parameter can be set with a lower 

limit of 2 and no upper limit. The default value is 3. 

The maximum number of request buffers that may be 

allocated is BUFFERS * session_count. 

Beginning with Teradata Tools and Utilities 06.02.00.01, 

request buffers are a global resource, so 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 

BUFFERS * session_count. 

Prior to Teradata Tools and Utilities 06.02.00.01, a request 

buffer was permanently owned by the session to which it 

was first assigned, and so could not be used by any other 

session. The maximum number of requests buffers that a 

session could own was determined by the value of 

BUFFERS. 

-c charactersetname Defines a character set for the Teradata TPump job. 

The character set specification remains in effect for the 

entire Teradata TPump job, even if the Teradata Database 

server resets, causing the Teradata TPump job to be 

restarted. 

Note: The character set specification does not remain in 

effect if the client system fails, or if the Teradata TPump 

job is canceled. In these cases, when the job is 

resubmitted, the job must use the same character set 

specification that was used on the initial job. If a different 

character set specification is used when such a job is 

resubmitted, the data loaded by the restarted job will not 

appear the same as the data loaded by the initial job. 




Table 12: Run-time Parameters/Systems (continued) 


If a character set specification is not entered, the default is 

whatever character set that is specified for Teradata 

Database when Teradata TPump was invoked. 

Note: See Client Character Sets in Chapter 1 for more 

information on supported character sets. 

When using a UTF-16 client character set on the network 

or UTF-8 client character set on the mainframe, specify 

the client character set name by the runtime parameter 

(that is, "-c" on the network and "CHARSET" on the 

mainframe.) 

Not Applicable -i scriptencoding Specifies the encoding form of the job script. If this 

parameter is not specified and the client character set is 

UTF-16, Teradata TPump interprets the job script to 

UTF-16. If character-type data is also specified in the 

script, Teradata TPump converts the string literals and the 

corresponding field in the import data to the same 

character set before comparing or concatenating them. 

(String literals are specified with .APPLY…WHERE….; 

LAYOUT…CONTINUEIF….; FIELD…NULLIF…; 

FIELD…||…commands.) 

Valid encoding options are: 

• UTF-8 or UTF8 

• UTF-16BE, or UTF16BE, or UTF16-BE 

• UTF-16LE, or UTF16LE, or UTF16-LE 


The specified encoding character set applies to all script 

files included by the .RUN FILE commands. 

The UTF-16 or UTF 8 Byte Order Mark (BOM) can be 

present or absent in the script file. 

When UTF-16 BOM is present and 'UTF-16' is 

specified, Teradata TPump interprets the script according 

to the endianness indicated by the UTF-16 BOM. When 

the UTF-16 BOM is not present, Teradata TPump 

interprets the script according to the endianness indicated 

by the encoding option. 

Not Applicable -u outputencoding Specifies the encoding form of the job output. The 

parameter is valid only when the UTF-16 client character 

set is used. 

When this parameter is used, it should be placed in front 

of other runtime parameters to ensure the whole job 

output is printed in the desired encoding form. 






If is not placed ahead of other runtime parameters when 

invoking the job, a warning message will be printed. 

Available output encoding options are: 

• UTF-16BE, or UTF16BE, or UTF16-BE 

• UTF-16LE, or UTF16LE, or UTF16-LE 


UTF-16BE instructs Teradata TPump to print the job 

output in big endian UTF-16 encoding scheme. 

UTF-LE instructs Teradata TPump to print the job 

output in little endian UTF-16 encoding scheme. On big 

endian client systems, UTF-16 instructs Teradata TPump 

to print the job output in big endian UTF-16 encoding 

scheme. On little endian client systems, UTF-16 instructs 

Teradata TPump to print the job output in little endian 

UTF-16 encoding scheme. 

The UTF-16 BOM is not printed as a part of job output. 

When this parameter is not specified and the client 

character set is UTF-16, if Teradata TPump output needs 

to be redirected to a log file on network platforms, “-u 

outputencoding” must be specified. 

CONFIG = 

filename 

-C filename Specifies the configuration file for the Teradata TPump 

job. The configuration file contains various configuration 

and tuning parameters for Teradata TPump. The 

particular usefulness of this file is for values that: 

• are site- or host-specific 

• script that developers may not necessarily be aware of 

• will likely change independently of Teradata TPump 

scripts. 

The installation of Teradata TPump installs a default 

configuration file. On UNIX, it also installs a shell script 

that calls Teradata TPump using the default configuration 

file on the command line. 

The format of the entries in the file is: 

 

• Lines in the file that do not begin with a valid keyword 

are ignored. 

• Keywords are case insensitive. 

• On UNIX systems, this file is called tdatpump.cfg and 

is expected to be found in the directory /usr/lib. 

• If the configuration file is not found, the program 

issues a warning message and uses the default values 

wherever necessary. 






At this time, the only valid keyword is INMEMSORT, 

which is an integer data type containing the maximum 

number of bytes that can be sorted in memory. Teradata 

TPump recovery logic uses this value. This keyword can 

be modified to increase the amount of memory available 

for sorting. 

If this keyword is not provided in the configuration file, 

or the configuration file is not provided, the default value 

for INMEMSORT is 6,000,000 for UNIX, 12,000,000 for 

z/OS, and 3,000,000 for Windows. 

PRDICITY 

periodicityvalue 

ERRLOG= 

error filename 

-d periodicityvalue Specifies to change the periodicity value to control the 

rate at which statements are transferred to the database. 

This parameter may be adjusted to improve the Teradata 

TPump workflow. 

This parameter is in effect whenever the BEGIN LOAD 

command uses the RATE parameter to control the rate 

that statements are sent to the database. The default 

periodicity value is four 15-second periods per minute. 

The periodicityvalue variable contains a value between 1 

and 600, which is the value range for the number of 

periods specified. The default value is 4. 

Alternatively, periodicity can be changed by executing the 

TPumpMacro.UserUpdateSelect macro (provided with 

Teradata TPump Monitor SQL scripts) to update the 

monitor interface table while the job is running. 

-e errorfilename Specifies to use the error logging function. Using this 

parameter creates an alternate error log file to hold 

messages generated by Teradata TPump. Specifying an 

alternate file name produces a duplicate record of all 

Teradata TPump error messages. This allows any errors 

detected to be examined without having to go through 

the entire output stream. 

The errorfilename defined is the location where error 

messages are copied. Directory identifiers can also be 

included in the file names defined. 

On UNIX, the maximum length of the file name depends 

on the UNIX version currently in use. 

On channel-attached client systems, the alternate file 

specification is limited to eight characters , and on z/OS, 

it must be to a DD name defined in the JCL. 

Note: If the file names defined already exist, they are 

overwritten. Otherwise, they are automatically created. 

There is no default error log errorfilename specification. 






MACROS -m Invocation option to tell Teradata TPump to keep macros 

that were created during the job run. These macros can be 

used as predefined macros for the same job. 

In order to use the same script after the -m parameter is 

used in the previous run, the EXECMACRO command 

must be added to the script. 

To avoid duplicate macro names, a random number from 

1 to 99 is used in each macro name when the NAME 

command is not used. The format in which the macro is 

created is: 

MYYYYMMDD_HHMMSS_LLLLL_DDD_SSS 

where 

• LLLLL is the low-order 5 digit of the logon sequence 

returned by the database from the .LOGON 

command. 

• DDD is the .DML sequence (ordinal) number. This 

value is not reset to one for successive loads (.BEGIN 

LOAD) in a single job, but continues to be 

incremented. 

• SSS is the SQL statement sequence (ordinal) number 

within the .DML group. 

RTYTIMES=nn -t nn Specification for retry times. The default for nn is 16. If 

nn = 0, retry times will be set back to 16. 

The retry times options in the BEGIN LOAD can override 

this option for the requests/data sent between "BEGIN 

LOAD" and "END LOAD" pair. 

'tpump command' 

-r 'tpump 

command' 

Invocation option that can signify the start of a Teradata 

TPump job. This is usually a RUN FILE command 

specifying the file containing the Teradata TPump job 

script because only one Teradata TPump command may 

be specified. For example, on UNIX: 

'.RUN FILE tpump.script;' 

VERBOSE -v Specifies to turn on verbose mode. Using this parameter 

provides additional statistical data in addition to the 

regular statistics. 

In verbose mode, the input file from which statistics are 

normally displayed includes such additional statistics as 

the number of database requests sent, in addition to the 

normal number of requests. 

Note: In verbose mode, Teradata TPump displays each 

retryable error when it occurred. 






Not Applicable -y Specification for the data encryption option. When 

specified, data and requests will be encrypted in all 

sessions used by the job. 

The encryption options in the BEGIN LOAD or the 

PARTITION commands can override this option for the 

sessions associated with those commands 

Not Applicable < infilename Name of the standard input file containing the Teradata 

TPump commands and Teradata SQL statements. The 

infilename specification redirects the standard input 

(stdin). If an infilename specification is not entered, the 

default is stdin. If end-of-file is reached on the specified 

input file, the input does not refer to stdin and the job 

terminates. 

Note: On channel-attached client systems, the DD 

control statement must be used to specify the input file 

before Teradata TPump is invoked. 

Not Applicable > outfilename Name of the standard output file for Teradata TPump 

messages. The outfilename specification redirects the 

standard output (stdout). If an outfilename specification 

is not entered, the default is stdout. 

Note: If an outfilename specification is used to redirect 

stdout, do not use the same outfilename as an output or 

echo destination in the DISPLAY or ROUTE commands. 

Doing so produces incomplete results because of the 

conflicting write operations to the same file. 

Note: On channel-attached client systems, the DD 

control statement must be used to specify the output file 

before the utility is invoked. 

RVERSION -V Display version number and stop. 

Note: See the invocation examples in Appendix B: “Teradata TPump Examples” for sample 

JCL listings, commands, and output samples for the invocation options. 

Examples - Redirection of Inputs and Outputs 

The following examples show various ways to redirect stdin and stdout via UNIX. 

Example 1 

This example specifies both an input file and an output file. The Teradata TPump script is in 

/home/tpuser/tests/test1 and the job output is written to /home/tpuser/tests/out1. 

tpump /home/tpuser/tests/out1 



Terminating Teradata TPump 

Example 2 

This example specifies only an input file. The Teradata TPump script is in /home/tpuser/tests/ 

test1 and the job output is written to stdout, which ordinarily would be the terminal. 

TPumptpump /home/tpuser/tests/out1 

Example 4 

This example specifies neither an input nor an output file. Teradata TPump commands are 

typed at a terminal via stdin and job output is written to the terminal via stdout. 

tpump 

Terminating Teradata TPump 

Normal Termination 

This section covers methods of termination and other topics related to terminating Teradata 

TPump. 

There are two ways to terminate Teradata TPump: 

• Normal termination 

• Abort termination 

Use the Teradata TPump LOGOFF command in the Teradata TPump job script to terminate 

the utility normally on both network- and channel-attached client systems: 

.LOGOFF 

retcode 

; 

HE03A003 

Teradata TPump logs off all sessions with Teradata Database and returns a status message 

indicating: 

• The total processor time that was used 

• The job start and stop date/time 

• The highest return code that was encountered: 

• 0 if the job completed normally 



Restart and Recovery 

Abort Termination 

• 4 if a warning condition occurred 

• 8 if a user error occurred 

• 12 if a fatal error occurred 

• 16 if no message destination is available 

Teradata TPump also: 

• Maintains or drops the restart log table, depending on the success or failure of the job. 

• If specified, Teradata TPump returns the optional retcode value to the client operating 

system. 

See the LOGON command description in Chapter 3 for more information about return codes 

and the conditions that maintain or drop the restart log table. 

The procedure for aborting a Teradata TPump job depends on whether the utility is running 

on a network-attached or a channel-attached client system: 

To abort a Teradata TPump job running on a channel-attached client system 

✔ Cancel the job from the client system console. 

To abort a Teradata TPump job running on a network-attached client system 

✔ Press the Control + C key combination three times on the workstation keyboard. 

After Terminating a Teradata TPump Job 

After terminating a Teradata TPump job: 

• Restart the job and allow it to run to completion 

• Reinitialize the job and run it to completion 

• Abandon the job and clean up the database objects. 

For more information on how to perform the above options, see “Restart and Recovery.”. 


This section explains Teradata TPump’s handling of restart and recovery operations in the 

event of a system failure. 

The Teradata TPump facility includes a number of features that enable recovery from client or 

Teradata Database failure, with minimal requirements for job resubmission or continuation. 

Upon restart or resubmission, Teradata TPump interrogates the restart log table on Teradata 

Database and resumes operations from where it had left off. 




Caution: 

Do not tamper with the contents of the restart log table. A missing or altered restart log table 

will cause the Teradata TPump job to be recovered incorrectly. 

Basic Teradata TPump Recovery 

Whenever a database restart is detected or a Teradata TPump job is restarted on the host 

system, the following activity occurs: 

• The restart log table is scanned with reference to the Teradata TPump script. Each 

statement within the script is either executed because a row does not exist or ignored 

because a row exists in the restart log. 

• In the case of the END LOAD statement, there are a number of rows which are placed in 

the restart log table which let Teradata TPump decide what to do. Teradata TPump ignores 

any complete IMPORT within a LOAD and begins at the incomplete IMPORT. 

• Within an unfinished IMPORT, Teradata TPump begins processing at the last complete 

checkpoint. If the Teradata TPump job was running in SIMPLE mode before the restart, 

then recovery is complete and processing continues at the last complete checkpoint. 

• If Teradata TPump was running in ROBUST mode before it was restarted, then Teradata 

TPump must next ascertain how much processing has been completed since the last 

checkpoint. This is accomplished by reading back a set of “Partial Checkpoints” from the 

restart log table in Teradata Database, sorting them, and then reprocessing all transactions 

which were left incomplete when the job was interrupted. 

Protection and Location of Teradata TPump Database Objects 

The restart log table is critical to the recovery process. If the restart log table is dropped, there 

is no way to recover an interrupted Teradata TPump job. 

In addition to the restart log table, Teradata TPump also creates an error table and a number 

of macros (where each macro corresponds to a DML SQL statement involved in current 

IMPORT). If these database objects are dropped, they can, with some effort, being recreated. 

However, it is much more convenient for this NOT to be necessary. 

Teradata TPump does not have special locks that it places on database objects. It is important 

that administrators take security precautions to avoid the loss of these objects. 

If the objects are dropped accidentally, the following information should allow an 

administrator to recreate them. 

Teradata TPump macros are placed in the same database that contains the log restart table. 

The macros are named according to the following convention: 

Jobname_DDD_SSS 

where 

• Jobname is the job name, which, if not explicitly specified, defaults to: 

MYYYYMMDD_HHMMSS_LLLLL. 

• LLLLL is the low-order 5 digits of the logon sequence number returned by the database 

from the .LOGON command. 




• DDD is the number of the .DML sequence (ordinal) number. This value is not reset to one 

for successive loads (.BEGIN LOAD) in a single job, but continues to be incremented. 

• SSS is the SQL statements sequence (ordinal) number within the .DML group. 

Thus, given the following script fragment: 

.LOGTABLE LT_SIGH; 

.LOGON TDPID/CME,CME; 

... 

.LAYOUT LAY1A 

... 

.DML LABEL TAB1PART1; 

INSERT into tab1 values (:F0,:F1,:F2,:F3); 

.DML LABEL TAB2PART1; 

INSERT into tab2 values (:F0,:F1,:F2,:F3); 

... 

.IMPORT INFILE TPDAT 

LAYOUT LAY1A 

APPLY TAB1PART1 

APPLY TAB2PART1; 

and assuming the job name is defaulted, the macros are named: 

M20020530_171209_06222_001_001 and M20020530_171209_06222_002_001. 

The contents of a Teradata TPump macro is taken directly from the script and consists of a 

parameter clause derived from the LAYOUT and the actual statement which is specified in the 

script. Continuing the example above, if the LAYOUT associated with the statement is as 

follows: 

.LAYOUT LAY1A; 

.FIELD F0 * integer key; 

.FIELD F1 * integer; 

.FIELD F2 * integer; 

.FILLER FX * integer; 

.FIELD F3 * char(38); 

then the macros will be created as follows: 

CREATE MACRO CME.M20020530_171209_06222_001_001 ( 

F0 (INTEGER), F1 (INTEGER), F2 (INTEGER), F3 (CHAR(38)) 

) AS (INSERT INTO TAB1 VALUES(:F0, :F1, :F2, :F3); 

); 

CREATE MACRO CME.M20020530_171209_06222_002_001 ( 

F0 (INTEGER), F1 (INTEGER), F2 (INTEGER), F3 (CHAR(38)) 

) AS ( INSERT INTO TAB2 VALUES(:F0, :F1, :F2, :F3); 

); 

Note that the actual names of the parameters in the parameter list are not important; however, 

what is important is that the types of the parameters are specified in the macro in exactly the 

same order as the types in the LAYOUT. Also important is the fact that FILLER fields are not 

included in the parameter list since they are stripped out by Teradata TPump. 

The error table, if it is not explicitly specified, is: 

_nnn_ET 

Where nnn is the load sequence number. 




If the database for the error table is not explicit in the script, the table is placed in the database 

associated with the Teradata TPump user logon, unless the DATABASE command has been 

issued. 

Continuing the above example, assuming the user defaults the error table, then the create table 

command for it will be: 

CREATE SET TABLE M20020530_171209_06222_001_ET, 

NO BEFORE JOURNAL, 

NO AFTER JOURNAL 

( 

ImportSeq BYTEINT, 

DMLSeq BYTEINT, 

SMTSeq BYTEINT, 

ApplySeq BYTEINT, 

sourceseq INTEGER, 

DataSeq BYTEINT, 

ErrorCode INTEGER, 

ErrorMsg VARCHAR(255) CHARACTER SET UNICODE NOT CASESPECIFIC, 

ErrorField SMALLINT, 

HostData VARBYTE(63677)) 

UNIQUE PRIMARY INDEX ( ImportSeq ,DMLSeq ,SMTSeq ,ApplySeq ,sourceseq , 

DataSeq ); 

Reinitialize a Teradata TPump Job 

If the restart log table has been accidentally dropped or corrupted for a Teradata TPump job, 

reinitialize the job using the following procedure: 

Reinitialize a Teradata TPump Job 

1 Determine how much of the job has completed in order to take data out of the Teradata 

TPump input data set. 

How this is done will depend on the table and procedures involved with table 

maintenance. This will vary between jobs and with the procedures in effect at each 

customer site. 

2 Delete any database objects associated with the Teradata TPump job that may exist. This 

cleans up Teradata TPump. 

These objects include the error table and any DML-associated macros. Directions for 

finding these objects are provided in the previous section. 

Recover an Aborted Teradata TPump Job 

An aborted Teradata TPump job is one that has been terminated early for any number of 

reasons (out of database space, accidental cancellation by mainframe operators, UNIX kernel 

panic, error limit in the Teradata TPump job exceeded, and so on) and all Teradata TPump 

database objects, the restart log table, the error table, and DML macros are intact. 

An aborted Teradata TPump job may be restarted using the same job script that was used in 

the original job, and Teradata TPump will perform the recovery of the job. 



Program Considerations 

Recover from Script Errors 

When Teradata TPump encounters an error in the input script, a diagnostic message is 

generated and the operation is stopped with a non-zero return code. The script can modify 

and correct the faulty code, and resubmit the job. Operations begin with the statement 

following the last one that was successfully completed. 


This section provides information to help applications programmers to design and script 

Teradata TPump jobs. Additional information needed by programmers and/or system 

administrators includes space requirements, locks, and the use of fallback or nonfallback 

tables. 

The information in this section includes Teradata TPump command conventions, variables, 

and ANSI/SQL DateTime Data types. Information related to using comments, specifying a 

character set, using graphic data types, and using graphic constants is found in this section. 

Restrictions and limitations, as well as termination return codes, are covered as well. 

Teradata TPump Command Conventions 

The following command conventions apply when using Teradata TPump. 

Teradata TPump Reserved Words 

Commands supported by Teradata TPump do not use reserved words (or keywords), except 

those that are operators, and only where an expression is allowed. Although there is no official 

restriction against the use of Teradata TPump reserved words as variable names, it is strongly 

recommended to avoid their use, as well as the use of Teradata SQL reserved words. Avoid 

words which are operators (see Table 13). Their use can result in ambiguous expressions. 

Table 13 contains a list of Teradata TPump Operators. 

Table 13: Teradata TPump Operators 

Commands 

AND BETWEEN EQ 

GE GT IN 

IS LE LIKE 

LT MOD NE 

NOT NULL OR 

Teradata SQL Reserved Words 

Teradata TPump supports a subset of Teradata SQL listed in Table 25 on page 92. The subset 

of Teradata SQL consists only of statements beginning with one of the reserved words (or 




keywords) in Table 1. Avoid the use of the Teradata SQL reserved words listed in Teradata 

TPump commands. 

Conditional Expressions 

Some of the commands described in this chapter use conditional expressions. If they evaluate 

to true, conditional expressions return a result of 1; if false, they return a result of 0. 

Table 14 contains a list of Teradata TPump Conditional Expressions. 

Table 14: Teradata TPump Conditional Expressions 

Commands 

+ - / MOD NOT 

|| IS NOT NULL IS NULL EQ 

= NE ^= 

NOT= ~= GE >= 

GT > LE



The logged on user must have the appropriate user privileges on the tables. At the time the 

BEGIN LOAD is initiated, SELECT privileges, as well as INSERT, UPDATE, and DELETE 

privileges are required, depending on the DML statements specified in the current task. 

Privileges must follow standard Teradata privilege rules. The kind of privilege required 

depends on the kind of DML statements to be applied. Teradata TPump tasks require that the 

target table is owned or access is available. Additional privilege for the target table is required, 

depending on the DML command, INSERT, UPDATE, or DELETE. The additional privilege is 

described for each statement type in later sections. No matter what kind of statement, 

CREATE TABLE privilege on the databases where the error tables are going to be placed. 

CREATE TABLE privilege for Teradata TPump to create a restart log table is also required. If 

the restart log table specified for the support environment already exists, INSERT and 

UPDATE privileges on the table are required. 

In a Teradata TPump task, it is possible for more than one statement/data record combination 

to affect a single row. If application of any statement/data record combination to a row would 

produce an error, it is not applied, but all prior and subsequent error-free combinations 

affecting the same row or other rows are applied. 

Teradata TPump can guarantee the order of operations on a given row via the correct use of 

the serialize option to specify the primary index of a given target table. When serialize is used, 

operations for a given set of rows occurs in order on one session. Without serialize, statements 

are executed on the first session available; hence, operations may occur out of order. 

Assuming that the serialize option is in effect, note that the order in which DML statement or 

host record pairings are applied to a given target row is totally deterministic; so too is the 

order in which rows are applied to the target rows. Operations occur in exactly the same order 

as they are read from the data source and, if there are multiple apply clauses, in order by apply 

clause from first to last. 

In addition to using serialize option in the BEGIN LOAD command, the SERIALIZEON 

keyword can also be specified in the DML command, which lets serialization be turned on for 

the fields specified. The SERIALIZEON keyword can be used in the DML command with the 

SERIALIZE keyword in the BEGIN LOAD command. When this is done, the DML-level 

serialization ignores and overrides the BEGIN LOAD-level serialization. In this case, the DML 

command with the serialization option in effect will be serialized on the fields specified. 

Operations generated from the first IMPORT statement take place before operations 

generated from the second IMPORT. 

Variables 

This section contains information about the variables used in Teradata TPump. 

Predefined System Variables 

Avoid use of the prefix &SYS in user-defined symbols because the names of predefined utility 

variables begin with the prefix. Table 15 contains a list of predefined system variables. 




Table 15: Predefined System Variables 

System Variable 

&SYSDATE 

&SYSDATE4 

&SYSDAY 

&SYSDELCNT[n} 

&SYSETCNT[n} 

&SYSINSCNT[n} 

&SYSJOBNAME 

&SYSOS 

&SYSRC 

&SYSRCDCNT[n] 

Description 

8-character date format yy/mm/dd 

10-character date format yyyy/mm/dd 

3-character day of week: MON TUE WED THU FRI SAT SUN 

Number of rows deleted from all the target tables of Import n. If n is not 

specified, it gives the count of deletes done to all the target tables for all 

imports. The maximum value of n is 4. 

Number of records inserted into the error table for import n. If n is not 

specified, it gives the total count of all the records inserted into the error 

table for all imports. The maximum value of n is 4. 

Number of rows inserted into all the target tables for import n. If n is not 

specified, this variable gives the total inserts done to all the target tables 

for all imports. The maximum value of n is 4. 

Up to 16 characters (ASCII or EBCDIC) in length, in whichever 

character set is appropriate. 

If &SYSJOBNAME is not set using the NAME command, it defaults to 

MYYYYMMDD_hhmmss_lllll, where 

M = macro 

YYYY = year 

MM = month 

DD = day 

hh = hour 

mm = minute 

ss = second 

lllll = is the low-order 5 digits of the logon sequence number returned by 

the database from the .LOGON command. 

Client operating system: 

• UNIX 

• HP-UX 

• IBM-AIX 

• Win32 

• Linux 

• For z/OS: 

VS1 

z/OS 

z/OS /SP 

z/OS /ESA 

Completion code from last response by Teradata Database. 

Total number of records read for import n. If n is not specified, it gives 

the total records read for all imports. 




Table 15: Predefined System Variables (continued) 

System Variable 

&SYSTIME 

&SYSUPDCNT[n] 

&SYSUSER 

&SYSAPLYCNT[n] 

&SYSNOAPLYCNT[n] 

&SYSRJCTCNT[n] 

Description 

8-character time format hh:mm:ss 

Gives total updates to all target tables for import n. If n is not given, it 

gives the total updates done to all the target tables for all the imports. 

The maximum value of n is 4. 

Client system dependent: CMS user ID, z/OS Batch user ID. (z/OS-batch 

returns user ID only when a security package such as RACF, ACF2, or 

Top Secret has been installed). 

Number of records applied for import n. If n is not given, it gives the 

total number of records applied for all imports. 

Number of records not applied for import n. If n is not given, it gives the 

total number of records not applied for all imports. 

Number of records rejected for import n. If n is not given, it gives the 

total number of rejected records of all the imports. The maximum value 

of n is 4. 

Date and Time Variables 

&SYSDATE, &SYSDATE4, &SYSTIME, and &SYSDAY reflect the time when Teradata TPump 

begins execution. The original values are restored at restart. These values are character data 

types and should not be used in numeric operations. System variables cannot be modified, 

only referenced. 

The values returned by &SYSDAY are all in upper case. Monday, for example, is returned as 

'MON': 

0003 .IF '&SYSDAY' NOT = 'MON' THEN; 

14:10:28 - FRI JUL 30, 1993 

UTY2402 Previous statement modified to: 

0004 .IF 'FRI' NOT = 'MON' THEN; 

0005 .RUN FILE UTNTS39; 

0006 .ENDIF; 

This example causes the RUN FILE command to be executed every day but Monday. It can be 

seen from this example that any of the system variables can be used as the subject condition 

within an IF/ELSE/ENDIF command construct. This allows creation of a script forcing certain 

events to occur or tasks to operate in a predetermined sequence, based on the current setting 

of the variable. 

As another example, if we create the following table: 

.SET TABLE TO 'TAB&SYSDAY'; 

Create table &TABLE ( 

Account_Number INTEGER NOT NULL, 

Last_Name VARCHAR(25), 

First_Name VARCHAR(25), 

Street_Address VARCHAR(30), 

City VARCHAR(20), 

State CHAR(2), 




Zip_Code CHAR(5) 

Balance DECIMAL(9,2) FORMAT '-$,$$$,$$$.99' ) 

Unique primary Index (Account_Number); 

and then check the system variable &SYSRC for a return code to verify if the table already 

exists, a file containing options to continue or quit is logged at the console. Any other error 

return codes terminate the job with a Teradata Database error, as follows: 

.SET CREATERC TO &SYSRC; 

.IF CREATERC = 3803 /* Table &TABLE already exists */ 

.RUN FILE RUN01; 

.ELSE 

.IF CREATERC 0 THEN 

.LOGOFF CREATRC; 

.ENDIF 

.BEGIN LOAD ----------; /* No errors returned. We can start the job.*/ 

/* TPump statements go here..... */ 

.END LOAD; 

.LOGOFF; 

File RUN01, which operates when the 3803 error causes the RUN FILE command to execute, 

contains the following options: 

.DISPLAY '&SYSUSER: Table FOO already exists....' 

to FILE console; 

.DISPLAY '&SYSUSER: Reply Continue anyway...' 


.DISPLAY '&SYSUSER: Reply Abort this JOB....' 


.DISPLAY '&SYSUSER: Reply or .Default ' 


.ACCEPT RESPONSE FROM FILE CONSOLE; 

.IF RESPONSE 'C' THEN 

.LOGOFF CREATERC; /* Quit before we cause trouble */ 

.ENDIF; 

Row Count Variables 

The row count variables, which are updated for each Teradata TPump task, allow the insert, 

update, and delete row counts and the error table counts for each import to be queried: 

• &SYSDELCNT[n] 

• &SYSETCNT[n] 

• &SYSINSCNT[n] 

• &SYSUPDCNT[n] 

The values are stored in the Teradata TPump utility restart log table and are restored after a 

client system or Teradata Database restart. 

When EXECUTE INSERT|UPDATE|DELETE is used, Teradata TPump must 

rely on the user to have correctly identified the action (INSERT, UPDATE, or DELETE) which 

the macro performs. Teradata TPump cannot always determine the number of target tables, 

and therefore can only provide a single combined value for all target tables. Using the existing 

facility of variable substitution, each new system variable can be referenced as soon as the 

variable is defined. The new variables are defined during the import phase and should be 




referenced after the END LOAD command and before any subsequent BEGIN LOAD 

command in the Teradata TPump job script. 

The values of the new system variables must be stored in the Teradata TPump log table and be 

restored after a restart. 

Utility Variables 

Teradata TPump supports utility variables. These variables are set via either the SET 

command or the ACCEPT command. Chapter 3 describes them in greater detail. 

Additionally, Teradata TPump predefines some utility variables that provide information 

about the Teradata TPump environment at execution time. The name of these variables must 

begin with an ampersand (&) when variable substitution is desired. The rest of the name must 

obey the rules for standard Teradata SQL column names. Consequently, the name of the 

variable without ampersand can be no longer than 29 characters, so that with an ampersand it 

does not exceed the 30-character limit. 

Teradata TPump supports an environmental variable for each DML statement executed. At 

the end of an import, a variable is established for each statement executed. The variable is 

named using the number of the import (one through four), the label of the clause 

“containing” the DML statement, and the number of the statement within the IMPORT’s 

apply clause. 

Variable Substitution 

Variable substitution, to allow for dynamic statement modification, is allowed on any 

statement by preceding the variable name with an ampersand. Each occurrence of a variable 

name, preceded by an ampersand, is replaced by its current value. Numeric values are 

permitted, but their values are converted to character for the replacement. This replacement 

occurs before the statement is analyzed. The replacement operation for a given statement 

occurs only once (one scan). This means that replacements generating ampersand variable 

names are not replaced. 

Even when it appears in a quoted string, an ampersand is always interpreted as the first 

character of a utility variable unless it is immediately followed by another ampersand. Such a 

double ampersand is converted to a single textual ampersand. 

If a reference to a utility variable is followed by a nonblank character that could appear in a 

variable name, there must be a period between the variable and the nonblank character(s). 

Teradata TPump discards the period in this context. 

For example, if a utility variable called &x has the value xy and is to be immediately followed 

by the characters .ab in some context, the sequence of variable and characters must appear as 

&x..ab to produce xy.ab as the result. Such a double period is converted to a single textual 

period and concatenated with the value of the utility variable. 

ANSI/SQL DateTime Data Types 

The following ANSI/SQL DateTime data types can be specified as column or field modifiers in 

some of the Teradata SQL statements used with Teradata TPump: 




• DATE 

• TIME 

• TIMESTAMP 

• INTERVAL 

For example, they can be used in CREATE TABLE statements and in INSERT statements. 

However, some restrictions may apply when ANSI/SQL DateTime data types are used. 

In the FIELD command, the ANSI/SQL DateTime data types must be converted to fixedlength 

CHAR(10) data types. See section “Using ANSI/SQL DateTime Data Types” on 

page 138 for a description of the fixed-length CHAR representations for each ANSI/SQL 

DateTime data types. 

Comments 

Teradata TPump supports C language style comments. A comment begins with a slash asterisk 

“/*” and all subsequent input is treated as a comment until a terminating asterisk slash “*/” is 

encountered. Comments may nest and they do not occur within string or character literals. 

For an example, a “/*” within a quoted string is not treated as the beginning of a comment. 

Comments are written to the message destination. Substitution of values for variable names 

continues within comments. If the variable name is required, two “&”s should be coded. Note 

that recursive comments are permitted, which means that to end the comment, the number of 

terminating “*/” sequences must match the number of start “/*” comment sequences that are 

outstanding. 

Comments can be optionally sent to Teradata Database. If a comment is used together with a 

Teradata SQL statement, a semicolon may be placed as a terminating character to end the 

comment. The semicolon tells Teradata TPump to strip out the comment so that it is not sent 

to Teradata Database. If a semicolon is not used, the comment is sent to Teradata Database 

together with the Teradata SQL statement. 

Nested comments are supported when they occur before or after Teradata SQL statements. 

Nested comments within Teradata SQL statements are not supported. Nested comments must 

terminate with a semicolon. If a semicolon is not appended, the comment is erroneously sent 

to Teradata Database and a syntax error is returned. 

Specify a Character Set 

Table 16 describes ways to either specify the character set or accept a default specification. 




Table 16: Ways to Either Specify a Character Set or Accept a Default Specification 

Specification or Default Selection 

Runtime parameter specification 

Client System Specification 

Teradata Database Default 

Teradata TPump Utility Default 

Description 

Use when Teradata TPump is invoked, as described earlier in 

this chapter: 

• charset=charactersetname for channel-attached z/OS client 

systems 

• -c charactersetname for network-attached UNIX and 

Windows client systems 

Specify the character set for a client system before invoking 

Teradata TPump by configuring the: 

• HSHSPB parameter for channel-attached z/OS client 

systems 

• clispb.dat file for network-attached UNIX and Windows 

client systems 

Note: The charactersetname specification used when Teradata 

TPump is invoked always takes precedence over the current 

client system specification. 

If a charactersetname specification is not used when Teradata 

TPump is invoked, and there is no character set specification 

for the client system, Teradata TPump uses the default 

specification in the Teradata Database system table 

DBC.Hosts. 

Note: If the DBC.Hosts table specification for the default 

character set is relied upon, make sure that the initial logon is 

in the default character set: 

• EBCDIC for channel-attached z/OS client systems 

• ASCII for network-attached UNIX and Windows client 

systems 

If there is no character set specification in DBC.Hosts, then 

Teradata TPump defaults to: 

• EBCDIC for channel-attached VM and z/OS client systems 

• ASCII for network-attached UNIX and Windows client 

systems 

Character Set Specifications for AXSMODs 

When an AXSMOD is used with Teradata TPump, the session character set is passed as an 

attribute to the AXSMOD for possible use. The attribute value is a variable-length character 

string with either the character set name or the character representation of the character set 

ID. The attribute varies based on how the character set is specified. 

Table 17 contains a list of specifications for AXSMOD. 




Table 17: Character Set Specifications for AXSMOD 

Specify the session character set by 

ID 

name 

Attribute name is 

CHARSET_NUMBER 

CHARSET_NAME 

Multibyte Character Sets 

Teradata Database supports multibyte characters in object names when the client session 

character set is UTF-8 or UTF-16. Refer to International Character Set Support for a list of 

valid characters used in object names. In Teradata TPump scripts, double quote multibyte 

characters are used in object names. 

To log on with UTF-8 character set or other supported multibyte character sets (Chinese, 

Japanese, or Korean), create object names shorter than 30 bytes. This limitation applies to 

userid, password, and account. The logon string might fail if it exceeds 30 bytes per object 

name. 

Multibyte character sets impact the operation of certain Teradata TPump commands, as well 

as object names in Teradata SQL statements. 

Table 18 describes the impact on multibyte character sets on certain Teradata TPump 

commands. 

Table 18: Character Sets Impact on Teradata TPump Commands 

Teradata TPump 

Command Affected Element Impact 

ACCEPT Utility variables The utility variables may contain multibyte 

characters. If the client does not allow multibyte 

character set names, then the filename must be in 

uppercase English. 

BEGIN LOAD 

Table names: 

• Target tables 

• Error tables 

Target table names and error table names may 

contain multibyte characters. 

DML DML label name The label name in a DML statement may contain 

multibyte characters. The label name may be 

referenced in the APPLY clause of an IMPORT 

statement. 

FIELD Field name The field name specified may contain multibyte 

characters. The name can be referenced in other 

FIELD commands in NULLIF and field 

concatenation expressions, and in APPLY 

WHERE conditions in IMPORT commands. The 

FIELD command can also contain a NULLIF 

expression, which may use multibyte characters. 




Table 18: Character Sets Impact on Teradata TPump Commands (continued) 


Command Affected Element Impact 

FILLER Filler name The name specified in a FILLER command may 


IF IF condition The condition in an IF statement may compare 

multibyte character strings. 

LAYOUT 

LOGON 

LOGTABLE 

Layout name 

CONTINUEIF condition 

User name 

Password 

Table name 

Database name 

The layout name may contain multibyte 

characters and may be used in the LAYOUT 

clause of an IMPORT command. The 

CONTINUEIF condition may specify multibyte 

character set character comparisons. 

The user name and password may contain 

multibyte characters. 

The logtable name and database name may 


NAME set SYSJOBNAME This variable may contain kanji characters. 

SET Utility variable The utility variable may contain multibyte 

characters. The variable can be substituted 

wherever substitution is allowed. 

TABLE Table and database name The table name (and database name if the table 

name is fully qualified) specified in a TABLE 

statement may contain multibyte characters. 

Avoid using the TABLE command when using 

UTF-8 or UTF-16 character sets by explicitly 

specifying the layout. 

Graphic Data Types 

To define double-byte character set data, the GRAPHIC, VARGRAPHIC, and LONG 

VARGRAPHIC data types are supported. Teradata TPump accepts GRAPHIC data in the 

input data set or file containing the Teradata TPump statements to be executed. 

The FIELD and FILLER statements that describe the input data are the statements affected by 

GRAPHIC data support. Table 19 lists the GRAPHIC data types that can be specified for the 

datadesc option in the FIELD or FILLER statement. 

Table 19: GRAPHIC Data Types for datadesc option in FIELD or FILLER Statement 

GRAPHIC Data Type Input Length Description 

GRAPHIC (n) 

if n specified, (n*2) bytes; 

otherwise, 2 bytes (n=1 is 

assumed) 

n double-byte characters 

VARGRAPHIC (n) m+2 bytes where m/2



Table 19: GRAPHIC Data Types for datadesc option in FIELD or FILLER Statement (continued) 

GRAPHIC Data Type Input Length Description 

LONG VARGRAPHIC m+2 bytes where m/2



Table 20: Restrictions and Limitations on Operational Features and Functions (continued) 

Operational Feature/Function 

Date specification 

Access logging 

Primary Indexes and Partitioning 

Column Sets 

Restriction/Limitation 

For dates before 1900 or after 1999, the year portion of the 

date must be represented by four numerals (yyyy). The default 

of two numerals (yy) to represent the year is interpreted to be 

the 20th century, and must be overridden to avoid spurious 

year information. If the table column defined as type DATE 

does not have the proper format, the dates may not process 

properly. The correct date format must be specified at the time 

of table creation, for example: 

CREATE TABLE tab (ADATE DATE*); 

DEFINE a (char(10)) 

INSERT tab (ADATE = :a(DATE, FORMAT 'yyyy-mmdd')); 

Unlike the MultiLoad and FastLoad utilities, access logging can 

cause a severe performance penalty in Teradata TPump. This is 

because Teradata TPump uses normal SQL operations rather 

than a proprietary protocol, and if all successful table updates 

are logged, a log entry is made for each operation. The primary 

index of the access logging table may then create the possibility 

of row hash conflicts. 

Specify values for the partitioning column set when 

performing Teradata TPump deletes and updates to avoid lock 

contention problems that can degrade performance. Avoid 

updating primary index and partitioning columns with 

Teradata TPump to minimize performance degradation. 

Termination Return Codes 

When a Teradata TPump job terminates, it returns a completion code to the client system. 

Table 21 lists the conventions used. 

Table 21: Termination Return Codes 

Code 

Description 

0 Normal completion 

4 Warning 

8 User error 

12 Severe internal error 

16 No message destination is available 

Note: To avoid ambiguous or conflicting results, always use values greater than 20 when 

specifying a return code with the LOGOFF command. 



Writing a Teradata TPump Job Script 

Many CLI and Teradata Database errors generate return codes of 12. For Teradata Database 

errors that can be corrected and resubmitted, Teradata TPump tries up to 16 times to resubmit 

and, at the end of this process, returns a code of 12. Many CLI and Teradata Database errors 

generate the return code of 12, except for: 

• Errors on Teradata SQL statements outside of the Teradata TPump task (before the BEGIN 

LOAD command or after the END LOAD command). Teradata TPump ignores these 

errors, which display error messages but do not cause early termination, nor generate 

Teradata TPump return codes. 

• Retryable errors or errors caused by Teradata Database restarts. 


This section describes the contents of a Teradata TPump job script and explains how to write 

one. 

Definition 

Caution: 

The Teradata TPump job script, or program, is a set of Teradata TPump commands and 

Teradata SQL statements that alter the contents of the specified target tables in Teradata 

Database. These commands and statements: 

• Insert new rows 

• Update some or all of the contents of selected existing rows 

• Delete selected existing rows 

Each Teradata TPump job includes a number of support commands that establish and 

maintain the Teradata TPump support environment, and a number of task commands that 

perform the actual database insert, update, or delete operations. These commands and 

statements identify and describe the input data to be applied to the target table, and then place 

that data into the target table. These activities may commence anytime after configuring the 

program as described in “Teradata TPump Support Environment” on page 37. 

In the event of a client failure, the identical script must be resubmitted in order to restart. If 

the script is edited, a restart will not be permitted. 

Script Writing Guidelines 

The following script writing guidelines will help write a Teradata TPump job script: 

• A script may contain up to four IMPORTs (tasks), delimited by a leading BEGIN LOAD 

command and a trailing END LOAD command. 

• The BEGIN LOAD command specifies the number of sessions and establishes a number of 

controlling parameters. 

The BEGIN LOAD command also specifies the error table, and is the only table specified. 

An optional qualifying database name may also be specified. This database name may be 




different from the database being modified, thus allowing tables to be created and dropped 

with no impact on the production database. 

In addition, the BEGIN LOAD command establishes acceptable threshold levels for 

important task controls, such as number and percentage of errors, session limits, duration 

of logon attempts in hours (tenacity), and checkpointing frequency. This command also 

provides optional controls to: 

• determine where any macros are placed 

• guarantee serial operations on given rows 

• select the number of statements to pack into a multiple-statement request 

• select a restart logic mode 

• The next item appearing in a script is usually a description of the records in the external 

file containing the change data for the target tables. The description of these input records 

appears in a sequence of commands headed by the LAYOUT command. 

The LAYOUT command tags the record layout being depicted with a unique name, which 

is then referenced by subsequent script commands in tasks throughout the rest of the job. 

The LAYOUT is followed by the supporting information contained in the sequence of one 

or more FIELD, FILLER, and TABLE commands. 

• Each FIELD command describes a single data item occupying a column in the input row. 

These items are described by data type, starting position, length, and several other 

characteristics. The FIELD command is used only for those items (columns) relevant to 

the current task, which are to be sent to Teradata Database as changes to the target table. 

The FIELD command may include the KEY modifier if the column is to be considered part 

of the primary index for purposes of serialization. 

• Each FILLER command describes a column in the input row in the same way as the FIELD 

command. These FILLER fields are never sent to Teradata Database. The FILLER 

command, however, identifies those columns which should not be sent to Teradata 

Database. Thus, if a sequence of 10 alternating FIELD and FILLER commands is used to 

describe 10 contiguous columns in the row, every other column, a total of five columns, 

would be sent to Teradata Database. 

• The TABLE command identifies any existing table with the same layout as the input. The 

TABLE command is used when the changes are being enacted on entire rows, rather than 

selected columns. 

• The next entry in the script is the DML command, which is followed by the DML 

statements INSERT, UPDATE, and DELETE. The DML command creates an identifying 

label for the DML statement input, which immediately follows the command. The DML 

command also defines an error handling process for handling missing and duplicate rows, 

with respect to the error table. 

The three DML statements (INSERT, UPDATE, and DELETE) follow the DML command, 

and may occur in any order and in any quantity. The INSERT statement is used to place a 

complete and entirely new row into the target table. 

The UPDATE statement takes the data contents from columns in the input record, as 

defined with the LAYOUT, FIELD, FILLER command sequence, and substitutes the data 




into the target table. The UPDATE rows are selected based on criteria specified in a 

conditional clause in the statement. 

The DML command also allows UPDATE and INSERT statements to be paired to provide 

Teradata TPump with an upsert capability. This allows Teradata TPump, in a single pass, 

to attempt an UPDATE and, if it fails, perform an INSERT on the same row. 

The DELETE statement removes entire rows from the target table whenever the evaluation 

of the deleting condition is true, as specified in a conditional clause in the statement. 

• The only information not yet provided in the task is the identity of the input data file, the 

starting and ending records in the file that are being used in this task, and other related 

information. This is done with the IMPORT command. This command basically tells the 

Teradata TPump utility to bring in file X, from record A through record N, to associate the 

layout name (and specifications) with the input records, and to apply the desired DML 

(INSERT, UPDATE, and DELETE) statement to each record. 

• The last command in the script is the END LOAD command. This command flags the end 

of the commands and statements for the task, and triggers the program to begin execution 

of the task. 

For compatibility with the MultiLoad utility, multiple IMPORTs (up to four) are allowed 

within a single BEGIN/END LOAD pair. However, because Teradata TPump does have an 

apply phase, there is no significant difference between a script containing four BEGIN/ 

END LOAD pairs, each with one IMPORT, and a script with one BEGIN/END LOAD pair 

and four IMPORTs. 

Procedure for Writing a Script 

A complete Teradata TPump job includes: 

• Invoking Teradata TPump 

• Logging onto Teradata Database and establishing the Teradata TPump support 

environment 

• Specifying the Teradata TPump tasks 

• Logging off from Teradata Database and terminating Teradata TPump. 

Use the following procedure as a guide for writing Teradata TPump job scripts: 

Writing Teradata TPump Job Scripts 

1 Invoke Teradata TPump, specifying the runtime options: 

• Normal or abbreviated (brief) printout 

• Number of buffers per session 

• Character set 

• Configuration file 

• Periodicity rate 

• Error logging function 

• Macro save option 




• Alternate run file 

• Verbose mode 

Refer to “Invoking Teradata TPump” for detailed information about how to specify these 

options. 

2 Establish the Teradata TPump support environment using the support commands 

summarized in Table 8. 

As a minimum, this part of the Teradata TPump job must include: 

• A LOGTABLE command to specify the restart log table 

• A LOGON command to provide a logon string that is used to connect all Teradata SQL 

and Teradata TPump utility sessions with Teradata Database. 

3 Specify the Teradata TPump task using the task commands summarized in Table 8. 

4 To specify another Teradata TPump task: 

• Use the support commands to modify the Teradata TPump support environment for 

the next task. 

• Use the task commands to specify the next task. 

Repeat these steps for each task in the Teradata TPump job. 

Note: Though a single Teradata TPump job can include a number of different tasks, 

limiting the jobs to a single task for each invocation of Teradata TPump provides the 

highest assurance of a successful restart/recovery operation if a system failure interrupts 

the job. 

5 Use the LOGOFF command to disconnect all active sessions with Teradata Database and 

terminate Teradata TPump on the client system. 

Teradata TPump Script Example 

The following example shows what a simple Teradata TPump script and its corresponding 

output might look like. The lines that begin with 4-digit numbers (for example, 0001) are 

scripts, the rest are output. 

**** 19:02:53 UTY6633 WARNING: No configuration file, using build defaults 

======================================================================== 

= = 


= Platform MVS = 

= = 

======================================================================== 

= = 


= = 

======================================================================== 


======================================================================== 

= = 


= = 

======================================================================== 

0001 .LOGTABLE TPLOG0045; 

0002 .LOGON TDRT/IVYDB,; 






**** 19:02:54 UTY8400 Default character set: EBCDIC 






**** 19:02:55 UTY6217 Logtable 'IVYDB.TPLOG0045' has been created. 

======================================================================== 

= = 


= = 

======================================================================== 

0003 .NAME TP0045; 

0004 .BEGIN LOAD 

SESSIONS 20 

PACK 20 

ROBUST ON 

SERIALIZE ON 

CHECKPOINT 0 

ERRORTABLE TPERR0045; 

======================================================================== 

= = 

= Processing TPump Statements = 

= = 

======================================================================== 


0006 .FIELD F0 * integer key; 

0007 .FIELD F1 * integer; 


0009 .FIELD F3 * char(38); 

0010 .DML LABEL DML0045; 

0011 UPDATE TPTBL0045 set F2 = F1 + 1 where F0 = :F0 ; 

0012 .IMPORT INFILEINDATA FROM 1 THRU 100 


APPLY DML0045; 




======================================================================== 

= = 


= = 

======================================================================== 







. Restart Mode: ROBUST. 

. Serialization: ON. 



**** 19:02:56 UTY6673 Warning: this TPump job will not be restartable once data 

loading has begun, since checkpointing has been suppressed when checkpoint 

is specified to zero. 




View Teradata TPump Output 










. ========= ============== 





** Statistics for Apply Label : DML0045 


U IVYDB TPTBL0045 100 

**** 19:03:02 UTY0821 Error table IVYDB.TPERR0045 is EMPTY, dropping table. 

0014 .IF &SYSUPDCNT = 100 THEN; 

**** 19:03:03 UTY2402 Previous statement modified to: 

0015 .IF 100 = 100 THEN; 

0016 .DISPLAY 'ROWCOUNT OK' TO FILE SYSTEST; 

0017 .ELSE; 

0018 .DISPLAY 'ROWCOUNT NOT OK' TO FILE SYSTEST; 

0019 .ENDIF; 

0020 .IF &SYSETCNT = 0 THEN; 

**** 19:03:03 UTY2402 Previous statement modified to: 

0021 .IF 0 = 0 THEN; 

0022 .DISPLAY 'NO ERRORS' TO FILE SYSTEST; 

0023 .ELSE; 

0024 .DISPLAY 'ERRORS!!!' TO FILE SYSTEST; 

0025 .ENDIF; 

======================================================================== 

= = 


= = 

======================================================================== 




. Start : 19:02:53 - TUE OCT 06, 2009 

. End : 19:03:04 - TUE OCT 06, 2009 



Teradata TPump reporting functions provide timely information about the status of tasks in 

progress and those just completed. 

• Teradata TPump Statistics—The Teradata TPump Statistics facility provides information 

on the success or failure of Teradata TPump processing, with respect to data records 

transferred, target table row modifications, and error table statistics. These statistics are 

accumulated and presented at the end of the job. 




Teradata TPump Statistics 

• Teradata TPump Options Messages—The options messages list the settings of some 

important Teradata TPump task parameters. 

• Logoff/Disconnect Messages—The logoff/disconnect messages report several key run 

statistics. 

For each task, Teradata TPump accumulates statistical items and writes them to the customary 

output destination of the external system, SYSPRINT/stdout (or the redirected stdout), or the 

destination specified in the ROUTE command. 

Table 22 lists the Teradata TPump statistics kept. 

Table 22: Teradata TPump Statistics 

Reference 

Number Reference Item Statistic 

1 Candidate records considered The number of records read. 

2 Apply conditions satisfied The number of statements sent to the database. If 

there are no rejected or skipped records, this value is 

equal to the number of candidate records, multiplied 

by the number of APPLY statements referenced in the 

import. 

3 Errors loggable to error table The number of records resulting in errors on the 

database. These records are found in the associated 

error table. 

4 Candidate records rejected The number of records which are rejected by the 

Teradata TPump client code because they are 

formatted incorrectly. 

5 Statistics for Apply Label This area breaks out the total activity count for each 

statement within each DML APPLY clause. The Type 

column contains the values U for update, I for insert, 

and D for delete. Note that unlike the other reported 

statistics, these values are NOT accumulated across 

multiple imports. 

6 Number of database requests 

sent 

These statistics are displayed only in the verbose 

mode, which is selected as a runtime parameter, 

VERBOSE, in z/OS, or -v in UNIX. 

In addition, Teradata TPump receives a count of the number of rows deleted from Teradata 

Database. Teradata TPump writes it either to SYSPRINT/stdout (or the redirected stdout), or 

the destination specified in the ROUTE command. 

If a record is rejected due to an error, as in the case of a duplicate, missing, or extra insert, 

update, or delete row, the following statistical output shows that an error condition occurred. 





. ========= ============== 

Candidate records considered:........ 8....... 8



F2 integer, 

F3 char(38)) 

UNIQUE PRIMARY INDEX(F0); 


0004 CREATE TABLE TAB2, FALLBACK, NO JOURNAL ( 

F0 integer, 

F1 integer, 

F2 integer, 

F3 char(38)) 

UNIQUE PRIMARY INDEX(F0); 


0005 .BEGIN LOAD 

SESSIONS 10 

ROBUST ON 

SERIALIZE ON 

CHECKPOINT 10 

NOMONITOR 

ERRORTABLE ET_TEST1; 

======================================================================== 

= = 


= = 

======================================================================== 

0006 .LAYOUT LAY1A; 

0007 .FIELD F0 * integer key; 



0010 .FIELD F3 * char(38); 

0011 .DML LABEL TAB1PART1; 

0012 INSERT into tab1 values (:F0,:F1,:F2,:F3); 

0013 .DML LABEL TAB2PART1; 

0014 INSERT into tab2 values (:F0,:F1,:F2,:F3); 

0015 .DML LABEL TAB1UPSERT 

DO INSERT FOR MISSING UPDATE ROWS 

IGNORE DUPLICATE INSERT ROWS; 

0016 UPDATE tab1 set F2=:F2 + 1 where f0=:f0 + 50 and f1 < 4; 

0017 INSERT into tab1 ( F0, F1, F2, F3) values (:F0 + 50,:F1,:F2,:F3); 

0018 .DML LABEL TAB2UPSERT 


IGNORE DUPLICATE INSERT ROWS; 

0019 UPDATE tab2 set F2=:F2 + 1 where f0=:f0 + 50 and f1 < 4; 

0020 INSERT into tab2 ( F0, F1, F2, F3) values (:F0 + 50,:F1,:F2,:F3); 

0021 .IMPORT INFILE INDATA 

FROM 1 THRU 100 

LAYOUT LAY1A 

APPLY TAB1PART1 

APPLY TAB2PART1; 

0022 .IMPORT INFILE INDATA 

FROM 1 THRU 100 

LAYOUT LAY1A 

APPLY TAB1UPSERT 

APPLY TAB2UPSERT; 




======================================================================== 

= = 


= = 




======================================================================== 



























. ========= ============== 

Candidate records considered:........ 100....... 100




Number of RDBMS requests sent:....... 10....... 20 

** Statistics for Apply Label : TAB1UPSERT 


U ARIDB tab1 50 

I ARIDB tab1 50 

** Statistics for Apply Label : TAB2UPSERT 


U ARIDB tab2 50 

I ARIDB tab2 50 

**** 01:33:54 UTY0821 Error table ARIDB.ET_TEST1 is EMPTY, dropping table. 

0024 .LOGOFF; 

======================================================================== 

= = 


= = 

======================================================================== 




. Start : 01:33:23 - TUE OCT 06, 2009 

. End : 01:33:58 - TUE OCT 06, 2009 


The above script has a realistic degree of complexity. The script demonstrates a Teradata 

TPump job that contains two imports and each import has at least two associated statements. 

For the first import there are two statements, each of which is specified in a separate DML 

statement. The IMPORT statement references the two statements through two APPLY clauses. 

The second import adds additional complexity by having two statements in each DML 

statement. In this case, the two statements in each DML compose an upsert statement. 

Teradata TPump Options Messages 

The options message lists the settings of some important Teradata TPump task parameters. A 

few examples follow: 

Example 1 

The following example depicts a typical options message. 






. Errlimit: 1 rejected record(s). 





Example 2 

In this example, the error limit is expressed as a percent of rows, not as a hard limit, the 

recovery mode is simple, and serialization is on. 








. Checkpoint: 5 minutes. 

. Errlimit: 10% of records rejected. 




. StartUp Rate: 500 Statements per Minute. 

Example 3 

In this example, there is no error limit in effect and tenacity has been set to zero. 


. Tenacity: Sessions must successfully connect on first try. 



. Checkpoint: 5 minutes. 






Logoff/Disconnect Messages 

In response to the LOGOFF command, Teradata TPump completes the step by disconnecting 

active sessions and reporting on total run statistics. The logtable is either dropped or kept, 

depending on the success or failure of the previous activity. 

When a Teradata TPump session is logged off, the following status messages are written to the 

SYSPRINT/stdout (or the redirected stdout) data destination, or to the destination specified 

in the ROUTE command. 

**** 01:57:45 UTY6216 The restart log table has been dropped.**** 


**** 01:57:45 UTY2410 Total processor time used = '0.270389 Seconds'**** 

. Start : 01:33:23 - TUE OCT 06, 2009 

. End : 01:33:58 - TUE OCT 06, 2009 


Progress Monitoring 

Teradata TPump differs from most other Teradata load utilities in that there is no support for 

it in QrySessn. Instead, the optional Teradata TPump Monitor (see Table 23) is the only 

method for remotely overseeing the progress of the utility. Note however, that while Teradata 

TPump requests do appear in the QrySessn output, they are displayed as a collection of 

individual transactions instead of being summarized into one utility instance. 



Monitor Teradata TPump Jobs 


Monitor Interface Table 

Teradata TPump provides an optional monitoring tool to monitor and update Teradata 

TPump jobs. The Teradata TPump Monitor provides for run-time monitoring of the Teradata 

TPump job that allows tracking and altering the rate at which requests are issued to the 

database via a command-line interface. 

The Teradata TPump Monitor provides the following functions: 

• Provides a set of SQL scripts that create a Monitor Interface table. Teradata TPump 

updates this table approximately once every minute. 

• Allows the status of an import to be learned by querying against the Monitor Interface 

table. 

• Allows altering the statement rate of an import by updating the Monitor Interface table. 

Use SQL scripts shipped with Teradata TPump to create a Monitor Interface Table 

(SysAdmin.TPumpStatusTbl) in the database where Teradata TPump maintains information 

about an import. Teradata TPump both reads commands from and updates status in the 

Monitor Interface Table. 

This table is required in order to use the Teradata TPump Monitor functionality, but is 

otherwise optional. If the table does not exist, the worst that will happen is that Teradata 

TPump issues a warning message indicating this fact. 

This table must be secure, so it is created by the DBA. 

An SQL script tpumpar.csql is provided in the Teradata TPump installation that performs the 

appropriate setup. The tpumpar.csql script includes an action request. 

Table 23 contains the monitor interface columns (other columns exist in order to support 

future functionality): 

Table 23: Monitor Interface Table 

Name Type Notes 

Import INTEGER Part of primary index. The import number. (There may be 

multiple imports in a Teradata TPump job. 

InitStartDate DATE The initial start date of the import. 

InitStartTime FLOAT The initial start time of the import. 

Complete CHAR(1) Y if this import is complete. (There may be multiple 

imports.) 

CurrStartDate DATE The last date this import was started (may be a restart). 

CurrStartTime FLOAT The last time this import was started (may be a restart). 

LastUpdateDate DATE The last date this import updated the table. 




Table 23: Monitor Interface Table (continued) 

Name Type Notes 

LastUpdateTime FLOAT The last time this import updated the table. 

LogDB VARCHAR(32) Part of primary index. The name of the log table database. 

LogTable VARCHAR(32) Part of primary index. The name of the log table. 

PeriodsDesired INTEGER Allows specifying the desired periodicity. 

PleaseAbort CHAR(1) Set to Y to abort. 

RecordsErrored INTEGER The number of records resulting in errors on the database. 

RecordsOut INTEGER The number of statements sent to the database. 

RecordsSkipped INTEGER The number of records skipped for apply conditions. 

RecordsRejcted INTEGER The number of records rejected for bad data (on host) 

RecordsRead INTEGER The number of records read. 

RequestAction CHAR(1) Before processing any action request, a message will be logged 

stating that the requested action is being taken. The following 

action requests are permitted: 

• Blank – No action 

• C – Take a checkpoint and continue the job 

• P – Take a checkpoint and pause until a subsequent action 

request resumes or terminates the job 

• R – Resume the job 

• T – Take a checkpoint and terminate the job with rc = 8. 

The job may be restarted. 

• A – Terminate the job immediately with rc = 12. The job 

may be restarted. 

RequestChange CHAR(1) Set to Y by the user so Teradata TPump will pick up the 

changes. Set to N by Teradata TPump after changes are 

accepted. 

RestartCount INTEGER The number of times this import has been restarted. 

StmtsDesired INTEGER The statement rate (if StmtsUnLimited is N) 

StmtsUnLimited CHAR(1) Y if this import running without a statement rate limit. 

If N, refer to StmtsDesired for the statement rate. 

UserName VARCHAR(32) The name of the user running the job. Used for security. 

Security concerns dictate that the SQL script to set up the Monitor Interface table for Teradata 

TPump monitoring also establishes a set of views and macros in addition to the 

TPumpStatusTbl. Although database administrators can access the table directly, using 

macros and views is recommended because they provide for security and ensure rational use 

of the table. 




Without action on the part of the database administrator, no normal user can update the 

status of jobs. To grant controlled update access to the TPumpStatusTbl, a single command 

will suffice: 

“GRANT EXEC ON TPumpMacro TO _____;” 

The macros for Teradata TPump monitoring reside in the database TPumpMacro and 

SysAdmin. 

Teradata TPump Monitor Views 

The following views of the Monitor Interface table are available: 

View SysAdmin.TPumpStatus 

This view is for database administrators and lets them see all running Teradata TPump 

imports. 

CREATE VIEW SysAdmin.TPumpStatus AS LOCKING 

SysAdmin.TPumpStatusTbl FOR ACCESS 

SELECT * FROM SysAdmin.TPumpStatusTbl; 

View SysAdmin.TPumpStatusX 

This view is for all users and provides a view of Teradata TPump jobs. However, this view will 

only show jobs which are “owned” by the user. 

CREATE VIEW SysAdmin.TPumpStatusX AS LOCKING 

SysAdmin.TPumpStatusTbl FOR ACCESS 

SELECT * FROM SysAdmin.TPumpStatusTbl 

WHERE UserName = USER; 

Teradata TPump Monitor Macros 

Teradata TPump Monitor provides a set of macros that can be used to update the Monitor 

Interface table and to monitor and control individual Teradata TPump import jobs. The 

following Teradata TPump Monitor macros are provided: 

Macro TPumpMacro. TPumpUpdateSelect 

This macro is provided for database administrators to use to manipulate and monitor 

individual Teradata TPump jobs: 

CREATE MACRO SysAdmin.TPumpUpdateSelect 

( 

LogDB 

VARCHAR(32), 

LogTable VARCHAR(32), 

UserName VARCHAR(32), 

Import 

INTEGER, 

RequestChange CHAR(1), 

StmtsUnLimited CHAR(1), 

StmtsDesired INTEGER, 

PeriodsDesired INTEGER 




) 

AS 

( 

LOCK ROW WRITE /* OR LOCKING Sysadmin.TPumpStatus for WRITE */ 

SELECT 

RecordsOut , 

RecordsSkipped , 

RecordsRejcted , 

RecordsRead , 

RecordsErrored 

FROM 

SysAdmin.TPumpStatusTbl 

WHERE 

UserName = :UserName AND 

LogDB = :LogDB AND 

Import = :Import AND 

LogTable = :LogTable 

; UPDATE SysAdmin.TPumpStatusTbl 

SET 

RequestChange = :RequestChange, 

StmtsUnLimited = :StmtsUnLimited, 

StmtsDesired = :StmtsDesired, 

PeriodsDesired = :PeriodsDesired 

WHERE 

UserName = :UserName AND 


LogTable = :LogTable AND 

Import = :Import ; 

);mport = :Import ; 

); 

Macro TPumpMacro. UserUpdateSelect 

The macro UserUpdateSelect is provided to monitor/update Teradata TPump jobs. 

CREATE MACRO TPumpMacro.UserUpdateSelect 

( 

LogDB 

VARCHAR(32), 

LogTable VARCHAR(32), 

Import 

INTEGER, 

RequestChange CHAR(1), 

StmtsUnLimited CHAR(1), 

StmtsDesired INTEGER, 

PeriodsDesired INTEGER 

) 

AS 

( 

LOCK ROW WRITE /* OR LOCKING Sysadmin.TPumpStatus FOR WRITE */ 

SELECT 

RecordsOut , 

RecordsSkipped , 

RecordsRejcted , 

RecordsRead , 

RecordsErrored 

FROM 

SysAdmin.TPumpStatusTbl 

WHERE 

UserName = USER 

AND 



Estimating Space Requirements 


Import = :Import AND 

LogTable = :LogTable 

); 

; UPDATE SysAdmin.TPumpStatusTbl 

SET 

RequestChange = :RequestChange, 

StmtsUnLimited = :StmtsUnLimited, 

StmtsDesired = :StmtsDesired, 

PeriodsDesired = :PeriodsDesired 

WHERE 

UserName = USER AND 


LogTable = :LogTable AND 

Import = :Import ; 


This section discusses space requirements for the Teradata TPump log table. 

A row of approximately 200 bytes is written to the log table on each of the following events. 

• One row is written at initialization. 

• One row is written for each SQL statement issued through the Teradata TPump support 

environment. 

• One row is written at the BEGIN LOAD command. 

• One row is written at the END LOAD command. 

• Two rows are written for each IMPORT command. 

• One row is written for each statement used in a load (between the BEGIN LOAD 

command and the END LOAD command). 

• One row is written for each checkpoint taken. 

• In the ROBUST mode, for each packed request, a number of partial checkpoint rows are 

written to the log between checkpoints. The rows are deleted each time a checkpoint is 

written. 

The partial checkpoint row contains 117 + (12 * packfactor) bytes per transaction. So the 

number of partial checkpoints will vary, depending on the checkpoint frequency, the power of 

the loading host, and the power of the Teradata target database. 

Thus, an equation for the space is: 

200 + 200 * each statement in the support environment + 400 * each BEGIN/END LOAD + 

200 * each statement issued as DML + 200 * the estimated number of checkpoints + (117 + 

(12 * packfactor)) * the number of partial checkpoints. A simplified version would be: 

R = 200 + 200S + 400L + 200D + 200C + (117 + (12P))N, 

where: 

R = Required space for Teradata TPump log table 




S = Each SQL statement issued through the support environment 

L = Each BEGIN/END LOAD command pair 

D = Each DML statement 

C = Estimated number of checkpoints 

P = Packfactor 

N = Number of partial checkpoints 

Space Calculation Example 

The following example of how Teradata TPump log table space is derived takes a simple load 

that consists of the following script: 

LOGTABLE CME.TLddNT14H; 

.LOGON OPNACC1/CME,CME; 

DROP TABLE TBL14TA; 

DROP TABLE TBL14TB; 

DROP TABLE tlnt14err; 

CREATE TABLE TBL14TA,FALLBACK 

(ABYTEINT BYTEINT, 

ASMALLINT SMALLINT, 

AINTEGER INTEGER, 

ADECIMAL DECIMAL (5,2), 

ACHAR CHAR (5), 

ABYTE BYTE(1), 

AFLOAT FLOAT, 

ADATE DATE) 

UNIQUE PRIMARY INDEX (ASMALLINT); 

CREATE TABLE TBL14TB,FALLBACK 

(ABYTEINT BYTEINT, 

ASMALLINT SMALLINT, 

AINTEGER INTEGER, 

ADECIMAL DECIMAL (5,2), 

CHAR CHAR (5), 

ABYTE BYTE(1), 

AFLOAT FLOAT, 

ADATE DATE) 

UNIQUE PRIMARY INDEX (ASMALLINT); 

/*****************************************************************/ 

/* BEGIN TLOAD WITH ALL THE OPTIONS SPECIFIED SUCH AS ERRLIMIT, **/ 

/* CHECKPOINT, SESSIONS,TENACITY **/ 

/*****************************************************************/ 

.BEGIN LOAD ERRLIMIT 5 CHECKPOINT 15 SESSIONS 4 1 TENACITY 2 

ERRORTABLE tlnt14err ROBUST ON PACK 20; 

.LAYOUT LAY1A; 

.FILLER ATEST * BYTEINT; 

.FIELD ABYTEINT * BYTEINT; 

.FIELD ASMALLINT * SMALLINT; 

.FIELD AINTEGER * INTEGER; 

.FIELD ADECIMAL * DECIMAL (5,2); 

.FIELD ACHAR * CHAR (5); 

.FIELD ABYTE * BYTE(1); 

.FIELD AFLOAT * FLOAT; 

.FIELD ADATE * DATE; 

.DML LABEL LABELA IGNORE DUPLICATE ROWS IGNORE MISSING ROWS 




IGNORE EXTRA ROWS; 

INSERT INTO TBL14TA VALUES (:ABYTEINT,:ASMALLINT,:AINTEGER,:ADECIMAL, 

:ACHAR,:ABYTE,:AFLOAT,:ADATE); 

.DML LABEL LABELB IGNORE DUPLICATE ROWS IGNORE MISSING ROWS 


INSERT INTO TBL14TB VALUES (:ABYTEINT,:ASMALLINT,:AINTEGER,:ADECIMAL, 

:ACHAR,:ABYTE,:AFLOAT,:ADATE); 

.IMPORT INFILE ./tlnt014.dat 

LAYOUT LAY1A FROM 1 FOR 400 

APPLY LABELA WHERE ATEST = 1 

APPLY LABELB WHERE ATEST = 2; 

.END LOAD; 

.LOGOFF; 

From this script the space requirements can be calculated to be: 

• 200 bytes for initialization + 

• 200 bytes * 6 for support environment statements + 

• 200 bytes * 2 for DML SQL statements + 

• 400 bytes for the BEGIN/END load pair + 

• 200 bytes for the IMPORT 

which is a starting total of 2400 bytes. 

Further, assume that Teradata Database can accept about 32 statements per second and that 

the load takes a little more than an hour to complete. 

The space for partial and complete checkpoints is calculated with the following steps: 

Calculating the Space for Checkpoints 

1 32 statements per second translates to 1920 statements per minute. 

2 1920 / 20 (the packing factor) = 93 partial checkpoints/minute 

3 Multiply by 15 (15 minute CP frequency) = 1395 partial checkpoint rows maximum. 

4 Each checkpoint row is 117 + (12 * 20) = 357 bytes so 498,015 bytes are in partial 

checkpoint rows. 

5 Given that the load takes just more than an hour, assume 5 checkpoints are written at 

300 bytes each. 

Now we have the grand total of space in the log table: 

2,400 + 498,015 + 1,500 = 517,980 bytes. 





CHAPTER 3 


This chapter describes the Teradata TPump commands and Teradata SQL statements that 

execute from the Teradata TPump utility. 

Experienced Teradata TPump users can also refer to the simplified command descriptions in 

the Teradata TPump chapter of Teradata Tools and Utilities Command Summary. This book 

provides the syntax diagrams and a brief description of the syntax variables for each Teradata 

client utility. 

Syntax Notes 

This section provides information which should be known before using Teradata TPump 

commands and Teradata SQL statements. 

Each Teradata TPump command: 

Object Name Restrictions 

• Must begin on a new line. 

• Must start with a period (.) character. In this document, Teradata TPump command 

periods are shown only in syntax diagrams and examples, but not in the narrative text. 

• Must end with a semicolon (;) character. 

• May continue for as many lines as necessary, as long as it satisfies the beginning and 

ending requirements. 

Statements are standard Teradata SQL statements and are not preceded by periods. 

The following Syntax rules apply to object names: 

• A semicolon cannot be used in an object name because a semicolon is used to designate 

the end of a Teradata TPump command. 

• 30 bytes cannot be used as the quoted object name length. 

• An ampersand (&) cannot be used in an object name. 

See Appendix A: “How to Read Syntax Diagrams” for more information about how to read 

the syntax diagrams used in this book. 

Geospatial Data Restrictions 

The following rules apply to Geospatial data: 


Chapter 3: Teradata TPump Commands 

Syntax Notes 

• Teradata TPump does not support Geospatial data represented by LOBs. 

• Teradata TPump does not support geospatial data beyond 64000. 

Large Decimal and BIGINT Restrictions 

The following restrictions apply to Large Decimal and BIGINT: 

• Nullif and apply-where clause support includes Large Decimal. BIGINT is not included. 

• SET and ACCEPT commands cannot assign and accept Large Decimal and BIGINIT 

values. 

• Serialization on Large Decimal and BIGINT fields is not recommended. 


Table 24 is an alphabetical list of the commands supported by Teradata TPump. The syntax 

and use of these commands is described in detail in this chapter. 

Table 24: Teradata TPump Commands 

Command 

ACCEPT 

BEGIN LOAD 

DATEFORM 

DISPLAY 

DML 

ELSE 

ENDIF 

END LOAD 

FIELD 

FILLER 

Definition 

Accepts the data type and value of one or more utility variables from an external 

source. 

Indicates the start of a Teradata TPump task and specifies the parameters for 

executing the task. 

Defines the form of the DATE data type specifications for the Teradata TPump 

job. 

Writes messages to the specified destination. 

Defines a label and error treatment option for the Teradata SQL DML 

statement(s) following the DML command. INSERT, UPDATE, DELETE, and 

EXECUTE are the DML statement options. 

The ELSE command is followed by commands and statements that execute 

when the preceding IF command is false. See IF, ELSE, and ENDIF. 

Exits from the conditional expression IF or IF/ELSE command sequences. 

ENDIF is followed by commands and statements resuming the program. See IF, 

ELSE, and ENDIF. 

Indicates completion of Teradata TPump command entries and initiates the 

task. This is the last command of a Teradata TPump task. 

Defines a field of the data source record. Fields specified by this command are 

sent to Teradata Database. This command is used with the LAYOUT 

command. 

Defines a field in the data source that is not sent to Teradata Database. This 

command is used with the LAYOUT command. 



Syntax Notes 

Table 24: Teradata TPump Commands (continued) 

Command 

IF 

IMPORT 

LAYOUT 

LOGOFF 

LOGON 

LOGTABLE 

NAME 

PARTITION 

ROUTE 

RUN FILE 

SET 

SYSTEM 

TABLE 

Definition 

The IF command is followed by a conditional expression which, if true, executes 

commands and statements following the IF command. See IF, ELSE, and 

ENDIF. 

Identifies the data source, layout, and optional selection criteria to the client 

program. 

Specifies layout of the externally stored data records to be used in the Teradata 

TPump task. This command is used in conjunction with an immediately 

following sequence of FIELD, FILLER, and TABLE commands. 

Disconnects all active sessions and terminates execution of Teradata TPump on 

the client. 

Establishes a Teradata SQL session on Teradata Database, and specifies the 

LOGON string to be used in connecting all sessions required by subsequent 

functions. 

Identifies the table to be used for journaling checkpoint information required 

for safe, automatic restart of Teradata TPump in the event of a client or Teradata 

Database failure. 

Sets the utility variable &SYSJOBNAME with a job name of up to 16 characters. 

Establishes session partitions to transfer SQL requests to Teradata Database. 

Identifies the destination of output produced by Teradata TPump. 

Invokes the specified external source as the current source of commands and 

statements. 

Assigns a data type and a value to a utility variable. 

Suspends Teradata TPump to issue commands to the local operating system. 

Identifies a table whose column names and data descriptions are used as the 

names and data descriptions of the input record fields. Used in place of, or in 

addition to, the FIELD command. This command is used with the LAYOUT 

command. 

Note: When UTF-16 session character set is used, the TABLE command will 

generate a field of CHAR(2n) for the CHAR(n) typed column and a field of 

VARCHAR(2m) for the VARCHAR(m) typed column because each character in 

the column takes 2-byte storage when using UTF-16 session character set. 

Teradata TPump Teradata SQL Statements 

The following Teradata SQL statements supported by Teradata TPump are included in this 

chapter because they require special considerations for use with Teradata TPump. They are 

used for loading purposes and for creating Teradata TPump macros. The syntax and use of 

these Teradata SQL statements is described in detail in this chapter. 

Table 25 lists the Teradata SQL Statements supported by Teradata TPump. 



Syntax Notes 

Table 25: Teradata TPump Teradata SQL Statements 

Statement 

DATABASE 

DELETE 

EXECUTE 

INSERT 

UPDATE Statement and Atomic Upsert 

Definition 

Changes the default database qualification for all DML 

statements. 

Removes specified rows from a table. 

Specifies a user-created (predefined) macro for execution. 

The macro named in this statement resides in Teradata 

Database and specifies the type of DML statement 

(INSERT, UPDATE, or DELETE) being handled by the 

macro. 

Adds new rows to a table by directly specifying the row 

data to be inserted. 

Changes field values in existing rows of a table. 



ACCEPT 

ACCEPT 

Purpose 

The ACCEPT command accepts data types and values from an external source and uses them 

to set one or more utility variables. The ACCEPT command is a valid command preceding 

LOGON and LOGTABLE commands. 

Syntax 

, 

.ACCEPT 

var 

FILE 

fileid 

A 

FROM 

ENVIRONMENT 

VARIABLE 

B 

ENV 

VAR 

A 

; 

IGNORE 

charpos1 

charpos1 

THRU 

THRU 

charpos2 

charpos1 

THRU 

charpos2 

B 

env_var 

; 

HE03B011 

where 

Syntax Element 

var 

env_var 

Description 

Name of the utility variable that is to be set with the value accepted 

from the designated source 

Character string values appear as quoted strings in the data file. 

Environment variable that provides the value for the specified utility 

variables (var) 



ACCEPT 


fileid 

charpos1 and charpos2 

Description 

Data source of the external system. 

The external system DD (or similar) statement specifies a file. 

UNIX and Windows 

infilename (the path name for a file). 

If the path name has embedded white space characters, enclose the 

entire path name in single or double quotes. 

z/OS 

a true DDNAME. 

If DDNAME is specified, Teradata TPump reads data records from 

the specified source. 

A DDNAME must obey the same rules for its construction as 

Teradata SQL column names, except that: 

• the “at” sign (@) is allowed as an alphabetic character 

• the underscore (_) is not allowed 

The DDNAME must also obey the applicable rules of the external 

system. 

If DDNAME represents a data source on magnetic tape, the tape 

may be either labelled or nonlabelled (if the operating system 

supports it). 

Start and end character positions of a field in each input record 

which contains extraneous information 

Teradata TPump ignores the specified field(s) as follows: 

• If charpos1 is specified, Teradata TPump ignores only the single 

specified character position. 

• If charpos1 THRU character positions are specified, Teradata 

TPump ignores character positions from charpos1 through the 

end of the record. 

• If THRU charpos2 is specified, Teradata TPump ignores character 

positions from the beginning of the record through charpos2. 

• If charpos1 THRU charpos2 is specified, Teradata TPump ignores 

character positions from charpos1 through charpos2. 

Usage Notes 

A single record, row, or input line is accepted from the designated source. Ensure that there is 

only one record in the file from which the ACCEPT command is getting the variables. 

If multiple variables are coded, each is sequentially assigned input text up to the first white 

space character encountered that is not within a quoted string. 

Input text for numeric values must be delimited only by white space or record boundaries. 

Input text for character strings must be enclosed in apostrophes. For example: 

.Accept age, name from file info; 



ACCEPT 

The data record provided to satisfy the preceding ACCEPT should include two fields. The 

following example shows two sample data records, where the first is correct but the next is not: 

32 'Tom' /* This line contains valid data. */ 

32 Tom /* Tom is invalid data. */ 

An additional method of placing comments in input text is as follows: 

32 'Tom'; This line contains valid data. 

When the number of variables listed is greater than the number of responses available, unused 

variables remain undefined (NULL). If there are not enough variables to hold all responses, a 

warning message is issued. If the input source is a file, the next record (starting with the first) 

of the file is always retrieved. 



BEGIN LOAD 

BEGIN LOAD 

Purpose 

The BEGIN LOAD command initiates or restarts a Teradata TPump task, specifying the 

number of sessions to use and any other parameters needed to execute the task. 

Syntax 

.BEGIN LOAD 

SESSIONS 

number 

threshold 

A 

A 

ERRORTABLE 

tname 

dbname. 

ERRLIMIT errcount 

errpercent 

APPEND 

NODROP 

QUEUETABLE 

CHECKPOINT 

frequency 

SERIALIZE 

OFF 

ON 

DATAENCRYPTION 

OFF 

ON 

ARRAYSUPPORT OFF 

ON 

TENACITY hours 

PACK 

statements 

PACKMAXIMUM 

LATENCY seconds 

NOTIMERPROCESS 

RATE 

statement_rate 

RETRYTIMES 

nn 

SLEEP minutes 

NOATOMICUPSERT 

NOMONITOR 

ROBUST ON 

OFF 

MACRODB dbname 

NOTIFY 

OFF 

LOW 

MEDIUM 

HIGH 

ULTRA 

EXITname 

TEXT ' string ' 

MSG ' string ' 

3021G017 



BEGIN LOAD 

where 


SESSIONS 

number 

threshold 

ERRORTABLE 

APPEND 

NODROP 

QUEUETABLE 

Description 

Keyword for the number of Teradata TPump sessions. 

Number of sessions to be logged on for update purposes for Teradata 


A Teradata TPump task logs on and uses the number of sessions 

specified. One additional session is used for performing various utility 

functions. 

There is no default value for number; it must be specified. Neither is 

there a maximum value, except for system-wide session limitations, 

which vary among machines. 

Limiting the number of sessions conserves resources on both the 

external system and Teradata Database. This conservation is at the 

expense of a potential decrease in throughput and increase in elapsed 

time. 

Minimum number of sessions to be logged on for update purposes for 

the utility. 

When logging on sessions, if the limits are reached above the threshold 

value, Teradata TPump stops trying to log on, and uses whatever 

sessions are already logged on. 

If the sessions run out before the threshold is reached, Teradata TPump 

logs off all sessions, waits for the time determined by the SLEEP value, 

and tries to log on again. 

Optional keyword for identifying a database and error table. 

Use a database name as a qualifying prefix to the error tables. Specifying 

a database that is not the production database avoids cluttering the 

production system with error tables. This means that because the 

database should have been allocated a lot of PERM space, that space will 

not have to be increased for all databases with tables involved in the 

Teradata TPump task. 

Caution: It is the user’s responsibility to ensure that the error table 

sharing was meaningful. Two jobs targeting different tables 

with different input record layouts cannot share the same 

error table. 

Specifies the existing error table. 

If the specified error table does not exist, Teradata TPump will create it. 

If the structure of the existing error table is not compatible with the 

error table Teradata TPump creates, the job will run into an error when 

Teradata TPump tries to insert or update the error table. 

Specifies to retain (not DROP) the error table, even it is empty at the 

end of a job. 

NODROP can be used with APPEND to persist the error table or alone. 

Selects the error table as a Queue Table. 



BEGIN LOAD 


dbname. 

tname 

Description 

The qualified database for the error table. 

If the database is not specified, the database which contains the log table 

is used. The period following the dbname separates the database name 

from the tname parameter. If a different database is specified, it may 

help to avoid cluttering the production database with error tables. 

Error table that receives information about errors detected during the 

load. 

tname may be preceded by a database name qualifier. This table is 

referred to as the error table or ET table. 

Teradata TPump does not explicitly specify the level of protection 

applied to this table, using instead the default protection level applied to 

the database wherein the error table is placed. If the database specifies 

fallback, tname becomes fallback. 

The default error table name is composed of the job name, followed by 

an underscore and sequence number of the load, then an underscore 

and an ET, as in jobname_nnn_ET. 

tname identifies a nonexisting table for a nonrestart task, or an existing 

table for a restart task. 

For all errors inserted in this error table, the identifiers for the offending 

combination of statement and data record are included in the 

appropriate row of tname. The columns in the error table allow the 

identification of a specific data record and statement combination 

which produced an error. The column names and definitions of the 

error table are: 

ImportSeq—A byteint containing the IMPORT command sequence 

number. 

DMLSeq —A byteint containing the sequence number of the DML 

command within the command file. 

SMTSeq—A byteint containing the sequence number of the DML 

statement within the DML command. 

ApplySeq—A byteint containing the sequence number of the APPLY 

clause within its IMPORT command. 

SourceSeq—An integer containing the position of a data record within a 

data source. 

DataSeq—A byteint identifying the data source. This value is always 

one. 

ErrorCode —An integer containing an error return code. 

ErrorMsg—Contains the corresponding error message for the error 

code. 

ErrorField —A smallint, which, if valid, indicates the bad field. 

The names of record fields sent to Teradata Database are specified via 

the LAYOUT command, in conjunction with FIELD and TABLE 

commands. 

HostData - A variable length byte string containing the data sent by the 

external system. 



BEGIN LOAD 


ERRLIMIT 

errcount 

CHECKPOINT 

Description 

Optional keyword for setting a limit on records rejected for errors. 

When the ERRLIMIT is exceeded, Teradata TPump performs a 

checkpoint, then terminates the job. The data read before ERRLIMIT 

was exceeded will be submitted and completed before the job is 

terminated. This means when a job is terminated due to ERRLIMIT was 

exceeded, there may be more error records in the error table than the 

number specified in ERRLIMIT. To facilitate diagnosis of data errors, 

the ERRLIMIT should be greater than the number of statements packed 

into one request. 

Error threshold for controlling the number of rejected records. Usage 

depends on whether used with the errpercent parameter. 

• When used without the errpercent parameter, specifies, as an 

unsigned integer, the number of records that can be rejected and 

recorded in tname during a load (all records sent between the BEGIN 

LOAD and END LOAD commands). The default is no limit. 

• When used with the errpercent parameter (which is approximate), 

specifies the maximum number of records that must be sent to 

Teradata Database before the errpercent parameter is applied. 

For example, if errcount = 100 and errpercent = 5, then 100 records must 

be sent to Teradata Database before the approximate 5 percent rejection 

limit is applied. If only the first five records are rejected when the 100th 

record is sent, the limit is not exceeded. If there are six rejections, 

however, then the limit is exceeded. After the 100th record is sent, 

Teradata TPump stops processing if the 5 percent limit has been 

exceeded. 

When the limit has been exceeded, Teradata TPump writes an error 

message to the external system’s customary message destination and 

terminates the task. 

All tables in use are left in their state at the time of the termination. This 

allows errors to be corrected in data records and restarting of the task 

from the last checkpoint. If a restart is not possible or not desired, any 

unwanted tables should be dropped. 

Keyword indicating the number of minutes between the occurrences of 

checkpoints. 

This is followed by a frequency value. 



BEGIN LOAD 


frequency 


ON/OFF 

Description 

The interval in minutes between check pointing operations. Specify an 

unsigned integer from 0 through 60, inclusive. 

To specify a CHECKPOINT frequency of less than or equal to 60, a 

checkpoint is recorded at the specified frequency, in minutes. 

To specify a CHECKPOINT frequency of more than 60, Teradata TPump 

terminates the job. 

Specifying a CHECKPOINT frequency of zero bypasses all checkpoint 

functions. Teradata TPump does not do checkpoint operations at all, 

which is different from Teradata Tools and Utilities 07.00 and earlier. 

The Teradata TPump job will not be re-startable once data loading has 

begun. 

If a CHECKPOINT frequency is not specified, check pointing occurs 

every 15 minutes by default. 

Whether specified or not, checkpoints are written at the end of each 

data input source. 

Note: Checkpoints should not be set for an FDL-compatible INMOD 

routine with the FOR, FROM, or THRU options. When an 

FDL-compatible INMOD routine is used with the FOR, FROM, or 

THRU options, Teradata TPump terminates and an error message 

appears if the checkpoint frequency is other than zero. 

Keyword to encrypt import data and the request text during the 

communication between Teradata TPump and Teradata Database. 

If ON, the encryption will be performed. If DATAENCRYPTION is not 

specified, the default is OFF. 

The "-y" runtime parameter applies the encryption to all connected 

sessions, which include the control session and the load sessions. This 

option only applies the encryption to the load sessions, which are the 

sessions specified by the SESSIONS keyword in the BEGIN LOAD 

command, and overrides the "-y" runtime parameter when OFF is 

explicitly specified. For example, assuming the PARTITION command 

is not used in the job, when "-y" runtime parameter is specified with the 

job and DATAENCRYPTION OFF is specified in the script, the 

encryption will only apply to the control session. Similarly, assuming 

the PARTITION command is not used in the job when "-y" runtime 

parameter is not specified with the job, and DATAENCRYPTION ON is 

specified in the script, the encryption will apply to all load sessions but 

not the control session. 

When the PARTITION command is used, the encryption setting 

explicitly specified in the PARTITION command will override the 

setting of this option over the sessions defined by the PARTITION 

command. 



BEGIN LOAD 


ArraySupport 

ON/OFF 

TENACITY 

hours 

Description 

“ArraySupport ON|OFF” option to the .BEGIN LOAD command and 

the .DML command. 

When “ArraySupport ON” is specified in the .BEGIN LOAD command, 

the .DML commands enclosed in .BEGIN LOAD and .END LOAD 

command pair will use the ArraySupport feature for its DML statement, 

unless “ArraySupport OFF” is specified for the .DML command. The 

default value of ArraySupport for the .BEGIN LOAD command is OFF. 

When “ArraySupport ON|OFF” is not specified with the .DML 

command, the default value for ArraySupport for that .DML command 

is the effective setting of ArraySupport in the .BEGIN LOAD command 

where the .DML command resides. When “ArraySupport ON|OFF” is 

specified at the .DML command, the specified value overrides the 

default setting determined by the .BEGIN LOAD command. 

When a .DML command is using the ArraySupport feature, it must 

contain one and only one DML statement, and the session partition that 

the .DML command references needs to be used by this .DML 

command exclusively. 

If the DML statement is an UPSERT-type statement, it can be specified 

as a pair of INSERT/UPDATE statements with DO INSERT FOR 

MISSING UPDATE clause. Teradata TPump will create its equivalent 

form of UPDATE … ELSE INSERT …, example Atomic Upsert, and use 

it as the actual DML statement. Or an UPDATE … ELSE INSERT … 

statement can be directly specified with DO INSERT FOR MISSING 

UPDATE clause. 

The non-atomic form of UPSERT is not supported by Teradata TPump 

Array Support. 

Keyword (with hours parameter) defining how long the utility tries to 

log on the sessions needed to perform the Teradata TPump job. 

If a logon is denied, Teradata TPump delays for the time specified by the 

SLEEP parameter (the default is six minutes) and retries the logon. It 

retries until either the logon succeeds or the number of hours specified 

by TENACITY is exceeded. 

If the TENACITY parameter is not specified, the utility retries the 

logons for four hours. 

Teradata TPump tenacity factor, as an integral number of hours. 

Specifies how long Teradata TPump keeps trying to logon to the 

required sessions. 

The default value for hours is 4 if the parameter is not specified. If hours 

is specified as 0, Teradata TPump does not retry logons after a logon 

fails because of a capacity limit. 

When a “no more sessions” error appears (either a 301 return code from 

a workstation CLI or a 513 return code from a mainframe CLI), 

Teradata TPump drops the sessions already acquired, and terminates the 

job without trying another logon. 



BEGIN LOAD 


LATENCY 

seconds 

NOTIMERPROCESS 

minutes 

SERIALIZE ON/OFF 

PACKMAXIMUM 

Description 

Keyword for flushing stale buffers. 

Note: When using the Teradata TPump latency option with Named 

Pipe Access Module, need_full_block = no option should be added in the 

Named Pipe Access Module initialization string. 

Flushing threshold based on number of seconds oldest record has 

resided in buffer. 

LATENCY cannot be less than one second. 

If the SERIALIZE parameter is set to OFF, only the current buffer can 

possibly be stale. If SERIALIZE is ON, the number of stale buffers can 

range from zero to the number of sessions. 

Keyword to tell Teradata TPump not to fork a child process as a timer 

process. 

When a child process is forked, the SIGUSR2 signal notifies the parent 

process when the latency period expires. When a child process is not 

forked, the SIGALRM signal notifies the Teradata TPump process when 

the latency period expires. A child process is necessary for the latency 

function to work properly on the UNIX platforms when the MQSeries 

Access Module is used. 

Number of minutes to wait between unsuccessful logon attempts due to 

session limits errors on Teradata Database or CLIv2. 

If SLEEP is not specified, the default between unsuccessful logon 

attempts is 6 minutes. 

Keyword to set the state (ON/OFF) of the serialization feature which, if 

ON, guarantees that operations on a given key combination (row) occur 

serially. 

If SERIALIZE is not specified, the default is OFF. 

This feature is meaningful only when a primary key for the loaded data 

is specified by using the KEY option of the FIELD command. 

Serialization must be set to OFF if the .TABLE command is used and the 

target table is a NoPI table. 

To ensure data integrity, the SERIALIZE parameter defaults to ON in 

the absence of an explicit value if there are upserts in a Teradata TPump 

job. 

Keyword requesting Teradata TPump to dynamically determine the 

maximum possible PACK factor for the current load. 

Maximum value is 2430. 

Displayed in message UTY6652, the value thus determined should be 

specifically used on subsequent runs, as the use of PACKMAXIMUM 

requires iterative interactions with the database during initialization to 

heuristically determine the maximum possible PACK factor. 

Note: Since the maximum packing factor has changed from 600 to 

2430, it will take a longer time for Teradata TPump to test the packing 

factor if PACKMAXIMUM is specified. 



BEGIN LOAD 


PACK 

statements 

RATE 

RETRYTIMES nn 

Description 

Keyword for the number of statements to pack into a multiplestatement 

request. 


Packing improves network/channel efficiency by reducing the number 

of sends and receives between the application and Teradata Database. 

Number of statements, as a positive integer of up to 2430, to pack into a 

multiple-statement request. 

Default value is 20 statements per request. 

Under certain conditions, Teradata TPump may determine that the pack 

factor has been set too high. Teradata TPump then automatically lowers 

the pack setting to an appropriate value and issues warning message 

UTY6625, for instance: 

“UTY6625 WARNING: Packing has been changed to 12 statements per 

request” and continues. 

Packing improves network/channel efficiency by reducing the number 

of sends/receives between the application and the database. 

The packing factor is validated by sending a fully packed request to 

Teradata Database using a prepare. This test checks for syntax problems 

and requests that are excessively large and may overwhelm the parser. 

To simplify the script development process, Teradata TPump ignores 

certain errors returned by an overloaded parser, shrinks the request, 

retries the prepare until it executes successfully and finally, issues a 

warning noting the revised packing factor size. 

When this happens, the Teradata TPump script should be modified to 

eliminate the warning, thereby avoiding the time-consuming process of 

shrinking the request. 

A packing failure may occur if the source parcel length does not match 

the data defined. If this happens, Teradata TPump issues the message: 

“UTY2819 WARNING: Packing may fail because input data does not 

match with the data defined.” 

To resolve this problem, increase the packing factor and resubmit the 

job. 

Keyword for entering the rate at which statements are sent to Teradata 


Keyword for retry times number of retry times. 

Default is 16. 

If nn equals 0, the retry times will be set to 16. If retrytimes is set, this 

only takes effect for the requests/data between "BEGIN LOAD" and 

"END LOAD" pair. 



BEGIN LOAD 


statement_rate 

Description 

Initial maximum rate at which statements are sent to Teradata Database 

per minute. 

The statement rate must be a positive integer. If the statement rate is 

unspecified, the rate is unlimited. 

If the statement_ rate is less than the statement packing factor, Teradata 

TPump sends requests smaller than the packing factor. 

If the Teradata TPump Monitor is in use, the statement_rate can be 

changed later on. 

SLEEP 

NOATOMICUPSERT 

NOMONITOR 

ROBUST ON/OFF 

Keyword for the number of minutes to sleep. 

Keyword to perform non-atomic upsert operations for UPSERT DMLs 

in the job script if these UPSERT DMLs are not provided in the Atomic 

UPSERT form. 

Keyword to prevent Teradata TPump from checking for statement rate 

changes from, or update status information for, the Teradata TPump 

Monitor. 

The ON parameter ensures data integrity when target tables have 

identity columns. 

The OFF parameter signals Teradata TPump to use simple restart logic. 

In this case, restarts cause Teradata TPump to begin where the last 

checkpoint occurred in a job. Any processing that occurred after the 

checkpoint is redone. This method does not have the extra overhead of 

the additional database writes in the Robust logic. 

Caution: Certain errors may cause reprocessing, resulting in extra 

error table rows due to reexecuting statements (attempting to 

re-insert rows, for example). Or, if the target table allows 

duplicate rows, reexecuting statements may cause extra 

duplicate rows to be inserted into the target table instead of 

causing extra error table rows. 

Simple logic is adequate in certain DML statements that can be repeated 

without changing the results of the operation. Examples of statements 

that are not simple logic include the following: 

• INSERTs into tables that allow duplicate rows (MULTISET tables). 

• Self-referencing DML statements such as: 

• “UPDATE FOO SET A=A+1...” 

• “UPDATE FOO SET A = 3 WHERE A=4” 

MACRODB 

dbname 

Keyword for database to contain any macros used by Teradata TPump. 

Name of database which is to contain any macros built/used by Teradata 


This database overrides the default placement of macros into the 

database which contains the log restart table. 



BEGIN LOAD 


NOTIFY 

EXIT name 

TEXT 'string' 

MSG 'string' 

Description 

Teradata TPump implementation of the notify user exit option: 

• NOTIFY OFF suppresses the notify user exit option. 

• NOTIFY LOW enables the notify user exit option for those events 

signified by “Yes” in the Low Notification Level column of Table 26. 

• NOTIFY MEDIUM enables the notify user exit option for the most 

significant events, as specified by “Yes” in the Medium Notification 

Level column of Table 26. 

• NOTIFY HIGH enables the notify user exit option for every Teradata 

TPump event that involves an operational decision point, as 

specified by “Yes” in the High Notification Level column of Table 26. 

• NOTIFY ULTRA enables the notify user exit option for every 

Teradata TPump event that involves an operational decision point, as 

specified by “Yes” in the ULTRA Notification Level column of 

Table 26. 

Keyword phrase that calls a user-defined exit where name is the name of 

a user-supplied library with a member name of _dynamn. 

The default library names are: 

• NOTFYEXT for channel-attached z/OS client systems 

• libnotfyext.so for network-attached UNIX and Windows client 

systems 

The exit must be written in C, or in a language with a runtime 

environment that is compatible with C. 

On some versions of UNIX, ./prefix characters may have to be added to 

the EXIT name specification if the module is in the current directory. 

User-supplied string of up to 80 characters that Teradata TPump passes 

to the named exit routine. 

The string specification must be enclosed in single quote characters ('). 

User-supplied string of up to 16 characters that Teradata TPump logs to: 

• The operator’s console for channel-attached z/OS client systems 

• The system log for network-attached UNIX and Windows client 

systems 

The string specification must be enclosed in single quote characters ('). 

Table 26 lists events that create notifications. 

Table 26: Events that Create Notifications 

Notification Level 

Event Low Medium High Ultra Signifies 

Checkpoint Begin No No Yes Yes Teradata TPump started a 

checkpoint. 



BEGIN LOAD 

Table 26: Events that Create Notifications (continued) 

Notification Level 

Checkpoint End No No Yes Yes Teradata TPump successfully 

completed a checkpoint. 

CLIv2 Error Yes Yes Yes Yes Teradata TPump received a CLIv2 

error. 

Database Error Yes Yes Yes Yes A Teradata Database error that 

terminates Teradata TPump. 

DML Error No No Yes Yes Teradata TPump is about to log a 

DML error to the error table. 

Error Table No No Yes Yes Successful processing of the SEL 

COUNT(*) request for the error 

table. 

Exit Yes Yes Yes Yes Teradata TPump completed a load 

task. 

File or INMOD Open No No Yes Yes Successful processing of the 

IMPORT command. 

Import Begin No No Yes Yes Teradata TPump is about to start 

reading records. 

Import End No No Yes Yes Last record has been read. 

Initialize Yes Yes Yes Yes Successful processing of the Notify 

option (BEGIN LOAD command) 

Interim Run Statistics No No No Yes Teradata TPump is about to update 

the Monitor Interface table, or 

Teradata TPump successfully 

completed a checkpoint, or an 

Import has just completed 

successfully. 

Table Statistics No Yes Yes Yes Teradata TPump has successfully 

written the table statistics. 

Teradata Database 

Restart 

No Yes Yes Yes Teradata TPump received a crash 

error from Teradata or CLI. 

Usage Notes 

Multiple tables can be targeted by a single Teradata TPump job. 

If the script author is uncertain whether or not to use ROBUST restart logic, it is always safe to 

use the ROBUST ON parameter. 

To ensure data integrity, the SERIALIZE parameter defaults to ON in the absence of an 

explicit value if there are upserts in the Teradata TPump job. 

The statement rate per minute you set using the RATE keyword is also affected by the 

periodicity value. By default, Teradata TPump uses a periodicity value of four when enforcing 



BEGIN LOAD 

the statement rate limit. You can adjust the periodicity rate from 1 to 2430 using a run-time 

parameter. 

For example, if you set the statement rate at 1600 and the periodicity at 10, then the maximum 

number of statements processed is 160 (1600/10) statements every 6 (60/10) seconds. 

Caution: 

A LOGOFF command entered after a BEGIN and before the matching END LOAD logs you 

off the Teradata TPump utility. 



DATABASE 

DATABASE 

Purpose 

Teradata TPump supports the Teradata SQL DATABASE statement, which changes the default 

database qualification for all unqualified DML and DDL statements. 

Syntax 

DATABASE database 

; 

3021A020 

where 


database 

Description 

New qualified default database for the error table 

Changes the database from the one originally specified by the BEGIN 

LOAD command. 

Usage Notes 

The DATABASE command only affects native SQL commands. In particular, it has no effect 

on the BEGIN LOAD command. 

The DATABASE command does affect INSERT, UPDATE, DELETE, and EXEC statements 

issued as part of a load. (When Teradata TPump logs on sessions, it immediately issues a 

DATABASE statement on each session.) 

The DATABASE command does not affect the placement of Teradata TPump macros. 



DATEFORM 

DATEFORM 

Purpose 

The DATEFORM command lets you define the form of the DATE data type specifications for 

the Teradata TPump job. 

Syntax 

.DATEFORM 

INTEGERDATE 

ANSIDATE 

; 

3021A006 

where 


INTEGERDATE 

ANSIDATE 

Description 

Keyword that specifies integer DATE data types for the Teradata TPump 

job 

This is the default Teradata DATE data type specification for Teradata 

TPump jobs if you do not enter a DATEFORM command. 

Keyword that specifies ANSI fixed-length CHAR(10) DATE data types for 

the Teradata TPump job 

Usage Notes 

Table 27 describes the things to consider when using the DATEFORM command. 

Table 27: DATEFORM Command Usage Notes 

Topic 

Command Frequency 

and Placement 

Data Type Conversions 

Usage Notes 

• Only one DATEFORM command can be used. 

• The DATEFORM command must be entered before LOGON 

command. 

When the ANSIDATE specification is used, the ANSI/SQL DateTime data 

types must be converted to fixed-length CHAR data types when specifying 

the column/field names in the Teradata TPump FIELD command. 

See the Usage Notes subsection of the FIELD command for a description 

of the fixed-length CHAR representations for each DATE, TIME, 

TIMESTAMP, and INTERVAL data type specification. 



DATEFORM 

Table 27: DATEFORM Command Usage Notes (continued) 

Topic 

Release Applicability 

Usage Notes 

The ANSIDATE specification is valid for Teradata TPump jobs on Teradata 

Database for UNIX. 



DELETE 

DELETE 

Purpose 

Teradata TPump supports the DELETE Teradata SQL statement, which removes rows from a 

table. 

Syntax 

DELETE tname WHERE conditional 

; 

FROM 

HE05B032 

where 


tname 

WHERE 

condition 

Description 

Table from which rows are to be deleted 

tname is qualified either explicitly by database name, or by the current default 

database. 

Conditional clause identifying the row(s) to delete 

The conditional clause uses values from input data record fields as defined by a 

FIELD command or TABLE command of the layout referenced by an IMPORT 

using this statement. 

Usage Notes 

The following notes describe how to use DELETE statements following a DML command. 

A DELETE statement may also be used in the support environment; normal rules for DELETE 

are followed in that case. 

Teradata TPump operates only on single table statements so DELETE statements must not 

contain any joins. 

To delete records from a table, the username specified on the LOGON command must have 

DELETE privilege on the specified table. 

When the condition(s) of the DELETE statement WHERE clause are evaluated, the result can 

be definitely true, definitely false, or indeterminate. If the result is true for a specific row, 

Teradata TPump deletes the row. An indeterminate result, due to an abnormal arithmetic 



DELETE 

condition such as underflow, overflow, or division by zero, is treated as an error, and Teradata 

TPump records both row and error code in the error table. 

The DELETE statement must identify only one object. 

Remember the following when constructing scripts: 

• A DELETE statement can be applied to either a table or view, provided that the view does 

not specify a join. 

• Equality values for all the primary index columns should normally be specified in the 

WHERE clause. 

The OR construct can be used in the WHERE clause of a DELETE statement; alternatively, 

two or more separate DML statements (one per OR term) can be used, with the DML 

statements applied conditionally with the APPLY clause of the IMPORT command. The 

nature of the alternatives will usually make one of the methods more appropriate. 

• The column(s) specified in this clause need not be a part of any index, but can be one or 

more nonindexed columns. This clause may specify nonequality values for any 

combination of columns of unique indices, or any values for other columns. 

• The maximum number of INSERT, UPDATE, and DELETE statements that can be 

referenced in an IMPORT is 128. The 128th DML which would cause the insertion of the 

DML sequence number of 128 for the DMLSEQ field in the error table could lead to 

Teradata Database 3520 error. 

• The maximum number of DML statements that can be packed into a request is 2430. The 

default number of statements packed is 20. 

DML validtime qualifier and NONTEMPORAL semantics are supported. For more 

information, see SQL Data Manipulation Language and SQL Data Manipulation Language 

Advanced Topics. 

Example 

The following example uses an input data source containing a series of one-field, four-byte 

records. Each record contains the value (EmpNum) of the primary index column (EmpNo) of 

a row to be deleted from the Employee table. 

.BEGIN LOAD SESSION number; 

.LAYOUT Layoutname; 

.FIELD EmpNum 1 INTEGER; 

.DML LABEL DMLlabelname; 

DELETE Employee WHERE EmpNo = :EmpNum; 

.IMPORT INFILE Infilename LAYOUT Layoutname APPLY DMLlabelname; 

.END LOAD; 



DISPLAY 

DISPLAY 

Purpose 

The DISPLAY command can be used to write messages to the specified destination. 

Syntax 

DISPLAY 

'text' 

FILE 

fileid 

; 

TO 

3021A021 

where 


'text' 

fileid 

Description 

Text to be written to the specified output destination 

Data source of the external system. 

The external system DD (or similar) statement specifies a file. 


infilename (the path name for a file) 

If the path name has embedded white space characters, enclose the 

entire path name in single or double quotes. 

z/OS 


If DDNAME is specified, Teradata TPump reads data records from 

the specified source. 

A DDNAME must obey the same rules for its construction as 

Teradata SQL column names, except that: 



A DDNAME must obey the applicable rules of the external system. 

If DDNAME represents a data source on magnetic tape, the tape 

may be either labelled or nonlabelled (if the operating system 

supports it). 



DISPLAY 

Usage Notes 

Utility variables are replaced by their values before text is displayed. This is done by preceding 

the variable name with an ampersand (&). To display the name of a utility variable, code two 

“&”s instead of one. 

To display an apostrophe within the text string, two consecutive apostrophes (single quotes) 

must be used to distinguish it from both the single quotes enclosing the string and a regular 

double quote. 

In UNIX-based systems, if outfilename is used to redirect stdout as well as the file in a 

DISPLAY command, the results written to outfilename may be incomplete due to conflicting 

writes to the same file. 

On UNIX systems, use an asterisk (*) as the fileid specification to direct the display messages 

to the system console/standard output (stdout) device. The system console is the: 

• Display screen in interactive mode 

• Standard output device in batch mode 



DML 

DML 

Purpose 

The DML command defines a label and error treatment options for one or more immediately 

following DML statements. DML statements relevant to a Teradata TPump job are INSERT, 

UPDATE, DELETE, and EXECUTE, with UPDATE and INSERT statements sometimes paired 

to form either a basic upsert or an Atomic upsert operation. 

Syntax 

.DML 

LABEL 

label 

A 

A ; 

MARK DUPLICATE 

ROWS 

IGNORE 

INSERT 

UPDATE 

MISSING 

UPDATE 

DELETE 

EXTRA 

UPDATE 

DELETE 

DO INSERT FOR 

MISSING UPDATE 

, 

SERIALIZEON ( serialize_on_field 

, 

) 

USE ( use_field ) 

PARTITION 

ARRAYSUPPORT 

partition_name 

OFF 

ON 

3021E007 

where 


LABEL 

Description 

Keyword indicating that the following parameter is a label for the DML 

statements that follow 



DML 


label 

MARK 

Description 

Unique label is to be used for the immediately following set of one or more 

DML statements 

A label must obey the same rules for its construction as Teradata SQL column 

names. 

The label name may be referenced in the APPLY clause of an IMPORT 

command. 

Keyword indicating that the system should make a duplicate, missing, or extra 

INSERT, UPDATE, or DELETE row entry in the error table and continue 

processing. 

A row is a duplicate row if all column values in the row are the exact duplicate 

of another row. Duplicate row checking is bypassed if the table is a multiset 

table (which allows duplicate rows), or if the table has one or more unique 

indexes (the uniqueness test(s) make any duplicate row check unnecessary). 

If MARK is set and a uniqueness violation occurs on either a unique primary 

index or a unique secondary index, the offending rows go to the error table, 

whether or not the row is a duplicate row. In the case of an upsert, both the 

INSERT and UPDATE portions must fail for an error to be recorded. 

If neither MARK or IGNORE is specified for duplicate rows, MARK applies to 

both INSERTs and UPDATEs. Similarly, if neither MARK or IGNORE is 

specified for missing or extra rows, MARK applies to both UPDATEs and 

DELETEs. 

MARK is the default for: 

• Both UPDATEs and DELETEs that refer to missing or extra rows. 

• Duplicate rows arising from both INSERTs and UPDATEs, except when 

those statements are combined to form an upsert, in which case the default 

is IGNORE. 

IGNORE 

keyword indicating that the system should not make an error table entry for 

the duplicate, missing, or extra INSERT, UPDATE, or DELETE row 

The system should continue processing instead. 

A row is a duplicate row if all column values in the row are the exact duplicate 

of another row. Duplicate row checking is bypassed if the table is a multiset 

table (which allows duplicate rows), or if the table has one or more unique 

indexes (the uniqueness test(s) make any duplicate row check unnecessary); in 

these cases, IGNORE DUPLICATE ROWS has no effect. Any uniqueness 

violations will result in the offending rows going to the error table. 

If neither INSERT nor UPDATE is specified for duplicate rows, IGNORE 

applies to both INSERTs and UPDATEs. 

Similarly, if neither UPDATE nor DELETE is specified for missing or extra 

rows, IGNORE applies to both UPDATEs and DELETEs. IGNORE is the 

default condition for an upsert operation. 

INSERT 

The upsert feature may be used (when used as DO INSERT FOR MISSING 

UPDATE ROWS or DO INSERT ROWS). 



DML 


Description 

An upsert saves time while loading a database. An upsert completes, in one 

pass, an operation which requires two passes for other utilities. The DML 

statements that follow this option must be in the order of a single UPDATE 

statement followed by a single INSERT statement. 

This option first executes the UPDATE statement. If the UPDATE fails because 

the target row does not exist, Teradata TPump automatically executes the 

INSERT statement. This capability allows updates to the database without first 

presorting the data. Otherwise, the data would have to be sorted into: 

• rows that need to be updated 

• rows that need to be inserted 

Further information on the usage and restrictions of the upsert feature 

appears in the following usage notes. 

PARTITION 


SERIALIZEON 

serialize_on_field 

USE 

use_field 

Optional keyword used to name a session partition to be used for all SQL 

requests associated with this DML command 

If this keyword is not present, a session created from the SESSIONS will be 

used. 

Note: If serialization of two or more DML statements is required, the 

statements cannot be put in different partitions. Serialization requires that all 

DML statements with identical hash values of the rows be submitted from the 

same session. 

Parameter identifying the partition name 

The partition name must obey the same rules for its construction as Teradata 

SQL column names. 

Keyword used to turn serialization on for the fields specified 

SERIALIZEON keyword may be used before, after, or between any IGNORE 

or MARK statements. 

Parameter identifying the field names where serialization is turned on 

This is the same field name used in the LAYOUT command which was used by 

the INSERT statement and referenced by the APPLY clause. 

Separate the field names with a comma and enclose them in parentheses. 

Keyword used to specify the fields that are to be used with a DML’s SQL 

statements 

Use of this keyword allows specification of the FIELDs from the LAYOUT 

command which are actually needed for each DML, so that data from all fields 

will not be sent.[ 

The USE keyword may be placed before, after, or between any IGNORE/ 

MARK statements. 

Parameter identifying the field names to use 

Every LAYOUT FIELD used by any of the DML’s SQL statements must be 

enumerated in the USE list; otherwise, an error will occur. 

Separate the field names with a comma and enclose them in parentheses. 



DML 


ArraySupport 

ON/OFF 

Description 

“ArraySupport ON|OFF” option to the .BEGIN LOAD command and the 

.DML command 

When “ArraySupport ON” is specified in the .BEGIN LOAD command, the 

.DML commands enclosed in .BEGIN LOAD and .END LOAD command pair 

will use the ArraySupport feature for its DML statement, unless “ArraySupport 

OFF” is specified for the .DML command. The default value of ArraySupport 

for the .BEGIN LOAD command is OFF. 

When “ArraySupport ON|OFF” is not specified with the .DML command, the 

default value for ArraySupport for that .DML command is the effective setting 

of ArraySupport in the .BEGIN LOAD command where the .DML command 

resides. When “ArraySupport ON|OFF” is specified at the .DML command, 

the specified value overrides the default setting determined by the .BEGIN 

LOAD command. 

When a .DML command is using the ArraySupport feature, it must contain 

one and only one DML statement and the session partition that the .DML 

command references needs to be used exclusively by this .DML command. 

If the DML statement is an UPSERT-type statement, it can be specified as a 

pair of INSERT/UPDATE statements with DO INSERT FOR MISSING 

UPDATE clause. Teradata TPump will create its equivalent form of UPDATE 

… ELSE INSERT …, example Atomic Upsert, and use it as the actual DML 

statement. Or an UPDATE … ELSE INSERT … statement can be directly 

specified with DO INSERT FOR MISSING UPDATE clause. 

The non-atomic form of UPSERT is not supported by Teradata TPump Array 

Support. 

Usage Notes 

The SQL EXECUTE command must be used between the BEGIN LOAD command and the 

END LOAD command. 

All INSERT, UPDATE, DELETE, and EXECUTE statements specified in the Teradata TPump 

script should fully specify the primary index of the referenced table to prevent the generation 

of table-level locks. 

A maximum of 2430 DML statements may be packed into a request; the default is 

20 statements. 

Teradata TPump assumes that row hash locking is used by INSERT, UPDATE, DELETE, and 

EXECUTE statements. If row hash locking is not used, Teradata TPump will run anyway, but 

may encounter trouble because table-level locking will cause each statement to block. 

In addition, Teradata TPump does not support UPDATE or EXECUTE statements that 

modify the primary index of the target table. Teradata TPump performs no checking to 

prevent the script author from creating DML that requests unreasonable updates, except that 

Teradata TPump will not use Atomic UPSERT if the UPDATE portion of the UPSERT 

specifies an unreasonable update. This restriction is imposed by Teradata Database. 

IGNORE DUPLICATE ROWS does not apply if there are ANY unique indexes in the row. 



DML 

Sample Scripts 

Teradata TPump converts INSERT, UPDATE, and DELETE statements into macro 

equivalents, and, depending on the packing specified, submits multiple statements in one 

request. Teradata TPump also supports the EXECUTE statement, which can be used to bypass 

the macro creation step for frequently executed macros. For more information on the 

EXECUTE statement, refer to EXECUTE in this chapter. 

The maximum number of INSERT, UPDATE, and DELETE statements that can be referenced 

in an IMPORT is 128. The 128th DML which would cause the insertion of the DML sequence 

number of 128 for the DMLSEQ field in the error table could lead to Teradata Database 3520 

error. 

At the end of an IMPORT, an environmental variable is established for each DML command 

executed. Teradata TPump variables are not limited to 30 characters. These variables contain 

the activity counts associated with each statement. The variables created are of the form: 

&IMP __ 

where 

n = the number of the IMPORT, from one through four. 

Apply label = the label of the clause containing the DML command in question. 

x = the number of the statement within the containing APPLY clause. 

Serialization 

The SERIALIZEON keyword allows serialization to be turned on for the specified fields. The 

SERIALIZEON keyword can be used before, after, or between any IGNORE or MARK 

statements. 

The SERIALIZEON keyword can also be used with the SERIALIZE keyword in the BEGIN 

LOAD command and with the KEY keyword in the FIELD command. When it is used in this 

way, the DML-level serialization ignores and overrides the BEGIN LOAD-level serialization. 

In addition, the DML serialized APPLYs can be mixed with nonserialized DML APPLYs in the 

same IMPORT command. 

See “BEGIN LOAD” and “FIELD” for details about these commands. 

The following is an example using the SERIALIZEON keyword: 


.LOGON slugger/dbc,dbc; 

.BEGIN LOAD 

ERRLIMIT 100 50 

CHECKPOINT 15 

SESSIONS 20 

TENACITY 2 


PACK 30 

ROBUST ON 

NOMONITOR; 

.LAYOUT LAY01; 



DML 

.FIELD cc1 * CHAR(8); 




.DML LABEL LABEL01 


SERIALIZEON (CC1); 

UPDATE TPTBL01 

SET C4 = :CC4 

WHERE C1 = :CC1; 

INSERT TPTBL01 (C1, C2, C4) 

VALUES (:CC1,:CC2, CC4); 

UPDATE TPTBL02 SET C4 = :CC4 WHERE C1 = :CC1 

AND C2 = :CC2; 

INSERT TPTBL02 (C1, C2, C3, C4) 

VALUES (:CC1,:CC2,:CC3, :CC4); 

.IMPORT INFILE .\TPDAT.txt FORMAT TEXT 

LAYOUT LAY01 

APPLY LABEL01 


.END LOAD; 

.LOGOFF; 

The following is an example using the USE keyword: 


.LOGON slugger/cfl,cfl; 

DROP TABLE TPERR01; 

DROP TABLE TPTBL01; 



CREATE TABLE TPTBL01( 

C1 INTEGER, 

C2 VARCHAR(30), 




C6 VARCHAR(30)) 

UNIQUE PRIMARY INDEX (C1); 


C1 INTEGER, 







C1 INTEGER, 








DML 






.BEGIN LOAD 

CHECKPOINT 15 

SESSIONS 5 


NOMONITOR; 


.FIELD FLD1 * VARCHAR(10); 











.DML LABEL LABEL01 USE(FLD1, FLD2, FLD4, FLD6, FLD8, FLD10); 

INSERT TPTBL01 (C1, C2, C3, C4, C5, C6) 

VALUES (:FLD1,:FLD2,:FLD4,:FLD6,:FLD8,:FLD10); 

.DML LABEL LABEL02 USE(FLD1, FLD3, FLD5, FLD7, FLD11); 

INSERT TPTBL02 (C1, C2, C3, C4, C5) 

VALUES (:FLD1,:FLD3,:FLD5,:FLD7,:FLD11); 

.DML LABEL LABEL03; 

INSERT TPTBL03 (C1, C2, C3, C4, C5, C6, C7, C8, C10, C11) 

VALUES (:FLD1, :FLD2, :FLD3, :FLD4, :FLD5, 

:FLD6, :FLD7, :FLD8, :FLD10, :FLD11); 

.IMPORT INFILE INDATA FORMAT VARTEXT ',' 

LAYOUT LAY01 

APPLY LABEL01 WHERE FLD9 = 'A' 

APPLY LABEL02 WHERE FLD9 = 'B' 


.VERSION; 

.END LOAD; 

.LOGOFF; 

Note that as in the above example, DML USE APPLYs can be mixed with DML APPLYs not 

using the USE keyword within the same IMPORT. 

The following is an example using partitioning: 


.LOGON cs4400s3/cfl,cfl; 




DML 



CREATE TABLE TPTBL01, FALLBACK( 

C1 CHAR(12) not null, 

C2 CHAR(8) not null) 

PRIMARY INDEX (C1); 


C1 CHAR(12), 

C2 CHAR(8), 

C3 CHAR(6)) 


.BEGIN LOAD 


CHECKPOINT 15 

TENACITY 2 


ROBUST off 

serialize on 

; 


.FIELD cc1 * CHAR(12) key; 



.filler space1 * char(1); 

.partition part1 pack 10 sessions 10; 

.partition part2 sessions 5 1 packmaximum; 

.DML LABEL LABEL01 partition part1 

DO INSERT FOR MISSING ROWS 

ignore extra update rows 

use(cc1, cc2); 


SET C2 = :CC2 


INSERT TPTBL01 (C1, C2) 

VALUES (:CC1,:CC2); 


serializeon( cc1 ) 


DO INSERT FOR MISSING UPDATE ROWS; 

UPDATE TPTBL02 SET C2 = :CC2 WHERE C1 = :CC1; 


VALUES (:CC1,:CC2,:CC3); 

.IMPORT INFILE c:\NCR\Test\TpumpData001.txt FORMAT TEXT 

LAYOUT LAY02 

APPLY LABEL01 

APPLY LABEL02 where CC2 = '00000001'; 

.END LOAD; 

.LOGOFF; 



DML 

The Basic Upsert Feature 

Example Upsert 

When using the basic upsert feature: 

• There must be exactly two DML statements in this DML group. 

• The first DML statement must be an UPDATE statement that follows all of the Teradata 

TPump task rules. 

• The second DML statement must be an INSERT statement. 

• Both DML statements must refer to the same table. 

• The INSERT statement, when built, must reflect the same primary index specified in the 

WHERE clause of the UPDATE statement. This is true for both a single column primary 

index and a compound primary index. 

By following these rules, a number of uses for the DO INSERT ROWS option can be found. In 

the past, data could be presorted into INSERTs and UPDATEs, or UPDATEs attempted with 

all the data, and then do an INSERT on any UPDATEs that failed. With upsert, Teradata 

TPump needs only one pass of the data to UPDATE rows that need to be updated and INSERT 

rows that need to be inserted. 

Note: To ensure data integrity, the SERIALIZE parameter defaults to ON in the absence of an 


When MARK MISSING UPDATE ROWS specified, while using DO INSERT ROWS, Teradata 

TPump records any UPDATE that fails. This record appears in the Application Error Table, 

together with an error code that shows that the INSERT of the DO INSERT ROWS was then 

executed. If the INSERT fails, the INSERT row is also recorded in the Application Error table. 

The default for an upsert function, however, is not to mark missing update rows. This is 

because when the upsert function is performed, the INSERT is expected to occur when the 

UPDATE fails. The failure of the UPDATE portion of an upsert does not, in itself, constitute 

an error and should not be treated as one. 

The MARK MISSING DELETE ROW option has no meaning when used with the DO 

INSERT ROWS option. 

The option of MARK (IGNORE) EXTRA DELETE (UPDATE) ROWS provides Teradata 

TPump with a way to protect against an update or delete affecting multiple rows, which can 

happen in Teradata TPump because the primary index can be non-unique. 

MARK is the default for all DML options, except for an upsert. 

Each record in the following example contains the value of the primary index column 

(EmpNo) of a row of the Employee table whose PhoneNo column is to be assigned a new 

phone number from field Fone. 

When the UPDATE fails, the INSERT statement is activated and Teradata TPump enters the 

upsert mode. In this case, each record contains the primary index value (EmpNum) of a row 

that is to be inserted successively into the Employee table whose columns are EmpNo and 

PhoneNo. 



DML 

.BEGINLOAD SESSION number; 



.FIELD Fone * (CHAR (10)); 

.DML LABEL DMLlabelname 


UPDATE Employee SET PhoneNo = :Fone WHERE EmpNo = :EmpNum; 

INSERT Employee (EmpNo, PhoneNo) VALUES (:EmpNum, :Fone); 


.END LOAD; 

The scope of a DML command (and its label) terminates at the first following command of 

any kind or at the end of the file containing the DML statements, whichever occurs first. 

The SQL EXECUTE command must be between the BEGIN LOAD command and END 

LOAD command. 

For IMPORT tasks, up to seven distinct error treatment options for one DML command may 

be specified. For example: 

.DML LABEL COMPLEX 

IGNORE DUPLICATE INSERT ROWS 

MARK DUPLICATE UPDATE ROWS 

IGNORE MISSING UPDATE ROWS 

MARK MISSING DELETE ROWS 


It is valid to specify that missing update rows be both marked and treated as INSERTs or, as in 

the example, both ignored and treated as INSERTs. 

If Teradata TPump encounters any of the following: 

• no DML command in an IMPORT task, 

• DML statements outside the scope of a DML command in an IMPORT task, or 

• a DML command with no DML statements in an IMPORT task, 

it writes a diagnostic message to the primary output destination for the system, terminates the 

Teradata TPump task, and returns to the main Teradata TPump control module with a 

conventional nonzero return code. The error can be corrected and resubmitted to the Teradata 

TPump task. 

The DML commands (with their following DML statements) must appear between the 

appropriate BEGIN LOAD command and the IMPORT commands that refer to them. When 

the END LOAD command is encountered, the sequence of DML commands and DML 

statements is forgotten. The DML command cannot be shared by multiple BEGIN LOAD 

statements. The DML statements are described in the following sections. 

The maximum number of DML commands that can be used in a single Teradata TPump task 

is 128. If an excessive number of DML commands and statements are sent to Teradata 

Database, an error message is logged, stating that there are too many DML steps for one 

Teradata TPump job. 



DML 

The Atomic Upsert Feature 

The basic upsert function has been enhanced to support an Atomic upsert capability. This 

enhancement permits Teradata TPump to perform single-row upserts in a single pass. This 

one-pass logic adopts the upsert-handling technique used by MultiLoad. The one-pass logic is 

designated Atomic to distinguish the grouping of paired UPDATE and INSERT statements 

which are executed as a single SQL statement. 

The syntax for Atomic upsert consists of an UPDATE statement and an INSERT statement, 

separated by an ELSE keyword. 

Existing Teradata TPump scripts using the Atomic upsert form do not have to be changed. 

Teradata TPump will automatically convert the old UPDATE/INSERT pairs to the Atomic 

upsert feature whenever appropriate. Any attempts to change this will result in a syntax error. 

The new syntax, which can also be used by CLIv2 and BTEQ applications, is dependent on 

whether or not the database version, against which the Teradata TPump job is run, supports 

this feature. If the database does not support Atomic Upsert, Teradata TPump reverts to the 

earlier logic of sending the INSERT request if an UPDATE request fails. 

The three basic constraints on the upsert feature are: 

• SAME TABLE: The UPDATE and INSERT statements must specify the same table. 

• SAME ROW: The UPDATE and INSERT statements must specify the same row; that is, the 

primary index value in the INSERT row must be the same as the primary value in the 

targeted UPDATE row. 

• HASHED ROW ACCESS: The UPDATE fully specifies the primary index, allowing the 

target row to be accessed with a one-AMP hashed operation. 

Although Teradata TPump does not verify basic upsert constraints, Teradata Database will 

reject Atomic upsert constructs that fail the constraint test, and notify Teradata TPump by 

returning an appropriate error message to the client. 

If the Atomic Upsert is done on a Temporal table, the optional Temporal qualifier can only be 

added before the UPDATE statement. 

Other Restrictions on Atomic Upsert Feature 

Some of these restrictions concern syntax that is supported in UPDATE and INSERT 

statements separately, but not when combined in an Atomic upsert statement. Other 

restrictions concern the upsert feature's not supporting certain Teradata Database features 

such as triggers and join/hash indexes, meaning that the upsert statement cannot be used on 

any table utilizing those features. 

The following restrictions are not supported by the Atomic upsert feature, and return an error 

if submitted to Teradata Database: 

• INSERT … SELECT: Syntax not supported. The INSERT may not use a subquery to 

specify any of the inserted values. Note that support of this syntax is likely to be linked to 

support of subqueries in the UPDATE's WHERE clause constraints as described above, 

and may involve new syntax features to allow the UPDATE and INSERT to effectively 

reference the same subquery. 



DML 

• UPDATE-WHERE-CURRENT: Syntax not supported. The WHERE clause cannot use an 

updatable cursor to do what is called a positioned UPDATE. (It is unlikely that this syntax 

will ever be supported.) Note that this restriction does not prevent cursors from being 

used in other ways with Atomic upsert statements. For example, a DECLARE CURSOR 

statement may include upsert statements among those to be executed when the cursor is 

opened, as long as the upserts are otherwise valid. 

• UPDATE-FROM: Not supported. The SET clause cannot use a FROM clause table 

reference in the expression for the updated value for a column. 

• UPDATE-WHERE SUBQUERIES: Not supported. The WHERE clause cannot use a 

subquery either to specify the primary index or to constrain a nonindex column. Note that 

supporting this UPDATE syntax would also require support for either INSERT … SELECT 

or some other INSERT syntax feature that lets it specify the same primary index value as 

the UPDATE. 

• UPDATE-PRIMARY INDEX: Not supported. The UPDATE cannot change the primary 

index. This is sometimes called unreasonable update. 

• TRIGGERS: Feature not supported if either the UPDATE or INSERT could cause a trigger 

to be fired. The restriction applies as if the UPDATE and INSERT were both executed, 

because the parser trigger logic will not attempt to account for their conditional execution. 

UPDATE triggers on columns not referenced by the UPDATE clause, however, will never 

be fired by the upsert and are therefore permitted. DELETE triggers cannot be fired at all 

by an upsert and are likewise permitted. Note that an upsert could be used as a trigger 

action but it would be subject to the same constraints as any other upsert. Because an 

upsert is not allowed to fire any triggers itself, an upsert trigger action must not generate 

any further cascaded trigger actions. 

• JOIN/HASH INDEXES: Feature not supported if either the UPDATE or INSERT could 

cause the join/hash index to be updated. As with triggers, the restriction applies to each 

upsert as if the UPDATE and INSERT were both executed. While the UPDATE could 

escape this restriction if the join/hash index does not reference any of the updated 

columns, it is much less likely (and maybe impossible) for the INSERT to escape. If the 

benefit of lifting the restriction for a few unlikely join/hash index cases turns out to be not 

worth the implementation cost, the restriction may have to be applied more broadly to any 

table with an associated join/hash index. 

Treat the failed constraint as a nonfatal error, report the error in the job log for diagnostic 

purposes, and continue with the job by reverting to the old non-Atomic upsert protocol. 

Existing Teradata TPump Scripts 

Existing Teradata TPump scripts for upserts do not need to be changed. The syntax as 

described below for an upsert will continue to be supported: 


UPDATE ; 

INSERT ; 



DML 

Atomic Upsert Examples 

This section describes several examples that demonstrate how the Atomic upsert feature 

works, including cases where errors are detected and returned to the user. All of the examples 

use the same table, called Sales, as shown below: 

CREATE TABLE Sales, FALLBACK, 

(ItemNbr INTEGER NOT NULL, 

SaleDate DATE FORMAT 'MM/DD/YYYY' NOT NULL, 

ItemCount INTEGER) 

PRIMARY INDEX (ItemNbr); 

It is assumed that the table has been populated with the following data: 

INSERT INTO Sales (10, '05/30/2005', 1); 

Assume that there exists a table called NewSales that has the same column definitions as those 

of table Sales. 

Example 1 (Error: Different Target Tables) 

This example demonstrates an upsert statement that does not specify the same table name for 

the UPDATE part and the INSERT part of the statement. 

.Dml label upsertdml do insert for missing update rows; 

UPDATE Sales SET ItemCount = ItemCount + 1 WHERE (ItemNbr = 10 AND 

SaleDate = '05/30/2005'); 

INSERT INTO NewSales (10,'05/30/2005', 1); 

A rule of an upsert statement is that only one single table is processed for the statement. 

Because the tables, Sales and NewSales, are not the same for the upsert statement, an error is 

returned, indicating that the name of the table must be the same for both the UPDATE and 

the INSERT. 

Example 2 (Error: Different Target Rows) 

This example demonstrates an upsert statement that does not specify the same primary index 

value for the UPDATE part and the INSERT part of the statement. 

.Dml label upsertdml do insert for duplicate update rows; 


SaleDate = '05/30/2005'); 

INSERT INTO Sales (20,'05/30/2005', 1); 

The primary index values for the UPDATE and the INSERT must be the same. Otherwise, we 

would be looking at two different rows: one for UPDATE and the other for INSERT, which is 

not the purpose of an upsert. An error is returned for the upsert statement because the 

specified primary index values of 10 and 20 are not the same (the primary index value must be 

the same for both the UPDATE and the INSERT). 

Example 3 (Valid Upsert UPDATE) 

This example demonstrates a successful upsert statement where a row gets updated. 



SaleDate = '05/30/2005'); 




DML 

After all of the rules have been validated, the row with ItemNbr = 10 and SaleDate = '05/30/ 

2005' gets updated. A successful update of one row is returned. 

Example 4 (Valid Upsert INSERT) 

This example demonstrates a successful upsert statement where a row gets inserted. 



SaleDate = '05/30/2005') 


After all of the rules have been validated and no row was found with Item = 20 and SaleDate = 

'05/30/2005' for the UPDATE, a new row is inserted with ItemNbr = 20. A successful insert of 

one row is returned. 



END LOAD 

END LOAD 

Purpose 

The END LOAD command must be present as the last command of a Teradata TPump task to 

initiate the execution of the task. 

Syntax 

.END LOAD 

; 

3021A022 



EXECUTE 

EXECUTE 

Purpose 

Teradata TPump supports the Teradata SQL EXECUTE statement, which specifies a usercreated 

(predefined) macro for execution. The EXECUTE statement specifies the type of DML 

statement (INSERT, UPDATE, DELETE, or UPSERT) to be handled by the macro. 

The macro named in this EXECUTE statement must reside in Teradata Database before the 

import task starts. Only one DML statement (INSERT, UPDATE, DELETE, or UPSERT) can 

be specified in a Teradata TPump predefined macro. 

Caution: 

The SQL EXECUTE command must be used between the BEGIN LOAD command and the 

END LOAD command. 

Syntax 

EXECUTE name UPDATE/UPD 

; 

EXEC database. 

INSERT/INS 

DELETE/DEL 

UPSERT/UPS 

3021A001 

where 


database 

name 

DELETE/DEL 

INSERT/INS 

UPDATE/UPD 

UPSERT/UPS 

Description 

Name of the database in Teradata Database where the macro to be executed 

resides 

Name of the macro resident in Teradata Database to be executed 

Keyword indicating a DELETE statement is being executed by the macro 

Keyword indicating an INSERT statement is being executed by the macro 

Keyword indicating an UPDATE statement is being executed by the macro 

Keyword indicating an Atomic upsert is being executed by the macro 

Usage Notes 

Using predefined macros saves time because Teradata TPump does not need to create and 

drop new macros each time a Teradata TPump job script is run. 

The rules for user-created macros are: 



EXECUTE 

• Teradata TPump expects the parameter list for any macro to match the FIELD list specified 

by the LAYOUT in the script. FILLER fields are ignored. If the USE clause is used in the 

DML statement, Teradata TPump expects the parameter list for every macro in the DML 

statement to match the field list specified by the USE clause. The order should be the same 

as the fields in the LAYOUT. 

• The macro should specify a single prime index operation: INSERT, UPDATE, DELETE, or 

UPSERT. Teradata TPump reports an error if the macro contains more than one 

supported statement. 

• The restrictions on INSERT, UPDATE, DELETE, and UPSERT statements supported by 

Teradata TPump are described in the corresponding sections of this manual. 

If the EXECUTE statement is replacing an INSERT, UPDATE, DELETE, or UPSERT statement 

in a job script, the EXECUTE statement must be placed at the same location as the INSERT, 

UPDATE, DELETE, or UPSERT statement that it replaces. The following example shows an 

INSERT statement is replaced by an equivalent predefined macro: 

.DML LABEL LABELA; 

DELETE ; 

INSERT ; 

UPDATE ; 

.DML LABEL LABELA ; 

DELETE ; 

EXECUTE INSERT ; 

UPDATE ; 

The correct syntax for a Teradata TPump predefined macro is one of the following: 

• CREATE MACRO () as (UPDATE....; ) ; 

• CREATE MACRO () as (INSERT.....; ) ; 

• CREATE MACRO () as (DELETE.....; ) ; 

• CREATE MACRO () as (UPSERT.....; ) ; 

If a Teradata Database server supports Atomic upsert, then automatic use of Atomic upsert is 

allowed, when possible, without changing existing Teradata TPump scripts. This is 

accomplished in the following manner: 

• Teradata TPump attempts to use the Atomic upsert syntax in defining a single UPSERT 

macro (instead of an UPDATE/INSERT macro pair). 

• If the UPSERT macro is successfully defined, Teradata TPump uses the Atomic upsert 

function for the UPSERT. 

• If an error occurs during UPSERT macro definition, presumably due to a violation of 

Teradata Database Atomic upsert restrictions, Teradata TPump issues a warning and 

reverts to the current Teradata TPump upsert method of paired UPDATE/INSERT 

statements. 

Teradata TPump will continue to operate as it does now when the existing Teradata TPump 

syntax for upsert is encountered, and references to predefined macros are used for either the 

UPDATE or the INSERT or both. 



EXECUTE 

For example: 

.DML LABEL DO INSERT FOR MISSING UPDATE ROWS ... ; 

EXECUTE UPDATE ; 

INSERT ; 


UPDATE ; 



EXECUTE UPDATE ; 


To allow for the use of predefined macros that take advantage of Atomic upsert, Teradata 

TPump command syntax supports an UPSERT macro: 

.DML LABEL ; 

EXECUTE UPSERT ; 

When using predefined macros for atomic upserts, the DML statement will have “Ignore 

Missing Update Rows” as a default option. 

Atomic upsert syntax is not backward compatible; thus it cannot be used until the Teradata 

Database server is updated to a compatible release. If Teradata Database supports Atomic 

upsert, a Teradata TPump run can handle a mix of both standard and Atomic upserts. 

Upserts are reported as UPDATEs and INSERTs in the statistics displayed by Teradata TPump 

(and passed to the NOTIFY EXIT routine), because an Atomic upsert that results in an 

UPDATE will be reported by Teradata Database as an UPDATE activity type, and an Atomic 

upsert that results in an INSERT will be reported by Teradata Database as an INSERT activity 

type. 



FIELD 

FIELD 

Purpose 

The FIELD command specifies a field of the input record; it can also contain a NULLIF 

expression. All fields specified by FIELD commands are sent to Teradata Database. Only 

fields relevant to the tasks using this layout need be specified. 

Syntax 

.FIELD fieldname startpos datadesc 

A 

fieldexpr 

NULLIF nullexpr 

A 

DROP 

LEADING 

TRAILING 

BLANKS 

NULLS 

AND 

TRAILING 

LEADING 

NULLS 

BLANKS 

B ; 

KEY 

B 

3021A019 

where 


fieldname 

Description 

Name of an input record field to which: 

1 a DML statement refers, 

2 a nullexpr of a FIELD command or condition expression of a LAYOUT 

command refers, or 

3 a condition expression of the IMPORT command APPLY clause refers. 

A fieldname must obey the same rules for its construction as Teradata SQL 

column names. 

fieldname can be referenced in other FIELD commands via NULLIF and field 

concatenation expressions, and in APPLY WHERE conditions in IMPORT 

commands. 

startpos 

Starting position of a field of the data records in an external data source 

It may be specified as an unsigned integer which is a character position starting 

with 1, or as an asterisk which means the next available character position 

beyond the preceding field. Nothing prevents redefinition of positions of input 

records by specifying the same positions in multiple FIELD commands. See the 

example below. 

Note that where input records may be continued by use of the CONTINUEIF 

condition, a startpos specified as an unsigned integer refers to a character 

position in the final concatenated result from which the continuation indicator 

fields have been removed. Refer to the description of the condition parameter of 

the LAYOUT command. 



FIELD 


datadesc 

nullexpr 

nullexpr 

Continued 

Description 

Type and length of data in the field. 

Teradata TPump generates the USING phrase accordingly with the 

user-assigned field name to which the body of the DML statement refers. 

Condition used for selectively inserting a null value into the affected column 

The condition is specified as a conditional expression involving any number of 

fields, each represented by its fieldname, and constants. All fieldnames appearing 

in the conditional expression must be defined by any of the following 

specifications: 

1 The startpos and datadesc parameters of the FIELD command. 

2 A FILLER command. 

3 A TABLE command. 

If the specified condition is true, Teradata TPump sends the data to Teradata 

Database with indicators, whether or not the INDICATORS option is specified 

on the LAYOUT command. 

When the character set of the job script is different from the client character set 

used for the job (for example, on z/OS the job script must be in Teradata 

EBCDIC when using the UTF-8 client character set, or UTF-16 client character 

set can be used with the job script in UTF-8), Teradata TPump will translate the 

string constants specified in the expression and the import data referenced in 

the expression to the same character set before evaluating the expression. 

For example, when the client character set is UTF-16 and the script character 

set is UTF-8, if the following commands are given: 

.field C1 * varchar(20); 

.field C2 * varchar(40) nullif c1 = 'DELETED'; 

Teradata TPump will translate the data in the C1 field to the UTF-8 form and 

compare it with the UTF-8 form of 'DELETED' to obtain the evaluation result. 

Similarly, on the mainframe, when the client character set is UTF8 and the script 

character set is Teradata EBCDIC, if the following commands are given: 

.field C1 * char(20); 

.field C2 * rchar(40) nullif c1 = 'removed'; 

Teradata TPump will translate the data in the C1 field from the UTF8 form to 

the Teradata EBCDIC form and compare it to the Teradata EBCDIC form of 

'removed' to obtain the valuation result. 

Caution: When using UTF8 client set on the mainframe, be sure to examine 

the definition in International Character Set Support to determine the 

code points of the special characters which might be required. 

Different versions of EBCDIC do not always agree as to the 

placement of these characters. 

The mappings between Teradata EBCDIC and Unicode can be 

referred to in Appendix E of International Character Set Support. 

The fieldname1 parameter in other FIELD commands can be referenced in 

nullexpr. 



FIELD 


fieldexpr 

DROP 

KEY 

Description 

Concatenation of two or more items, either: 

• fields 

• character constants 

• string constants 

or a combination of these, as in: 

fieldname1||'C'||fieldname2||'STRING'||fieldname3... 

The field names within a layout must be unique and the data type of the field 

must be either CHAR or VARCHAR. Nested concatenations are not supported. 

If all items of the fieldexpr are fixed character (for example, no VARCHARs), the 

data type of the resulting field is CHAR(m), where “m” is the sum of the length 

for each component item. 

If at least one component of the fieldexpr is a VARCHAR, the data type of the 

resulting field is VARCHAR(m), where “m” is the sum of the maximum length 

for each component item. 



EBCDIC when using the UTF8 client character set, or UTF-16 client character 

set can be used with the job script in UTF8), Teradata TPump will translate the 

character constants and the string constants specified in the expression from the 

script character set form to the client character set form before concatenating 

the constants with the specified fields. 

Caution: When using the UTF8 client set on the mainframe, be sure to 

examine the definition in International Character Set Support to 

determine the code points of the special characters which might be 

require. Different versions of EBCDIC do not always agree as to the 




Characters present in the specified position(s) to be dropped from the specified 

fieldname, which must be of a character data type 

Teradata TPump drops the specified characters and presents the field to 

Teradata Database as a VARCHAR data type. 

If two dropping actions are specified, they must not be identical. 

If a FIELD command defines a fieldname in terms of two or more concatenated 

fieldname fields, any specified DROP clause applies to the concatenated result, 

not to the individual fieldname fields. But, because each fieldname must be 

defined by its own previous FIELD command, a DROP clause can be specified 

on these commands to apply to the individual fields. 

Keyword, which, when added to the end of the FIELD command, specifies that 

the field is part of the hash key for purposes of serialization, if the SERIALIZE 

parameter on the BEGIN LOAD command is active. 

The serialization feature is meaningful only when a primary key for the loaded 

data is specified via this KEY option. 



FIELD 

Usage Notes 

One or more FIELD commands may be intermixed with the TABLE command and the 

FILLER command. These commands must follow a LAYOUT command. 

If an input record field in fieldname is redefined, the data type from “character” to “decimal” 

with the datadesc parameter cannot be changed. This is illegal in Teradata TPump and will 

abort the job and return an error message. 

If both NULLIF and DROP LEADING/TRAILING BLANKS/NULLSis specified on the same 

FIELD command, the DROP clause is evaluated after the NULLIF clause. As an example, in 

the FIELD command: 

.FIELD FIELDNAME * CHAR (5) NULLIF FIELDNAME = 'x' 

DROP LEADING BLANKS; 

if the input for fieldname is 'x', the NULLIF expression would evaluate to false because the 

leading blanks are not dropped before the NULLIF evaluation. 

Specifying Data Types 

Use the datadesc parameter to specify the type and length of data in the field. Teradata TPump 

generates the USING phrase accordingly with the user-assigned field name to which the body 

of the DML statement refers. 

For complete details on data types and data conversions, see SQL Data Types and Literals. 

The following is a short list of the input length and field description for the data type 

specifications which can be made in the datadesc parameter: 

Graphic Data Type Specifications 

GRAPHIC(n) 

Where n is the length of the input stream in terms of double-byte characters. 

Length: n*2 bytes, if n is specified; otherwise 2 bytes, as n=1 is assumed. 

Description: n double-byte characters. 

The following example illustrates the use of the GRAPHIC data types in support of kanji or 

multibyte character data. The FIELD statement can contain GRAPHIC data types. 

.LAYOUT KANJIDATA; 

.FIELD EMPNO * SMALLINT; 

.FIELD LASTNAME * GRAPHIC(30); 

.FILLER FIRSTNAME * GRAPHIC(30); 

.FIELD JOBTITLE * VARGRAPHIC(30); 

VARGRAPHIC(n) 

Where n is the length of the input stream in terms of double-byte characters. 

Length: m + 2 bytes where m/2


FIELD 

Length: m + 2 bytes where m/2


FIELD 

Example 1 

Instead of specifying the following: 

... 

.FIELD fc * CHAR(5) NULLIF fc = 'empty'; 

.FIELD fi * INTEGER NULLIF fi = 0; 

... 

.DML LABEL ins; 

INSERT INTO tbl1 VALUES(...,:fc,:fi,...); 

Use this instead: 

... 

.FIELD fc * CHAR(5); 

.FIELD fi * INTEGER; 

... 


INSERT INTO tbl1 VALUES(...,NULLIF(:fc,'empty'),NULLIF(:fi,0),...); 

Example 2 

In more complex situations, as in the following example: 

... 

.FIELD fs * CHAR(1) ; 

.FIELD fc * CHAR(5) NULLIF (fs 'M') AND (fs 'F'); 

.FIELD fi * INTEGER NULLIF fi < 0; 

... 


INSERT INTO tbl2 VALUES(...,:fs,:fc,:fi,...); 

Use this instead: 

... 

.FIELD fs * CHAR(1) ; 

.FIELD fc * CHAR(5); 

.FIELD fi * INTEGER; 

... 


INSERT INTO tbl2 VALUES(...,:fs, 

CASE WHEN (:fs = 'M') OR (:fs = 'F') THEN :fc ELSE NULL END, 

CASE WHEN (:fi >= 0) THEN :fi ELSE NULL END,...); 

Using ANSI/SQL DateTime Data Types 

When the DATEFORM command is used to specify ANSIDATE as the DATE data type, each 

DATE field is internally converted to a CHAR(10) field. All ANSI/SQL DateTime TIME, 

TIMESTAMP, and INTERVAL data types must be converted to fixed-length CHAR data types 

to specify column and field names in a Teradata TPump FIELD command. 

Table 28 shows how to use ANSI/SQL DateTime specifications. 



FIELD 

Table 28: ANSI/SQL DateTime Specifications 

Data Type Variable Definition Conversion Example 

TIME 

TIME (n) 

TIMESTAMP 

TIMESTAMP (n) 

TIME WITH TIME ZONE 

TIME (n) WITH TIME 

ZONE 

TIMESTAMP WITH TIME 

ZONE 

TIMESTAMP (n) WITH 

TIME ZONE 

INTERVAL YEAR 

INTERVAL YEAR (n) 

INTERVAL YEAR TO 

MONTH 

INTERVAL YEAR (n) TO 

MONTH 

n = number of digits 

after decimal point 

Valid values: 0–6 

Default = 6 




Default = 6 




Default = 6 



Valid values: 0-6 

Default = 6 



Default = 2 



Default = 2 

CHAR(8 + n + (1 if n > 0, otherwise 0)) 

Format (n = 0): hh:mm:ss 

Example: 11:37:58 

Format: (n = 4): hh:mm:ss.ssss 

Example: 11:37:58.1234 


Format (n = 0): yyyy-mm-dd hh:mm:ss 

Example: 1998-09-04 11:37:58 

Format (n = 4): 

yyyy-mm-dd hh:mm:ss.ssss 

Example: 

1998-09-04 11:37:58.1234 


Format (n = 0): hh:mm:ss{±}hh:mm 

Example: 11:37:58-08:00 

Format (n = 4): hh:mm:ss.ssss {±} hh:mm 

Example: 11:37:58.1234-08:00 



yyyy-mm-dd hh:mm:ss{±}hh:mm 

Example: 

1998-09-24 11:37:58+07:00 


yyyy-mm-dd hh:mm:ss.ssss{±} hh:mm 

Example: 

1998-09-24 11:37:58.1234+07:00 

CHAR(n) 

Format (n = 2): yy 

Example: 98 

Format: (n = 4): yyyy 

Example: 1998 

CHAR(n + 3) 

Format (n = 2): yy-mm 

Example: 98-12 

Format: (n = 4): yyyy-mm 

Example: 1998-12 



FIELD 

Table 28: ANSI/SQL DateTime Specifications (continued) 


INTERVAL MONTH 

INTERVAL MONTH (n) 

INTERVAL DAY 

INTERVAL DAY (n) 

INTERVAL DAY TO HOUR 

INTERVAL DAY (n) TO 

HOUR 

INTERVAL DAY TO 

MINUTE 


MINUTE 


SECOND 


SECOND 


SECOND (m) 


SECOND (m) 

INTERVAL HOUR 

INTERVAL HOUR (n) 

INTERVAL HOUR TO 

MINUTE 

INTERVAL HOUR (n) TO 

MINUTE 



Default = 2 



Default = 2 



Default = 2 



Default = 2 



Default = 2 

m = number of digits 



Default = 6 



Default = 2 



Default = 2 

CHAR(n) 

Format (n = 2): mm 

Example: 12 

Format: (n = 4): mmmm 

Example: 0012 

CHAR(n) 

Format (n = 2): dd 

Example: 31 

Format: (n = 4): dddd 

Example: 0031 

CHAR(n + 3) 

Format (n = 2): dd hh 

Example: 31 12 

Format: (n = 4): dddd hh 

Example: 0031 12 

CHAR(n + 6) 

Format (n = 2): dd hh:mm 

Example: 31 12:59 

Format: (n = 4): dddd hh:mm 

Example: 0031 12:59 

CHAR(n + 9 + m + (1 if m > 0, otherwise 

0)) 

Format (n = 2, m = 0): hh:mm:ss 

Example: 12:59:59 

Format: (n = 4, m = 4): hhhh:mm:ss.ssss 

Example: 0012:59:59.1234 

CHAR(n) 

Format: (n = 2): hh 

Example: 12 

Format: (n = 4): hhhh 

Example: 0012 

CHAR(n + 3) 

Format: (n = 2): hh:mm 

Example: 12:59 

Format: (n = 4): hhhh:mm 




FIELD 

Table 28: ANSI/SQL DateTime Specifications (continued) 



SECOND 

INTERVAL HOUR (n TO 

SECOND 


SECOND (m) 

INTERVAL HOUR (n) TO 

SECOND (m) 

INTERVAL MINUTE 

INTERVAL MINUTE (n) 

INTERVAL MINUTE TO 

SECOND 


TO SECOND 

INTERVAL MINUTE TO 

SECOND (m) 


TO SECOND (m) 

INTERVAL SECOND 

INTERVAL SECOND (n) 

INTERVAL SECOND (n,m) 



Default = 2 


after the decimal point 


Default = 6 



Default = 2 



Default = 2 




Default = 6 



Default = 2 




Default = 6 


0)) 

Format: (n = 2, m = 0): hh:mm:ss 

Example: 12:59:59 

Format: (n = 4, m = 4): hhhh:mm:ss.ssss 

Example: 0012:59:59.1234 

CHAR(n) 

Format (n = 2): mm 

Example: 59 

Format: (n = 4): mmmm 

Example: 0059 


0)) 

Format (n = 2, m = 0): mm:ss 


Format: (n = 4, m = 4): mmmm:ss.ssss 

Example: 0059:59.1234 

CHAR(n + m + (1 if m > 0, otherwise 0)) 

Format (n = 2, m = 0): ss 

Example: 59 

Format: (n = 4, m = 4): ssss.ssss 

Example: 0059.1234 



FILLER 

FILLER 

Purpose 

The FILLER command describes a named or unnamed field as filler which is not to be sent to 

Teradata Database. Only fields relevant to this Teradata TPump task need to be specified. 

Syntax 

.FILLER 

fieldname 

startpos 

datadesc 

; 

3021A023 

where 


fieldname 

startpos 

datadesc 

Description 

Name of an input record field to which a nullexpr of a FIELD command refers; 

or to which a “condition” expression of the IMPORT command’s APPLY 

clause refers 

The only reason for naming a filler field is to enable one of these expressions to 

refer to it. A fieldname must obey the same rules for its construction as 

Teradata SQL column names. 

The reason for describing a field that is not to be sent to Teradata Database 

and is not used in any of the expressions mentioned in the previous paragraph 

is to make it possible to specify startpos as an asterisk for subsequent fields of 

the input records. If the use of the asterisk is not important, fields that do not 

participate in the Teradata TPump do not need to be defined. 

Starting position of a field of the data records in an external data source 

It may be specified as an unsigned decimal integer, which is a character 

position starting with 1, or as an asterisk, which is the next available character 

position beyond the preceding field. 

Note that where input records may be continued by use of the CONTINUEIF 

condition, a startpos specified as an unsigned integer refers to a character 

position in the final concatenated result from which the continuation 

indicators have been removed. Refer to the description of the condition 

parameter of the LAYOUT command. 

Type and length of data in the field 



FILLER 

Usage Notes 

Example 

One or more FILLER commands may be intermixed with the FIELD command or the TABLE 

command. These commands must follow a LAYOUT command. 

This example illustrates the use of the GRAPHIC data types in support of kanji or multibyte 

character data. The FILLER statement describing the input data set or file can contain 

GRAPHIC data types. 

.LAYOUT KANJIDATA; 

.FIELD EMPNO * SMALLINT; 

.FIELD LASTNAME * GRAPHIC(30); 

.FILLER FIRSTNAME * GRAPHIC(30); 

.FIELD JOBTITLE * VARGRAPHIC(30); 



IF, ELSE, and ENDIF 


Purpose 

Teradata TPump provides a structure of IF, ELSE, and ENDIF commands for the conditional 

control of execution processes. Conditional execution works as follows: 

Syntax 

.IF 

conditional expression 

statements to execute if TRUE 

THEN 

; 

.ELSE 

; 

.ENDIF ; 

statements to resume with 

statements to execute if FALSE 

3021A024 

where 


conditional 

expression 

statements to execute 

if TRUE 

statements to execute 

if FALSE 

statements to resume 

with 

Description 

User-defined variables or pre-defined system variables following the IF 

command, whose condition (TRUE or FALSE) triggers the execution of 

alternative groups of statements 

Statements to be executed whenever the conditional expression following 

the IF command evaluates as TRUE 

Statements following the optional ELSE command which execute only 

when the conditional expression following the IF command evaluates as 

FALSE 

Statements following the ENDIF command to terminate the conditional 

statement execution process and resume the normal command sequence 

Usage Notes 

The conditional expression in the IF command may consist of either user-defined variables or 

predefined system variables. 

The ELSE command clause is optional. ELSE is used only when there are statements to be 

executed when the condition is evaluated as false. Conditional expression is an expression 




which can be evaluated as either true or false. When evaluation of the expression returns a 

numeric result, 0 is interpreted as false; nonzero results are interpreted as true. See the “Utility 

Variables” on page 62. 

Teradata TPump supports the nesting of IF commands to a level of 100. 

Any ELSE or ENDIF commands must be present in their entirety and cannot be composed 

simply of variables in need of substitution. 

Commands and statements following an IF, ELSE, or ENDIF structure that are not executed 

are not parsed and do not have their variables substituted. 

Example 1 

Teradata TPump is case sensitive when doing a compare on an &SYS system variable. The 

RUN FILE command does not execute because the substituted values returned in this example 

are all in uppercase. This factor must be considered when creating a script to force the 

execution of a predetermined sequence of events. If, in line 0003, 'FRI' was used, the compare 

would work and the RUN FILE command would execute. 

0003 .IF '&SYSDAY' = 'Fri' THEN; 

14:10:28 - FRI MAY 09, 1997 


0004 .IF 'FRI' = 'Fri' THEN; 

0005 .RUN FILE UTNTS38; 

0006 .ENDIF; 

Example 2 

In Example 2, the user has created the table named &TABLE and a variable named 

CREATERC, into which is set the system return code resulting from the execution of the 

CREATE TABLE statement. If the table name has not already been used, and the return code is 

not zero, the return code evaluates to an error condition and the job logs off with the error 

code displayed. 

0010 .SET CREATERC TO &SYSRC; 

0011 .IF &CREATERC = 3803 /* Table &TABLE already exists */ THEN; 


0012 .LOGOFF 08; 

0013 .RUN FILE RUN01; 

0014 .ELSE 

0015 .IF &CREATERC 0 THEN 

0016 .LOGOFF &CREATRC; 

0017 .ENDIF 



IMPORT 

IMPORT 

Purpose 

The IMPORT command identifies a source for data input. By referencing the LAYOUT 

command and DML command, IMPORT ties the previous commands together. The input 

data source used for IMPORT depends on whether the Teradata TPump utility is running on 

an IBM z/OS client, or on a network-attached client platform, as shown in the following 

syntax diagram. 

Syntax 

For Channel-Attached Client Systems: 

.IMPORT 

INFILE ddname 

AXSMOD name 

'init-string' 

A 

B 

A 

B 

HOLD 

FREE 

INMOD modulename 

USING (parms) 

C 

C 

FROM m 

FOR n 

THRU k 

D 

D 

FORMAT 

VARTEXT 

'c' 

3 

E 

DISPLAY ERRORS 

NOSTOP 

E 

LAYOUT layoutname 

F 

F ; 

APPLY label 

WHERE condition 

3021A004 



IMPORT 

For Network-Attached Client Systems: 

.IMPORT 

INFILE filename 

AXSMOD name 

'init-string' 

A 

B 

A 

B 

INMOD modulename 

USING (parms) 

FROM m 

FOR n 

THRU k 

C 

C 

FORMAT 

FASTLOAD 

BINARY 

TEXT 

UNFORMAT 

VARTEXT 

'c ' 

3 

D 


NOSTOP 

D LAYOUT layoutname 

; 

APPLY label 


where 

3021A025 


Description 

INFILE ddname External data source that contains the input records on channel-attached z/ 

OS client systems. In z/OS, this is a DDNAME. 

If DDNAME is specified, Teradata TPump reads data records from the 

specified source. If modulename is also specified, Teradata TPump passes the 

records it reads to the specified module. 

The DDNAME must obey the applicable rules of the external system. 

A DDNAME must obey the same construction rules as Teradata SQL column 

names except that: 

• The “at” character (@) is allowed as an alphabetic character 

• The underscore character (_) is not allowed 

If the DDNAME represents a data source on magnetic tape, the tape may be 

either labeled or nonlabeled, as supported by the operating system. 



IMPORT 


AXSMOD name 

Description 

Name of the access module file to be used to import data 

The names of the access module files are: 

Teradata OLE DB Access Module 

oledb_axsmod.dll on Microsoft® Windows platforms 

Named Pipes Access Module 

• np_axsmod.sl on Hewlett-Packard® HP-UX platforms 

• np_axsmod.so on IBM® AIX®, Sun® Solaris® SPARC®, Sun® Solaris® 

Opteron®, and Novell® SUSE® Linux Enterprise and Red Hat® Enterprise 

Linux® Advanced Server platforms, z/Linux,] 

• np_axsmod.dll on Windows platforms 

Note: When using Teradata TPump latency option with Named Pipe 

Access Module, the Named Pipe Access Module parameter file should use 

need_full_block = no option. 

Teradata WebSphere® MQ Access Module (client version) 

• libmqsc.sl on HP-UX platforms 

• libmqsc.so on IBM AIX, z/Linux, Sun Solaris SPARC, Solaris Opteron, and 

Linux platforms 

• libmqsc.dll on Windows platforms 

Teradata WebSphere® MQ Access Module (server version) 

• libmqs.sl on HP-UX platforms 

• libmqs on IBM z/OS/ESA platforms 

• libmqs.so on IBM AIX, z/Linux, Sun Solaris SPARC, Solaris Opteron, and 

Linux platforms 

• libmqs.dll on Windows platforms 

A custom shared library file name can be used for a custom access module. 

The AXSMOD option is not required for importing: 

• Disk files on either network- or channel-attached client systems 

• Magnetic tape files on channel-attached client systems 

It is required for importing magnetic tape and other types of files on 

network-attached client systems. 

Refer to Teradata Tools and Utilities Access Module Reference for more 

information about the specific access modules. 

Teradata Access Module for JMS 

• libjmsam.so on IBM AIX, Sun Solaris SPARC, Solaris Opteron, and Red 

Hat Linux platforms 

• libjmsam.sl on HP-UX 

• libjmsam.dll on Windows platforms 

'init-string' 

Optional initialization string for the access module 



IMPORT 


INFILE filename 

HOLD 

FREE 

INMOD 

modulename 

Description 

Fully qualified UNIX or Windows path name for an input file on networkattached 

client systems 

If the path name has embedded white space characters, the entire path name 

must be enclosed in single or double quotes. 

To specify the INFILE filename, the data is read from the specified source. To 

specify the INMOD modulename, the data is passed to the specified module. 

Default condition to not deallocate the input tape device specified by ddname 

when the import operation completes on channel-attached client systems 

Instead, the HOLD specification deallocates the device when the entire 

Teradata TPump operation completes. 

Deallocation of the tape input device specified by ddname when the import 

operation completes on channel-attached client systems 

When de-allocated, any attempt to open the input device, either in the same 

Teradata TPump utility task or in another task within the same script, 

produces an undefined ddname error. 

The default is to not deallocate the device. 

Optional user-written routine for preprocessing the input data 

In z/OS, the modulename is the name of a load module. In UNIX and 

Windows, it is the pathname for the INMOD executable code file. 

The modulename must obey the applicable rules of the external system. 

A modulename must obey the same construction rules as Teradata SQL 

column names except that on channel-attached client systems: 

• The “at” character (@) is allowed as an alphabetic character 

• The underscore character (_) is not allowed 

When both the INFILE fileid and the INMOD modulename parameters are 

specified, the input file is read and the data is passed to the INMOD routine 

for preprocessing. 

If the INFILE fileid parameter is not specified, the INMOD routine must 

provide the input data record. 

Note: When an INMOD routine is used with the INFILE specification, 

Teradata TPump performs the file read operation, and the INMOD routine 

acts as a pass-through filter. 

Because the FDL-compatible INMOD routine must always perform the file 

read operation, an FDL-compatible INMOD routine cannot be used with the 

INFILE specification of a Teradata TPump IMPORT command. 

Note: On some versions of UNIX, ./ prefix characters may have to be added 

to the modulename specification if the module is in the current directory. 



IMPORT 


USING (parms) 

FROM m 

FOR n 

THRU k 

Description 

Character string with the parameters passed to the user exit routine 

The parms string can include one or more character strings, each delimited 

on either end by an apostrophe or quotation mark. 

Maximum size of the parms string is 1K bytes. 

Parentheses within delimited character strings or comments have the same 

syntactical significance as alphabetic characters. 

Before passing the parms string to the user exit routine, the following items 

are replaced with a single blank character: 

• Each comment. 

• Each consecutive sequence of white space characters, such as blank, tab 

and so on, that appears outside of delimited strings. 

The entire parms string must be enclosed in parentheses. On channelattached 

client systems, the parentheses are included in the string passed to 

the user exit routine. 

Note: The parms string must be FDLINMOD for the user exit routines 

written for the prior Pascal version of the FastLoad utility (program 

FASTMAIN). 

Logical record number, as an integer, of the record in the identified data 

source where processing is to begin 

If a FROM m specification is not used, Teradata TPump begins processing 

with the first record received from the data source. 

Number of records, as an integer, starting at record m, to be processed 

If a FOR n or a THRU k specification is not used, Teradata TPump continues 

processing through the last record obtained from the data source. 

Logical record number, as an integer, of the record in the identified data 

source where processing is to end 

If a THRU k or a FOR n specification is not used, Teradata TPump continues 

processing through the last record obtained from the data source. 



IMPORT 


FORMAT 

Description 

Record format of the input file 

The format can be: 

FASTLOAD—A 2-byte integer, n, followed by n bytes of data and an end-ofrecord 

marker (either X'0A' or X'0D'). 

BINARY—A 2-byte integer, n, followed by n bytes of data. 

TEXT—An arbitrary number of bytes, followed by an end-of-record marker 

which is a: 

• Line feed (X'0A') on UNIX platforms. 

• Carriage-return and line-feed pair (X'0D0A') on Windows platforms. 

TEXT format should only be specified for character data. Do not specify 

TEXT format for binary data, such as, PERIOD data. 

UNFORMAT—defined by FIELD, FILLER, and TABLE commands of the 

specified layout. 

Note: When using UNFORMAT formatting in z/OS, ensure that the data 

stream and data source are consistent with the layout defined in the utility 

script. Discrepancies in the length of the data stream could result in data 

corruption. 

VARTEXT—in variable-length text record format, with each field separated 

by a delimiter. Rules for a delimiter are: 

• No control characters other than a TAB character can be used as a 

delimiter. 

• Any character that appears in the data cannot be used as a delimiter. 

• Delimiters can only be up to 10 single-characters long. 

If a FORMAT option is not specified, the default is FASTLOAD. 

Note: On the mainframe platform, when access module is not used, the 

default is the input data read record by record and the LAYOUT is applied to 

each read record. 



IMPORT 


'c' 

Description 

Optional specification of the delimiter characters that separate fields in the 

variable-length text records of the input data source 

The default, if a 'c' specification is not used, is the vertical bar character ( | ). 

When the character set of the job script is different from the client character 

set used for the job (for example, on z/OS the job script must be in Teradata 

EBCDIC when using the UTF8 client character set, or UTF-16 client 

character set can be used with the job script in UTF8), Teradata TPump will 

translate the effective delimiter from the script character set form to the client 

character set form before separating the fields with it. 


set is UTF8, if the following command is given: 

… FORMAT VARTEXT '-' ... 

Teradata TPump translates '-' from the UTF8 form to the UTF-16 form and 

then separate the fields in the record according to the UTF-16 form of '-'. 

Similarly, on the mainframe, when the client character set is UTF8 and the 

script character set is Teradata EBCDIC, if the following command is given: 

… FORMAT VARTEXT '6A'xc ... 

Teradata TPump interprets x'6A' according to Teradata EBCDIC and 

translates it to the corresponding Unicode code point, U+007C "VERTICAL 

LINE", and uses the UTF8 encoding scheme of U+007C, 0x7C (which is '|' in 

7-bit ASCII), as the delimiter character for the record. 

Caution: When using the UTF8 client set on the mainframe, examine the 

definition in the International Character Set Support manual to 

determine the code points of the special characters required. 



For example, the code point of '|' in most IBM EBCDIC code pages 

is x'4F'. If a '|' is specified as the delimiter in the script or the 

delimiter to default in a system environment using such an IBM 

EBCDIC code page is left, (which is essentially the same as 

specifying '|'), but the UTF8 data uses x'7C' ('|' in Unicode) as the 

delimiter, the job will run into errors because: 

• the code point of x'4F' in Teradata EBCDIC maps to U+008D but not 

U+007C, and 

• the delimiter must use single-byte characters when it is in the client 

character set form. 


NOSTOP 

LAYOUT 

layoutname 

APPLY label 

Optional keyword specification that writes input data records that produce 

errors to the standard error file 

Optional keyword specification that inhibits the Teradata TPump 

termination in response to an error condition associated with a variablelength 

text record 

Layout of the input record, as specified by a previous command 

Error treatment options specified by a previous DML LABEL command for 

subsequent INSERT, UPDATE, or DELETE statements 



IMPORT 



Description 

Condition that determines whether the indicated label options are applied to 

the records and sent to Teradata Database, where: 

• condition true = yes 

• condition false = no 

The condition specification can reference: 

• Any combination of fields defined in the currently active layout 

• System and user-defined constants and variables 

• The fieldname1 specified in commands 

When VARTEXT is specified, the Teradata TPump utility assumes that the 

input data is variable-length text fields separated by a field delimiter 

character. The utility parses each input data record on a field-by-field basis, 

and creates a VARCHAR field for each input text field. 

When the character set of the job script is different from the client character 

set used for the job (for example, on z/OS the job script must be in Teradata 

EBCDIC when using the UTF8 client character set, or UTF-16 client 

character set can be used with the job script in UTF8), Teradata TPump 

translates the string constants specified in the condition and the import data 

referenced in the condition to the same character set before evaluating the 

condition. 


set is UTF8, if the following command is given 

… APPLY lable1 WHERE C1 = 'INSERT'; 

Teradata TPump translates the data in the C1 field to the UTF8 form and 

compares it with the UTF8 form of 'INSERT' to obtain the evaluation result. 

Similarly, on the mainframe, when the client character set is UTF8 and the 

script character set is Teradata EBCDIC, if the following command is given: 

… APPLY lable2 WHERE C2 = 'DELETE'; 

Teradata TPump translates the data in the C2 field from the UTF8 form to the 

Teradata EBCDIC form and perform the comparison with the Teradata 

EBCDIC form of 'DELETE'. 

Caution: 

When using the UTF8 client set on the mainframe, be sure to 




placement of these characters. The mappings between Teradata 

EBCDIC and Unicode can be referred to in Appendix E of 

International Character Set Support. 

Usage Notes 

A maximum of four IMPORT commands can be used in a single Teradata TPump load task. A 

single load comprises the set of commands and statements bounded by a BEGIN LOAD-END 

LOAD command pair. If the number of IMPORTs sent to Teradata Database for the load 

exceeds four, an error message is logged. Teradata TPump has been limited to four IMPORTs 

per load in order to limit the amount of memory needed to keep track of job-related statistics. 



IMPORT 




error. 

The only DML statements that are candidates for application by an IMPORT command are 

those within the scope of DML commands whose labels appear in one or more of the 

IMPORT command’s APPLY clauses. The referenced DML commands and their following 

DML statement(s) must appear between the BEGIN LOAD command that defines the task 

and the referencing IMPORT commands. A statement or group of statements is applied if no 

condition is specified, or if the specified condition is true. 

Teradata TPump permits multiple statements to be applied to the same data record in either of 

two ways. First, if an APPLY clause refers to a label whose scope includes multiple DML 

statements, each of these statements is applied to the same data record under the same 

condition specified in the clause. Second, if multiple APPLY clauses are used, each can refer to 

the label of a different DML statement or group of statements. Each label’s statements are 

applied to the same data record under that condition specified in the respective clause. These 

features allow the same data record to be applied to different tables under the same or 

differing conditions. 

VARTEXT Record Usage 

When VARTEXT is specified, Teradata TPump assumes that the input data is variable-length 

text fields separated by a field delimiter character. It parses each input data record on a fieldby-field 

basis, and creates a VARCHAR field for each input text field. 

When using the VARTEXT specification, VARCHAR, VARBYTE, and LONG VARCHAR are 

the only valid data type specifications to use in Teradata TPump layout FIELD and FILLER 

commands. 

Two consecutive delimiter characters direct Teradata TPump to null the field corresponding to 

the one immediately following the first delimiter character. 

Also, if the last character in a record is a delimiter character, and there is at least one more field 

to be processed, then Teradata TPump nulls the field corresponding to the next one to be 

processed, as defined in the layout FIELD and FIELD command. 

The total number of fields in each input record must be equal to or greater than the number of 

fields described in the Teradata TPump layout FIELD and FIELD commands. 

If it is less, Teradata TPump generates an error message. If it is more, Teradata Database 

ignores the extra fields. 

The last field of a record does not have to end with a delimiter character. It can end with a 

delimiter character, but it is not required. 

When Teradata TPump encounters an error condition in an input record, it normally discards 

the record and terminates. When loading variable-length text records, inhibit either or both of 

these functions by specifying the error-handling options: 

• DISPLAY ERRORS 



IMPORT 

APPLY Example 

• NOSTOP 

If NOSTOP is specified, Teradata TPump will not terminate even if an error is encountered. 

By specifying both options and redirecting STDERR to a file location instead of the terminal 

screen, the Teradata TPump job runs to completion and saves all the error records. Then the 

error records can be manually modified and loaded into the table. 

All IMPORT commands for a Teradata TPump task must appear between the BEGIN LOAD 

and END LOAD commands for the task. 

Teradata TPump imposes several syntax rules for the parms string for an INMOD user exit 

routine. On entry to any INMOD user exit routine for Teradata TPump, the conventional 

parameter register points to a parameter list of two 32-bit addresses used to communicate 

with the INMOD. 

At the end of an IMPORT, an environmental variable is established for each DML command 

executed. Teradata TPump variables are not constrained to 30 characters. These variables 

contain the activity counts associated with each statement. The variables created are of the 

form: 

&IMP __ 

where 

n = the number of the IMPORT, from one through four. 

Apply label = the label of the clause containing the DML command in question. 

x = the number of the statement within the containing APPLY clause. 

The following script is an example of a Teradata TPump job using the APPLY keyword to 

create conditional clauses to apply DML INSERTs, UPDATEs, and UPSERTs to the IMPORT. 

.BEGIN LOAD SESSIONS 34; 

.LAYOUT EQTTB535; 

.FIELD Pool_Upd_Code * CHAR(01); 

.FIELD Eqmt_Init 

* CHAR(04); 

.... 

.DML LABEL UPSERTAC 


UPDATE EQTDBT50.EQTTB535_TAL SET 

TCS_POOL_IDFR_NUM =:TCS_POOL_IDFR_NUM 

..... 

WHERE 

..... 

; 

INSERT INTO EQTDBT50.EQTTB535_TAL 

VALUES( 

POOL_EXPN_DATE =:POOL_EXPN_DATE (DATE, FORMAT 'YYYYMMDD') 

..... 

); 

.DML LABEL UPSERTDL; 

UPDATE EQTDBT50.EQTTB535_TAL SET 

..... 

WHERE 



IMPORT 

..... 

; 

.IMPORT INFILE INFILE 

LAYOUT EQTTB535 

APPLY UPSERTAC WHERE (POOL_UPD_CODE = 'C' 

OR POOL_UPD_CODE = 'A') 

APPLY UPSERTDL WHERE POOL_UPD_CODE = 'D' 

; 

.END LOAD; 

/* For the upsert: */ 

/* (first statement in .DML UPSERTAC) */ 

/* make sure we have the 50 updates */ 

.IF &IMP1_UPSERTAC_1 50 THEN 

.LOGOFF 100; 

/* ... and 50 inserts */ 

/* (second statement in .DML UPSERTAC) */ 

.IF &IMP1_UPSERTAC_2 50 THEN 

.LOGOFF 101; 

/* And for the plain update: */ 

/* (first statement in .DML UPSERTDL) */ 

/* we should have 10 of these. */ 

.IF &IMP1_UPSERTDL_1 10 THEN 

.LOGOFF 102; 

.LOGOFF; 



INSERT 

INSERT 

Purpose 

Teradata TPump supports the Teradata SQL INSERT statement, which adds new rows to a 

table by directly specifying the row data to be inserted. 

Syntax 

INSERT tname .* 

; 

INS INTO , 

VALUES ( :fieldname ) 

, 

expression 

( cname ) 

3021A026 

where 


tname 

cname 

fieldname 

expression 

Description 

Table that is to receive rows created from input data records 

If the table is not explicitly qualified by database name, the default database 

qualifies it. 

Column of the specified table that is to receive the value from a field of 

matching input records, where the value is identified by the corresponding 

entry in the fieldname list 

Field of an input record, whose value is given to a column of the specified table 

that is identified by the corresponding entry in the cname clause in this 

statement 

If this statement did not specify a cname, the object’s CREATE statement 

provides the corresponding column identifier. This assumes that all columns 

from the table correspond to those specified in the original CREATE 

statement. 

Alternative to the fieldname clause, an expression that includes one or more 

actual fieldnames as terms may instead be used 

Usage Notes 

The following notes describe how to use an INSERT statement following a DML command. 

An INSERT statement may also be used in the support environment; normal rules for INSERT 

are followed in that case. 

One way of specifying the applicable DML statements is to relate each field name to the name 

of the column to which the field’s data is applied. Another way tells Teradata TPump to apply 



INSERT 

Temporal Semantics 

Example 1 

Example 2 

the first nonfiller field of a record that is sent to Teradata Database to the first defined column 

of the affected table, the second nonfiller field to the second column, and so on. 

Teradata TPump converts INSERT statements into macro equivalents and, depending on the 

packing specified, submits multiple statements on one request. 

To insert records into the table identified by tname, the username specified in the LOGON 

command must have the INSERT privilege for the table. 

A value must be specified for every column, either explicitly or by default. 

For Teradata TPump use, if the object of the INSERT statement is a view, it must not specify a 

join. Teradata TPump operates only on single table statements so INSERT statements must 

not contain any joins. 

The correspondence between the fields of data records to be inserted into a table, and the 

columns of the table, can be specified in any of four ways. These appear in the following 

examples, using targetable as the table or view name. 




error. 

The maximum number of DML statements that can be packed into a request is 2430. The 


ANSI/SQL DateTime Specifications 

The ANSI/SQL DATE, TIME, TIMESTAMP, and INTERVAL DateTime data types can be used 

in Teradata SQL CREATE TABLE statements. Specify the data types as column/field modifiers 

in INSERT statements. 






.TABLE Targetablename; 


INSERT INTO Targetablename.*; 


.END LOAD; 

.LAYOUT lname; 

.FIELD first 1 somedatatype; 

.FIELD f2nd * anydatatype; 



INSERT 

. 

. 

. 

.FIELD flast * datatype; 

.DML LABEL label; 

INSERT INTO targetable VALUES (:first, :f2nd, ... :flast); 

Example 3 

Example 4 

.LAYOUT lname; 

.FIELD first 1 somedatatype; 

.FIELD f2nd * anydatatype; 

. 

. 

. 

.FIELD flast * datatype; 

.DML LABEL label; 

INSERT INTO targetable (col1, col2, ... colast) 

VALUES (:f2nd, :first, ... :flast); 

An input data source contains a series of 10- to 40-byte records. Each record contains the 

primary index value (EmpNum) of a row that is to be inserted successively into the Employee 

table whose columns are EmpNo, Name, and Salary. 

.BEGIN LOAD SESSION number ; 



.FIELD Name * (VARCHAR (30)); 

.FIELD Sal * (DECIMAL (7,2)); 


INSERT Employee (EmpNo, Name, Salary) VALUES (:EmpNum, :Name, :Sal); 


.END LOAD; 



LAYOUT 

LAYOUT 

Purpose 

The LAYOUT command, in conjunction with the immediately following sequence of FIELD, 

FILLER, and TABLE commands, specifies the layout of the externally stored data records. 

Syntax 

where 

.LAYOUT layoutname 

; 

CONTINUEIF condition 

INDICATORS 

3021A027 


layoutname 

Description 

Name assigned to the layout for reference by one or more subsequent IMPORT 

commands 

A layoutname must obey the same rules for its construction as Teradata SQL 

column names. 

The name specified also may be used in the LAYOUT clause of an IMPORT 

command. 



LAYOUT 


CONTINUEIF 

condition 

Description 

following: 

position = value 

where position is an unsigned integer (never an asterisk) that specifies the 

starting character position of the field of every input record that contains the 

continuation indicator, and where value is the continuation indicator specified 

as a character constant or a string constant. Teradata TPump uses the length of 

the constant as the length of the continuation indicator field. 

In the CONTINUEIF option, the condition specified as position = value is 

case-sensitive; verify that the correct case has been specified for this parameter. 

If the condition is true, Teradata TPump forms a single record to be sent to 

Teradata Database, by concatenating the next input record at the end of the 

current record. (The current record is the one most recently obtained from the 

external data source.) 

If the condition parameter is false, Teradata TPump sends to Teradata Database, 

the current input record either by itself, or as the last of a sequence of 

concatenated records. 

Note that the starting position of the continuation indicator field is specified as 

a character position of the input record. Character positions start with 

character position one. Teradata TPump removes the continuation indicator 

field from the input records so that they are not part of the final concatenated 

result. 

For other fields whose startpos is specified as an unsigned integer, the startpos 

refers to the field position within the final concatenated result. Consequently, 

the continuation indicator field cannot be defined as all or part of a field 

defined with the FIELD, FILLER, or TABLE commands. Refer to the startpos 

parameter of the FIELD command. 



EBCDIC when using the UTF8 client character set, or UTF-16 client character 

set can be used with the job script in UTF8), Teradata TPump translates the 

specified value, which is either a character constant or a string constant, from 

the script character set form to the client character set form before evaluating 

the condition. Teradata TPump uses the length of the constant in the client 

character set form as the length of the continuation indicator field. 

Caution: 

When using the UTF8 client set on the mainframe, be sure to 









LAYOUT 


INDICATORS 

Description 

Condition that the data is in the indicator mode 

This means that the first n bytes of each record are indicator bytes, where n is 

the rounded-up integer quotient of the number of fields defined by this 

LAYOUT command for transmission to Teradata Database, divided by 8. 

Teradata TPump sends all the FIELD commands, including redefines, to 

Teradata Database. If a field has been defined and then redefined, indicator bits 

must be set for both. FILLER commands also need to have indicator bits set. 

Teradata TPump sends both the defined and the redefined fields to Teradata 

Database. This demonstrates the inefficiency of redefines which cause the 

transfer of an extraneous field. 

If INDICATORS is specified on the LAYOUT command and the data file does 

not contain indicator bytes in each record, the target table will be loaded with 

spurious data. Conversely, if INDICATORS is not specified and the data file 

contains indicator bytes in each record, the target table will likewise be 

corrupted. Exercise caution to guard against either occurrence. 

A LAYOUT command that includes the INDICATORS option must accurately 

describe all fields of the record to agree with the column descriptions and 

ordering of the table from which this indicator-mode data was previously 

selected. If the INDICATORS option is specified, Teradata TPump sends the 

data to Teradata Database with indicators. 

The NULLIF parameter of the FIELD command can be specified with or 

without the INDICATORS option. If NULLIF is specified, Teradata TPump 

sends the data to Teradata Database with indicators, whether or not the 

INDICATORS option is specified. 

Usage Notes 

Although there is no explicit limit to the number of LAYOUT commands allowed, there is a 

practical limit. The implied limit on usable LAYOUT commands per Teradata TPump load is 

four, because Teradata TPump allows up to four IMPORT commands within a load, and each 

IMPORT can reference only one LAYOUT. 

A LAYOUT command must be immediately followed by a combination of FIELD, FILLER, 

and/or TABLE commands. This sequence of commands, referenced by the layoutname, may 

describe one or more record formats contained in one or more client data sources (see 

redefinition options for FIELD, FILLER, and TABLE). The LAYOUT command sequence is 

terminated by the first subsequent command that is not a FIELD, FILLER, or TABLE 

command. 

A layoutname may be used by one or more Teradata TPump tasks (delimited by BEGIN LOAD 

and END LOAD) in a single job step and must be defined prior to any IMPORT commands 

that reference it. All IMPORT commands in a single Teradata TPump task must reference the 

same layoutname in the LAYOUT clause. 



LOGDATA 

LOGDATA 

Purpose 

Supplies parameters to the LOGMECH command beyond those needed by the logon 

mechanism, such as user ID and password, to successfully authenticate the user. The 

LOGDATA command is optional. Whether or not parameters are supplied and the values and 

types of parameters depend on the selected logon method. LOGDATA is available only on 

network-based platforms. 

Syntax 

.LOGDATA logdata_string 

; 

'logdata_string ' 

2409A054 

where 


logdata_string 'logdata_string' 

Description 

Parameters required for the logon mechanism specified using 

“LOGMECH” on page 164 

For information about the logon parameters for supported 

mechanisms, see Security Administration. 

The string is limited to 64 KB and must be in the session 

character set. 

To specify a string containing white space or other special 

characters, enclose the data string in single quotes. 

Note: The security feature this command supports is not 

supported with the UTF-16 session character set. 

Usage Notes 

Examples 

For more information about logon security, see Security Administration. 

If used, the LOGDATA command and the LOGMECH command must precede the LOGON 

command. The commands themselves may occur in any order. 

The example demonstrates using the LOGDATA, LOGMECH, and LOGON commands in 

combination to specify the Kerberos logon authentication method and associated parameters: 

.logmech KRB5; 

.logdata joe@domain1@@mypassword; 

.logon cs4400s3; 



LOGMECH 

LOGMECH 

Purpose 

Identifies the appropriate logon mechanism by name. If the specified mechanism requires 

parameters other than user ID and password for authentication, the LOGDATA command 

provides these parameters. The LOGMECH command is optional and available only on 

network-attached systems. 

Syntax 

.LOGMECH logmech_name 

; 

2409A053 

where 


logmech_name 

Description 

Definition of the logon mechanism 

For a discussion of supported logon mechanisms, see Security Administration. 

The name is limited to 8 bytes; it is not case-sensitive. 

Usage Notes 

Examples 

Every session to be connected requires a mechanism name. If none is supplied, a default 

mechanism can be used instead, as defined on either the server or client system in an 

XML-based configuration file. 

For more information about logon security, see Security Administration. 

If used, the LOGDATA and LOGMECH commands must precede the LOGON command. The 

commands themselves may occur in any order. 

The following example demonstrates using the LOGDATA, LOGMECH, and LOGON 

commands in combination to specify the Windows logon authentication method and 

associated parameters: 

.logmech NTLM; 

.logdata joe@domain1@@mypassword; 

.logon cs4400s3; 



LOGOFF 

LOGOFF 

Purpose 

The LOGOFF command disconnects all active sessions and terminates execution of Teradata 

TPump on the client. An optional return code value may be specified as a conditional or 

arithmetic expression, evaluated to a signed integer. 

Syntax 

.LOGOFF 

retcode 

; 

3021A028 

where 


retcode 

Description 

Completion code returned to the client operating system 

If retcode is not specified, Teradata TPump returns the value generated by the 

error condition. 

Usage Notes 

Example 

Teradata TPump tracks the internal error condition code throughout the job and returns 

either 0 for complete success, 4 for warnings, 12 for fatal errors, and 16 for no sysprint. These 

values are the “error conditions”. 

To avoid ambiguity or conflict with standard Teradata TPump completion codes, values 

greater than 20 should be used. Teradata TPump returns the higher value between the value 

generated by the error condition and the return code specified in LOGOFF. 

If the LOGOFF command processes, this indicates that the highest return code reached was no 

more than 4 (warning). Any return code other than 0 or 4 would have terminated the job. 

LOGOFF is permitted at any point in the input script and logs off immediately. 

Suppose successful execution of a Teradata SQL statement (such as CREATE TABLE) is 

necessary to prepare for Teradata TPump. If it is determined that the statement has failed with 

an unacceptable completion code, and if BADRC is set to &SYSRC after the failed SQL 

statement, the execution of Teradata TPump can be terminated and the unacceptable code 

returned to the client by executing this command: 

.LOGOFF &BADRC; 



LOGOFF 

The restart table is dropped when this command is executed. If execution is terminated before 

the LOGOFF command is encountered, the restart table is not dropped, in order to support a 

restart at a later time. 

If a serious error terminates the program before the LOGOFF command is processed, the 

return code output is the value generated by the error condition rather than the optional 

retcode specified as a LOGOFF command option. 



LOGON 

LOGON 

Purpose 

Syntax 

The LOGON command establishes a Teradata SQL session between Teradata TPump and 

Teradata Database. Use it to specify the LOGON string for connecting sessions required by 

subsequent functions. The ACCEPT and SET commands are valid commands preceding 

LOGON and LOGTABLE commands. 

Standard LOGON 

.LOGON 

tdpid / 

username 

, password 

,' acctid ' 

; 

3021A005 

Note: On z/OS, with the use of the User Logon Exit routine in TDP, the user name is not 

required. See Teradata Director Program Reference for more information. 

Single Sign On LOGON 

.LOGON 

tdpid / 

username 

, password 

,'acctid ' 

; 

2409A010 

Note: When logon encryption is enabled on the gateway, single sign on is disabled on the 

client and standard logon syntax should be used instead. 

where 


tdpid 

Description 

Optional identifier associated with a particular copy of Teradata Database 

If this field is not specified, the default tdpid, established by the system 

administrator, is used. 

For channel-attached systems, the tdpid string must be in the form: 

TDPn 

where n is the TDP identifier 



LOGON 


username 

password 

'acctid' 

Description 

User identifier of up to a 30-character maximum 

Optional password associated with the username, up to a 30-character 

maximum 

Teradata Database must be configured to recognize the password specified. 

Optional account identifier associated with the username, up to a 30-character 

maximum 

The string specification must be enclosed in single quotes. 

If this field is not specified, a default “acctid” is used. 

Usage Notes 

Both the LOGON command and the LOGTABLE command are required to set up the 

Teradata TPump support environment. Use them in any order, but they must precede any 

other commands. However, a RUN FILE command can be used to identify a file containing 

the LOGON command before the LOGON and LOGTABLE commands. 

LOGON and LOGTABLE commands typically occur as: 

.logtable logtable001; 

.logon tdpx/me,paswd; 

When the LOGON command is executed, the initial Teradata TPump utility session is logged 

on. The logon information is saved and re-used when processing the BEGIN LOAD command 

to connect the appropriate number of sessions. 

The parameters (tdpid, username, password, and “acctid”) are optional and are used in all 

sessions established with Teradata Database. The LOGON command may only occur once. 

The period (.) preceding LOGON is also optional. 

The tdpid identifier specifies a particular Teradata Database. See the system or site 

administrator for the identifier planned to use. If a tdpid is not specified and the site 

administrator has not updated the System Parameter Block, the default identifier is Teradata 

Database. The long form of this parameter, tdpx, should be used to avoid CLI errors that can 

occur when the short form is used. 

The tdpid parameter is optional if the site has only one TDP, if a TDP command was 

previously executed, or if the default TDP was selected. This parameter is not case-sensitive. 

Teradata TPump does not prompt for a username or password. If either or both of these are 

required, Teradata TPump fails and reports the error. Both of these parameters may be 

optional if a logon exit is used. 

Where possible, do not use special characters in the acctid parameter string. Although acctid 

may contain special characters, the special characters might be interpreted differently by 

different output devices. Therefore, a script containing special characters might have to be 

modified if the output is routed to another device. If the acctid contains an apostrophe (single 

quote) character, use either the second form of the LOGON command, which is delimited by 

quotes, or double the apostrophe character as follows: 



LOGON 

.LOGON 0/fml,fml,"engineering’s account" 

or 

.LOGON 0/fml,fml,'engineering"s account" 

If the acctid does not contain an apostrophe, the two LOGON command forms are the same. 

If any parameter is entered incorrectly, the logon fails and Teradata TPump returns an error 

message. For security reasons, the error message does not state in which parameter the error 

occurred. 

If password security on a channel-attached client is a concern, use the RUN FILE command to 

alter the script to accept the LOGON command from another dataset/file under the control of 

ACF2 or another client-resident security system. For example: 

//stepname EXEC PGM=TPUMP,... 

//SECURE DD DSN = FOO 

//SYSIN DD * 

.LOGTABLE MYTABLE; 

.RUN SECURE; 

Then log on by simply entering the LOGON command with a valid user name and no 

password if the system administrator has granted this option. As an example, to log onto 

Teradata TPump as user ABC with ABC as the password (which is masked from view on the 

output listing), specify the LOGON command on one line as follows: 

.logon ABC,ABC 

When the command is entered, Teradata TPump displays something like: 

**** 15:12:47 UTY8400 Teradata Database Version: 13.10.00.00 








Logon exits are supported on both mainframe and UNIX clients. The CLIv2 User Logon Exit 

routine can be used to make some or all logon string elements optional. 

LOGON is used with the LOGTABLE command, both of which are required. LOGON and 

LOGTABLE may appear in any order. If LOGON is entered first, a warning that LOGTABLE is 

required is returned. 

The parameters (tdpid, username, password, and “acctid”) are used in all sessions established 

with Teradata Database. The LOGON command may occur only once. 

Note: If the database is configured to use the Single Sign On (SSO) and the Teradata client 

machine is logged on, the machine name, user name, and password are not required in the 

LOGON command. The user name and password combination specified when the Teradata 

client machine was logged on are authenticated via network security for a SSO such that valid 

Teradata users will be permitted to log on to Teradata Database. The use of SSO is strictly 

optional, unless the Gateway has been configured to accept only SSO-style logons. 



LOGON 

To connect to a Teradata Database other than the default, the TDPid must be included in the 

LOGON command. If the TDPid is not specified, the default contained in clispb.dat will be 

used. To be interpreted correctly, the TDPid must be followed by the slash separator (/), to 

distinguish the TDPid from a Teradata Database user name. For example, to connect to 

slugger, enter one of the following: 

.LOGON slugger/; 

.LOGON slugger/,,'acctinfo'; 

If the LOGON command is entered first, Teradata TPump warns that the LOGTABLE 

command is also required. 

If an account ID is to be used, the optional account ID must be specified in the LOGON 

command. 



LOGTABLE 

LOGTABLE 

Purpose 

Caution: 

The LOGTABLE command identifies the table to be used for journaling checkpoint 

information required for safe, automatic restart of the Teradata TPump support environment 

in the event of a client or Teradata Database hardware platform failure. 

The LOGTABLE command is used in conjunction with the LOGON command, both of which 

are required. Both LOGON and LOGTABLE may appear in any order. The ACCEPT and SET 

commands are valid commands preceding LOGON and LOGTABLE commands. If LOGON is 

entered first, a warning is returned that the LOGTABLE is required. 

Do not share the restart log table between two or more Teradata TPump jobs. Each Teradata 

TPump job must have its own restart log table to ensure that it runs correctly. If a distinct 

restart log table for each Teradata TPump job is not used, the results are unexpected. In 

addition, one or more of the affected jobs may not be able to restart. 

Syntax 

.LOGTABLE 

dbname. 

tname 

; 

3021A029 

where 


dbname 

tname 

Description 

(Optional) Database name under which the log table exists 

The default is the database name associated with the username specified in the 

LOGON command. Teradata TPump searches for the table (tname) in that 

database unless another database name is specified in this option. 

Identifier for the restart log table 

Usage Notes 

A LOGTABLE command is required for each invocation of Teradata TPump. Only a single 

LOGTABLE command is allowed for each execution. It must precede all environmental and 

application commands (other than RUN FILE and LOGON) in the input stream. 

The specified table is used as the Teradata TPump restart log. It does not have to be fully 

qualified. If the table exists, it is examined to determine if this is a restart. When this is the 

case, a restart is done automatically. If the table does not exist, it is created and used as a restart 

log during this invocation of Teradata TPump. 



LOGTABLE 

The log table is maintained automatically by Teradata TPump. If this table is manipulated in 

any way, the restart capability is lost. The only action that should be taken is to DROP the log 

table; never attempt to delete rows from the table. The log table should not be dropped when 

the Teradata TPump job using that log table is running. If the log table is dropped during a job 

run, Teradata TPump will run into errors. 

The default for the database name cannot be overridden with a DATABASE statement because 

it must come after LOGTABLE/ LOGON. Instead, the LOGTABLE dbname option must be 

used. 

Teradata TPump allows a DELETE DATABASE statement because DELETE is a standard 

Teradata SQL function. This statement can delete the current restart log after it has been 

created, which terminates the job. 

Example 

The following example presents both the LOGTABLE command and the LOGON command 

as they typically occur. 

.logtable Mine.Logtable001; 

.logon tdpx/me,paswd; 

Log Table Space Requirements 

The calculation of space requirements for a Teradata TPump log table is highly dependent on 

the specifics of the job. Although there are mandatory inserts for every Teradata TPump job, 

others occur on a job-dependent basis. See “Estimating Space Requirements” for details on 

how to calculate log table space. 



NAME 

NAME 

Purpose 

The NAME command assigns a unique job name identifier to the environmental variable 

&SYSJOBNAME. 

Syntax 

.NAME jobname 

; 

3021A030 

where 


jobname 

Description 

Character string that identifies the name of a job in a maximum of 

16 characters 

If this command is not specified, the default job name of ltdbase_logtable is 

used, where: 

• ltdbase is a character string of up to the first seven characters of the name of 

the database containing the log table. 

• logtable is a character string with the first eight characters of the log table 

name. 

Usage Notes 

The NAME environmental command must be used only once, in order to set the job name 

and the variable &SYSJOBNAME. Further attempts to execute the command will fail. 

The NAME command sets the variable &SYSJOBNAME to the specified string. The string is 

truncated to 16 characters. It is an error to use this command more than once in a Teradata 

TPump script or after the first BEGIN LOAD command in the script. 

If &SYSJOBNAME is not set using the NAME command, it defaults to 

MYYYYMMDD_HHMMSS_LLLLL, where 

M = macro 

MM = month 

DD = day 

YYYY = year 

hh = hour 

mm = minute 

ss = second 



NAME 

lllll = is the low order 5 digits of the logon sequence number returned by the database from the 

.LOGON command. 

This variable is not set until created with the NAME command, or with the first BEGIN LOAD 

by default. Any attempt to use it before a NAME command is issued (or before the first 

BEGIN LOAD if there is no NAME command), results in a syntax error. This variable is 

significant because it is used by Teradata TPump when composing default names for various 

database artifacts, namely the error table and Teradata TPump-created macros. 

Note: If serialization for two or more DML statements is required, they cannot be put in 

different partitions. Serialization requires that all DML statements with identical hash values 

of the rows be submitted from the same session. 



PARTITION 

PARTITION 

Purpose 

The PARTITION command defines a collection of sessions used to transfer SQL requests to 

Teradata Database. A DML command may name the partition to be used for its requests to 

the database. 

A default session partition may still be created using the SESSIONS and PACK parameters of 

the BEGIN LOAD command. 

This command works in conjunction with a DML parameter, PARTITION, which names the 

session partition that a DML’s SQL will use. If the DML command does not have a 

PARTITION parameter, then the default partition created using the SESSIONS and PACK 

parameters of the BEGIN LOAD command will be used. 

Syntax 

.PARTITION partition_name SESSIONS number A 

threshold 

A 


PACK 

PACKMAXIMUM 

statements 

OFF 

ON 

3021B018 

where 


number 

Description 

Number of sessions to be logged on for the partition 

Teradata TPump logs on and uses the number of sessions specified to 

communicate requests to Teradata Database. 

There is no default value for number; it must be specified. Neither is there a 

maximum value, except for system-wide session limitations, which vary 

among machines. 

Limiting the number of sessions conserves resources on both the external 

system and Teradata Database. This conservation is at the expense of a 

potential decrease in throughput and increase in elapsed time. 



PARTITION 



ON/OFF 

PACK 

PACKMAXIMUM 


SESSIONS 

Description 

Keyword to encrypt import data and the request text during the 

communication between Teradata TPump and Teradata Database for the 

sessions defined in the PARTITION command 

If ON, the encryption will be performed. If OFF, the encryption will not be 

performed. If DATAENCRYPTION is not specified, the default is OFF 

when "-y" runtime parameter is not specified and DATAENCRYPTION is 

OFF in the BEGIN LOAD command. If "-y" runtime parameter is specified 

or DATAENCRYPTION is ON in the BEGIN LOAD command, the default 

is ON. 

This option applies to the sessions defined by the PARTITION command. 

When the session is specified explicitly, the setting overrides the encryption 

setting by the "-y" runtime parameter and by the DATAENCRYPTION 

option in the BEGIN LOAD command for the sessions defined in the 

PARTITION command. 

Keyword for the number of statements to pack into a multiple-statement 

request 


Packing improves network/channel efficiency by reducing the number of 

sends and receives between the application and Teradata Database. 

Keyword requesting Teradata TPump to dynamically determine the 

maximum possible PACK factor for the current partition 


Displayed in message UTY6652, the value thus determined should be 

specifically used on subsequent runs, as the use of PACKMAXIMUM 

requires iterative interactions with the database during initialization to 

heuristically determine the maximum possible PACK factor. 

Name assigned to the partition for reference by one or more subsequent 

DML commands 

A partition name must obey the same rules for its construction as Teradata 

SQL column names. The name specified may be used in the PARTITION 

clause of a DML command. 

Keyword for designating the number of sessions for the partition 



PARTITION 


statements 

threshold 

Description 

Number of statements, as a positive integer of up to 2430, to pack into a 

multiple-statement request 

Default value is 20 statements per request. 

Note: Under certain conditions, Teradata TPump may determine that the 

pack factor has been set too high. Teradata TPump then automatically 

lowers the pack setting to an appropriate value and issues warning message 

UTY6625, for example: 

“UTY6625 WARNING: Packing has been changed to 12 statements per 

request”, and continues. 

Packing improves network/channel efficiency by reducing the number of 

sends/receives between the application and the database. 

The packing factor is validated by sending a fully packed request to 

Teradata Database using a prepare. This test checks for syntax problems 

and requests that are excessively large and overwhelm the parser. 

To simplify the script development process, Teradata TPump ignores 

certain errors returned by an overloaded parser, shrinks the request, retries 

the prepare until it executes successfully and finally, issues a warning noting 

the revised packing factor size. 

When this happens, the Teradata TPump script should be modified to 

eliminate the warning, which avoids the time-consuming process of 

shrinking the request. 

Note: A packing failure may occur if the source parcel length does not 

match the data defined. If this happens, Teradata TPump issues the 

message: 

“UTY2819 WARNING: Packing may fail because input data does not 

match with the data defined.” 

To resolve this problem, increase the packing factor and resubmit the job. 

Minimum number of sessions to be logged on for the partition 

When logging on sessions, if system limits are reached above the threshold 

value, Teradata TPump stops trying to log on, and uses whatever sessions 

are already logged on. 

If the sessions run out before the threshold is reached, Teradata TPump 

logs off all sessions, waits for the time determined by the SLEEP value 

(specified in the BEGIN LOAD command), and tries to log on again. 

Example 

A sample script that uses partitioning follows: 


.LOGON cs4400s3/cfl,cfl; 





C1 CHAR(12) not null, 



PARTITION 

C2 CHAR(8) not null) 

PRIMARY INDEX (C1); 


C1 CHAR(12), 

C2 CHAR(8), 

C3 CHAR(6)) 


.BEGIN LOAD 


CHECKPOINT 15 

TENACITY 2 


ROBUST off 

serialize on 

; 


.FIELD cc1 * CHAR(12) key; 



.filler space1 * char(1); 

.partition part1 pack 10 sessions 10; 

.partition part2 sessions 5 1 packmaximum; 


DO INSERT FOR MISSING ROWS 


use(cc1, cc2); 


SET C2 = :CC2 


INSERT TPTBL01 (C1, C2) 

VALUES (:CC1,:CC2); 


serializeon( cc1 ) 



UPDATE TPTBL02 SET C2 = :CC2 WHERE C1 = :CC1; 


VALUES (:CC1,:CC2,:CC3); 

.IMPORT INFILE c:\NCR\Test\TpumpData001.txt FORMAT TEXT 

LAYOUT LAY02 

APPLY LABEL01 

APPLY LABEL02 where CC2 = '00000001'; 

.END LOAD; 

.LOGOFF; 



ROUTE 

ROUTE 

Purpose 

The ROUTE command identifies the destination of various outputs produced by Teradata 


Syntax 

.ROUTE 

MESSAGES 

FILE fileid1 

TO 

ECHO FILE fileid2 

WITH 

TO 

ECHO OFF 

WITH 

FILE fileid1 

ECHO fileid2 

TO 

WITH 

TO 

FILE fileid1 

ECHO OFF 

TO 

WITH 

; 

3021A031 

where 


MESSAGES 

fileid1 and fileid2 

ECHO 

Description 

Preferred location where the messages be redirected (normally written to 

DDNAME SYSPRINT in z/OS or stdout in UNIX); that is, sent to an 

additional destination, or both 

Alternate message destination in the external system 


Fileid is the path name for a file. If the path name has embedded white 

space characters, enclose the entire path name in single or double quotes. 

z/OS 

A DDNAME. See the z/OS fileid topic in the “Usage Notes” section. 

Additional destination, with a fileid specification 

Use the ECHO keyword to specify, for example, that messages be captured 

in a file (fileid2) while still being written to the terminal. 

Note: The ECHO OFF specification cancels the additional file 

specification of a previously established ECHO destination. 

Usage Notes 

In z/OS, fileid is a true DDNAME; and in UNIX, it is a file pathname. If DDNAME is specified, 

Teradata TPump writes data records to the specified destination. A DDNAME must obey the 

same rules for its construction as Teradata SQL column names except that the “at” sign (@) is 



ROUTE 

Example 1 

allowed as an alphabetic character and the underscore ( _ ) is not allowed. The DDNAME 

must also obey the applicable rules of the external system. If DDNAME represents a data 

source on magnetic tape, the tape may be either labelled or nonlabelled (if the operating 

system supports it). 

On UNIX systems, an asterisk (*) can be used as the fileid1 or fileid2 specifications to route 

messages to the system console/standard output (stdout) device. The system console is the: 

• Display screen in interactive mode 

or 

• Standard output device in batch mode 

.ROUTE MESSAGES TO FILE OUTPUT WITH ECHO TO FILE SYSOUT; 

ECHO, when specified with OFF, stops routing output to the previously established echo 

destination. 

Example 2 

.ROUTE MESSAGES FILE OUTPUT; 

The messages are written to the file designated by OUTPUT from this point unless redirected 

by another ROUTE command. 

In UNIX-based systems, if “outfilename” is used to redirect “stdout,” and also as the file in a 

ROUTE WITH ECHO command, the results written to “outfilename” may be incomplete due 

to conflicting writes to the same file. 



RUN FILE 

RUN FILE 

Purpose 

The RUN FILE command invokes the specified external source as the current source of 

commands and statements. 

Syntax 

.RUN FILE 

fileid 

IGNORE 

charpos1 

charpos1 THRU 

THRU charpos2 

charpos1 THRU charpos2 

; 

3021A032 

where 


fileid 

Description 

Data source of the external system 

The client system DD or equivalent statement specifies a file. 


infilename (the path name for a file). If the path name has embedded 

white space characters, enclose the entire path name in single or double 

quotes. 

z/OS 


If DDNAME is specified, Teradata TPump reads data records from the 

specified source. 

A DDNAME must obey the same rules for its construction as Teradata 

SQL column names, except that: 



The DDNAME must also obey the applicable rules of the external system. 

If DDNAME represents a data source on magnetic tape, the tape may be 

either labelled or nonlabelled (if the operating system supports it). The 

“at” sign (@) is allowed as an alphabetic character and the underscore (_) 

is not allowed. 



RUN FILE 


charpos1 and charpos2 

Description 

Start and end character positions of a field in each input record which 

contains extraneous information 

Teradata TPump ignores the specified field(s) as follows: 

• charpos1: only the single specified character position is ignored. 

• charpos1 THRU: character positions from charpos1 through the end of 

the record are ignored. 

• THRU charpos2: character positions from the beginning of the record 

through charpos2 are ignored. 

• charpos1 THRU charpos2: character positions from charpos1 through 

charpos2 are ignored. 

Usage Notes 

Once Teradata TPump executes the RUN FILE command, further commands and DML 

statements are read from the specified source until a LOGOFF command or end-of-file 

condition is encountered, whichever occurs first. An end-of-file condition automatically 

causes Teradata TPump to resume reading its commands and DML statements from the 

previously active source (or the previous RUN source when RUNs are nested), either SYSIN 

for z/OS, or stdin (normal or redirected) in UNIX. After SYSIN/stdin processes any userprovided 

invocation parameter, it remains the active input source. 

If an end-of-file condition occurs on fileid, SYSIN/stdin is read because there are no more 

commands or statements in the PARM string. 

The command source specified by a RUN FILE command may contain nested RUN FILE 

commands to 16 levels. 

On UNIX systems, an asterisk (*) can be used as the fileid specification for the system console/ 

standard input (stdin) device. The system console is the: 

• Keyboard in interactive mode 

or 

• Standard input device in batch mode 

Example 

.RUN FILE LOGON; 



SET 

SET 

Purpose 

The SET command assigns a data type and a value to a utility variable. Variables need not be 

declared in advance to be the object of the SET command. If a variable does not already exist, 

the SET command creates it. 

The SET command also dynamically changes the data type to that of the assigned value if it 

has already been defined. Variables used to the right of TO in the expression must have already 

been defined. 

Syntax 

.SET 

var 

TO 

expression 

; 

3021A033 

where 


var 

expression 

Description 

Name of the utility variable which is set to the evaluated expression 

following it 

Value and data type to which the utility variable is to be set 

Usage Notes 

The utility variable can be substituted wherever substitution is allowed. 

If the expression evaluates to a numeric value, the symbol is assigned an integer value, as in: 

.SET FOONUM TO -151 ; 

If the expression is a quoted string, the symbol is assigned a string value, as in: 

.SET FOOCHAR TO '-151' ; 

The minimum and maximum limits for Floating Point data types are as follows: 

4.0E-75


SET 

Example 2 

In this example, X evaluates to 12. If a decimal point is added to the concatenated variables, as 

in: 

.SET C TO 1; 

.SET D TO 2; 

.SET X TO &C..&D; 

X then evaluates to 1.2. 



SYSTEM 

SYSTEM 

Purpose 

The SYSTEM command allows access to the local operating system during Teradata TPump 

operations. 

Syntax 

.SYSTEM 'oscommand' 

; 

3021A034 

where 


‘oscommand' 

Description 

Command string (enclosed within single quotes) that is appropriate to the local 

operating system 

The SYSTEM command suspends the current Teradata TPump application in 

order to execute the command. When the command completes, the return code 

from the invoked command is displayed, and the &SYSRC variable is updated 

with the return code. 

Usage Notes 

On z/OS clients, the command is passed to the PGM executor. The first token of the command 

string is interpreted as a load module and the remainder as a PARM string. As an example, the 

following statement calls the load module IEBUPDTE, passing the PARM string “NEW”. 

.SYSTEM “IEBUPDTE NEW”; 

This command calls IEBUPDTE in the same way it is called via the JCL statement: 

//EXEC PGM=IEBUPDTE,PARM='NEW' 

On z/OS, the program must be present in the STEPLIB or JOBLIB concatenation, be resident 

in one of the LPAs, or be located in the linklist concatenation. 

Otherwise, the invocation will fail, with code SYS_ABTM (-14) returned, resulting from an 

underlying abend S806-04. Other types of failures also are possible. 

On UNIX clients, the SYSTEM command invokes the standard UNIX interface to issue the 

command to the shell (sh), and waits for its completion. 



TABLE 

TABLE 

Purpose 

The TABLE command identifies a table whose column names and data descriptions are used 

as the names and data descriptions of the input record fields. These are assigned in the order 

defined. The TABLE command must be used with the LAYOUT command. 

Syntax 

.TABLE 

tableref 

; 

3021A035 

where 


tableref 

Description 

Existing table whose column names and data descriptions are assigned, in the 

order defined, to fields of the input data records 

The column names of the table specified by the TABLE command must be 

Teradata SQL column names that do not require being enclosed in quotation 

marks. Tables cannot be created with invalid column names. Any nonstandard 

column name causes one of three kinds of errors, depending on the nature of 

the divergence from the standard. These errors are: 

• Embedded blanks cause a syntax error, depending on the non-blank 

contents of the name. 

• Invalid characters cause an invalid name error. 

• Reserved words cause a syntax error that mentions invalid use of the 

reserved word. 

Usage Notes 

One or more TABLE commands may be intermixed with the FIELD command or FILLER 

command following a LAYOUT command. 

This method of specifying record layout fields assumes each field, as defined by the data 

description of the corresponding column of tableref, is contiguous with the previous one, 

beginning at the next available character position beyond any previous field specifications for 

the input records. The fields must appear in the order defined for the columns of the table. 

The object identified by the tableref parameter must be a table. It need not appear as a 

parameter of the BEGIN LOAD command, but the user must either be an owner of the object 

or have at least one privilege on it. If specified as an unqualified table name, the current 

default database qualifies it. 



TABLE 

When serialization has been set to ON by the BEGIN LOAD command, the primary index 

columns for the specified table are considered key fields for serialization purposes. 

When the TABLE command is used and the table contains a structured UDT type, Teradata 

TPump returns an external representation of the UDT and that requires the user to transform. 

The term “external type” means the data type of the external opaque container for a 

structured UDT and is the type returned by the from-sql transform method. 





Purpose 

Teradata TPump supports the UPDATE Teradata SQL statement, which changes field values in 

existing rows of a table. 

Syntax 

where 

, 

UPDATE tname SET cname = expr WHERE conditional ; 

UPD 

3021A036 


tname 

cname 

expr 


Description 

Table or view to be updated 

This table was previously identified as tname in the BEGIN LOAD command. 

If tname is not explicitly qualified by database name, the current default 

database qualifies it. 

Column whose value is to be replaced by the value of expr 

The column named must not be a column of the primary index. 

Expression whose resulting value is to replace the current value of the 

identified column 

The expression can contain any combination of constants, current values of 

columns of the referenced row, or values from fields of input data records. 

References to fields of input data records are as follows: 

:fieldname 

where :fieldname is defined by a FIELD command or TABLE command of the 

layout referenced by an IMPORT using this UPDATE. 

Conditional clause specifying the row or rows to be updated 

The conditional clause can use values from fields of input data records by 

referring to their field names as follows: 

:fieldname 

where fieldname is defined by a FIELD command or TABLE command. 

Equality values for all the columns of the primary index must be explicitly 

specified in this clause. 




Usage Notes - Update 

Temporal Semantics 

The following notes describe how to use an UPDATE statement following a DML command. 

An UPDATE statement may also be used in the support environment; normal rules for 

UPDATE are followed in that case. 

• To update records in a table, the userid that is logged on must have UPDATE privilege for 

the table. 

• In an IMPORT task, if multiple Unique Primary Index (UPI) columns are specified, the 

columns should all be specified in the WHERE clause of the UPDATE statement. In this 

case, the WHERE clause is fully qualified, thereby allowing Teradata TPump to avoid table 

locks and optimize the processing. 

• For Teradata TPump use, if the object of the UPDATE statement is a view, it must not 

specify a join. Teradata TPump operates only on single table statements so UPDATE 

statements must not contain any joins. 

• Only one object may be identified. 

• The OR construct can be used in the WHERE clause of a DELETE statement; alternatively, 

two or more separate DML statements (one per OR term) can be used, with the DML 

statements applied conditionally with the APPLY clause of the IMPORT command. The 

nature of the alternatives will usually make one of the methods more appropriate. 

• The maximum number of INSERT, UPDATE, and DELETE statements that can be 

referenced in an IMPORT is 128. The 128th DML which would cause the insertion of the 

DML sequence number of 128 for the DMLSEQ field in the error table could lead to 

Teradata Database 3520 error. 

• The maximum number of DML statements that can be packed into a request is 2430 . The 


• To ensure data integrity, the SERIALIZE parameter defaults to ON in the absence of an 





Example 

The following example describes an input data source containing a series of 14-byte records. 

Each record contains the value of the primary index column (EmpNo) of a row of the 

Employee table whose PhoneNo column is to be assigned a new phone number from field 

Fone. 




.FIELD Fone * (CHAR (10)); 


UPDATE Employee SET PhoneNo = :Fone WHERE EmpNo = :EmpNum; 





.END LOAD; 

Usage Notes - Atomic Upsert 

The syntax for Atomic upsert consists of an UPDATE statement and an INSERT statement 

separated by an ELSE keyword as follows: 

UPDATE ELSE INSERT ; 

Teradata TPump inserts the ELSE keyword between the UPDATE and INSERT statements by 

itself, so the user should not enter it in the script. If the ELSE keyword is used in this context, 

Teradata TPump will terminate with a syntax error. 

The and are operands for regular UPDATE and 

INSERT SQL statements, respectively. Only certain types of UPDATE and INSERT operands 

are valid in an Atomic upsert statement, and the operand parameters within a given upsert 

statement are subject to further constraints linking the update and insert parameters. 

When using the standard upsert feature, the primary index should always be fully specified for 

the UPDATE statement, just as for other DML in a Teradata TPump script, so that the update 

can be processed as a one-AMP rather than an all-AMP operation. In addition, both the 

UPDATE and the INSERT of an upsert statement pair should specify the same target table, 

and the primary index value specified in the UPDATE's WHERE clause should match the 

primary index value implied by the column values in the INSERT. When processing an 

Atomic upsert statement, Teradata Database will usually reject statements that fail to meet 

these basic upsert constraints and return an error, enabling Teradata TPump to detect and 

handle constraint violations. 

Constraints considered to be basic to the upsert operation are: 

• SAME TABLE: The UPDATE and INSERT statements must specify the same table. 

• SAME ROW: The UPDATE and INSERT statements must specify the same row; that is, the 

primary index value in the inserted row must be the same as the primary value in the 

targeted UPDATE row. 

• HASHED ROW ACCESS: The UPDATE must fully specify the primary index, allowing the 

target row to be accessed with a one-AMP hashed operation. 

• Some of these restrictions concern syntax that is supported in UPDATE and INSERT 

statements separately but not when combined in an Atomic upsert statement. Restrictions 

not supported by the Atomic upsert feature that return an error if submitted to Teradata 

Database are: 

• INSERT... SELECT: Syntax not supported. The INSERT may not use a subquery to specify 

any of the inserted values. Note that support of this syntax is likely to be linked to support 

of subqueries in the UPDATE's WHERE clause constraints as described above, and may 

involve new syntax features to allow the UPDATE and INSERT to effectively reference the 

same subquery. 

• UPDATE-WHERE-CURRENT: Syntax not supported. The WHERE clause cannot use an 

updatable cursor to do what is called a positioned UPDATE. (It is unlikely that this syntax 

will ever be supported.) Note that this restriction does not prevent cursors from being 




used in other ways with Atomic upsert statements. For example, a DECLARE CURSOR 

statement may include upsert statements among those to be executed when the cursor is 

opened, as long as the upserts are otherwise valid. 

• UPDATE-FROM: Not supported. The SET clause cannot use a FROM clause table 

reference in the expression for the updated value for a column. 

• UPDATE-WHERE SUBQUERIES: Not supported. The WHERE clause cannot use a 

subquery either to specify the primary index or to constrain a nonindex column. Note that 

supporting this UPDATE syntax would also require support for either INSERT … SELECT 

or some other INSERT syntax feature that lets it specify the same primary index value as 

the UPDATE. 

• UPDATE-PRIMARY INDEX: Not supported. The UPDATE cannot change the primary 

index. This is sometime called unreasonable update. 

• TRIGGERS: Feature not supported if either the UPDATE or INSERT could cause a trigger 

to be fired. The restriction applies as if the UPDATE and INSERT were both executed, 

because the parser trigger logic will not attempt to account for their conditional execution. 

UPDATE triggers on columns not referenced by the UPDATE clause, however, will never 

be fired by the upsert and are therefore permitted. DELETE triggers cannot be fired at all 

by an upsert and are likewise permitted. Note that an upsert could be used as a trigger 

action but it would be subject to the same constraints as any other upsert. Because upsert 

is not allowed to fire any triggers itself, an upsert trigger action must not generate any 

further cascaded trigger actions. 

• JOIN/HASH INDEXES: Feature not supported if either the UPDATE or INSERT could 

cause the join/hash index to be updated. As with triggers, the restriction applies to each 

upsert as if the UPDATE and INSERT were both executed. While the UPDATE could 

escape this restriction if the join/hash index does not reference any of the updated 

columns, it is much less likely (and maybe impossible) for the INSERT to escape this 

restriction. If the benefit of lifting the restriction for a few unlikely join/hash index cases 

turns out to be not worth the implementation cost, the restriction may have to be applied 

more broadly to any table with an associated join/hash index. 

Teradata TPump treats a failed constraint as a nonfatal error, reports the error in the job log 

for diagnostic purposes, and continues with the job by reverting to nonbasic upsert protocol. 

To resolve order-dependency issues, Teradata TPump always processes the UPDATE before the 

INSERT because: 

• It matches the ordering implied by the upsert name: UP[date] + [in]SERT. 

• It matches the ordering implied by the UPDATE-ELSE-INSERT syntax. 

• It matches the common definition of upsert semantics. 

• It allows for an upsert operation on MULTISET tables, where an insert-first policy would 

always succeed on INSERT and never on UPDATE. 

Existing Teradata TPump scripts for upsert do not need to be changed. The syntax as 

described below for upsert will continue to be supported: 


UPDATE ; 

INSERT ; 




Teradata TPump changes this syntax into Atomic upsert syntax by replacing the semicolon 

between the UPDATE and INSERT statements with an ELSE keyword to convert the statement 

pair into a single Atomic upsert statement. 

If user-created macros are used in place of the UPDATE and INSERT statements, Teradata 

TPump generates: 

EXEC ELSE EXEC ; 

because this statement does not conform to Atomic upsert syntax used by Teradata TPump. 

Atomic Upsert Examples 

This section describes several examples that demonstrate how the Atomic upsert feature 

works, including cases where errors are detected and returned to the user. All of the examples 

use the same table, called Sales, as shown below: 

CREATE TABLE Sales, FALLBACK, 

(ItemNbrINTEGER NOT NULL, 

SaleDateDATE FORMAT 'MM/DD/YYYY' NOT NULL, 

ItemCountINTEGER) 

PRIMARY INDEX (ItemNbr); 

Assume that the table has been populated with the following data: 


A table called NewSales has the same column definitions as those of table Sales. 

Example 1 (Error: different target tables) 

This example demonstrates an upsert statement that does not specify the same table name for 

the UPDATE part and the INSERT part of the statement. 


SaleDate = '05/30/2005') ELSE INSERT INTO NewSales (10, '05/30/2005', 

1); 

A rule of an upsert is that only one single table is processed for the statement. Because the 

tables, Sales and NewSales, are not the same for the upsert statement, an error is returned to 

the user indicating that the name of the table must be the same for both the UPDATE and the 

INSERT. 

Example 2 (Error: different target rows) 

This example demonstrates an upsert statement that does not specify the same primary index 

value for both the UPDATE and INSERT parts of the statement. 

UPDATE Sales SET ItemCount = Itemcount + 1 WHERE (ItemNbr = 10 AND 

SaleDate = '05/30/2005') ELSE INSERT INTO Sales (20, '05/30/2005', 1); 

The primary index values for the UPDATE and the INSERT must be the same. In this case, an 

error is returned to the user indicating that the primary index value must be the same for both 

the UPDATE and the INSERT. 




Example 3 (Error: unqualified primary index) 

This example demonstrates an upsert statement that does not specify the primary index in the 

WHERE clause. 

UPDATE Sales SET ItemCount = ItemCount + 1 WHERE SaleDate = '05/30/2005' 

ELSE INSERT INTO Sales (10, '05/30/2005', 1); 

When the primary index is not fully specified in the UPDATE of an upsert statement, an allrow 

scan to find rows to update might result. This is again not the purpose of upsert, and an 

error is returned to the user. 

Example 4 (Error: missing ELSE) 

This example demonstrates an upsert statement with a missing ELSE keyword. 


SaleDate = '05/30/2005') INSERT INTO Sales (10, '05/30/2005', 1); 

Example 5 (Error: INSERT-SELECT) 

This example demonstrates an upsert statement that specifies INSERT … SELECT. 


SaleDate = '05/30/2005') ELSE INSERT INTO Sales SELECT * FROM NewSales 

WHERE (ItemNbr = 10 AND SaleDate = '05/30/2005'); 

The INSERT part of an upsert may not use a subquery to specify any of the inserted values. In 

this case, a syntax error is returned. 

Example 6 (Error: UPDATE-FROM) 

This example demonstrates an upsert statement that specifies UPDATE-FROM. 

UPDATE Sales FROM NewSales SET Sales.ItemCount = NewSales.ItemCount 

WHERE Sales.ItemNbr = NewSales.ItemNbr ELSE INSERT INTO Sales (10, '05/ 

30/2005', 1); 

The SET clause may not use a FROM clause table reference in the expression for the updated 

value for a column, and an error is returned. 

Example 7 (Error: UPDATE-WHERE SUBQUERIES) 

This example demonstrates an upsert statement that specifies UPDATE-WHERE 

SUBQUERIES. 

UPDATE Sales SET ItemCount = ItemCount + 1 WHERE ItemNbr IN (SELECT 

ItemNbr FROM NewSales) ELSE INSERT INTO Sales (10, '05/30/2005', 1); 

The WHERE clause of the UPDATE may not use a subquery for any purpose. In this case, 

error ERRTEQUPSCOM is returned. 

Example 8 (Error: UPDATE-PRIMARY INDEX) 

This example demonstrates an upsert statement that tries to update a primary index value. 

UPDATE Sales SET ItemNbr = 20 WHERE (ItemNbr = 10 AND SaleDate = '05/30/ 

2005') ELSE INSERT INTO Sales (20, '05/30/2005', 1); 

Unreasonable updates or updates that change the primary index values are not allowed in an 

upsert statement, and an error is returned. 




Example 9 (Valid Upsert UPDATE) 

This example demonstrates a successful upsert statement that updates a row. 



After all of the rules have been validated, the row with ItemNbr = 10 and SaleDate = '05/30/ 

2005' gets updated. A successful update of one row results. 

Example 10 (Valid Upsert INSERT) 

This example demonstrates a successful upsert statement that inserts a row. 



After all of the rules have been validated and no row was found with Item = 20 and SaleDate = 

'05/30/2005' for the UPDATE, a new row is inserted with ItemNbr = 20. A successful insert of 

one row results. 


CHAPTER 4 

Troubleshooting 

This chapter provides a description of user aids for identifying and correcting errors that 

might occur during a Teradata TPump task. Foremost among these tools are a large number of 

error messages. For more information on error messages, refer to Messages. 

Troubleshooting information in this chapter includes: 

• Early Error Detection 

• Error Types 

• Error Messages 

• Reading Teradata TPump Error Tables 

• Teradata TPump Performance Checklist 

Early Error Detection 

The Teradata TPump utility avoids wasting time and resources on a task that contains 

terminating errors in either input statements, commands, or both. To accomplish this, 

statements and commands for a task are acquired and analyzed for detectable syntax and 

other errors before a Teradata TPump task is initiated on Teradata Database. 

When a BEGIN LOAD command invokes Teradata TPump, and the utility can complete an 

error-free pass, it proceeds. If not, Teradata TPump cleans up and terminates after an error 

pass. Teradata TPump uses Teradata Database to detect errors in the set of DML statements 

for the task. The first erroneous statement terminates Teradata TPump. 

Error Types 

Most errors are fatal, resulting in termination of Teradata TPump. The exceptions to this 

general rule are as follows: 

• User-specified SQL commands fail with no adverse effect. The variable &SYSRC is set, and 

if the script tests this variable it can stop the job if necessary. 

• Data-related errors in the database can reach the user-specified error limit before 

terminating the job. A list of data related errors is provided in Table 29. 

• Errors that can be retried. The error numbers for these types of errors are: 2595, 2631, 

2639, 2641, 2826, 2834, 2835, 3110, 3111, 3231, 3120, 3319, 3598, 3603, 5991, 6699, 8018, 

and 8024. 


Chapter 4: Troubleshooting 

Error Messages 

• When Teradata TPump sends SQL statement to Teradata Database in Prepare mode, 

Teradata TPump treats warnings (messages sent back with SUCCESS parcels) as user 

errors and exits with error code 8. 


Teradata Database error message gpt errors that can be fixed and resubmitted are 2631, 2639, 

2641, 2834, 2835, 3110, 3111, 3120, 3127, 3178, 3598, 3603, and 8024. 

Teradata TPump ignores errors on Teradata SQL statements outside of the Teradata TPump 

task; that is, before the BEGIN LOAD command or after the END LOAD command. The 

Teradata TPump job continues and no return code is returned, although Teradata Database 

error messages are displayed. 

When Teradata TPump encounters errors caused by a Teradata Database failure, it neither 

terminates the job nor produces a return code. When Teradata Database recovers, Teradata 

TPump restarts the job and continues without user intervention. Teradata Database failure 

messages are 2825, 2826, 2827, 2828, 3897, and 8018. 

When one of these errors occur, a row is inserted into Teradata TPump’s error table for the 

statement or data record in question. If the error occurs for one of the statements in a 

multiple-statement request, the remaining statements are re-driven. 

The retryable errors are automatically retried up to 16 times if retry times are not specified. 

For the complete text and explanation of error messages, refer to Messages. 

A row is inserted into Teradata TPump’s error table for the statement in error. If the error 

occurs for one of the statements in a multiple-statement request, then the remaining 

statements are re-driven. These errors include the conditions listed in Table 29. 

Table 29: Teradata TPump Error Conditions 

Error 

Description 

2603 Bad argument for SQRT function. 

2604 Bad argument involving %TVMID.%FLDID for SQRT function. 

2605 Bad argument for LOG function. 

2606 Bad argument involving %TVMID.%FLDID for LOG function. 

2607 Bad argument for LN function. 

2608 Bad argument involving %TVMID.%FLDID for LN function. 

2614 Precision loss during expression evaluation. 

2615 Precision loss calculating expression involving %TVMID.%FLDID. 

2616 Numeric overflow occurred during computation. 

2617 Overflow occurred computing an expression involving %TVMID.%FLDID. 




Table 29: Teradata TPump Error Conditions (continued) 

Error 

Description 

2618 Invalid calculation: division by zero. 

2619 Division by zero in an expression involving %TVMID.%FLDID. 

2620 The format or data contains a bad character. 

2621 Bad character in format or data of %TVMID.%FLDID. 

2622 Bad argument for ** operator. 

2623 Bad argument involving %TVMID.%FLDID for ** operator. 

2650 Numeric Processor Operand Error. 

2651 Operation Error computing expression involving %TVMID.%FLDID. 

2665 Invalid date. 

2666 Invalid date supplied for %TVMID.%FLDID. 

2674 Precision loss during data conversion. 

2675 Numerical overflow occurred during computation. 



2682 Precision loss during data conversion. 

2683 Numerical overflow occurred during computation. 



2689 Non-nullable field was null. 

2700 Referential constraint violation: invalid Foreign Key value. 

2726 Referential constraint violation: cannot delete/update the Parent Key value. 

2801 Duplicate unique prime key error in %DBID.%TVMID. 

2802 Duplicate row error in %DBID.%TVMID. 

2803 Secondary index uniqueness violation in %DBID.%TVMID. 

2805 Maximum row length exceeded in %TVMID. 

2814 Data size exceeds the maximum specified. 

2816 Failed to insert duplicate row into Teradata TPump target table. This error occurs if MARK 

DUPLICATE INSERT/UPDATE ROWS is specified and a duplicate row is detected. 





Error 

Description 

2817 Activity count greater than one for Teradata TPump UPDATE/DELETE. This error occurs 

if MARK EXTRA UPDATE/DELETE ROWS is specified and an activity count greater than 

one was seen. In this case, the error table row is inserted, but the corresponding UPDATE/ 

DELETE also completes. 

2818 Activity count zero for Teradata TPump UPDATE or DELETE. This error occurs if MARK 

MISSING UPDATE/DELETE ROWS is specified and an activity count of zero was seen. 

2844 Journal image is longer than maximum. 

2893 Right truncation of string data. 

3535 A character string failed conversion to a numeric value. 

3564 Range constraint: Check error in field%TVMID.%FLDID. 

3577 Row size overflow. 

3578 Scratch space overflow. 

3604 Cannot place a null value in a NOT NULL field. 

3751 Expected a digit for the exponent. 

3752 Too many digits in exponent. 

3753 Too many digits in integer or decimal. 

3754 Numeric precision error. 

3755 Numeric overflow error. 

3756 Numeric divided-by-zero error. 

3757 Numeric stack overflow error. 

3758 Numeric stack underflow error. 

3759 Numeric illegal character error. 

3996 Right truncation of string data. 

5317 Check constraint violation. 

5326 Operand of EXTRACT function is not a valid data type or value. 

5410 Invalid TIME literal. 

5411 Invalid TIMESTAMP literal. 

5991 Error during plan generation. 

6705 Illegally formed character string was encountered during translation. 

6706 The string contains an untranslatable character. 

6996 Invalid conversion or assignment operation on Period. 



Reading Teradata TPump Error Tables 


Error 

Description 

7433 Invalid time. 

7441 Date not corresponding to an existing era. 

7442 Invalid era. 

7451 Invalid timestamp. 

7452 Invalid interval. 

7453 Invalid field overflow. 

7454 DateTime field overflow. 

7455 Invalid time specified. 

9102 Invalid CAST. The source character value must be valid for casting as PERIOD. 


Teradata TPump error tables are a diagnostic device that help you locate and fix problems. For 

more information, refer to the description of these tables in “BEGIN LOAD”. 

Occasionally, Teradata TPump encounters rows that cannot be correctly processed. When this 

happens, Teradata TPump creates a row in the error table that is produced for each target 

table. Error tables are structured to provide enough information to reveal the cause of a 

problem and allow correction. 

In the case of missing, duplicate, or extra rows, these are noted in the error table only if the 

DML command specifies that requirement with the MARK parameter, which is the default for 

DML statements except for those participating in an upsert. 

Three error codes relate specifically to the incidence of missing, duplicate, and extra rows: 

• 2816: Failed to insert duplicate row into Teradata TPump target table. 

This error occurs if MARK DUPLICATE INSERT/UPDATE ROWS is specified and a 

duplicate row is detected. 

• 2817: Activity count greater than one for Teradata TPump UPDATE/DELETE. 

This error occurs if MARK EXTRA UPDATE/DELETE ROWS is specified and an activity 

count greater than one resulted. In this case, the error table row is inserted, but the 

corresponding UPDATE/DELETE also completes. 

• 2818: Activity count zero for Teradata TPump UPDATE or DELETE. 

This error occurs if MARK MISSING UPDATE/DELETE ROWS is specified and an 

activity count of zero resulted. 




Avoiding Data Errors 

Acquisition Error Table 

The following data-related conditions can all cause records to be written to the error table: 

• A non-existent target table 

• Inadequate privileges to the target table 

• Mismatched table schema and Teradata TPump DML 

• Attempting to store NULL value in a NOT NULL table column 

• Out-of-range values 

• Data conversion errors, which require input data to be corrected 

To help prevent performance issues, it is important to ensure that your data sources generate 

data records that are valid for the characteristic of the target tables. 

The error table is primarily used to hold information about errors that occur while Teradata 

Database is trying to redistribute the data during the acquisition phase. If Teradata Database is 

unable to build a valid primary index, some application phase errors may be put into this 

table. 

Table 30 defines the Acquisition Error Table, with column entries comprising the unique 

primary index. 

Table 30: Acquisition Error Table 

Column Data Type Definition 

ImportSeq byteint Sequence number assigned to the IMPORT command in which 

the error occurred. 

DMLSeq byteint Sequence number assigned to the DML command in which the 

error occurred. 

SMTSeq byteint Sequence number of the DML statement in the DML command 

that was being executed while this error occurred. 

ApplySeq byteint Sequence number of apply clause in IMPORT command 

executing when error occurred. 

SourceSeq integer The data row number in the client file that the DBC was 

building when the error occurred. 

DataSeq byteint The data source where the record resides. 

ErrorCode char(255) The database code for the error. 

ErrorMsg char The corresponding error message for the error code. 

ErrorField smallint The number of the field in error if it can be determined. 

HostData varbyte (63677) The first 63,677 bytes of client data associated with the error. 

LoadStartTime 

The beginning of the job time. On restart, LoadStartTime is the 

beginning of the restart time. 




Interpreting Error Table Information 

The following Teradata TPump task describes how to interpret the error table information to 

isolate and fix the problem. This task is greatly abbreviated, containing only the DML 

command and the IMPORT command. A probable sequence of actions for locating and fixing 

the problem follows the task. 

SEQ TYPE SEQ # Statement 

-------- --- ------------------------------------------------------- 

DML 001 .DML LABEL FIRSTDML; 

STMT 001 INSERT INTO table1 VALUES( :FIELD1, :FIELD2 ); 

STMT 002 UPDATE table2 SET field3 = :FIELD3 WHERE field4 =:FIELD4; 

DML 002 .DML LABEL SECNDDML; 

STMT 001 DELETE FROM table3 WHERE field3 = :FIELD3; 

IMPORT 001 .IMPORT INFILE file1 LAYOUT layout1 

APPLY 001 APPLY FIRSTDML; 

IMPORT 002 .IMPORT INFILE file2 LAYOUT layout2 

APPLY 001 APPLY FIRSTDML 

APPLY 002 APPLY SECNDDML; 

In this example, the Statement column represents the user entry. The SEQ # and SEQ TYPE 

columns are the Sequence Number and Sequence Type assigned to each statement. If an error 

occurs while using this task and the information in the following error table is displayed, 

where the error occurred and what was being executed at the time of the error can be 

determined. 

ImportSeq DMLSeq SMTSeq ApplySeq SourceSeq DBCErrorCode DBCErrorField 

--- --- --- --- --------- ----- ------------ 

002 001 002 001 20456 2679 field3 

The following sequence provides a series of analytical steps for extracting and interpreting the 

information in this row of the error table. 

1 Check the DMLSeq field to find the statement being executed. It contains the sequence 

number 001. 

2 Check the SMTSeq field. The sequence number 002 in this field indicates that the error 

occurred while executing: change this statement of the first DML command, which is the 

UPDATE statement in the above task. 

3 Verify that the script shows that the DML command is used twice, once in each IMPORT. 

4 The value of 002 in the ImportSeq field shows that the error occurred in the second 

IMPORT clause. 

5 The value of 001 in the ApplySeq field indicates that the error occurred in the first apply of 

that clause, which was being executed when the error occurred. 

6 The value of 2679 in the DBCErrorCode field shows: 

The format or data contains a bad character 

which indicates that bad data is coming from the client. 



Teradata TPump Performance Checklist 

7 The ErrorField field of the error row shows that the error occurred while building field3 of 

the table. 

8 The script then shows that the error occurred when field3 was being built from :FIELD3 in 

the client data. 

9 The LAYOUT clause in the script shows where the problem data is positioned within the 

row coming from the client. 

10 The script shows that the IMPORT clause with the error was loading file2, and indicates 

what error occurred, which statement detected the error, and which file has the error. 

11 The SourceSeq field of the error table pinpoints the problem location in the 20456th 

record of this file. The problem is isolated and can now be fixed. 

Most problems in the error tables do not require as much research as this example. This 

error was selected in order to use all of the information in the error table. As a rule, only 

one or two error table items need to be looked at to locate and correct problems. 

Teradata TPump Performance Checklist 

The following checklist helps to isolate and analyze Teradata TPump performance problems 

and their causes. 

• Monitor the Teradata TPump job using the Monitor macros. Determine whether the job is 

making progress. 

• Check for locks using the Teradata Database Showlocks utility. Transaction locks can be 

detected by checking for blocked Teradata utilities that use the performance monitor 

feature of Teradata Database (Teradata Manager). 

• Check table DBC.Resusage for problem areas (for example, data bus capacity or CPU 

capacity at 100% for one or more processors). 

• Avoid large error tables, if possible, because error processing is generally expensive. 

• Verify that the primary index is unique. Nonunique primary indexes can cause severe 

Teradata TPump performance problems. 


CHAPTER 5 

Using INMOD and Notify Exit Routines 

This chapter provides a detailed description of the INMOD feature used in Teradata TPump 

and the notify exit routines that are associated with INMODs. 

An INMOD is a user-generated module called by the IMPORT command, which reads data 

from a data source. Teradata TPump honors INMODs developed for other load utilities. 

Owing to the complexity of this feature, it has been given a separate place in this chapter, 

rather than including it in the command syntax descriptions. 

The following information is included in this chapter: 

• Overview 

• Using INMOD and Notify Exit Routines 

Overview 

INMOD Routines 

This section provides an overview of the INMOD and notify exit routines. Information 

includes INMOD routines, notify exit routines, programming languages, programming 

structure, routine entry points, the Teradata TPump/INMOD routine interface, the Teradata 

TPump/notify exit routine interface, and rules and restrictions for using routines. 

The term INMOD is an acronym for input modification routines. An INMOD is a 

user-written routine used by Teradata TPump to supply or preprocess input records before 

they are sent to Teradata Database. 

An INMOD routine can be used to supply input records or to perform preprocessing tasks on 

the input records before passing them to Teradata TPump. Such tasks, for example, could: 

• Generate records to be passed to Teradata TPump. 

• Validate data records before passing them to Teradata TPump. 

• Read data directly from one or more database systems such as IMS, Total. 

• Convert fields in a data record before passing it to Teradata TPump. 

The INMOD is specified as part of the IMPORT command. See “IMPORT” for INMOD 

syntax information. 


Chapter 5: Using INMOD and Notify Exit Routines 

Overview 

Notify Exit Routines 

A notify exit routine specifies a predefined action to be performed whenever certain 

significant events occur during a Teradata TPump job. 

Notify exit routines are especially useful in an operator-free environment where job 

scheduling relies heavily on automation to optimize system performance. 

For example, by writing an exit routine in C (without using CLIv2) and using the NOTIFY . . . 

EXIT option of the BEGIN LOAD command, a routine can be provided to detect whether a 

Teradata TPump job succeeds or fails, how many records were loaded, what the return code 

was for a failed job, and so on. 

Programming Languages 

Teradata TPump is written in: 

• IBM C for channel-attached z/OS client systems 

• C for network-attached UNIX and Windows client systems 

INMOD and notify exit routines can be written in the programming languages listed in 

Table 31. They are dependent on the platform which runs Teradata TPump: 

Table 31: INMOD Routines 

Platform 

Routines 

z/OS • INMOD routines in IBM C 

• Notify exit routines in IBM C 

UNIX, Windows • INMOD and notify exit routines in C 



Overview 

Programming Structure 

Table 32 defines the structure by programming language for communicating between 

Teradata TPump and INMOD or notify exit routines. 

Table 32: Programming Routines by Language 

Routine Language 

C 

Programming Structure 

First parameter: 

struct { 

long Status; 

long RecordLength; 

char buffer[xxxxx]; 

} 

Note: In the char buffer specification, the buffer length xxxxx is: 

• 32004 for Teradata for Windows 

• 64004 for Teradata Database for UNIX 

Second parameter: 

struc 

long seqnum; 

short parmlen; 

char parm[80]; 

} 

In each structure, the records must be constructed so that the left-to-right order of the data 

field corresponds to the order of the field names specified in the Teradata TPump LAYOUT 

command and subsequent FIELD, FILLER, and TABLE commands. 

Routine Entry Points 

Table 33 lists the entry points for INMOD routines. 

Table 33: Entry Points for INMOD Routines 

INMOD Routine Language 

IBM C on z/OS platforms 

z/OS platform 

C on UNIX and Windows platforms 

Entry Point 

_dynamn 

DYNAMN 

_dynamn (or BLKEXIT*) 

*Only for FDL-compatible INMODs compiled and linked 

with BLKEXIT as the entry point. When the FDL-compatible 

INMOD is used, USING(“FDLINMOD”) must be specified 

in the IMPORT statement. 

Table 34 lists the entry points for Notify Exit routines. 



Overview 

Table 34: NOTIFY EXIT Routine 

Notify Exit Routine Language 

IBM C on z/OS platforms 

z/OS platform 

C on UNIX and Windows platforms 

Entry Point 

_dynamn 

DYNAMN 

_dynamn 

The Teradata TPump/INMOD Routine Interface 

Teradata TPump exchanges information with an INMOD routine by using the conventional 

parameter register to point to a parameter list of two 32-bit addresses. 

The first 32-bit address points to a three-value structure consisting of status code, length, and 

body. The second 32-bit address points to a data structure containing a sequence number and 

a parameter list. 

Status Code 

Status Code is a 32-bit signed binary value that carries information in both directions. 

Table 35 lists Teradata TPump-to-INMOD interface uses eight status codes, as defined in the 

table. 

Table 35: Teradata TPump-to-INMOD Status Codes 

Value 

Description 

0 Teradata TPump is calling for the first time and expects the INMOD routine to return a 

record. 

At this point, the INMOD routine should perform its initialization tasks before sending a 

data record to Teradata TPump. 

1 Teradata TPump is calling, not for the first time and expects the INMOD routine to return 

a record. 

2 The client system has been restarted, the INMOD routine should reposition to the last 

checkpoint, and Teradata TPump is not expecting the INMOD routine to return a data 

record. 

Note: If the client system restarts before the first checkpoint, Teradata TPump sends entry 

code 0 to re-initialize. Repositioning information, provided by the INMOD after a code 3, 

is read from the restart log table and returned in the buffer normally used for the data 

record. 

3 A checkpoint has been written, the INMOD routine should remember the checkpoint 

position, and Teradata TPump does not expect the INMOD routine to return a data 

record. 

In the buffer normally used to return data, the INMOD should return any information 

(up to 100 bytes) needed to reposition to this checkpoint. The utility saves this 

information in the restart log table. 



Overview 

Table 35: Teradata TPump-to-INMOD Status Codes (continued) 

Value 

Description 

4 Teradata Database has failed, the INMOD routine should reposition to the last 

checkpoint, and Teradata TPump is not expecting the INMOD routine to return a data 

record. 

Note: If the database restarts before the first checkpoint, Teradata TPump sends entry 

code 5 for cleanup, and then it sends entry code 0 to re-initialize. 

Teradata TPump reads the repositioning information, provided by the INMOD after a 

code 3, from the restart log table and returned to the INMOD in the buffer normally used 

for the data record. 

5 The Teradata TPump job has ended and the INMOD routine should perform any 

required cleanup tasks. 

6 The INMOD should initialize and prepare to receive records. 

7 The next record is available for the INMOD. 

Table 36 explains the two status codes used by the INMOD-to-Teradata TPump interface. 

Table 36: INMOD-to-Teradata TPump Interface Status Codes 

Value 

Description 

0 A record is being returned as the body value for a read call (code 1). 

For calls other than read, a value of 0 indicates successful completion. 

Any nonzero 

value 

The INMOD routine is at an end-of-file condition for a read call (code 1). For calls 

other than read, a nonzero value indicates a processing error that terminates 

Teradata TPump. 

Length 

Length is the 32-bit binary value that the INMOD routine uses to specify the length, in bytes, 

of the data record. The INMOD routine can use a length value of zero to indicate an end-offile 

condition. 

Body 

Body is the area where the INMOD routine places the data record. Maximum record length is 

31K or 31,744 bytes for Teradata for Windows. Maximum record length for Teradata Database 

for UNIX is 62K or 63,488 bytes. 

Sequence Number 

Sequence number is a 4-byte integer record counter portion of the source sequence number. 

Parameter List 

The parameter list in the second 32-bit address consists of the following: 

• VARCHAR specification 



Overview 

• Two-byte length specification, m 

• The m-byte parms string, as parsed and presented by Teradata TPump 

Caution: 

To prevent data corruption, INMOD routines that cannot comply with these protocols should 

terminate if they encounter a restart code 2, 3, or 4. To support proper Teradata TPump restart 

operations, INMOD routines must save and restore checkpoint information as described here. 

If the INMOD saves checkpoint information in some other manner, a subsequent restart/ 

recovery operation could result in data loss or corruption. 

Teradata TPump/Notify Exit Routine Interface 

Teradata TPump accumulates operational information about specific events that occur during 

a Teradata TPump job. If the BEGIN LOAD command includes a NOTIFY option with an 

EXIT specification, then, when the specific events occur, Teradata TPump calls the named 

notify exit routine and passes to it: 

• An event code to identify the event 

• Specific information about the event 

Table 37 lists the event codes and describes the data that Teradata TPump passes to the notify 

exit routine for each event. (See the description of the NOTIFY option in the “BEGIN LOAD” 

command description in Chapter 3: “Teradata TPump Commands,” for a description of the 

events associated with each level of notification—low, medium, high, and ultra.) 

Note: To support future enhancements, always make sure that the notify exit routines ignore 

invalid or undefined event codes, and that they do not cause Teradata TPump to terminate 

abnormally. 

Table 37: Events Passed to the Notify Exit Routine 

Event 

Event 

Code Event Description Data Passed to the Notify Exit Routine 

Initialize 0 Successful processing of the NOTIFY 

option of the BEGIN LOAD 

command. 

• Version ID length—4-byte unsigned integer 

• Version ID string—32-character (maximum) array 

• Utility ID—4-byte unsigned integer 

• Utility name length—4-byte unsigned integer 

• Utility name string—36-character (maximum) 

array 

• User name length—4-byte unsigned integer 

• User name string—64-character (maximum) array 

• Optional string length—4-byte unsigned integer 

• Optional string—80-character (maximum) array 

File or INMOD 

open 

1 Successful processing of the IMPORT 

command that specifies the file or 

INMOD routine name 

• File name length—4-byte unsigned integer 

• File name—256-character (maximum) array 

• Import number—4-byte unsigned integer 

Checkpoint begin 2 Teradata TPump is about to perform 

a checkpoint operation 

Record number—4-byte unsigned integer 



Overview 

Table 37: Events Passed to the Notify Exit Routine (continued) 

Event 

Event 


Import begin 3 The first record is about to be read for 

each import task 

Import end 4 The last record has been read for each 

import task. The returned data is the 

record statistics for the import task 

Error table 5 Processing of the SEL COUNT(*) 

request completed successfully for the 

error table 

Import number—4-byte unsigned integer 


• Records read—4-byte unsigned integer 

• Records skipped—4-byte unsigned integer 

• Records rejected—4-byte unsigned integer 

• Records sent to Teradata Database—4-byte 

unsigned integer 

• Data errors—4-byte unsigned integer 

• Table name—128-byte character (maximum) array 

• Number of rows—4-byte unsigned integer 


restart 

6 Teradata TPump received a crash 

message from Teradata Database or 

from the CLIv2 

No data accompanies the Teradata Database restart 

event code 

CLIv2 error 7 Teradata TPump received a CLIv2 

error 

Error code—4-byte unsigned integer 


error 

8 Teradata TPump received a Teradata 

Database error that will produce an 

exit code of 12 

Error code—4-byte unsigned integer 

Note: Not all Teradata Database errors cause this 

event. A 3807 error, for example, while trying to drop 

or create a table, does not terminate Teradata TPump. 

Exit 9 Teradata TPump completed a load 

task 

Table statistics 10 Teradata TPump has successfully 

written the table statistics 

Checkpoint end 11 Teradata TPump successfully 

completed the checkpoint operation 

Exit code—4-byte unsigned integer 

• Type (I = Insert, U = Update, or D = Delete) — 

1-byte character variable 

• Database name—64-character (maximum) array 

• Table/macro name—64-character (maximum) 

array 

• Activity count—4-byte unsigned integer 

Record number—4-byte unsigned integer 



Overview 

Table 37: Events Passed to the Notify Exit Routine (continued) 

Event 

Event 


Interim run 

statistics 

12 Teradata TPump is updating the 

Monitor Interface table, has just 

completed a checkpoint, or has read 

the last record for an import task. The 

returned data is the statistics for the 

current load 


• Statements sent to Teradata Database—4-byte 


• Requests sent to Teradata Database—4-byte 


• Records read—4-byte unsigned integer 

• Records skipped—4-byte unsigned integer 

• Records rejected—4-byte unsigned integer 

• Records sent to Teradata Database—4-byte 


• Data errors—4-byte unsigned integer 

DML error 13 Teradata TPump received a Teradata 

Database error that was caused by 

DML and will introduce an error-row 

insert to the error table 


• Error code—4-byte unsigned integer 

• Error message—256-character (maximum) array 

• Record number—4-byte unsigned integer 

• Apply number—1-byte unsigned char 

• DML number—1-byte unsigned char 

• Statement number—1-byte unsigned char 

• Record data—64,004-character (maximum) array 

• Record data length—4-byte unsigned integer 

• Feedback—a pointer to 4-byte unsigned integer 

“Feedback” always points to integer 0 when it is passed 

to the user exit routine. The user may change the value 

of this integer to 1 to instruct Teradata TPump not to 

log the error to the error table. In this case, Teradata 

TPump will not log the error, but continue other 

regular process on this error. 



Overview 

Rules and Restrictions for Using Routines 

The following sections describe the operational rules and restrictions for using INMOD and 

notify exit routines in Teradata TPump jobs. 

Specifying Routines 

INMOD and notify exit routine names must be unique within the system. 

A Teradata TPump job can specify one INMOD routine with each IMPORT command. These 

specifications can be to the same or different INMOD routines. 

In addition to the multiple INMOD routines, each Teradata TPump job can specify an exit 

routine with the NOTIFY... EXIT option of the BEGIN LOAD command. 

Compiling and Linking Routines 

The methods for compiling and linking routines vary with the operating system. The 

following sections describe the methods for z/OS, UNIX, and Windows. 

Using z/OS 

On channel-attached z/OS client systems, INMOD and notify exit routines must be compiled 

under IBM C. 

Using UNIX 

On network-attached UNIX client systems, INMOD and notify exit routines must: 

• Be compiled with the MetaWare High C compiler 

• Be linked into a shared object module 

• Use an entry point named _dynamn 

Using Windows 

On network-attached Windows client systems, INMOD and notify exit routines must: 

• Be written in C 

• Have a dynamn entry point that is a _declspec 

• Be saved as a Dynamic Link Library (DLL) file 

For more information, see the examples in Appendix C: “INMOD and Notify Exit Routine 

Examples” for sample programs and procedures that compile and link INMOD and notify 

exit routines for the operating system environment. 

Addressing Mode on z/OS Systems 

Either 31-bit or 24-bit addressing for INMOD routines can be used on channel-attached 

systems. The 31-bit mode provides access to more memory, which enhances performance for 

Teradata TPump jobs with a large number of sessions. 

Use the following linkage parameters to specify the addressing mode when building INMOD 

routines for z/OS systems: 

• For 31-bit addressing: AMODE(31) RMODE(24) 

• For 24-bit addressing: AMODE(24) RMODE(24) 



Overview 

INMOD Routine Compatibility with Other Load Utilities 

FDL-compatible INMOD routines that were created for FastLoad by including the 

FDLINMOD parameter as the USING (parms) option of the IMPORT command can be used. 

Using this parameter provides compatible support operations except for the way 

checkpointing is performed: 

• If a Teradata TPump job uses the FROM, FOR, or THRU options to request a range of 

records from an FDL-compatible INMOD routine, then Teradata TPump bypasses any 

default record checkpoint function. By default, Teradata TPump takes a checkpoint every 

15 minutes. The Teradata TPump checkpoint function can be bypassed by specifying a 

CHECKPOINT rate of zero in your BEGIN LOAD commands. 

If Teradata Database experiences a restart/recovery operation, Teradata TPump starts over 

and gets the records again from the beginning of the range. 

Under these same circumstances, if a BEGIN LOAD command included a CHECKPOINT 

rate other than zero, Teradata TPump terminates with an error condition. 

• If a Teradata TPump job does not request a range of records, then Teradata TPump 

performs checkpointing either by default (every 15 minutes) or per the job specifications. 

If Teradata Database experiences a restart/recovery operation and the INMOD routine 

supports recovery, Teradata TPump continues the data acquisition activity from the last 

recorded checkpoint. 

Note, however, that the source sequence numbers generated by Teradata TPump may not 

correctly identify the sequence in which the INMOD routine supplied the records. The 

data is still applied correctly, however, despite this discrepancy. 

An FDL-compatible INMOD routine cannot be specified with the INFILE specification of a 

Teradata TPump IMPORT command. 

When an INMOD routine is specified with the INFILE specification: 

• Teradata TPump performs the file-read operation 

• The INMOD routine acts as a pass-through filter 

The combination of an FDL-compatible INMOD routine with a Teradata TPump INFILE 

specification is not valid because an FDL-compatible INMOD routine must always perform 

the file read operation. 

Checkpoints 

To support Teradata TPump restart operations, the INMOD routine must support checkpoint 

operations, as described in “The Teradata TPump/INMOD Routine Interface” on page 206. 

If an INMOD routine that does not support the checkpoint function is used, the job may 

encounter problems when Teradata TPump takes a checkpoint. 

By default, Teradata TPump takes a checkpoint every 15 minutes. The Teradata TPump 

checkpoint function can be bypassed by specifying a CHECKPOINT rate of zero in the 

BEGIN LOAD command; that way, the job completes without taking a checkpoint. 

Though this would nullify the Teradata TPump restart/reload capability, it would allow an 

INMOD routine that does not support the checkpoint function to be used. 





This section provides some specific information required for using INPUT and notify exit 

routines in Teradata TPump. Topics include Teradata TPump-specific restrictions, the 

Teradata TPump/INMOD interface for different client operating systems, preparation of the 

INMOD program, INMOD input values, INMOD output values, and programming 

specifications for Unix-based and Windows clients. 

Teradata TPump-specific Restrictions 

INMOD names should be unique within the system. INMODs are not re-entrant and cannot 

be shared by two Teradata TPump (or FastLoad, MultiLoad, or FastExport) sessions at the 

same time. 

Some changes have been made to the INMOD utility interface for Teradata TPump because of 

operational differences between Teradata TPump and the older utilities. For compatibility 

with INMODs, the FDLINMOD parameter should be used. The use of this parm provides 

support of existing INMODs, with the following restrictions: 

• When the FDLINMOD parm is used, INMODs that are compatible with other utilities 

may be used. However, if a range of records is requested from an FDL-compatible INMOD 

(using FROM, FOR, or THRU on the IMPORT command), Teradata TPump bypasses any 

default record checkpointing. If there is a recovery under these circumstances, Teradata 

TPump starts over and acquires the records again from the beginning of the range. Under 

these same circumstances, if checkpointing is requested by specifying the CHECKPOINT 

parameter on the BEGIN LOAD command, Teradata TPump terminates with an error. 

• If a range of records is not requested when using an FDL-compatible INMOD, Teradata 

TPump performs checkpointing, either by default or by the user’s request. If there is a 

recovery and the INMOD supports recovery, Teradata TPump continues its data 

acquisition from the last recorded checkpoint. However, the source sequence numbers 

generated by Teradata TPump may not correctly identify the sequence in which the 

INMOD supplied the records. Despite this discrepancy, the data is still applied correctly. 

• An FDL-compatible INMOD routine cannot be specified in conjunction with the INFILE 

specification of a Teradata TPump IMPORT command. If an INMOD is specified together 

with the INFILE specification, Teradata TPump performs the file read operation and the 

INMOD acts as a pass-through filter. Since an FDL-compatible INMOD always performs 

the file read operation, it is not valid with a Teradata TPump INFILE specification. 

Warning: 

The Teradata TPump default is to take a checkpoint every 15 minutes. With other loading 

utilities, checkpointing must be explicitly requested. If an attempt to run with an INMOD that 

does not use checkpointing is made, problems may arise when Teradata TPump defaults to a 

checkpoint mode. To avoid this condition, Teradata TPump checkpointing by specifying zero 

can be disabled as the checkpoint rate parameter on the BEGIN LOAD command, so that the 

checkpoint is never reached. This may be imperative for users who do not have INMODs capable 

of checkpointing. 




Teradata TPump/INMOD Interface 

This section discusses the Teradata TPump/INMOD Interface for different client operating 

systems: 

Teradata TPump/INMOD Interface on IBM Client-based Systems 

The use of an INMOD is specified on the IMPORT command. On IBM client-based systems, 

Teradata Database interfaces with INMODs written in C. 

Examples of these INMODs are presented in Appendix C: “INMOD and Notify Exit Routine 

Examples”. An optional parms string to be passed to the INMOD may also be specified on the 

IMPORT command. Teradata TPump imposes the following syntax rules for this string: 

• The parms string may include one or more character strings, each delimited on either end 

by apostrophes or quotation marks. The maximum size of the parms string is 1 KB. 

• If a FastLoad INMOD is used, the parms string of the IMPORT command must be 

FDLINMOD. 

• The parms string passed to an INMOD includes the parentheses used to specify the parm. 

Thus, if the IMPORT specifies USING ('5'), the entire expression ('5') is passed to the 

INMOD. 

• Parentheses within delimited character strings or comments have the same syntactical 

significance as alphabetic characters. 

• In the parms string that Teradata TPump passes to the INMOD routine, each comment is 

replaced by a single blank character. 

• In the parms string that Teradata TPump passes to the INMOD routine, each consecutive 

sequence of whitespace characters, such as blank, tab, and so on, that appears outside of 

delimited strings, is replaced by a single blank character. 

• FDLINMOD is used for compatibility by pointing to a data structure that is the same for 

BDL and FDL INMODs. 

Teradata TPump/INMOD Interface on UNIX-based Systems 

On UNIX-based client platforms, Teradata TPump is written in C and, therefore, the INMOD 

procedure is dynamically loaded at runtime, rather than link-edited into the Teradata TPump 

module or operated as a separate executable program. 

The runtime loader requires that the INMOD module be compiled and linked as a shared 

object, and that the entry point for the procedure be named _dynamn. 

The use of an INMOD is specified in the IMPORT command. On UNIX-based systems, 

Teradata Database interfaces only with INMODs written in C. An example of a C INMOD is 

presented in Appendix C: “INMOD and Notify Exit Routine Examples”. An optional parms 

string to be passed to the INMOD may also be specified on the IMPORT command. Teradata 

TPump imposes these syntax rules: 

• One INMOD is allowed for each IMPORT command. Multiple IMPORTs are allowed; 

these may use the same or different INMODs. 

• The input filename parameter specified on the IMPORT command must be the 

fully qualified UNIX pathname for the input file. 




• The INMOD filename parameter specified on the IMPORT command must be the 

fully qualified UNIX pathname of the INMOD shared object file. 


by an apostrophe, or delimited on either end by a quotation mark. The maximum size of 

the parms string is 1k bytes. 


“FDLINMOD”. 

• The parms string as a whole must be enclosed in parentheses. 









FDL INMODs. 

Teradata TPump/INMOD Interface on Windows Systems 

On Windows client platforms, Teradata TPump is written in C and, therefore, the INMOD 

procedure is dynamically loaded at runtime, rather than link-edited into the Teradata TPump 

module or run as a separate executable program. 

The runtime loader requires that the INMOD module be compiled and linked as a Dynamic- 

Link Library (DLL) file, and that the point for the procedure be named _dynamn. 

The use of an INMOD is specified in the IMPORT command. On systems, Teradata 

Database interfaces only with written in C. An optional parms string to be passed to INMOD 

may also be specified on the IMPORT command. Teradata TPump imposes the following 

syntax rules: 

• One INMOD is allowed for each IMPORT command. Multiple are allowed; these may use 

the same or different INMODs. 

• The input filename parameter specified on the IMPORT command must be the fully 

qualified Windows pathname for the input file. 

• The INMOD filename parameter specified on the IMPORT command must be the fully 

qualified Windows pathname of the INMOD DLL file. 


by an apostrophe, or delimited on either end by a quotation mark. The maximum size of 

the parms string is 1k bytes. 


“FDLINMOD”. 

• The parms string as a whole must be enclosed in parentheses. 





Preparing the INMOD Program 







FDL INMODs. 

Preparing the INMOD Program 

This section describes the protocol used between Teradata TPump and an INMOD written for 

Teradata TPump. The protocols are applicable to all client platforms running Teradata 

TPump. Considerations applicable exclusively to UNIX-based clients are contained in 

“Programming INMODs for UNIX-based Clients” on page 218. 

On entry to an INMOD user exit routine for Teradata TPump, the conventional parameter 

register points to a parameter list of two 32-bit addresses. The first 32-bit address points to a 

data structure containing the following fields: 

• Return Code/Function Code, 4-byte integer. 

• Length, 4-byte integer, Length of the data record. 

• Data Record, Input data record buffer. The maximum length is: 

• 31K or 31,744 bytes for Teradata for Windows 

• 62K or 63,488 bytes for Teradata Database for UNIX 

INMOD Input Values 

Table 38 lists valid values of the Return Code/Function Code field and their meanings As 

input to the INMOD routine, as input to the INMOD routine. 

Table 38: INMOD Input Return Code Values 

Code 

Description 

0 Request for INMOD to initialize and return first record. 

1 Request for INMOD to return a record. 

2 Request for INMOD to reposition to last checkpoint because of client restart. Repositioning 

information, provided by the INMOD after a code 3, is read from the restart logtable and 

returned to the INMOD in the buffer normally used for the data record. 

3 Request for INMOD to take a checkpoint. In the buffer normally used to return data, the 

INMOD should return any information (up to 100 bytes) that it may need to reposition to 

this checkpoint. Teradata TPump then saves this information in its restart log table. 



INMOD Output Values 

Table 38: INMOD Input Return Code Values (continued) 

Code 

Description 

4 Request for INMOD to reposition to last checkpoint because of a Teradata Database failure. 

Repositioning information, provided by the INMOD after a code 3, is read from the restart 

log table and returned to the INMOD in the buffer normally used for the data record. 

5 Request for INMOD to wrap up at termination. 

6 Request for INMOD to initialize. 

7 Request for INMOD to receive first (next) record. 

INMOD Output Values 

Table 39 lists valid values of the Return Code field and their meanings, as output to the 

INMOD routine. 

Table 39: INMOD Output Return Code Values 

Code 

Description 

0 on read call (code 1) Indicates End Of File not reached. The length field should be 

set to the length of the output record. If an input record was 

supplied to the INMOD and it is to be skipped, set the length 

field to zero. If no input record was supplied, setting the 

length to zero acts as an End Of File. 

Non-0 on read call (code 1) 

Indicates End Of File. 

0 on non-read call (not code 1) Indicates successful operation. 

Non-0 on non-read call (not code 1) 

Indicates a processing error. Teradata TPump terminates. 

The second 32-bit address points to a data structure containing the following fields: 

• Sequence Number, 4-byte integer, Integer record counter portion of the source sequence 

number. 

• Parameter List, Varchar, 2-byte length, m, followed by the m-byte parms string as parsed 

and presented by Teradata TPump. 

INMODs that cannot comply with these protocols should terminate if a Restart Code 2, 

Code 3, or Code 4 is encountered. Otherwise, data might become corrupted. In order to be 

restartable, INMODs must make use of Teradata TPump to save and restore checkpoint 

information as described above. If the INMOD saves its checkpointing information privately, 

recovery might result in data corruption. 

Note: On z/OS, the module must reside in the steplib/joblib (for JCL), task library (for clist/ 

exec), or the system linklist (for any). 



Programming INMODs for UNIX-based Clients 


In addition to the techniques for preparing INMODs listed in “Preparing the INMOD 

Program” on page 216 which apply to all platforms, there are several rules that must be 

followed only for developing C INMODs for UNIX-based clients. These are: 

• The INMOD subroutine must be named _dynamn. 

• The INMOD must be compiled with the MetaWare High C compiler. 

• The compiled INMOD module must be linked into a shared object module. 

Compiling and Linking a C INMOD on a UNIX-based Client 

Note: For a description of the syntax diagrams used in this book, see Appendix A: “How to 

Read Syntax Diagrams.” 

The following syntax example can be used to compile a C INMOD on a UNIX-based client. 

Compile Syntax 

cc -c inmod.c 

3021A038 

where 


cc 

c 

inmod.c 

Description 

Program that invokes the MetaWare High C Compiler 

Linker option specifying to compile without linking to produce an output file 

(a.out) 

A C source module for the INMOD 

Use the following syntax example to link the object modules into a shared object module. 

Link Syntax 

, 

ld -dy -G inmod.o -o inmod.so 

HE05A016 

where 





ld 

dy 

G 

inmod.o 

o 

inmod.so 

Description 

Invokes the UNIX linker editor 

Specifies to use dynamic linking 

Specifies to create a shared object 

Describes an object module derived from the compile step (see above) 

Specifies the output filename; default is a.out 

Specifies the resulting shared object module 

This is the user-specified name in the IMPORT command. 

Note: Object modules can be linked into shared objects or shared libraries (i.e., 

.so or .sl extension respectively) on HP-UX Itanium. 

Compiling and Linking a C INMOD on Sun Solaris SPARC 

Use the following syntax example to compile a C INMOD on Sun Solaris SPARC client 

systems. 

cc -G 

-KPIC 

sourcefile.c 

-o shared-object-name 

2409B051 

where 


cc 

Description 

Invokes the MetaWare High C Compiler 

-G Specifies to create a shared object 

-KPIC 

sourcefile 

Is a compiler option that generates Position Independent Code (PIC) for all user 

exit routine 

Is a C source module for the INMOD 

-o Specifies the output file name 

shared-objectname 


This is the name specified as: 

• The INMOD modulename parameter of the IMPORT command of the 

TPump job script 

• The EXIT name parameter for the NOTIFY option of the BEGIN LOAD 

command of the TPump job script 

The shared-object-name can be any valid UNIX file name. 




Compiling and Linking a C INMOD on a Sun Solaris Opteron 

Use the following syntax example to compile a C INMOD on a Sun Solaris Opteron client 

system. 

cc 

-dy 

-G 

sourcefile.c 


2409A055 

where 


cc 

-dy 

Description 


Specifies to use dynamic linking 

-G Specifies to create a shared object 

sourcefile 

Is a C source module for the INMOD 




This is the name specified: 

• The INMOD modulename parameter of the IMPORT command of the 

Teradata TPump job script. 

• The EXIT name parameter for the NOTIFY option of the BEGIN LOAD 

command of the Teradata TPump job script. 

The shared-object-name can be any valid UNIX file name. 




Compiling and Linking a C INMOD on HP-UX PA RISC 

Use the following syntax example to compile a C INMOD on HP-UX PA RISC client. 


cc -Aa -D_HPUX_SOURCE +z +u1 -c sourcefile.c 

3021B002 

where 


-Aa 

- 

D_HPUX_SOU 

RCE 

cc 

Description 

Option that enables the compiler to conform to ANSI standards 

Enables the compiler to access macros and typedefs that are not defined by the 

HPUX Operating System, but not the ANSI standard. 


+z Is a compiler option specified to generate Position Independent Code (PIC) for 

all user exit routines 

+u1 Is a compiler option that allows pointers to access non-natively aligned data 

sourcefile 

UNIX file name(s) of the source file(s) for the INMOD or notify exit routine 

Use the following syntax example to link the object modules on HP-UX PA-RISC into the 

shared object. 

Link Syntax 

, 

ld -b inmod.o -o inmod.so 

3021A003 

where 


ld 

Description 


-b Is a linker option specified to generate a shared object file 

inmod.o 

o 

Is an object module derived from the compile step (see above) 

Specifies the output filename; default is a.out 





inmod.so 

Description 



Compiling and Linking a C INMOD on HP-UX Itanium 

Use the following syntax example to compile a C INMOD on an HP-UX Itanium-based client. 


cc +u1 -D_REENTRANT +DD64 -c 

inmod.c 

2409A057 

where 


cc 

Description 

Invokes the MetaWare High C compiler 

+u1 Is a compiler option that allows pointers to access non-natively aligned data 

-D_REENTRANT 

+DD64 

Ensures that all the Pthread definitions are visible at compile time 

Generates 64-bit object code for PA2.0 architecture 

-c Compiles one or more source files but does not enter the linking phase 

inmod.c 

A C source module for the INMOD 

Use the following syntax example to link the object modules on HP-UX Itanium into the 

shared object. 

Link Syntax 

ld -n -b inmod.o -lc -o 

inmod.so 

2409A056 

where 


ld 

Description 






Description 

-n Generates an executable with file type SHARE_MAGIC. This option is ignored 

in 64-bit mode. 

-b Is a linker option specified to generate a shared object file 

inmod.o 

-lc 

Is an object module derived from the compile step (see above) 

Search a library libc.a, libc.so, or libc.sh 

-o Specifies the output filename; default is a.out 

inmod.so 



Note: Object modules can be linked into shared objects or shared libraries (i.e., 

.so or .sl extension respectively) on HP-UX Itanium. 

Compiling and Linking a C INMOD on IBM AIX 

Use the following syntax example to compile a C INMOD on an IBM AIX-based client. 


cc -qmkshrobj -o shared-object-name -sourcefile.c 

2409C008 

where 


cc 

--qmkshrobj 

Description 

Call to the program that invokes the native UNIX C compiler 

Creates a shared object from the generated object files 

-o Switches to the linker 


sourcefile 

Name of the shared object file The shared-object-name can be any valid file 

name. This is the INMOD modulename parameter of the IMPORT of the 

MultiLoad job script. 

UNIX file name(s) of the source file(s) for the INMOD 

Compiling and Linking a Notify Exit Routine on IBM AIX 

Use the following syntax example to compile a Notify Exit Routine on an IBM AIX-based 

client. 





cc -c -brtl -fPIC sourcefile.c 

3021A008 

where 


cc 

Description 

Is a call to the program that invokes the native UNIX C compiler 

-c Is a compiler option that specifies to not send object files to the linkage editor 

-brtl 

-fPIC 

sourcefile.c 

Tells the linkage editor to accept both .sl and .a library file types 

Is a compiler option that generates Position Independent Code (PIC) for all user 

exit routines 

Is a C source module for the [Notify Exit Routine. 

Use the following syntax example to link the object modules into a shared object module. 

Link Syntax 

ld -G -e_dynamn -bE: export_dynamn.txt 

A 

A 

objectfile.o -o shared-object-name -lm -lc 

3021A011 

where 


ld 

G 

-e_dynamn 

-bE : export_dynamn.txt 

objectfile.o 

Description 


Produces a shared object enabled for use with the run-time linker 

Sets the entry point of the exit routine to _dynamn 

Is a linker option that exports the symbol "_dynamn" explicitly and 

the file export_dynamn.txt contains the symbol 

Is an object module created during compile step 





Description 


shared-object-name 

-lm 

-lc 


This is the EXIT name parameter for the NOTIFY option of the 

BEGIN LOAD command of the Teradata TPump job script. 

Is a linker option specifying to link with the /lib/libm.a library 

Is a linker option specifying to link with the /lib/libc.a library 

Compiling and Linking a C INMOD on a Linux Client 

Use the following syntax example to compile a C INMOD on a Linux client. 

Note: Be sure to compile the INMOD and notify exit routines in 32-bit mode so that they are 

compatible with Teradata TPump. 

gcc 

-I/usr/include -shared -fPIC 

-m32 

sourcefile.c 


2409B023 

where 


gcc 

shared 

Description 

Invokes the C compiler on Linux 

Produces a shared object, which can then be linked with other objects to form an 

executable 

-m32 Generate code for a 32-bit environment. The 32-bit environment sets int, long 

and pointer to 32 bits. 

-fPIC 

Produces Position Independent Code 


Compiling and Linking a C INMOD on a z/Linux Client 

Use the following syntax example to compile a C INMOD on a z/Linux client. 



gcc -I/usr/include -m31 -shared -fPIC sourcefile.c -o shared-object-name 

2409A059 




where 


gcc 

Description 

Call to the program that invokes the native C compiler 

-m31 Generates code for a 32-bit environment. 

-shared 

-fPIC 


Flag that produces a shared object that can then be linked with other objects to 

form an executable 

Compiler option that generates Position Independent Code for all user exit 

routines 

Name of the shared object file. The shared-object-name can be any valid file 

name. This is the name specified as: 

• The INMOD modulename parameter of the IMPORT of the MultiLoad job 

script. 

• The EXIT name parameter for the NOTIFY option of the BEGIN MLOAD 

and BEGIN DELETE MLOAD of the MultiLoad job script. 

-o Output file name 

Compiling and Linking a C INMOD on on IBM OS z/OS 

Use the following syntax from the USS environment to compile and link source files to a DLL: 



cc 

-o 

"MVS.PDSE.LOAD(module_name)" 

"//MVS.PDSE.C(source_name.c)" -W c,dll,expo = -W l,dll 

2409A058 

where 


Description 

-o Name of the executable load module that is produced during the link-edit phase. 

In the following example, a load module INMOD is placed in a z/OS PDSE 

named PDSE.LOAD, and the source code, INMOD, is compiled as a member of 

a z/OS PDSE named TEST.C: 

cc -o "//PDSE.LOAD(INMOD)" "//TEST.C(INMOD)" -W 

c,dll,expo -W l,dll 

Member names are limited to eight characters. 

-W c,dll,expo Options passed to the compiler phase to indicate that the source is to be 

compiled as a dll with all functions exported. 

-W l,dll Options passed to the link-edit phase to indicate that the module is linked as a dll. 



Programming INMODs for a Windows Client 


The previous section lists INMOD preparation techniques that apply to all platforms. There 

are several additional rules to follow when developing C INMODs for Windows clients. These 

are: 

• The INMOD routine must be written in C 

• The INMOD routine must have an entry point named _dynamn and declared with 

_declspec keyword 

• The file must be saved as a DLL file 

Compiling and Linking a C INMOD on a Windows Client 

Use the following syntax example to create a DLL on a Windows client. 

cl /DWIN32 / LD inmod.c 

3021B012 

where 


cl 

D 

LD 

inmod.c 

Description 

Invokes the Microsoft C Compiler 

Defines a macro 

Creates a .dll 

Denotes a C source module for the INMOD 





APPENDIX A 

How to Read Syntax Diagrams 

This appendix describes the conventions that apply to reading the syntax diagrams used in 

this book. 

Syntax Diagram Conventions 

Notation Conventions 

Item 

Definition / Comments 

Letter An uppercase or lowercase alphabetic character ranging from A through Z. 

Number A digit ranging from 0 through 9. 

Do not use commas when typing a number with more than 3 digits. 

Word 

Spaces 

Punctuation 

Variables and reserved words. 

• UPPERCASE LETTERS represent a keyword. 

Syntax diagrams show all keywords in uppercase, unless operating system 

restrictions require them to be in lowercase. 

• lowercase letters represent a keyword that you must type in lowercase, such as a 

UNIX command. 

• lowercase italic letters represent a variable such as a column or table name. 

Substitute the variable with a proper value. 

• lowercase bold letters represent a variable that is defined immediately 

following the diagram that contains the variable. 

• UNDERLINED LETTERS represent the default value. 

This applies to both uppercase and lowercase words. 

Use one space between items such as keywords or variables. 

Type all punctuation exactly as it appears in the diagram. 

Paths 

The main path along the syntax diagram begins at the left with a keyword, and proceeds, left 

to right, to the vertical bar, which marks the end of the diagram. Paths that do not have an 

arrow or a vertical bar only show portions of the syntax. 

The only part of a path that reads from right to left is a loop. 


Appendix A: How to Read Syntax Diagrams 


Continuation Links 

Paths that are too long for one line use continuation links. Continuation links are circled 

letters indicating the beginning and end of a link: 

A 

A 

Required Entries 

When you see a circled letter in a syntax diagram, go to the corresponding circled letter and 

continue reading. 

Required entries appear on the main path: 

FE0CA002 

SHOW 

FE0CA003 

If you can choose from more than one entry, the choices appear vertically, in a stack. The first 

entry appears on the main path: 

SHOW 

CONTROLS 

VERSIONS 

FE0CA005 

Optional Entries 

You may choose to include or disregard optional entries. Optional entries appear below the 

main path: 

SHOW 

CONTROLS 

FE0CA004 

If you can optionally choose from more than one entry, all the choices appear below the main 

path: 




READ 

SHARE 

ACCESS 

JC01A010 

Some commands and statements treat one of the optional choices as a default value. This 

value is UNDERLINED. It is presumed to be selected if you type the command or statement 

without specifying one of the options. 

Strings 

Strings appear in single quotes: 

'msgtext' 

JC01A004 

If the string text includes a single quote or a blank space, the string appears in double quotes: 

''abc'd" 

''abc d" 

JC01A005 

Abbreviations 

If a keyword or a reserved word has a valid abbreviation, the unabbreviated form always 

appears on the main path. The shortest valid abbreviation appears beneath. 

SHOW 

CONTROLS 

CONTROL 

FE0CA042 

In the above syntax, the following formats are valid: 

• SHOW CONTROLS 

• SHOW CONTROL 

Loops 

A loop is an entry or a group of entries that you can repeat one or more times. Syntax 

diagrams show loops as a return path above the main path, over the item or items that you can 

repeat: 




, 3 

, 4 

( 

cname ) 

JC01B012 

Read loops from right to left. 

The following conventions apply to loops: 

Loop Convention 

A maximum number of entries is 

allowed. 

A minimum number of entries is 

required. 

A separator character is required 

between entries. 

A delimiter character is required 

around entries. 

Description 

The number appears in a circle on the return path. 

In the example, you may type cname a maximum of 4 times. 

The number appears in a square on the return path. 

In the example, you must type at least three groups of column 

names. 

The character appears on the return path. 

If the diagram does not show a separator character, use one 

blank space. 

In the example, the separator character is a comma. 

The beginning and end characters appear outside the return 

path. 

Generally, a space is not needed between delimiter characters 

and entries. 

In the example, the delimiter characters are the left and right 

parentheses. 

Excerpts 

Sometimes a piece of a syntax phrase is too large to fit into the diagram. Such a phrase is 

indicated by a break in the path, marked by (|) terminators on either side of the break. The 

name for the excerpted piece appears between the terminators in boldface type. 




The boldface excerpt name and the excerpted phrase appears immediately after the main 

diagram. The excerpted phrase starts and ends with a plain horizontal line: 

LOCKING 

excerpt 

A 

A 

HAVING 

con 

where_cond 

excerpt 

, 

cname 

, 

col_pos 

JC01A014 

Multiple Legitimate Phrases 

In a syntax diagram, it is possible for any number of phrases to be legitimate: 

DATABASE 

TABLE 

VIEW 

dbname 

tname 

vname 

JC01A016 

In this example, any of the following phrases are legitimate: 

• dbname 

• DATABASE dbname 

• tname 

• TABLE tname 

• vname 

• VIEW vname 




Sample Syntax Diagram 

, 

CREATE VIEW 

viewname 

AS 

A 

CV 

cname 

LOCKING 

LOCK 

A 

dbname 

ACCESS 

B 

DATABASE 

FOR 

SHARE 

MODE 

tname 

IN 

READ 

TABLE 

WRITE 

vname 

EXCLUSIVE 

VIEW 

EXCL 

, 

, 

B SEL expr FROM tname 

qual_cond C 

.aname 

C 

HAVING cond ; 

qual_cond 

WHERE cond 

, 

GROUP BY 

cname 

, 

col_pos 

JC01A018 

Diagram Identifier 

The alphanumeric string that appears in the lower right corner of every diagram is an internal 

identifier used to catalog the diagram. The text never refers to this string. 


APPENDIX B 

Teradata TPump Examples 

This appendix provides some examples of Teradata TPump scripts and their corresponding 

output. Included are: 

• Simple Script Example 

• Restarted Upsert Example 

• Example Using the TABLE Command 

In the output examples, the lines that begin with 4-digit numbers (for example, 0001) are 

scripts, the rest are output. 

Simple Script Example 

The following is an example of a simple script. 

/***********************************************/ 

/* Script Name: TP0623 */ 

/* Description: WIN32 script. */ 

/***********************************************/ 


.LOGON HYIBMX01/BRUCEDB,BRUCE; 



/***********************************************/ 

/* STEP01 CREATES THE TABLES FOR THE TPump JOB */ 

/***********************************************/ 


F1 INTEGER,F2 CHAR(50), 

F3 VARCHAR(50),F4 FLOAT, 

F5 BYTE (10),F6 VARBYTE (10), 

F7 DECIMAL(8,2),F8 BYTEINT, 

F9 SMALLINT,F10 DATE, 

F11 BIGINT,F12 DECIMAL(38,0)) 


/***********************************************/ 

/* BEGIN LOAD WITH ALL THE OPTIONS SPECIFIED */ 

/* SUCH AS ERRLIMIT, CHECKPOINT, SESSIONS, */ 

/* TENACITY, etc. */ 

/***********************************************/ 

.BEGIN LOADCHECKPOINT 15SESSIONS 4 1 

TENACITY 2ERRORTABLE TPERR0623 

ERRLIMIT 10ROBUST OFF 


Appendix B: Teradata TPump Examples 


PACK 500DATAENCRYPTION ON 

ARRAYSUPPORT ON RATE 200 

RETRYTIMES 200 SLEEP 40 

NOATOMICUPSERT MACRODB BRUCEDB 

NOTIFY OFFSERIALIZE ON; 


.FIELD FF1 * INTEGER KEY; 

.FIELD FF2 * CHAR(50); 

.FIELD FF3 * VARCHAR(50); 

.FIELD FF4 * FLOAT; 

.FIELD FF5 * BYTE(10); 

.FIELD FF6 * VARBYTE(10); 

.FIELD FF7 * DECIMAL(8,2); 

.FIELD FF8 * BYTEINT; 

.FIELD FF9 * SMALLINT; 

.FIELD FF10 * DATE; 

.FIELD FF11 * BIGINT; 


.DML LABEL LABEL0623IGNORE DUPLICATE ROWS 

IGNORE MISSING ROWS 


INSERT INTO TPTBL0623 VALUES (:FF1,:FF2,:FF3,:FF4, 

:FF5,:FF6,:FF7,:FF8, 

:FF9,:FF10,:FF11,:FF12); 

.IMPORT INFILE ./ALLTYPE.data 



.END LOAD; 

.LOGOFF; 

produces the following output: 

**** 15:17:25 UTY6633 WARNING: No configuration file, using build defaults 

======================================================================== 

= = 


= Platform WIN32 = 

= = 

======================================================================== 

= = 


= = 

======================================================================== 


======================================================================== 

= = 


= = 

======================================================================== 

0001 /***********************************************/ 



/***********************************************/ 


0002 .LOGON HYIBMX01/BRUCEDB,; 

**** 15:17:29 UTY8400 Teradata Database Release:13.10g.00.53 












**** 15:17:32 UTY6217 Logtable 'BRUCEDB.TPLOG0623' has been created. 

======================================================================== 

= = 


= = 

======================================================================== 





0005 /***********************************************/ 


/***********************************************/ 



F3 VARCHAR(50), F4 FLOAT, 

F5 BYTE (10), F6 VARBYTE (10), 


F9 SMALLINT, F10 DATE, 

F11 BIGINT, F12 DECIMAL(38,0)) 



0006 /***********************************************/ 




/***********************************************/ 

.BEGIN LOAD CHECKPOINT 15 SESSIONS 4 1 

TENACITY 2 ERRORTABLE TPERR0623 

ERRLIMIT 10 ROBUST OFF 

PACK 500 DATAENCRYPTION ON 

ARRAYSUPPORT ON RATE 200 

RETRYTIMES 200 SLEEP 40 

NOATOMICUPSERT MACRODB BRUCEDB 

NOTIFY OFF SERIALIZE ON; 

======================================================================== 

= = 


= = 

======================================================================== 


0008 .FIELD FF1 * INTEGER KEY; 

0009 .FIELD FF2 * CHAR(50); 


0011 .FIELD FF4 * FLOAT; 

0012 .FIELD FF5 * BYTE(10); 

0013 .FIELD FF6 * VARBYTE(10); 

0014 .FIELD FF7 * DECIMAL(8,2); 

0015 .FIELD FF8 * BYTEINT; 

0016 .FIELD FF9 * SMALLINT; 

0017 .FIELD FF10 * DATE; 




0018 .FIELD FF11 * BIGINT; 


0020 .DML LABEL LABEL0623 IGNORE DUPLICATE ROWS 



0021 INSERT INTO TPTBL0623 VALUES ( :FF1, :FF2, :FF3, :FF4, 

:FF5, :FF6, :FF7, :FF8, 

:FF9, :FF10, :FF11, :FF12); 

0022 .IMPORT INFILE ./ALLTYPE.data 






======================================================================== 

= = 


= = 

======================================================================== 






. Errlimit: 10 rejected record(s). 




. StartUp Rate: 200 Statements per Minute. 

.Rate Per Period: 50 Statements per 15000 milliseconds. 

. Atomic Upsert: DISABLED. 

















. ========= ============== 







I BRUCEDB TPTBL0623 1000 

**** 15:22:54 UTY0821 Error table BRUCEDB.TPERR0623 is EMPTY, dropping table. 

0024 .LOGOFF; 

======================================================================== 

= = 



Restarted Upsert Example 


= = 

======================================================================== 




. Start : 15:17:25 - TUE OCT 06, 2009 

. End : 15:22:59 - TUE OCT 06, 2009 



This restarted upsert example uses two IMPORT clauses. The first one loads half of the 

records from the data source into an empty table. The second one does an upsert using all the 

records in the same data file. The result is that it updates the rows inserted during the first 

import and inserts all of the rows that the first import skipped. 

This script: 

/***********************************************/ 



/***********************************************/ 


.LOGON ESIBMX01/LYDIADB,LYDIA; 



/***********************************************/ 


/***********************************************/ 


F1 INTEGER,F2 CHAR(50), 

F3 VARCHAR(50),F4 FLOAT, 

F5 BYTE (10),F6 VARBYTE (10), 


F9 SMALLINT,F10 DATE, 

F11 BIGINT,F12 DECIMAL(38,0)) 


/***********************************************/ 




/***********************************************/ 

.BEGIN LOADCHECKPOINT 15SESSIONS 4 1 

SERIALIZE ONERRORTABLE TPERR0734; 


.FIELD FF1 * INTEGER KEY; 

.FIELD FF2 * CHAR(50); 

.FIELD FF3 * VARCHAR(50); 

.FIELD FF4 * FLOAT; 

.FIELD FF5 * BYTE(10); 

.FIELD FF6 * VARBYTE(10); 


.FIELD FF8 * BYTEINT; 

.FIELD FF9 * SMALLINT; 




.FIELD FF10 * DATE; 

.FIELD FF11 * BIGINT; 


/* insert half of the rows ......................*/ 

.DML LABEL LABEL0734AIGNORE DUPLICATE ROWS 




:FF5,:FF6,:FF7,:FF8, 

:FF9,:FF10,:FF11,:FF12); 

/* ... and then upsert all of the rows ..........*/ 

.DML LABEL LABEL0734BIGNORE DUPLICATE ROWS 


IGNORE EXTRA ROWS 


UPDATE TPTBL0734 SET F7 = F7 + 1 WHERE F1 = :FF1; 


:FF5,:FF6,:FF7,:FF8, 

:FF9,:FF10,:FF11,:FF12); 

/* should result in an upsert with half inserts and half updates */ 


LAYOUT LAY0734 FROM 1 FOR 400 

APPLY LABEL0734A WHERE FF3 = 'TERADATA'; 



APPLY LABEL0734B; 

.END LOAD; 

.LOGOFF; 

produces the following output (assuming it was restarted during the second import): 

0001 /***********************************************/ 



/***********************************************/ 


0002 .LOGON ESIBMX01/LYDIADB,; 










**** 16:52:00 UTY6217 Logtable 'LYDIADB.TPLOG0734' has been created. 

======================================================================== 

= = 


= = 

======================================================================== 





0005 /***********************************************/ 


/***********************************************/ 






F3 VARCHAR(50), F4 FLOAT, 

F5 BYTE (10), F6 VARBYTE (10), 


F9 SMALLINT, F10 DATE, 

F11 BIGINT, F12 DECIMAL(38,0)) 



0006 /***********************************************/ 




/***********************************************/ 

.BEGIN LOAD CHECKPOINT 15 SESSIONS 4 1 

SERIALIZE ON ERRORTABLE TPERR0734; 

======================================================================== 

= = 


= = 

======================================================================== 


0008 .FIELD FF1 * INTEGER KEY; 

0009 .FIELD FF2 * CHAR(50); 


0011 .FIELD FF4 * FLOAT; 

0012 .FIELD FF5 * BYTE(10); 

0013 .FIELD FF6 * VARBYTE(10); 


0015 .FIELD FF8 * BYTEINT; 

0016 .FIELD FF9 * SMALLINT; 

0017 .FIELD FF10 * DATE; 

0018 .FIELD FF11 * BIGINT; 


0020 /* insert half of the rows ......................*/ 

.DML LABEL LABEL0734A IGNORE DUPLICATE ROWS 




:FF5, :FF6, :FF7, :FF8, 

:FF9, :FF10, :FF11, :FF12); 

0022 /* ... and then upsert all of the rows ..........*/ 

.DML LABEL LABEL0734B IGNORE DUPLICATE ROWS 


IGNORE EXTRA ROWS 


0023 UPDATE TPTBL0734 SET F7 = F7 + 1 WHERE F1 = :FF1; 


:FF5, :FF6, :FF7, :FF8, 

:FF9, :FF10, :FF11, :FF12); 

0025 /* should result in an upsert with half inserts and half updates */ 



APPLY LABEL0734A WHERE FF3 = 'TERADATA'; 

0026 .IMPORT INFILE ./ALLTYPE.data 


APPLY LABEL0734B; 







======================================================================== 

= = 


= = 

======================================================================== 



























. ========= ============== 





** Statistics for Apply Label : LABEL0734A 


I LYDIADB TPTBL0734 200 

**** 16:52:33 UTY8800 WARNING: Rate Monitoring turned off - no permission on macro: 

TPumpMacro.ImportCreate. 

















. ========= ============== 



Example Using the TABLE Command 





** Statistics for Apply Label : LABEL0734B 


U LYDIADB TPTBL0734 200 

I LYDIADB TPTBL0734 200 

**** 16:52:50 UTY0821 Error table LYDIADB.TPERR0734 is EMPTY, dropping table. 

0028 .LOGOFF; 

======================================================================== 

= = 


= = 

======================================================================== 




. Start : 16:51:54 - TUE OCT 06, 2009 

. End : 16:52:55 - TUE OCT 06, 2009 



This example script uses the TABLE command and “INSERT .*” feature. 


.LOGON ESSNLX14/KRCDB,KRCDB; 




F0 integer, F1 integer, 

F2 integer, F3 CHAR(38)) 


.BEGIN LOAD SESSIONS 8; 


.TABLE TPTBL0096; 

.DML LABEL LABEL0096 ; 

INSERT INTO TPTBL0096.*; 

.IMPORT INFILE datafile1 


APPLY LABEL0096 FROM 1 THRU 111; 

.END LOAD; 

.LOGOFF; 

produces the following results. When looking at the following results, notice that the output 

fields generated by the TABLE command includes the “KEY” modifier for the field coming 

from the primary index of the table. This is what enables the use of the “SERIALIZE” option: 

0001 .LOGTABLE TPLOG0096; 

0002 .LOGON ESSNLX14/KRCDB,; 













**** 17:07:37 UTY6217 Logtable KRCD.TPLOG0096' has been created. 

======================================================================== 

= = 


= = 

======================================================================== 





0005 CREATE TABLE TPTBL0096, FALLBACK( 

F0 integer, F1 integer, 

F2 integer, F3 CHAR(38)) 



0006 .BEGIN LOAD SESSIONS 8; 

======================================================================== 

= = 


= = 

======================================================================== 


0008 .TABLE TPTBL0096; 

**** 17:07:43 UTY6009 Fields generated by .TABLE command begin. 

**** 17:07:43 UTY6010 *** .FIELD F0 * INTEGER KEY; 

**** 17:07:43 UTY6010 *** .FIELD F1 * INTEGER; 

**** 17:07:43 UTY6010 *** .FIELD F2 * INTEGER; 

**** 17:07:43 UTY6010 *** .FIELD F3 * CHAR(38); 

**** 17:07:43 UTY6011 Fields generated by .TABLE command end. 

0009 .DML LABEL LABEL0096 ; 

0010 INSERT INTO TPTBL0096.*; 

0011 .IMPORT INFILE datafile1 


APPLY LABEL0096 FROM 1 THRU 111; 




======================================================================== 

= = 


= = 

======================================================================== 














**** 17:08:04 UTY8800 WARNING: Rate Monitoring turned off - no permission on macro: 

TPumpMacro.ImportCreate. 

















. ========= ============== 







I KRCDB TPTBL0096 111 

**** 17:08:10 UTY0821 Error table KRC.M20080627_170744_00603_001_ET is EMPTY, dropping 

table. 

0013 .LOGOFF; 

======================================================================== 

= = 


= = 

======================================================================== 




. Start : 17:07:30 -TUE OCT 06, 2009 

. End : 17:08:17 - TUE OCT 06, 2009 






APPENDIX C 

INMOD and Notify Exit Routine 

Examples 

This appendix provides INMOD examples using C INMOD - UNIX 

These examples contain z/OS control statements. 

Workstation-based clients support only INMODs written in C; an example of this is also 

provided in this appendix. 

C INMOD - UNIX 

/************************************************************************ 

* * 

* TITLE: tpumpimd.c * 

* * 

* Copyright 1997-2009 Teradata Corporation. * 

* ALL RIGHTS RESERVED. * 

* Teradata Corporation CONFIDENTIAL AND TRADE SECRET * 

* * 

* This copyrighted material is the Confidential, Unpublished * 

* Property of the Teradata Corporation. This copyright notice and * 

* any other copyright notices included in machine readable * 

* copies must be reproduced on all authorized copies. * 

* * 

************************************************************************* 

Notes: 

This program is for INMOD testing using C user exit routine. 

When this routine is activated it looks at the content of the 

function code passed (a->code) and depending on its value, it 

0) initializes, i.e., opens a file, etc... 

1) reads a record 

5) acknowledges "close inmod" request. The user exit routine 

must return "return code"(a->code) and "length" (a->len). You 

should send return code = zero when no errors occur and non-zero for 

an error. LOAD expects length = zero at the end of file. Then 

it sends "CLOSE INMOD" request. THE USER EXIT routine must 

explicitly return "return code" = ZERO to terminate the 

conversation. 

The following TPUMP control statements will work with this inmod: 

.LOGTABLE ; 

.LOGON ; 

DROP TABLE TABLE200; 


Appendix C: INMOD and Notify Exit Routine Examples 


DROP TABLE ET_TABLE200; 

CREATE TABLE TABLE200 ( 

X1 integer, 

x2 char(76) 

); 

.BEGIN LOAD SESSIONS 4 

ERRORTABLE ET_TABLE200; 

.LAYOUT TABLE200; 

.FIELD x1 1 integer nullif x1 = 5; 

.FIELD x2 * char(6) nullif x1 = 4; 









.DML LABEL A; 

INSERT INTO TABLE200 VALUES 

( 

:x1 

,:x2 

); 

.IMPORT INMOD 

LAYOUT TABLE200 

APPLY A FROM 1 THRU 100; 

.END LOAD ; 

.LOGOFF; 

************************************************************************/ 

#include 

#include 

#include 

typedef unsigned short Int16; 

typedef unsigned char Int8; 

typedef unsigned long int Int32; 

/* PASSING parameter structures 

*/ 

typedef struct { 

Int32 code; 

Int32 len; 

struct { 

int seqno; 

Int8 body[80]; 

} buf; 

} inmodbuf; 

typedef struct { 

Int32 seq; 




Int16 len; 

char param[80]; 

} inmodpty; 

static int count=0; 

char *memcpy(); 

static int readrecord(inmodbuf *); 

#ifdef 

WIN32 

__declspec(dllexport) void _dynamn 

(a,b) 

inmodbuf *a; 

inmodpty *b; 

#else 

void _dynamn(a,b) 

inmodbuf *a; 

inmodpty *b; 

#endif 

{int code=0; 

/*printf("BEGIN--> %d %d %s\n",a->code,a->len,tempbuf); */ 

/*printf(" +++ %d %d %s\n",b->seq ,b->len,b->param); */ 

code= (int) a->code; 

switch (code) { 

case 0: 

/* Here you open the file and read the first record */ 

/* printf("## CODE=0, openinig...\n"); */ 

count = 0; 

if (! readrecord(a)) 

printf("Messed up in open.\n"); 

break; 

case 1: 

/* Utility requested next record, read it */ 

/* printf("## CODE=1, reading...\n"); */ 

if (! readrecord(a)) 

printf("Messed up in read.\n"); 

break; 

case 5: 

/* Utility is closing INMOD routine */ 

a->code=0; 

a->len=0; 

/* printf("## CODE=5, terminating...\n"); */ 

break; 

default: 

a->code=12; /* any number not = to zero */ 

a->len=0; 

printf("##### UNKNOWN code ######\n");a->code=0;a->len=0; 

}; 

/*printf("END --> %d %d %s\n",a->code,a->len,tempbuf); */ 

/*printf(" +++ %d %d %s\n",b->seq ,b->len,b->param);*/ 

} 

static int readrecord(a) 

inmodbuf *a; 



Sample Notify Exit Routine 

{ 

int rtn=0; 

int i=0; 

if (count < 50000) 

{ 

a->buf.seqno = count; 

count++; 

for (i=0; ibuf.body[i] = 'X'; 

a->buf.body[75] = '\0'; 

} 

a->len=80; 

a->code=0; 

rtn=1; 

} 

else 

{ 

printf("=== EOF ===\n"); 

a->code=99; 

a->len=0; 

}; 

return(rtn); 


The following is the listing of tldnfyxt.c, the sample notify exit routine that is provided with 

Teradata TPump software. 

/********************************************************************* 

* * 

* tldnfyxt.c - Sample Notify Exit for Tpump. * 

* * 

* Copyright 1997-2009 Teradata Corporation. * 

* ALL RIGHTS RESERVED. * 

* Teradata Corporation CONFIDENTIAL AND TRADE SECRET * 

* * 

* This copyrighted material is the Confidential, Unpublished * 

* Property of the Teradata Corporation. This copyright notice and * 

* any other copyright notices included in machine readable * 

* copies must be reproduced on all authorized copies. * 

* * 

* * 

* Purpose - This is a sample notify exit for Tpump . * 

* * 

* Execute - Build Notify on a Unix system * 

* compile and link into shared object * 

* cc -G tldnfyxt.c - o libtldnfyxt.so * 

* - Build Notify on a Win32 system * 

* compile and link into dynamic link library * 

* cl /DWIN32 /LD tldnfyxt.c * 

* - Build Notify on AIX system * 

* cc -c -brtl -qalign=packed tldnfyxt.c * 

* ld -G -e_dynamn -bE:export_dynamn.txt tldnfyxt.o * 

* -o libtldnfyxt.so -lm -lc * 

* where export_dynamn.txt conaints the symbol "_dynamn"* 

* - Build Notify on Linux system * 




* gcc -shared -fPIC tldnfyxt.c -o libtldnfyxt.so * 

* * 

**********************************************************************/ 

#ifdef __MVS__ 

#pragma pack(1) 

#endif 

#include 

typedef unsigned int UInt32; 

typedef int Int32; 

#define NOTIFYID_FASTLOAD 1 

#define NOTIFYID_MULTILOAD 2 

#define NOTIFYID_FASTEXPORT 3 

#define NOTIFYID_BTEQ 4 

#define NOTIFYID_TPUMP 5 

#define MAXVERSIONIDLEN 32 

#define MAXUTILITYNAMELEN 36 

#define MAXUSERNAMELEN 64 

#define MAXUSERSTRLEN 80 

#define MAXTABLENAMELEN 128 

#define MAXFILENAMELEN 256 

typedef enum { 

NMEventInitialize = 0, 

NMEventFileInmodOpen = 1, 

NMEventCkptBeg = 2, 

NMEventImportBegin = 3, 

NMEventImportEnd = 4, 

NMEventErrorTable = 5, 

NMEventDBSRestart = 6, 

NMEventCLIError = 7, 

NMEventDBSError = 8, 

NMEventExit = 9, 

NMEventTableStats = 10, 

NMEventCkptEnd = 11, 

NMEventRunStats = 12, 

NMEventDMLError = 13 

} NfyTLDEvent; 

#define TIDUPROW 2816 

typedef enum { 

DEFeedbackDefault = 0, 

DEFeedbackNoLogging = 1 

} DMLErrorFeedbackType; 

typedef struct _TLNotifyExitParm { 

UInt32 Event; /* should be NfyFLDEvent values */ 

union { 

struct { 

int VersionLen; 

char VersionId[MAXVERSIONIDLEN]; 

int UtilityId; 

int UtilityNameLen; 

char UtilityName[MAXUTILITYNAMELEN]; 

int UserNameLen; 

char UserName[MAXUSERNAMELEN]; 

int UserStringLen; 

char UserString[MAXUSERSTRLEN]; 




} Initialize; 

struct { 

int nImport; 

} ImpStart; 

struct { 

UInt32 FileNameLen; /* for file open event */ 

char FileOrInmodName[MAXFILENAMELEN]; 

UInt32 nImport; 

} FileOpen ; 

struct { 

UInt32 Records; 

} CheckPt; 

struct { 

char *TableName; 

UInt32 Rows; 

} ETDrop ; 

struct { 

Int32 ReturnCode; 

} Exit; 

struct { 

int nImport; 

UInt32 RecsIn; 

UInt32 RecsSkipped; 

UInt32 RecsRejd; 

UInt32 RecsOut; 

UInt32 RecsError; 

} Complete; 

struct { 

char type; 

char *dbasename; 

char *szName; 

UInt32 Activity; 

} TableStats; 

struct { 

UInt32 ErrorCode; 

} DBSError; 

struct { 


} CLIError; 

struct { 

int nImport; 

UInt32 nSQLstmt; 

UInt32 nReqSent; 

UInt32 RecsIn; 

UInt32 RecsSkipped; 

UInt32 RecsRejd; 

UInt32 RecsOut; 

UInt32 RecsError; 

} Stats; 

struct { 

UInt32 nImport; 


char *ErrorMsg; 

UInt32 nRecord; 

unsigned char nApplySeq; 

unsigned char nDMLSeq; 

unsigned char nSMTSeq; 

char *ErrorData; 

UInt32 ErrorDataLen; 




UInt32 *feedback; 

} DMLError; 

} Vals; 

} TLNotifyExitParm; 

#ifdef I370 

#define TLNfyExit MLNfEx 

#endif 

extern Int32 TLNfyExit( 

#ifdef __STDC__ 

TLNotifyExitParm *Parms 

#endif 

); 

#ifdef WIN32 

__declspec(dllexport) long _dynamn(TLNotifyExitParm *P) 

#else 

Int32 _dynamn(P) 

TLNotifyExitParm *P; 

#endif 

{ 

FILE *fp; 

int i; 

if (!(fp = fopen("NFYEXIT.OUT", "a"))) 

return(1); 

switch(P->Event) { 

case NMEventInitialize : /* Nothing */ 

fprintf(fp, "exit called @ Tpump init.\n"); 

fprintf(fp, "Version: %s\n", P->Vals.Initialize.VersionId); 

#ifdef __MVS__ 

P->Vals.Initialize.UtilityName[MAXUTILITYNAMELEN-1] = '\0'; 

#else 

P->Vals.Initialize.UtilityName[MAXUTILITYNAMELEN] = '\0'; 

#endif 

fprintf(fp, "Utility: %s\n", P->Vals.Initialize.UtilityName); 

fprintf(fp, "User: %s\n", P->Vals.Initialize.UserName); 

if (P->Vals.Initialize.UserStringLen) 

fprintf(fp, "UserString: %s\n", P->Vals.Initialize.UserString); 

break; 

case NMEventFileInmodOpen : 

fprintf(fp, "Exit called @ File/Inmod Open\n\ 

File/Inmod Name : %s Import : %d\n", 

P->Vals.FileOpen.FileOrInmodName,P->Vals.FileOpen.nImport); 

break; 

case NMEventCkptBeg : 

fprintf(fp,"exit called @ checkpoint begin : %u Records .\n", 

P->Vals.CheckPt.Records); 

break; 

case NMEventCkptEnd : 

fprintf(fp,"exit called @ checkpoint End : %u Records Sent.\n", 

P->Vals.CheckPt.Records); 

break; 

case NMEventCLIError : 




fprintf(fp, "exit called @ CLI error %d\n", 

P->Vals.CLIError.ErrorCode); 

break; 

case NMEventErrorTable : 

fprintf(fp,"exit called @ ErrTable Drop : " 

"%u logable records.\n", 

P->Vals.ETDrop.Rows); 

break; 

case NMEventDBSError : 

fprintf(fp, "exit called @ DBS error %d\n", 

P->Vals.DBSError.ErrorCode); 

break; 

case NMEventImportBegin: 

fprintf(fp, "exit called @ import %d starting. \n", 

P->Vals.ImpStart.nImport); 

break; 

case NMEventImportEnd : 

fprintf(fp, "exit called @ import %d ending \n", 

P->Vals.Complete.nImport); 

fprintf(fp, 

"Total Records Read: %u \nRecords Skipped " 

"%u \nUnreadable Records:%u \nRecords Sent: 

"%u \nData Errors : 

P->Vals.Complete.RecsIn, 

P->Vals.Complete.RecsSkipped, 

P->Vals.Complete.RecsRejd, 

P->Vals.Complete.RecsOut, 

P->Vals.Complete.RecsError); 

%u \n", 

break; 

case NMEventDBSRestart : 

fprintf(fp, "exit called @ RDBMS restarted\n"); 

break; 

case NMEventExit : 

fprintf(fp, "exit called @ tpump notify out of scope:" 

" return code %d.\n", 

P->Vals.Exit.ReturnCode); 

break; 

case NMEventTableStats: 

fprintf(fp,"exit called @ Table Stats: \n"); 

if(P->Vals.TableStats.type == 'I') 

fprintf(fp,"Rows Inserted : " 

"%u \nTable/Macro Name : %s \nDatabase Name" 

" : %s \n", 

P->Vals.TableStats.Activity, 

P->Vals.TableStats.szName, 

P->Vals.TableStats.dbasename); 

if(P->Vals.TableStats.type == 'U') 

fprintf(fp,"Rows Updated : " 

"%u \nTable/Macro Name : %s \nDatabase Name" 

" : %s \n", 







if(P->Vals.TableStats.type == 'D') 

fprintf(fp,"Rows Deleted : " 

"%u \nTable/Macro Name : 

" : %s \n", 




%s \nDatabase Name" 

break; 

case NMEventRunStats : 

fprintf(fp, "exit called @ states\n"); 

fprintf(fp, "import %d \n", 

P->Vals.Stats.nImport); 

fprintf(fp, 

"Total SQL Statements: %u \nRequest Sent: %u \n" 

"Records Read: %u \nRecords Skipped: %u \n" 

"nUnreadable Records: %u \nRecords Sent: %u \n" 

"Data Errors : %u \n", 

P->Vals.Stats.nSQLstmt, 

P->Vals.Stats.nReqSent, 

P->Vals.Stats.RecsIn, 

P->Vals.Stats.RecsSkipped, 

P->Vals.Stats.RecsRejd, 

P->Vals.Stats.RecsOut, 

P->Vals.Stats.RecsError); 

break; 

case NMEventDMLError : 

fprintf(fp, "exit called @ DML error \n"); 

fprintf(fp, "import %d \n", 

P->Vals.DMLError.nImport); 

fprintf(fp, 

"Error code: %u \nError text: %s \n" 

"Record number: %u \nApply number: %d \n" 

"DML number: %d \nStatement number: %d \n" 

"Error data length : %u \n" 

"feedback : %u \n", 

P->Vals.DMLError.ErrorCode, 

P->Vals.DMLError.ErrorMsg, 

P->Vals.DMLError.nRecord, 

P->Vals.DMLError.nApplySeq, 

P->Vals.DMLError.nDMLSeq, 

P->Vals.DMLError.nSMTSeq, 

P->Vals.DMLError.ErrorDataLen, 

*(P->Vals.DMLError.feedback)); 

fprintf(fp, "Error data: "); 

for (i=0 ;iVals.DMLError.ErrorDataLen; i++) { 

fprintf(fp, "%c", P->Vals.DMLError.ErrorData[i]); 

} 

fprintf(fp, "\n"); 

if (P->Vals.DMLError.ErrorCode == TIDUPROW) { 

*(P->Vals.DMLError.feedback) = DEFeedbackNoLogging; 

fprintf(fp, "Returning feedback = %u \n", 

DEFeedbackNoLogging); 

} 

break; 

default : 

fprintf(fp,"\nAn Invalid Event Passed to the Exit Routine\n"); 

break; 




} 

} 

fclose(fp); 

return(0); 


APPENDIX D 

User-Defined-Types 

and User-Defined-Methods 

This appendix provides information on User-Defined-Types (UDTs) and 

User-Defined-Methods (UDMs): 

• User-Defined-Types and User-Defined-Methods 

• User-Defined-Methods (UDMs) 

• Creating UDTs with Teradata TPump 

• Inserting and Retrieving UDTs with Client Products 

• External Types 

• Inserting UDTs with Teradata TPump 

• Retrieving UDTs with Teradata TPump 

• Retrieving UDT Metadata with Teradata TPump 

User-Defined-Types and User-Defined-Methods 

This section provides a brief overview of how Teradata client products support user-defined 

custom data types known as User-Defined Types (UDTs), and user-defined custom functions 

known as User-Defined Methods (UDMs). 

• User-Defined Types (UDTs) 

• User-Defined Methods (UDMs) 

For more in depth information on using UDTs and UDMs see Introduction to Teradata, B035- 

1091, SQL External Routine Programming, B035-1147 and SQL Fundamentals, B035-1141. 

User-Defined Types (UDTs) 

UDTs can be created to provide representations of real world entities within Teradata 

Database. Choosing a set of UDTs which closely matches the entities encountered in a given 

business can yield a system which is easier to understand and hence easier to maintain. 

Support for UDTs and UDMs integrates the power of object-oriented technology directly into 

Teradata Database. 


Appendix D: User-Defined-Types and User-Defined-Methods 


User-Defined-Methods (UDMs) 

Teradata Database developer-created custom functions, which are explicitly connected to 

UDTs are known as User-Defined-Methods (UDMs). All UDMs must reside on server. 

UDMs can be used to create an interface to the UDT that is independent of the UDT's internal 

representation. This makes it possible to later enhance a given UDT even in cases where the 

internal representation of the UDT must be changed to support the enhancement, without 

changing all of the database applications which use the UDT. 

Creating UDTs with Teradata TPump 

Teradata TPump cannot create a custom UDT. 

Inserting and Retrieving UDTs with Client Products 

External Types 

A UDT can only exist on the Teradata Database server. Each UDT has an associated “from-sql 

routine” and “to-sql routine”. 

• Insert - The “to-sql routine” constructs a UDT value from a pre-defined type value. The 

“to-sql routine” is automatically invoked when inserting values from a client system into a 

UDT on the Teradata Database server. 

• Retrieve - The “from-sql routine” generates a pre-defined type value from a UDT. The 

“from-sql routine” is automatically invoked when a UDT is retrieved from the Teradata 

Database server to a client system. 

The “from-sql routine” and the “to-sql routine” create a mapping between a UDT and a predefined 

type. This pre-defined type is called the external type of a UDT. A client application 

only deals with the external type; it does not deal with UDT value directly. 

External Type Example 

For example, if the following conditions exist: 

• UDT named FULLNAME exists 

• The external type associated with FULLNAME is VARCHAR(46) 

Then, during an retrieve of FULLNAME values, the Teradata Database server converts the 

values from FULLNAME values to VARCHAR(46) values by invoking the “from-sql routine” 

associated with the FULLNAME UDT. 

Note: The client must expect to receive the data in the same format as it receives 

VARCHAR(46) values. 

Similarly, when values are provided by the client for insert into a FULLNAME UDT, the client 

must provide values in the same way it would provide values for a VARCHAR(46) field. The 

Teradata Database server will convert the values from VARCHAR(46) to FULLNAME values 

using the “to-sql routine” associated with the FULLNAME UDT. 




Inserting UDTs with Teradata TPump 

Teradata Parallel Data Pump program can insert values into tables containing UDT columns 

in the same manner as is done for other tables. 

• Input Records - The input records to Teradata TPump must have the column data for 

UDT columns in its external type format. When the input record format is defined, the 

external type must be used for the UDT columns. Also, if the “TABLE” command is used 

to define the input record format and columns in the referenced tables contain UDTs, then 

the external types corresponding to the UDTs will be used in the input record format for 

those columns 

• Table Command - If the “TABLE” command is used to define the input record format, and 

columns in the referenced TABLEs contain UDTs, then the external types corresponding 

to the UDTs will be used in the input record format for those columns. 

Retrieving UDTs with Teradata TPump 

UDTs cannot be retrieved with Teradata TPump. 

Retrieving UDT Metadata with Teradata TPump 

UDT metadata cannot be retrieved with Teradata TPump. 





Glossary 

A 

abend: Abnormal END of a task. Termination of a task prior to its completion because of an 

error condition that cannot be resolved by the recovery facilities that operate during 

execution. 

abort: In Teradata SQL, a statement that stops a transaction in progress and backs out 

changes to the database only if the conditional expression associated with the abort statement 

is true. 

account The distinct account name portion of the system account strings, excluding the 

performance group designation. Accounts can be employed wherever a user object can be 

specified. 

access module: A software component that provides a standard set of I/O functions to 

access data on a specific device. 

Acquisition Phase: Responsible for populating the primary data subtables of the work 

tables. Data is received from the host, converted into internal format, and inserted into the 

work tables. The work tables are sorted at the end of the acquisition phase and prior to the 

application phase. 

administrator: 

A special user responsible for allocating resources to a community of users. 

AMP: Access Module Processor. A vproc that receives steps from a PE and performs 

database functions to retrieve or update data. Each AMP is associated with one vdisk, where 

the data is stored. An AMP manages only its own vdisk and not the vdisk of any other AMP. 

ANSI: American National Standards Institute. ANSI maintains a standard for SQL. For 

information about Teradata compliance with ANSI SQL, see SQL Fundamentals. 

Application Phase: Responsible for turning rows from a work table into updates, deletes, 

and inserts and applying them to a single target table. 

architecture: A definition and preliminary design which describes the components of a 

solution and their interactions. Architecture is the blueprint by which implementers construct 

a solution that meets the defined needs. 

ASCII: American Standard Code for Information Interchange. Pronounced as-key. A 

character set used primarily on personal computers. 

B 

BTEQ: Basic Teradata Query. A utility that allows users on a workstation to access data on 

Teradata Database, and format reports for both print and screen output. A CLI program used 


Glossary 

to interact with Teradata Database. BTEQ commands control sessions, submit Teradata SQL 

requests, format results, and handle output data. BTEQ can also be used to verify the 

installation of Teradata client utilities. 

C 

CLIv2: Call-Level Interface Version 2. A collection of callable service routines that provide 

an interface to Teradata Database. Specifically, CLI is the interface between the application 

program and the Micro Teradata Directory Program (for network-attached clients) or the 

Micro Operating System Interface (for network-attached clients). CLIv2 provides the 

application with a pointer to each of the parcels returned from Teradata Database. 

channel-attached: Peripheral devices directly attached to a computer via a channel or bus. 

The term is used in contrast with devices that are reached remotely over a network 

character set: A grouping of alphanumeric and special characters used by computer systems 

to support different user languages and applications. Various character sets have been codified 

by the American National Standards Institute (ANSI). 

checkpoint rate: The interval between checkpoint operations during the acquisition phase 

of an import task, expressed as either the number of rows read from the client system or sent 

to Teradata Database, or as an amount of time, in minutes. 

client: 

A computer that can access Teradata Database. 

cluster: Logical, table-level archive whereby only those rows residing on specific AMPs, and 

which are members of the specified cluster, are archived onto a single tape data set. This allows 

multiple jobs to be applied for backup of large tables, to reduce the backup window. This 

method is used to affect a parallel archive/restore operation via a “divide and conquer” backup 

strategy. 

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. 

D 

DDL: Data Definition Language. In Teradata SQL, the statements and facilities that 

manipulate database structures (such as CREATE, MODIFY, DROP, GRANT, REVOKE, and 

GIVE) and the Data Dictionary information kept about those structures. 

Data Dictionary: In Teradata Database, the information automatically maintained about all 

tables, views, macros, databases, and users known to Teradata Database, including 

information about ownership, space allocation, accounting, and privilege relationships 

between those objects. Data Dictionary information is updated automatically during the 

processing of data definition statements, and is used by the parser to obtain information 

needed to process all Teradata SQL statements. 


Glossary 

data loading: The process of loading data from a client platform to a Teradata Database 

server. For Teradata TPump, data loading includes any combination of INSERT, UPDATE, 

DELETE, and UPSERT operations. 

data manipulation: In Teradata SQL, the statements and facilities that change the 

information content of the database. These statements include INSERT, UPDATE, and 

DELETE. 

data warehouse: A subject oriented, integrated, time-variant, non-volatile collection of data 

in support of management’s decision making process. A repository of consistent historical 

data that can be easily accessed and manipulated for decision support. 

DBA: Database administrator. Generally, a person responsible for the design and 

management of one or more databases and for the evaluation, selection, and implementation 

of database management systems. 

DD: 

Data dictionary or data definition. See also Data Dictionary. 

DEFINE statement: A statement preceding the INSERT statement that describes the fields 

in a record before the record is inserted in the table. This statement is similar to the SQL 

USING clause. 

DELETE statement: A task that uses a full file scan to remove a large number of rows from a 

single Teradata Database table. A delete task is composed of three major phases: preliminary, 

application, and end. The phases are a collection of one or more transactions that are 

processed in a predefined order according to utility protocol. 

delimiter: In Teradata SQL, a punctuation mark or other special symbol that separates one 

clause in a Teradata SQL statement from another, or that separates one Teradata SQL 

statement from another. 

DLL: Dynamic link library. A feature of the Windows family of operating systems that 

allows executable routines to be stored separately as files with .dll extensions and to be loaded 

only when needed by a program. 

DML: Data manipulation language. In Teradata SQL, the statements and facilities that 

manipulate or change the information content of the database. These statements include 

SELECT, INSERT, UPDATE, and DELETE. 

E 

EBCDIC: Extended binary coded decimal interchange code. An IBM code that uses 8 bits to 

represent 256 possible characters. It is used primarily in IBM mainframes, whereas personal 

computers use ASCII. 

error tables: Tables created during processing that capture any errors that occurred. The 

Teradata convention is to name the tables ET and UV. An ET table contains errors that occur 

during the Acquisition Phase related to data and the data environment (such as constraint 

violations and unavailable AMPs). A UV table contains errors that occur during the 

Application Phase related to violations of unique primary indexes. 


Glossary 

extract: 

The process of copying a subset of data from a source to a target environment. 

exit routines: Specifies a predefined action to be performed whenever certain significant 

events occur during a utility job. 

F 

failure: Any condition that precludes complete processing of a Teradata SQL statement. Any 

failure will abort the current transaction. 

FastExport: Teradata FastExport utility. A program that quickly transfers large amounts of 

data from tables and views of Teradata Database to a client application. 

FastLoad: Teradata FastLoad utility. A program that loads empty tables on Teradata 

Database with data from a network-attached or channel-attached client. 

field: The basic unit of information stored in Teradata Database. A field is either null, or has 

a single numeric or string value. See also column, database, row, table. 

I 

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. 

INMOD Routine: User-written routines that can be used by load/export utilities to 

preprocess input records before they are sent to Teradata Database. Routines can be written in 

C language (for network-attached platforms), orIBM C, (for channel-attached platforms). A 

routine can read and preprocess records from a file, generate data records, read data from 

other database systems, validate data records, and convert data record fields. 

instance: In object-oriented programming, the relationship between an object and its class. 

The object is an instance of the class. 

I/O: 

Input/output 

J 

JCL: Job Control Language. A language for describing jobs (units of work) to the OS/390, z/ 

OS, and VSE operating systems, which run on IBM's OS/390 and z800/900 large server 

(mainframe) computers. These operating systems allocate time and space resources among 

the total number of active jobs. Jobs in turn break down into job steps, which are the 

statements required to run a particular program. Jobs are background (sometimes called 

batch) units of work that run without requiring user interaction (for example, print jobs). In 

addition, the operating system manages interactive (foreground) user requests that initiate 

units of work. In general, foreground work is given priority over background work. 

job script: A set of commands and Teradata SQL statements that can initiate an operation 

that inserts new rows, updates existing rows, and deletes rows in specified target tables and 

views in Teradata Database. 


Glossary 

join: 

result. 

A SELECT operation that combines information from two or more tables to produce a 

L 

locks: Teradata load/unload utilities automatically lock any table being loaded and free a 

lock only after an END LOADING statement is entered. Therefore, tables are only available 

when the operation is complete. 

log: A record of events. A file that records events. Many programs produce log files. Often a 

log file is looked at to determine what is happening when problems occur. Log files have the 

extension “.log”. 

M 

macro: A file created and stored on Teradata Database and executed in response to a 

Teradata SQL EXECUTE statement. Each macro execution is implicitly treated as a 

transaction. 

methods: In object-oriented programming, programming routines by which objects are 

manipulated. 

MultiLoad: Teradata MultiLoad utility. A command-driven utility that performs fast, highvolume 

maintenance functions on multiple tables and views of Teradata Database. 

multiset tables: 

Tables that allow duplicate rows. 

N 

name: A word supplied by the user that refers to an object, such as a column, database, 

macro, table, user, or view. 

network-attached: A computer that communicates over the LAN with a server (for 

example, Teradata Database). 

notify exit: A user-defined exit routine that specifies a predefined action to be performed 

whenever certain significant events occur during a job. For example, by writing an exit in C 

(without using CLIv2) and using the NotifyExit attribute, the routine can detect whether a job 

succeeds or fails, the number of loaded records, the return code for a failed job, and so on. 

null: 

The absence of a value for a field. 

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. 

owner: In Teradata SQL, the user who has the ability to grant or revoke all privileges on a 

database. By default, the creator of the database is the owner, but ownership can be transferred 

from one user to another by the GIVE statement. 


Glossary 

P 

parameter: A variable name in a macro for which an argument value is substituted when 

the macro is executed. 

parser: A program executing in a PE that translates Teradata SQL statements entered by a 

user into the steps that accomplish the user’s intensions. 

PE: Parsing engine. The vprocs that receive SQL requests from the client and break the 

requests into steps. The PE sends the steps to the AMPs and subsequently returns the answer 

to the client. 

primary key: The field (column) in a database table that is indexed and maintains the main 

sequence of the table. For example, account numbers are typically primary keys. A "composite 

primary key" is made up of two or more fields (columns) such as region + account number. A 

primary key is also known as a unique identifier. 

privilege: A user’s right to perform read, write, and execute operations against a table, 

database, user, macro, or view. 

R 

RDBMS (Relational Database Management System): 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. 

records: When using Teradata utilities, both formatted and unformatted records are 

accepted for loading. A formatted record, in the Teradata Database world, consists of a record 

created by a Teradata utility, such as BTEQ, where the record is packaged with begin- and endrecord 

bytes specific to Teradata Database. Unformatted records are any data file, such as a text 

file, that does not have various properties such as a consistent structure with regard to record 

length and order of data elements. These files must be defined before loading onto Teradata 


request: 


In host software, a message sent from an application program to Teradata 

restart log table: 

paused job. 

One of four restart tables that the Teradata utilities require for restarting a 

result: 

The information returned to the user to satisfy a request made of 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. 

S 

schema: Used for identifying the structure of data. Producers have an output schema to 

define what the source data will look like in the data stream. Consumers have an input schema 

to define what is read from the data stream. If the input and output schemas are the same, the 

schema need only be defined once. 


Glossary 

script: 

or job. 

A file that contains a set of commands and SQL statements that initiates an operation 

separator: A character or group of characters that separates words and special symbols in 

Teradata SQL. Blanks and comments are the most common separators. 

server: The computer system running Teradata Database. Typically, a Teradata Database 

server has multiple nodes, which may include both TPA and non-TPA nodes. All nodes of the 

server are connected via the Teradata BYNET or other similar interconnect. 

session: A session begins when the user logs on to Teradata Database and ends when the 

user logs off Teradata Database. Also called a Teradata Database session. In client software, a 

logical connection between an application program on a host and Teradata Database that 

permits the application program to send one request to and receive one response from 

Teradata Database at a time. 

source: The table designated to receive data that is moved or copied from some other source 

file, table, or database. 

SQL: Structured Query Language. An industry-standard language for creating, updating 

and, querying relational database management systems. SQL was developed by IBM in the 

1970s for use in System R. It is the de facto standard as well as being an ISO and ANSI 

standard. It is often embedded in general purpose programming languages. 

The programming language used to communicate with Teradata Database. 

SSO: Single Sign On. An authentication option that allows Teradata users on Windows 

systems to access Teradata Database based on authorized network usernames and passwords. 

This feature simplifies the procedure requiring users to enter an additional username and 

password when logging on to Teradata Database using client applications. 

statement: A request for processing by Teradata Database that consists of a keyword verb, 

optional phrases, operands, and is processed as a single entity. 

statistics: The details of the processes used to collect, analyze, and transform the database 

objects used by a given query. 

T 

table: A set of one or more columns with zero or more rows that consist of fields of related 

information. 

target database: The database designated to receive data that is moved or copied from some 

other source file, table, or database. 

target table: the table designated to receive data that is moved or copied from another table, 

source file, or database. 

TDPID: 

accessed. 

Teradata Director Program Identifier. The name of the Teradata Database being 


Glossary 

Teradata SQL: Teradata Database dialect of the relational language SQL, having data 

definition and data manipulation statements. For example, CREATE TABLE is a data 

definition statement. A data manipulation statement is a data retrieval statement, such as 

SELECT. 

transaction: A set of Teradata SQL statements executed as a unit. All of the statements must 

execute normally or else any changes made during the transaction are backed out and none of 

the remaining statements in the transaction are executed. Teradata Database supports both 

ANSI and Teradata transaction semantics. 

trigger: One or more Teradata SQL statements associated with a table and executed when 

specified conditions are met. 

type: A column attribute that specifies the representation of data values for fields in that 

column. Teradata SQL data types include numerics and strings. 

U 

UDF User-Defined Function. UDFs are extensions to Teradata SQL. Users can write UDFs 

to analyze and transform data already stored in their data warehouse in ways that are beyond 

the functionality of Teradata’s native functions. 

UDM User-Defined Method. A custom function explicitly connected to a UDT. 

Functionality applicable to a UDT can be located in the UDM associated with that UDT 

instead of being replicated to all of the applications that use that UDT, simplifies maintenance. 

UDT User-Defined Type. A collection of one or more data values organized into a single 

customized data type and a set of methods that operates on those values. 

user: In Teradata SQL, a database associated with a person who uses Teradata Database. The 

database stores the person’s private information and accesses other Teradata Databases. 

UPI: Unique primary index; a UPI is required and is typically assigned to major entities in 

the database. 

user: A person who uses Teradata Database. The database stores the person’s private 

information and accesses other Teradata Databases. 

UTF-8: Teradata’s 8-bit multi-byte character set used by Teradata Database to calculate an 

export width based on column character set (Latin, Unicode, KanjiSJIS) and for the session. 

For example "Col1 Char(100) Latin Character set" will be exported as 100 bytes for ASCII 

session and 300 bytes in UTF8. 

UTF-16 

Teradata’s 16-bit multi-byte character set. 

Z 

z/Linux Linux operating system (RedHat or SuSE) compiled to run on IBM System z 

machines. 


Glossary 

z/OS (MVS (Multiple Virtual Storage) 

computers. 

One of the primary operating systems for large IBM 


Glossary 


Index 

Symbols 

- 46 

&SYSAPLYCNT system variable 60 

&SYSDATE system variable 59 

&SYSDATE4 system variable 59 

&SYSDAY system variable 59 

&SYSDELCNT system variable 59 

&SYSETCNT system variable 59 

&SYSINSCNT system variable 59 

&SYSJOBNAME system variable 59 

&SYSNOAPLYCNT system variable 60 

&SYSOS system variable 59 

&SYSRC system variable 59 

&SYSRCDCNT system variable 59 

&SYSRJCTCNT system variable 60 

&SYSUPDCNT system variable 60 

&SYSUSER system variable 60 

(serialize_on_field specification 

DML command 117 

./ prefix 

EXIT name specification, BEGIN EXPORT command 149 

A 

abort termination 52 

aborted Teradata TPump job 

recovery 55 

ACCEPT command 

definition 90 

function 29 

syntax 93 

acctid specification 

LOGON command 168 

Acquisition Error Table 200 

aggregate operators, programming considerations 67 

ALTER TABLE SQL statement 30 

alternate error file runtime parameter 48 

ANSI/SQL DateTime specifications 

programming considerations 62 

restrictions 63 

ANSIDATE keyword 

DATEFORM command 109 

APPEND keyword 

BEGIN LOAD command 97 

application commands 

syntax 89 

APPLY label specification, IMPORT command 152 

ArraySupport keyword 

BEGIN LOAD 101, 118 

Atomic upsert feature 125 

Atomic UPSERT keyword 

EXECUTE command 130 

AXSMOD keyword 

IMPORT command 148 

AXSMOD name, IMPORT command 148 

B 

-b runtime parameter 45 

batch mode 

syntax for invoking on UNIX 43 

syntax for invoking on Windows 43 

syntax for invoking on z/OS 44 

BEGIN LOAD command 

definition 90 

function 29 

in script 69 

syntax 96 

BRIEF runtime parameter 45 

buffers per session runtime parameter 45 

BUFFERS runtime parameter 45 

C 

-c charactersetname runtime parameter 45 

C language INMODs 

programming structure 205 

C language, comment support 63 

-C runtime parameter 47 

character sets 

Chinese and Korean 24 

client system specifications 64 

default 64 

effects on Teradata TPump commands 65 

for AXSMOD 64 

Japanese 23 

runtime parameters 45 

site defined 27 

Teradata Database default 64 

Unicode 25 

UTF-16 26 

UTF-8 26 

character-to-date data conversions 25 

character-to-numeric 

data conversions 25 


Index 

charpos1 94 

charpos2 94 

CHARSET= charactersetname runtime parameter 45 

CHECKPOINT keyword 


CHECKPOINT SQL statement 30 

checkpoints 

description 25 

Chinese and Korean character sets 24 

cname specification 

INSERT command 157 

UPDATE statement 188 

COLLECT STATISTICS SQL statement 30 

command 

function 29 

in script 70 

overview 33 

command functions 28 

commands 

ACCEPT 

definition 90 

function 29 

syntax 93 

BEGIN LOAD 

definition 90 

function 29 

syntax 96 

DATEFORM 

definition 90 

function 29 

syntax 109 

DISPLAY 

definition 90 

function 29 

syntax 113 

DML 

definition 90 

function 29 

syntax 115 

ELSE 

definition 90 

function 29 

syntax 144 

END LOAD 

definition 90 

function 29 

syntax 129 

ENDIF 

definition 90 

function 29 

syntax 144 

FIELD 

definition 90 

function 29 

syntax 133 

FILLER 

definition 90 

function 30 

syntax 142 

IF 

definition 91 

syntax 144 

IMPORT 

definition 91 

function 30 

syntax 146 

LAYOUT 

definition 91 

function 30 

syntax 160 

LOGOFF 

definition 91 

function 29 

syntax 165 

LOGON 

definition 91 

function 29 

syntax 167 

LOGTABLE 

definition 91 

function 29 

syntax 171 

NAME 

definition 91 

function 29 

syntax 173 

PARTITION 

definition 91 

function 30 

syntax 175 

ROUTE 

definition 91 

function 29 

syntax 179 

RUN FILE 

definition 91 

function 29 

syntax 181 

SET 

definition 91 

function 29 

syntax 183 

SYSTEM 

definition 91 

function 29 

syntax 185 

TABLE 

definition 91 


Index 

function 30 

syntax 186 

usage 57 

COMMENT 31 

comment support 63 

condition specification 

LAYOUT command 161 

conditional expression specification 

IF, ELSE, and ENDI command 144 

conditional expressions 57 

CONFIG runtime parameter 47 

configuration file 

optional specification 41 

parameters overridden by runtime parameters 

BRIEF 45 

CHARSET 45 

ERRLOG 48 

runtime parameter 47 

conversions 

character-to-numeric 25 

integer-to-decimal 25 

numeric-to-numeric 25 

CREATE DATABASE SQL statement 31 

CREATE MACRO SQL statement 31 

CREATE TABLE SQL statement 31 

CREATE VIEW SQL statement 31 

D 

-d runtime parameter 48 

data 

file concatenation, programming considerations 67 

data conversions 

capabilities 25 

character-to-date 25 

character-to-numeric 25 

date-to-character 25 

integer-to-decimal 25 

numeric-to-numeric 25 

data definition language 17, 37, 108 

data dictionary, defined 262 

data formats 22 

data manipulation language 17, 37, 108 

data serialization 18 

data types 

ANSI/SQL DateTime 62 

ANSI/SQL DateTime restrictions 63 

database objects 

protection and location 53 

database specification 

DATABASE command 108 


DATABASE SQL statement 31 

definition 92 

syntax 108 

datadesc specification 

FIELD command 134 

FILLER command 142 

DATAENCRYPTION keyword 

BEGIN LOAD command 100, 176 

DATEFORM command 

definition 90 

function 29 

syntax 109 

DateTime data types, specifying 62 

date-to-character data conversions 25 

dbname specification 


LOGTABLE command 171 

dbname. specification 


DDL 17, 37, 108 

ddname specification 


decimal, zoned 25 

DELETE 130 

macro 131 

DELETE DATABASE SQL statement 31 

DELETE DML statement 

in script 70, 71 

DELETE SQL statement 31, 111 

definition 92 

syntax 111 

DISPLAY command 

definition 90 

function 29 

syntax 113 

DISPLAY ERRORS keyword, IMPORT command 152 

DML 17, 29, 33, 37, 70, 108 

DML command 

definition 90 

syntax 115 

DROP DATABASE SQL statement 31 

DROP keyword, FIELD command 135 

dynamn entry point 

for C INMOD routines 205, 206 

for IBM C INMOD routines 205, 206 

E 

-e filename runtime parameter 48 

echo 179 

ELSE command 

definition 90 

function 29 

syntax 144 

END LOAD command 

definition 90 


Index 

function 29 

in script 71 

syntax 129 

ENDIF command 

definition 90 

function 29 

syntax 144 

env_var 93 

errcount specification 


ERRLIMIT keyword 


ERRLOG=filename runtime parameter 48 

error detection 195 

error tables 

acquisition 200 

reading 199 

troubleshooting 199 

errors 195 

ERRORTABLE keyword 


EXECUTE SQL statement 

definition 92 

EXECUTE statement 

syntax 130 

EXIT keyword 


EXIT name specification, BEGIN LOAD command 105 

exit routines, definition 204 

expr specification 


expression specification 


SET command 183 

expressions, programming considerations 67 

F 

-f runtime parameter 45 

features, advanced, INMODs 203 

FIELD command 

definition 90 

function 29 

in script 70 

syntax 133 

fieldexpr specification 


fieldname specification 




file requirements 

for invoking Teradata TPump 41 

fileid 94, 113 

filename specification 


FILLER command 

definition 90 

function 30 

in script 70 

syntax 142 

FOR n specification, IMPORT command 150 

FREE option, IMPORT command 149 

frequency specification 


FROM keyword 


G 

GIVE SQL statement 31 

GRANT SQL statement 31 

graphic constants 

hexadecimal 67 

KanjiEBCDIC 67 

support for 67 

graphic data types 

support for 66 

H 

HOLD option 


hours specification 


I 

IF command 

definition 91 

syntax 144 

IGNORE keyword 


IMPORT command 

definition 91 

function 30 

in script 71 

syntax 146 

INDICATORS keyword 


INFILE filename specification 


INFILE keyword 

IMPORT command 147, 149 

infilename standard input file specification 50 

init-string specification 


INMODs 203 

compiling and linking 218 


Index 

FastLoad 215 

IBM interface 214 

input return code values 216 

input values 216, 217 

interface 214 

major functions 203 

output return code values 217 

preparing program 216 

programming 218 

routines 

entry points 205 

platforms supported 204 

programming languages supported 204 

programming structure 205 

rules and restrictions 211 

using 213 

Teradata TPump interface 214 

UNIX interface 214 

UNIX programming 218 

Windows interface 215 

input/output 

controlling 38 

INSERT DML statement 

in script 70 

INSERT keyword 



INSERT macro 131 

INSERT SQL statement 31 

definition 92 

syntax 157 

INTEGERDATE keyword 

DATEFORM command 109 

integer-to-decimal 


internationalization 18 

invoking 

on UNIX platform 42 

on Windows platform 42 

invoking Teradata TPump 41 

J 

Japanese character sets 23 

job 

recovery if aborted 55 

jobname specification 

NAME command 173 

K 

kanjiEBCDIC 

graphic constants 67 

KEY keyword, FIELD command 135 

keyword 


Korean and Chinese character sets 24 

L 

LABEL keyword 


label specification 



LATENCY keyword 


LAYOUT command 

definition 91 

function 30 

in script 70 

syntax 160 

LAYOUT name specification, IMPORT command 152 

layoutname specification 



lock 

access 34 

acquisition 34 

application 34 

row hash locking 34 

write 34 

log table 

space requirement calculation example 86 

space requirements 85 

LOGDATA command 

syntax 163 

LOGMECH command 

syntax 164 

LOGOFF command 

definition 91 

function 29 

messages 80 

syntax 165 

logoff/disconnect message 75 

LOGON command 

definition 91 

function 29 

syntax 167 

LOGTABLE command 

definition 91 

function 29 

syntax 171 

logtables 

non-shareability 171 

space requirements 172 

M 

-m runtime parameter 49 


Index 

macro runtime parameters 49 

MACRODB keyword 


macros 33 

predefined 34 

Teradata TPump usage 18 

MACROS runtime parameter 49 

MARK keyword 


maximum 

row size, programming considerations 67 

messages 179 

minutes specification 


MODIFY DATABASE SQL statement 31 

monitor facility 81 

MSG string specification, BEGIN LOAD command 105 

MultiLoad utility 

data conversion capabilities 25 

MULTISET table 104 

N 

name 130 

NAME command 

definition 91 

function 29 

syntax 173 

name specification 



Named Pipes Access Module 148 

No Primary Index tables 19 

NOATOMICUPSERT 104 

NODROP keyword 


NOMONITOR keyword 


non-shareability 

logtables 171 

NoPI tables 19 

normal termination 51 

NOSTOP keyword, IMPORT command 152 

NOTIFY option specification, BEGIN LOAD command 105 

NOTIMERPROCESS keyword 


nullexpr specification 


number specification 


PARTITION command 175 

numeric-to-numeric 


O 

operators 

reserved words 56 

options messages 75, 79 

oscommand string specification 

SYSTEM command 185 

outfilename standard output file specification 50 

P 

pack factor 85, 86 

PACK keyword 



packing 119, 158 

packing factor 85, 103, 104, 177 

PACKMAXIMUM keyword 



parms specification 


PARTITION command 

definition 91 

function 30 

syntax 175 

PARTITION keyword 


partition_name specification 



password specification 


performance checklist 

troubleshooting 

performance checklist 202 

periodicity runtime parameter 48 

PRDICITY runtime parameter 48 

predefined 

macros 34 

preparing a Teradata TPump script 69 

privileges 34 

product version numbers 3 

programming INMODs 

for UNIX-based clients 218 

UNIX-based clients 218 

R 

-r tpump command runtime parameter 49 

RATE keyword 


recovery 

aborted Teradata TPump job 55 

procedures 52 


Index 

reduced print output runtime parameter 45 

redundant conversions 

supported 25 

RENAME SQL statement 31 

REPLACE MACRO SQL statement 31 

REPLACE VIEW SQL statement 31 

reporting 

options messages 79 

statistics 75 

restart 76 

reserved words 

use in Teradata TPump 56 

restart 

statistics 76 

restart log table 52, 53 

restart procedures 52 

restrictions and limitations 

programming considerations 

aggregate operators 67 

data file concatenation 67 

expressions 67 

maximum row size 67 

Teradata RDBMS data retrieval 67 

retcode specification 

LOGOFF command 165 

return codes 51 

REVOKE SQL statement 31 

ROBUST keyword 


ROUTE command 

definition 91 

function 29 

syntax 179 

row 

size, maximum 67 

row count variables 61 

row hash locking 34 

RUN FILE command 

definition 91 

function 29 

syntax 181 

S 

script 

example 72 

preparation 69 

writing guidelines 69 

writing procedure 71 

scriptencoding parameter 46 

seconds specification 


SERIALIZE keyword 


SERIALIZEON keyword 


sessions 91, 96, 101, 165, 167 

SESSIONS keyword 



SET command 

definition 91 

function 29 

syntax 183 

SET QUERY_BAND SQL statement 31 

SET SESSION COLLATION SQL statement 31 

single sign on 167 

SLEEP keyword 97, 101, 177 


software releases 

supported 3 

space requirements 

for Teradata TPump log tables 85 

log table 85 

SQL 

defined 267 

SQL statements 

DATABASE 

definition 92 

syntax 108 

DELETE 

definition 92 

syntax 111 

EXECUTE 

definition 92 

syntax 130 

INSERT 

definition 92 

syntax 157 

supported by Teradata TPump 30 

UPDATE 

definition 92 

syntax 188 

SQL, Teradata 37 

SSO 


starting Teradata TPump 

on UNIX platform 42 

on Windows platform 42 

startpos specification 



statement_rate specification 


statements 33 

statements specification 




Index 

statements to execute if FALSE specification 

IF, ELSE, and ENDIF command 144 

statements to execute if TRUE specification 


statements to resume with specification 


statistics 75 

facility 74 

restart 76 

string variable 

MSG specification, BEGIN LOAD command 105 

TEXT specification, BEGIN LOAD command 105 

support commands, defined 28 

support environment 37 

SYSAPLYCNT system variable 60 

SYSDATE system variable 59 

SYSDATE4 system variable 59 

SYSDAY system variable 59 

SYSDELCNT system variable 59 

SYSETCNT system variable 59 

SYSINSCNT system variable 59 

SYSJOBNAME 29 

SYSJOBNAME system variable 59 

SYSNOAPLYCNT system variable 60 

SYSOS system variable 59 

SYSRC system variable 59 

SYSRCDCNT system variable 59 

SYSRJCTCNT system variable 60 

SYSTEM command 

definition 91 

function 29 

syntax 185 

system failure 

restart and recovery 52 

system variables 

&SYSAPLYCNT 60 

&SYSDATE 59 

&SYSDATE4 59 

&SYSDAY 59 

&SYSDELCNT 59 

&SYSETCNT 59 

&SYSINSCNT 59 

&SYSJOBNAME 59 

&SYSNOAPLYCNT 60 

&SYSOS 59 

&SYSRC 59 

&SYSRCDCNT 59 

&SYSRJCTCNT 60 

&SYSTIME 

&SYSTIME system variable 60 

&SYSUPDCNT 60 

&SYSUSER 60 

SYSTIME system variable 60 

SYSUPDCNT system variable 60 

SYSUSER system variable 60 

T 

TABLE command 

definition 91 

function 30 

in script 70 

syntax 186 

tableref specification 

TABLE command 186 

tables 

fallback 36 

nonfallback 36 

task 

commands 28 

task commands 38 

syntax and usage 89 

usage 57 

tdpid specification 


TENACITY keyword 101 


Teradata OLE DB Access Module 148 

Teradata RDBMS 

data retrieval, programming considerations 67 

Teradata SQL 37 

Teradata SQL statements 



advanced features 203 

invoking 

batch mode on UNIX 43 

batch mode on Windows 43 

batch mode on z/OS 44 

macros 33 

Monitor facility 81 

Monitor facility interface 81 

script, example of 72 

support command, defined 28 

support environment 38 

using INMOD routines 213 

Teradata TPump Conditional Expressions 57 

Teradata TPump/INMOD Routine Interface 206 

Teradata WebSphere® MQ Access Module 148 

Teradata WebSphere® MQ Access Module (server version) 

148 

terminating a Teradata TPump job 52 

termination 

return codes 51 

text 113 

TEXT string specification, BEGIN LOAD command 105 

threshold specification 



Index 

THRU keyword 


time and date variables 60 

tname specification 


DELETE statement 111 


LOGTABLE command 171 


tpump command runtime parameter 49 

troubleshooting 195 

early error detection 195 

error detection 195 

reading error tables 199 

U 

Unicode 

character sets 25 

UNIX 

starting Teradata TPump 42 

syntax for invoking in batch mode 43 

UPDATE DML statement 70 

in script 70 

UPDATE keyword 


UPDATE macro 131 

UPDATE SQL statement 31 

definition 92 

syntax 188 

upsert 

Atomic 125 

example 123 

feature 33, 123 

UPSERT keyword 33 



UPSERT macro 131 

USE keyword 


use_field specification 


username specification 


USING (parms) specification 


USING keyword 


UTF-16 


UTF16 


utility variables 


V 

-v 75 

-V runtime parameter 50 

-v runtime parameter 49 

var 93 

var specification 

SET command 183 

variables 

date and time 

date and time variables 60 

row count 61 

substitution 62 

utility 


VARTEXTvariable-length text record format 151 

verbose mode runtime parameter 49 

VERBOSE runtime parameter 49 

version numbers 3 

W 

WHERE condition specification 

DELETE statement 111 



Windows 

starting Teradata TPump 42 


Z 

z/OS 


zoned decimal format 25 


Index

Teradata Parallel Data Pump

You also want an ePaper? Increase the reach of your titles

Delete template?

Save as template?