Download - Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Transcript
Page 1: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Teradata Parallel Data PumpReference

Release 13.10B035-3021-020A

February 2010

Page 2: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

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

Teradata, BYNET, DBC/1012, DecisionCast, DecisionFlow, DecisionPoint, Eye logo design, InfoWise, Meta Warehouse, MyCommerce, SeeChain, SeeCommerce, SeeRisk, Teradata Decision Experts, Teradata Source Experts, WebAnalyst, and You’ve Never Seen Your Business Like This Before are trademarks or registered trademarks of Teradata Corporation or its affiliates.

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

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

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

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

GoldenGate is a trademark of GoldenGate Software, Inc.

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

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

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

Linux is a registered trademark of Linus Torvalds.

LSI and Engenio are registered trademarks of LSI Corporation.

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

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

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

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

SPARC is a registered trademark of SPARC International, Inc.

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

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

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

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

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

THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROVIDED ON AN “AS-IS” BASIS, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO THE ABOVE EXCLUSION MAY NOT APPLY TO YOU. IN NO EVENT WILL TERADATA CORPORATION BE LIABLE FOR ANY INDIRECT, DIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS OR LOST SAVINGS, EVEN IF EXPRESSLY ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

The information contained in this document may contain references or cross-references to features, functions, products, or services that are not announced or available in your country. Such references do not imply that Teradata Corporation intends to announce such features, functions, products, or services in your country. Please consult your local Teradata Corporation representative for those features, functions, products, or services available in your country.

Information contained in this document may contain technical inaccuracies or typographical errors. Information may be changed or updated without notice. Teradata Corporation may also make improvements or changes in the products or services described in this information at any time without notice.

To maintain the quality of our products and services, we would like your comments on the accuracy, clarity, organization, and value of this document. Please e-mail: [email protected]

Any comments or materials (collectively referred to as “Feedback”) sent to Teradata Corporation will be deemed non-confidential. Teradata Corporation will have no obligation of any kind with respect to Feedback and will be free to use, reproduce, disclose, exhibit, display, transform, create derivative works of, and distribute the Feedback and derivative works thereof without limitation on a royalty-free basis. Further, Teradata Corporation will be free to use any ideas, concepts, know-how, or techniques contained in such Feedback for any purpose whatsoever, including developing, manufacturing, or marketing products or services incorporating Feedback.

Copyright © 1996-2010 by Teradata Corporation. All Rights Reserved.

Page 3: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

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

Page 4: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

PrefacePrerequisites

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 Description

February 2010Teradata Tools and Utilities 13.10

• 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.

April 2009Teradata Tools and Utilities 13.00

• 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

Page 5: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

PrefaceAdditional Information

Additional Information

Additional information that supports this product and Teradata Tools and Utilities is available at the web sites listed in the table that follows. In the table, mmyx represents the publication date of a manual, where mm is the month, y is the last digit of the year, and x is an internal publication code. Match the mmy of a related publication to the date on the cover of this book. This ensures that the publication selected supports the same release.

August 2008Teradata Tools and Utilities 13.00

• 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

Date and Release Description

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

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

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.

Teradata Parallel Data Pump Reference 5

Page 6: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

PrefaceAdditional Information

Additional product information

Use the Teradata Information Products web site to view or download specific manuals that supply related or additional information to this manual.

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

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 ReferenceB035-3021-mmyx

• Teradata Tools and Utilities Command SummaryB035-2401-mmyx

• Teradata Tools and Utilities Access Module Programmer Guide B035-2425-mmyx

CD-ROM images Access a link to a downloadable CD-ROM image of all customer documentation for this release. Customers are authorized to create CD-ROMs for their use from this image.

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

2 Under the Online Publications subcategory, Browse by Category, click Data Warehousing.

3 Click CD-ROM List and Images.

4 Follow the ordering instructions.

Ordering information for manuals

Use the Teradata Information Products web site to order printed versions of manuals.

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

2 Under Print & CD Publications, click How to Order.

3 Follow the ordering instructions.

General information about Teradata

The Teradata home page provides links to numerous sources of information about Teradata. Links include:

• Executive reports, case studies of customer experiences with Teradata, and thought leadership

• Technical information, solutions, and expert advice

• Press releases, mentions, and media resources

1 Go to Teradata.com.

2 Select a link.

Type of Information Description Access to Information

6 Teradata Parallel Data Pump Reference

Page 7: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

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

Teradata Parallel Data Pump Reference 7

Page 8: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Table of Contents

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

8 Teradata Parallel Data Pump Reference

Page 9: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Table of Contents

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

Teradata Parallel Data Pump Reference 9

Page 10: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Table of Contents

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

10 Teradata Parallel Data Pump Reference

Page 11: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Table of Contents

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

Teradata Parallel Data Pump Reference 11

Page 12: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Table of Contents

Appendix C: INMOD and Notify Exit Routine Examples . . . . . . . . . . . . . . . . . . . . . . .247

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

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

Appendix D: User-Defined-Typesand 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

12 Teradata Parallel Data Pump Reference

Page 13: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

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

Teradata Parallel Data Pump Reference 13

Page 14: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

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

14 Teradata Parallel Data Pump Reference

Page 15: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

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:

Teradata Parallel Data Pump Reference 15

Page 16: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 1: OverviewTeradata TPump Utility

• 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 network-attached 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.

Complementing MultiLoad

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.

16 Teradata Parallel Data Pump Reference

Page 17: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 1: OverviewTeradata TPump Utility

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.

Teradata Parallel Data Pump Reference 17

Page 18: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 1: OverviewTeradata TPump Utility

• 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.

How it Works

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.

18 Teradata Parallel Data Pump Reference

Page 19: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 1: OverviewTeradata TPump Utility

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 Parallel Data Pump Reference 19

Page 20: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 1: OverviewTeradata TPump Utility

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

20 Teradata Parallel Data Pump Reference

Page 21: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 1: OverviewTeradata TPump Utility

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

Teradata Parallel Data Pump Reference 21

Page 22: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 1: OverviewOperating Features and Capabilities

very reason that they are so resource-intensive. Teradata TPump has no such database-imposed 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.

Operating Features and Capabilities

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 Description

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

FASTLOAD 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'.

TEXT Specifies that each input record is an arbitrary number of bytes followed by an end-of-record marker, which is a:

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

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

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

VARTEXT Specifies that each variable-length text record has each field separated by a delimiter character.

22 Teradata Parallel Data Pump Reference

Page 23: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 1: OverviewOperating Features and Capabilities

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.”

Client Character Sets

Standard Character Sets

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

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.

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

Table 2: Standard Character Sets

Standard Character Sets

System Configuration Name

Channel-Attached EBCDIC

Network-Attached ASCII

Table 3: Japanese Character Sets

Japanese Character Sets

System Configuration Character Set Name

Channel-Attached KATAKANAEBCDIC

KANJIEBCDIC5026_0I

KANJIEBCDIC5035_0I

Network-Attached KANJIEUC_0U

KANJISJIS_0S

Teradata Parallel Data Pump Reference 23

Page 24: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 1: OverviewOperating Features and Capabilities

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 5 lists the Korean character sets:

Rules for Using Chinese and Korean Character Sets

Certain rules apply when using Chinese and Korean character sets on channel- and network-attached 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 multi-byte 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.

Table 4: Chinese Character Sets

Chinese Character Sets

System Configuration Name

Channel-Attached SCHEBCDIC935_2IJ

TCHEBCDIC937_3IB

Network-Attached SCHGB2312_1T0

TCHBIG5_1R0

Table 5: Korean Character Sets

Korean Character Sets

System Configuration Name

Channel-Attached HANGULEBCDIC933_1II

Network-Attached HANGULKSC5601_2R4

24 Teradata Parallel Data Pump Reference

Page 25: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 1: OverviewOperating Features and Capabilities

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.

Teradata Parallel Data Pump Reference 25

Page 26: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 1: OverviewOperating Features and Capabilities

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.

26 Teradata Parallel Data Pump Reference

Page 27: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 1: OverviewTeradata TPump Commands

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 Commands

Teradata TPump accepts both Teradata TPump commands and a subset of Teradata SQL statements. These are described in the following sections:

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

Teradata Parallel Data Pump Reference 27

Page 28: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 1: OverviewTeradata TPump Commands

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 8 lists the Teradata TPump commands that perform the support and task activities:

Table 7: Teradata TPump Command Input Activities

Activity Description

Support 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.

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.

28 Teradata Parallel Data Pump Reference

Page 29: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 1: OverviewTeradata TPump Commands

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 Lets the form of the DATE data type specifications be defined for the Teradata TPump job

DISPLAY Writes messages to the specified destination

ELSE (see IF, ELSE, and ENDIF)

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

ENDIF (see IF, ELSE, and ENDIF)

Delimits the group of Teradata TPump commands and statements that were subject to previous IF or ELSE commands or both

IF (see IF, ELSE, and ENDIF)

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

LOGDATA Supplies parameters to the LOGMECH command beyond those needed by the logon mechanism, such as user ID and password, to successfully authenticate the user

LOGMECH Identifies the appropriate logon mechanism by name

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

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

LOGTABLE 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

NAME 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

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

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

SET Assigns a data type and a value to a utility variable

SYSTEM 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 Defines a field of the data source recordUsed with LAYOUT command

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

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

Teradata Parallel Data Pump Reference 29

Page 30: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 1: OverviewTeradata TPump Commands

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.

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

IMPORT Identifies the data source, the layout, and the DML operation(s) to be performed, with optional conditions for performing these operations

LAYOUT Introduces the record format of the data source to be used in the Teradata TPump taskThis command is followed by a sequence or combination of FIELD, FILLER, and TABLE commands.

PARTITION Establishes session partitions to transfer SQL requests to Teradata Database

TABLE Identifies a table whose column names and data descriptions are used as the field names and data descriptions of the data source recordsUsed with LAYOUT command

Table 8: Teradata TPump Commands (continued)

Activity

Teradata TPump Command Function

Table 9: teradata SQL Statements in Teradata TPump

Teradata SQL Statement Function

ALTER TABLE Changes the column configuration or options of an existing table

CHECKPOINT Adds checkpoint entry to a journal table

COLLECT STATISTICS Collects statistical data for one or more columns of a table

30 Teradata Parallel Data Pump Reference

Page 31: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 1: OverviewTeradata TPump Commands

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.

COMMENT Stores or retrieves a comment string associated with a database object

CREATE DATABASECREATE MACROCREATE TABLECREATE VIEW

Creates a new database, macro, table, or view

DATABASE Specifies a new default database for the current session

DELETE Removes rows from a table

DELETE DATABASE Removes all tables, views, and macros from a database

DROP DATABASE Removes an empty table from Teradata Database

EXECUTE 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.

GIVE Transfers ownership of a database to another user

GRANT Grants privileges to a database object

INSERT Inserts new rows to a table

MODIFY DATABASE Changes the options of an existing database

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

REPLACE MACROREPLACE VIEW

Redefines an existing macro or view

REVOKE Rescinds privileges to a database object

SET QUERY_BAND 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 Overrides the collation specification for the current session

SET SESSION OVERRIDE REPLICATION ON/OFF

Turn on/off replication service

UPDATE Statement and Atomic Upsert

Changes the column values of an existing row in a table

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

Teradata SQL Statement Function

Teradata Parallel Data Pump Reference 31

Page 32: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 1: OverviewThe 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

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

32 Teradata Parallel Data Pump Reference

Page 33: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 1: OverviewThe Teradata TPump Task

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

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.

Upsert Feature

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.

Teradata TPump Macros

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.

Teradata Parallel Data Pump Reference 33

Page 34: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 1: OverviewThe Teradata TPump Task

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

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.

Privileges

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.

34 Teradata Parallel Data Pump Reference

Page 35: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 1: OverviewThe Teradata TPump Task

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:

column_reference = colon_variable_reference

or

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

Teradata Parallel Data Pump Reference 35

Page 36: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 1: OverviewThe Teradata TPump Task

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 Nonfallback 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 one or more AMPs are down prior to entering the task and if one or more target tables are nonfallback, Teradata TPump terminates.

If two or more AMPs in a cluster are logically or physically down, or both, the task does not run, or terminates if running.

The Teradata TPump task may be restarted as soon as all AMPs are back up.

During the task, if AMPs are down to the extent that data on the disk is corrupted, the affected tables must be restored.

If an AMP goes down once the task has started, the task cannot be restarted until all AMPs are back up.

Not applicable. If more than one AMP in the same cluster is down, Teradata Database cannot come up.

Not applicable. Certain I/O errors during the task corrupt the target table so that it must be restored. In this case, Teradata TPump terminates.

36 Teradata Parallel Data Pump Reference

Page 37: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

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 Database.

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.

Teradata Parallel Data Pump Reference 37

Page 38: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpInvoking 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.

38 Teradata Parallel Data Pump Reference

Page 39: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpInvoking Teradata TPump

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;

Teradata Parallel Data Pump Reference 39

Page 40: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpInvoking Teradata TPump

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 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 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 : LABEL0044Type 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.

40 Teradata Parallel Data Pump Reference

Page 41: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpInvoking Teradata TPump

**** 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:

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.

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

Data Set/File or Device Provides

standard input Teradata TPump commands and Teradata SQL statements that make up a Teradata TPump job

standard output Destination for Teradata TPump output responses and messages

standard error Destination for Teradata TPump errors

configuration Optional specification of Teradata TPump utility default values

Teradata Parallel Data Pump Reference 41

Page 42: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpInvoking Teradata TPump

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

Start the Teradata TPump utility on Teradata Database for UNIX and Windows with a UNIX-style 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.

Interactive Mode

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:

======================================================================== = = = Teradata Parallel Data Pump Utility Release 13.10.00.000 = = Platform WIN32 = = = ======================================================================== = = = Copyright 1997-2010 Teradata Corporation. ALL RIGHTS RESERVED. = = = ========================================================================**** 11:54:53 UTY2411 Processing start date: WED NOV 18, 2009 ========================================================================

42 Teradata Parallel Data Pump Reference

Page 43: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpInvoking Teradata TPump

= = = Logon/Connection = = = ========================================================================

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:

Batch Mode on Network-attached Windows 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 Windows client systems:

3021E016

tpump

-C filename

-d periodicityvalue

-e errorfilename

c

-b

-f numberofbuffers

-m

-r 'tpump command'

-y

< infilename > outfilename

charactersetname

-v

-i scriptencoding

-u outputencoding

-t nn

-V

Teradata Parallel Data Pump Reference 43

Page 44: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpInvoking Teradata TPump

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

Refer to the runtime parameter descriptions in Table 12 on page 45 and use the following syntax to invoke Teradata TPump on channel-attached z/OS client systems.

Run-time Parameters

Table 12 describes the run-time parameters used by Teradata TPump on channel-attached and network-attached systems.

3021E015

tpump

-C filename

-d periodicityvalue

-e errorfilename

-c

-b

-f numberofbuffers

-m

-r "tpumpcommand"

-v

< infilename > outfilename

charactersetname

-y

-i scriptencoding

-u outputencoding-t nn

-V

3021D014

// EXEC TDSTPUMP

CONFIG = filename

MACROS

PRDICITY = periodicityvalue

ERRLOG = filename

BUFFERS = numberofbuffers

BRIEF

VERBOSE

'tpump command'

PARM = , ,

CHARSET = charactersetname

RTYTIMES = nn

RVERSION

44 Teradata Parallel Data Pump Reference

Page 45: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpInvoking Teradata TPump

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

-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.

CHARSET =charactersetname

-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.

Teradata Parallel Data Pump Reference 45

Page 46: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpInvoking Teradata TPump

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

• UTF-16 or UTF16

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.

Table 12: Run-time Parameters/Systems (continued)

Channel-attached Network-attached Description

46 Teradata Parallel Data Pump Reference

Page 47: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpInvoking Teradata TPump

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-16 or UTF16

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:

<keyword> <value>

• 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.

Table 12: Run-time Parameters/Systems (continued)

Channel-attached Network-attached Description

Teradata Parallel Data Pump Reference 47

Page 48: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpInvoking Teradata TPump

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

-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.

ERRLOG=error filename

-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.

Table 12: Run-time Parameters/Systems (continued)

Channel-attached Network-attached Description

48 Teradata Parallel Data Pump Reference

Page 49: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpInvoking Teradata TPump

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.

Table 12: Run-time Parameters/Systems (continued)

Channel-attached Network-attached Description

Teradata Parallel Data Pump Reference 49

Page 50: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpInvoking Teradata TPump

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/test1 >/home/tpuser/tests/out1

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.

Table 12: Run-time Parameters/Systems (continued)

Channel-attached Network-attached Description

50 Teradata Parallel Data Pump Reference

Page 51: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpTerminating 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/test1

Example 3

This example specifies only an output file. Enter the TPump script via stdin, normally at the terminal. When input is complete, type Control-D to indicate end-of-file. Type Control-D by simultaneously pressing the Control key and the letter D. The job output is written to /home/tpuser/tests/out1.

tpump >/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

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

Normal 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:

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

HE03A003

.LOGOFF

retcode

;

Teradata Parallel Data Pump Reference 51

Page 52: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpRestart and Recovery

• 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.

Abort Termination

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.”.

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.

52 Teradata Parallel Data Pump Reference

Page 53: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpRestart and Recovery

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.

Teradata Parallel Data Pump Reference 53

Page 54: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpRestart and Recovery

• 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 LAY1AAPPLY TAB1PART1APPLY 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:

<JobName>_nnn_ET

Where nnn is the load sequence number.

54 Teradata Parallel Data Pump Reference

Page 55: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpRestart and Recovery

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.

Teradata Parallel Data Pump Reference 55

Page 56: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpProgram 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.

Program Considerations

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.

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

Table 13: Teradata TPump Operators

Commands

AND BETWEEN EQ

GE GT IN

IS LE LIKE

LT MOD NE

NOT NULL OR

56 Teradata Parallel Data Pump Reference

Page 57: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpProgram Considerations

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.

These conditional expressions are similar to those described in SQL Functions, Operators, Expressions, and Predicates, with the following exceptions:

1 In the reference manual, a column name in a conditional expression is equivalent, in this document, to the field name, in records from an external data source or a utility variable.

2 In logical expressions that make up a conditional expression, the LIKE operator is not supported. In these expressions, only the following operators are supported:

a All comparison operators documented in SQL Functions, Operators, Expressions, and Predicates.

b NOT IN operator (only the first of the two forms).

3 In arithmetic expressions that make up a logical expression, the following elements are not supported:

a The exponentiation operator

b Aggregate operators

c Arithmetic functions

Use Task Commands

A BEGIN LOAD command must begin each task to declare, at a minimum, the number of sessions involved in the load.

Table 14: Teradata TPump Conditional Expressions

Commands

+ - / MOD NOT

|| IS NOT NULL IS NULL EQ

= NE <> ^=

NOT= ~= GE >=

GT > LE <=

LT < BETWEEN NOT BETWEEN

AND OR IN NOT IN

Teradata Parallel Data Pump Reference 57

Page 58: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpProgram Considerations

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.

58 Teradata Parallel Data Pump Reference

Page 59: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpProgram Considerations

Table 15: Predefined System Variables

System Variable Description

&SYSDATE 8-character date format yy/mm/dd

&SYSDATE4 10-character date format yyyy/mm/dd

&SYSDAY 3-character day of week: MON TUE WED THU FRI SAT SUN

&SYSDELCNT[n} 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.

&SYSETCNT[n} 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.

&SYSINSCNT[n} 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.

&SYSJOBNAME 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 = macroYYYY = yearMM = monthDD = dayhh = hourmm = minutess = secondlllll = is the low-order 5 digits of the logon sequence number returned by the database from the .LOGON command.

&SYSOS Client operating system:

• UNIX

• HP-UX

• IBM-AIX

• Win32

• Linux

• For z/OS:

VS1

z/OS

z/OS /SP

z/OS /ESA

&SYSRC Completion code from last response by Teradata Database.

&SYSRCDCNT[n] Total number of records read for import n. If n is not specified, it gives the total records read for all imports.

Teradata Parallel Data Pump Reference 59

Page 60: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpProgram Considerations

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, 1993UTY2402 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),

&SYSTIME 8-character time format hh:mm:ss

&SYSUPDCNT[n] 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.

&SYSUSER 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).

&SYSAPLYCNT[n] Number of records applied for import n. If n is not given, it gives the total number of records applied for all imports.

&SYSNOAPLYCNT[n] 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.

&SYSRJCTCNT[n] 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.

Table 15: Predefined System Variables (continued)

System Variable Description

60 Teradata Parallel Data Pump Reference

Page 61: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpProgram Considerations

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 <C> Continue anyway...'to FILE console;

.DISPLAY '&SYSUSER: Reply <A> Abort this JOB....'to FILE console;

.DISPLAY '&SYSUSER: Reply <C> or <A>.Default <A>'to FILE console;

.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 <macroname> 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

Teradata Parallel Data Pump Reference 61

Page 62: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpProgram Considerations

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:

62 Teradata Parallel Data Pump Reference

Page 63: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpProgram Considerations

• 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 fixed-length 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.

Teradata Parallel Data Pump Reference 63

Page 64: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpProgram Considerations

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 16: Ways to Either Specify a Character Set or Accept a Default Specification

Specification or Default Selection Description

Runtime parameter specification 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

Client System Specification 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.

Teradata Database Default 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

Teradata TPump Utility Default 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

64 Teradata Parallel Data Pump Reference

Page 65: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpProgram Considerations

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 17: Character Set Specifications for AXSMOD

Specify the session character set by Attribute name is

ID CHARSET_NUMBER

name CHARSET_NAME

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.

Teradata Parallel Data Pump Reference 65

Page 66: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpProgram Considerations

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.

FILLER Filler name The name specified in a FILLER command may contain multibyte characters.

IF IF condition The condition in an IF statement may compare multibyte character strings.

LAYOUT Layout nameCONTINUEIF condition

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.

LOGON User namePassword

The user name and password may contain multibyte characters.

LOGTABLE Table nameDatabase name

The logtable name and database name may contain multibyte characters.

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.

Table 18: Character Sets Impact on Teradata TPump Commands (continued)

Teradata TPump Command Affected Element Impact

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 <= n 2-byte integer, followed by m/2 double-byte characters

66 Teradata Parallel Data Pump Reference

Page 67: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpProgram Considerations

Graphic Constants

Teradata TPump supports two forms of graphic constants. The graphic literal or string constant is allowed only in the kanji EBCDIC character sets. It must have an even number of bytes within the quoted string to represent double-byte characters.

The two forms of graphic constants are as follows.

• The kanjiEBCDIC graphic constant form (used for the IBM mainframe)

• The hexadecimal representation of graphic data (used for both the IBM mainframe and network platforms)

For more information on graphic constants and hexadecimal constants, refer to SQL Fundamentals.

Restrictions and Limitations

Table 20 describes Teradata TPump restrictions and limitations on operational features and functions.

LONG VARGRAPHIC m+2 bytes where m/2 <=32000 2-byte integer, followed by m/2 double-byte characters

Table 19: GRAPHIC Data Types for datadesc option in FIELD or FILLER Statement (continued)

GRAPHIC Data Type Input Length Description

Table 20: Restrictions and Limitations on Operational Features and Functions

Operational Feature/Function Restriction/Limitation

Maximum row size The maximum row size for a Teradata TPump job, data plus indicators, is approximately 64,000 bytes. This limit is a function of the row size limit of Teradata Database.

• Aggregate operators

• Concatenation of data files

• Data retrieval from Teradata Database via SELECT statements

Not allowed

Expressions Evaluated from left to right, using the Teradata Database order of preference, but can be overridden by parentheses.

IMPORT commands Limit of four IMPORT commands within a single Teradata TPump load task.

Teradata Parallel Data Pump Reference 67

Page 68: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpProgram Considerations

Termination Return Codes

When a Teradata TPump job terminates, it returns a completion code to the client system.

Table 21 lists the conventions used.

Note: To avoid ambiguous or conflicting results, always use values greater than 20 when specifying a return code with the LOGOFF command.

Date specification 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-mm-dd'));

Access logging 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.

Primary Indexes and Partitioning Column Sets

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.

Table 20: Restrictions and Limitations on Operational Features and Functions (continued)

Operational Feature/Function Restriction/Limitation

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

68 Teradata Parallel Data Pump Reference

Page 69: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpWriting 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.

Writing a Teradata TPump Job Script

This section describes the contents of a Teradata TPump job script and explains how to write one.

Definition

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.

Caution: 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

Teradata Parallel Data Pump Reference 69

Page 70: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpWriting a Teradata TPump Job Script

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

70 Teradata Parallel Data Pump Reference

Page 71: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpWriting a Teradata TPump Job Script

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

Teradata Parallel Data Pump Reference 71

Page 72: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpWriting a Teradata TPump Job Script

• 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 ======================================================================== = = = Teradata Parallel Data Pump Utility Release 13.10.00.000 = = Platform MVS = = = ======================================================================== = = = Copyright 1997-2009 Teradata Corporation. ALL RIGHTS RESERVED. = = = ========================================================================**** 19:02:53 UTY2411 Processing start date: TUE OCT 06, 2009 ======================================================================== = = = Logon/Connection = = = ========================================================================0001 .LOGTABLE TPLOG0045;0002 .LOGON TDRT/IVYDB,;

72 Teradata Parallel Data Pump Reference

Page 73: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpWriting a Teradata TPump Job Script

**** 19:02:54 UTY8400 Teradata Database Release: 13.10g.00.53**** 19:02:54 UTY8400 Teradata Database Version: 13.10g.00.53**** 19:02:54 UTY8400 Default character set: EBCDIC**** 19:02:54 UTY8400 Current RDBMS has UDT support**** 19:02:54 UTY8400 Maximum supported buffer size: 1M**** 19:02:54 UTY8400 Upsert supported by RDBMS server**** 19:02:54 UTY8400 Array Support supported by RDBMS server**** 19:02:55 UTY6211 A successful connect was made to the RDBMS.**** 19:02:55 UTY6217 Logtable 'IVYDB.TPLOG0045' has been created. ======================================================================== = = = Processing Control Statements = = = ========================================================================0003 .NAME TP0045;0004 .BEGIN LOAD SESSIONS 20 PACK 20 ROBUST ON SERIALIZE ON CHECKPOINT 0 ERRORTABLE TPERR0045; ======================================================================== = = = Processing TPump Statements = = = ========================================================================0005 .LAYOUT LAY0045;0006 .FIELD F0 * integer key;0007 .FIELD F1 * integer;0008 .FIELD F2 * 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 LAYOUT LAY0045 APPLY DML0045;0013 .END LOAD;**** 19:02:55 UTY6609 Starting to log on sessions...**** 19:02:56 UTY6610 Logged on 20 sessions. ======================================================================== = = = TPump Import(s) Beginning = = = ========================================================================**** 19:02:56 UTY6630 Options in effect for following TPump Import(s): . Tenacity: 4 hour limit to successfully connect load sessions. . Max Sessions: 20 session(s). . Min Sessions: 16 session(s). . Checkpoint: 0 minute(s). . Errlimit: No limit in effect. . Restart Mode: ROBUST. . Serialization: ON. . Packing: 20 Statements per Request. . StartUp Rate: UNLIMITED Statements per Minute.**** 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.**** 19:02:58 UTY6608 Import 1 begins.

Teradata Parallel Data Pump Reference 73

Page 74: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpView Teradata TPump Output

**** 19:03:01 UTY6642 Import 1 statements: 100, requests: 20**** 19:03:01 UTY6643 Import 1 average statements per request: 5.00**** 19:03:01 UTY6644 Import 1 average statements per record: 1.00**** 19:03:01 UTY6645 Import 1 statements/session: avg. 5.00, min. 5.00, max. 5.00**** 19:03:01 UTY6646 Import 1 requests/session: average 1.00, minimum 1.00, maximum 1.00**** 19:03:01 UTY6648 Import 1 DBS wait time/session: avg. 0.05, min. 0.00, max. 1.00**** 19:03:01 UTY6649 Import 1 DBS wait time/request: avg. 0.05, min. 0.00, max. 1.00**** 19:03:01 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 : DML0045Type Database Table or Macro Name Activity 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; ======================================================================== = = = Logoff/Disconnect = = = ========================================================================**** 19:03:04 UTY6216 The restart log table has been dropped.**** 19:03:04 UTY6212 A successful disconnect was made from the RDBMS.**** 19:03:04 UTY2410 Total processor time used = '0.208906 Seconds' . Start : 19:02:53 - TUE OCT 06, 2009 . End : 19:03:04 - TUE OCT 06, 2009 . Highest return code encountered = '0'.

View Teradata TPump Output

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.

74 Teradata Parallel Data Pump Reference

Page 75: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpView Teradata TPump Output

• 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.

Teradata TPump 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.

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.

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.

Teradata Parallel Data Pump Reference 75

Page 76: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpView Teradata TPump Output

. IMPORT 1 Total thus far

. ========= ==============Candidate records considered:........ 8....... 8 <-----(1)-Apply conditions satisfied:.......... 8....... 8 <-----(2)-Errors loggable to error table:...... 1....... 1 <-----(3)-Candidate records rejected:.......... 1....... 1 <-----(4)-Number of RDBMS requests sent:....... 6....... 6 <-----(6)-

** Statistics for Apply Label : LABELBType Database Table or Macro Name Activity

I CME TDBTB734_TAL 7 <-(5)-

Restart Statistics

Teradata TPump stores statistics in the restart log table. After a restart, all statistics are properly restored.

Teradata TPump Statistical Output

The following is an example of Teradata TPump output. Lines that are marked on the right-hand side with (-----------(n) are explained above.

**** 01:33:23 UTY2407 Run time parameters in effect are: VERBOSE. ======================================================================== = = = Teradata Parallel Data Pump Utility Release 13.10.00.000 = = Platform SOLARIS/SPARC = = = ======================================================================== = = = Copyright 1997-2009 Teradata Corporation. ALL RIGHTS RESERVED. = = = ========================================================================**** 01:33:23 UTY2411 Processing start date: TUE OCT 06, 2009 ======================================================================== = = = Logon/Connection = = = ========================================================================0001 .LOGTABLE TPLOG0046;0002 .LOGON ESSSOL01/ARIDB,;**** 01:33:27 UTY8400 Teradata Database Release: 13.10g.00.53**** 01:33:27 UTY8400 Teradata Database Version: 13.10g.00.53**** 01:33:27 UTY8400 Default character set: ASCII**** 01:33:27 UTY8400 Current RDBMS has UDT support**** 01:33:27 UTY8400 Maximum supported buffer size: 1M**** 01:33:27 UTY8400 Upsert supported by RDBMS server**** 01:33:27 UTY8400 Data Encryption supported by RDBMS server**** 01:33:27 UTY8400 Array Support supported by RDBMS server**** 01:33:28 UTY6211 A successful connect was made to the RDBMS.**** 01:33:28 UTY6217 Logtable 'ARIDB.TPLOG0046' has been created. ======================================================================== = = = Processing Control Statements = = = ========================================================================0003 CREATE TABLE TAB1, FALLBACK, NO JOURNAL ( F0 integer, F1 integer,

76 Teradata Parallel Data Pump Reference

Page 77: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpView Teradata TPump Output

F2 integer, F3 char(38)) UNIQUE PRIMARY INDEX(F0);**** 01:33:28 UTY1016 'CREATE' request successful.0004 CREATE TABLE TAB2, FALLBACK, NO JOURNAL ( F0 integer, F1 integer, F2 integer, F3 char(38)) UNIQUE PRIMARY INDEX(F0);**** 01:33:29 UTY1016 'CREATE' request successful.0005 .BEGIN LOAD SESSIONS 10 ROBUST ON SERIALIZE ON CHECKPOINT 10 NOMONITOR ERRORTABLE ET_TEST1; ======================================================================== = = = Processing TPump Statements = = = ========================================================================0006 .LAYOUT LAY1A;0007 .FIELD F0 * integer key;0008 .FIELD F1 * integer;0009 .FIELD F2 * integer;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 DO INSERT FOR MISSING UPDATE ROWS 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;0023 .END LOAD;**** 01:33:29 UTY6609 Starting to log on sessions...**** 01:33:32 UTY6610 Logged on 10 sessions. ======================================================================== = = = TPump Import(s) Beginning = = =

Teradata Parallel Data Pump Reference 77

Page 78: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpView Teradata TPump Output

========================================================================**** 01:33:32 UTY6630 Options in effect for following TPump Import(s): . Tenacity: 4 hour limit to successfully connect load sessions. . Max Sessions: 10 session(s). . Min Sessions: 8 session(s). . Checkpoint: 10 minute(s). . Errlimit: No limit in effect. . Restart Mode: ROBUST. . Serialization: ON. . Packing: 20 Statements per Request. . StartUp Rate: UNLIMITED Statements per Minute.**** 01:33:34 UTY6608 Import 1 begins.**** 01:33:38 UTY6641 Since last chkpt., 100 recs. in, 200 stmts., 10 reqs**** 01:33:38 UTY6647 Since last chkpt., avg. DBS wait time: 0.40**** 01:33:38 UTY6612 Beginning final checkpoint...**** 01:33:38 UTY6641 Since last chkpt., 100 recs. in, 200 stmts., 10 reqs**** 01:33:38 UTY6647 Since last chkpt., avg. DBS wait time: 0.40**** 01:33:38 UTY6607 Checkpoint Completes with 200 rows sent.**** 01:33:38 UTY6642 Import 1 statements: 200, requests: 10**** 01:33:38 UTY6643 Import 1 average statements per request: 20.00**** 01:33:38 UTY6644 Import 1 average statements per record: 1.00**** 01:33:38 UTY6645 Import 1 statements/session: avg. 20.00, min. 20.00, max. 20.00**** 01:33:38 UTY6646 Import 1 requests/session: average 1.00, minimum 1.00, maximum 1.00**** 01:33:38 UTY6648 Import 1 DBS wait time/session: avg. 0.40, min. 0.00, max. 2.00**** 01:33:38 UTY6649 Import 1 DBS wait time/request: avg. 0.40, min. 0.00, max. 2.00**** 01:33:38 UTY1803 Import processing statistics . IMPORT 1 Total thus far . ========= ============== Candidate records considered:........ 100....... 100<-----(1)- Apply conditions satisfied:.......... 200....... 200<-----(2)- Records logable to error table:...... 0....... 0<-----(3)- Candidate records rejected:.......... 0....... 0<-----(4)- Number of RDBMS requests sent:....... 10....... 10<-----(6)-** Statistics for Apply Label : TAB1PART1Type Database Table or Macro Name Activity I ARIDB tab1 100<-(5)-** Statistics for Apply Label : TAB2PART1Type Database Table or Macro Name Activity I ARIDB tab2 100 **** 01:33:41 UTY6608 Import 2 begins.**** 01:33:54 UTY6641 Since last chkpt., 100 recs. in, 200 stmts., 10 reqs**** 01:33:54 UTY6647 Since last chkpt., avg. DBS wait time: 1.30**** 01:33:54 UTY6612 Beginning final checkpoint...**** 01:33:54 UTY6641 Since last chkpt., 100 recs. in, 200 stmts., 10 reqs**** 01:33:54 UTY6647 Since last chkpt., avg. DBS wait time: 1.30**** 01:33:54 UTY6607 Checkpoint Completes with 200 rows sent.**** 01:33:54 UTY6642 Import 2 statements: 200, requests: 10**** 01:33:54 UTY6643 Import 2 average statements per request: 20.00**** 01:33:54 UTY6644 Import 2 average statements per record: 1.00**** 01:33:54 UTY6645 Import 2 statements/session: avg. 20.00, min. 20.00, max. 20.00**** 01:33:54 UTY6646 Import 2 requests/session: average 1.00, minimum 1.00, maximum 1.00**** 01:33:54 UTY6648 Import 2 DBS wait time/session: avg. 1.30, min. 0.00, max. 12.00**** 01:33:54 UTY6649 Import 2 DBS wait time/request: avg. 1.30, min. 0.00, max. 12.00**** 01:33:54 UTY1803 Import processing statistics . IMPORT 2 Total thus far . ========= ============== Candidate records considered:........ 100....... 200 Apply conditions satisfied:.......... 200....... 400 Records logable to error table:...... 0....... 0

78 Teradata Parallel Data Pump Reference

Page 79: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpView Teradata TPump Output

Candidate records rejected:.......... 0....... 0 Number of RDBMS requests sent:....... 10....... 20** Statistics for Apply Label : TAB1UPSERTType Database Table or Macro Name Activity U ARIDB tab1 50 I ARIDB tab1 50** Statistics for Apply Label : TAB2UPSERTType Database Table or Macro Name Activity U ARIDB tab2 50 I ARIDB tab2 50**** 01:33:54 UTY0821 Error table ARIDB.ET_TEST1 is EMPTY, dropping table.0024 .LOGOFF; ======================================================================== = = = Logoff/Disconnect = = = ========================================================================**** 01:33:58 UTY6216 The restart log table has been dropped.**** 01:33:58 UTY6212 A successful disconnect was made from the RDBMS.**** 01:33:58 UTY2410 Total processor time used = '0.8 Seconds' . Start : 01:33:23 - TUE OCT 06, 2009 . End : 01:33:58 - TUE OCT 06, 2009 . Highest return code encountered = '0'.

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.

**** 17:09:34 UTY6630 Options in effect for following TPump Import(s):. Tenacity: 4 hour limit to successfully connect load sessions.. Max Sessions: 10 session(s).. Min Sessions: 8 session(s).. Checkpoint: 10 minute(s).. Errlimit: 1 rejected record(s).. Restart Mode: ROBUST.. Serialization: ON.. Packing: 20 Statements per Request.. StartUp Rate: UNLIMITED Statements per Minute.

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.

Teradata Parallel Data Pump Reference 79

Page 80: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpView Teradata TPump Output

**** 17:09:34 UTY6630 Options in effect for following TPump Import(s):. Tenacity: 4 hour limit to successfully connect load sessions.. Max Sessions: 4 session(s).. Min Sessions: 4 session(s).. Checkpoint: 5 minutes.. Errlimit: 10% of records rejected.. Restart Mode: SIMPLE.. Serialization: ON.. Packing: 20 Statements per Request.. 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.

**** 17:09:34 UTY6630 Options in effect for following TPump Import(s):. Tenacity: Sessions must successfully connect on first try.. Max Sessions: 1 session(s).. Min Sessions: 1 session(s).. Checkpoint: 5 minutes.. Errlimit: No limit in effect.. Restart Mode: ROBUST.. Serialization: OFF.. Packing: 40 Statements per Request.. StartUp Rate: UNLIMITED Statements per Minute.

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 UTY6212 A successful disconnect was made from the RDBMS.**** 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

. Highest return code encountered = '0'.

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.

80 Teradata Parallel Data Pump Reference

Page 81: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpMonitor Teradata TPump Jobs

Monitor Teradata TPump Jobs

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.

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.

Teradata Parallel Data Pump Reference 81

Page 82: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpMonitor Teradata TPump Jobs

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.

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.

Table 23: Monitor Interface Table (continued)

Name Type Notes

82 Teradata Parallel Data Pump Reference

Page 83: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpMonitor Teradata TPump Jobs

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

Teradata Parallel Data Pump Reference 83

Page 84: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpMonitor Teradata TPump Jobs

) AS(

LOCK ROW WRITE /* OR LOCKING Sysadmin.TPumpStatus for WRITE */SELECT

RecordsOut ,RecordsSkipped ,RecordsRejcted ,RecordsRead ,RecordsErrored

FROM SysAdmin.TPumpStatusTbl

WHEREUserName = :UserName ANDLogDB = :LogDB AND Import = :Import AND LogTable = :LogTable

; UPDATE SysAdmin.TPumpStatusTblSET

RequestChange = :RequestChange,StmtsUnLimited = :StmtsUnLimited,StmtsDesired = :StmtsDesired, PeriodsDesired = :PeriodsDesired

WHEREUserName = :UserName ANDLogDB = :LogDB 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

WHEREUserName = USER AND

84 Teradata Parallel Data Pump Reference

Page 85: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpEstimating Space Requirements

LogDB = :LogDB AND Import = :Import AND LogTable = :LogTable

; UPDATE SysAdmin.TPumpStatusTblSET

RequestChange = :RequestChange,StmtsUnLimited = :StmtsUnLimited,StmtsDesired = :StmtsDesired,PeriodsDesired = :PeriodsDesired

WHEREUserName = USER ANDLogDB = :LogDB AND LogTable = :LogTable AND Import = :Import ;

);

Estimating Space Requirements

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

Teradata Parallel Data Pump Reference 85

Page 86: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpEstimating Space Requirements

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 2ERRORTABLE 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

86 Teradata Parallel Data Pump Reference

Page 87: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpEstimating Space Requirements

IGNORE EXTRA ROWS;INSERT INTO TBL14TA VALUES (:ABYTEINT,:ASMALLINT,:AINTEGER,:ADECIMAL,

:ACHAR,:ABYTE,:AFLOAT,:ADATE);.DML LABEL LABELB IGNORE DUPLICATE ROWS IGNORE MISSING ROWS

IGNORE EXTRA ROWS;INSERT INTO TBL14TB VALUES (:ABYTEINT,:ASMALLINT,:AINTEGER,:ADECIMAL,

:ACHAR,:ABYTE,:AFLOAT,:ADATE);.IMPORT INFILE ./tlnt014.dat

LAYOUT LAY1A FROM 1 FOR 400APPLY LABELA WHERE ATEST = 1APPLY 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.

Teradata Parallel Data Pump Reference 87

Page 88: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 2: Using Teradata TPumpEstimating Space Requirements

88 Teradata Parallel Data Pump Reference

Page 89: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

CHAPTER 3

Teradata TPump Commands

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:

• 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.

Object Name Restrictions

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:

Teradata Parallel Data Pump Reference 89

Page 90: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsSyntax 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.

Teradata TPump Commands

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 Definition

ACCEPT Accepts the data type and value of one or more utility variables from an external source.

BEGIN LOAD Indicates the start of a Teradata TPump task and specifies the parameters for executing the task.

DATEFORM Defines the form of the DATE data type specifications for the Teradata TPump job.

DISPLAY Writes messages to the specified destination.

DML 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.

ELSE The ELSE command is followed by commands and statements that execute when the preceding IF command is false. See IF, ELSE, and ENDIF.

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.

END LOAD Indicates completion of Teradata TPump command entries and initiates the task. This is the last command of a Teradata TPump task.

FIELD 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.

FILLER Defines a field in the data source that is not sent to Teradata Database. This command is used with the LAYOUT command.

90 Teradata Parallel Data Pump Reference

Page 91: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsSyntax Notes

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.

IF 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.

IMPORT Identifies the data source, layout, and optional selection criteria to the client program.

LAYOUT 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.

LOGOFF Disconnects all active sessions and terminates execution of Teradata TPump on the client.

LOGON Establishes a Teradata SQL session on Teradata Database, and specifies the LOGON string to be used in connecting all sessions required by subsequent functions.

LOGTABLE 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.

NAME Sets the utility variable &SYSJOBNAME with a job name of up to 16 characters.

PARTITION Establishes session partitions to transfer SQL requests to Teradata Database.

ROUTE Identifies the destination of output produced by Teradata TPump.

RUN FILE Invokes the specified external source as the current source of commands and statements.

SET Assigns a data type and a value to a utility variable.

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

TABLE 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.

Table 24: Teradata TPump Commands (continued)

Command Definition

Teradata Parallel Data Pump Reference 91

Page 92: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsSyntax Notes

Table 25: Teradata TPump Teradata SQL Statements

Statement Definition

DATABASE Changes the default database qualification for all DML statements.

DELETE Removes specified rows from a table.

EXECUTE 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.

INSERT Adds new rows to a table by directly specifying the row data to be inserted.

UPDATE Statement and Atomic Upsert Changes field values in existing rows of a table.

92 Teradata Parallel Data Pump Reference

Page 93: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsACCEPT

ACCEPT

PurposeThe 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

where

Syntax Element Description

var 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.

env_var Environment variable that provides the value for the specified utility variables (var)

HE03B011

.ACCEPT

env_var

var

,

FILE fileid

ENVIRONMENT VARIABLE

ENV

charpos1

charpos1

THRU

THRU

THRUcharpos1 charpos2

charpos2

IGNORE

FROM

VAR

A

A

B

B

;

;

Teradata Parallel Data Pump Reference 93

Page 94: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsACCEPT

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;

fileid Data source of the external system.

The external system DD (or similar) statement specifies a file.

UNIX and Windowsinfilename (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/OSa 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).

charpos1 and charpos2 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.

Syntax Element Description

94 Teradata Parallel Data Pump Reference

Page 95: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsACCEPT

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.

Teradata Parallel Data Pump Reference 95

Page 96: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsBEGIN LOAD

BEGIN LOAD

PurposeThe 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

3021G017

NOTIFY OFF

LOWMEDIUM

nameEXIT

MSGHIGH

TEXT string' '

string' '

.BEGIN LOAD numberthreshold

ERRORTABLE

SESSIONS

dbname.

tname

ERRLIMIT

errpercent

errcount

CHECKPOINT frequency

TENACITY hours

SERIALIZE

statements

seconds

PACK

PACKMAXIMUM

LATENCY

RATE statement_rate

SLEEP minutes

NOMONITOR

ROBUST ON

OFF

A

A

MACRODB dbname

ULTRA

NOTIMERPROCESS

APPEND NODROP

NOATOMICUPSERT

DATAENCRYPTION

ARRAYSUPPORTONOFF

ON

OFF

ON

OFF

QUEUETABLE

RETRYTIMES nn

96 Teradata Parallel Data Pump Reference

Page 97: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsBEGIN LOAD

where

Syntax Element Description

SESSIONS Keyword for the number of Teradata TPump sessions.

number Number of sessions to be logged on for update purposes for Teradata TPump.

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.

threshold 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.

ERRORTABLE 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.

APPEND 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.

NODROP 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.

QUEUETABLE Selects the error table as a Queue Table.

Teradata Parallel Data Pump Reference 97

Page 98: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsBEGIN LOAD

dbname. 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.

tname 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.

Syntax Element Description

98 Teradata Parallel Data Pump Reference

Page 99: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsBEGIN LOAD

ERRLIMIT 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.

errcount 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.

CHECKPOINT Keyword indicating the number of minutes between the occurrences of checkpoints.

This is followed by a frequency value.

Syntax Element Description

Teradata Parallel Data Pump Reference 99

Page 100: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsBEGIN LOAD

frequency 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.

DATAENCRYPTION ON/OFF

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.

Syntax Element Description

100 Teradata Parallel Data Pump Reference

Page 101: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsBEGIN LOAD

ArraySupport ON/OFF

“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.

TENACITY 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.

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.

Syntax Element Description

Teradata Parallel Data Pump Reference 101

Page 102: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsBEGIN LOAD

LATENCY 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.

seconds 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.

NOTIMERPROCESS 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.

minutes 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.

SERIALIZE ON/OFF 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.

PACKMAXIMUM 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.

Syntax Element Description

102 Teradata Parallel Data Pump Reference

Page 103: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsBEGIN LOAD

PACK Keyword for the number of statements to pack into a multiple-statement request.

Maximum value is 2430.

Packing improves network/channel efficiency by reducing the number of sends and receives between the application and Teradata Database.

statements 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.

RATE Keyword for entering the rate at which statements are sent to Teradata Database.

RETRYTIMES nn 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.

Syntax Element Description

Teradata Parallel Data Pump Reference 103

Page 104: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsBEGIN LOAD

statement_rate 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 Keyword for the number of minutes to sleep.

NOATOMICUPSERT 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.

NOMONITOR Keyword to prevent Teradata TPump from checking for statement rate changes from, or update status information for, the Teradata TPump Monitor.

ROBUST ON/OFF 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 Keyword for database to contain any macros used by Teradata TPump.

dbname Name of database which is to contain any macros built/used by Teradata TPump.

This database overrides the default placement of macros into the database which contains the log restart table.

Syntax Element Description

104 Teradata Parallel Data Pump Reference

Page 105: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsBEGIN LOAD

Table 26 lists events that create notifications.

NOTIFY 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.

EXIT name 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.

TEXT 'string' 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 (').

MSG 'string' 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: Events that Create Notifications

Notification Level

Event Low Medium High Ultra Signifies

Checkpoint Begin No No Yes Yes Teradata TPump started a checkpoint.

Syntax Element Description

Teradata Parallel Data Pump Reference 105

Page 106: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsBEGIN LOAD

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

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.

Table 26: Events that Create Notifications (continued)

Notification Level

106 Teradata Parallel Data Pump Reference

Page 107: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsBEGIN 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.

Teradata Parallel Data Pump Reference 107

Page 108: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsDATABASE

DATABASE

PurposeTeradata TPump supports the Teradata SQL DATABASE statement, which changes the default database qualification for all unqualified DML and DDL statements.

Syntax

where

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.

Syntax Element Description

database New qualified default database for the error table

Changes the database from the one originally specified by the BEGIN LOAD command.

3021A020

DATABASE ;database

108 Teradata Parallel Data Pump Reference

Page 109: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsDATEFORM

DATEFORM

PurposeThe DATEFORM command lets you define the form of the DATE data type specifications for the Teradata TPump job.

Syntax

where

Usage Notes

Table 27 describes the things to consider when using the DATEFORM command.

Syntax Element Description

INTEGERDATE 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.

ANSIDATE Keyword that specifies ANSI fixed-length CHAR(10) DATE data types for the Teradata TPump job

.DATEFORM INTEGERDATE

ANSIDATE

;

3021A006

Table 27: DATEFORM Command Usage Notes

Topic Usage Notes

Command Frequency and Placement

• Only one DATEFORM command can be used.

• The DATEFORM command must be entered before LOGON command.

Data Type Conversions 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.

Teradata Parallel Data Pump Reference 109

Page 110: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsDATEFORM

Release Applicability The ANSIDATE specification is valid for Teradata TPump jobs on Teradata Database for UNIX.

Table 27: DATEFORM Command Usage Notes (continued)

Topic Usage Notes

110 Teradata Parallel Data Pump Reference

Page 111: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsDELETE

DELETE

PurposeTeradata TPump supports the DELETE Teradata SQL statement, which removes rows from a table.

Syntax

where

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

Syntax Element Description

tname Table from which rows are to be deleted

tname is qualified either explicitly by database name, or by the current default database.

WHERE condition

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.

DELETE ;

HE05B032

tname WHERE conditionalFROM

Teradata Parallel Data Pump Reference 111

Page 112: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsDELETE

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;

112 Teradata Parallel Data Pump Reference

Page 113: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsDISPLAY

DISPLAY

PurposeThe DISPLAY command can be used to write messages to the specified destination.

Syntax

where

Syntax Element Description

'text' Text to be written to the specified output destination

fileid Data source of the external system.

The external system DD (or similar) statement specifies a file.

UNIX and Windowsinfilename (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/OSa 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

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).

3021A021

DISPLAY

TO

;FILE fileid'text'

Teradata Parallel Data Pump Reference 113

Page 114: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsDISPLAY

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

114 Teradata Parallel Data Pump Reference

Page 115: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsDML

DML

PurposeThe 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

where

Syntax Element Description

LABEL Keyword indicating that the following parameter is a label for the DML statements that follow

.DML label

3021E007

A

MARKA ;

IGNORE

DO INSERT FOR

DUPLICATE

INSERT

MISSING UPDATE

LABEL

ROWS

UPDATE

MISSING

UPDATE

DELETE

EXTRA

UPDATE

DELETE

SERIALIZEON ( )serialize_on_field

,

USE ( use_field

,

)

PARTITION partition_name

ARRAYSUPPORT

ON

OFF

Teradata Parallel Data Pump Reference 115

Page 116: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsDML

label 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.

MARK 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).

Syntax Element Description

116 Teradata Parallel Data Pump Reference

Page 117: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsDML

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 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.

partition_name Parameter identifying the partition name

The partition name must obey the same rules for its construction as Teradata SQL column names.

SERIALIZEON Keyword used to turn serialization on for the fields specified

SERIALIZEON keyword may be used before, after, or between any IGNORE or MARK statements.

serialize_on_field 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.

USE 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.

use_field 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.

Syntax Element Description

Teradata Parallel Data Pump Reference 117

Page 118: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsDML

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.

ArraySupport ON/OFF

“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.

Syntax Element Description

118 Teradata Parallel Data Pump Reference

Page 119: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsDML

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 <n>_<Apply label>_<x>

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.

Sample Scripts

The following is an example using the SERIALIZEON keyword:

.LOGTABLE TPLOG01;

.LOGON slugger/dbc,dbc;

.BEGIN LOADERRLIMIT 100 50CHECKPOINT 15SESSIONS 20TENACITY 2ERRORTABLE TPERR01PACK 30ROBUST ONNOMONITOR;

.LAYOUT LAY01;

Teradata Parallel Data Pump Reference 119

Page 120: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsDML

.FIELD cc1 * CHAR(8);

.FIELD cc2 * CHAR(4);

.FIELD cc3 * CHAR(6);

.FIELD cc4 * CHAR(62);.DML LABEL LABEL01DO INSERT FOR MISSING UPDATE ROWSSERIALIZEON (CC1);UPDATE TPTBL01SET C4 = :CC4WHERE C1 = :CC1;INSERT TPTBL01 (C1, C2, C4)VALUES (:CC1,:CC2, CC4);

UPDATE TPTBL02 SET C4 = :CC4 WHERE C1 = :CC1AND C2 = :CC2;

INSERT TPTBL02 (C1, C2, C3, C4)VALUES (:CC1,:CC2,:CC3, :CC4);

.IMPORT INFILE .\TPDAT.txt FORMAT TEXTLAYOUT LAY01APPLY LABEL01APPLY LABEL02;

.END LOAD;

.LOGOFF;

The following is an example using the USE keyword:

.LOGTABLE TPLOG01;

.LOGON slugger/cfl,cfl;

DROP TABLE TPERR01;DROP TABLE TPTBL01;DROP TABLE TPTBL02;DROP TABLE TPTBL03;

CREATE TABLE TPTBL01(C1 INTEGER,C2 VARCHAR(30),C3 VARCHAR(30),C4 VARCHAR(30),C5 VARCHAR(30),C6 VARCHAR(30))UNIQUE PRIMARY INDEX (C1);

CREATE TABLE TPTBL02(C1 INTEGER,C2 VARCHAR(30),C3 VARCHAR(30),C4 VARCHAR(30),C5 VARCHAR(30))UNIQUE PRIMARY INDEX (C1);

CREATE TABLE TPTBL03(C1 INTEGER,C2 VARCHAR(30),C3 VARCHAR(30),C4 VARCHAR(30),C5 VARCHAR(30),C6 VARCHAR(30),

120 Teradata Parallel Data Pump Reference

Page 121: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsDML

C7 VARCHAR(30),C8 VARCHAR(30),C10 VARCHAR(30),C11 VARCHAR(30))UNIQUE PRIMARY INDEX (C1);

.BEGIN LOADCHECKPOINT 15SESSIONS 5ERRORTABLE TPERR01NOMONITOR;

.LAYOUT LAY01;

.FIELD FLD1 * VARCHAR(10);

.FIELD FLD2 * VARCHAR(10);

.FIELD FLD3 * VARCHAR(10);

.FIELD FLD4 * VARCHAR(15);

.FIELD FLD5 * VARCHAR(20);

.FIELD FLD6 * VARCHAR(25);

.FIELD FLD7 * VARCHAR(30);

.FIELD FLD8 * VARCHAR(30);

.FIELD FLD9 * VARCHAR(1);

.FIELD FLD10 * VARCHAR(30);

.FIELD FLD11 * VARCHAR(30);

.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 LAY01APPLY LABEL01 WHERE FLD9 = 'A'APPLY LABEL02 WHERE FLD9 = 'B'APPLY LABEL03;

.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:

.LOGTABLE TPLOG01;

.LOGON cs4400s3/cfl,cfl;DROP TABLE TPTBL01;

Teradata Parallel Data Pump Reference 121

Page 122: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsDML

DROP TABLE TPTBL02;DROP TABLE TPERR01;

CREATE TABLE TPTBL01, FALLBACK(C1 CHAR(12) not null,C2 CHAR(8) not null)PRIMARY INDEX (C1);

CREATE TABLE TPTBL02, FALLBACK(C1 CHAR(12),C2 CHAR(8),C3 CHAR(6))UNIQUE PRIMARY INDEX (C1);

.BEGIN LOADERRLIMIT 100 50CHECKPOINT 15TENACITY 2ERRORTABLE TPERR01ROBUST offserialize on;

.LAYOUT LAY02;

.FIELD cc1 * CHAR(12) key;

.FIELD cc2 * CHAR(8);

.FIELD cc3 * CHAR(6);

.filler space1 * char(1);

.partition part1 pack 10 sessions 10;

.partition part2 sessions 5 1 packmaximum;

.DML LABEL LABEL01 partition part1DO INSERT FOR MISSING ROWSignore extra update rows

use(cc1, cc2);

UPDATE TPTBL01SET C2 = :CC2WHERE C1 = :CC1;INSERT TPTBL01 (C1, C2)VALUES (:CC1,:CC2);

.DML LABEL LABEL02 partition part2serializeon( cc1 )ignore extra update rowsDO INSERT FOR MISSING UPDATE ROWS;

UPDATE TPTBL02 SET C2 = :CC2 WHERE C1 = :CC1;INSERT TPTBL02 (C1, C2, C3)

VALUES (:CC1,:CC2,:CC3);

.IMPORT INFILE c:\NCR\Test\TpumpData001.txt FORMAT TEXTLAYOUT LAY02APPLY LABEL01APPLY LABEL02 where CC2 = '00000001';

.END LOAD;

.LOGOFF;

122 Teradata Parallel Data Pump Reference

Page 123: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsDML

The Basic Upsert Feature

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 explicit value if there are upserts in the Teradata TPump job.

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.

Example 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.

Teradata Parallel Data Pump Reference 123

Page 124: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsDML

.BEGINLOAD SESSION number;

.LAYOUT Layoutname;

.FIELD EmpNum 1 INTEGER;

.FIELD Fone * (CHAR (10));

.DML LABEL DMLlabelnameDO INSERT FOR MISSING UPDATE ROWS;UPDATE Employee SET PhoneNo = :Fone WHERE EmpNo = :EmpNum;INSERT Employee (EmpNo, PhoneNo) VALUES (:EmpNum, :Fone);.IMPORT INFILE Infilename LAYOUT Layoutname APPLY DMLlabelname;.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 DO INSERT FOR MISSING UPDATE 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.

124 Teradata Parallel Data Pump Reference

Page 125: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsDML

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.

Teradata Parallel Data Pump Reference 125

Page 126: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsDML

• 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:

DO INSERT FOR MISSING UPDATE ROWS;UPDATE <update-operands>;INSERT <insert-operands>;

126 Teradata Parallel Data Pump Reference

Page 127: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsDML

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;UPDATE Sales SET ItemCount = ItemCount + 1 WHERE (ItemNbr = 10 AND 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.

.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 Sales (10, '05/30/2005', 1);

Teradata Parallel Data Pump Reference 127

Page 128: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsDML

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.

.Dml label upsertdml do insert for missing update rows;UPDATE Sales SET ItemCount = ItemCount + 1 WHERE (ItemNbr = 20 AND SaleDate = '05/30/2005') INSERT INTO Sales (20, '05/30/2005', 1);

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.

128 Teradata Parallel Data Pump Reference

Page 129: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsEND LOAD

END LOAD

PurposeThe 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

;

Teradata Parallel Data Pump Reference 129

Page 130: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsEXECUTE

EXECUTE

PurposeTeradata TPump supports the Teradata SQL EXECUTE statement, which specifies a user-created (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

where

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:

Syntax Element Description

database Name of the database in Teradata Database where the macro to be executed resides

name Name of the macro resident in Teradata Database to be executed

DELETE/DEL Keyword indicating a DELETE statement is being executed by the macro

INSERT/INS Keyword indicating an INSERT statement is being executed by the macro

UPDATE/UPD Keyword indicating an UPDATE statement is being executed by the macro

UPSERT/UPS Keyword indicating an Atomic upsert is being executed by the macro

EXECUTE ;name

3021A001

EXEC database.UPDATE/UPD

INSERT/INS

DELETE/DEL

UPSERT/UPS

130 Teradata Parallel Data Pump Reference

Page 131: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsEXECUTE

• 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 <delete-operands> ;INSERT <insert-operands> ;UPDATE <update-operands> ;

.DML LABEL LABELA ;DELETE <delete-operands> ;EXECUTE <insert-macro-name> INSERT ;UPDATE <update-operands> ;

The correct syntax for a Teradata TPump predefined macro is one of the following:

• CREATE MACRO <name> (<parameter list>) as (UPDATE....; ) ;

• CREATE MACRO <name> (<parameter list>) as (INSERT.....; ) ;

• CREATE MACRO <name> (<parameter list>) as (DELETE.....; ) ;

• CREATE MACRO <name> (<parameter list>) 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.

Teradata Parallel Data Pump Reference 131

Page 132: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsEXECUTE

For example:

.DML LABEL <dml-label-name> DO INSERT FOR MISSING UPDATE ROWS ... ;EXECUTE <update-macro-name> UPDATE ;INSERT <insert-operands> ;

.DML LABEL <dml-label-name> DO INSERT FOR MISSING UPDATE ROWS ... ;UPDATE <update-operands> ;

EXECUTE <insert-macro-name> INSERT ;

.DML LABEL <dml-label-name> DO INSERT FOR MISSING UPDATE ROWS ... ;EXECUTE <update-macro-name> UPDATE ;EXECUTE <insert-macro-name> INSERT ;

To allow for the use of predefined macros that take advantage of Atomic upsert, Teradata TPump command syntax supports an UPSERT macro:

.DML LABEL <dml-label>;EXECUTE <upsert-macro-name> 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.

132 Teradata Parallel Data Pump Reference

Page 133: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsFIELD

FIELD

PurposeThe 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

where

Syntax Element Description

fieldname 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 fieldname A

A

startpos datadescnullexprNULLIF

DROP

TRAILING

LEADING BLANKS

NULLS

TRAILING

AND LEADING

NULLS

BLANKS

B ;

KEY

B

fieldexpr

3021A019

Teradata Parallel Data Pump Reference 133

Page 134: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsFIELD

datadesc 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.

nullexpr 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.

nullexprContinued

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.

Syntax Element Description

134 Teradata Parallel Data Pump Reference

Page 135: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsFIELD

fieldexpr 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.

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 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 placement of these characters.

The mappings between Teradata EBCDIC and Unicode can be referred to in Appendix E of International Character Set Support.

DROP 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.

KEY 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.

Syntax Element Description

Teradata Parallel Data Pump Reference 135

Page 136: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsFIELD

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 <= 32000.

Description: 2-byte integer followed by m/2 double-byte characters.

LONG VARGRAPHIC

136 Teradata Parallel Data Pump Reference

Page 137: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsFIELD

Length: m + 2 bytes where m/2 <= 32000.

Description: 2 byte integer followed by m/2 double-byte characters.

Note: For both VARGRAPHIC and LONG VARGRAPHIC, m, a value occupying the first 2 bytes of the input data, is the length of the input in bytes, not characters. Each multibyte character set character is 2 bytes.

Note: LONG VARGRAPHIC also implies VARGRAPHIC (32000). Range is 0 to 32000 in a 64,000-byte field.

Decimal Data Type Specifications

DECIMAL(x) and DECIMAL(x,y)

Length: 1, 2, 4, 8 or 16 bytes for network; packed decimal for mainframe

Description: 128-bit double precision, floating point

Period Data Type Specifications

A period is an anchored duration. It represents a set of contiguous time granules within that duration. A period is implemented using a Period data type. Each period consists of two elements:

• BEGIN (the beginning element)

• END (the ending element)

The element type is one of the following DateTime data types.

• PERIOD(DATE)

• PERIOD(TIME[(n)])

• PERIOD(TIME[(n)] WITH TIME ZONE)

• PERIOD(TIMESTAMP[(n)])

• PERIOD(TIMESTAMP[(n)] WITH TIME ZONE)

For more information on the PERIOD data type, see SQL Data Types and Literals.

NULLIF Performance

Using a large number of NULLIF clauses can cause a significant increase in the CPU usage on the system where Teradata TPump is running. This rise in CPU usage may increase the time the job takes to run.

An increase in CPU usage is most noticeable when the following do not exist:

• FILLER commands in the LAYOUT

• Input position gaps or overlaps

• Concatenated fields

• DROP clauses

To avoid an increase in CPU usage on the system running Teradata TPump, transfer the processing of NULLIF expressions to Teradata Database.

Teradata Parallel Data Pump Reference 137

Page 138: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsFIELD

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;

...

.DML LABEL ins;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;

...

.DML LABEL ins; INSERT INTO tbl2 VALUES(...,:fs,:fc,:fi,...);

Use this instead:

...

.FIELD fs * CHAR(1) ;

.FIELD fc * CHAR(5);

.FIELD fi * INTEGER;

...

.DML LABEL ins; 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.

138 Teradata Parallel Data Pump Reference

Page 139: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsFIELD

Table 28: ANSI/SQL DateTime Specifications

Data Type Variable Definition Conversion Example

TIME

TIME (n)

n = number of digits after decimal point

Valid values: 0–6

Default = 6

CHAR(8 + n + (1 if n > 0, otherwise 0))

Format (n = 0): hh:mm:ssExample: 11:37:58

Format: (n = 4): hh:mm:ss.ssssExample: 11:37:58.1234

TIMESTAMP

TIMESTAMP (n)

n = number of digits after decimal point

Valid values: 0–6

Default = 6

CHAR(19 + n + (1 if n > 0, otherwise 0))

Format (n = 0): yyyy-mm-dd hh:mm:ssExample: 1998-09-04 11:37:58

Format (n = 4):yyyy-mm-dd hh:mm:ss.ssssExample:1998-09-04 11:37:58.1234

TIME WITH TIME ZONE

TIME (n) WITH TIME ZONE

n = number of digits after decimal point

Valid values: 0–6

Default = 6

CHAR(14 + n + (1 if n > 0, otherwise 0))

Format (n = 0): hh:mm:ss{±}hh:mmExample: 11:37:58-08:00

Format (n = 4): hh:mm:ss.ssss {±} hh:mmExample: 11:37:58.1234-08:00

TIMESTAMP WITH TIME ZONE

TIMESTAMP (n) WITH TIME ZONE

n = number of digits after decimal point

Valid values: 0-6

Default = 6

CHAR(25 + n + (1 if n > 0, otherwise 0))

Format (n = 0):yyyy-mm-dd hh:mm:ss{±}hh:mmExample:1998-09-24 11:37:58+07:00

Format (n = 4):yyyy-mm-dd hh:mm:ss.ssss{±} hh:mmExample:1998-09-24 11:37:58.1234+07:00

INTERVAL YEAR

INTERVAL YEAR (n)

n = number of digits

Valid values: 1-4

Default = 2

CHAR(n)

Format (n = 2): yyExample: 98

Format: (n = 4): yyyyExample: 1998

INTERVAL YEAR TO MONTH

INTERVAL YEAR (n) TO MONTH

n = number of digits

Valid values: 1-4

Default = 2

CHAR(n + 3)

Format (n = 2): yy-mmExample: 98-12

Format: (n = 4): yyyy-mmExample: 1998-12

Teradata Parallel Data Pump Reference 139

Page 140: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsFIELD

INTERVAL MONTH

INTERVAL MONTH (n)

n = number of digits

Valid values: 1-4

Default = 2

CHAR(n)

Format (n = 2): mmExample: 12

Format: (n = 4): mmmmExample: 0012

INTERVAL DAY

INTERVAL DAY (n)

n = number of digits

Valid values: 1-4

Default = 2

CHAR(n)

Format (n = 2): ddExample: 31

Format: (n = 4): ddddExample: 0031

INTERVAL DAY TO HOUR

INTERVAL DAY (n) TO HOUR

n = number of digits

Valid values: 1-4

Default = 2

CHAR(n + 3)

Format (n = 2): dd hhExample: 31 12

Format: (n = 4): dddd hhExample: 0031 12

INTERVAL DAY TO MINUTE

INTERVAL DAY (n) TO MINUTE

n = number of digits

Valid values: 1-4

Default = 2

CHAR(n + 6)

Format (n = 2): dd hh:mmExample: 31 12:59

Format: (n = 4): dddd hh:mmExample: 0031 12:59

INTERVAL DAY TO SECOND

INTERVAL DAY (n) TO SECOND

INTERVAL DAY TO SECOND (m)

INTERVAL DAY (n) TO SECOND (m)

n = number of digits

Valid values: 1-4

Default = 2

m = number of digits after decimal point

Valid values: 0-6

Default = 6

CHAR(n + 9 + m + (1 if m > 0, otherwise 0))

Format (n = 2, m = 0): hh:mm:ssExample: 12:59:59

Format: (n = 4, m = 4): hhhh:mm:ss.ssssExample: 0012:59:59.1234

INTERVAL HOUR

INTERVAL HOUR (n)

n = number of digits

Valid values: 1-4

Default = 2

CHAR(n)

Format: (n = 2): hhExample: 12

Format: (n = 4): hhhhExample: 0012

INTERVAL HOUR TO MINUTE

INTERVAL HOUR (n) TO MINUTE

n = number of digits

Valid values: 1-4

Default = 2

CHAR(n + 3)

Format: (n = 2): hh:mmExample: 12:59

Format: (n = 4): hhhh:mmExample: 0012:59

Table 28: ANSI/SQL DateTime Specifications (continued)

Data Type Variable Definition Conversion Example

140 Teradata Parallel Data Pump Reference

Page 141: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsFIELD

INTERVAL HOUR TO SECOND

INTERVAL HOUR (n TO SECOND

INTERVAL HOUR TO SECOND (m)

INTERVAL HOUR (n) TO SECOND (m)

n = number of digits

Valid values: 1-4

Default = 2

m = number of digits after the decimal point

Valid values: 0-6

Default = 6

CHAR(n + 6 + m + (1 if m > 0, otherwise 0))

Format: (n = 2, m = 0): hh:mm:ssExample: 12:59:59

Format: (n = 4, m = 4): hhhh:mm:ss.ssssExample: 0012:59:59.1234

INTERVAL MINUTE

INTERVAL MINUTE (n)

n = number of digits

Valid values: 1-4

Default = 2

CHAR(n)

Format (n = 2): mmExample: 59

Format: (n = 4): mmmmExample: 0059

INTERVAL MINUTE TO SECOND

INTERVAL MINUTE (n) TO SECOND

INTERVAL MINUTE TO SECOND (m)

INTERVAL MINUTE (n) TO SECOND (m)

n = number of digits

Valid values: 1-4

Default = 2

m = number of digits after decimal point

Valid values: 0-6

Default = 6

CHAR(n + 3 + m + (1 if m > 0, otherwise 0))

Format (n = 2, m = 0): mm:ssExample: 59:59

Format: (n = 4, m = 4): mmmm:ss.ssssExample: 0059:59.1234

INTERVAL SECOND

INTERVAL SECOND (n)

INTERVAL SECOND (n,m)

n = number of digits

Valid values: 1-4

Default = 2

m = number of digits after decimal point

Valid values: 0-6

Default = 6

CHAR(n + m + (1 if m > 0, otherwise 0))

Format (n = 2, m = 0): ssExample: 59

Format: (n = 4, m = 4): ssss.ssssExample: 0059.1234

Table 28: ANSI/SQL DateTime Specifications (continued)

Data Type Variable Definition Conversion Example

Teradata Parallel Data Pump Reference 141

Page 142: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsFILLER

FILLER

PurposeThe 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

where

Syntax Element Description

fieldname 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.

startpos 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.

datadesc Type and length of data in the field

.FILLER

fieldname

3021A023

;startpos datadesc

142 Teradata Parallel Data Pump Reference

Page 143: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsFILLER

Usage Notes

One or more FILLER commands may be intermixed with the FIELD command or the TABLE command. These commands must follow a LAYOUT command.

Example

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);

Teradata Parallel Data Pump Reference 143

Page 144: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsIF, ELSE, and ENDIF

IF, ELSE, and ENDIF

PurposeTeradata TPump provides a structure of IF, ELSE, and ENDIF commands for the conditional control of execution processes. Conditional execution works as follows:

Syntax

where

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

Syntax Element Description

conditional expression

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 execute if TRUE

Statements to be executed whenever the conditional expression following the IF command evaluates as TRUE

statements to execute if FALSE

Statements following the optional ELSE command which execute only when the conditional expression following the IF command evaluates as FALSE

statements to resume with

Statements following the ENDIF command to terminate the conditional statement execution process and resume the normal command sequence

.IF

THEN

;conditional expression

3021A024

.ELSE

statements to resume with

;

statements to execute if TRUE

statements to execute if FALSE

.ENDIF ;

144 Teradata Parallel Data Pump Reference

Page 145: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsIF, ELSE, and ENDIF

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, 1997UTY2402 Previous statement modified to: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;UTY2402 Previous statement modified to:0012 .LOGOFF 08;0013 .RUN FILE RUN01;0014 .ELSE0015 .IF &CREATERC <> 0 THEN0016 .LOGOFF &CREATRC;0017 .ENDIF

Teradata Parallel Data Pump Reference 145

Page 146: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsIMPORT

IMPORT

PurposeThe 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:

3021A004

C

CFROM m

FREE

HOLD

USING (parms)

FOR n

THRU k

LAYOUT layoutname

F ;

APPLY label

D

WHERE condition

modulenameINMOD

.IMPORT A

'init-string'

AXSMOD

INFILE ddname

name

B

A

B

D EFORMAT VARTEXT

DISPLAY ERRORS

NOSTOP

3

'c'

E F

146 Teradata Parallel Data Pump Reference

Page 147: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsIMPORT

For Network-Attached Client Systems:

where

Syntax Element 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.

3021A025

C

FROM m FOR n

THRU k

LAYOUT layoutnameD ;

APPLY label

D

WHERE condition

FORMAT

BINARY

TEXT

FASTLOAD

UNFORMAT

C

USING (parms)

modulenameINMOD

.IMPORT A

'init-string'

AXSMOD

INFILE filename

name

B

A

B

'c '

3

DISPLAY ERRORS

NOSTOP

VARTEXT

Teradata Parallel Data Pump Reference 147

Page 148: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsIMPORT

AXSMOD name 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

Syntax Element Description

148 Teradata Parallel Data Pump Reference

Page 149: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsIMPORT

INFILE filename Fully qualified UNIX or Windows path name for an input file on network-attached 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.

HOLD 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.

FREE 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.

INMOD modulename

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.

Syntax Element Description

Teradata Parallel Data Pump Reference 149

Page 150: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsIMPORT

USING (parms) 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 channel-attached 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).

FROM m 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.

FOR n 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.

THRU k 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.

Syntax Element Description

150 Teradata Parallel Data Pump Reference

Page 151: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsIMPORT

FORMAT 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-of-record 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.

Syntax Element Description

Teradata Parallel Data Pump Reference 151

Page 152: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsIMPORT

'c' 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.

For example, when the client character set is UTF-16 and the script character 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. Different versions of EBCDIC do not always agree as to the placement of these characters.

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.

DISPLAY ERRORS Optional keyword specification that writes input data records that produce errors to the standard error file

NOSTOP Optional keyword specification that inhibits the Teradata TPump termination in response to an error condition associated with a variable-length text record

LAYOUT layoutname

Layout of the input record, as specified by a previous command

APPLY label Error treatment options specified by a previous DML LABEL command for subsequent INSERT, UPDATE, or DELETE statements

Syntax Element Description

152 Teradata Parallel Data Pump Reference

Page 153: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsIMPORT

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.

WHERE condition 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.

For example, when the client character set is UTF-16 and the script character 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 examine the definition in International Character Set Support to determine the code points of the special characters 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.

Syntax Element Description

Teradata Parallel Data Pump Reference 153

Page 154: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsIMPORT

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 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 field-by-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

154 Teradata Parallel Data Pump Reference

Page 155: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsIMPORT

• 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 <n>_<Apply label>_<x>

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.

APPLY Example

.BEGIN LOAD SESSIONS 34;.LAYOUT EQTTB535;.FIELD Pool_Upd_Code * CHAR(01);.FIELD Eqmt_Init * CHAR(04);.... .DML LABEL UPSERTAC

DO INSERT FOR MISSING UPDATE ROWS;UPDATE EQTDBT50.EQTTB535_TAL SETTCS_POOL_IDFR_NUM =:TCS_POOL_IDFR_NUM.....

WHERE.....;

INSERT INTO EQTDBT50.EQTTB535_TALVALUES(POOL_EXPN_DATE =:POOL_EXPN_DATE (DATE, FORMAT 'YYYYMMDD').....

);.DML LABEL UPSERTDL;UPDATE EQTDBT50.EQTTB535_TAL SET.....

WHERE

Teradata Parallel Data Pump Reference 155

Page 156: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsIMPORT

..... ;

.IMPORT INFILE INFILELAYOUT EQTTB535APPLY 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;

156 Teradata Parallel Data Pump Reference

Page 157: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsINSERT

INSERT

PurposeTeradata TPump supports the Teradata SQL INSERT statement, which adds new rows to a table by directly specifying the row data to be inserted.

Syntax

where

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

Syntax Element Description

tname 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.

cname 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

fieldname 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.

expression Alternative to the fieldname clause, an expression that includes one or more actual fieldnames as terms may instead be used

INSERT ;tname

3021A026

VALUES

INS INTO ,

( cname )

,( :fieldname )

.*

expression

Teradata Parallel Data Pump Reference 157

Page 158: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsINSERT

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.

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.

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.

Temporal Semantics

DML validtime qualifier and NONTEMPORAL semantics are supported. For more information, see SQL Data Manipulation Language and SQL Data Manipulation Language Advanced Topics.

Example 1

.BEGIN LOAD SESSION number;

.LAYOUT Layoutname;

.TABLE Targetablename;

.DML LABEL DMLlabelname; INSERT INTO Targetablename.*;.IMPORT INFILE Infilename LAYOUT Layoutname APPLY DMLlabelname;.END LOAD;

Example 2

.LAYOUT lname;

.FIELD first 1 somedatatype;

.FIELD f2nd * anydatatype;

158 Teradata Parallel Data Pump Reference

Page 159: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsINSERT

.

.

.

.FIELD flast * datatype;

.DML LABEL label; INSERT INTO targetable VALUES (:first, :f2nd, ... :flast);

Example 3

.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);

Example 4

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 ;

.LAYOUT Layoutname;

.FIELD EmpNum 1 INTEGER;

.FIELD Name * (VARCHAR (30));

.FIELD Sal * (DECIMAL (7,2));

.DML LABEL DMLlabelname; INSERT Employee (EmpNo, Name, Salary) VALUES (:EmpNum, :Name, :Sal); .IMPORT INFILE Infilename LAYOUT Layoutname APPLY DMLlabelname;.END LOAD;

Teradata Parallel Data Pump Reference 159

Page 160: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsLAYOUT

LAYOUT

PurposeThe 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

Syntax Element Description

layoutname 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 ;

3021A027

CONTINUEIF condition

layoutname

INDICATORS

160 Teradata Parallel Data Pump Reference

Page 161: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsLAYOUT

CONTINUEIF condition

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.

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 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 examine the definition in International Character Set Support to determine the code points of the special characters 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.

Syntax Element Description

Teradata Parallel Data Pump Reference 161

Page 162: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsLAYOUT

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.

INDICATORS 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.

Syntax Element Description

162 Teradata Parallel Data Pump Reference

Page 163: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsLOGDATA

LOGDATA

PurposeSupplies 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

where

Usage Notes

For more information about logon security, see Security Administration.

Examples

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;

Syntax Element Description

logdata_string 'logdata_string' 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.

2409A054

.LOGDATA ;logdata_string

'logdata_string '

Teradata Parallel Data Pump Reference 163

Page 164: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsLOGMECH

LOGMECH

PurposeIdentifies 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

where

Usage Notes

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.

Examples

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;

Syntax Element Description

logmech_name 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.

2409A053

.LOGMECH ;logmech_name

164 Teradata Parallel Data Pump Reference

Page 165: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsLOGOFF

LOGOFF

PurposeThe 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

where

Usage Notes

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.

Example

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;

Syntax Element Description

retcode Completion code returned to the client operating system

If retcode is not specified, Teradata TPump returns the value generated by the error condition.

3021A028

.LOGOFF

retcode

;

Teradata Parallel Data Pump Reference 165

Page 166: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsLOGOFF

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.

166 Teradata Parallel Data Pump Reference

Page 167: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsLOGON

LOGON

PurposeThe 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.

Syntax

Standard LOGON

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

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

Syntax Element Description

tdpid 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

3021A005

.LOGON

tdpid /

;username

, password, ' acctid '

2409A010

.LOGON

tdpid /

;

username , password,'acctid '

Teradata Parallel Data Pump Reference 167

Page 168: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsLOGON

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:

username User identifier of up to a 30-character maximum

password Optional password associated with the username, up to a 30-character maximum

Teradata Database must be configured to recognize the password specified.

'acctid' 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.

Syntax Element Description

168 Teradata Parallel Data Pump Reference

Page 169: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsLOGON

.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**** 15:12:47 UTY8400 Default character set: ASCII**** 15:12:47 UTY8400 Current RDBMS has UDT support**** 15:12:47 UTY8400 Maximum supported buffer size: 1M**** 15:12:47 UTY8400 Upsert supported by RDBMS server**** 15:12:47 UTY8400 Data Encryption supported by RDBMS server**** 15:12:47 UTY8400 Array Support supported by RDBMS server**** 15:12:48 UTY6211 A successful connect was made to the RDBMS.

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.

Teradata Parallel Data Pump Reference 169

Page 170: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsLOGON

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.

170 Teradata Parallel Data Pump Reference

Page 171: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsLOGTABLE

LOGTABLE

PurposeThe 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.

Caution: 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

where

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.

Syntax Element Description

dbname (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.

tname Identifier for the restart log table

3021A029

.LOGTABLE

dbname.

;tname

Teradata Parallel Data Pump Reference 171

Page 172: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsLOGTABLE

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.

172 Teradata Parallel Data Pump Reference

Page 173: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsNAME

NAME

PurposeThe NAME command assigns a unique job name identifier to the environmental variable &SYSJOBNAME.

Syntax

where

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 = macroMM = monthDD = dayYYYY = yearhh = hourmm = minutess = second

Syntax Element Description

jobname 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.

.NAME ;jobname

3021A030

Teradata Parallel Data Pump Reference 173

Page 174: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsNAME

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.

174 Teradata Parallel Data Pump Reference

Page 175: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsPARTITION

PARTITION

PurposeThe 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

where

Syntax Element Description

number 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.

3021B018

threshold

.PARTITION partition_name SESSIONS number A

PACK statements

A

PACKMAXIMUM

DATAENCRYPTION

OFFON

Teradata Parallel Data Pump Reference 175

Page 176: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsPARTITION

DATAENCRYPTION ON/OFF

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.

PACK Keyword for the number of statements to pack into a multiple-statement request

Maximum value is 2430.

Packing improves network/channel efficiency by reducing the number of sends and receives between the application and Teradata Database.

PACKMAXIMUM Keyword requesting Teradata TPump to dynamically determine the maximum possible PACK factor for the current partition

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.

partition_name 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.

SESSIONS Keyword for designating the number of sessions for the partition

Syntax Element Description

176 Teradata Parallel Data Pump Reference

Page 177: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsPARTITION

Example

A sample script that uses partitioning follows:

.LOGTABLE TPLOG01;

.LOGON cs4400s3/cfl,cfl;DROP TABLE TPTBL01;DROP TABLE TPTBL02;DROP TABLE TPERR01;

CREATE TABLE TPTBL01, FALLBACK(C1 CHAR(12) not null,

statements 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.

threshold 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.

Syntax Element Description

Teradata Parallel Data Pump Reference 177

Page 178: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsPARTITION

C2 CHAR(8) not null)PRIMARY INDEX (C1);

CREATE TABLE TPTBL02, FALLBACK(C1 CHAR(12),C2 CHAR(8),C3 CHAR(6))UNIQUE PRIMARY INDEX (C1);

.BEGIN LOADERRLIMIT 100 50CHECKPOINT 15TENACITY 2ERRORTABLE TPERR01ROBUST offserialize on;

.LAYOUT LAY02;

.FIELD cc1 * CHAR(12) key;

.FIELD cc2 * CHAR(8);

.FIELD cc3 * CHAR(6);

.filler space1 * char(1);

.partition part1 pack 10 sessions 10;

.partition part2 sessions 5 1 packmaximum;

.DML LABEL LABEL01 partition part1DO INSERT FOR MISSING ROWSignore extra update rows

use(cc1, cc2);

UPDATE TPTBL01SET C2 = :CC2WHERE C1 = :CC1;INSERT TPTBL01 (C1, C2)VALUES (:CC1,:CC2);

.DML LABEL LABEL02 partition part2serializeon( cc1 )ignore extra update rowsDO INSERT FOR MISSING UPDATE ROWS;

UPDATE TPTBL02 SET C2 = :CC2 WHERE C1 = :CC1;INSERT TPTBL02 (C1, C2, C3)

VALUES (:CC1,:CC2,:CC3);

.IMPORT INFILE c:\NCR\Test\TpumpData001.txt FORMAT TEXTLAYOUT LAY02APPLY LABEL01APPLY LABEL02 where CC2 = '00000001';

.END LOAD;

.LOGOFF;

178 Teradata Parallel Data Pump Reference

Page 179: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsROUTE

ROUTE

PurposeThe ROUTE command identifies the destination of various outputs produced by Teradata TPump.

Syntax

where

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

Syntax Element Description

MESSAGES 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

fileid1 and fileid2 Alternate message destination in the external system

UNIX and WindowsFileid 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/OSA DDNAME. See the z/OS fileid topic in the “Usage Notes” section.

ECHO 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.

3021A031

.ROUTE MESSAGES

TO

;FILE fileid1

WITH

ECHO

WITH

ECHO OFF

TO

FILE

TO

FILE

TO

FILE fileid2

fileid1 ECHO

WITH TO

fileid2

fileid1WITH

ECHO OFF

Teradata Parallel Data Pump Reference 179

Page 180: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsROUTE

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

Example 1

.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.

180 Teradata Parallel Data Pump Reference

Page 181: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsRUN FILE

RUN FILE

PurposeThe RUN FILE command invokes the specified external source as the current source of commands and statements.

Syntax

where

Syntax Element Description

fileid Data source of the external system

The client system DD or equivalent statement specifies a file.

UNIX and Windowsinfilename (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/OSa 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). The “at” sign (@) is allowed as an alphabetic character and the underscore (_) is not allowed.

3021A032

.RUN FILE

IGNORE

;fileidcharpos1

THRU charpos2

charpos1 THRU

charpos1 THRU charpos2

Teradata Parallel Data Pump Reference 181

Page 182: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsRUN FILE

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 user-provided 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;

charpos1 and charpos2 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.

Syntax Element Description

182 Teradata Parallel Data Pump Reference

Page 183: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsSET

SET

PurposeThe 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

where

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 <=abs(float variable)<7.0E75

Example 1

Teradata TPump supports concatenation of variables, using the SET command, such as:

.SET C TO 1;

.SET D TO 2;

.SET X TO &C.&D;

Syntax Element Description

var Name of the utility variable which is set to the evaluated expression following it

expression Value and data type to which the utility variable is to be set

3021A033

.SET

TO

;var expression

Teradata Parallel Data Pump Reference 183

Page 184: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsSET

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.

184 Teradata Parallel Data Pump Reference

Page 185: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsSYSTEM

SYSTEM

PurposeThe SYSTEM command allows access to the local operating system during Teradata TPump operations.

Syntax

where

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.

Syntax Element Description

‘oscommand' 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.

3021A034

.SYSTEM ;'oscommand'

Teradata Parallel Data Pump Reference 185

Page 186: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsTABLE

TABLE

PurposeThe 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

where

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.

Syntax Element Description

tableref 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.

.TABLE

3021A035

;tableref

186 Teradata Parallel Data Pump Reference

Page 187: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsTABLE

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.

Teradata Parallel Data Pump Reference 187

Page 188: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsUPDATE Statement and Atomic Upsert

UPDATE Statement and Atomic Upsert

PurposeTeradata TPump supports the UPDATE Teradata SQL statement, which changes field values in existing rows of a table.

Syntax

where

Syntax Element Description

tname 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.

cname Column whose value is to be replaced by the value of expr

The column named must not be a column of the primary index.

expr 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.

WHERE condition 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.

UPDATE ;tname

3021A036

UPD

,

SET cname = expr WHERE conditional

188 Teradata Parallel Data Pump Reference

Page 189: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsUPDATE Statement and Atomic Upsert

Usage Notes - Update

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 default number of statements packed is 20.

• 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.

Temporal Semantics

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 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.

.BEGIN LOAD SESSION number;

.LAYOUT Layoutname;

.FIELD EmpNum 1 INTEGER;

.FIELD Fone * (CHAR (10));

.DML LABEL DMLlabelname; UPDATE Employee SET PhoneNo = :Fone WHERE EmpNo = :EmpNum;

Teradata Parallel Data Pump Reference 189

Page 190: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsUPDATE Statement and Atomic Upsert

.IMPORT INFILE Infilename LAYOUT Layoutname APPLY DMLlabelname;

.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 <update-operands> ELSE INSERT <insert-operands>;

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 <update-operands> and <insert-operands> 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

190 Teradata Parallel Data Pump Reference

Page 191: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsUPDATE Statement and Atomic Upsert

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:

DO INSERT FOR MISSING UPDATE ROWS;UPDATE <update-operands>;INSERT <insert-operands>;

Teradata Parallel Data Pump Reference 191

Page 192: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsUPDATE Statement and Atomic Upsert

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 <update-macro> ELSE EXEC <insert-macro>;

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:

INSERT INTO Sales (10, '05/30/2005', 1);

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.

UPDATE Sales SET ItemCount = ItemCount + 1 WHERE (ItemNbr = 10 AND 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.

192 Teradata Parallel Data Pump Reference

Page 193: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsUPDATE Statement and Atomic Upsert

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 all-row 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.

UPDATE Sales SET ItemCount = ItemCount + 1 WHERE (ItemNbr = 10 AND 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.

UPDATE Sales SET ItemCount = ItemCount + 1 WHERE (ItemNbr = 10 AND 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.

Teradata Parallel Data Pump Reference 193

Page 194: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 3: Teradata TPump CommandsUPDATE Statement and Atomic Upsert

Example 9 (Valid Upsert UPDATE)

This example demonstrates a successful upsert statement that updates a row.

UPDATE Sales SET ItemCount = ItemCount + 1 WHERE (ItemNbr = 10 AND SaleDate = '05/30/2005') ELSE INSERT INTO Sales (10, '05/30/2005', 1);

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.

UPDATE Sales SET ItemCount = ItemCount + 1 WHERE (ItemNbr = 20 AND SaleDate = '05/30/2005') ELSE INSERT INTO Sales (20, '05/30/2005', 1);

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.

194 Teradata Parallel Data Pump Reference

Page 195: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

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.

Teradata Parallel Data Pump Reference 195

Page 196: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 4: TroubleshootingError 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.

Error Messages

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.

196 Teradata Parallel Data Pump Reference

Page 197: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 4: TroubleshootingError Messages

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.

2676 Invalid calculation: division by zero.

2679 The format or data contains a bad character.

2682 Precision loss during data conversion.

2683 Numerical overflow occurred during computation.

2684 Invalid calculation: division by zero.

2687 The format or data contains a bad character.

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.

Table 29: Teradata TPump Error Conditions (continued)

Error Description

Teradata Parallel Data Pump Reference 197

Page 198: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 4: TroubleshootingError Messages

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.

Table 29: Teradata TPump Error Conditions (continued)

Error Description

198 Teradata Parallel Data Pump Reference

Page 199: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 4: TroubleshootingReading Teradata TPump Error Tables

Reading Teradata TPump Error Tables

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.

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.

Table 29: Teradata TPump Error Conditions (continued)

Error Description

Teradata Parallel Data Pump Reference 199

Page 200: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 4: TroubleshootingReading Teradata TPump Error Tables

Avoiding Data Errors

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.

Acquisition Error Table

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.

200 Teradata Parallel Data Pump Reference

Page 201: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 4: TroubleshootingReading Teradata TPump Error Tables

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 layout1APPLY 001 APPLY FIRSTDML;

IMPORT 002 .IMPORT INFILE file2 LAYOUT layout2APPLY 001 APPLY FIRSTDMLAPPLY 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 Parallel Data Pump Reference 201

Page 202: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 4: TroubleshootingTeradata 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.

202 Teradata Parallel Data Pump Reference

Page 203: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

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

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.

INMOD 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.

Teradata Parallel Data Pump Reference 203

Page 204: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 5: Using INMOD and Notify Exit RoutinesOverview

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

204 Teradata Parallel Data Pump Reference

Page 205: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 5: Using INMOD and Notify Exit RoutinesOverview

Programming Structure

Table 32 defines the structure by programming language for communicating between Teradata TPump and INMOD or notify exit routines.

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 34 lists the entry points for Notify Exit routines.

Table 32: Programming Routines by Language

Routine Language Programming Structure

C 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];

}

Table 33: Entry Points for INMOD Routines

INMOD Routine Language Entry Point

IBM C on z/OS platforms _dynamn

z/OS platform DYNAMN

C on UNIX and Windows platforms _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.

Teradata Parallel Data Pump Reference 205

Page 206: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 5: Using INMOD and Notify Exit RoutinesOverview

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 34: NOTIFY EXIT Routine

Notify Exit Routine Language Entry Point

IBM C on z/OS platforms _dynamn

z/OS platform DYNAMN

C on UNIX and Windows platforms _dynamn

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.

206 Teradata Parallel Data Pump Reference

Page 207: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 5: Using INMOD and Notify Exit RoutinesOverview

Table 36 explains the two status codes used by the INMOD-to-Teradata TPump interface.

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-of-file 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

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: 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.

Table 35: Teradata TPump-to-INMOD Status Codes (continued)

Value Description

Teradata Parallel Data Pump Reference 207

Page 208: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 5: Using INMOD and Notify Exit RoutinesOverview

• 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

EventEvent 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

208 Teradata Parallel Data Pump Reference

Page 209: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 5: Using INMOD and Notify Exit RoutinesOverview

Import begin 3 The first record is about to be read for each import task

Import number—4-byte unsigned integer

Import end 4 The last record has been read for each import task. The returned data is the record statistics for the import task

• 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

Error table 5 Processing of the SEL COUNT(*) request completed successfully for the error table

• Table name—128-byte character (maximum) array

• Number of rows—4-byte unsigned integer

Teradata Database 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

Teradata Database 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

Exit code—4-byte unsigned integer

Table statistics 10 Teradata TPump has successfully written the table statistics

• 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

Checkpoint end 11 Teradata TPump successfully completed the checkpoint operation

Record number—4-byte unsigned integer

Table 37: Events Passed to the Notify Exit Routine (continued)

EventEvent Code Event Description Data Passed to the Notify Exit Routine

Teradata Parallel Data Pump Reference 209

Page 210: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 5: Using INMOD and Notify Exit RoutinesOverview

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

• Import number—4-byte unsigned integer

• Statements sent to Teradata Database—4-byte unsigned integer

• Requests sent to Teradata Database—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

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

• Import number—4-byte unsigned integer

• 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.

Table 37: Events Passed to the Notify Exit Routine (continued)

EventEvent Code Event Description Data Passed to the Notify Exit Routine

210 Teradata Parallel Data Pump Reference

Page 211: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 5: Using INMOD and Notify Exit RoutinesOverview

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)

Teradata Parallel Data Pump Reference 211

Page 212: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 5: Using INMOD and Notify Exit RoutinesOverview

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.

212 Teradata Parallel Data Pump Reference

Page 213: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 5: Using INMOD and Notify Exit RoutinesUsing INMOD and Notify Exit Routines

Using INMOD and Notify Exit Routines

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 Parallel Data Pump Reference 213

Page 214: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 5: Using INMOD and Notify Exit RoutinesUsing INMOD and Notify Exit Routines

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.

214 Teradata Parallel Data Pump Reference

Page 215: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 5: Using INMOD and Notify Exit RoutinesUsing INMOD and Notify Exit Routines

• The INMOD filename parameter specified on the IMPORT command must be the fully qualified UNIX pathname of the INMOD shared object file.

• The parms string may include one or more character strings, each delimited on either end by an apostrophe, or delimited on either end by a quotation mark. The maximum size of the parms string is 1k bytes.

• If a FastLoad INMOD is used, the parms string of the IMPORT command must be “FDLINMOD”.

• The parms string as a whole must be enclosed in parentheses.

• 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 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.

• The parms string may include one or more character strings, each delimited on either end by an apostrophe, or delimited on either end by a quotation mark. The maximum size of the parms string is 1k bytes.

• If a FastLoad INMOD is used, the parms string of the IMPORT command must be “FDLINMOD”.

• The parms string as a whole must be enclosed in parentheses.

• Parentheses within delimited character strings or comments have the same syntactical significance as alphabetic characters.

Teradata Parallel Data Pump Reference 215

Page 216: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 5: Using INMOD and Notify Exit RoutinesPreparing the INMOD Program

• 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 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.

216 Teradata Parallel Data Pump Reference

Page 217: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 5: Using INMOD and Notify Exit RoutinesINMOD Output Values

INMOD Output Values

Table 39 lists valid values of the Return Code field and their meanings, as output to the INMOD routine.

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).

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.

Table 38: INMOD Input Return Code Values (continued)

Code Description

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.

Teradata Parallel Data Pump Reference 217

Page 218: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 5: Using INMOD and Notify Exit RoutinesProgramming INMODs for UNIX-based Clients

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

where

Use the following syntax example to link the object modules into a shared object module.

Link Syntax

where

Syntax Element Description

cc Program that invokes the MetaWare High C Compiler

c Linker option specifying to compile without linking to produce an output file (a.out)

inmod.c A C source module for the INMOD

3021A038

cc -c inmod.c

HE05A016

ld -dy inmod.o-G -o inmod.so

,

218 Teradata Parallel Data Pump Reference

Page 219: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 5: Using INMOD and Notify Exit RoutinesProgramming INMODs for UNIX-based Clients

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.

where

Syntax Element Description

ld Invokes the UNIX linker editor

dy Specifies to use dynamic linking

G Specifies to create a shared object

inmod.o Describes an object module derived from the compile step (see above)

o Specifies the output filename; default is a.out

inmod.so 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.

Syntax Element Description

cc Invokes the MetaWare High C Compiler

-G Specifies to create a shared object

-KPIC Is a compiler option that generates Position Independent Code (PIC) for all user exit routine

sourcefile Is a C source module for the INMOD

-o Specifies the output file name

shared-object-name

Specifies the resulting shared object module

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.

2409B051

cc -G -o shared-object-namesourcefile.c-KPIC

Teradata Parallel Data Pump Reference 219

Page 220: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 5: Using INMOD and Notify Exit RoutinesProgramming INMODs for UNIX-based Clients

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.

where

Syntax Element Description

cc Invokes the MetaWare High C Compiler

-dy Specifies to use dynamic linking

-G Specifies to create a shared object

sourcefile Is a C source module for the INMOD

-o Specifies the output file name

shared-object-name

Specifies the resulting shared object module

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.

2409A055

sourcefile.c -o shared-object-name-G-dycc

220 Teradata Parallel Data Pump Reference

Page 221: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 5: Using INMOD and Notify Exit RoutinesProgramming INMODs for UNIX-based Clients

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.

Compile Syntax

where

Use the following syntax example to link the object modules on HP-UX PA-RISC into the shared object.

Link Syntax

where

Syntax Element Description

-Aa Option that enables the compiler to conform to ANSI standards

-D_HPUX_SOURCE

Enables the compiler to access macros and typedefs that are not defined by the HPUX Operating System, but not the ANSI standard.

cc Invokes the MetaWare High C Compiler

+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

Syntax Element Description

ld Invokes the UNIX linker editor

-b Is a linker option specified to generate a shared object file

inmod.o Is an object module derived from the compile step (see above)

o Specifies the output filename; default is a.out

3021B002

-D_HPUX_SOURCE-Aa +zcc +u1 -c sourcefile.c

3021A003

ld -b inmod.o -o inmod.so

,

Teradata Parallel Data Pump Reference 221

Page 222: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 5: Using INMOD and Notify Exit RoutinesProgramming INMODs for UNIX-based Clients

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.

Compile Syntax

where

Use the following syntax example to link the object modules on HP-UX Itanium into the shared object.

Link Syntax

where

inmod.so Specifies the resulting shared object module

This is the user-specified name in the IMPORT command.

Syntax Element Description

Syntax Element Description

cc Invokes the MetaWare High C compiler

+u1 Is a compiler option that allows pointers to access non-natively aligned data

-D_REENTRANT Ensures that all the Pthread definitions are visible at compile time

+DD64 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

Syntax Element Description

ld Invokes the UNIX linker editor

2409A057

inmod.c+u1cc -D_REENTRANT +DD64 -c

2409A056

inmod.o inmod.so-nld -b -lc -o

222 Teradata Parallel Data Pump Reference

Page 223: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 5: Using INMOD and Notify Exit RoutinesProgramming INMODs for UNIX-based Clients

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.

Compile Syntax

where

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.

-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 Is an object module derived from the compile step (see above)

-lc Search a library libc.a, libc.so, or libc.sh

-o Specifies the output filename; default is a.out

inmod.so 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.

Syntax Element Description

Syntax Element Description

cc Call to the program that invokes the native UNIX C compiler

--qmkshrobj Creates a shared object from the generated object files

-o Switches to the linker

shared-object-name

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.

sourcefile UNIX file name(s) of the source file(s) for the INMOD

2409C008

cc -qmkshrobj -o -sourcefile.cshared-object-name

Teradata Parallel Data Pump Reference 223

Page 224: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 5: Using INMOD and Notify Exit RoutinesProgramming INMODs for UNIX-based Clients

Compile Syntax

where

Use the following syntax example to link the object modules into a shared object module.

Link Syntax

where

Syntax Element Description

cc 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 Tells the linkage editor to accept both .sl and .a library file types

-fPIC Is a compiler option that generates Position Independent Code (PIC) for all user exit routines

sourcefile.c Is a C source module for the [Notify Exit Routine.

Syntax Element Description

ld Invokes the UNIX linker editor

G Produces a shared object enabled for use with the run-time linker

-e_dynamn Sets the entry point of the exit routine to _dynamn

-bE : export_dynamn.txt Is a linker option that exports the symbol "_dynamn" explicitly and the file export_dynamn.txt contains the symbol

objectfile.o Is an object module created during compile step

3021A008

cc -c -brtl -fPIC sourcefile.c

3021A011

ld -G -e_dynamn -bE: export_dynamn.txt

objectfile.o -o shared-object-name -lm -lc

A

A

224 Teradata Parallel Data Pump Reference

Page 225: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 5: Using INMOD and Notify Exit RoutinesProgramming INMODs for UNIX-based Clients

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.

where

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.

Note: Be sure to compile the INMOD and notify exit routines in 32-bit mode so that they are compatible with Teradata TPump.

-o Specifies the output file name

shared-object-name Specifies the resulting shared object module

This is the EXIT name parameter for the NOTIFY option of the BEGIN LOAD command of the Teradata TPump job script.

-lm Is a linker option specifying to link with the /lib/libm.a library

-lc Is a linker option specifying to link with the /lib/libc.a library

Syntax Element Description

Syntax Element Description

gcc Invokes the C compiler on Linux

shared 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

-o Specifies the output file name

2409B023

gcc sourcefile.c-I/usr/include -shared -fPIC-m32

-o shared-object-name

2409A059

gcc -I/usr/include -m31 -shared -fPIC sourcefile.c -o shared-object-name

Teradata Parallel Data Pump Reference 225

Page 226: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 5: Using INMOD and Notify Exit RoutinesProgramming INMODs for UNIX-based Clients

where

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:

Note: Be sure to compile the INMOD and notify exit routines in 32-bit mode so that they are compatible with Teradata TPump.

where

Syntax Element Description

gcc Call to the program that invokes the native C compiler

-m31 Generates code for a 32-bit environment.

-shared Flag that produces a shared object that can then be linked with other objects to form an executable

-fPIC Compiler option that generates Position Independent Code for all user exit routines

shared-object-name

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

Syntax Element 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.

2409A058

cc "MVS.PDSE.LOAD(module_name)"-o

-W c,dll,expo ="//MVS.PDSE.C(source_name.c)" -W l,dll

226 Teradata Parallel Data Pump Reference

Page 227: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 5: Using INMOD and Notify Exit RoutinesProgramming INMODs for a Windows Client

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.

where

Syntax Element Description

cl Invokes the Microsoft C Compiler

D Defines a macro

LD Creates a .dll

inmod.c Denotes a C source module for the INMOD

3021B012

cl /DWIN32 LD inmod.c/

Teradata Parallel Data Pump Reference 227

Page 228: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Chapter 5: Using INMOD and Notify Exit RoutinesProgramming INMODs for a Windows Client

228 Teradata Parallel Data Pump Reference

Page 229: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

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

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.

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 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.

Spaces Use one space between items such as keywords or variables.

Punctuation Type all punctuation exactly as it appears in the diagram.

Teradata Parallel Data Pump Reference 229

Page 230: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Appendix A: How to Read Syntax DiagramsSyntax Diagram Conventions

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:

When you see a circled letter in a syntax diagram, go to the corresponding circled letter and continue reading.

Required Entries

Required entries appear on the main path:

If you can choose from more than one entry, the choices appear vertically, in a stack. The first entry appears on the main path:

Optional Entries

You may choose to include or disregard optional entries. Optional entries appear below the main path:

If you can optionally choose from more than one entry, all the choices appear below the main path:

FE0CA002

A

A

FE0CA003

SHOW

FE0CA005

SHOW

VERSIONS

CONTROLS

FE0CA004

SHOW

CONTROLS

230 Teradata Parallel Data Pump Reference

Page 231: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Appendix A: How to Read Syntax DiagramsSyntax Diagram Conventions

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:

If the string text includes a single quote or a blank space, the string appears in double quotes:

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.

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:

JC01A010SHARE

READ

ACCESS

JC01A004

'msgtext'

JC01A005

''abc'd"

''abc d"

FE0CA042

SHOW

CONTROL

CONTROLS

Teradata Parallel Data Pump Reference 231

Page 232: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Appendix A: How to Read Syntax DiagramsSyntax Diagram Conventions

Read loops from right to left.

The following conventions apply to loops:

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.

Loop Convention Description

A maximum number of entries is allowed.

The number appears in a circle on the return path.

In the example, you may type cname a maximum of 4 times.

A minimum number of entries is required.

The number appears in a square on the return path.

In the example, you must type at least three groups of column names.

A separator character is required between entries.

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.

A delimiter character is required around entries.

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.

JC01B012

(

, 4

cname )

, 3

232 Teradata Parallel Data Pump Reference

Page 233: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Appendix A: How to Read Syntax DiagramsSyntax Diagram Conventions

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:

Multiple Legitimate Phrases

In a syntax diagram, it is possible for any number of phrases to be legitimate:

In this example, any of the following phrases are legitimate:

• dbname

• DATABASE dbname

• tname

• TABLE tname

• vname

• VIEW vname

LOCKING excerpt

where_cond

A

cname

excerpt

JC01A014

A

HAVING con

,

col_pos

,

JC01A016

DATABASE

dbname

TABLE

tname

VIEW

vname

Teradata Parallel Data Pump Reference 233

Page 234: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Appendix A: How to Read Syntax DiagramsSyntax Diagram Conventions

Sample Syntax Diagram

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.

JC01A018

viewnameCREATE VIEW AS

cname

A

C

CV

,

LOCKING

LOCK

ACCESSA

DATABASE

dbname

TABLE

tname

VIEW

vname

FOR

IN

B

SHARE

READ

WRITE

EXCLUSIVE

EXCL

MODE

FROMB SEL C

.aname

expr

,

tname

,

qual_cond

qual_cond

WHERE cond

cname

,

col_pos

,GROUP BY

HAVING cond ;

234 Teradata Parallel Data Pump Reference

Page 235: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

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. *//***********************************************/.LOGTABLE TPLOG0623;.LOGON HYIBMX01/BRUCEDB,BRUCE;

DROP TABLE TPTBL0623;DROP TABLE TPERR0623;

/***********************************************//* STEP01 CREATES THE TABLES FOR THE TPump JOB *//***********************************************/CREATE TABLE TPTBL0623, FALLBACK(

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))

UNIQUE PRIMARY INDEX (F1);

/***********************************************//* BEGIN LOAD WITH ALL THE OPTIONS SPECIFIED *//* SUCH AS ERRLIMIT, CHECKPOINT, SESSIONS, *//* TENACITY, etc. *//***********************************************/.BEGIN LOADCHECKPOINT 15SESSIONS 4 1

TENACITY 2ERRORTABLE TPERR0623ERRLIMIT 10ROBUST OFF

Teradata Parallel Data Pump Reference 235

Page 236: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Appendix B: Teradata TPump ExamplesSimple Script Example

PACK 500DATAENCRYPTION ON ARRAYSUPPORT ON RATE 200 RETRYTIMES 200 SLEEP 40 NOATOMICUPSERT MACRODB BRUCEDB NOTIFY OFFSERIALIZE ON;

.LAYOUT LAY0623;

.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;

.FIELD FF12 * DECIMAL(38,0);

.DML LABEL LABEL0623IGNORE DUPLICATE ROWSIGNORE MISSING ROWSIGNORE EXTRA ROWS;

INSERT INTO TPTBL0623 VALUES (:FF1,:FF2,:FF3,:FF4,:FF5,:FF6,:FF7,:FF8,:FF9,:FF10,:FF11,:FF12);

.IMPORT INFILE ./ALLTYPE.data LAYOUT LAY0623 APPLY LABEL0623;.END LOAD;.LOGOFF;

produces the following output:

**** 15:17:25 UTY6633 WARNING: No configuration file, using build defaults ======================================================================== = = = Teradata Parallel Data Pump Utility Release 13.10.00.000 = = Platform WIN32 = = = ======================================================================== = = = Copyright 1997-2009 Teradata Corporation. ALL RIGHTS RESERVED. = = = ========================================================================**** 15:17:25 UTY2411 Processing start date: TUE OCT 06, 2009 ======================================================================== = = = Logon/Connection = = = ========================================================================0001 /***********************************************/ /* Script Name: TP0623 */ /* Description: WIN32 script. */ /***********************************************/ .LOGTABLE TPLOG0623;0002 .LOGON HYIBMX01/BRUCEDB,;**** 15:17:29 UTY8400 Teradata Database Release:13.10g.00.53**** 15:17:29 UTY8400 Teradata Database Version: 13.10g.00.53**** 15:17:29 UTY8400 Default character set: ASCII**** 15:17:29 UTY8400 Current RDBMS has UDT support

236 Teradata Parallel Data Pump Reference

Page 237: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Appendix B: Teradata TPump ExamplesSimple Script Example

**** 15:17:29 UTY8400 Maximum supported buffer size: 1M**** 15:17:29 UTY8400 Upsert supported by RDBMS server**** 15:17:29 UTY8400 Data Encryption supported by RDBMS server**** 15:17:29 UTY8400 Array Support supported by RDBMS server**** 15:17:32 UTY6211 A successful connect was made to the RDBMS.**** 15:17:32 UTY6217 Logtable 'BRUCEDB.TPLOG0623' has been created. ======================================================================== = = = Processing Control Statements = = = ========================================================================

0003 DROP TABLE TPTBL0623;**** 15:17:35 UTY1016 'DROP' request successful.0004 DROP TABLE TPERR0623;**** 15:17:37 UTY1008 RDBMS failure: 3807, Object 'TPERR0623' does not exist.

0005 /***********************************************/ /* STEP01 CREATES THE TABLES FOR THE TPump JOB */ /***********************************************/ CREATE TABLE TPTBL0623, FALLBACK( 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)) UNIQUE PRIMARY INDEX (F1);**** 15:17:39 UTY1016 'CREATE' request successful.

0006 /***********************************************/ /* BEGIN LOAD WITH ALL THE OPTIONS SPECIFIED */ /* SUCH AS ERRLIMIT, CHECKPOINT, SESSIONS, */ /* TENACITY, etc. */ /***********************************************/ .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; ======================================================================== = = = Processing TPump Statements = = = ========================================================================0007 .LAYOUT LAY0623;0008 .FIELD FF1 * INTEGER KEY;0009 .FIELD FF2 * CHAR(50);0010 .FIELD FF3 * VARCHAR(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;

Teradata Parallel Data Pump Reference 237

Page 238: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Appendix B: Teradata TPump ExamplesSimple Script Example

0018 .FIELD FF11 * BIGINT;0019 .FIELD FF12 * DECIMAL(38,0);0020 .DML LABEL LABEL0623 IGNORE DUPLICATE ROWS IGNORE MISSING ROWS IGNORE EXTRA ROWS;0021 INSERT INTO TPTBL0623 VALUES ( :FF1, :FF2, :FF3, :FF4, :FF5, :FF6, :FF7, :FF8, :FF9, :FF10, :FF11, :FF12);0022 .IMPORT INFILE ./ALLTYPE.data LAYOUT LAY0623 APPLY LABEL0623;0023 .END LOAD;**** 15:17:39 UTY6609 Starting to log on sessions...**** 15:17:44 UTY6610 Logged on 3 sessions. ======================================================================== = = = TPump Import(s) Beginning = = = ========================================================================**** 15:17:44 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: 10 rejected record(s). . Restart Mode: SIMPLE. . Serialization: ON. . Packing: 500 Statements per Request. . StartUp Rate: 200 Statements per Minute. .Rate Per Period: 50 Statements per 15000 milliseconds. . Atomic Upsert: DISABLED.**** 15:17:50 UTY6608 Import 1 begins.**** 15:22:51 UTY6641 Since last chkpt., 1000 recs. in, 1000 stmts., 24 reqs**** 15:22:51 UTY6647 Since last chkpt., avg. DBS wait time: 0.42**** 15:22:51 UTY6612 Beginning final checkpoint...**** 15:22:51 UTY6641 Since last chkpt., 1000 recs. in, 1000 stmts., 24 reqs**** 15:22:51 UTY6647 Since last chkpt., avg. DBS wait time: 0.42**** 15:22:52 UTY6607 Checkpoint Completes with 1000 rows sent.**** 15:22:52 UTY6642 Import 1 statements: 1000, requests: 24**** 15:22:52 UTY6643 Import 1 average statements per request: 41.67**** 15:22:52 UTY6644 Import 1 average statements per record: 1.00**** 15:22:52 UTY6645 Import 1 statements/session: avg. 333.33, min. 333.00, max. 334.00**** 15:22:52 UTY6646 Import 1 requests/session: average 8.00, minimum 8.00, maximum 8.00**** 15:22:52 UTY6648 Import 1 DBS wait time/session: avg. 3.33, min. 2.00, max. 4.00**** 15:22:52 UTY6649 Import 1 DBS wait time/request: avg. 0.42, min. 0.25, max. 0.50**** 15:22:52 UTY1803 Import processing statistics . IMPORT 1 Total thus far . ========= ============== Candidate records considered:........ 1000....... 1000 Apply conditions satisfied:.......... 1000....... 1000 Records logable to error table:...... 0....... 0 Candidate records rejected:.......... 0....... 0** Statistics for Apply Label : LABEL0623Type Database Table or Macro Name Activity I BRUCEDB TPTBL0623 1000**** 15:22:54 UTY0821 Error table BRUCEDB.TPERR0623 is EMPTY, dropping table.0024 .LOGOFF; ======================================================================== = =

238 Teradata Parallel Data Pump Reference

Page 239: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Appendix B: Teradata TPump ExamplesRestarted Upsert Example

= Logoff/Disconnect = = = ========================================================================**** 15:22:58 UTY6216 The restart log table has been dropped.**** 15:22:59 UTY6212 A successful disconnect was made from the RDBMS.**** 15:22:59 UTY2410 Total processor time used = '0.21875 Seconds' . Start : 15:17:25 - TUE OCT 06, 2009 . End : 15:22:59 - TUE OCT 06, 2009 . Highest return code encountered = '0'.

Restarted Upsert Example

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:

/***********************************************//* Script Name: TP0734 *//* Description: WIN32 script. *//***********************************************/.LOGTABLE TPLOG0734;.LOGON ESIBMX01/LYDIADB,LYDIA;DROP TABLE TPTBL0734;DROP TABLE TPERR0734;/***********************************************//* STEP01 CREATES THE TABLES FOR THE TPump JOB *//***********************************************/CREATE TABLE TPTBL0734, FALLBACK(

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))

UNIQUE PRIMARY INDEX (F1);/***********************************************//* BEGIN LOAD WITH ALL THE OPTIONS SPECIFIED *//* SUCH AS ERRLIMIT, CHECKPOINT, SESSIONS, *//* TENACITY, etc. *//***********************************************/.BEGIN LOADCHECKPOINT 15SESSIONS 4 1

SERIALIZE ONERRORTABLE TPERR0734;.LAYOUT LAY0734;.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;

Teradata Parallel Data Pump Reference 239

Page 240: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Appendix B: Teradata TPump ExamplesRestarted Upsert Example

.FIELD FF10 * DATE;

.FIELD FF11 * BIGINT;

.FIELD FF12 * DECIMAL(38,0);/* insert half of the rows ......................*/.DML LABEL LABEL0734AIGNORE DUPLICATE ROWS

IGNORE MISSING ROWSIGNORE EXTRA ROWS;

INSERT INTO TPTBL0734 VALUES (:FF1,:FF2,:FF3,:FF4,:FF5,:FF6,:FF7,:FF8,:FF9,:FF10,:FF11,:FF12);

/* ... and then upsert all of the rows ..........*/.DML LABEL LABEL0734BIGNORE DUPLICATE ROWS

IGNORE MISSING ROWSIGNORE EXTRA ROWSDO INSERT FOR MISSING UPDATE ROWS;

UPDATE TPTBL0734 SET F7 = F7 + 1 WHERE F1 = :FF1; INSERT INTO TPTBL0734 VALUES (:FF1,:FF2,:FF3,:FF4,

:FF5,:FF6,:FF7,:FF8,:FF9,:FF10,:FF11,:FF12);

/* should result in an upsert with half inserts and half updates */.IMPORT INFILE ./ALLTYPE.data

LAYOUT LAY0734 FROM 1 FOR 400APPLY LABEL0734A WHERE FF3 = 'TERADATA';

.IMPORT INFILE ./ALLTYPE.dataLAYOUT LAY0734 FROM 1 FOR 400APPLY LABEL0734B;

.END LOAD;

.LOGOFF;

produces the following output (assuming it was restarted during the second import):

0001 /***********************************************/ /* Script Name: TP0734 */ /* Description: WIN32 script. */ /***********************************************/ .LOGTABLE TPLOG0734;0002 .LOGON ESIBMX01/LYDIADB,;**** 16:51:58 UTY8400 Teradata Database Release: 13.10g.00.53**** 16:51:58 UTY8400 Teradata Database Version: 13.10g.00.53**** 16:51:58 UTY8400 Default character set: ASCII**** 16:51:58 UTY8400 Current RDBMS has UDT support**** 16:51:58 UTY8400 Maximum supported buffer size: 1M**** 16:51:58 UTY8400 Upsert supported by RDBMS server**** 16:51:58 UTY8400 Data Encryption supported by RDBMS server**** 16:51:58 UTY8400 Array Support supported by RDBMS server**** 16:52:00 UTY6211 A successful connect was made to the RDBMS.**** 16:52:00 UTY6217 Logtable 'LYDIADB.TPLOG0734' has been created. ======================================================================== = = = Processing Control Statements = = = ========================================================================0003 DROP TABLE TPTBL0734;**** 16:52:02 UTY1016 'DROP' request successful.0004 DROP TABLE TPERR0734;**** 16:52:03 UTY1008 RDBMS failure: 3807, Object 'TPERR0734' does not exist.0005 /***********************************************/ /* STEP01 CREATES THE TABLES FOR THE TPump JOB */ /***********************************************/

240 Teradata Parallel Data Pump Reference

Page 241: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Appendix B: Teradata TPump ExamplesRestarted Upsert Example

CREATE TABLE TPTBL0734, FALLBACK( 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)) UNIQUE PRIMARY INDEX (F1);**** 16:52:06 UTY1016 'CREATE' request successful.0006 /***********************************************/ /* BEGIN LOAD WITH ALL THE OPTIONS SPECIFIED */ /* SUCH AS ERRLIMIT, CHECKPOINT, SESSIONS, */ /* TENACITY, etc. */ /***********************************************/ .BEGIN LOAD CHECKPOINT 15 SESSIONS 4 1 SERIALIZE ON ERRORTABLE TPERR0734; ======================================================================== = = = Processing TPump Statements = = = ========================================================================0007 .LAYOUT LAY0734;0008 .FIELD FF1 * INTEGER KEY;0009 .FIELD FF2 * CHAR(50);0010 .FIELD FF3 * VARCHAR(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;0019 .FIELD FF12 * DECIMAL(38,0);0020 /* insert half of the rows ......................*/ .DML LABEL LABEL0734A IGNORE DUPLICATE ROWS IGNORE MISSING ROWS IGNORE EXTRA ROWS;0021 INSERT INTO TPTBL0734 VALUES ( :FF1, :FF2, :FF3, :FF4, :FF5, :FF6, :FF7, :FF8, :FF9, :FF10, :FF11, :FF12);0022 /* ... and then upsert all of the rows ..........*/ .DML LABEL LABEL0734B IGNORE DUPLICATE ROWS IGNORE MISSING ROWS IGNORE EXTRA ROWS DO INSERT FOR MISSING UPDATE ROWS;0023 UPDATE TPTBL0734 SET F7 = F7 + 1 WHERE F1 = :FF1;0024 INSERT INTO TPTBL0734 VALUES ( :FF1, :FF2, :FF3, :FF4, :FF5, :FF6, :FF7, :FF8, :FF9, :FF10, :FF11, :FF12);0025 /* should result in an upsert with half inserts and half updates */ .IMPORT INFILE ./ALLTYPE.data LAYOUT LAY0734 FROM 1 FOR 400 APPLY LABEL0734A WHERE FF3 = 'TERADATA';0026 .IMPORT INFILE ./ALLTYPE.data LAYOUT LAY0734 FROM 1 FOR 400 APPLY LABEL0734B;0027 .END LOAD;**** 16:52:06 UTY6609 Starting to log on sessions...

Teradata Parallel Data Pump Reference 241

Page 242: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Appendix B: Teradata TPump ExamplesRestarted Upsert Example

**** 16:52:11 UTY6610 Logged on 3 sessions. ======================================================================== = = = TPump Import(s) Beginning = = = ========================================================================**** 16:52:11 UTY6630 Options in effect for following TPump Import(s): . Tenacity: 4 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: ROBUST. . Serialization: ON. . Packing: 20 Statements per Request. . StartUp Rate: UNLIMITED Statements per Minute.**** 16:52:18 UTY6608 Import 1 begins.**** 16:52:25 UTY6641 Since last chkpt., 400 recs. in, 200 stmts., 12 reqs**** 16:52:25 UTY6647 Since last chkpt., avg. DBS wait time: 0.58**** 16:52:25 UTY6612 Beginning final checkpoint...**** 16:52:25 UTY6641 Since last chkpt., 400 recs. in, 200 stmts., 12 reqs**** 16:52:25 UTY6647 Since last chkpt., avg. DBS wait time: 0.58**** 16:52:25 UTY6607 Checkpoint Completes with 200 rows sent.**** 16:52:25 UTY6642 Import 1 statements: 200, requests: 12**** 16:52:25 UTY6643 Import 1 average statements per request: 16.67**** 16:52:25 UTY6644 Import 1 average statements per record: 1.00**** 16:52:25 UTY6645 Import 1 statements/session: avg. 66.67, min. 66.00, max. 67.00**** 16:52:25 UTY6646 Import 1 requests/session: average 4.00, minimum 4.00, maximum 4.00**** 16:52:25 UTY6648 Import 1 DBS wait time/session: avg. 2.33, min. 0.00, max. 4.00**** 16:52:25 UTY6649 Import 1 DBS wait time/request: avg. 0.58, min. 0.00, max. 1.00**** 16:52:25 UTY1803 Import processing statistics . IMPORT 1 Total thus far . ========= ============== Candidate records considered:........ 400....... 400 Apply conditions satisfied:.......... 200....... 200 Records logable to error table:...... 0....... 0 Candidate records rejected:.......... 0....... 0** Statistics for Apply Label : LABEL0734AType Database Table or Macro Name Activity I LYDIADB TPTBL0734 200**** 16:52:33 UTY8800 WARNING: Rate Monitoring turned off - no permission on macro: TPumpMacro.ImportCreate.**** 16:52:33 UTY6608 Import 2 begins.**** 16:52:47 UTY6641 Since last chkpt., 400 recs. in, 400 stmts., 21 reqs**** 16:52:47 UTY6647 Since last chkpt., avg. DBS wait time: 0.67**** 16:52:47 UTY6612 Beginning final checkpoint...**** 16:52:47 UTY6641 Since last chkpt., 400 recs. in, 400 stmts., 21 reqs**** 16:52:47 UTY6647 Since last chkpt., avg. DBS wait time: 0.67**** 16:52:48 UTY6607 Checkpoint Completes with 400 rows sent.**** 16:52:48 UTY6642 Import 2 statements: 400, requests: 21**** 16:52:48 UTY6643 Import 2 average statements per request: 19.05**** 16:52:48 UTY6644 Import 2 average statements per record: 1.00**** 16:52:48 UTY6645 Import 2 statements/session: avg. 133.33, min. 133.00, max. 134.00**** 16:52:48 UTY6646 Import 2 requests/session: average 7.00, minimum 7.00, maximum 7.00**** 16:52:48 UTY6648 Import 2 DBS wait time/session: avg. 4.67, min. 0.00, max. 8.00**** 16:52:48 UTY6649 Import 2 DBS wait time/request: avg. 0.67, min. 0.00, max. 1.14**** 16:52:48 UTY1803 Import processing statistics . IMPORT 2 Total thus far . ========= ==============

242 Teradata Parallel Data Pump Reference

Page 243: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Appendix B: Teradata TPump ExamplesExample Using the TABLE Command

Candidate records considered:........ 400....... 800 Apply conditions satisfied:.......... 400....... 600 Records logable to error table:...... 0....... 0 Candidate records rejected:.......... 0....... 0** Statistics for Apply Label : LABEL0734BType Database Table or Macro Name Activity U LYDIADB TPTBL0734 200 I LYDIADB TPTBL0734 200**** 16:52:50 UTY0821 Error table LYDIADB.TPERR0734 is EMPTY, dropping table.0028 .LOGOFF; ======================================================================== = = = Logoff/Disconnect = = = ========================================================================**** 16:52:54 UTY6216 The restart log table has been dropped.**** 16:52:55 UTY6212 A successful disconnect was made from the RDBMS.**** 16:52:55 UTY2410 Total processor time used = '0.21875 Seconds' . Start : 16:51:54 - TUE OCT 06, 2009 . End : 16:52:55 - TUE OCT 06, 2009 . Highest return code encountered = '0'.

Example Using the TABLE Command

This example script uses the TABLE command and “INSERT <TABLENAME>.*” feature.

.LOGTABLE TPLOG0096;

.LOGON ESSNLX14/KRCDB,KRCDB;DROP TABLE TPTBL0096;DROP TABLE TPERR0096;CREATE TABLE TPTBL0096, FALLBACK( F0 integer, F1 integer, F2 integer, F3 CHAR(38))UNIQUE PRIMARY INDEX (F0);

.BEGIN LOAD SESSIONS 8;

.LAYOUT LAY0096;

.TABLE TPTBL0096;

.DML LABEL LABEL0096 ; INSERT INTO TPTBL0096.*;

.IMPORT INFILE datafile1 LAYOUT LAY0096 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:35 UTY8400 Teradata Database Release: 13.10g.00.53

Teradata Parallel Data Pump Reference 243

Page 244: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Appendix B: Teradata TPump ExamplesExample Using the TABLE Command

**** 17:07:35 UTY8400 Teradata Database Version: 13.10g.00.53**** 17:07:35 UTY8400 Default character set: ASCII**** 17:07:35 UTY8400 Current RDBMS has UDT support**** 17:07:35 UTY8400 Maximum supported buffer size: 1M**** 17:07:35 UTY8400 Upsert supported by RDBMS server**** 17:07:35 UTY8400 Data Encryption supported by RDBMS server**** 17:07:35 UTY8400 Array Support supported by RDBMS server**** 17:07:37 UTY6211 A successful connect was made to the RDBMS.**** 17:07:37 UTY6217 Logtable KRCD.TPLOG0096' has been created. ======================================================================== = = = Processing Control Statements = = = ========================================================================0003 DROP TABLE TPTBL0096;**** 17:07:39 UTY1016 'DROP' request successful.0004 DROP TABLE TPERR0096;**** 17:07:41 UTY1008 RDBMS failure: 3807, Object 'TPERR0096' does not exist.0005 CREATE TABLE TPTBL0096, FALLBACK( F0 integer, F1 integer, F2 integer, F3 CHAR(38)) UNIQUE PRIMARY INDEX (F0);**** 17:07:43 UTY1016 'CREATE' request successful.

0006 .BEGIN LOAD SESSIONS 8; ======================================================================== = = = Processing TPump Statements = = = ========================================================================

0007 .LAYOUT LAY0096;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 LAYOUT LAY0096 APPLY LABEL0096 FROM 1 THRU 111;0012 .END LOAD;**** 17:07:44 UTY6609 Starting to log on sessions...**** 17:07:56 UTY6610 Logged on 8 sessions. ======================================================================== = = = TPump Import(s) Beginning = = = ========================================================================**** 17:07:56 UTY6630 Options in effect for following TPump Import(s): . Tenacity: 4 hour limit to successfully connect load sessions. . Max Sessions: 8 session(s). . Min Sessions: 6 session(s). . Checkpoint: 15 minute(s).

244 Teradata Parallel Data Pump Reference

Page 245: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Appendix B: Teradata TPump ExamplesExample Using the TABLE Command

. Errlimit: No limit in effect. . Restart Mode: ROBUST. . Serialization: OFF. . Packing: 20 Statements per Request. . StartUp Rate: UNLIMITED Statements per Minute.**** 17:08:04 UTY8800 WARNING: Rate Monitoring turned off - no permission on macro: TPumpMacro.ImportCreate.**** 17:08:04 UTY6608 Import 1 begins.**** 17:08:07 UTY6641 Since last chkpt., 111 recs. in, 111 stmts., 6 reqs**** 17:08:07 UTY6647 Since last chkpt., avg. DBS wait time: 0.50**** 17:08:07 UTY6612 Beginning final checkpoint...**** 17:08:07 UTY6641 Since last chkpt., 111 recs. in, 111 stmts., 6 reqs**** 17:08:07 UTY6647 Since last chkpt., avg. DBS wait time: 0.50**** 17:08:08 UTY6607 Checkpoint Completes with 111 rows sent.**** 17:08:08 UTY6642 Import 1 statements: 111, requests: 6**** 17:08:08 UTY6643 Import 1 average statements per request: 18.50**** 17:08:08 UTY6644 Import 1 average statements per record: 1.00**** 17:08:08 UTY6645 Import 1 statements/session: avg. 13.88, min. 0.00, max. 20.00**** 17:08:08 UTY6646 Import 1 requests/session: average 0.75, minimum 0.00, maximum 1.00**** 17:08:08 UTY6648 Import 1 DBS wait time/session: avg. 0.38, min. 0.00, max. 2.00**** 17:08:08 UTY6649 Import 1 DBS wait time/request: avg. 0.38, min. 0.00, max. 2.00**** 17:08:08 UTY1803 Import processing statistics . IMPORT 1 Total thus far . ========= ============== Candidate records considered:........ 111....... 111 Apply conditions satisfied:.......... 111....... 111 Records logable to error table:...... 0....... 0 Candidate records rejected:.......... 0....... 0** Statistics for Apply Label : LABEL0096Type Database Table or Macro Name Activity I KRCDB TPTBL0096 111**** 17:08:10 UTY0821 Error table KRC.M20080627_170744_00603_001_ET is EMPTY, dropping table.0013 .LOGOFF; ======================================================================== = = = Logoff/Disconnect = = = ========================================================================**** 17:08:17 UTY6216 The restart log table has been dropped.**** 17:08:17 UTY6212 A successful disconnect was made from the RDBMS.**** 17:08:17 UTY2410 Total processor time used = '0.390625 Seconds' . Start : 17:07:30 -TUE OCT 06, 2009 . End : 17:08:17 - TUE OCT 06, 2009 . Highest return code encountered = '0'.

Teradata Parallel Data Pump Reference 245

Page 246: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Appendix B: Teradata TPump ExamplesExample Using the TABLE Command

246 Teradata Parallel Data Pump Reference

Page 247: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

APPENDIX C

INMOD and Notify Exit RoutineExamples

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 routinemust return "return code"(a->code) and "length" (a->len). Youshould send return code = zero when no errors occur and non-zero foran error. LOAD expects length = zero at the end of file. Thenit sends "CLOSE INMOD" request. THE USER EXIT routine mustexplicitly return "return code" = ZERO to terminate theconversation.

The following TPUMP control statements will work with this inmod:

.LOGTABLE <logtable>;

.LOGON <logon>;

DROP TABLE TABLE200;

Teradata Parallel Data Pump Reference 247

Page 248: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Appendix C: INMOD and Notify Exit Routine ExamplesC INMOD - UNIX

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;

.FIELD x3 * char(10) nullif x1 = 4;

.FIELD x4 * char(10) nullif x1 = 4;

.FIELD x5 * char(10) nullif x1 = 4;

.FIELD x6 * char(10) nullif x1 = 4;

.FIELD x7 * char(10) nullif x1 = 4;

.FIELD x8 * char(10) nullif x1 = 4;

.FIELD x9 * char(5) nullif x1 = 4;

.FIELD x10 * char(5) nullif x1 = 4;

.DML LABEL A;

INSERT INTO TABLE200 VALUES( :x1,:x2);

.IMPORT INMOD <inmodname> LAYOUT TABLE200 APPLY A FROM 1 THRU 100;

.END LOAD ;

.LOGOFF;

************************************************************************/#include <stddef.h> #include <stdlib.h> #include <stdio.h> 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;

248 Teradata Parallel Data Pump Reference

Page 249: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Appendix C: INMOD and Notify Exit Routine ExamplesC INMOD - UNIX

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;#elsevoid _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;

Teradata Parallel Data Pump Reference 249

Page 250: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Appendix C: INMOD and Notify Exit Routine ExamplesSample Notify Exit Routine

{ int rtn=0; int i=0; if (count < 50000) { a->buf.seqno = count; count++; for (i=0; i<75; i++) a->buf.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); }

Sample Notify Exit Routine

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 *

250 Teradata Parallel Data Pump Reference

Page 251: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Appendix C: INMOD and Notify Exit Routine ExamplesSample Notify Exit Routine

* gcc -shared -fPIC tldnfyxt.c -o libtldnfyxt.so ** ***********************************************************************/#ifdef __MVS__#pragma pack(1)#endif

#include <stdio.h>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];

Teradata Parallel Data Pump Reference 251

Page 252: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Appendix C: INMOD and Notify Exit Routine ExamplesSample Notify Exit Routine

} 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 { UInt32 ErrorCode; } CLIError; struct { int nImport; UInt32 nSQLstmt; UInt32 nReqSent; UInt32 RecsIn; UInt32 RecsSkipped; UInt32 RecsRejd; UInt32 RecsOut; UInt32 RecsError; } Stats; struct {

UInt32 nImport; UInt32 ErrorCode; char *ErrorMsg; UInt32 nRecord; unsigned char nApplySeq; unsigned char nDMLSeq; unsigned char nSMTSeq; char *ErrorData; UInt32 ErrorDataLen;

252 Teradata Parallel Data Pump Reference

Page 253: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Appendix C: INMOD and Notify Exit Routine ExamplesSample Notify Exit Routine

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)#elseInt32 _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 :

Teradata Parallel Data Pump Reference 253

Page 254: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Appendix C: INMOD and Notify Exit Routine ExamplesSample Notify Exit Routine

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 : %u \n", P->Vals.Complete.RecsIn, P->Vals.Complete.RecsSkipped, P->Vals.Complete.RecsRejd, P->Vals.Complete.RecsOut, P->Vals.Complete.RecsError); 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", P->Vals.TableStats.Activity,

254 Teradata Parallel Data Pump Reference

Page 255: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Appendix C: INMOD and Notify Exit Routine ExamplesSample Notify Exit Routine

P->Vals.TableStats.szName, P->Vals.TableStats.dbasename); if(P->Vals.TableStats.type == 'D') fprintf(fp,"Rows Deleted : " "%u \nTable/Macro Name : %s \nDatabase Name" " : %s \n", P->Vals.TableStats.Activity, P->Vals.TableStats.szName, P->Vals.TableStats.dbasename); 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 ;i<P->Vals.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;

Teradata Parallel Data Pump Reference 255

Page 256: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Appendix C: INMOD and Notify Exit Routine ExamplesSample Notify Exit Routine

} fclose(fp); return(0);}

256 Teradata Parallel Data Pump Reference

Page 257: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

APPENDIX D

User-Defined-Typesand User-Defined-Methods

This appendix provides information on User-Defined-Types (UDTs) andUser-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.

Teradata Parallel Data Pump Reference 257

Page 258: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Appendix D: User-Defined-Types and User-Defined-MethodsUser-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

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.

External Types

The “from-sql routine” and the “to-sql routine” create a mapping between a UDT and a pre-defined 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.

258 Teradata Parallel Data Pump Reference

Page 259: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Appendix D: User-Defined-Types and User-Defined-MethodsUser-Defined-Types and User-Defined-Methods

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.

Teradata Parallel Data Pump Reference 259

Page 260: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Appendix D: User-Defined-Types and User-Defined-MethodsUser-Defined-Types and User-Defined-Methods

260 Teradata Parallel Data Pump Reference

Page 261: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

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

Teradata Parallel Data Pump Reference 261

Page 262: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

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.

262 Teradata Parallel Data Pump Reference

Page 263: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

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.

Teradata Parallel Data Pump Reference 263

Page 264: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

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.

264 Teradata Parallel Data Pump Reference

Page 265: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Glossary

join: A SELECT operation that combines information from two or more tables to produce a result.

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, high-volume 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.

Teradata Parallel Data Pump Reference 265

Page 266: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

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 end-record 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 Database.

request: In host software, a message sent from an application program to Teradata Database.

restart log table: One of four restart tables that the Teradata utilities require for restarting a paused job.

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.

266 Teradata Parallel Data Pump Reference

Page 267: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Glossary

script: A file that contains a set of commands and SQL statements that initiates an operation or job.

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: Teradata Director Program Identifier. The name of the Teradata Database being accessed.

Teradata Parallel Data Pump Reference 267

Page 268: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

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.

268 Teradata Parallel Data Pump Reference

Page 269: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Glossary

z/OS (MVS (Multiple Virtual Storage) One of the primary operating systems for large IBM computers.

Teradata Parallel Data Pump Reference 269

Page 270: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Glossary

270 Teradata Parallel Data Pump Reference

Page 271: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

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

Aabort termination 52aborted Teradata TPump job

recovery 55ACCEPT command

definition 90function 29syntax 93

acctid specificationLOGON command 168

Acquisition Error Table 200aggregate operators, programming considerations 67ALTER TABLE SQL statement 30alternate error file runtime parameter 48ANSI/SQL DateTime specifications

programming considerations 62restrictions 63

ANSIDATE keywordDATEFORM command 109

APPEND keywordBEGIN LOAD command 97

application commandssyntax 89

APPLY label specification, IMPORT command 152

ArraySupport keywordBEGIN LOAD 101, 118

Atomic upsert feature 125Atomic UPSERT keyword

EXECUTE command 130AXSMOD keyword

IMPORT command 148AXSMOD name, IMPORT command 148

B-b runtime parameter 45batch mode

syntax for invoking on UNIX 43syntax for invoking on Windows 43syntax for invoking on z/OS 44

BEGIN LOAD commanddefinition 90function 29in script 69syntax 96

BRIEF runtime parameter 45buffers per session runtime parameter 45BUFFERS runtime parameter 45

C-c charactersetname runtime parameter 45C language INMODs

programming structure 205C language, comment support 63-C runtime parameter 47character sets

Chinese and Korean 24client system specifications 64default 64effects on Teradata TPump commands 65for AXSMOD 64Japanese 23runtime parameters 45site defined 27Teradata Database default 64Unicode 25UTF-16 26UTF-8 26

character-to-date data conversions 25character-to-numeric

data conversions 25

Teradata Parallel Data Pump Reference 271

Page 272: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Index

charpos1 94charpos2 94CHARSET= charactersetname runtime parameter 45CHECKPOINT keyword

BEGIN LOAD command 99CHECKPOINT SQL statement 30checkpoints

description 25Chinese and Korean character sets 24cname specification

INSERT command 157UPDATE statement 188

COLLECT STATISTICS SQL statement 30command

function 29in script 70overview 33

command functions 28commands

ACCEPTdefinition 90function 29syntax 93

BEGIN LOADdefinition 90function 29syntax 96

DATEFORMdefinition 90function 29syntax 109

DISPLAYdefinition 90function 29syntax 113

DMLdefinition 90function 29syntax 115

ELSEdefinition 90function 29syntax 144

END LOADdefinition 90function 29syntax 129

ENDIFdefinition 90function 29syntax 144

FIELDdefinition 90function 29

syntax 133FILLER

definition 90function 30syntax 142

IFdefinition 91syntax 144

IMPORTdefinition 91function 30syntax 146

LAYOUTdefinition 91function 30syntax 160

LOGOFFdefinition 91function 29syntax 165

LOGONdefinition 91function 29syntax 167

LOGTABLEdefinition 91function 29syntax 171

NAMEdefinition 91function 29syntax 173

PARTITIONdefinition 91function 30syntax 175

ROUTEdefinition 91function 29syntax 179

RUN FILEdefinition 91function 29syntax 181

SETdefinition 91function 29syntax 183

SYSTEMdefinition 91function 29syntax 185

TABLEdefinition 91

272 Teradata Parallel Data Pump Reference

Page 273: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Index

function 30syntax 186

usage 57COMMENT 31comment support 63condition specification

LAYOUT command 161conditional expression specification

IF, ELSE, and ENDI command 144conditional expressions 57CONFIG runtime parameter 47configuration file

optional specification 41parameters overridden by runtime parameters

BRIEF 45CHARSET 45ERRLOG 48

runtime parameter 47conversions

character-to-numeric 25integer-to-decimal 25numeric-to-numeric 25

CREATE DATABASE SQL statement 31CREATE MACRO SQL statement 31CREATE TABLE SQL statement 31CREATE VIEW SQL statement 31

D-d runtime parameter 48data

file concatenation, programming considerations 67data conversions

capabilities 25character-to-date 25character-to-numeric 25date-to-character 25integer-to-decimal 25numeric-to-numeric 25

data definition language 17, 37, 108data dictionary, defined 262data formats 22data manipulation language 17, 37, 108data serialization 18data types

ANSI/SQL DateTime 62ANSI/SQL DateTime restrictions 63

database objectsprotection and location 53

database specificationDATABASE command 108EXECUTE command 130

DATABASE SQL statement 31definition 92

syntax 108datadesc specification

FIELD command 134FILLER command 142

DATAENCRYPTION keywordBEGIN LOAD command 100, 176

DATEFORM commanddefinition 90function 29syntax 109

DateTime data types, specifying 62date-to-character data conversions 25dbname specification

BEGIN LOAD command 104LOGTABLE command 171

dbname. specificationBEGIN LOAD command 98

DDL 17, 37, 108ddname specification

IMPORT command 147decimal, zoned 25DELETE 130

macro 131DELETE DATABASE SQL statement 31DELETE DML statement

in script 70, 71DELETE SQL statement 31, 111

definition 92syntax 111

DISPLAY commanddefinition 90function 29syntax 113

DISPLAY ERRORS keyword, IMPORT command 152DML 17, 29, 33, 37, 70, 108DML command

definition 90syntax 115

DROP DATABASE SQL statement 31DROP keyword, FIELD command 135dynamn entry point

for C INMOD routines 205, 206for IBM C INMOD routines 205, 206

E-e filename runtime parameter 48echo 179ELSE command

definition 90function 29syntax 144

END LOAD commanddefinition 90

Teradata Parallel Data Pump Reference 273

Page 274: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Index

function 29in script 71syntax 129

ENDIF commanddefinition 90function 29syntax 144

env_var 93errcount specification

BEGIN LOAD command 99ERRLIMIT keyword

BEGIN LOAD command 99ERRLOG=filename runtime parameter 48error detection 195error tables

acquisition 200reading 199troubleshooting 199

errors 195ERRORTABLE keyword

BEGIN LOAD command 97EXECUTE SQL statement

definition 92EXECUTE statement

syntax 130EXIT keyword

BEGIN LOAD command 105EXIT name specification, BEGIN LOAD command 105exit routines, definition 204expr specification

UPDATE statement 188expression specification

INSERT command 157SET command 183

expressions, programming considerations 67

F-f runtime parameter 45features, advanced, INMODs 203FIELD command

definition 90function 29in script 70syntax 133

fieldexpr specificationFIELD command 135

fieldname specificationFIELD command 133FILLER command 142INSERT command 157

file requirementsfor invoking Teradata TPump 41

fileid 94, 113

filename specificationIMPORT command 149

FILLER commanddefinition 90function 30in script 70syntax 142

FOR n specification, IMPORT command 150FREE option, IMPORT command 149frequency specification

BEGIN LOAD command 100FROM keyword

IMPORT command 150

GGIVE SQL statement 31GRANT SQL statement 31graphic constants

hexadecimal 67KanjiEBCDIC 67support for 67

graphic data typessupport for 66

HHOLD option

IMPORT command 149hours specification

BEGIN LOAD command 101

IIF command

definition 91syntax 144

IGNORE keywordDML command 116

IMPORT commanddefinition 91function 30in script 71syntax 146

INDICATORS keywordLAYOUT command 162

INFILE filename specificationIMPORT command 149

INFILE keywordIMPORT command 147, 149

infilename standard input file specification 50init-string specification

IMPORT command 148INMODs 203

compiling and linking 218

274 Teradata Parallel Data Pump Reference

Page 275: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Index

FastLoad 215IBM interface 214input return code values 216input values 216, 217interface 214major functions 203output return code values 217preparing program 216programming 218routines

entry points 205platforms supported 204programming languages supported 204programming structure 205rules and restrictions 211using 213

Teradata TPump interface 214UNIX interface 214UNIX programming 218Windows interface 215

input/outputcontrolling 38

INSERT DML statementin script 70

INSERT keywordDML command 116EXECUTE command 130

INSERT macro 131INSERT SQL statement 31

definition 92syntax 157

INTEGERDATE keywordDATEFORM command 109

integer-to-decimaldata conversions 25

internationalization 18invoking

on UNIX platform 42on Windows platform 42

invoking Teradata TPump 41

JJapanese character sets 23job

recovery if aborted 55jobname specification

NAME command 173

KkanjiEBCDIC

graphic constants 67KEY keyword, FIELD command 135keyword

EXECUTE command 130Korean and Chinese character sets 24

LLABEL keyword

DML command 115label specification

DML command 116IMPORT command 152

LATENCY keywordBEGIN LOAD command 102

LAYOUT commanddefinition 91function 30in script 70syntax 160

LAYOUT name specification, IMPORT command 152layoutname specification

IMPORT command 152LAYOUT command 160

lockaccess 34acquisition 34application 34row hash locking 34write 34

log tablespace requirement calculation example 86space requirements 85

LOGDATA commandsyntax 163

LOGMECH commandsyntax 164

LOGOFF commanddefinition 91function 29messages 80syntax 165

logoff/disconnect message 75LOGON command

definition 91function 29syntax 167

LOGTABLE commanddefinition 91function 29syntax 171

logtablesnon-shareability 171space requirements 172

M-m runtime parameter 49

Teradata Parallel Data Pump Reference 275

Page 276: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Index

macro runtime parameters 49MACRODB keyword

BEGIN LOAD command 104macros 33

predefined 34Teradata TPump usage 18

MACROS runtime parameter 49MARK keyword

DML command 116maximum

row size, programming considerations 67messages 179minutes specification

BEGIN LOAD command 102MODIFY DATABASE SQL statement 31monitor facility 81MSG string specification, BEGIN LOAD command 105MultiLoad utility

data conversion capabilities 25MULTISET table 104

Nname 130NAME command

definition 91function 29syntax 173

name specificationBEGIN LOAD command 105IMPORT command 148

Named Pipes Access Module 148No Primary Index tables 19NOATOMICUPSERT 104NODROP keyword

BEGIN LOAD command 97NOMONITOR keyword

BEGIN LOAD command 104non-shareability

logtables 171NoPI tables 19normal termination 51NOSTOP keyword, IMPORT command 152NOTIFY option specification, BEGIN LOAD command 105NOTIMERPROCESS keyword

BEGIN LOAD command 102nullexpr specification

FIELD command 134number specification

BEGIN LOAD command 97PARTITION command 175

numeric-to-numericdata conversions 25

Ooperators

reserved words 56options messages 75, 79oscommand string specification

SYSTEM command 185outfilename standard output file specification 50

Ppack factor 85, 86PACK keyword

BEGIN LOAD command 103PARTITION command 176

packing 119, 158packing factor 85, 103, 104, 177PACKMAXIMUM keyword

BEGIN LOAD command 102PARTITION command 176

parms specificationIMPORT command 150

PARTITION commanddefinition 91function 30syntax 175

PARTITION keywordDML command 117

partition_name specificationDML command 117PARTITION command 176

password specificationLOGON command 168

performance checklisttroubleshooting

performance checklist 202periodicity runtime parameter 48PRDICITY runtime parameter 48predefined

macros 34preparing a Teradata TPump script 69privileges 34product version numbers 3programming INMODs

for UNIX-based clients 218UNIX-based clients 218

R-r tpump command runtime parameter 49RATE keyword

BEGIN LOAD command 103recovery

aborted Teradata TPump job 55procedures 52

276 Teradata Parallel Data Pump Reference

Page 277: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Index

reduced print output runtime parameter 45redundant conversions

supported 25RENAME SQL statement 31REPLACE MACRO SQL statement 31REPLACE VIEW SQL statement 31reporting

options messages 79statistics 75

restart 76reserved words

use in Teradata TPump 56restart

statistics 76restart log table 52, 53restart procedures 52restrictions and limitations

programming considerationsaggregate operators 67data file concatenation 67expressions 67maximum row size 67Teradata RDBMS data retrieval 67

retcode specificationLOGOFF command 165

return codes 51REVOKE SQL statement 31ROBUST keyword

BEGIN LOAD command 104ROUTE command

definition 91function 29syntax 179

rowsize, maximum 67

row count variables 61row hash locking 34RUN FILE command

definition 91function 29syntax 181

Sscript

example 72preparation 69writing guidelines 69writing procedure 71

scriptencoding parameter 46seconds specification

BEGIN LOAD command 102SERIALIZE keyword

BEGIN LOAD command 102

SERIALIZEON keywordDML command 117

sessions 91, 96, 101, 165, 167SESSIONS keyword

BEGIN LOAD command 97PARTITION command 176

SET commanddefinition 91function 29syntax 183

SET QUERY_BAND SQL statement 31SET SESSION COLLATION SQL statement 31single sign on 167SLEEP keyword 97, 101, 177

BEGIN LOAD command 104software releases

supported 3space requirements

for Teradata TPump log tables 85log table 85

SQLdefined 267

SQL statementsDATABASE

definition 92syntax 108

DELETEdefinition 92syntax 111

EXECUTEdefinition 92syntax 130

INSERTdefinition 92syntax 157

supported by Teradata TPump 30UPDATE

definition 92syntax 188

SQL, Teradata 37SSO

LOGON command 167starting Teradata TPump

on UNIX platform 42on Windows platform 42

startpos specificationFIELD command 133FILLER command 142

statement_rate specificationBEGIN LOAD command 104

statements 33statements specification

BEGIN LOAD command 103PARTITION command 177

Teradata Parallel Data Pump Reference 277

Page 278: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Index

statements to execute if FALSE specificationIF, ELSE, and ENDIF command 144

statements to execute if TRUE specificationIF, ELSE, and ENDIF command 144

statements to resume with specificationIF, ELSE, and ENDIF command 144

statistics 75facility 74restart 76

string variableMSG specification, BEGIN LOAD command 105TEXT specification, BEGIN LOAD command 105

support commands, defined 28support environment 37SYSAPLYCNT system variable 60SYSDATE system variable 59SYSDATE4 system variable 59SYSDAY system variable 59SYSDELCNT system variable 59SYSETCNT system variable 59SYSINSCNT system variable 59SYSJOBNAME 29SYSJOBNAME system variable 59SYSNOAPLYCNT system variable 60SYSOS system variable 59SYSRC system variable 59SYSRCDCNT system variable 59SYSRJCTCNT system variable 60SYSTEM command

definition 91function 29syntax 185

system failurerestart 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 60SYSUPDCNT system variable 60

SYSUSER system variable 60

TTABLE command

definition 91function 30in script 70syntax 186

tableref specificationTABLE command 186

tablesfallback 36nonfallback 36

taskcommands 28

task commands 38syntax and usage 89usage 57

tdpid specificationLOGON command 167

TENACITY keyword 101BEGIN LOAD command 101

Teradata OLE DB Access Module 148Teradata RDBMS

data retrieval, programming considerations 67Teradata SQL 37Teradata SQL statements

supported by Teradata TPump 30Teradata TPump

advanced features 203invoking

batch mode on UNIX 43batch mode on Windows 43batch mode on z/OS 44

macros 33Monitor facility 81Monitor facility interface 81script, example of 72support command, defined 28support environment 38using INMOD routines 213

Teradata TPump Conditional Expressions 57Teradata TPump/INMOD Routine Interface 206Teradata WebSphere® MQ Access Module 148Teradata WebSphere® MQ Access Module (server version)

148terminating a Teradata TPump job 52termination

return codes 51text 113TEXT string specification, BEGIN LOAD command 105threshold specification

PARTITION command 177

278 Teradata Parallel Data Pump Reference

Page 279: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Index

THRU keywordIMPORT command 150

time and date variables 60tname specification

BEGIN LOAD command 98DELETE statement 111INSERT command 157LOGTABLE command 171UPDATE statement 188

tpump command runtime parameter 49troubleshooting 195

early error detection 195error detection 195reading error tables 199

UUnicode

character sets 25UNIX

starting Teradata TPump 42syntax for invoking in batch mode 43

UPDATE DML statement 70in script 70

UPDATE keywordEXECUTE command 130

UPDATE macro 131UPDATE SQL statement 31

definition 92syntax 188

upsertAtomic 125example 123feature 33, 123

UPSERT keyword 33DML command 123EXECUTE command 130

UPSERT macro 131USE keyword

DML command 117use_field specification

DML command 117username specification

LOGON command 168USING (parms) specification

IMPORT command 150USING keyword

IMPORT command 150UTF-16

character sets 26UTF16

character sets 26utility variables

supported by Teradata TPump 62

V-v 75-V runtime parameter 50-v runtime parameter 49var 93var specification

SET command 183variables

date and timedate and time variables 60

row count 61substitution 62utility

supported by Teradata TPump 62VARTEXTvariable-length text record format 151verbose mode runtime parameter 49VERBOSE runtime parameter 49version numbers 3

WWHERE condition specification

DELETE statement 111IMPORT command 153UPDATE statement 188

Windowsstarting Teradata TPump 42syntax for invoking in batch mode 43

Zz/OS

syntax for invoking in batch mode 44zoned decimal format 25

Teradata Parallel Data Pump Reference 279

Page 280: Teradata Parallel Data Pump Reference - Teradata · PDF fileTeradata Parallel Data Pump Reference 3 Preface Purpose This book provides information about Teradata TPump, which is a

Index

280 Teradata Parallel Data Pump Reference