Teradata FastLoad
Reference
Release 13.10
B035-2411-020A
August 2010
The product or products described in this book are licensed products of Teradata Corporation or its affiliates.
Teradata, BYNET, DBC/1012, DecisionCast, DecisionFlow, DecisionPoint, Eye logo design, InfoWise, Meta Warehouse, MyCommerce,
SeeChain, SeeCommerce, SeeRisk, Teradata Decision Experts, Teradata Source Experts, WebAnalyst, and You’ve Never Seen Your Business
Like This Before are trademarks or registered trademarks of Teradata Corporation or its affiliates.
Adaptec and SCSISelect are trademarks or registered trademarks of Adaptec, Inc.
AMD Opteron and Opteron are trademarks of Advanced Micro Devices, Inc.
BakBone and NetVault are trademarks or registered trademarks of BakBone Software, Inc.
EMC, PowerPath, SRDF, and Symmetrix are registered trademarks of EMC Corporation.
GoldenGate is a trademark of GoldenGate Software, Inc.
Hewlett-Packard and HP are registered trademarks of Hewlett-Packard Company.
Intel, Pentium, and XEON are registered trademarks of Intel Corporation.
IBM, CICS, RACF, Tivoli, and z/OS are registered trademarks of International Business Machines Corporation.
Linux is a registered trademark of Linus Torvalds.
LSI and Engenio are registered trademarks of LSI Corporation.
Microsoft, Active Directory, Windows, Windows NT, and Windows Server are registered trademarks of Microsoft Corporation in the United
States and other countries.
Novell and SUSE are registered trademarks of Novell, Inc., in the United States and other countries.
QLogic and SANbox are trademarks or registered trademarks of QLogic Corporation.
SAS and SAS/C are trademarks or registered trademarks of SAS Institute Inc.
SPARC is a registered trademark of SPARC International, Inc.
Sun Microsystems, Solaris, Sun, and Sun Java are trademarks or registered trademarks of Sun Microsystems, Inc., in the United States and
other countries.
Symantec, NetBackup, and VERITAS are trademarks or registered trademarks of Symantec Corporation or its affiliates in the United States
and other countries.
Unicode is a collective membership mark and a service mark of Unicode, Inc.
UNIX is a registered trademark of The Open Group in the United States and other countries.
Other product and company names mentioned herein may be the trademarks of their respective owners.
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROVIDED ON AN “AS-IS” BASIS, WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR
NON-INFRINGEMENT. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO THE ABOVE EXCLUSION
MAY NOT APPLY TO YOU. IN NO EVENT WILL TERADATA CORPORATION BE LIABLE FOR ANY INDIRECT, DIRECT, SPECIAL, INCIDENTAL,
OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS OR LOST SAVINGS, EVEN IF EXPRESSLY ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.
The information contained in this document may contain references or cross-references to features, functions, products, or services that are
not announced or available in your country. Such references do not imply that Teradata Corporation intends to announce such features,
functions, products, or services in your country. Please consult your local Teradata Corporation representative for those features, functions,
products, or services available in your country.
Information contained in this document may contain technical inaccuracies or typographical errors. Information may be changed or updated
without notice. Teradata Corporation may also make improvements or changes in the products or services described in this information at
any time without notice.
To maintain the quality of our products and services, we would like your comments on the accuracy, clarity, organization, and value of this
document. Please e-mail: [email protected]
Any comments or materials (collectively referred to as “Feedback”) sent to Teradata Corporation will be deemed non-confidential. Teradata
Corporation will have no obligation of any kind with respect to Feedback and will be free to use, reproduce, disclose, exhibit, display, transform,
create derivative works of, and distribute the Feedback and derivative works thereof without limitation on a royalty-free basis. Further, Teradata
Corporation will be free to use any ideas, concepts, know-how, or techniques contained in such Feedback for any purpose whatsoever, including
developing, manufacturing, or marketing products or services incorporating Feedback.
Copyright © 1998-2010 by Teradata Corporation. All Rights Reserved.
Preface
Purpose
This book provides information about Teradata FastLoad (FastLoad), which is a Teradata®
Tools and Utilities product. Teradata Tools and Utilities is a group of products designed to
work with Teradata Database.
Teradata FastLoad is a command-driven utility that quickly loads large amounts of data to
empty tables in a Teradata Database. FastLoad uses multiple sessions to load data; however, it
loads data into only one table on a Teradata Database per job.
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 FastLoad 13.10
Note: See “SHOW VERSIONS” on page 150 to verify the Teradata FastLoad version
number.
For the most current information about supported releases, do the following:
1
Go to http://www.info.teradata.com/.
2
Click General Search under Online Publications.
3
Type 3119 in the Publication Product ID box.
4
Under Sort By, select Date.
5
Click Search.
6
Open the version of the Teradata Tools and Utilities ##.# Supported Platforms and Product
Versions spreadsheet associated with this release.
Teradata FastLoad Reference
3
Preface
Prerequisites
The spreadsheet includes supported Teradata Database versions, platforms, and product
release numbers.
Prerequisites
The following prerequisite knowledge is required for this product:
•
Familiarity with computer technology, relational database management systems, and
utilities that load and retrieve data
•
Teradata SQL
•
Teradata Database
Changes to This Book
The following changes were made to this book in support of the current release. Changes are
marked with change bars. For a complete list of changes to the product, see the Teradata Tools
and Utilities Release Definition associated with this release.
Date and Release
Description
August 2010 Teradata
Tools and Utilities
13.10
• Added FastLoad TMSM Integration
• Added support for VSAM on z/OS
• Added text stating only session level SET QUERY_BAND statements are
applicable to FastLoad
February 2010
Teradata Tools and
Utilities 13.10
• IBM C is used to develop FastLoad replacing SAS/C
Note: Fastload 13.10 supports INMODs written in SAS/C.
Teradata FastLoad
Reference
4
• FastLoad 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” on page 169
• Added information about special characters used in standard input
filenames
• Updated sample outputs for all Invocation Examples. See “Appendix
B Multifile Teradata FastLoad Job Script Examples” on page 161
• Added information on the new CONFIGERRORS parameter in
configuration files
• Added information to support RUN [FILE]
• Teradata FastLoad now supports online archive. For more information,
see Database Administration, B035-1093-mmyx
Teradata FastLoad Reference
Preface
Additional Information
Date and Release
Description
August 2009
Teradata Tools and
Utilities 13.00
• Added information on Loading No Primary Index (NoPI) tables in
chapter 2
• Updated FastLoad configuration file information
Teradata FastLoad
Reference
13.00
August 2008
Teradata Tools and
Utilities 13.00
Teradata FastLoad
Reference
13.00
•
•
•
•
•
•
Included information about not using a semicolon in object names
Added Appendix E, User-Defined-Types and User-Defined-Methods
Updated IBM terminology
Updated rules for delimiter characters
Corrected compile syntax diagrams
Added 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.
Type of Information
Description
Access to Information
Release overview
Use the Release Definition for the following
information:
1 Go to http://www.info.teradata.com/.
• Overview of all of the products in the
release
• Information received too late to be
included in the manuals
• Operating systems and Teradata
Database versions that are certified to
work with each product
• Version numbers of each product and
the documentation for each product
• Information about available training
and the support center
3 Type 2029 in the Publication Product ID box.
Late information
Teradata FastLoad Reference
2 Click General Search under Online Publications.
4 Click Search.
5 Select the appropriate Release Definition from
the search results.
5
Preface
Additional Information
Type of Information
Description
Access to 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 Click Data Warehousing under Online
Publications, Browse by Category.
3 Do one of the following:
• For a list of Teradata Tools and Utilities
documents, click Teradata Tools and Utilities,
and then select an item under Releases or
Products.
• Select a link to any of the data warehousing
publications categories listed.
Specific books related to Teradata FastLoad are as
follows:
• Basic Teradata Query Reference B035-2414mmyx
• Database Administration B035-1093-mmyx
• Database Design B035-1094-mmyx
• International Character Set Support B035-1132mmyx
•
•
•
•
Introduction to Teradata B035-1091-mmyx
Messages
Security Administration B035-1100-mmyx
SQL Data Definition Language B035-1144-mmyx
• SQL Data Manipulation Language B035-1146mmyx
• SQL Data Types and Literals B035-1143-mmyx
• SQL Fundamentals B035-1141-mmyx
• SQL External Routine Programming B035-1147mmyx
• Teradata Call-Level Interface Version 2 Reference
for Network-Attached Systems B035-2417-mmyx
• Teradata Call-Level Interface Version 2 Reference
for Channel-Attached Systems B035-2417-mmyx
• Teradata Dynamic Workload Manager User Guide
B035-2417-mmyx
• Teradata Tools and Utilities Access Module
Programmer Guide B035-2424-mmyx
• Teradata Tools and Utilities Access Module
Reference B035-2425-mmyx
• Teradata Tools and Utilities Command Summary
B035-2401-mmyx
• Utilities B035-1102-mmyx
6
Teradata FastLoad Reference
Preface
Additional Information
Type of Information
Description
Access to Information
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/.
Use the Teradata Information Products web
site to order printed versions of manuals.
1 Go to http://www.info.teradata.com/.
Ordering
information for
manuals
2 Click Data Warehousing under Online
Publications, Browse by Category.
3 Click CD-ROM List and Images.
2 Click How to Order under Print & CD
Publications.
3 Follow the ordering instructions.
General information
about Teradata
The Teradata home page provides links to
numerous sources of information about
Teradata. Links include:
1 Go to Teradata.com.
2 Select a link.
• Executive reports, case studies of
customer experiences with Teradata,
and thought leadership
• Technical information, solutions, and
expert advice
• Press releases, mentions, and media
resources
Teradata FastLoad Reference
7
Preface
Additional Information
8
Teradata FastLoad Reference
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Teradata FastLoad Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
What It Does. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How It Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17
17
18
18
Operating Features and Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Operating Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Data Transfer Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Data Conversion Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Checkpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Input Data Formats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Formatted Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Unformatted Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Binary Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Text Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Variable-length Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Unsupported Data Sets and Tapes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
20
21
21
22
23
23
24
Teradata FastLoad Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Teradata FastLoad Command Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Teradata SQL Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Teradata FastLoad Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Teradata FastLoad Reference
9
Table of Contents
Chapter 2:
Using Teradata FastLoad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33
Invoking Teradata FastLoad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33
File Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33
Interactive Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34
Batch Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34
Channel-Attached Runtime Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35
Network-Attached Runtime Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39
z/OS Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
UNIX and Windows Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46
Terminating Teradata FastLoad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47
Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47
Normal Termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47
Abort Termination. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48
Restart a Paused Teradata FastLoad Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48
After a Client System or Teradata FastLoad Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49
After a Database Overfill Condition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49
After a Teradata Database Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49
After an AP Reset Condition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
After an Unrecoverable Error Condition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
Restart Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51
Programming Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52
Teradata FastLoad Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52
Character Set Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54
Unicode Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56
ANSI/SQL DateTime Specifications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57
Checkpoint Tradeoffs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57
Checkpoint Support with Access Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58
Concurrent Load Utility Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58
Data Conversion Factors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58
Error Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59
Nonunique Index Sorts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
Duplicate Rows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
Range Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
Record Mode Load Anomaly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61
UNIX Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61
Restrictions and Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61
Loading No Primary Index Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
Conventions for Quotes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
10
Teradata FastLoad Reference
Table of Contents
INMOD and Notify Exit Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Programming Considerations for Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Programming Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Addressing Mode on z/OS Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Teradata FastLoad/INMOD Routine Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Teradata FastLoad/Notify Exit Routine Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Teradata FastLoad Sample INMOD Routines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating Custom INMOD Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
63
63
64
64
65
65
67
69
70
Teradata FastLoad Job Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Enter Teradata FastLoad Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Teradata FastLoad Job Script Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
71
71
71
71
Run Multifile Teradata FastLoad Jobs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Initiate the Teradata FastLoad Job and Loading the First Data Source . . . . . . . . . . . . . .
Restart the Teradata FastLoad Job and Loading the Second Data Source . . . . . . . . . . . .
Restart the Teradata FastLoad Job and Loading the Third Data Source. . . . . . . . . . . . . .
Terminate the Teradata FastLoad Job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Command Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
73
74
74
74
74
75
Handling Teradata FastLoad Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Teradata FastLoad Error Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Error Recording . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Error Table Formats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Correcting Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Procedure for Correcting Errors in the First Error Table. . . . . . . . . . . . . . . . . . . . . . . . . .
Procedure for Correcting Errors in the Second Error Table . . . . . . . . . . . . . . . . . . . . . . .
76
76
77
77
78
78
80
FastLoad TMSM Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Chapter 3:
Teradata FastLoad Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Syntax Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Object Name Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Geospatial Data Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
AXSMOD. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
BEGIN LOADING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
CLEAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
DATEFORM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
DEFINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
END LOADING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Teradata FastLoad Reference
11
Table of Contents
ERRLIMIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107
HELP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109
HELP TABLE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111
INSERT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113
LOGDATA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117
LOGMECH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118
LOGOFF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119
LOGON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121
NOTIFY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124
OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .129
QUIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .132
Completion Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .133
RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .134
Completion Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135
Completion Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135
RUN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .136
SESSIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .138
SET RECORD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .141
SET SESSION CHARSET. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146
SHOW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .148
SHOW VERSIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .150
SLEEP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151
TENACITY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .153
Appendix A:
How to Read Syntax Diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155
Syntax Diagram Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155
Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .157
Multiple Legitimate Phrases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .159
Sample Syntax Diagram. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160
Diagram Identifier . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160
Appendix B:
Multifile Teradata FastLoad Job Script Examples . . . . . . . . . . . . . .161
First Output File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161
Second Output File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .163
12
Teradata FastLoad Reference
Table of Contents
Third Output File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Appendix C:
INMOD and Notify Exit Routine Examples . . . . . . . . . . . . . . . . . . . . . . 169
z/OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
IBM C INMOD Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
UNIX OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
BLKEXIT.C Sample INMOD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
BLKEXITR.C Sample INMOD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
All Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Notify Exit Routine Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Appendix D:
Compile, Link, and Execute INMOD
and Notify Exit Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
z/OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
IBM C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
IBM C or C++ INMODs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
UNIX OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sun Solaris SPARC. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sun Solaris Opteron. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HP-UX PA RISC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HP-UX Itanium . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
z/Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
188
188
188
189
190
191
192
Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Appendix E:
User-Defined-Types
and User-Defined-Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
User-Defined-Types and User-Defined-Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
User-Defined-Types (UDTs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
User-Defined-Methods (UDMs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating UDTs with FastLoad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Inserting and Retrieving UDTs with Client Products. . . . . . . . . . . . . . . . . . . . . . . . . . . .
External Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Teradata FastLoad Reference
195
195
196
196
196
196
13
Table of Contents
Inserting UDTs with FastLoad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .197
Retrieving UDTs with FastLoad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .197
Retrieving UDT Metadata with FastLoad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .197
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .199
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .215
14
Teradata FastLoad Reference
List of Tables
Table 1: Formatted Record Field Descriptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Table 2: Unformatted Record Field Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Table 3: Binary Record Field Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Table 4: Teradata FastLoad Commands for Session Control . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Table 5: Teradata FastLoad Commands for Data Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Table 6: Teradata SQL Statements Supported in Teradata FastLoad. . . . . . . . . . . . . . . . . . . . 26
Table 7: FastLoad Data Sets/Files and Input/Output Devices. . . . . . . . . . . . . . . . . . . . . . . . . . 33
Table 8: Runtime Parameters (Channel-Attached Systems). . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Table 9: Runtime Parameters (Network-Attached Systems) . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Table 10: Character Sets Supported by Teradata FastLoad . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Table 11: Site-Defined Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Table 12: Range Constraint Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Table 13: Programming Languages Supported by Platform and Type of User-Developed
Routine. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Table 14: Programming Structures for Teradata FastLoad/INMOD Communication . . . . . 65
Table 15: Entry Points for INMOD Routines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Table 16: Teradata FastLoad--to--INMOD Interface Status Codes . . . . . . . . . . . . . . . . . . . . . 66
Table 17: INMOD-to-Teradata FastLoad Interface Status Codes . . . . . . . . . . . . . . . . . . . . . . 66
Table 18: Events Passed to the Notify Exit Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Table 19: Sample INMOD Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Table 20: FastLoad Entering Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Table 21: Teradata FastLoad Terminating Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Table 22: Error Conditions that Cause Teradata Database to Reject an Input Data Record . 76
Table 23: Error Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Table 24: errortname1 Columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Table 25: Usage Notes for AXSMOD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Table 26: Usage Note for BEGIN LOADING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Table 27: Usage Notes for DATEFORM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Table 28: Input Length and Field Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Table 29: Limitations by Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Table 30: Usage Notes for END LOADING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Table 31: RECORD Completion Message Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Teradata FastLoad Reference
15
List of Tables
Table 32: Usage Notes for ERRLIMIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107
Table 33: Usage Notes for HELP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109
Table 34: Usage Notes for HELP TABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111
Table 35: Usage Notes for INSERT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114
Table 36: LOGOFF Command Usage Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119
Table 37: LOGOFF Command Completion Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120
Table 38: Usage Notes for LOGON. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122
Table 39: Events that Create Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .126
Table 40: Usage Notes for NOTIFY. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .126
Table 41: NOTIFY Command Message Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .127
Table 42: OS Command Examples on a UNIX Client System . . . . . . . . . . . . . . . . . . . . . . . . .129
Table 43: Example OS Command on Windows Client System . . . . . . . . . . . . . . . . . . . . . . . .130
Table 44: Example Procedure for OS Command on z/OS Client System . . . . . . . . . . . . . . . .131
Table 45: Usage Notes for QUIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .132
Table 46: Usage Notes for RECORD. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .134
Table 47: Usage Notes for Run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137
Table 48: Usage Notes for SESSIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139
Table 49: Usage Notes for SET SESSION CHARSET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146
Table 50: Usage Notes for SLEEP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152
Table 51: Usage Notes for TENACITY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .154
16
Teradata FastLoad Reference
CHAPTER 1
Overview
This chapter provides an introductory overview of the Teradata FastLoad utility. Topics
include:
•
Teradata FastLoad Utility
•
Operating Features and Capabilities
•
Input Data Formats
•
Teradata FastLoad Commands
•
Teradata FastLoad Example
Teradata FastLoad Utility
This section describes Teradata FastLoad features and operation.
Description
Teradata FastLoad is a command-driven utility which can be used to quickly load large
amounts of data in an empty table on a Teradata Database.
Data can be loaded from:
•
Disk or tape files on a channel-attached client system
•
Input files on a network-attached workstation
•
Special input module (INMOD) routines written to select, validate, and preprocess input
data
•
Any other device providing properly formatted source data
Teradata FastLoad uses multiple sessions to load data. However, it loads data into only one
table on a Teradata Database per job. To load data into more than one table in the Teradata
Database, multiple Teradata FastLoad jobs must be submitted—one for each table.
Note: Full tape support is not available for any function in Teradata FastLoad for networkattached client systems. To import data from a tape, write a custom access module that
interfaces with the tape device. For information about how to write a custom access module,
refer to the Teradata Tools and Utilities Access Module Programmer Guide.
Teradata FastLoad Reference
17
Chapter 1: Overview
Operating Features and Capabilities
What It Does
When Teradata FastLoad is invoked, the utility executes the Teradata FastLoad commands
and Teradata SQL statements in the Teradata FastLoad job script. These direct Teradata
FastLoad to:
1
Log on to the Teradata Database for a specified number of sessions, using username,
password, and tdpid/acctid information.
2
Load the input data into the Teradata FastLoad table on the Teradata Database.
3
Log off from the Teradata Database.
4
If the load operation was successful, return the following information about the Teradata
FastLoad operation and then terminate:
•
Total number of records read, skipped, and sent to the Teradata Database
•
Number of errors posted to the Teradata FastLoad error tables
•
Number of inserts applied
•
Number of duplicate rows
How It Works
Teradata FastLoad processes a series of Teradata FastLoad commands and Teradata SQL
statements entered either interactively or in batch mode.
Use the Teradata FastLoad commands for session control and data handling of the data
transfers. The Teradata SQL statements create, maintain, and drop tables on the Teradata
Database.
During a load operation, Teradata FastLoad inserts the data from each record of the data
source into one row of the table on a Teradata Database. The table on the Teradata Database
receiving the data must be empty and have no defined secondary indexes.
Note: Teradata FastLoad does not load duplicate rows from the data source to the Teradata
Database. (A duplicate row is one in which every field contains the exact same data as the
fields of an existing row.) This is true even for MULTISET tables. To load duplicate rows in a
MULTISET table, use MultiLoad.
Operating Features and Capabilities
This section describes the operating modes and character sets for running Teradata FastLoad.
For specific information on supported operating systems, refer to Teradata Tools and Utilities
##.##.## Supported and Certified Versions, B035-3119-mmyx. This spreadsheet shows version
numbers and platform information for all Teradata Tools and Utilities products and is
available at http://www.info.teradata.com/.
Caution:
18
Some system configurations running Teradata FastLoad on a network-attached workstation
that has a UNIX® operating system with the data set mounted on a Network File System
(NFS) can produce errors and failed or incomplete data transfer operations. Do not use
Teradata FastLoad with an NFS-mounted data set.
Teradata FastLoad Reference
Chapter 1: Overview
Data Transfer Capabilities
Operating Modes
Teradata FastLoad runs in the following operating modes:
•
Interactive
•
Batch
Character Sets
Teradata FastLoad supports Latin, Chinese, Japanese, and Korean character sets for networkattached and channel-attached configurations. For additional information about characterset support and definition, see “Character Set Specification” on page 54.
Teradata FastLoad also supports UTF-16 (workstation only) and UTF-8 character sets. For
additional information, see “Unicode Character Sets” on page 56.
Data Transfer Capabilities
This section covers Teradata FastLoad’s data transfer capabilities.
On network-attached workstations, Teradata FastLoad uses the TCP/IP network protocol for
all data transfer operations.
On channel-attached systems, Teradata FastLoad transfers data as either:
•
A multi-volume data set or file
•
A number of single-volume data sets or files in separate Teradata FastLoad jobs
Serial Teradata FastLoad operations can be restarted by loading the next tape in a series
instead of beginning with the first tape in a set.
In either case, Teradata FastLoad:
•
Uses multiple Teradata sessions, at one session per AMP, to transfer data
•
Transfers multiple rows of data within a single message
Also, in either case, until the Teradata FastLoad job is completed and the data loaded into the
Teradata FastLoad table:
•
There is no journaling or fallback data
•
The secondary indexes cannot be defined
Data Conversion Capabilities
Teradata FastLoad 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
FastLoad table on the Teradata Database. If, for example, an input field with numeric type
data is targeted for a column with a character data type specification, Teradata FastLoad can
change the input data specification to character before inserting it into the table.
The types of data conversions which can be specified are:
Teradata FastLoad Reference
19
Chapter 1: Overview
Input Data Formats
•
Numeric-to-numeric (for example integer-to-decimal)
•
Character-to-numeric
•
Character-to-date
•
Date-to-character
Note: Redundant conversions, like integer-to-integer, are legal and necessary to support the
zoned decimal format. For more information about the zoned decimal format, see the
Database Design and SQL Data Types and Literals documentation.
Use the datatype specification of the DEFINE command to convert input data to a different
type before inserting it into the Teradata FastLoad table on the Teradata Database.
For details on data types and data conversions, see SQL Data Types and Literals.
Checkpoints
Checkpoints are entries posted to a restart log table at regular intervals during the Teradata
FastLoad data transfer operation. If processing stops while a Teradata FastLoad job is running,
the job can be restarted at the most recent checkpoint.
If, for example, 1,000,000 records are being loaded into a table and they have specified
checkpoints every 50,000 records, Teradata FastLoad pauses and posts an entry to the restart
log table whenever multiples of 50,000 records have been successfully sent to the 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.
Enable the checkpoint function by specifying a checkpoint value in the BEGIN LOADING
command.
Input Data Formats
This section covers the data formats supported by Teradata FastLoad as well as those data sets
and tapes not supported by the utility.
Input data is the raw data that Teradata FastLoad loads from the client system or workstation
to the Teradata Database. The input data can be either formatted, unformatted, variablelength text or of specific file types, depending on the configuration of the client system.
For network-attached configurations, Teradata FastLoad supports the following data formats:
•
Formatted
•
Unformatted
•
Binary
•
Text
•
Variable-length text
For channel-attached configurations, Teradata FastLoad supports data sets and tape files with
the following record format (RECFM) attributes:
20
Teradata FastLoad Reference
Chapter 1: Overview
Input Data Formats
•
Data sets and tape files with the following record format (RECFM) attributes:
•
F (fixed)
•
FB (fixed block)
•
V (variable)
•
VB (variable block)
•
VBS (variable block, spanned)
Formatted Data
Formatted data on network-attached systems is input data that conforms to the format of data
from a Teradata Database source, such as a BTEQ EXPORT file.
Each record has:
•
A two-byte data length field
•
Optionally, a variable-length indicator bytes field
•
A variable-length input data field
•
A one-byte end-of-record delimiter field
Table 1 lists the formatted record field descriptions.
Table 1: Formatted Record Field Descriptions
Input Record Field Description
Data length
A two-byte field indicating the total length of the record, in bytes, excluding the
first two bytes (this field), and the last byte (the end-of-record field)
The data length must be specified as an explicit value, not an ASCII value. For a
data length of one byte, for example, the specification must be hexadecimal 01. It
cannot be hexadecimal 31, or the ASCII equivalent of the number 1.
Indicator bytes
Optional bytes to indicate null data
Input data
The actual input data for rows in the Teradata FastLoad table.
The input data stream always starts at either:
• The third byte of the record, if there are no optional indicator bytes
• Immediately after the last optional indicator byte
The length of the input data field, less any optional indicator bytes, is as specified
in the first two bytes.
End-of-record
The end-of-record delimiter field can be either of two hexadecimal values:
• 0A (carriage return)
• 0D (line feed)
Unformatted Data
Unformatted data on network-attached systems is data that does not conform to the format of
data from a Teradata Database source. It may, however, originate from a Teradata Database
source, or from other sources, such as a Fortran file.
Teradata FastLoad Reference
21
Chapter 1: Overview
Input Data Formats
Unformatted records include:
•
Optionally, a variable-length indicator bytes field
•
A variable-length data field
Unformatted records have no end-of-record delimiter field.
Table 2 lists the unformatted record field descriptions.
Table 2: Unformatted Record Field Descriptions
Input Record Field
Description
Indicator bytes
Optional bytes to indicate null data
Input data
Raw data to be loaded into the Teradata FastLoad table on the Teradata
Database
Note: If the network-attached system configuration includes both UNIX and Windows
operating system platforms, ensure that the Teradata FastLoad job scripts accommodate the
different ways that each platform specifies new lines in ASCII text files.
Windows platforms use a two-character sequence to signify a new line—carriage return + line
feed. UNIX platforms use a single new-line character to perform the same function.
When loading unformatted ASCII files from a network-attached system, always ensure that
the DEFINE command properly identifies the format of the new-line function for the source
platform:
•
One character for UNIX platforms
•
Two characters for Windows platforms
Binary Data
The binary data format is a 2-byte integer, n, followed by n bytes of data. Binary data format is
similar to formatted data format, except that there is no end-of-record marker.
Each record has:
•
A two-byte data length field
•
Optionally, a variable-length indicator bytes field
•
A variable-length input data field
Table 3 lists the unformatted binary record field descriptions.
22
Teradata FastLoad Reference
Chapter 1: Overview
Input Data Formats
Table 3: Binary Record Field Descriptions
Input Record Field Description
Data length
A two-byte field indicating the total length of the record, in bytes, excluding the
first two bytes (this field)
The data length must be specified as an explicit value, not an ASCII value. For a
data length of one byte, for example, the specification must be hexadecimal 01. It
cannot be hexadecimal 31, or the ASCII equivalent of the number 1.
Indicator bytes
Optional bytes to indicate null data
Input data
The actual input data for rows in the Teradata FastLoad table.
The input data stream always starts at either:
• The third byte of the record, if there are no optional indicator bytes
or
• Immediately after the last optional indicator byte
The length of the input data field, less any optional indicator bytes, is as specified
in the first two bytes.
Text Data
TEXT specifies that each record consists of an arbitrary number of characters in the client
session character set, followed by an end-of-record marker, which is:
•
On UNIX platforms, the newline character (identified in Unicode as LINE FEED
U+000A)
•
On Windows platforms, the two-character sequence carriage return followed by line feed
(identified in Unicode as CARRIAGE RETURN U+000D and LINE FEED U+000A,
respectively)
For client session character sets other than UTF16, the end-of-record marker byte sequence is:
•
On UNIX platforms, X'0A'
•
On Windows platforms, X'0D0A'
For the UTF16 client session character set (in which each character is encoded in two bytes),
the end-of-record marker byte sequence is:
•
On big endian UNIX platforms, X'000A'
•
On little endian UNIX platforms, X'0A00'
•
On Windows platforms, X'0D000A00'
Note: TEXT format should only be specified for character data. Do not specify TEXT format
for binary data, such as, INTEGER, BYTEINT, PERIOD, and other binary data. Depending
on the actual byte values of the binary data, unexpected results may occur.
Variable-length Text
Variable-length text on a network-attached system is ASCII text data consisting of variablelength fields and records, with each field separated by a delimiter character.
Teradata FastLoad Reference
23
Chapter 1: Overview
Teradata FastLoad Commands
When loading variable-length text records from a network-attached system, use the SET
RECORD command to specify the delimiter character.
Unsupported Data Sets and Tapes
Teradata FastLoad does not support the following types of data sets and tapes on channelattached systems:
•
Concatenated data sets
•
Nonlabel (NL) and bypass label (BPL) tapes
Teradata FastLoad Commands
Teradata FastLoad accepts both Teradata FastLoad commands and a subset of Teradata SQL
statements. The Teradata FastLoad commands perform session control and data-handling
activities. The Teradata SQL statements define and manipulate the data stored in the Teradata
Database. This section provides a summary of the Teradata FastLoad commands and Teradata
SQL statements.
Teradata FastLoad Command Summary
The Teradata FastLoad commands perform two types of activities:
•
Session control—Session control commands begin and end Teradata FastLoad sessions
and provide online information about a particular Teradata FastLoad operation.
and
•
Data handling—Data handling commands establish and define a Teradata FastLoad
operation.
Table 4 and Table 5 summarize the Teradata FastLoad commands that perform these
activities. For a detailed description of each Teradata FastLoad command, see Chapter 3:
“Teradata FastLoad Commands.”
Table 4: Teradata FastLoad Commands for Session Control
Command Name
Function
HELP
Lists Teradata FastLoad commands and options
HELP TABLE
Creates a list of field names which can be used with the INSERT statement
LOGOFF
Ends Teradata FastLoad sessions and terminates Teradata FastLoad
QUIT
24
LOGON
Begins one or more Teradata FastLoad sessions
NOTIFY
Specifies a user exit or action to be performed when certain significant
events occur
OS
Enters client operating system commands
Teradata FastLoad Reference
Chapter 1: Overview
Teradata FastLoad Commands
Table 4: Teradata FastLoad Commands for Session Control (continued)
Command Name
Function
SESSIONS
Specifies the number of Teradata FastLoad sessions logged on with a
LOGON command and, optionally, the minimum number of sessions
required to run the job. If the database system (DBS) supports Teradata
Active System Management (TASM), the number of sessions to run the jobs
is determined by the DBS setup rules. Therefore, the SESSIONS command
has no effect. For more information, see Database Administration, B0351093-mmyx.
SHOW
Shows the current field/file definitions established by DEFINE commands
SHOW VERSIONS
Shows the current level of all Teradata FastLoad software modules
SLEEP
Specifies the number of minutes that Teradata FastLoad pauses before
retrying a logon operation
TENACITY
Specifies the number of hours that Teradata FastLoad continues trying to
log on when the maximum number of load jobs is already running on the
Teradata Database
Table 5: Teradata FastLoad Commands for Data Handling
Teradata FastLoad
Command
Function
AXSMOD
Specifies the name and initialization string for a shared object file that loads
data from a file on network-attached client systems
BEGIN LOADING
Identifies the tables used in the Teradata FastLoad operation and, optionally,
specifies when checkpoints are taken or if the user supplies indicator data
CLEAR
Cancels the current DEFINE command specifications
DATEFORM
Specifies the form of the DATE data type specifications for the Teradata
FastLoad job
DEFINE
Describes each field of an input data source record and specifies the name of
the input data source or INMOD routine
END LOADING
Informs the Teradata Database that all input data has been sent
ERRLIMIT
Limits the number of errors detected during the loading phase of a Teradata
FastLoad job
Processing stops when the limit is reached.
RECORD
Specifies the number of a record in an input data source at which Teradata
FastLoad begins to read data and/or the number of the last record to be read
RUN
Invokes the specified external source as the current source of commands and
statements
Teradata FastLoad Reference
25
Chapter 1: Overview
Teradata FastLoad Commands
Table 5: Teradata FastLoad Commands for Data Handling (continued)
Teradata FastLoad
Command
Function
SET RECORD
Specifies that the input data records are either:
• Formatted
• Unformatted
• Binary
• Text
• Variable-length text
Note: The SET RECORD command applies only to network-attached
systems.
SET SESSION
CHARSET
Specifies which character set is in effect during a specific Teradata FastLoad
invocation
Note: The SET SESSION CHARSET command applies only to networkattached systems.
Note: The SET RETRY command is obsolete and ignored by Teradata FastLoad. For a
description of the tenacity function, see “Invoking Teradata FastLoad” on page 33 and
“TENACITY” on page 153.
Teradata SQL Statements
Teradata SQL statements define and manipulate the data stored in the Teradata Database.
Table 6 summarizes the Teradata SQL statements supported by Teradata FastLoad
Teradata FastLoad supports only the Teradata SQL statements listed in Table 6. To use other
Teradata SQL statements, Teradata FastLoad must first be exited, and the statEments entered
from another application, such as Basic Teradata Query (BTEQ).
Table 6: Teradata SQL Statements Supported in Teradata FastLoad
Teradata SQL Statement
Function
CREATE TABLE
Defines the columns, index, and other qualities of a table
DATABASE
Changes the default database
DELETE
Deletes rows from a table
DROP TABLE
Removes a table and all of its rows from a database
INSERT
Inserts rows into a table
SET QUERY_BAND...FOR
SESSION
Allows a set of name-value pairs to be defined by the user and/
or middle tier application so they can be customized to each
application’s unique needs at the session level.
Note: Only SET QUERY_BAND...FOR SESSION is valid.
Although Teradata Database does not return error for SET
QUERY_BAND...FOR TRANSACTION but it’s invalid.
26
Teradata FastLoad Reference
Chapter 1: Overview
Teradata FastLoad Example
For syntax and a complete description of each Teradata SQL statement, see SQL Data
Definition Language and SQL Data Manipulation Language.
The Teradata FastLoad version of the INSERT statement includes a special “wildcard” table
name specification that is not supported by the Teradata Database. For a complete description
of the Teradata FastLoad version of the INSERT statement, see “INSERT” on page 113.
Teradata FastLoad Example
This section provides an example of a small Teradata FastLoad job which can be quickly set up
and run. The example shows how to:
•
Create a data file that will be used as the input source for a Teradata FastLoad job
•
Use a Teradata FastLoad job script to load data into a newly created table
•
Select data from the table to verify the load task
Note: This example is for UNIX or Windows operating systems on a network-attached client
system. Refer to the following appendixes for additional UNIX and Windows examples, and
for z/OS examples on channel-attached systems:
•
Appendix B: “Multifile Teradata FastLoad Job Script Examples”
•
Appendix C: “INMOD and Notify Exit Routine Examples”
•
Appendix D: “Compile, Link, and Execute INMOD and Notify Exit Routines”
Dropping the Employee Table
The table in this example is named Employee. Use the Teradata SQL DROP TABLE command
to delete any existing version of the Employee table from the database:
bteq
.logon tdpid/username,password
DROP TABLE employee;
.quit
Creating the Source Data File
Create and save a six-record text file named insert.input:
|10021
|10001
|10002
|10028
|10029
|10023
|Brown, Jo
|Jones, Bill
|Smith, Jim
|Lee, Sandra
|Berg, Andy
|Ayer, John
|200|2312|Development
|100|5376|President
|100|4912|Sales
|200|5844|Support
|200|2312|Test
|300|4432|Accounting
|63000.00
|83000.00
|73000.00
|77000.00
|67000.00
|52000.00
|20|Jan
|15|Jan
|10|Jan
| 4|Jan
|10|Jan
| 8|Jan
01
01
01
01
01
01
1955|F|
1960|M|
1970|M|
1971|F|
1967|M|
1965|M|
|M|16|
|M|14|
|M|13|
|M|18|
|M|15|
|M|13|
0|
0|
1|
0|
0|
0|
Use this file as the input source for a Teradata FastLoad job.
Note: The file example uses field delimiter characters ( | ) to help visualize each field—it is not
required to use them in the file.
Teradata FastLoad Reference
27
Chapter 1: Overview
Teradata FastLoad Example
Writing the Teradata FastLoad Job Script
Create and save a Teradata FastLoad job script file named flinsert.fastload that loads the sixrecord insert.data file into the Employee table:
sessions 2;
errlimit 25;
logon tdpid/username,password;
CREATE TABLE employee (
EmpNo SMALLINT FORMAT ‘9(5)’ BETWEEN 10001 AND 32001 NOT NULL,
Name VARCHAR(12),
DeptNo SMALLINT FORMAT ‘999’ BETWEEN 100 AND 900 ,
PhoneNo SMALLINT FORMAT ‘9999’ BETWEEN 1000 AND 9999,
JobTitle VARCHAR(12),
Salary DECIMAL(8,2) FORMAT ‘ZZZ,ZZ9.99’ BETWEEN 1.00 AND 999000.00 ,
YrsExp BYTEINT FORMAT ‘Z9’ BETWEEN -99 AND 99 ,
DOB DATE FORMAT ‘MMMbDDbYYYY’,
Sex CHAR(1) UPPERCASE,
Race CHAR(1) UPPERCASE,
MStat CHAR(1) UPPERCASE,
EdLev BYTEINT FORMAT ‘Z9’ BETWEEN 0 AND 22,
HCap BYTEINT FORMAT ‘Z9’ BETWEEN -99 AND 99 )
UNIQUE PRIMARY INDEX( EmpNo ) ;
set record unformatted;
define
delim0(char(1)),
EmpNo(char(9)), delim1(char(1)),
Name(char(12)), delim2(char(1)),
DeptNo(char(3)), delim3(char(1)),
PhoneNo(char(4)), delim4(char(1)),
JobTitle(char(12)), delim5(char(1)),
Salary(char(9)), delim6(char(1)),
YrsExp(char(2)), delim7(char(1)),
DOB(char(11)), delim8(char(1)),
Sex(char(1)), delim9(char(1)),
Race(char(1)), delim10(char(1)),
MStat(char(1)), delim11(char(1)),
EdLev(char(2)), delim12(char(1)),
HCap(char(2)), delim13(char(1)),
newlinechar(char(1))
file=insert.input;
show;
begin loading employee errorfiles error_1, error_2;
insert into employee (
:EmpNo,
:Name,
:DeptNo,
:PhoneNo,
:JobTitle,
:Salary,
:YrsExp,
:DOB,
:Sex,
:Race,
:MStat,
:EdLev,
:HCap
);
28
Teradata FastLoad Reference
Chapter 1: Overview
Teradata FastLoad Example
end loading;
logoff;
Comments
1
For syntax and descriptions of the following commands, see Chapter 3: “Teradata
FastLoad Commands”:
•
•
•
•
•
2
SESSIONS
ERRLIMIT
LOGON
SET RECORD
DEFINE
•
•
•
•
•
SHOW
BEGIN LOADING
INSERT
END LOADING
LOGOFF
The CREATE TABLE statement creates a new table on the Teradata Database:
•
Named employee
•
With 13 columns:
•
•
•
•
•
•
•
•
EmpNo
Name
DeptNo
PhoneNo
JobTitle
Salary
YrsExp
•
•
•
•
•
•
DOB
Sex
Race
MStat
EdLev
HCap
Indexed by EmpNo (UNIQUE PRIMARY)
For syntax and a complete description of the Teradata SQL CREATE TABLE statement,
see SQL Data Definition Language and SQL Data Manipulation Language.
3
The DEFINE command specifies each field of the data records that will be sent to the
Teradata Database. (The insert.input data file was created in the “Creating the Source Data
File” subsection.)
Each field definition provides the name and data type description for each field in the
input data records. In making the field declarations, note that the one character delimiter
fields are optional. They do not need to be used in the example.
4
The BEGIN LOADING command specifies the error files and starts the Teradata FastLoad
job, using the insert.input file and the Employee table.
Running the Teradata FastLoad Job
Use the following command to invoke Teradata FastLoad and run the flinsert.fastload job
script:
fastload < flinsert.fastload
Note that the redirection mechanism is required for Teradata FastLoad job scripts on
network-attached client systems.
Teradata FastLoad Reference
29
Chapter 1: Overview
Teradata FastLoad Example
Verifying the Import Task
Use the following BTEQ commands to verify the Teradata FastLoad job by selecting newly
loaded data from the Employee table:
bteq
.logon tdpid/username,password
.width 120
select * from employee where salary > 65000.00;
.quit
The response indicates that the Employee table was successfully loaded with the data from the
insert.input file:
*** Query completed. 4 rows found. 13 columns returned.
*** Total elapsed time was 6 seconds.
EmpNo
----10028
10001
10002
10029
Name
DeptNo PhoneNo
------------ ------ ------Lee, Sandra
200
5844
Jones, Bill
100
5376
Smith, Jim
100
4912
Berg, Andy
200
2312
JobTitle
--------Support
Preside
Sales
Test
Salary YrsExp
--------- -----77,000.00
4
83,000.00
15
73,000.00
10
67,000.00
10
DOB Sex Race MStat
----------- --- ---- ----JAN 01 1971 F
M
JAN 01 1960 M
M
JAN 01 1970 M
M
JAN 01 1967 M
M
EdLev
----18
14
13
15
HCap
---0
0
1
0
Other Alternatives
The Teradata FastLoad example is a simple, straightforward exercise can be used to quickly
create a job script and run Teradata FastLoad. The following information explains some of the
more significant functional alternatives that Teradata FastLoad provides, and provides
references to where they are described in greater detail.
Channel-Attached Client Systems
The Teradata FastLoad example assumes UNIX or Windows OS is the operating system on a
network-attached client system.
To run the example using z/OS on a channel-attached client system, use the standard [z/OS
JCL control statements (DD) to allocate and create the Teradata FastLoad data sets or files
before invoking the utility.
For more information about invoking Teradata FastLoad on channel-attached client systems,
see “Invoking Teradata FastLoad” on page 33.
MultiLoad Utility
The Teradata FastLoad example shows a very simple Teradata FastLoad job—loading a very
small amount of data into an empty table.
MultiLoad could have been used to perform the same task, but the job would have run much
more slowly—Teradata FastLoad works only on empty tables. MultiLoad can be used to:
30
•
Insert additional data rows into existing tables
•
Update individual rows of existing tables
•
Delete individual rows from existing tables
•
Load data into multiple tables
•
Load data into MULTISET tables
Teradata FastLoad Reference
Chapter 1: Overview
Teradata FastLoad Example
•
Load data into tables with nonunique secondary indexes
Input File Formats
The format of the input data source for the Teradata FastLoad example (insert.input) is
UNFORMATTED, as specified by the SET RECORD command.
Teradata FastLoad also supports input data source files with the following formats:
•
FORMATTED
•
BINARY
•
TEXT
•
VARTEXT
For descriptions of all the supported input file formats, see “SET RECORD” on page 141.
INMOD Routines
In the Teradata FastLoad example, the utility reads the input data records directly from the
specified source file (insert.input).
An alternative would be to write an INMOD routine that Teradata FastLoad could call to
obtain input records.
The INMOD routine, for example, could:
•
Read and preprocess records from a file
•
Generate data records
•
Read data from other database systems
•
Validate data records
•
Convert data record fields
In this case, use the optional INMOD name specification of the DEFINE command to identify
the name of the INMOD routine.
For more information about using INMOD routines, see “INMOD and Notify Exit Routines”
on page 63 and the INMOD name option in “DEFINE” on page 93.
Teradata FastLoad Reference
31
Chapter 1: Overview
Teradata FastLoad Example
32
Teradata FastLoad Reference
CHAPTER 2
Using Teradata FastLoad
This chapter provides detailed information about using the Teradata FastLoad utility. Topics
include:
•
Invoking Teradata FastLoad
•
Terminating Teradata FastLoad
•
Restart a Paused Teradata FastLoad Job
•
Programming Considerations
•
INMOD and Notify Exit Routines
•
Teradata FastLoad Job Scripts
•
Run Multifile Teradata FastLoad Jobs
•
Handling Teradata FastLoad Errors
•
FastLoad TMSM Integration
Invoking Teradata FastLoad
This section describes invocation parameters and other factors related to starting and
terminating Teradata FastLoad.
File Requirements
In addition to the input data source, Teradata FastLoad accesses four different data sets/files
or input/output devices. Table 7 lists the FastLoad data sets/files and input/output devices.
Table 7: FastLoad Data Sets/Files and Input/Output Devices
Data Set/File or Device
Provides
standard input
Teradata FastLoad commands and Teradata SQL statements that
make up a Teradata FastLoad job
standard output
Destination for Teradata FastLoad output responses and messages
standard error
Destination for Teradata FastLoad error messages
configuration
Optional specification of Teradata FastLoad utility default values
When running Teradata FastLoad in interactive mode, the terminal keyboard functions as the
standard input device and the display screen is the standard output/error device.
Teradata FastLoad Reference
33
Chapter 2: Using Teradata FastLoad
Invoking Teradata FastLoad
When running Teradata FastLoad in batch mode, a data set or file name must be specified for
each of these functions. The method of doing this varies, depending on the configuration of
your client system:
•
On network-attached client systems, use the standard redirection mechanism to specify
the Teradata FastLoad files when invoking the utility.
•
On channel-attached client systems, use standard z/OS JCL control commands to allocate
and create the Teradata FastLoad data sets or files before invoking the utility.
Interactive Mode
To invoke Teradata FastLoad in interactive mode, enter fastload at the system command
prompt:
fastload
Teradata FastLoad displays the following message to begin an interactive session:
===================================================================
=
=
=
FASTLOAD UTILITY
VERSION 13.10.00.000
=
=
PLATFORM SOLARIS/SPARC
=
=
=
===================================================================
===================================================================
=
=
=
Copyright 1984-2010, Teradata Corporation.
=
=
ALL RIGHTS RESERVED.
=
=
=
===================================================================
Batch Mode
This section covers invoking Teradata FastLoad in batch mode on network-attached and
client-attached systems.
Batch Mode on Network-Attached Client Systems
Refer to the runtime parameter descriptions in Table 9 on page 39 and use the following
syntax to invoke Teradata FastLoad in batch mode on network-attached client systems:
34
Teradata FastLoad Reference
Chapter 2: Using Teradata FastLoad
Invoking Teradata FastLoad
fastload
-b kilobytes
< infilename
> outfilename
-c character-set-name
-e filename
-M max-sessions
-N min-sessions
-r outputrate
RATE=outputrate
-s minutes
-t hours
-v
-y
-i scriptencoding
-u outputencoding
-V
2411F007
Batch Mode on Channel-Attached z/OS Client Systems
Refer to the runtime parameter descriptions in Table 8 on page 36, and use the following
syntax to invoke Teradata FastLoad in batch mode on channel-attached z/OS client systems:
// EXEC TDSFAST
,
,FDLOPT= '
BUFSIZE=kilobytes
'
CHARSET=character-set-name
ERRLOG=filename
MAXSESS=max-sessions
MINSESS=min-sessions
RATE =outputrate
SLEEP=minutes
TENACITY=hours
VERBOSE
RVERSION
-r outputrate
2411D008
Channel-Attached Runtime Parameters
Table 8 describes the runtime parameters used by Teradata FastLoad.
Using these Teradata FastLoad runtime parameters will override configuration parameter
settings.
Teradata FastLoad Reference
35
Chapter 2: Using Teradata FastLoad
Invoking Teradata FastLoad
Table 8: Runtime Parameters (Channel-Attached Systems)
Parameter
Description
BUFSIZE=
kilobytes
Output buffer size specification, where kilobytes is the size of
the output buffer, in kilobytes, that will be used for Teradata
FastLoad messages to the Teradata Database
The output buffer size and the size of the rows in the Teradata
FastLoad table determine the maximum number of rows that
can be included in each message to the Teradata Database. A
larger buffer size reduces processing overhead by including
more data in each message.
The default buffer size is also the maximum size allowed—63
KB. If a value greater than 63 KB is specified, Teradata
FastLoad:
• Responds with a warning message
• Resets the buffer size back to the default value
• Continues with the Teradata FastLoad job
36
Teradata FastLoad Reference
Chapter 2: Using Teradata FastLoad
Invoking Teradata FastLoad
Table 8: Runtime Parameters (Channel-Attached Systems) (continued)
Parameter
Description
CHARSET= character-set-name
A character set specification remains in effect for the entire
Teradata FastLoad job, even if the Teradata Database server
resets, causing the Teradata FastLoad job to be restarted.
Caution:
The character set specification does not remain in
effect if the client system fails, or if the Teradata
FastLoad job is cancelled. In these cases, when the
job is resubmitted, he same character set
specification that was used on the initial job must be
used. 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.
When a particular character set is specified, the identifiers and
data in that character set can be specified, thus affecting how
the data is loaded into the Teradata FastLoad table.
If a character set specification is not entered, the default is
whatever character set that is specified for the Teradata
Database whenever Teradata FastLoad was invoked.
The order in which the character set is determined for a
Teradata FastLoad job is as follows:
• User-specified by either a runtime parameter on channelattached systems or a SET SESSION CHARSET command
on network-attached systems
• When using UTF-8 client character set on the mainframe,
the client character set name needs to be specified by the
runtime parameter (for example, CHARSET=UTF-8).
UTF8 is also a valid value.
• System Parameter Block (SPB) specified by either the
HSHSPB on channel-attached systems or the clispb.dat file
on network-attached systems
• Teradata Database default, determined by a query from
Teradata FastLoad
Note: On IBM z/OS, the job script must be in Teradata
EBCDIC when using UTF-8 client character set. Teradata
FastLoad translates commands in the job script from Teradata
EBCDIC to UTF-8 during the load. Be sure to examine the
definition in the International Character Set Support manual to
determine the code points of any 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 in Appendix E of
International Character Set Support manual.
Teradata FastLoad Reference
37
Chapter 2: Using Teradata FastLoad
Invoking Teradata FastLoad
Table 8: Runtime Parameters (Channel-Attached Systems) (continued)
Parameter
Description
ERRORLOG= filename
Alternate file specification for Teradata FastLoad error
messages
Specifying an alternate file name produces a duplicate record of
all Teradata FastLoad error messages.
The alternate file specification is limited to eight characters
and, on z/OS, it must be to a DD name defined in the JCL.
There is no default filename specification.
MAXSESS = max-sessions
Maximum number of Teradata FastLoad sessions logged on to
the Teradata Database
Maximum specification must be greater than zero and no more
than the total number of AMPs on the system.
Default is one session for each AMP.
MINSESS = min-sessions
Minimum number of Teradata FastLoad sessions required to
run the job.
Minimum specification must be greater than zero and it must
be less than the value given for MAXSESS.
Default is 1.
RATE=outputrate
The rate for displaying progress messages to standard output
for rows successfully loaded to the Teradata Database.
If not specified, FastLoad defaults to writing a message every
100000 rows. Standard output for the default looks similar to
the following:
**** 22:00:06 Starting row 400000
**** 22:00:11 Starting row 500000
**** 22:00:15 starting row 600000
outputrate must be specified as an integer between 1 and
4294967295. Integers outside this range or float values are
invalid. If an invalid value is specified, FastLoad displays a
message stating that an invalid outputrate value has been
specified and the default value is used to process the Teradata
FastLoad job.
RVERSION
Display version number and stop.
This option must be run alone. Running the -V option with
other run time options will produce invalid results.
SLEEP= minutes
Specification of the sleep option in which minutes is the
number of minutes that Teradata FastLoad pauses before
retrying the logon operation.
For more information, see “SLEEP” on page 151.
The Teradata FastLoad default value is 6 minutes.
38
Teradata FastLoad Reference
Chapter 2: Using Teradata FastLoad
Invoking Teradata FastLoad
Table 8: Runtime Parameters (Channel-Attached Systems) (continued)
Parameter
Description
TENACITY= hours
Specification of the tenacity option in which hours is the
number of hours that Teradata FastLoad continues trying to
log on when the maximum number of load jobs are already
running on the Teradata Database.
For more information, see “TENACITY” on page 153.
The Teradata FastLoad default is no tenacity. Either a Teradata
FastLoad configuration file entry, the runtime parameter, or a
TENACITY command in your Teradata FastLoad job script
must be used to enable the tenacity feature for the Teradata
FastLoad logon operation.
VERBOSE
Allows every request sent to the Teradata Database to be
printed.
Network-Attached Runtime Parameters
Table 9 describes the runtime parameters used by Teradata FastLoad.
Using these Teradata FastLoad runtime parameters will override configuration parameter
settings.
Table 9: Runtime Parameters (Network-Attached Systems)
Parameter
Description
-b kilobytes
Output buffer size specification, where kilobytes is the size of
the output buffer, in kilobytes, that will be used for Teradata
FastLoad messages to the Teradata Database.
The output buffer size and the size of the rows in the Teradata
FastLoad table determine the maximum number of rows that
can be included in each message to the Teradata Database. A
larger buffer size reduces processing overhead by including
more data in each message.
The default buffer size is also the maximum size allowed—63
KB. If a value greater than 63 KB is specified, Teradata
FastLoad:
• Responds with a warning message
• Resets the buffer size back to the default value
• Continues with the Teradata FastLoad job
Teradata FastLoad Reference
39
Chapter 2: Using Teradata FastLoad
Invoking Teradata FastLoad
Table 9: Runtime Parameters (Network-Attached Systems) (continued)
Parameter
Description
-c character-set-name
Character set specification for the Teradata FastLoad job.
A character set name, as described in “Character Set
Specification” on page 54 can be specified.
Character set specification remains in effect for the entire
Teradata FastLoad job, even if the Teradata Database server
resets, causing the Teradata FastLoad job to be restarted.
Caution:
The character set specification does not remain in
effect if the client system fails, or if the Teradata
FastLoad job is cancelled. In these cases, when a job
is resubmitted, it must use the same character set
specification that was used on the initial job. If a
different character set specification is used when the
job is resubmitted, the data loaded by the restarted
job will not appear the same as the data loaded by
the initial job.
When a particular character set is specified, the identifiers and
data in that character set can be specified, thus affecting how
the data is loaded into the Teradata FastLoad table.
If a character set specification is not entered, the default is
whatever character set that is specified for the Teradata
Database whenever Teradata FastLoad is invoked.
Note: The order in which the character set is determined for a
Teradata FastLoad job is as follows:
1 User-specified by either a runtime parameter on channel-
attached systems or a SET SESSION CHARSET command
on network-attached systems
2 System Parameter Block (SPB) specified by either the
HSHSPB on channel-attached systems or the clispb.dat file
on network-attached systems
3 Teradata Database default, determined by a query from
Teradata FastLoad
Note: When using UTF-16 client character set on the network,
the client character set name needs to be specified by the
runtime parameter (for example, -c UTF-16). UTF16 is also a
valid value.
40
Teradata FastLoad Reference
Chapter 2: Using Teradata FastLoad
Invoking Teradata FastLoad
Table 9: Runtime Parameters (Network-Attached Systems) (continued)
Parameter
Description
-i scriptencoding
Specifies the encoding form of the job script.
The parameter is introduced for use with the UTF-16 client
character set, so it is only valid when UTF-16 client character
set is used. If the client character set being used is not UTF-16
and the parameter is specified, Teradata FastLoad reports an
error and terminates.
Valid encoding options are:
•
•
•
•
UTF-8 or UTF8
UTF-16BE, or UTF16-BE, or UTF16BE
UTF-16LE, or UTF16-LE, or UTF16LE
UTF-16 or UTF16
• UTF-8 indicates the job script is in UTF-8 character set.
• UTF-16 indicates the job script is in UTF-16 character set
without specifying the endianness.
• UTF-16BE indicates the job script is in big endian UTF-16
character set.
• UTF-16LE indicates the job script is in little endian UTF-16
character set.
Or, if UTF-16LE is specified but the UTF-16 Byte Order Mark
(BOM) in the script file indicates the script is in big endian,
Teradata FastLoad reports an error and terminates.
The UTF-16 or UTF-8 BOM can be present or absent in the
script file. Specify the input script format with -i runtime
parameter (mandatory) and specify session character set with c runtime parameter (mandatory) to ensure that the BOM in
the script file can be processed correctly.
When UTF-16 is specified and the UTF-16 BOM is present in
the script file, Teradata FastLoad interprets the script according
to the endianness indicated by the UTF-16 BOM. When the
UTF-16 BOM is not present, Teradata FastLoad interprets the
script according to the endianness indicated by the option
value. If the endianness is not indicated by the option value (for
example, UTF-16 is specified instead of UTF16-BE or UTF16LE), Teradata FastLoad interprets the job script in UTF-16
according to the endianness of the client system where the
Teradata FastLoad job invoked. The specified encoding
character set applies to all script files included by the .RUN
FILE commands.
When this runtime parameter is not specified and UTF-16
client character is used, Teradata FastLoad interprets the job
script in UTF-16. When UTF-8 is specified, Teradata
FastLoad interprets the job script in UTF-8 and converts SQL
and DML statements in the script from UTF-8 to UTF16
before sending the SQL and DML statements to Teradata
Database.
Teradata FastLoad Reference
41
Chapter 2: Using Teradata FastLoad
Invoking Teradata FastLoad
Table 9: Runtime Parameters (Network-Attached Systems) (continued)
Parameter
Description
-u outputencoding
Specifies the encoding form of the job output.
The parameter is introduced for being used for UTF-16 client
character set so it is only valid when UTF-16 client character
set is used. If the client character set being used is not UTF-16
and the parameter is specified, Teradata FastLoad reports an
error and terminates.
Valid encoding options are:
•
•
•
•
UTF-8 or UTF8
UTF-16BE, or UTF16-BE, or UTF16BE
UTF-16LE, or UTF16-LE, or UTF16LE
UTF-16 or UTF16
• UTF-16BE instructs Teradata FastLoad to print the job
output in the big endian UTF16 character set.
• UTF-16LE instructs Teradata FastLoad to print the job
output in the little endian UTF-16 character set.
• On big endian client systems, UTF-16 instructs Teradata
FastLoad to print the job output in big endian UTF-16
character set.
• On the little endian client systems, UTF-16 instructs
Teradata FastLoad to print the job out in little endian UTF16 character set.
When the parameter is being used, it should be placed in front
of the other runtime parameters to ensure the whole job output
will be printed in the desired encoding form. If not placed
ahead of the other runtime parameters when invoking the job,
a warning message will be printed.
When the parameter is not specified and the client character set
being used is UTF-16, the job output will be printed as UTF16.
Note: Do not use Notepad to view Unicode characters and
MBCS. Word provides the option to select the encoding when
opening the file, and always displays the MBCSs correctly with
the proper encoding. Other Hexidecimal editors can also be
used to view Unicode characters and MBCS properly.
-e filename
Alternate file specification for Teradata FastLoad error
messages.
Specifying an alternate file name produces a duplicate record of
all Teradata FastLoad error messages.
On z/OS channel-attached systems, the alternate file
specification is limited to eight characters, and it must be to a
DD name defined in the JCL.
There is no default filename specification.
42
Teradata FastLoad Reference
Chapter 2: Using Teradata FastLoad
Invoking Teradata FastLoad
Table 9: Runtime Parameters (Network-Attached Systems) (continued)
Parameter
Description
< infilename
Name of the standard input file that contains the Teradata
FastLoad commands and Teradata SQL statements on
network-attached client systems.
The infilename specification redirects the standard input
(stdin). If an infilename specification is not entered, the default
is stdin.
Caution:
On a UNIX OS, if your infilename contains
parenthesis, commas, or equal signs, FastLoad will
return an error of “File Not Found”. The infilename
must be changed to remove these special characters.
On Windows, these characters are legal, and
therefore no changes are necessary.
Note: On channel-attached client systems, the SYSIN control
command must be used to specify the input file before the
utility is invoked.
> outfilename
Name of the standard output file for Teradata FastLoad
messages on network-attached systems.
The outfilename specification redirects the standard output
(stdout).
If an outfilename specification is not entered, the default is
stdout.
Caution:
If an outfilename specification is not used to redirect
stdout, do not use the same outfilename as an output
or echo destination in the ROUTE MESSAGES
command. Doing so produces incomplete results
because of the conflicting write operations to the
same file.
Note: On channel-attached client systems, the SYSPRINT
control command must be used to specify the output file before
invoking the utility.
Specification on channel-attached systems that the Teradata
FastLoad job will use an INMOD routine written in the IBM C
programming language. The Teradata FastLoad job will fail if
this option is not specified when using a IBM C INMOD
routine.
-M max-sessions
Maximum number of Teradata FastLoad sessions logged on to
the Teradata Database.
Maximum specification must be greater than zero and no more
than the total number of AMPs on the system.
Default is one session for each AMP.
-N min-sessions
Minimum number of Teradata FastLoad sessions required to
run the job.
Minimum specification must be greater than zero and it must
be less than the value given for MAXSESS.
Default is 1.
Teradata FastLoad Reference
43
Chapter 2: Using Teradata FastLoad
Invoking Teradata FastLoad
Table 9: Runtime Parameters (Network-Attached Systems) (continued)
Parameter
Description
-s minutes
Specification of the sleep option in which minutes is the
number of minutes that Teradata FastLoad pauses before
retrying the logon operation.
For more information, see “SLEEP” on page 151.
The Teradata FastLoad default value is 6 minutes.
-t hours
Specification of the tenacity option in which hours is the
number of hours that Teradata FastLoad continues trying to
log on when the maximum number of load jobs are already
running on the Teradata Database.
For more information, see “TENACITY” on page 153.
The Teradata FastLoad default is no tenacity. Either a Teradata
FastLoad configuration file entry, the runtime parameter, or a
TENACITY command in the Teradata FastLoad job script
must be used to enable the tenacity feature for the Teradata
FastLoad logon operation.
-v
Allows printing of every request sent to the Teradata Database.
-y
Specification for the data encryption option.
When specified at run time, all sessions will be encrypted.
-V
Display version number and stop.
This option must be run alone. Running the -V option with
other run time options will produce invalid results.
-w
FastLoad wraps long error message to cleanup the message.
“-w” allows a user to specify the output message width.
The output width can be set to any value from 62 to 256 bytes.
If used, FastLoad wraps long error messages at the width
specified, instead of the at 72 bytes if the option is not set for
backward compatibility.
If an out of range value is set, FastLoad issues a warning
message and continues to use default constant width for output
messages.
44
Teradata FastLoad Reference
Chapter 2: Using Teradata FastLoad
Invoking Teradata FastLoad
Table 9: Runtime Parameters (Network-Attached Systems) (continued)
Parameter
Description
-r outputrate
The rate for displaying progress messages to standard output
for rows successfully loaded to the Teradata Database.
If not specified, FastLoad defaults to writing a message every
100000 rows. Standard output for the default looks similar to
the following:
**** 22:00:06 Starting row 400000
**** 22:00:11 Starting row 500000
**** 22:00:15 starting row 600000
outputrate must be specified as an integer between 1 and
4294967295. Integers outside t-s range or float values are
invalid. If an invalid value is specified, FastLoad displays a
message stating that an invalid outputrate value has been,
specified and the default value is used to process the Teradata
FastLoad job.
z/OS Example
Following is an example z/OS program that invokes Teradata FastLoad:
//FASTLOAD EXEC TDSFAST,INFILE=’<input dataset>’
//FAST.SYSIN DD DATA,DLM=$$
<FastLoad Control Statements>
$$
where the ddname SYSIN is the input data set that contains the Teradata FastLoad job script.
z/OS Procedure
Following is a sample z/OS procedure that is provided on the release tape with Teradata
FastLoad software. This procedure can be changed to meet specific site requirements and use
it to invoke Teradata FastLoad on a channel-attached z/OS client system.
//TDSFAST PROC FDLOPT=,PFX1=’DBC’,PFX2=’DBC’,
//INFILE=’NULLFILE’
//*****************************************
//* THIS PROCEDURE EXECUTES
*
//* THE FASTLOAD PROGRAM
*
//*
*
//* YOU CAN COPY THIS PROCEDURE
*
//* INTO YOUR SYSTEM PROCLIB
*
//* FOR ALL DBC USERS GENERAL USAGE.
*
//*
*
//* EXAMPLE EXECUTION:
*
//*
//FAST EXEC TDSFAST
*
//*
//FAST.SYSIN
DD DATA,DLM=$$
*
//*
LOGON .....;
*
//*
LOGOFF;
*
//*
$$
*
//*
*
//*
DDNAMES USED:
*
//*
SYSPRINT - PRINTED OUTPUT.
*
//*
SYSIN
- INPUT DATA SET
*
Teradata FastLoad Reference
45
Chapter 2: Using Teradata FastLoad
Invoking Teradata FastLoad
//*
CONTAINING FASTLOAD
*
//*
STATEMENTS.
*
//*
INFILE
- INPUT DATA SET
*
//*
CONTAINING DATA.
*
//*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*
//* TAILOR THE FOLLOWING FOR YOUR
*
//* SPECIFIC ENVIRONMENT:
*
//* SYMBOLIC
USE
*
//* ========
===
*
//* PFX1
= HIGH LEVEL QUALIFIER
*
//*
FOR APPLOAD LIBRARY.
*
//* FPX2
= HIGH LEVEL QUALIFIER
*
//*
FOR IBM C RUNTIME LIBRRARY.*
//* FDLOPT
= FASTLOAD PARAMETER INPUT. *
//* INFILE
= DSNAME OF INPUT DATASET.
*
//*
*
//*---------------------------------------*
//*
*
//* -DATE-- III DR/DCR- CHNG#--COMMENTS-- *
//*
*
//* 23JAN96 MXM
CREATED FOR C
*
//*
VERSION OF
*
//*
FASTLOAD
*
//*****************************************
//FASTLOAD EXEC PGM=FASTLOAD,
//
PARM=’&FDLOPT’, REGION=4096K
//STEPLIB DD DSN=&PFX1..APPLOAD,DISP=SHR
//
DD DSN-&PFX2..TRLOAD,DISP=SHR
//SYSPRINT DD SYSOUT=*
//SYSABEND DD SYSOUT=*
//SYSTERM DD SYSOUT=*
//INFILE
DD DSN=&INFILE,DISP=SHR
UNIX and Windows Examples
Following are examples of three ways to invoke Teradata FastLoad on network-attached client
systems:
•
fastload </home/fluser/tests/test1 >/home/fluser/tests/out1
This command specifies both an input file and an output file:
•
/home/fluser/tests/test1 is the input file that provides the Teradata FastLoad
job script.
•
•
/home/fluser/tests/out1 is the destination file for output data.
fastload </home/fluser/tests/test1
This command specifies only an input file. In this case, the output is written to the
standard output device, which is usually a terminal.
•
fastload
This command specifies neither an input nor an output device. In this case, the terminal
provides both the command input and the output data destination.
46
Teradata FastLoad Reference
Chapter 2: Using Teradata FastLoad
Terminating Teradata FastLoad
Terminating Teradata FastLoad
This section covers methods of termination and other topics related to terminating Teradata
FastLoad.
Definition
There are two ways to terminate Teradata FastLoad, depending on the operational situation:
•
Normal Termination
or
•
Abort Termination
Either way ends all Teradata FastLoad sessions and logs off the Teradata Database. A normal
termination, however, does so in an orderly, controlled fashion, and returns messages
indicating the status of the Teradata FastLoad job, and whether the utility was paused or
terminated. An abort termination does not.
Normal Termination
Use the LOGOFF or QUIT command in a Teradata FastLoad batch job script or interactive
session to terminate Teradata FastLoad normally on both network-attached and channelattached client systems:
LOGOFF
;
QUIT
2411A013
Teradata FastLoad logs off all sessions with the 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
•
4 if a warning condition occurred
•
8 if a user error occurred
•
12 if a fatal error occurred
Whether the utility terminated or paused
For more information about return codes and the conditions that terminate or pause
Teradata FastLoad, see “LOGOFF” on page 119 or “QUIT” on page 132.
Teradata FastLoad Reference
47
Chapter 2: Using Teradata FastLoad
Restart a Paused Teradata FastLoad Job
Abort Termination
The procedure for aborting a Teradata FastLoad job depends on whether the utility is running
on a network-attached or channel-attached client system.
To abort a Teradata FastLoad job running on a network-attached client system
✔ Press the Control + C key combination three times on the workstation keyboard.
Note: Some sessions of the aborted Teradata FastLoad job may remain active until the
gateway timeout period expires. Error “2738 %TVMID already has Teradata FastLoad
running” may occur if the same Teradata FastLoad job is resubmitted within the timeout
period. If this happens, wait until the gateway time-out has expired before resubmitting
the same Teradata FastLoad job.
To abort a Teradata FastLoad job running on a channel-attached client system
✔ Cancel the job from the client system console.
Restart a Paused Teradata FastLoad Job
This section describes restarting Teradata FastLoad jobs that have been paused or interrupted.
Overview
A paused Teradata FastLoad job is one that was halted, before completing, during the loading
or end loading phase of the Teradata FastLoad operation. The paused condition can be
intentional, or the result of a system failure or error condition.
A Teradata FastLoad job can be paused intentionally by using the LOGOFF or QUIT
command before the END LOADING command in the Teradata FastLoad job script, as when
running a multifile Teradata FastLoad job.
Unintentional conditions that can pause a Teradata FastLoad job include:
•
Client system or Teradata FastLoad failures
•
Unrecoverable error conditions
•
Database or table overfills
•
Teradata Database failures
•
Application Processor (AP) reset conditions
When a Teradata FastLoad job is in the paused state, the Teradata FastLoad target table and
the two error tables on the Teradata Database are locked. Two error tables can be accessed by
using a locking modifier, such as:
48
Teradata FastLoad Reference
Chapter 2: Using Teradata FastLoad
Restart a Paused Teradata FastLoad Job
After a Client System or Teradata FastLoad Failure
When a client system or a Teradata FastLoad failure occurs while a Teradata FastLoad job is
running, Teradata FastLoad:
1
Pauses the job.
2
Tries to log off all Teradata FastLoad sessions on the Teradata Database.
locking error_table_name for access
select errorcode, errorfieldname
from error_table_name;
To access the Teradata FastLoad target table, a Teradata FastLoad job consisting of a BEGIN
LOADING and an END LOADING command must be submitted. This effectively restarts
and ends the job.
After executing the END LOADING command, the Teradata FastLoad target table can be
accessed, but the original job cannot be restarted.
The following subsections describe the various pause conditions, the factors affecting
Teradata FastLoad restart operations, and the procedure for restarting a paused Teradata
FastLoad job.
After a Database Overfill Condition
When a Teradata FastLoad job tries to load more data into a table than the table or the
database that it is in can hold, Teradata FastLoad pauses the job and returns the following
message:
RDBMS error 2644: No more room in database <uid>
Increase database size and restart Teradata FastLoad
In this case, after increasing the amount of space allocated to the database, the Teradata
FastLoad job can be restarted at the point where the reported out-of-space condition
occurred.
After a Teradata Database Failure
Restarting a Teradata FastLoad job that was paused because of a Teradata Database failure
depends on the operational configuration of the Teradata Database when it returns to service:
•
If the configuration of the restarted Teradata Database is exactly the same as it was when
Teradata FastLoad was invoked, then Teradata FastLoad restarts the job automatically. In
this case, if the Teradata FastLoad job was paused in the end loading phase, the Teradata
Database resumes processing at the same place it was stopped.
If the Teradata FastLoad job was paused in the loading phase, the Teradata Database
resumes processing:
•
Teradata FastLoad Reference
at the last checkpoint if the BEGIN LOADING command specified the checkpoint
option.
49
Chapter 2: Using Teradata FastLoad
Restart a Paused Teradata FastLoad Job
•
at the beginning if the BEGIN LOADING command did not specify the checkpoint
option.
Note: If the Teradata FastLoad job uses an INMOD routine, the routine must be able to
handle restarts and checkpoints when restarted in the loading phase.
•
If the configuration of the restarted Teradata Database is different from the way it was
when Teradata FastLoad is invoked, then Teradata FastLoad does not restart the job. In
this case, to restart and continue with the paused Teradata FastLoad job, must reestablish
the original configuration of the Teradata Database. If this is not possible, then the
Teradata FastLoad job must:
a
Delete the Teradata FastLoad table and error tables.
b
Resubmit the Teradata FastLoad job, from the beginning, as a new job.
After an AP Reset Condition
When a Teradata FastLoad job is interrupted by a resetting AP on the Teradata Database, the
restart alternatives depend on the environment in which Teradata FastLoad is running:
•
If running on a resetting AP, then Teradata FastLoad:
a
Pauses the job.
b
Tries to log off all Teradata FastLoad sessions on the Teradata Database.
This situation is similar to Teradata FastLoad jobs that are paused after a client-system
failure or a Teradata FastLoad failure.
•
If running on a nonresetting AP, then Teradata FastLoad is not paused, and does not need
to be manually restarted.
•
If running on a network-attached client system, then Teradata FastLoad is paused, but
does not need to be manually restarted. This situation is similar to a Teradata Database
restart or network failure.
For jobs run on a network-attached client system, or on a nonresetting AP, Teradata
FastLoad behavior following the AP reset condition varies, depending on whether the
Teradata FastLoad job has sessions connected through the resetting AP. If the Teradata
FastLoad job:
•
has one or more sessions connected through a resetting AP, Teradata FastLoad
automatically logs all sessions off and then on again, rolls back to the most recent
checkpoint, and then resumes processing.
•
has no sessions connected through a resetting AP, Teradata FastLoad is not affected by
the resetting AP.
Note: The increased session loading caused by the reconnection of other sessions
through the resetting AP may degrade the system response time.
After an Unrecoverable Error Condition
When an unrecoverable error condition occurs while a Teradata FastLoad job is processing
the BEGIN LOADING command, but before completing the end loading process, Teradata
FastLoad:
50
Teradata FastLoad Reference
Chapter 2: Using Teradata FastLoad
Restart a Paused Teradata FastLoad Job
1
Pauses the job.
2
Logs off all Teradata FastLoad sessions on the Teradata Database.
3
Writes the Teradata FastLoad PAUSED message to the standard output device, along with
the error code associated with the error.
Note: Teradata FastLoad terminates if an unrecoverable error condition occurs before it
begins processing the BEGIN LOADING command, or after it has completed processing the
END LOADING command.
Restart Procedures
The procedure which is used and the Teradata FastLoad response to restarting a paused
Teradata FastLoad job depends on the phase that the Teradata FastLoad job was in when it
was paused.
•
A job that was paused during loading can be restarted, either from the beginning, or from
the most recent checkpoint if the BEGIN LOADING command specified the checkpoint
option.
•
Or, a job that was paused during end loading from wherever it was interrupted can be
restarted. This is because the Teradata Database uses internal checkpointing during this
phase.
Note: Generally, nothing needs to be done because processing after the END LOADING
command is executed on the Teradata Database does not depend on Teradata FastLoad.
However, if restarting the job in the end loading phase is required, see the procedure that
follows.
To restart the job if the Teradata FastLoad job was paused during the loading phase
1
Remove the CREATE TABLE statement and any DROP TABLE and DELETE statements
from the Teradata FastLoad job script to prevent the restarted job from dropping the
partially loaded Teradata FastLoad table or deleting the entries in the two error tables.
2
Invoke Teradata FastLoad to start the job. The Teradata FastLoad utility:
•
Establishes new sessions using the LOGON command.
•
Reads the restart log to determine the restart point.
•
In response to the BEGIN LOADING command, indicates that the job is being
restarted.
If, for example, the job had a checkpoint specification of 100, and the failure occurred at
row 1100, the Teradata FastLoad response would be:
FastLoad RESTARTED
The last checkpoint was taken at
row: 1100
FastLoad will now restart at
row: 1101
Note: If the Teradata FastLoad job was paused during the loading phase and uses an INMOD
routine, the INMOD routine must be able to handle restarts and checkpoints when restarted
in the loading phase. Following a restart, Teradata FastLoad passes a status code of 2 or 4 to an
INMOD routine that is participating in a load operation. The routine must adjust the record
Teradata FastLoad Reference
51
Chapter 2: Using Teradata FastLoad
Programming Considerations
to be read to the position of the last checkpoint and, upon subsequent calls, send records to
Teradata FastLoad.
To restart the job if the Teradata FastLoad job was paused during the end loading phase
1
Use the same LOGON command described in the preceding procedure.
2
Submit BEGIN LOADING and END LOADING commands, as in the following example:
LOGON dbc/sjn,music ;
BEGIN LOADING Fast_Table
ERRORFILES Error_1, Error_2 ;
END LOADING ;
Note: If a Teradata FastLoad job script is used to assemble these commands, make sure to
delete the CREATE TABLE and any DROP TABLE and DELETE statements before restarting
the job.
Programming Considerations
This section describes the things to consider when designing and coding a Teradata FastLoad
job script.
Teradata FastLoad Configuration File
A Teradata FastLoad configuration file can be created to set the initial default values for the
following operating parameters when Teradata FastLoad is invoked:
•
TENACITY
•
SLEEP
•
BUFSIZE
•
CHARSET
•
INMODRETURN
•
MAXSESS
•
MINSESS
•
CONFIGERRORS
The values specified in the Teradata FastLoad configuration file override the internal utility
default values for these parameters.
The configuration file parameters themselves can be overridden by the TENACITY, SLEEP,
SESSION, and SET SESSION CHARSET commands in the Teradata FastLoad job script, and
by the corresponding runtime parameters, as shown in Table 8 on page 36 and Table 9 on
page 39. The order of preferences for the TENACITY, SLEEP and SESSION specifications,
from the highest to lowest, is:
52
1
Runtime parameters
2
Teradata FastLoad script commands
Teradata FastLoad Reference
Chapter 2: Using Teradata FastLoad
Programming Considerations
3
Teradata FastLoad configuration file specifications
4
Teradata FastLoad default values
Note: The utility default for TENACITY is no tenacity. Either a configuration file entry, the
runtime parameter, or the TENACITY command in your Teradata FastLoad job script must
be used to enable the tenacity feature for the Teradata FastLoad logon operation.
The order of preferences for the CHARSET specification, from the highest to lowest, is:
1
Teradata FastLoad script commands
2
Runtime parameters
3
Teradata FastLoad configuration file specifications
4
Teradata FastLoad default values
Configuration File Name and Location
On network-attached systems, the Teradata FastLoad configuration file must be named:
floadcfg.dat
And it must be located in either:
•
The directory from which Teradata FastLoad was launched
•
The directory specified in the FLOADLIB environment variable
On channel-attached systems, the DD statement for the Teradata FastLoad configuration file
must be labeled FLOADCFG
Configuration File Contents
The Teradata FastLoad configuration file can have up to eight entries, one for each parameter:
TENACITY=hours
SLEEP=minutes
BUFSIZE=kilobytes
CHARSET=character-set-name
INMODRETURN=ON or YES
MAXSESS=max-sessions
MINSESS=min-sessions
DATAENCRYPTION=ON or OFF
CONFIGERRORS=IGNORE/TERMINATE
where:
•
hours is the TENACITY specification of the number of hours that Teradata FastLoad
continues trying to log on when the maximum number of load jobs are already running
on the Teradata Database. For more information about this specification, see
“TENACITY” on page 153.
•
minutes is the SLEEP specification of the number of minutes that Teradata FastLoad
pauses between attempts to log on. For more information about this specification, see
“SLEEP” on page 151.
•
kilobytes is the size of the output buffer, in kilobytes, to be used for Teradata FastLoad
messages to the Teradata Database. For a description of the BUFSIZE specification, see
BUFSIZE/-b runtime parameter topic in Table 8 on page 36.
Teradata FastLoad Reference
53
Chapter 2: Using Teradata FastLoad
Programming Considerations
•
character-set-name is the character set specification for the job. For more information
about this specification, see the CHARSET runtime parameter topic in Table 8 on page 36
or -c runtime parameter topic in Table 9 on page 39 and “SET SESSION CHARSET” on
page 146.
•
ON or YES specifies that INMOD return codes are to be checked and returned. The
informational message INMOD return codes will be checked displays. Nonzero
return codes force Teradata FastLoad to terminate.
•
max-sessions is the MAXSESS specification for the maximum number of Teradata
FastLoad sessions logged on to the Teradata Database. For more information about this
specification, see “SESSIONS” on page 138.
•
min-sessions is the MINSESS specification for the minimum number of Teradata FastLoad
sessions required to run the job. For more information about this specification, see
“SESSIONS” on page 138.
•
ON or OFF specifies whether data encryption will be enabled for the job.
•
IGNORE/TERMINATE configures the option for configuration file error handling.
The configuration file can also have comment statements preceded by a number sign (#)
character.
Configuration File Processing
Teradata FastLoad automatically checks for a configuration file each time the invocation
command is entered. Upon locating a configuration file, the utility sets the defaults as
specified, produces the appropriate output messages, and begins processing the Teradata
FastLoad job.
By default, any invalid configuration file entry or syntax error immediately aborts a job and
produces return code 12. The first invalid parameter is reported; none of the other
configuration parameters are checked.
•
If CONFIGERRORS=IGNORE is specified, any subsequent configuration file problems
will be reported, but they will not affect the return code. FastLoad will continue to process
the next entry in the configuration file.
•
If CONFIGERRORS=TERMINATE is specified (the default), any subsequent invalid
configuration file entry will abort the job.
The CONFIGERRORS value can be changed more than once in a configuration file. Its value
affects subsequent entries processing until the next CONFIGERRORS entry or until the end of
the configuration file.
If no configuration file exists, the utility begins processing the load job without an error
indication. The configuration file is an optional feature; its absence is not considered an error
condition.
Character Set Specification
Table 10 lists character sets supported by Teradata FastLoad.
54
Teradata FastLoad Reference
Chapter 2: Using Teradata FastLoad
Programming Considerations
Table 10: Character Sets Supported by Teradata FastLoad
Character Set Name
Description
Configuration
ASCII
Latin
Network-attached
EBCDIC
Latin
Channel-attached
HANGULEBCDIC933_1II
Korean
Channel-attached
HANGULKSC5601_2R4
Korean
Network-attached
KANJIEUC_0U
Japanese
Network-attached
KANJISJIS_0S
Japanese
Network-attached
KATAKANAEBCDIC
Japanese
Channel-attached
KANJIEBCDIC5026_0I
Japanese
Channel-attached
KANJIEBCDIC5035_0I
Japanese
Channel-attached
SCHEBCDIC935_2lJ
Simplified Chinese
Channel-attached
SCHGB2312_1T0
Simplified Chinese
Network-attached
TCHEBCDIC937_3IB
Traditional Chinese
Channel-attached
TCHBIG5_1R0
Traditional Chinese
Network-attached
UTF-8
Unicode character set
• Channel-attached
• Network-attached
UTF-16
Unicode character set
Network-attached
Site-Defined Character Sets
When the character sets defined are not appropriate for a site, custom character sets can be
defined using the information in Table 11. For information on defining a custom character
set, see SQL Data Definition Language.
Table 11 lists the site-defined character sets.
Table 11: Site-Defined Character Sets
Character Set Name
Description
Configuration
SDHANGULEBCDIC933_5II
Korean
Channel-Attached
SDHANGULKSC5601_4R4
Korean
Network-Attached
SDKATAKANAEBCDIC_4IF
Japanese
Channel-Attached
SDKANJIEBCDIC5026_4IG
Japanese
Channel-Attached
SDKANJIEBCDIC5035_4IH
Japanese
Channel-Attached
SDKANJIEUC_1U3
Japanese
Network-Attached
Teradata FastLoad Reference
55
Chapter 2: Using Teradata FastLoad
Programming Considerations
Table 11: Site-Defined Character Sets (continued)
Character Set Name
Description
Configuration
SDKANJISJIS_1S3
Japanese
Network-Attached
SDSCHEBCDIC935_6IJ
Simplified Chinese
Channel-Attached
SDTCHEBCDIC937_7IB
Traditional Chinese
Channel-Attached
SDSCHGB2312_2T0
Simplified Chinese
Network-Attached
SDTCHBIG5_3R0
Traditional Chinese
Network-Attached
Note: For information on defining a custom character set, see International Character Set
Support.
Rules for Chinese and Korean Character Set Use
Follow these rules when using Chinese and Korean character sets on channel-attached and
network-attached platforms.
•
Object Names
Object names are limited to A-Z, a-z, 0-9, and special characters such as $ and _.
•
Maximum String Length
The DBS 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.
For more information about Chinese or Korean character set restrictions for the Teradata
Database, refer to International Character Set Support.
AXSMOD
When an AXSMOD is used, Teradata FastLoad will pass the session character set as an
attribute to the AXSMOD for its possible use (most AXSMODs will not make any use of this
information).
The attribute value will be a variable length character string consisting of the character set
name; the attribute name will be CHARSET_NAME.
Unicode Character Sets
UTF-8 and UTF-16 are two of the standard ways of encoding Unicode character data. 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-16 client character set
supports UTF-16 encoding. Currently, the Teradata Database supports the Unicode 5.1
standard, where each defined character requires exactly 16 bits.
For restrictions imposed by Teradata Database on the use of UTF-8 or UTF-16 character set,
see International Character Set Support.
56
Teradata FastLoad Reference
Chapter 2: Using Teradata FastLoad
Programming Considerations
UTF-8 Character Sets
Teradata FastLoad 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 FastLoad translates commands in the job script from Teradata EBCDIC to UTF8 during the load. Be sure to examine the definition in the 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.
UTF-16 Character Sets
Teradata FastLoad 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.
ANSI/SQL DateTime Specifications
The ANSI/SQL DATE, TIME, TIMESTAMP and INTERVAL DateTime data types in
Teradata SQL CREATE TABLE statements, can be used. Specify them as column/field
modifiers in INSERT statements. However, certain restrictions should be noted:
•
ANSI/SQL DateTime data types cannot be used when specifying the column/field names
in a DEFINE command.
•
ANSI/SQL DateTime data types must be converted to fixed-length CHAR data types when
specifying the column/field names in the DEFINE command.
For a description of the fixed-length CHAR representations for each DATE, TIME,
TIMESTAMP and INTERVAL data type specification, see “Usage Notes” on page 92.
Checkpoint Tradeoffs
Though the checkpoint feature substantially enhances Teradata FastLoad restart operations, it
also reduces the speed of the Teradata FastLoad job. Always consider the following factors
when deciding how often to specify checkpoints:
•
Each checkpoint temporarily halts the multiple session data transfer feature of Teradata
FastLoad, thereby decreasing the speed of the Teradata FastLoad job.
•
For each checkpoint, Teradata FastLoad waits for each session to complete sending its
current request, which interrupts the data transfer operation.
•
The record size and the size of the Teradata Database influence how often checkpoints
should be specified. On a smaller Teradata Database, specify checkpoints:
•
Teradata FastLoad Reference
Every 50,000 records if each record is more then 4 KB
57
Chapter 2: Using Teradata FastLoad
Programming Considerations
•
Every 100,000 records if each record is less than 4 KB
On a larger Teradata Database, specify higher (less frequent) checkpoint values.
Checkpoint Support with Access Modules
When an AXSMOD is used, Teradata FastLoad will pass the checkpoint value as an attribute
to the AXSMOD for its possible use. The attribute value will be a string containing the ASCII
encoding of the decimal textual representation of the checkpoint value. A value of “0”
indicates that Teradata FastLoad is not using checkpoints. A file opened by an access module
instance for which the CHECKPOINT_INTERVAL attribute is “0” will not receive a File Get
Position request.
Comments
Teradata FastLoad supports C program language comments. Comments supported for
Teradata FastLoad have the following characteristics:
•
Begin with a forward slash asterisk (/*) character sequence and end with an asterisk
forward slash (*/) sequence. These sequences are the beginning and ending delimiters; all
intervening text is treated as a comment.
•
Will be sent to the Teradata Database
•
Are invalid within string or character literals—a /* within a quoted string is not treated as
the beginning of a comment.
Teradata FastLoad does not support nested comments.
Concurrent Load Utility Tasks
The maximum number of concurrent Teradata FastLoad tasks that can run is variable; the
limit can be controlled by a system administrator. MaxLoadTasks may be overridden if
Teradata Active System Management (Teradata ASM) is active.
For the most up-to-date information on concurrent task limits, see the description of the
MaxLoadTask parameter of the DBSControl utility in the Utilities, Volume 1 manual.
Additional information is available in the Teradata Dynamic Workload Manager User Guide.
If a Teradata FastLoad job exceeds recommended limits, Teradata FastLoad returns a 2633
error message indicating that too many loads are running. In this case, the utility retries until:
•
It can execute the task.
•
It reaches the TENACITY hours time limit specified by the BEGIN EXPORT command or
runtime parameter.
Data Conversion Factors
Be aware of the following when using Teradata FastLoad to perform data conversion:
•
58
When using the DEFINE command to change the data type specification of source data
before inserting it into the Teradata FastLoad table on the Teradata Database, only one
type conversion per column can be specified.
Teradata FastLoad Reference
Chapter 2: Using Teradata FastLoad
Programming Considerations
Note: Teradata FastLoad cannot be used to define a column with an arithmetic
expression. For example, Teradata FastLoad will not calculate a monthly salary column
from yearly salary data.
•
When using Teradata FastLoad to load and convert data from decimal to character, define
the length of the column into which the data will be inserted to be larger than the size of
the source data in order to accommodate the sign byte. Otherwise, the Teradata Database
generates an error message as follows:
3944: Data length is invalid for the data type.
For details on data types and data conversions, see SQL Data Types and Literals.
Valid Data Conversion Example
The following valid example converts character data to integer data, assuming that column b
is of type INTEGER:
DEFINE a (char(10)) file= . . . ;
INSERT INTO table1 (b) VALUES (:a(integer)) ;
Valid Redundant Conversion Example
The following valid example converts data in zoned decimal format to type decimal format,
assuming that column d is of type DECIMAL (9,2):
DEFINE b (char(9)) file= . . . ;
INSERT INTO Table1 (d) VALUES (:b (decimal(9,2)));
Note: Redundant conversions can be used, as a reminder that a data conversion is taking
place.
Invalid Data Conversion Example
The following data conversion example is invalid because it requests two conversions—from
character to decimal, and then from decimal to integer, assuming that column b is of type
INTEGER:
DEFINE a(char(10)) file= . . . ;
INSERT INTO table1 (b) VALUES (:a (decimal(5,2))) ;
If loading Decimal(5,0) data, the length of the destination character column must be defined
as Char(6) instead of Char(5). The following data conversion example is invalid because the
column size is not large enough to hold all of the data:
DEFINE a(decimal(5,0)) file = .;
INSERT INTO table (b) VALUES (: a(char(5));
Error Limits
When specifying the ERRLIMIT value, consider the number and type of errors expected from
the Teradata FastLoad job.
•
If the Teradata FastLoad job is expected to encounter no errors or very few errors, then
specify an ERRLIMIT value that is low.
•
If the Teradata FastLoad job is expected to encounter many errors that are considered
allowable, then specify an ERRLIMIT value that is high.
Teradata FastLoad Reference
59
Chapter 2: Using Teradata FastLoad
Programming Considerations
Nonunique Index Sorts
If a Teradata FastLoad table is defined with a nonunique primary index, the performance of
the Teradata FastLoad job can be enhanced by not using the index value to sort the input data.
Duplicate Rows
Teradata FastLoad does not load duplicate rows, as in MULTISET tables. If Teradata FastLoad
is used to load a target table defined as MULTISET, the utility will discard any duplicate rows.
If duplicate rows must be loaded, consider using MultiLoad.
Range Constraints
Range constraints are data description phrases that are entered into the Teradata SQL
CREATE TABLE statement that limit the range of acceptable values for a column. Since the
range constraint checks occur while Teradata FastLoad inserts data into the Teradata
FastLoad table, the number of range constraints in the Teradata FastLoad job script has a
direct impact on the performance of Teradata FastLoad.
Range Constraint Types
Table 12 list the two types of range constraints, explicit and implicit.
Table 12: Range Constraint Types
Constraint Type
Example
Explicit
The Salary column range of between 1 and 99000.00, as shown in the following
CREATE TABLE example.
Implicit
The DeptNo column range of ZZ9, as shown in the following CREATE TABLE
example.
Range Constraint Examples
The following Teradata SQL CREATE TABLE statement shows the two types of range
constraint phrases for the Salary and DeptNo columns:
CREATE TABLE Employee
(EmpNo INTEGER FORMAT ‘ZZZZ9’,
Name VARCHAR (12) CASESPECIFIC TITLE
‘Employee//Name’, DeptNo INTEGER FORMAT ‘zz9’
TITLE ‘Dept#’,
Salary DECIMAL (7,2) BETWEEN 1 AND 99000.00
FORMAT ‘ZZ,ZZ9.99’)
UNIQUE PRIMARY INDEX (EmpNo);
Before inserting each row in the Employee table, Teradata FastLoad checks to verify that the
value for:
60
•
Salary is in the range of 1 to 99000.00
•
DeptNo is between –999 and 999
Teradata FastLoad Reference
Chapter 2: Using Teradata FastLoad
Programming Considerations
If it is known that the values for the DeptNo column are always in the range of -999 to 999,
then they can improve the performance of the Teradata FastLoad job by removing the ZZ9
phrase from the CREATE TABLE statement in the Teradata FastLoad job script.
Record Mode Load Anomaly
When loading data in Record Mode into a NULLABLE DATE field, if the source data is a
binary integer of value zero, then the Teradata Database sets the field to NULL, not to zero.
UNIX Signals
If Teradata FastLoad is running in a UNIX operating system, be aware of the UNIX signals
used by Teradata FastLoad. Teradata FastLoad UNIX signals cannot be used in any module or
routine programmed for use with Teradata FastLoad. Doing so causes an error in Teradata
FastLoad.
Teradata FastLoad uses the following UNIX signals:
•
SIGINT (interrupt signal)
•
SIGQUIT (quit signal)
•
SIGTERM (terminate signal)
•
SIGUSR1 (user signal 1)
Note: Signals are predefined messages sent between two UNIX OS processes to communicate
the occurrence of unexpected external events, or exceptions. Aborting a Teradata FastLoad
session while Teradata FastLoad is in the middle of processing a job is an example of an
exception. In this scenario, Teradata FastLoad uses the UNIX signals to trap the abort
command, disconnect all sessions, do any necessary cleanup, and then terminate in an orderly
manner.
Restrictions and Limitations
The following sections describe restrictions and limitations relevant for programming with
the Teradata FastLoad utility.
Session Limits
The value specified with the SESSIONS command is not the only factor that limits the
number of sessions that Teradata FastLoad establishes with the Teradata Database. The other
limiting factors are:
•
The Teradata Database limit of one session per AMP.
•
The platform limit on the maximum number of sessions per application.
This value is defined in the Communications Processor (COP) Interface software file,
CLISPB.DAT, under the MaxSess variable.
The TDP SET MAXSESSIONS command can be used to specify a platform limit. The
default limit is equal to the server MAXSESS.
•
Teradata FastLoad Reference
The limit of the network protocol software on network-attached systems.
61
Chapter 2: Using Teradata FastLoad
Programming Considerations
When invoking Teradata FastLoad, the actual session limit is determined by whichever
limiting factor is encountered first.
Space Requirements and Limitations
Always estimate the final size of the Teradata FastLoad table, and make sure that the
destination database on the Teradata Database has enough space to accommodate the
Teradata FastLoad job. If the database that owns the Teradata FastLoad table or the error
tables runs out of space, the Teradata Database returns an error message and Teradata
FastLoad pauses your Teradata FastLoad job. When this happens, allocate more space to the
database before restarting the job.
Join Index Restrictions
Teradata FastLoad does not maintain join indexes. Teradata FastLoad cannot be used to load
data to tables with an associated join index on a Teradata Database. In this case, first drop the
join index, then recreate it after running the Teradata FastLoad job.
Note: Teradata FastLoad does not support hash and join indexes.
Foreign Key References Limitation
Teradata FastLoad does not support foreign key references in target tables. Attempting a
Teradata FastLoad task or any action against a target table defined with a foreign key
constraint produces an error condition.
Secondary Indexes Limitation
Teradata FastLoad does not support target tables defined with secondary indexes. Attempting
a Teradata FastLoad task against a target table defined with secondary indexes produces an
error condition.
To load such a table, first drop the secondary indexes. Then load the table and recreate the
secondary indexes.
Or, alternatively, if only nonunique secondary indexes (NUSI) are involved, consider using
MultiLoad.
Note: Teradata FastLoad does not support secondary indexes of any kind.
Referential Integrity Limitation
Attempting a Teradata FastLoad task or any action against tables with [referential
integrity|defined triggers] produces an error condition.
Defined Triggers Limitation
Attempting a Teradata FastLoad task or any action against tables with [referential
integrity|defined triggers] produces an error condition.
62
Teradata FastLoad Reference
Chapter 2: Using Teradata FastLoad
INMOD and Notify Exit Routines
Loading No Primary Index Tables
A NoPI Table is a table that 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.
Note: FastLoad is generally faster than TD TPump whether the target table is PI or NoPI. TD
TPump has a bigger performance improvement with NoPI but it is still slower than FastLoad.
The “table must be empty” restriction applies if the target table is a NoPI table. FastLoad
cannot load into a populated NoPI table. See the No Primary Index discussion under
CREATE TABLE in SQL Data Definition Language.
FastLoad can load Primary Index (PI) tables defined as MULTISET, but all duplicate rows are
discarded, the target table is treated as if it were a SET table. NoPI tables are inherently
MULTISET, since no duplicate row checking is possible (duplicate rows can be on different
AMPs). Therefore, when FastLoad targets a NoPI table, no check is made for duplicate rows,
and duplicate rows are not discarded.
Conventions for Quotes
Strings that contain single quotes or double quotes are not allowed to span records (lines);
therefore, ensure that all quoted strings are limited to a single line.
INMOD and Notify Exit Routines
This section provides information about how to use input modification (INMOD) and notify
exit routines.
Overview
This section describes the different types of routines and when to use them.
INMOD Routines
The term INMOD is an acronym for input modification routines. These are user exit routines
that Teradata FastLoad and other load/export utilities can call to provide enhanced processing
functions on input records before they are sent to the Teradata Database.
When an INMOD routine is specified in the DEFINE command, it is the named routine,
rather than a data source, that provides the input data records that Teradata FastLoad loads
into the Teradata FastLoad table on the Teradata Database.
Use INMOD routines to:
•
Select and validate data records before passing them to the Teradata Database
•
Convert fields in data records before passing them to the Teradata Database
•
Read data directly from different database system data sets, such as IMS, TOTAL, and so
on, and create and pass a consolidated data record to the Teradata Database without using
an intermediate tape or disk data set.
Teradata FastLoad Reference
63
Chapter 2: Using Teradata FastLoad
INMOD and Notify Exit Routines
Notify Exit Routines
A notify exit routine specifies a predefined action to be performed whenever certain
significant events occur during a Teradata FastLoad job.
Notify exit routines are especially useful in operator-free environments 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
command, a routine to detect whether a Teradata FastLoad job succeeds or fails, how many
records were loaded, what the return code is for a failed job, and so on can be provided.
Programming Considerations for Routines
This section describes programming languages supported for each type of routine, as well as
other related considerations.
Programming Languages
Teradata FastLoad is written in:
•
IBM C for channel-attached z/OS client systems
•
C for network-attached UNIX and Windows client systems
In all cases, INMOD and notify exit routines are dynamically loaded at run time, rather than
link-edited into the Teradata FastLoad module. The programming languages listed in
Table 13 can be used to write INMOD and notify exit routines, depending on the platform
that runs Teradata FastLoad.
Table 13 lists the programming languages supported.
Table 13: Programming Languages Supported by Platform and Type of User-Developed Routine
Platform
INMOD Routine
Notify Exit Routine
z/OS
IBM C
IBM C
UNIX OS, Windows
C
C
Platforms
Write
z/OS
• INMOD routines in IBM C
• Notify exit routines in IBM C
UNIX OS, Windows
• INMOD and notify exit routines in C
Programming Structure
Table 14 defines the structure, by programming language, for communicating between
Teradata FastLoad and an INMOD or notify exit routines.
64
Teradata FastLoad Reference
Chapter 2: Using Teradata FastLoad
INMOD and Notify Exit Routines
Table 14: Programming Structures for Teradata FastLoad/INMOD Communication
Routine Language
Programming Structure
C
struct {
long Status;
long RecordLength;
char buffer[32004];
}
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 DEFINE command.
Routine Entry Points
Table 15 shows the entry points for INMOD routines.
Table 15: Entry Points for INMOD Routines
Routine Language
Entry Point
IBM C on z/OS platforms
dynamn
C on all supported workstation platforms
BLKEXIT
Addressing Mode on z/OS Systems
Use either 31-bit or 24-bit addressing for INMOD routines on channel-attached systems.
The 31-bit mode provides access to more memory, which enhances performance for Teradata
FastLoad 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:
•
AMODE(31) for 31-bit addressing
•
AMODE(24) for 24-bit addressing
Teradata FastLoad/INMOD Routine Interface
Teradata FastLoad exchanges information with an INMOD routine by passing an address that
points to a three-value structure: status code, length, and body.
Status Code
Status code is the 32-bit signed binary value that carries information in both directions.
Table 16 explains the six status codes used by the Teradata FastLoad-to-INMOD interface.
Teradata FastLoad Reference
65
Chapter 2: Using Teradata FastLoad
INMOD and Notify Exit Routines
Table 16: Teradata FastLoad--to--INMOD Interface Status Codes
Value
Description
0
Teradata FastLoad is calling for the first time.
Teradata FastLoad expects the INMOD routine to return a data record.
Note: At this point, the INMOD routine should perform its initialization tasks before
sending a data record to Teradata FastLoad.
1
Teradata FastLoad is calling, not for the first time.
Teradata FastLoad expects the INMOD routine to return a data record.
2
The client system has been restarted.
The INMOD routine should reposition to the last checkpoint.
Teradata FastLoad is not expecting the INMOD routine to return a record.
Note: This is a one-time call, and Teradata FastLoad does not issue a subsequent call
with a status code value of zero.
3
A checkpoint has been written.
The INMOD routine should remember the checkpoint position.
Teradata FastLoad does not expect the INMOD routine to return a record.
4
The Teradata Database has failed.
The INMOD routine should reposition to the last checkpoint.
Teradata FastLoad is not expecting the INMOD routine to return a record.
Note: This is a one-time call, and Teradata FastLoad does not issue a subsequent call
with a status code value of zero.
5
The Teradata FastLoad job has ended.
The INMOD routine should perform any required cleanup tasks.
Note: This condition only applies to network-attached client systems.
Table 17 describes the two status codes used by the INMOD-to-Teradata FastLoad interface.
Table 17: INMOD-to-Teradata FastLoad Interface Status Codes
Status Code
Description
0
a record is being returned as the Body value
any nonzero value
the INMOD routine is at an end-of-file condition
Length
Length is a 32-bit signed 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.
66
Teradata FastLoad Reference
Chapter 2: Using Teradata FastLoad
INMOD and Notify Exit Routines
Body
Body is the area where the INMOD routine places the data record.
The maximum record length depends on the release/version level of the Teradata Database.
Teradata FastLoad neither checks nor enforces record length restrictions on data provided by
the INMOD routine. The record length, therefore, must not exceed the capability of the
Teradata Database.
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
FastLoad 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 FastLoad/Notify Exit Routine Interface
Teradata FastLoad accumulates operational information about specific events that occur
during a Teradata FastLoad job. If the Teradata FastLoad job script includes a NOTIFY
command with an EXIT option specification, Teradata FastLoad calls the named notify exit
routine and passes to it when the specific events occur:
•
An event code to identify the event
•
Specific information about the event
Table 18 lists the event codes and describes the data that Teradata FastLoad passes to the
notify exit routine for each event. For a description of the events associated with each level of
notification (low, medium, and high), see “NOTIFY” on page 124.
Note: To support future enhancements, always ensure that notify exit routines ignore invalid
or undefined event codes, and that they do not cause Teradata FastLoad to terminate
abnormally.
Table 18: Events Passed to the Notify Exit Routine
Event
Code
Event
Event Description
Data Passed to the Notify Exit Routine
0
Initialize
Successful processing of the
NOTIFY command
•
•
•
•
•
•
•
•
•
1
File or INMOD open
Successful processing of the
DEFINE command that
specifies the file or INMOD
routine name.
• File name length—4-byte unsigned integer
• File name—256-character (maximum) array
Teradata FastLoad Reference
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—32-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
67
Chapter 2: Using Teradata FastLoad
INMOD and Notify Exit Routines
Table 18: Events Passed to the Notify Exit Routine (continued)
Event
Code
Event
Event Description
2
Phase 1 begin
• Table name length—4-byte unsigned integer
The beginning of the insert
phase, where the table name is • Table name—128-character (maximum) array
specified by the INSERT
statement.
3
Checkpoint
Checkpoint information has
been written to the restart log
table.
• Record number—4-byte unsigned integer
4
Phase 1 end
The CHECKPOINT
LOADING END request has
successfully completed after
the end of the insert phase.
•
•
•
•
5
Phase 2 begin
The END LOADING
command is about to be sent
to the Teradata Database.
No data accompanies the phase 2 begin event code
6
Phase 2 end
Processing of the END
LOADING command
completed successfully.
• Records loaded—4-byte unsigned integer
7
Error table 1
Processing of the SEL
COUNT(*) request
completed successfully for the
first error table.
• Number of rows—4-byte unsigned integer
8
Error table 2
Processing of the SEL
COUNT(*) request
completed successfully for the
second error table.
• Number of rows—4-byte unsigned integer
9
Teradata Database
restart
Teradata FastLoad received a
crash message from the
Teradata Database or from
the CLIv2.
No data accompanies the Teradata Database restart
event code
10
CLIv2 error
Teradata FastLoad received a
CLIv2 error.
• Error code—4-byte unsigned integer
11
Teradata Database error Teradata FastLoad received a
Teradata Database error that
will produce an exit code of
12.
• Error code—4-byte unsigned integer
Data Passed to the Notify Exit Routine
Records read—4-byte unsigned integer
Records skipped—4-byte unsigned integer
Records rejected—4-byte unsigned integer
Records sent to the Teradata Database—4-byte
unsigned integer
Note: Not all Teradata
Database errors cause this
event. An Error 3807, for
example, while trying to drop
or create a table does not
terminate Teradata FastLoad.
68
Teradata FastLoad Reference
Chapter 2: Using Teradata FastLoad
INMOD and Notify Exit Routines
Table 18: Events Passed to the Notify Exit Routine (continued)
Event
Code
Event
Event Description
Data Passed to the Notify Exit Routine
12
Exit
FastLoad is terminating.
• Exit code—4-byte unsigned integer
Teradata FastLoad Sample INMOD Routines
Teradata FastLoad software includes two sample INMOD routines that demonstrate how to
write an INMOD routine using the C programming language.
Table 19 describes these sample routines.
Table 19: Sample INMOD Routines
Routine
Description
BLKEXITR.C
Retrieves records from a data source and supplies them to Teradata
FastLoad. It runs continuously until it reaches EOF.
Note: The BLKEXITR.C sample INMOD routine supports Teradata
FastLoad restart operations.
BLKEXIT.C
Generates data internally and passes the records to a Teradata FastLoad
job for processing. To use this sample INMOD routine, supply a Teradata
FastLoad job to load the data to the Teradata Database.
Note: The BLKEXIT.C sample INMOD routine does not support
Teradata FastLoad restart operations.
The next two subsections provide sample Teradata FastLoad job scripts for calling the sample
Teradata FastLoad INMOD routines. As required, each job script includes a Teradata
FastLoad DEFINE command that specifies the INMOD option.
These jobs can execute either interactively or in batch, as described earlier in this chapter.
For a complete listing of each sample INMOD routine, see Appendix C: “INMOD and Notify
Exit Routine Examples.”
Calling BLKEXIT.C
The following Teradata FastLoad job script calls the BLKEXIT.C sample INMOD routine:
SESSIONS 1 ;
LOGON tdpid/username,password ;
DROP TABLE Fastest ;
DROP TABLE Fasterr1 ;
DROP TABLE Fasterr2 ;
CREATE TABLE FastTest
(Column1 Integer Format ’9(5)’
NOT NULL BETWEEN 1 AND 9999) UNIQUE PRIMARY INDEX
(Column1) ;
DEFINE Test(Integer) INMOD=Blkexit ;
BEGIN LOADING FastTest ERRORFILES Fasterr1,
Fasterr2 ;
INSERT INTO FastTest (Column1) VALUES
(:test);
Teradata FastLoad Reference
69
Chapter 2: Using Teradata FastLoad
INMOD and Notify Exit Routines
END LOADING ;
LOGOFF ;
Calling BLKEXITR.C
The following Teradata FastLoad job script calls the BLKEXITR.C sample INMOD routine:
* use your own account and password here. *
LOGON sia1/weekly, weekly;
DROP TABLE Error_1;
DROP TABLE Error_2;
DROP TABLE BlkExit;
CREATE TABLE BlkExit
Counter(Integer),
c2(smallint),
c3(integer),
c4(smallint),
c5(integer)
UNIQUE PRIMARY INDEX (Counter);
BEGIN LOADING BlkExit ErrorFiles Error_1, Error_2;
DEFINE Counter(Integer),
c2(smallint),
c3(integer),
c4(smallint),
c5(integer)
INMOD = BLKEXIT;
INSERT INTO BlkExit (Counter,
c2,
c3,
c4,
c5
)
VALUES (:Counter,
:c2,
:c3,
:c4,
:c5
);
END LOADING;
LOGOFF;
Creating Custom INMOD Routines
To meet specific system needs, either write custom INMOD routines, or modify the sample
Teradata FastLoad INMOD routines to:
•
Select only records that meet specific criteria
•
Convert certain fields to a different data type
•
Perform other functions, as required
Whenever a new INMOD routine is created, or modify an existing the new or modified
routine must be compiled and linked into a shared object for use by Teradata FastLoad.
Note for UNIX operating system users: Teradata FastLoad 6.0 and later uses dynamic linking
to load INMOD routines at run time. As a result, any INMOD routines created or modified
under earlier versions of the utility must be recompiled and re-linked.
70
Teradata FastLoad Reference
Chapter 2: Using Teradata FastLoad
Teradata FastLoad Job Scripts
For procedures and examples of compiling and linking INMOD routines, see Appendix C:
“INMOD and Notify Exit Routine Examples.”
Teradata FastLoad Job Scripts
This section describes the contents of the Teradata FastLoad job script and explains how to
write one.
Definition
A Teradata FastLoad job script, or program, is a set of Teradata FastLoad commands and
Teradata SQL statements that actually load the data from the input data source or INMOD
routine into the Teradata FastLoad table on the Teradata Database.
Before running Teradata FastLoad in batch mode, a standard input file must be created that
contains the Teradata FastLoad job script. Then use the appropriate input file specification to
identify the standard input file when invoking Teradata FastLoad:
•
< infilename specification on network-attached client systems
•
SYSIN DDNAME specification on channel-attached z/OS client systems
Enter Teradata FastLoad Commands
Teradata FastLoad accepts the Teradata FastLoad commands and a subset of Teradata SQL
statements described in Chapter 3: “Teradata FastLoad Commands.”
Though the command keywords are all shown in uppercase characters in the syntax diagrams,
the commands are not case sensitive. Use either uppercase or lowercase letters when typing
the commands.
When running Teradata FastLoad in interactive mode, wait for the Teradata FastLoad
command prompt before entering a Teradata FastLoad command:
FastLoad - Enter your command:
Teradata FastLoad Job Script Example
The following example Teradata FastLoad job script provides an overview of a typical
Teradata FastLoad operation:
SESSIONS 4;
RECORD 100 THRU 100000;
ERRLIMIT 25;
LOGON tdpid/userid,password
DROP TABLE FastTable;
DROP TABLE Error1;
DROP TABLE Error2;
CREATE TABLE FastTable, NO FALLBACK
( ID INTEGER, UFACTOR INTEGER, MISC CHAR(42))
PRIMARY INDEX(ID);
DEFINE ID (INTEGER), UFACTOR (INTEGER), MISC (CHAR(42))
Teradata FastLoad Reference
71
Chapter 2: Using Teradata FastLoad
Teradata FastLoad Job Scripts
FILE=FileName;
SHOW;
BEGIN LOADING FastTable ERRORFILES Error1,Error2
CHECKPOINT 10000;
INSERT INTO FastTable (ID, UFACTOR, MISC) VALUES
(:ID, :MISC);
END LOADING;
LOGOFF;
Table 20 describes the commands used in this sample script.
Table 20: FastLoad Entering Commands
Command
Description
SESSIONS
Directs Teradata FastLoad to log on to the Teradata Database for up to four
sessions.
RECORD
Directs Teradata FastLoad to begin reading data at record 100 in the input
data source and stop reading records at record 100,000.
ERRLIMIT
Directs Teradata FastLoad to stop processing when 25 errors occur.
LOGON
Logs the specified user on to the Teradata Database for up to four sessions, as
specified in the SESSIONS command.
DROP TABLE
Makes sure that the Teradata FastLoad table and the two error tables do not
already exist on the Teradata Database.
Teradata FastLoad will not run if the two error tables exist from a prior job.
And, though the Teradata FastLoad table can be an existing table, it must be
empty. Thus, instead of deleting an existing Teradata FastLoad table, use the
DELETE statement to remove all the rows.
CREATE TABLE
Creates the Teradata FastLoad table on the Teradata Database.
DEFINE
Defines the data fields in each record and identifies the input data source.
This command corresponds to a Teradata SQL USING clause.
SHOW
Displays the active definitions for the input data source and the field names
that were specified in the previous DEFINE command. This command allows
the exact definitions in effect during the Teradata FastLoad operation to be
verified.
BEGIN LOADING
Begins the loading phase of the Teradata FastLoad job. This command
specifies the name of the Teradata FastLoad table and the two error tables,
and, in this example, specifies that a checkpoint be taken every 10,000
records.
INSERT
Sends input data records to the Teradata Database and inserts rows into the
Teradata FastLoad table. Teradata FastLoad processes the data records by:
1 Packaging them into large data blocks
2 Transferring them to the Teradata Database, where they are distributed to
the AMPs
72
Teradata FastLoad Reference
Chapter 2: Using Teradata FastLoad
Run Multifile Teradata FastLoad Jobs
Table 20: FastLoad Entering Commands (continued)
Command
Description
END LOADING
Directs the Teradata Database to redistribute (hash) the rows of data on the
AMPs and store them in the Teradata FastLoad table.
Upon successful completion, Teradata FastLoad returns a status message that
displays the total number of:
• Records read
• Records skipped
• Records sent to the Teradata Database
• Records inserted as rows in the Teradata FastLoad table
• Error records in the two error tables
• Duplicate rows
LOGOFF
Logs off all Teradata FastLoad sessions, terminates Teradata FastLoad, and
presents the system command prompt.
Run Multifile Teradata FastLoad Jobs
This section covers the things to consider when running a multifile Teradata FastLoad job.
A multifile Teradata FastLoad job is one that loads the Teradata FastLoad table with input
data from more than one source. Do this by:
1
Using a LOGOFF command, with no END LOADING command, to intentionally pause
the Teradata FastLoad job after the job has been initiated and loaded the data from the
first source.
2
Successively restarting and pausing the Teradata FastLoad job to load the data from each
subsequent input source.
3
Using an END LOADING command to terminate the Teradata FastLoad job after the data
from the last input source has been loaded.
Note: When running a multifile Teradata FastLoad job, the Teradata FastLoad table and the
two error tables remain locked and are not available to users until the END LOADING
command is used to conclude the Teradata FastLoad job.
The following subsections provide example Teradata FastLoad job scripts that show how to
load a table called Fast_Table with data stored in three different input data sources—FirstFile,
SecondFile, and ThirdFile. “Command Functions” on page 75 describes each of the commands
in the three job scripts.
For a complete example using all loading commands, see Appendix C: “INMOD and Notify
Exit Routine Examples.”
Teradata FastLoad Reference
73
Chapter 2: Using Teradata FastLoad
Run Multifile Teradata FastLoad Jobs
Initiate the Teradata FastLoad Job and Loading the First Data Source
The following Teradata FastLoad job script begins the multifile Teradata FastLoad job and
loads data from the data source named FirstFile into the Teradata FastLoad table:
LOGON tdpid/jwt,smart ;
DROP TABLE Fast_Table ;
DROP TABLE Error_1 ;
DROP TABLE Error_2 ;
CREATE TABLE Fast_Table (col1 (char(5),
col2(integer)) ;
BEGIN LOADING Fast_Table ERRORFILES Error_1, Error_2 ;
DEFINE Field_1 (char(5)), Field_2 (integer)
FILE = FirstFile ;
INSERT INTO Fast_Table (col1, col2) VALUES
(:Field_1, :Field_2) ;
LOGOFF ;
Note: These examples do not use a RECORD command to specify a range of records in the
input data sources. By default, they load the entire contents of each source into the Teradata
FastLoad table. To specify a range of records, use a RECORD command before each INSERT
statement in multifile Teradata FastLoad job scripts.
Restart the Teradata FastLoad Job and Loading the Second Data Source
The following Teradata FastLoad job script loads the Teradata FastLoad table shown in the
previous example with data from the data source named SecondFile:
LOGON tdpid/jwt,smart ;
BEGIN LOADING Fast_Table ERRORFILES Error_1, Error_2 ;
DEFINE Field_1 (char(5)), Field_2 (integer)
FILE = SecondFile ;
INSERT INTO Fast_Table (col1, col2)
VALUES (:Field_1, :Field_2) ;
LOGOFF ;
Restart the Teradata FastLoad Job and Loading the Third Data Source
The following Teradata FastLoad job script loads the Teradata FastLoad table shown in the
previous examples with data from the data source named ThirdFile:
LOGON tdpid/jwt,smart ;
BEGIN LOADING Fast_Table ERRORFILES Error_1, Error_2 ;
DEFINE Field_1 (char(5)), Field_2 (integer)
FILE = ThirdFile ;
INSERT INTO Fast_Table (col1, col2)
VALUES (:Field_1, :Field_2) ;
LOGOFF ;
Terminate the Teradata FastLoad Job
Sending the END LOADING command is the last step in a multifile Teradata FastLoad job.
Include it in the job used to process the last input data source, or submit it as a separate job
script.
74
Teradata FastLoad Reference
Chapter 2: Using Teradata FastLoad
Run Multifile Teradata FastLoad Jobs
The following Teradata FastLoad job script issues the END LOADING command in a separate
job script:
LOGON tdpid/jwt,smart ;
BEGIN LOADING Fast_Table ERRORFILES Error_1, Error_2 ;
END LOADING ;
LOGOFF ;
Command Functions
Table 21 describes the multifile Teradata FastLoad job scripts from the preceding example.
Table 21: Teradata FastLoad Terminating Commands
Command
Description
BEGIN LOADING
Specifies the name of the Teradata FastLoad table and the two error tables,
and starts the loading phase of the Teradata FastLoad job
After executing the BEGIN LOADING command in the Teradata FastLoad
job script that initiates the job and loads the first data source, the Teradata
FastLoad response signifies the start of a new job:
BEGIN LOADING COMPLETE
In subsequent multifile Teradata FastLoad job scripts, the Teradata FastLoad
response is:
FastLoad is continuing
a multifile job.
CREATE TABLE
Creates a new Teradata FastLoad table, ensuring it is empty when the
Teradata FastLoad job initiates
DEFINE
Identifies the field in each record to be inserted into the Teradata FastLoad
table and specifies the name of the input data source
The field names should be the same for all of the multifile Teradata FastLoad
job scripts.
The FILE= attribute, however, successively identifies a different source data
source for each portion of the multifile Teradata FastLoad job.
DROP TABLE
Makes sure that the Teradata FastLoad table and the two error tables do not
already exist on the Teradata Database when the Teradata FastLoad job
initiates
END LOADING
Distributes all of the rows to the Teradata FastLoad table
The following message indicates that the command executed successfully:
END LOADING COMPLETE
Note: At this point, the Teradata FastLoad table and the two error tables are
unlocked and available to any user with the appropriate privileges.
INSERT
Transfers the data records from the specified input data source to the
Teradata FastLoad table
The Teradata Database automatically takes a checkpoint after the last record
of each insert operation.
Teradata FastLoad Reference
75
Chapter 2: Using Teradata FastLoad
Handling Teradata FastLoad Errors
Table 21: Teradata FastLoad Terminating Commands (continued)
Command
Description
LOGOFF
Pauses the Teradata FastLoad operation when executed before an END
LOADING command, which is the case for each multifile Teradata FastLoad
job script that identifies a new data source
Because the LOGOFF command is entered during the loading phase,
Teradata FastLoad responds with the message:
FastLoad Paused.
When a Teradata FastLoad job is paused during the loading phase, the tables
remain locked and cannot be accessed until Teradata FastLoad executes the
END LOADING command.
When submitted after an END LOADING command, as in the last multifile
Teradata FastLoad job script, the LOGOFF command terminates the
Teradata FastLoad job. In this case, Teradata FastLoad displays:
logoff;
and an end-of-job status message, such as:
**** 14:16:58 Logging off all sessions
**** 14:16:59 Total processor time used = '0.33 Seconds'
.
Start : Mon Aug 0114:16:49 2010
.
End
: Mon Aug 01 14:16:59 2010
.
Highest return code encountered = '0'.
**** 14:16:59 FDL4818 FastLoad Terminated
and then presents the system command prompt.
LOGON
Logs user JWT on to the Teradata Database
Handling Teradata FastLoad Errors
This section provides information about handling Teradata FastLoad errors.
Teradata FastLoad Error Conditions
While processing a Teradata FastLoad job script, Teradata FastLoad tracks and records
information about five types of error conditions that cause the Teradata Database to reject an
input data record. Table 22 describes these error conditions.
Table 22: Error Conditions that Cause Teradata Database to Reject an Input Data Record
76
Error Conditions
Description
Constraint violations
Records from the input file that do not comply with the range
constraints that were specified in the CREATE TABLE statement.
Conversion errors
Records from the input file that fail a data type conversion that
was specified in the DEFINE command.
Duplicate rows
Records from the input file that are exact duplicates of existing
rows.
Teradata FastLoad Reference
Chapter 2: Using Teradata FastLoad
Handling Teradata FastLoad Errors
Table 22: Error Conditions that Cause Teradata Database to Reject an Input Data Record (continued)
Error Conditions
Description
Unavailable AMP conditions
Records from the input file that are destined for a nonfallback
table on an AMP that is down.
Unique primary index violations
Records from the input file that have a value for the unique
primary index field that already exists, but is not a duplicate row.
Note: Teradata FastLoad does not store duplicate rows in an error table.
Additionally, when operating in batch mode, Teradata FastLoad returns the system error
codes for error conditions encountered during Teradata FastLoad operations. (Teradata
FastLoad does not return system error codes when operating in interactive mode.) This
subsection describes the procedures for handling the five types of Teradata FastLoad error
conditions.
Messages reference documentation contains more information about system error messages.
Error Recording
Teradata FastLoad stores the input data records related to constraint violations, conversion
errors, unavailable AMP conditions, and unique primary index violations in the two error
tables specified in the BEGIN LOADING command.
Table 23 lists error tables.
Table 23: Error Tables
Table
Stores Records That Produced These Error Types
errortname1
• Constraint violations
• Conversion errors
• Unavailable AMP conditions
These types of errors always occur during the loading phase of the
Teradata FastLoad job—after executing the BEGIN LOADING
command, but before the END LOADING command.
errortname2
Unique primary index violations
This type of error always occurs during the end-loading phase of the
Teradata FastLoad job—after executing the END LOADING command.
Teradata FastLoad discards all records that produce a duplicate row error, but includes the
total number of duplicate rows encountered, along with the total records in each error table,
in the end-of-job status report.
Error Table Formats
Table 24, the first error table, errortname1, has three columns:
Teradata FastLoad Reference
77
Chapter 2: Using Teradata FastLoad
Handling Teradata FastLoad Errors
Table 24: errortname1 Columns
Column
Contains
DataParcel
Entire data record, as provided by the source producer operator
DataParcel is used as the primary index for the first error table. The data record
string can be up to 64,000 bytes, depending on which version of the DBS the job is
run against.
ErrorCode
Teradata Database return code for the error condition, as specified in the
Messages reference documentation
ErrorFieldName
Name of the data item that caused the error condition, as specified in the
fieldname attribute of the DEFINE command in the Teradata FastLoad job script
The format of the second error table, errortname2, is identical to that of the Teradata FastLoad
target table.
Correcting Errors
Though the procedures are somewhat different, depending on the error table, correcting
errors is a three-step process, where:
1
The error information is retrieved from the error tables on the Teradata Database.
2
Errors are evaluated and correct ed.
3
Corrected records are inserted into the Teradata FastLoad table.
After the job has completed, another utility must be used—such as BTEQ—to access the
Teradata Database, because Teradata FastLoad only operates on an empty table. The
procedures and examples in the following subsections are performed under BTEQ. They
assume BTEQ has been invoked and logged on to the Teradata Database. For more
information about using BTEQ, see Basic Teradata Query Reference.
Procedure for Correcting Errors in the First Error Table
Use the following procedure to correct errors recorded in the error table specified as
errortname1:
1
Use the following Teradata SQL statement to retrieve the error code and field name for
each error in the first error table:
SELECT ErrorCode, ErrorFieldName FROM
ErrorCode ;
errortname1 ORDER BY
where errortname1 is the name specified for the first error table.
BTEQ responds with a list of the error codes and the associated field names, formatted as
follows:
***Query completed. 2 rows found. 2 columns returned.
***Total elapsed time was 1 second.
ErrorCode
ErrorFieldName
-------------------------2679
A
78
Teradata FastLoad Reference
Chapter 2: Using Teradata FastLoad
Handling Teradata FastLoad Errors
2679
A
The values listed in the ErrorCode column are the Teradata Database return codes for
each error condition, as specified in the Messages reference documentation.
The values listed in the ErrorFieldName column are the names of the fields that caused
each error.
2
Use the following BTEQ commands and Teradata SQL statements to retrieve the data
records for each error in the first error table and store them in the specified err.out file on
the client system:
•
If the values in the ErrorCode column indicate that either a constraint violation or a
conversion error occurred, retrieve the DataParcel information in record mode:
.SET RECORDMODE ON
.EXPORT DATA FILE=err.out
SELECT DataParcel FROM errortname1
In record mode, the Teradata Database returns the SELECT statement results in client
computer format, which is usually a hexadecimal dump. Thus, if all of the fields
identified in the Teradata FastLoad DEFINE commands were also specified in the
INSERT statements, the data retrieved from the Teradata FastLoad error table is in the
same format as it was in the original input data source.
•
Otherwise, if the values in the ErrorCode column indicate that the errors were all
caused by unavailable AMP conditions, do not use the RECORDMODE command:
.EXPORT DATA FILE=err.out
SELECT DataParcel FROM errortname1
Caution:
3
Use the ErrorCode and ErrorFieldName information returned in Step 1 and the
DataParcel information returned in Step 2 to determine which records to correct and
reload to the Teradata Database. The methods used to correct the individual error
conditions will vary, depending on the number and types of errors.
4
After the errors have been corrected, use the following BTEQ commands and Teradata
SQL statements to insert the corrected records into the Teradata FastLoad table on the
Teradata Database.
To
Use the
transfer the data to the Teradata Database
BTEQ IMPORT command
define the fields in each record
Teradata SQL USING modifier
insert a record into the Teradata FastLoad
table
Teradata SQL INSERT statement
Do not reference the first two bytes in the INSERT statement for data records that were
exported from the Teradata Database in record mode. Instead, make the first field (variable
parameter) in the USING modifier a dummy SMALLINT field.
When selecting data in record mode, the variable-length columns are all preceded by a
two-byte field whose value indicates the length of the data field. But, because the
DataParcel column of the errortname1 table is defined as a variable-length field, the first
Teradata FastLoad Reference
79
Chapter 2: Using Teradata FastLoad
Handling Teradata FastLoad Errors
two bytes always indicate the length. If this field is not referenced in the INSERT
statement, the Teradata Database ignores this portion of each record in the input data.
5
Repeat steps 2 through 4 as required to resolve all of the errortname1 error conditions.
6
Drop the errortname1 table from the Teradata Database after all of the errors have been
resolved.
Procedure for Correcting Errors in the Second Error Table
Use the following procedure to correct errors recorded in the error table specified as
errortname2:
1
Use the following Teradata SQL statement to retrieve all rows from the second error table:
SELECT * FROM errortname2 ORDER BY cname ;
where:
Syntax Element
Description
cname
Unique primary index for the table
errortname2
Name of the second error table
The BTEQ response is a list of the contents of the second error table, ordered by the values
in the primary index column.
2
Use the following Teradata SQL statement to retrieve each row from the Teradata
FastLoad table that has a primary index value identical to a row retrieved from the second
error table:
SELECT * FROM tname WHERE cname = errorvalue
where:
3
80
Syntax Element
Description
cname
Index of the Teradata FastLoad table
errorvalue
index value retrieved from the second error table
tname
Name of the Teradata FastLoad table
Compare the rows selected from the error table with the rows selected from the Teradata
FastLoad table and determine which is correct.
•
If the row selected from the error table is correct, then use a Teradata SQL DELETE
statement to delete the incorrect row from the Teradata FastLoad table, and an INSERT
statement to insert the correct row.
•
If the row selected from the Teradata FastLoad table is correct, then use a Teradata
SQL DELETE statement to delete the corresponding row from the error table.
4
Repeat Steps 2 and 3 until all rows in the error table are accounted for.
5
Drop the errortname2 table from the Teradata Database after all errors have been resolved.
Teradata FastLoad Reference
Chapter 2: Using Teradata FastLoad
FastLoad TMSM Integration
FastLoad TMSM Integration
Teradata Multi-System Manager (TMSM) is the monitoring and control facility for a variety
of Dual Active Solutions offered by Teradata. The expected users of this facility are
administrators of the Enterprise Data Warehouse (EDW) such as Teradata Database
administrators, ETL maintenance staff, systems administrators, or anyone who needs to
monitor and control processes that include, but are not limited to, Teradata Load and Unload
Utilities, Teradata SQL, ETL tools, and Teradata Database.
To integrate with TMSM, FastLoad has been enhanced to collect operational metadata and
event data, obtain the Unit of Work ID (UOW ID) from TMSM for a job, and send such data
to TMSM for monitoring purposes using the “send event” interface as described in the TMSM
Event System API Reference. By default, a FastLoad job will send events to TMSM as long as
TMSM is active. If TMSM is not active, the job will continue to run, except that no events will
be sent to TMSM.
Simple ETL process monitoring requires the tracking of the “start” and “end” of the process,
which can include multiple “steps”, each of which represents an activity or event of the
process to be monitored. In terms of FastLoad, a load job can be regarded as such a process.
FastLoad follows the flow required by TMSM:
1
Obtain a system-generated UOW ID from TMSM for a FastLoad job
2
Send a “start” event to TMSM along with the UOW ID
3
Optionally send one or more “step” events to TMSM along with the UOW ID
4
Send an “end” event to TMSM along with the UOW ID
Below is an example of how a FastLoad job sends event messages to TMSM in order for the
job to be monitored:
•
At job start: “Connecting session(s)”
•
At step start of acquisition: “Acquisition begins”
•
At step checkpoint time: “Checkpoint completes”
•
At step end of acquisition: “Acquisition completes”
•
At step end of application: “Application complete”
•
At job end: “Job terminating”
Teradata FastLoad Reference
81
Chapter 2: Using Teradata FastLoad
FastLoad TMSM Integration
82
Teradata FastLoad Reference
CHAPTER 3
Teradata FastLoad Commands
This chapter provides detailed descriptions of the Teradata FastLoad commands and the
Teradata FastLoad version of the INSERT statement which can be executed from the Teradata
FastLoad utility.
Teradata FastLoad accepts both Teradata FastLoad commands and a subset of Teradata SQL
statements. The Teradata FastLoad commands perform session control and data handling
activities. The Teradata SQL statements define and manipulate the data stored in the Teradata
Database.
Experienced users can also refer to the simplified command descriptions in the Teradata
FastLoad chapter of Teradata Tools and Utilities Command Summary. This book provides the
syntax diagrams for each Teradata client utility.
Syntax Notes
The following syntax rules apply when using Teradata FastLoad commands:
•
Commands may begin with a period, but do not have to begin with a period.
•
If there is no leading period, then there must be a semicolon at the end.
•
If the command has a leading period, it must all be on one line. Commands that begin
with a period cannot span multiple lines.
•
Although a semicolon character should always be used to signify the end of a Teradata
FastLoad command, it is not required for simple commands such as SHOW and
SESSIONS.
•
The ending semicolon character is optional for Teradata FastLoad commands that both
begin with a period and are specified on a single line.
•
Teradata SQL statements must not have a leading period and must always end with a
semicolon.
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 FastLoad command.
•
30 bytes cannot be used as the quoted object name length.
•
Dictionary (UDD) object names cannot be used.
Teradata FastLoad Reference
83
Chapter 3: Teradata FastLoad Commands
Syntax Notes
See Appendix A: “How to Read Syntax Diagrams” for a description of how to read the syntax
diagrams used in this book.
Geospatial Data Restrictions
The following rule applies to geospatial data:
•
84
Teradata FastLoad does not support ST_Geometry geospatial data.
Teradata FastLoad Reference
Chapter 3: Teradata FastLoad Commands
AXSMOD
AXSMOD
Purpose
The AXSMOD command specifies the name and optional initialization string for an access
module that provides data to the Teradata FastLoad utility on network-attached client
systems. For more information about specific access modules, see Teradata Tools and Utilities
Access Module Reference.
Syntax
;
AXSMOD name
"init-string"
2411A014
where
Syntax Element
Description
init-string
Optional initialization string for the access module.
name
Name of the access module file to be used to import data. These access
modules include:
• OLE DB Access Module: oledb_axsmod.dll on Windows platforms
• Named Pipes Access Module: See table, “AXSMOD Specifications for
Teradata Named Pipes Access Module”, in the “Named Pipes Access
Module” chapter of Teradata Tools and Utilities Access Module Reference
B035-2425 for the name of the access module file for each platform.
• Teradata WebSphere® MQ Access Module (client version): See table,
“AXSMOD Specifications for Teradata WebSphere MQ Access Module”,
in the “Teradata WebSphere MQ Access Module” chapter of Teradata
Tools and Utilities Access Module Reference B035-2425 for the name of the
access module file for each platform.
• Teradata WebSphere®MQ Access Module (server version): See table,
“AXSMOD Specifications for Teradata WebSphere MQ Access Module”,
in the “Teradata WebSphere MQ Access Module” chapter of Teradata
Tools and Utilities Access Module Reference B035-2425 for the name of the
access module file for each platform.
Teradata FastLoad Reference
85
Chapter 3: Teradata FastLoad Commands
AXSMOD
Syntax Element
Description
A personal shared library file name can be used if custom access module is
used.
The AXSMOD option is not required for importing disk files on either
network-attached or channel-attached client systems, or 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.
To specify the OLE DB Access Module, Named Pipes Access Module, or the
WebSphere MQ Access Module for specific platforms, seeTeradata Tools and
Utilities Access Module Reference.
Usage Notes
Table 25 describes the things to consider when using the AXSMOD command.
Table 25: Usage Notes for AXSMOD
Topic
Usage Notes
When to Use the
AXSMOD
Command
The AXSMOD command is not required for loading:
Command
Placement
When using an access module, the AXSMOD command must be stated before
the DEFINE command in the Teradata FastLoad job script. If the AXSMOD
command is stated after the DEFINE command, Teradata FastLoad
terminates with an error message.
• Disk files on either network or channel-attached client systems
• Magnetic tape files on channel-attached client systems
It is required for loading magnetic tape and other types of files on networkattached client systems.
Example
The following example provides the volume set name and owner as initialization parameters
for the REELlibrarian access module, called libprmrl.so:
AXSMOD libpmrl.so “-V FastLoad -O lmn” ;
where
86
•
libpmrl.so is the name of the access module
•
FastLoad is the name of the volume set
•
lmn is the owner of the volume set
Teradata FastLoad Reference
Chapter 3: Teradata FastLoad Commands
BEGIN LOADING
BEGIN LOADING
Purpose
The BEGIN LOADING command:
•
Identifies the Teradata FastLoad table to receive data transferred from a data source on the
client computer.
•
Specifies the names of the two error tables.
•
Starts a new Teradata FastLoad job or restarts a job that has been paused.
•
Locks the tables specified in the command so that users cannot access them until an END
LOADING command is executed. (After the end loading phase completes, any user with
the appropriate privileges can access these tables.)
•
Optionally:
•
Indicates how often checkpoints are taken.
•
Identifies the presence of null indicators.
Syntax
BEGIN LOADING
A ERRORFILES
dbname.
dbname.
errortname1,
dbname.
tname1
A
errortname2
B
;
B
NODROP
CHECKPOINT integer
DATAENCRYPTION value
INDICATORS
2411C011
where
Syntax Element
Description
dbname
Name of the database in which each table resides.
Teradata FastLoad uses the current default database if a database name is
not included with the table name specifications.
To refer to more than one database, include the database name with the
table name specifications.
tname1
Name of the Teradata FastLoad target table to receive the data from the
client system.
A name that duplicates the name of an existing table cannot be used
unless restarting a paused Teradata FastLoad job. The name must be a
new table name.
Teradata FastLoad Reference
87
Chapter 3: Teradata FastLoad Commands
BEGIN LOADING
Syntax Element
Description
errortname1
Name of the first error table.
A name that duplicates the name of an existing table cannot be used
unless restarting a paused Teradata FastLoad job. The name must be a
new table name.
errortname2
Name of the second error table.
A name that duplicates the name of an existing table cannot be used
unless restarting a paused Teradata FastLoad job. The name must be a
new table name.
CHECKPOINT
Enables the checkpoint option.
integer
Value that specifies the number of rows transmitted to the Teradata
Database between checkpoints using the CHECKPOINT keyword to
enable the checkpoint option.
(The checkpoint option is not enabled if it is not included the
CHECKPOINT keyword in the BEGIN LOADING command.)
For more information about specifying the CHECKPOINT integer value,
see the Checkpoints topic under “Usage Notes.”
INDICATORS
Places null indicator bits at the front of each record.
The number of fields in each record determines how many bytes contain
null indicators, as described in the Indicators topic under “Usage Notes”
for this command.
Note: The INDICATORS specification cannot be used when loading
records in variable-length text format. If the Teradata FastLoad job script
specifies INDICATORS in the BEGIN LOADING command and the
VARTEXT option in the SET RECORD command, the utility terminates
with an error message.
DATAENCRYPTION
value
Enables data encryption for a Teradata FastLoad job.
The options for value are:
• ON = The requests will be encrypted.
• OFF = The requests will not be encrypted.
This option will apply only to the BEGIN LOADING request and the
requests after the BEGIN LOADING command.
Using this option overwrites the data encryption settings specified by
both the runtime parameters and in the floadcfg.dat configuration file.
NODROP
Retains the error table at the end of a job, even if the error table is empty.
Caution:
When using this option, be careful to manually drop all error
tables before running additional jobs that use the same tables.
Failure to do so results in Teradata Database errors.
(Default) If this option is not specified, the error table is dropped at the
end of a job if the error table is empty.
Usage Notes
Table 26 describes the things to consider when using the BEGIN LOADING command.
88
Teradata FastLoad Reference
Chapter 3: Teradata FastLoad Commands
BEGIN LOADING
Table 26: Usage Note for BEGIN LOADING
Topic
Usage Notes
Required Privileges
The user ID that is logged in to the Teradata FastLoad job must have:
• SELECT and INSERT privileges on the Teradata FastLoad table
• CREATE TABLE privilege on the database that owns the two error
tables
Restart Log Table
To run Teradata FastLoad, the following privileges must be available to
user PUBLIC on the Teradata FastLoad restart log table
(SYSADMIN.FASTLOG):
•
•
•
•
Error Tables
Descriptions
DELETE
INSERT
SELECT
UPDATE
Teradata FastLoad creates two error tables when executing the BEGIN
LOADING command:
• The error table specified by errortname1 contains records that were
rejected because of an error other than unique primary index or
duplicate row violation.
• The error table specified by errortname2 contains records that violated
the unique primary index constraint.
Duplicate Records
The Teradata Database ignores duplicate records, which are not inserted
in either error table.
Reusing Table Names
If an error table has one or more rows, it is not dropped from the Teradata
Database at the end of a Teradata FastLoad job. To reuse the names
specified for the error tables, use the DROP TABLE statement to remove
the tables from the Teradata Database.
For more information, see “Error Recording” on page 77.
Checkpoints
The CHECKPOINT option defines points in a job where Teradata
FastLoad pauses to record that the Teradata Database has processed a
specified number of input records. When checkpoints are used, the entire
Teradata FastLoad job need not be run if it stops before completion.
Teradata FastLoad uses the checkpoint information in the restart log table
to determine the restart location.
When specifying the integer value for the CHECKPOINT option:
• If zero is entered as the value, Teradata FastLoad processes the BEGIN
LOADING command as if a CHECKPOINT value is not entered.
• If a value is not entered, or if a value is entered that is not an integer,
the Teradata Database returns a syntax error.
For more information, see “Checkpoint Tradeoffs” on page 57.
Teradata FastLoad Reference
89
Chapter 3: Teradata FastLoad Commands
BEGIN LOADING
Table 26: Usage Note for BEGIN LOADING (continued)
Topic
Usage Notes
Indicators
Indicators are bits at the beginning of a record that identify the nulled
fields in the record. When INDICATORS in the BEGIN LOADING
command are specified, Teradata FastLoad expects the first bytes of the
record to contain an indicator bit for each record field.
If the INDICATORS option is set but indicator bits are not entered at the
beginning of the record, Teradata FastLoad assumes that the first field
contains indicator bytes and loads the record incorrectly.
Indicator bits must be stored in a minimum of eight-bit bytes. For
example, if a record contains from one to eight fields, one byte is required
for the indicator bits. If a record contains from nine to 16 fields, two bytes
are required for the indicator bits, and so on.
Set unused bits in indicator bytes to zero.
Indicator Bit Positions
The positions of the indicator bits correspond to the record fields. The
first bit in the byte is the indicator for the first field in the record.
If an indicator bit is set to 1, the Teradata Database nulls the
corresponding field when the record is loaded. If the indicator bit is set to
zero, the Teradata Database loads the data specified for that field.
The following figure shows a record containing indicators.
These fields are nulled
01001000
00000000
F1 F2 F3
F4 F5 F6 F7 F8
....
F16
2411A015
See the following documents for more information about indicator bits
and the INDICATORS option:
• Teradata Call-Level Interface Version 2 Reference for Channel-Attached
Systems
• Teradata Call-Level Interface Version 2 Reference for Network-Attached
Systems
Example
The following command example starts a Teradata FastLoad job:
BEGIN LOADING Employee ERRORFILES ErrTable1,ErrTable2 CHECKPOINT 50000;
If the command is used to start a new job, then Teradata FastLoad responds:
BEGIN LOADING COMPLETE!
When BEGIN LOADING restarts a partially completed job, then Teradata FastLoad responds:
FastLoad is continuing a paused job!
If BEGIN LOADING is used to continue a multifile job, then Teradata FastLoad responds:
FastLoad is continuing a multifile job!
90
Teradata FastLoad Reference
Chapter 3: Teradata FastLoad Commands
CLEAR
CLEAR
Purpose
The CLEAR command cancels the definitions that were specified by a previous DEFINE
command, including the input data source.
Syntax
CLEAR
;
2411A016
Usage Notes
The CLEAR command is:
•
Local to Teradata FastLoad
•
Not transmitted to the Teradata Database
•
Intended for online use
Example
The following command example cancels the field definitions and input data source or
INMOD name of a previous DEFINE command:
CLEAR ;
Completion Message
The Teradata FastLoad completion message is:
Warning: All previous column and file definitions cleared!
If the SHOW command now is entered, the result is blank.
Teradata FastLoad Reference
91
Chapter 3: Teradata FastLoad Commands
DATEFORM
DATEFORM
Purpose
The DATEFORM command specifies the form of the DATE data type specifications for the
Teradata FastLoad job.
Syntax
DATEFORM
INTEGERDATE
ANSIDATE
;
2411A017
where
Syntax Element
Description
INTEGERDATE
Keyword that specifies integer DATE data types for the Teradata FastLoad
job.
This is the default Teradata DATE data type specification for Teradata
FastLoad jobs if a DATEFORM command is not entered.
ANSIDATE
Keyword that specifies ANSI fixed-length CHAR(10) DATE data types for
the Teradata FastLoad job.
Usage Notes
Table 27 describes the things to consider when using the DATEFORM command.
Table 27: Usage Notes for DATEFORM
Topic
Usage Notes
Command Placement
and Frequency
Only use one DATEFORM command.
Data Type Conversions
When the ANSIDATE specification is used, ANSI/SQL DateTime data
types must be converted to fixed-length CHAR data types when
specifying the column/field names in the Teradata FastLoad DEFINE
command.
The command must be entered before the LOGON command.
See “Usage Notes” for the DEFINE command description for a
description of the fixed-length CHAR representations for each DATE,
TIME, TIMESTAMP, and INTERVAL data type specification.
Release Applicability
92
The ANSIDATE specification is valid for Teradata FastLoad jobs.
Teradata FastLoad Reference
Chapter 3: Teradata FastLoad Commands
DEFINE
DEFINE
Purpose
The DEFINE command:
•
Describes the fields in a record of input data that are inserted in the Teradata FastLoad
table
•
Identifies the name of the input data source or use of an INMOD routine
Teradata FastLoad translates the DEFINE command specifications into a Teradata SQL
USING clause, and links the USING clause with a subsequent INSERT statement. The
Teradata FastLoad job must include DEFINE specifications for each field in a record from the
input data source before executing an INSERT statement.
Note: Though every field used in an INSERT statement must have been previously defined in
a DEFINE command, every field so defined need not be used in an INSERT statement.
Teradata FastLoad also uses the DEFINE command data type specifications to determine the
format and record length of stored data.
Syntax
A
DEFINE
,
DEF
fieldname (datatype
)
,NULLIF
value
=
;
A
= filename
FILE
DDNAME
INMOD = name
2411A018
where
Syntax Element
Description
fieldname
Name of a field in a record of the input data source, from left to right.
You cannot use FILE, DDNAME, or INMOD for a fieldname.
Note: Some or all of the field names can be omitted if the accompanying
INSERT statement uses the “wild card” table name specification
(tname.*) for all of the columns in the table. For the syntax of the
tname.* specification, see the INSERT statement description later in this
chapter.
Teradata FastLoad Reference
93
Chapter 3: Teradata FastLoad Commands
DEFINE
Syntax Element
Description
datatype
Keyword or keyword phrase that specifies the data type of the field.
For details on data types and data conversions, see SQL Data Types and
Literals.
The valid data types for records in a Teradata FastLoad table are:
BIGINT
BYTE (n)
BYTEINT
CHARACTERS (n)
DATE
DECIMAL (x) or DECIMAL (x,y)
FLOAT
GRAPHIC (n)
INTEGER
LONG VARCHAR
LONG VARGRAPHIC
PERIOD(DATE)
PERIOD(TIME[(n)])
PERIOD(TIME[(n)] WITH TIME ZONE)
PERIOD(TIMESTAMP[(n)])
PERIOD(TIMESTAMP[(n)] WITH TIME ZONE)
SMALLINT
VARBYTE (n)
VARCHAR (n)
VARGRAPHIC (n)
NULLIF=value
Keyword phrase that loads the Teradata Database field with a null value
if the defined client field contains the specified value.
The value specification can be 1 to 80 bytes in length, and it pertains only
to BYTE, CHAR and GRAPHIC types. It does not pertain to integer and
float data types.
The NULLIF option occurs only with the DEFINE command.
FILE=filename
Keyword phrase specifying the name of the data source that contains the
input data.
fileid must refer to a regular file. Specifically, pipes are not supported.
Note: For channel-attached systems, replace FILE with DDNAME for
z/OS. DDNAME is the sequential data set for z/OS.
INMOD=name
Keyword phrase specifying the name of a user exit routine that provides
input data records.
For more information about using INMOD routines, see “INMOD and
Notify Exit Routines” on page 63.
94
Teradata FastLoad Reference
Chapter 3: Teradata FastLoad Commands
DEFINE
Usage Notes
The following table describes the things to consider when using the DEFINE command.
•
Data Type Descriptions
Depending on the data type phrase of the CREATE TABLE statement, Teradata FastLoad
stores data with CHAR(n) and VARCHAR(n) data type specifications as follows:
•
•
•
When the DEFINE command data type attribute is CHAR(n) and the:
•
CREATE TABLE datadesc attribute is CHAR(n), Teradata FastLoad stores the data
in fixed-length format, entire field.
•
CREATE TABLE datadesc attribute is CHAR(m), Teradata FastLoad stores the
data in fixed-length format, padded if m > n, truncated if m < n.
•
CREATE TABLE datadesc attribute is VARCHAR(m), Teradata FastLoad stores
the data in variable-length format with blanks trimmed.
When the DEFINE command datatype attribute is VARCHAR(n) and the:
•
CREATE TABLE datadesc attribute is VARCHAR(m), Teradata FastLoad stores
the data in variable-length format, no padding, blanks not trimmed.
•
CREATE TABLE datadesc attribute is CHAR(m), Teradata FastLoad stores the
data in padded or truncated format, as required.
Input Length and Field Descriptions
Table 28 lists the input length and field description for each data type specification.
Note: In a UTF-16 session, a character size is 2 bytes. For CHAR(n) or VARCHAR(n)
field of the CREATE TABLE, the corresponding field size in DEFINE command must be
double, that is CHAR(n*2) or VARCHAR(n*2) respectively.
Note: In a UTF-8 session, a character size is from 1 to 3 bytes. For CHAR(n) or
VARCHAR(n) field of the CREATE TABLE, the corresponding field size in DEFINE
command must be triple, that is CHAR(n*3) or VARCHAR(n*3) respectively.
Table 28: Input Length and Field Descriptions
Data Type
Length
Description
BIGINT
8 bytes
64-bit signed binary
BYTE(n)
n bytes
n bytes
BYTEINT
1 byte
8-bit signed binary
CHAR, CHARS(n), and
CHARACTERS(n)
n bytes
n ASCII characters
DATE
4 bytes
32-bit integer in YYYMMDD format as a decimal value
Note: If a DATEFORM command has been used to
specify ANSIDATE as the DATE data type, Teradata
FastLoad internally converts each DATE field to a
CHAR(10) field.
Teradata FastLoad Reference
95
Chapter 3: Teradata FastLoad Commands
DEFINE
Table 28: Input Length and Field Descriptions (continued)
Data Type
Length
Description
DECIMAL(x) and DECIMAL(x,y)
1, 2, 4, 8, or 16 bytes for
network;
128-bit double precision, floating point
packed decimal for
mainframe
For more information on the DECIMAL data type, see
SQL Data Types and Literals.
FLOAT
8 bytes
64-bit, double precision, floating point
GEOSPATIAL DATA
maximum 64000
FastLoad does not support Geospatial data represented
by LOBs.
INTEGER
4 bytes
32-bit, signed binary
LONG VARCHAR
m + 2 characters where
m = 32000
16-bit integer, count m, followed by m ASCII
characters
Caution: LONG VARCHAR is interpreted as
VARCHAR (64000), which means that the
combination of the client-side session
character set and the server-side storage
character set can cause a LONG VARCHAR
specification in a DML USING clause to
mean something other than
VARCHAR(64000). Therefore, it is
recommended that LONG VARCHAR be
specified only if it is known that both the
server-side and client-side character sets are
single-byte.
PERIOD(DATE)
max=8 bytes
4-byte, signed integer flipped to client form. This
integer represents a date in the same manner as for a
DATE data type
(Example: (10000*(year-1900)) + (100*month) +
day).
precision (n/a)
The precision value specified must be between 0 and 6
inclusive.
PERIOD(TIME[(n)])
max =12 bytes
Second: 4-byte, signed integer flipped to client form.
This integer represents the number of seconds as a
scaled decimal.
Hour: 1 unsigned byte. This byte represents the
number of hours.
Minute: 1 unsigned byte to client form. This byte
represents the number of minutes
precision n
The precision value specified must be between 0 and 6
inclusive.
96
Teradata FastLoad Reference
Chapter 3: Teradata FastLoad Commands
DEFINE
Table 28: Input Length and Field Descriptions (continued)
Data Type
Length
Description
PERIOD(TIME[(n)] WITH TIME
ZONE)
max=16 bytes
Second: 4-byte, signed integer flipped to client form.
This integer represents the number of seconds as a
scaled decimal.
Hour: 1 unsigned byte. This byte represents the
number of hours.
Minute: 1 unsigned byte. This byte represents the
number of minutes.
Time Zone_Hour: 1 unsigned byte. This byte
represents the hours portion of the time zone
displacement along with whether the displacement is +
or -.
Time Zone Minute: 1 unsigned byte. This byte
represents the minutes portion of the time zone
displacement.
precision n
The precision value specified must be between 0 and 6
inclusive.
PERIOD(TIMESTAMP[(n)])
max=20 bytes
Second: 4-byte, signed integer flipped to client form.
This integer represents the number of seconds as a
scaled decimal.
Year: 2-byte, signed short integer flipped to client
form. This byte represents the year value.
Month: 1 unsigned byte. This byte represents the
month value.
Day: 1 unsigned byte. This byte represents the day of
the month.
Hour: 1 unsigned byte. This byte represents the
number of hours.
Minute: 1 unsigned byte. This byte represents the
number of minutes.
precision n
The precision value specified must be between 0 and 6
inclusive.
Teradata FastLoad Reference
97
Chapter 3: Teradata FastLoad Commands
DEFINE
Table 28: Input Length and Field Descriptions (continued)
Data Type
Length
Description
PERIOD(TIMESTAMP[(n)] WITH
TIME ZONE)
max=24 bytes
Second: 4-byte, signed integer flipped to client form.
This integer represents the number of seconds as a
scaled decimal.
Year: 2-byte, signed short integer flipped to client
form. This byte represents the year value.
Month: 1 unsigned byte. This byte represents the
month value.
Day: 1 unsigned byte. This byte represents the day of
the month.
Hour: 1 unsigned byte. This byte represents the
number of hours.
Minute: 1 unsigned byte. This byte represents the
number of minutes.
Time Zone_Hour: 1 unsigned byte. This byte
represents the time zone displacement in hours along
with whether the displacement is + or -.
Time Zone Minute: 1 unsigned byte. This byte
represents the time zone displacement in minutes.
precision n
The precision value specified must be between 0 and 6
inclusive.
SMALLINT
2 bytes
16-bit, signed binary
VARCHAR(n)
m + 2 bytes where m =
32000
16-bit integer, count m, followed by m ASCII
characters
VARBYTE(n)
m + 2 bytes where m <= 16-bit integer, count m, followed by m bytes of data
n
GRAPHIC(n)
(n*2) bytes, if n is
specified; otherwise, 2
bytes, as n = 1 is
assumed
n double-byte characters (1n is the length of the input
stream in terms of double-byte characters)
VARGRAPHIC(n)
m + 2 bytes where m/2
<= n
2-byte integer followed by m/2 double-byte characters
•
Note: For both VARGRAPHIC and LONG
VARGRAPHIC, m, a value occupying the first two
bytes of the input data, is the length of the input in
bytes, not characters. Each multibyte character-set
character is 2 bytes.
GRAPHIC Data Types
GRAPHIC data types define multibyte character set data. Teradata FastLoad accepts
GRAPHIC data in its input data when a site is defined for kanji.
The DEFINE command supports these types of input data:
98
Teradata FastLoad Reference
Chapter 3: Teradata FastLoad Commands
DEFINE
•
GRAPHIC
•
VARGRAPHIC
•
LONG VARGRAPHIC
The format to accommodate multibyte character sets and data containing multibyte
characters is:
•
“G” and “XG” for channel-attached systems
•
“XG” and the standard character string format for network-attached systems
where
Syntax Element
Description
“G”
G’<....>’
where
“<” and “>” represent the Shift-Out (0x0E) and Shift-In (0x0F)
characters, respectively
• All characters in between must be valid characters for the
character set
• The number of characters within the Shift-Out/Shift-In must
be an even number.
“XG”
‘hhhh’XG
where
• “hh” represents a pair of hexadecimal digits (0-9 and A-F)
• Each pair of hexadecimal digits represents a single GRAPHIC
character.
• Since a maximum of 80 bytes may be specified in a NULLIF
clause, this translates to 80 pairs of hexadecimal digits.
•
NULLIF Data Type Restrictions and Limitations
The NULLIF option nulls a column in a table when the data field is a certain value. A field
with a value of zero, for example, could represent a null date. To meet this requirement,
enter the field definition in the DEFINE command as:
DueDate (DATE, NULLIF =
0)
Teradata FastLoad compares the value entered in the NULLIF clause with the actual data
row. If they match, the utility sets the appropriate indicator bit to ON for the column in
that row and sends both the row and the indicator bit string to the Teradata Database. The
Teradata Database then inserts a null value into the column.
VARCHAR fields are checked to see if the length of the NULLIF string matches the 2-byte
length indicator field (in the data row). The values are compared only if they are equal. If a
value is a NULLIF value that equals 10 bytes, Teradata FastLoad compares it with the first
10 bytes of the corresponding field in the data row.
FastLoad does not support NULLIF clause on period data type columns.
The following minimum and maximum values may not apply in some applications
because of the runtime environment of the individual platform:
Teradata FastLoad Reference
99
Chapter 3: Teradata FastLoad Commands
DEFINE
Table 29 lists the limitations by data type.
Table 29: Limitations by Data Type
Data Type
Limitations
Examples
BYTE
Up to 80 hexadecimal digits, enclosed by
single quotes and must be an even
number. “XB” is required after the hex
string.
Valid examples:
The total number of bytes must not
exceed two times the number of bytes
specified in the data description.
Invalid examples:
DEFINE T1(BYTE (7), NULLIF = ’01’XB);
DEFINE T1(BYTE (7), NULLIF =
’0123456789ABCD’XB);
DEFINE T1(BYTE (7), NULLIF = ’0’XB) ;
DEFINE T1(BYTE (7), NULLIF = ’0M’XB) ;
Characters must be within the range of
0-9 or A-F.
BYTEINT
Must be within the range of -128 to 127.
Valid examples:
DEFINE T1(BYTEINT, NULLIF = 123) ;
DEFINE T1(BYTEINT, NULLIF = -123) ;
Invalid examples:
DEFINE T1(BYTEINT, NULLIF = 129) ;
DEFINE T1(BYTEINT, NULLIF = -129) ;
CHAR,
CHARS, and
CHARACTERS
For normal string format, from 1 to
80 bytes enclosed in single quotes.
For “XC” format, up to 80 pairs of
hexadecimal digits enclosed in single
quotes. This must be an even number and
the “XC” is required. Each pair of
hexadecimal digits corresponds to a single
character.
Valid examples:
DEFINE T1(CHAR (7), NULLIF = ’ ’) ;
DEFINE T1(CHAR (7), NULLIF = ’ABCDEFG’) ;
Invalid example:
DEFINE T1(CHAR (7), NULLIF = ’ABCDEFGH’)
;
DEFINE T1(CHAR (7), NULLIF =
’ABCDEFGH’XC’) ;
The total number of characters defined in
the NULLIF option must not exceed the
number of characters specified by the
data definition. Character compare
operations are case sensitive, and apply
only to the first 80 bytes.
DATE
INTEGER format only and cannot be
negative.
Valid examples:
DEFINE T1(INTEGER, NULLIF = 123) ;
DEFINE T1(DATE, NULLIF = 941015) ;
Invalid example:
DEFINE T1(DATE, NULLIF=94-10-15);
100
Teradata FastLoad Reference
Chapter 3: Teradata FastLoad Commands
DEFINE
Table 29: Limitations by Data Type (continued)
Data Type
Limitations
Examples
DECIMAL
Must be specified by a zoned number less
than or equal to 38 digits.
Valid examples:
The number of digits specified in the
NULLIF option must not exceed the
number of digits entered in the data
definition. If the NULLIF value contains
more digits after the decimal point than
are defined, results are undefined.
DEFINE T1(DECIMAL (5,2), NULLIF = 0)
;
DEFINE T1(DECIMAL
(5,2), NULLIF =
123.45) ;
Invalid example:
DEFINE T1(DECIMAL (6,0), NULLIF =
1234567) ;
Using NULLIF for DECIMAL (other than
zero) may jeopardize a NULLIF match.
FLOAT
Floating point values are represented
differently on the Teradata Database and
on some of the other platforms.
Consequently, compare operations with
exported floating point numbers may not
function properly.
A valid example:
DEFINE T1(FLOAT, NULLIF = 123) ;
The format for floating point numbers is:
xxx.xxx or xx.xxE(+/-)yy or xE(+/-)yy or
xxx
The range of valid floating point values
on the various platforms is:
• z/OS: 1E-36 to 1E+35
• UNIX OS: 4.94065645841246544e-324
to 1.79769313486231470e+308
Windows: 3.4e-38 to
3.4e+38
Teradata FastLoad Reference
101
Chapter 3: Teradata FastLoad Commands
DEFINE
Table 29: Limitations by Data Type (continued)
Data Type
Limitations
Examples
GRAPHIC and
VARGRAPHIC
From 1 to 80 characters and must be
enclosed in single quotes.
Valid examples on channel-attached systems:
For channel-attached systems, the quoted
string must be preceded by “G” or
followed by “XG”.
For network-attached systems, the quoted
string may be followed by “XG”, but
cannot be preceded by “G”.
DEFINE T1(GRAPHIC(4), NULLIF =
G'<ABCDEFGH>');
DEFINE T1(GRAPHIC(4), NULLIF =
G'<01234567>');
Invalid examples on channel-attached systems:
DEFINE T1(GRAPHIC(4), NULLIF =
G'<01234567ABCD>');
DEFINE T1(GRAPHIC(4), NULLIF =
G'ABCD0123');
When using the "G" format, the total
number of characters defined by the
NULLIF clause must not exceed two
times the number of bytes specified in the
data description.
Valid examples on network-attached systems:
When using the "XG" format, the total
number of hexadecimal digits defined by
the NULLIF clause must not exceed four
times the number of bytes specified in the
data description.
Invalid examples on network-attached systems:
The GRAPHIC or VARGRAPHIC string
has this form:
DEFINE T1(GRAPHIC(4), NULLIF =
'ABCDEFGH');
DEFINE T1(GRAPHIC(4), NULLIF =
'01234567');
DEFINE T1(GRAPHIC(4), NULLIF =
G'<ABCDEFGH>');
DEFINE T1(GRAPHIC(4), NULLIF =
G'<01234567>');
G’<ABC>’
where <ABC> is the quoted
string of valid MBC and the
characters < and >
represent 0x0E and 0x0F.
INTEGER
SMALLINT
Integer fields and date fields must be
within the range of
-2147483648 to 2147483647.
Valid examples:
Small integer fields must be within the
range of
Valid examples:
-32768 to 32767.
DEFINE T1(INTEGER, NULLIF = 123) ;
DEFINE T1(DATE, NULLIF = 941015) ;
DEFINE T1(SMALLINT, NULLIF = 123) ;
DEFINE T1(SMALLINT, NULLIF = -123) ;
Invalid examples:
DEFINE T1(SMALLINT, NULLIF = 32768)
;
DEFINE T1(SMALLINT, NULLIF = -32769)
;
VARBYTE
80 hex digits, enclosed by single quotes and must be an even number. “XB” is required after the hex
string.
VARCHAR
For normal string format, 1-80 bytes enclosed in single quotes.
For “XC” format, up to 80 pairs of hexadecimal digits, enclosed in single-quotes and must be an even
number. The “XC” is required, and each pair of hexadecimal digits corresponds to a single character.
•
102
Numeric Fields
Teradata FastLoad Reference
Chapter 3: Teradata FastLoad Commands
DEFINE
The MAXIMUM and MINIMUM range for all fields is the default for each machine
implementation. These values generally agree with the Teradata Database except in cases
where they are limited by the implementation. These values are documented by the
manufacturer or can be found in the “C” language guide for that machine.
•
Using Table Definitions to Define Data
Use either of the following commands to retrieve a list of field names from the referenced
table:
HELP TABLE tname ;
INSERT tname.* ;
Note: Do not use both of these commands together. In addition, do not use the tname.*
version of an INSERT statement when using Unicode data from the following types of
sessions. For more information about this precaution, see the “Using Unicode Data” topic
in the Usage Notes subsection of the INSERT command description.
•
A KATAKANAEBCDIC session
•
A session with a character set name ending with _0I
•
Any session with a character set that does not support multibyte characters (for
example, ASCII, or EBCDIC).
When this format of the INSERT statement, is used Teradata FastLoad constructs a list of
field names from the table definition. During the insert operation, the utility gets the field
names and their data types from the CREATE TABLE statement used to define the table
and from the table definition.
The following example uses an INSERT statement to get a list of field names from a table
called Employee:
LOGON dbc/peterson,veep ;
BEGIN LOADING Employee ERRORFILES
DEFINE FILE = Accounts ;
INSERT Employee.*;
Etable1, Etable2 ;
The following example uses a HELP command to get a list of field names from a table
called Employee:
LOGON dbc/peterson,veep ;
BEGIN LOADING Employee ERRORFILES
DEFINE FILE = INFILE ;
HELP TABLE Employee ;
INSERT INTO Employee (EmpNum, Name)
Etable1, Etable2 ;
VALUES (:EmpNum, :Name) ;
Note: With either of these examples, a DEFINE command specifying either the input data
source or INMOD parameter must also be entered.
When a DEFINE command does not fit on one input line, enter either:
•
The command on several lines
or
•
Several DEFINE commands
In either case, Teradata FastLoad concatenates the field definitions until an INSERT
statement is entered.
Also, when more than one DEFINE command is entered, the field definitions in all must
appear in the same order as they do in the input data record, just as they would if they
Teradata FastLoad Reference
103
Chapter 3: Teradata FastLoad Commands
DEFINE
were entered in a single DEFINE command. And, only a FILE or INMOD declaration can
be in one of the DEFINE commands.
•
Using ANSI/SQL DateTime Data Types
When the DATEFORM command is used to specify ANSIDATE as the DATE data type,
Teradata FastLoad internally converts each DATE field 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/field names in a Teradata FastLoad
DEFINE command.
After the conversion to fixed-length CHAR data type, if UTF-16 session character set is
used, the size should be doubled, and if UTF-8 session character set is used, the size should
be tripled.
For the conversion specifications and format examples for each ANSI/SQL DateTime
specification, see the INTERVAL type description in Chapter 4 of SQL Data Types and
Literals.
•
Using Period Data Types
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. A period has two elements BEGIN (the
beginning element) and END (the ending element) which have an element type that is one
of the three DateTime data types.
For the CHAR data type, “n” represents the size of the field. For PERIOD data types, this is
not the case. “n” represents the precision (number of digits in the fractional part of
seconds).
PERIOD data is always represented externally in binary format.
•
Using Session Character Set KANJISJIS_0S
When the session character set used is KANJISJIS_0S, if the CHAR(n) or VARCHAR(n) of
the table to be loaded is defined as UNICODE character set, the corresponding field size in
the DEFINE command should be doubled, that is CHAR(n*2) or VARCHAR(n*2)
respectively.
If the CHAR(n) or VARCHAR(n) of the table to be loaded is defined as LATIN character
set, the corresponding field size in the DEFINE command remains the same, that is
CHAR(n) or VARCHAR(n) respectively.
104
Teradata FastLoad Reference
Chapter 3: Teradata FastLoad Commands
END LOADING
END LOADING
Purpose
The END LOADING command distributes all of the rows that were sent from the client to the
Teradata Database during the loading phase to their final destination on the AMPs.
Syntax
;
END LOADING
2411A019
Usage Notes
Table 30 describes the things to consider when using the END LOADING command.
Table 30: Usage Notes for END LOADING
Topic
Usage Notes
End Loading Phase
The END LOADING command begins the end loading phase of a Teradata
FastLoad job. During this phase, all rows are distributed on the AMPs and
stored in the final Teradata FastLoad table.
When the end loading phase completes, the Teradata Database removes the
access locks that were placed on the three tables specified in the BEGIN
LOADING command so users with the proper privileges can access them
using Teradata SQL statements.
Entering Teradata
SQL Statements
Many of the Teradata SQL statements from Teradata FastLoad cannot be
entered because the utility supports only a subset of the Teradata SQL
language. So, when END LOADING has completed and access to data stored
in the Teradata FastLoad table or the error tables is required, it cannot be
done from Teradata FastLoad. You must use BTEQ or a similar application
program must be used to query these tables.
Error Tables
Teradata FastLoad automatically drops error tables that contain no rows
when END LOADING finishes executing.
Internal
Checkpointing
The Teradata Database uses internal checkpointing while processing an END
LOADING command. Therefore, a job can be interrupted during the end
loading phase without disturbing processing status. When the job is restarted,
the Teradata Database resumes processing from where it left off.
Example
The following command example completes a Teradata FastLoad job:
END LOADING ;
Teradata FastLoad Reference
105
Chapter 3: Teradata FastLoad Commands
END LOADING
Completion Message
The Teradata FastLoad completion message for the END LOADING command depends on
whether the job includes a RECORD command.
Table 31 describes the possible RECORD command Completion messages.
Table 31: RECORD Completion Message Conditions
Job
106
Teradata FastLoad Response Layout
If the Job includes a
RECORD command
Total Records Read =
500
- skipped by RECORD command = 50
- sent to the RDBMS =
450
Total Error Table 1 =
25
Total Error Table 2 =
0
Total Inserts Applied =
425
Total Duplicate Rows =
0
If the Job does not include a
RECORD command
Total
Total
Total
Total
Total
Records Read =
Error Table 1 =
Error Table 2 =
Inserts Applied =
Duplicate Rows =
500
25
0
475
0
Teradata FastLoad Reference
Chapter 3: Teradata FastLoad Commands
ERRLIMIT
ERRLIMIT
Purpose
The ERRLIMIT command limits the number of records that can be rejected while inserting
data into the Teradata FastLoad table.
Syntax
;
ERRLIMIT n
2411A021
where
Syntax Element
Description
n
Maximum number of records that can be rejected before executing the END
LOADING command.
The default error limit value is 1000000.
Usage Notes
Table 32 describes the things to consider when using the ERRLIMIT command.
Table 32: Usage Notes for ERRLIMIT
Topic
Usage Notes
Limiting Insertion
Errors
Use the ERRLIMIT command to limit the number of insertion errors
captured in the first error table (errortname1) during the loading phase of a
job. Processing terminates when the number of errors encountered reaches
the error limit.
If, for example, errors are not expected in the input data, set the error limit
value to one. In this case, the job terminates when any record causes an
error.
Note, however, that when the specified error limit is reached, Teradata
FastLoad continues processing until each session completes its current data
block. This continued processing can cause the total number of error rows
captured in the first error table to exceed the ERRLIMIT specification.
Restarting a Job
Teradata FastLoad Reference
A job can be restarted from the last checkpoint if it terminates because the
error limit is reached. If checkpoints were not taken, restart the job from
the beginning.
107
Chapter 3: Teradata FastLoad Commands
ERRLIMIT
Example
The following command example terminates the job after 20 errors:
ERRLIMIT 20 ;
Completion Message
The Teradata FastLoad completion message is:
Error limit set to :20
108
Teradata FastLoad Reference
Chapter 3: Teradata FastLoad Commands
HELP
HELP
Purpose
The HELP command returns the syntax of all Teradata FastLoad commands and lists the
Teradata SQL statements supported by Teradata FastLoad.
Syntax
;
HELP
2411A020
Usage Notes
Table 33 describes the things to consider when using the HELP command.
Table 33: Usage Notes for HELP
Topic
Usage Notes
Using the HELP
Command
The HELP command is intended for online use.
Return Message Symbols
The HELP command return messages use these symbols:
• [ ] (brackets) indicate an optional entry.
• { } (curly braces) indicate a choice of entries, one of which must be
selected.
Example
The following command example returns a list of Teradata FastLoad commands:
HELP ;
Completion Message
The Teradata FastLoad completion message is:
Listed below is the syntax of each Teradata FastLoad command.
Single-line commands may be preceded by a [.] or terminated by a [;].
Multi-line commands must NOT be preceded by a [.] but must be terminated by a [;].
SQL statements must NOT be preceded by a [.] and MUST be terminated by a [;].
AXSMOD name [ "<init-string>" ] ;
BEGIN LOADING [dbname.]tname1
ERRORFILES [dbname.]errortname1,
[dbname.]errortname2
Teradata FastLoad Reference
109
Chapter 3: Teradata FastLoad Commands
HELP
[ CHECKPOINT integer ]
[ INDICATORS
] ;
CLEAR ;
{ INTEGERDATE }
DATEFORM { ----------- } ;
{ ANSIDATE
}
DEF[INE]
[ fieldname (data type [,NULLIF [=] value ]) ...
[,fieldname (data type [,NULLIF [=] value ])] ]
[ { FILE=filename } ]
[ {
} ] ;
[ { INMOD=name
} ]
END LOADING ;
ERRLIMIT n ;
HELP ;
HELP TABLE tname ;
The INSERT statement has two formats:
1. INS[ERT] [INTO] tname.* ;
2. INS[ERT] [INTO] tname (cname [... ,cname])
VALUES (:fieldname [... ,fieldname]) ;
LOGOFF ;
LOG[ON] [tdpid/] username,password [ , 'acctid' ] ;
{ OFF
}
{ --} [ EXIT [name] [TEXT "string"] ]
NOTIFY { LOW
} [ MSG
[text]
] ;
{ MEDIUM } [ QUEUE [options]
]
{ HIGH
}
OS oscommand ;
QUIT ;
RECORD [startrecordnumber] [THRU endrecordnumber] ;
SESSIONS n|* [ m|* ] ;
{ FORMATTED
SET RECORD { --------{ UNFORMATTED
{ VARTEXT [ c ] [DISPLAY_ERRORS] [NOSTOP]
{ 0 - 255
}
{ ASCII
}
SET SESSION CHARSET { ----} ;
{ KanjiEUC_0U }
{ KanjiSJIS_0S }
SHOW ;
SHOW VERSION[S] ;
SLEEP n ;
TENACITY n ;
The following DBS/SQL statements are supported by the
FastLoad utility:
CREATE TABLE
DATABASE dbname ;
DEL[ETE] FROM tname [ ALL ] ;
DROP TABLE tname ;
}
} ;
}
}
Note: Replace “FILE=” with “DDNAME=” for z/OS .
110
Teradata FastLoad Reference
Chapter 3: Teradata FastLoad Commands
HELP TABLE
HELP TABLE
Purpose
The HELP TABLE command creates a list of field names by querying the Teradata Database
and deriving the DEFINE list from the table definition.
Syntax
tname
HELP TABLE
;
dbname.
2411A023
where
Syntax Element
Description
tname
Table to be queried.
dbname
Database in which the table resides.
Usage Notes
Table 34 describes the things to consider when using the HELP TABLE command.
Table 34: Usage Notes for HELP TABLE
Topic
Usage Notes
Using DEFINE
Commands
If the HELP TABLE command is used to define field names, a DEFINE
command must still be used to specify the input data source name or
INMOD routine.
UDT column
If the table contains a UDT column, an external representation of the UDT is
returned.
For example, if the user defines a USDollar data type as Decimal(13,2) and
defines a column as USDollar type in the table, Decimal(13,2) is returned as
the data type of this column.
Teradata FastLoad Reference
111
Chapter 3: Teradata FastLoad Commands
HELP TABLE
Table 34: Usage Notes for HELP TABLE (continued)
Topic
Usage Notes
Using a CLEAR
Command
When using two HELP TABLE commands in the same Teradata FastLoad
job, using a CLEAR command before the second one cancels the first. The
following command example produces a list of only the Department table:
HELP TABLE Employee ;
CLEAR ;
HELP TABLE Department ;
Entering the two HELP TABLE commands without a CLEAR command, as in
the following example, produces a list of both the Employee and Department
tables:
HELP TABLE Employee ;
HELP TABLE Department ;
Unicode Session
Character Set
Limitation
Teradata FastLoad uses the number of bytes of storage returned from
Teradata Database to construct the USING clause of a load operation.
Therefore, when the session character set is UTF-8 or UTF-16, the MAX
LENGTH returned from the database is not the actual byte count for the
Unicode column, meaning that the internally generated USING clause does
not properly reflect the structure of the input data stream.
Instead of using HELP TABLE to describe the structure of input data, use the
DEFINE command when the session character set is UTF-8 or UTF-16.
Example
The following command example builds a list of field names from the table definition for a
table named Employee:
HELP TABLE Employee ;
The SHOW command can be used to verify the field names defined in the HELP TABLE
command:
SHOW ;
112
Teradata FastLoad Reference
Chapter 3: Teradata FastLoad Commands
INSERT
INSERT
Purpose
INSERT is a Teradata SQL statement that inserts data records into the rows of the Teradata
FastLoad table.
Syntax
;
tname
INSERT
.
INTO
INS
*
,
values
( cname )
values
VALUES
,
( :fieldname )
2411A024
where
Syntax Element
Description
tname
Name of the table into which rows are inserted.
cname
Name of column to receive a new row value during the insert operation.
For each cname defined, a corresponding fieldname must be specified.
A list of column names can be defined in any order. The column names do
not have to be defined in the same order as they appear in the CREATE
TABLE statement.
fieldname
Field name that was defined in a previous DEFINE command.
During the insert operation, Teradata FastLoad inserts the field in the input
data record that was assigned to the fieldname into the corresponding
column (cname) of the Teradata FastLoad table.
.*
Wildcard specification that all columns in tname that are used to construct
the list of field names be used in the insert operation.
When the wildcard specification is used, Teradata FastLoad queries the
Teradata Database for all of the column names and uses them to construct a
valid INSERT statement.
Usage Notes
The following table describes the things to consider when using the INSERT statement.
Table 35 describes the things to consider when using the INSERT command.
Teradata FastLoad Reference
113
Chapter 3: Teradata FastLoad Commands
INSERT
Table 35: Usage Notes for INSERT
Topic
Usage Notes
Required Privileges
To use the INSERT statement, the user ID associated with the Teradata
FastLoad job must have INSERT privilege on the specified table.
Inserting Field
Values
During the insert operation, field values are inserted in the table in the order
in which the columns are listed in the CREATE TABLE statement. If field
values in the input data are stored in the same order as columns are defined in
the CREATE TABLE statement for the Teradata FastLoad table, a list of
column names does not need to be specified in the INSERT statement (for
instance, INSERT INTO table1 VALUES (:f1, :f2).
When the second format of the INSERT statement is used, a list of field
names is constructed from the definition of the table. During the insert
operation, field names and their data types are taken from the CREATE
TABLE statement and used to define the table.
The field name definitions are established in the order in which columns are
defined in the CREATE TABLE statement. So, the fields in each data record
must be in the same order as the columns in the definition of the table.
Using DEFINE
Commands
When using the second form of the INSERT statement, use the DEFINE
command to specify the name of the input data source or INMOD routine
used in the Teradata FastLoad job.
If a DEFINE command that defines one or more fields before the INSERT
statement is entered, Teradata FastLoad appends the field definitions to the
definitions constructed from the INSERT statement. (See the command
examples that follow.)
Note: The colon character preceding the input field name descriptions
(:fieldname) indicates that a corresponding DEFINE field must exist. If the
INSERT statement does not include: fieldname expressions, then Teradata
FastLoad transmits the command to the Teradata Database intact, without
linking it with a previous DEFINE command.
114
Using SHOW
TABLE Statements
If a Teradata SQL SHOW TABLE statement is used to display the exact
definition of a table, you must do so from BTEQ or another application.
Teradata FastLoad does not support this statement.
ANSI/SQL
DateTime
Specifications
The ANSI/SQL DATE, TIME, TIMESTAMP, and INTERVAL DateTime data
types in Teradata SQL CREATE TABLE statements can be used. They can be
specified as column/field modifiers in INSERT statements. They must be
converted to fixed-length CHAR data types when specifying the column/field
names in the Teradata FastLoad DEFINE command.
Teradata FastLoad Reference
Chapter 3: Teradata FastLoad Commands
INSERT
Table 35: Usage Notes for INSERT (continued)
Topic
Usage Notes
Using Unicode
Data
Caution:
Do not use the tname.* version of an INSERT statement when
using Unicode data from any of the following:
•
A KATAKANAEBCDIC session
•
A session with a character set name ending with _0I
•
Any session with a character set that does not support
multibyte characters (for example, ASCII or EBCDIC)
In addition to the field names from the referenced tables, these functions
return byte/character counts that Teradata FastLoad uses internally to
construct the USING clause for the subsequent load operation. Because of the
byte and character count conversions that take place when importing and
exporting CHAR and VARCHAR data between a client system and the
Teradata Database, the internally generated USING clause does not properly
reflect the structure of the input data stream.
Unicode Session
Character Set
Limitation
For information, see “Unicode Session Character Set Limitation” in the
Usage Notes of “HELP TABLE” on page 111.
Example 1
The following command example defines the EmpRecs input data source and the fields in
each record (Emp_Number and Emp_Name):
DEFINE Emp_Number (INTEGER), Emp_Name (VARCHAR(30)),
FILE=EmpRecs ;
INSERT INTO Employee (EmpNo, Name) VALUES
(:Emp_Number, :Emp_Name) ;
The INSERT statement defines the table and columns to receive new data values.
For each data record, the value in the first field (Emp_Number) is inserted in the EmpNum
column and the value in the second field (Emp_Name) is inserted in the Name column.
Example 2
The following command example establishes a list of field names from the definition of the
Teradata FastLoad table:
DEFINE FILE=InFile;
INSERT OldTable.* ;
The DEFINE command specifies the input data source (InFile) and defines each field to be
inserted in the Teradata FastLoad table (OldTable).
Example 3
Sometimes the records in an input data source contain data that does not belong in the
Teradata FastLoad table. If, for example, each record contains 100 bytes of extra data, a
dummy field can be defined in the DEFINE command that is not referenced in the INSERT
statement.
Teradata FastLoad Reference
115
Chapter 3: Teradata FastLoad Commands
INSERT
The following command example constructs a list of field names that match the current
definition of NewTable appended to the definition of the extra data item:
DEFINE ExtraData (CHAR (100)) FILE = InFile;
INSERT NewTable.*;
When extra data is used in the input data source with the INSERT TABLE .* feature, the extra
data must be located at the beginning of each record.
This feature cannot be used if the extra data occurs in the middle or at the end of the records.
In this case, explicitly define each data item in the data source and each item in the values
clause of the INSERT statement.
116
Teradata FastLoad Reference
Chapter 3: Teradata FastLoad Commands
LOGDATA
LOGDATA
Purpose
Supplies parameters to the LOGMECH command beyond those needed by the logon
mechanism, such as user ID and password, to successfully authenticate the user. The
LOGDATA command is optional. Whether or not parameters are supplied and the values and
types of parameters depend on the selected logon method.
LOGDATA is only available on network-based platforms.
Syntax
.LOGDATA
logdata_string
;
2411A036
where
Syntax Element
Description
logdata_string
Parameters for the logon mechanism specified using “LOGMECH”
on page 118
For information about the logon parameters for supported
mechanisms, see the Security Administration guide.
The string is limited to 64 KB and must be in the session character set.
Note: Make sure that the string ends with a semicolon.
Usage Notes
For more information about logon security, see Security Administration.
Example
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 Kerberos logon authentication method and
associated parameters:
.logmech KRB5;
.logdata joe@domain1@@mypassword;
.logon cs4400s3;
Teradata FastLoad Reference
117
Chapter 3: Teradata FastLoad Commands
LOGMECH
LOGMECH
Purpose
Identifies the appropriate logon mechanism by name. If the mechanism specified requires
parameters other than user ID and password for authentication, the LOGDATA command
provides these parameters. The LOGMECH command is optional and available only on
network-attached systems.
Syntax
.LOGMECH
logmech_name
;
2409A053
where
Syntax Element
Description
logmech_name
Defines the logon mechanism
For a discussion of supported logon mechanisms, see Security Administration.
The name is limited to 8 bytes; it is not case- sensitive.
Usage Notes
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.
Example
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;
118
Teradata FastLoad Reference
Chapter 3: Teradata FastLoad Commands
LOGOFF
LOGOFF
Purpose
The LOGOFF command ends Teradata FastLoad sessions and exits from the Teradata
Database.
The LOGOFF and QUIT commands may be used interchangeably.
Syntax
;
LOGOFF
QUIT
2411A013
Usage Notes
Table 36 describes the things to consider when using the LOGOFF command.
Table 36: LOGOFF Command Usage Notes
Topic
Usage Notes
Pausing Teradata FastLoad
If the LOGOFF command is entered after a BEGIN LOADING
command, but before the END LOADING command, the Teradata
FastLoad job pauses and can be restarted later.
Locked Tables
When a Teradata FastLoad job pauses during the loading phase, the
Teradata Database locks the tables named in the BEGIN LOADING
command. The tables remain locked until an END LOADING
command is entered.
Termination Return Codes
When a Teradata FastLoad job terminates, the utility returns a code
indicating the way the job completed:
• Code 0—Normal completion. The job completed successfully
and according to the specified plan.
• Code 4—Warning. A warning condition occurred; for example, a
job deviated from normal or from the specified plan, but still
completed successfully. A warning may indicate deviation from
the plan; for example, the number of sessions specified were not
actually used, or a part of the job did not run. Warning
conditions do not terminate the job.
• Code 8—User error. A user error, such as a syntax error in the job
script, terminated the job.
• Code 12—Severe error. A fatal error terminated the job. A fatal
error is any error other than a user error.
Teradata FastLoad Reference
119
Chapter 3: Teradata FastLoad Commands
LOGOFF
Example
The following command example ends Teradata FastLoad and exits the Teradata Database:
LOGOFF ;
Completion Message
The completion message indicates that the Teradata FastLoad job was either paused or
terminated, depending on whether the job was in the loading phase or not:
Table 37 describes the possible LOGOFF command Completion messages.
Table 37: LOGOFF Command Completion Messages
120
Job
Teradata FastLoad Response Layout
If the Job is in the
loading phase
**** 14:19:35 Logging off all sessions
**** 14:19:36 Total processor time used = '0.34 Seconds'
.
Start : Mon Aug 02 14:19:26 2010
.
End
: Mon Aug 02 14:19:36 2010
.
Highest return code encountered = '4'.
**** 14:19:36 FDL4818 FastLoad Paused
If the Job is not in
the loading phase
**** 14:19:35 Logging off all sessions
**** 14:19:36 Total processor time used = '0.34 Seconds'
.
Start : Mon Aug 02 14:19:26 2010
.
End
: Mon Aug 02 14:19:36 2010
.
Highest return code encountered = '0'.
**** 14:19:36 FDL4818 FastLoad Terminated
Teradata FastLoad Reference
Chapter 3: Teradata FastLoad Commands
LOGON
LOGON
Purpose
The LOGON command establishes one or more Teradata FastLoad sessions with the Teradata
Database.
Syntax
Standard LOGON Syntax
;
username, pasword
LOGON
tdpid/
,'acctid'
2411A022
Single Sign-on LOGON Syntax
;
LOGON
tdpid/
username , password
,'acctid'
2411A006
where
Syntax Element
Description
username
User identifier of up to 30 bytes.
password
Password associated with the username.
A password can have up to 30 bytes.
tdpid
Optional character string that identifies the name of a TDP.
The tdpid string can have from 1 to 8 characters.
Network-attached systems: The tdpid string can have up to 256 characters
and can be a domain name system (DNS) name.
The tdpid is the name of the host entered in the network hosts file. If this field
is not supplied, tdpid defaults to the TDP established for the user by the
system administrator.
Channel-attached systems: The tdpid string must be in the form:
TDPn
where n is the TDP identifier.
Teradata FastLoad Reference
121
Chapter 3: Teradata FastLoad Commands
LOGON
Syntax Element
Description
acctid
Account associated with the username
An account identifier can have up to 30 bytes.
If omitted, Teradata FastLoad uses the default account identifier defined
when the user was created.
Usage Notes
Table 38 describes the things to consider when using the LOGON command.
Table 38: Usage Notes for LOGON
Topic
Usage Notes
Logon Parameters
For standard logon, the parameters (tdpid, username, password, and acctid)
are used in all sessions established with the Teradata Database. The LOGON
command may occur only once.
For single sign-on logon, if the Gateway to Teradata Database is configured to
use single sign-on (SSO), and the user is already logged on to the Teradata
client machine, the machine name, user name, and password are not required
in the LOGON command. The user name and password combination
specified when the user logged on to the Teradata client machine are
authenticated via network security for a single sign-on such that valid
Teradata users will be permitted to log on to the Teradata Database. The use
of SSO is strictly optional, unless the Gateway has been configured to accept
only SSO-style logons.
To connect to a Teradata Database other than the one currently logged on,
the TDPid must be included in the LOGON command. If the TDPid is not
specified, the default contained in clispb.dat will be used. (Refer to the
Teradata Call-Level Interface Version 2 Reference for Network-Attached Systems
guide for information about setting defaults.)
To be interpreted correctly, the TDPid must be followed by the slash
separator (‘/’) to distinguish the TDPid from a Teradata Database username.
For example, to connect to slugger, enter one of the following:
.LOGON slugger/;
.LOGON slugger/,,'acctinfo';
If an account ID is to be used, the optional account ID must be specified in
the LOGON command.
Starting Teradata
FastLoad
The LOGON command starts a Teradata FastLoad job and automatically
establishes:
• Two Teradata SQL sessions
• A number of Teradata FastLoad sessions
Number of
Sessions
122
The number of Teradata FastLoad sessions depends on the system limitations
described in “Session Limits” on page 61.
Teradata FastLoad Reference
Chapter 3: Teradata FastLoad Commands
LOGON
Table 38: Usage Notes for LOGON (continued)
Topic
Usage Notes
Number of
Sessions
(continued)
Teradata FastLoad attempts to connect sessions, in groups of 16, until either:
Reported Sessions
After a LOGON command is entered, Teradata FastLoad reports the number
of Teradata FastLoad sessions that are logged on. The Teradata SQL sessions
are not included in this report.
Character Support
Current multi-byte character support of an object name is limited to 30 bytes.
• The number of sessions specified with a SESSIONS command are
connected
• A Teradata Database Error 2632 is returned
• Some other session limit is reached
Note: If the number that was specified in a SESSIONS command exceeds the
number of available sessions, Teradata FastLoad logs only the number of
available sessions.
The limitation applies to username, passwd, and account in the logon string.
CLI treats logon strings of UTF-8 and other Teradata-supported multi-byte
character sets (that is, Chinese, Japanese, Korean) as ASCII. CLI does not
convert before parsing. This means that some logon strings with multi-byte
characters, or a combination of multi-byte characters plus ASCII, could fail if
the total size of an object name is over 30 bytes.
The work around is to create object names that are less than 30 bytes.
Example
The following command example logs on user Peterson:
LOGON DBC/peterson,HTims ;
Completion Message
The Teradata FastLoad completion message is:
Number of FastLoad sessions connected = 8
FDL4808 LOGON successful
Teradata FastLoad Reference
123
Chapter 3: Teradata FastLoad Commands
NOTIFY
NOTIFY
Purpose
The NOTIFY command specifies a user exit or predefined action to be performed whenever
certain significant events occur during a Teradata FastLoad job. (For a listing of events that
cause notifications, see Table 39 on page 126.)
The notify function is especially useful in operator-free environments where job scheduling
relies heavily on automation to optimize system performance. For example, by writing an exit
in C (without using CLIv2) and using the NOTIFY… EXIT option, a routine to detect
whether a Teradata FastLoad job succeeds or fails, how many records were loaded, what the
return code was for a failed job, and so on can be provided.
Note: The Teradata FastLoad NOTIFY command applies only to the job that immediately
follows it.
Syntax
NOTIFY
;
OFF
LOW
EXIT
name
TEXT "string "
MSG
"string "
QUEUE
option
MEDIUM
EXIT
name
HIGH
TEXT "string "
MSG
"string "
2414A005
where
124
Syntax Element
Description
OFF
Default. No notification of events is to be provided.
LOW
Notification is to be provided for those events signified by “Yes” in the Low
Notification Level column of Table 39.
MEDIUM
Notification is to be provided for those events signified by “Yes” in the Medium
Notification Level column of Table 39.
HIGH
Notification is to be provided for those events signified by “Yes” in the High
Notification Level column of Table 39.
EXIT
A user-written exit is to be called at the appropriate time.
Teradata FastLoad Reference
Chapter 3: Teradata FastLoad Commands
NOTIFY
Syntax Element
Description
name
The name of a user-supplied library with an entry point named
_dynamn.
The default library names are:
• libnotfyext.dll for Windows
• libnotfyext.so for UNIX platforms
• NOTFYEXT for z/OS platforms.
TEXT "string"
A user-supplied string of up to 80 characters that Teradata FastLoad passes to
the named exit routine
The string specification must be enclosed in double-quote characters (").
MSG "string"
A user-supplied string of up to 16 characters that Teradata FastLoad logs on to:
• The operator console on channel-attached z/OS client systems
• The system log or EventLog service on network-attached UNIX or Windows
systems
The string specification must be enclosed in double quote characters. This
service is not available on Windows 98.
QUEUE
Specifies that a queue is to be manipulated via ENQ or DEQ
See the QUEUE Notes topic in “Usage Notes”, below, for more details.
This option is valid only for z/OS.
option
One of the following:
RNAME defines a quoted string of up to 255 characters. The default is
TRDUSER.
SCOPE defines one of the following:
• JOB specifies that the QUEUE is local to the job (including all of the job
steps). This is the default.
• SYSTEMS specifies that the QUEUE is global to all computers in the
complex.
• SYSTEM specifies that the QUEUE is global to the computer on which it is
running.
NOBLOCK specifies that if the ENQ blocks for any reason, it must return an
error instead. This is a fatal error for the job.
The default, an implied BLOCK (there is no BLOCK keyword), means that the
ENQ will wait for the QUEUE.
Table 39 lists events that create notification.
Teradata FastLoad Reference
125
Chapter 3: Teradata FastLoad Commands
NOTIFY
Table 39: Events that Create Notifications
Notification Level
Event
Low
Medium
High
Signifies
Initialize
Yes
Yes
Yes
Successful processing of the NOTIFY command
File or INMOD open
No
No
Yes
Successful processing of the DEFINE command
Phase 1 begin
No
Yes
Yes
Beginning of the insert phase, as specified by the INSERT
statement
Checkpoint
No
No
Yes
Checkpoint information has been written to the restart log table
Phase 1 end
No
Yes
Yes
Successful processing of the CHECKPOINT LOADING END
request after the end of the insert phase
Phase 2 begin
No
Yes
Yes
The END LOADING command is about to be sent to the
Teradata Database
Phase 2 end
No
Yes
Yes
Successful processing of the END LOADING command
Error table 1
No
No
Yes
Successful processing of the SEL COUNT(*) request for the first
error table
Error table 2
No
No
Yes
Successful processing of the SEL COUNT(*) request for the
second error table
Teradata Database
Restart
No
Yes
Yes
A crash error from the Teradata Database or the CLIv2
CLIv2 error
Yes
Yes
Yes
A CLIv2 error
Teradata Database error Yes
Yes
Yes
A Teradata Database error that will terminate Teradata FastLoad
Exit
Yes
Yes
Teradata FastLoad is terminating
Yes
Usage Notes
Table 40 describes the things to consider when using the NOTIFY command.
Table 40: Usage Notes for NOTIFY
Topic
Usage Notes
QUEUE Notes
When QUEUE with LOW option is specified, the following takes place:
1 When NOTIFY is processed, it performs an ENQ upon a QUEUE with
RNAME of ‘TRDUSER’ and a scope of ‘JOB’. This call blocks until it
acquires the QUEUE.
2 After the job gets the QUEUE, it continues until it reaches a specific point
(such as the request completes) when it releases the QUEUE by
performing a DEQ.
126
Teradata FastLoad Reference
Chapter 3: Teradata FastLoad Commands
NOTIFY
Table 40: Usage Notes for NOTIFY (continued)
Topic
Usage Notes
Error Handling
When an error occurs, NOTIFY behaves as follows:
• When NOTIFY is processed, the subsystems used by Teradata FastLoad
are initialized and, if necessary, any user exits are loaded and a call is made
to initialize the system log (or an ENQ is performed).
• If initialization fails, a warning message is issued and processing
continues. The exception to this rule is the case where a ‘NOTIFY ...
QUEUE’ is issued. If initialization (the ENQ call) fails, it is a fatal error.
• If anything fails after initialization, the request fails. If a user exit returns
anything other than 0, a failure is indicated and the job stops.
Restarts
The following points pertain to restarts related to NOTIFY:
• If a Teradata FastLoad job ends abnormally or unsuccessfully, it can be
restarted and some NOTIFY-related activities are re-executed. This is an
important issue with respect to writing user exits.
• If a Teradata FastLoad job ends abnormally or unsuccessfully while it is
holding a queue (using the QUEUE type parameter under z/OS), it
releases the queue before exiting the job. Therefore, when the job restarts,
ensure that it again acquires the queue before it continues processing.
Creating Exit
Routine
When creating an exit routine, the following general procedures are constant
across all operating systems:
• The exit must be named _dynamn.
• Success is indicated by the return of a 0 (long integer format).
• Failure is indicated by the return of a nonzero value (long integer format).
Different integers can be used to indicate different errors.
• The parameter to the procedure is a pointer to a variable record structure.
Note: For a definition of the variable record structure, see “Notify Exit
Routine Example” on page 180.
• A C prototype example for an exit procedure might be as follows (using a
Teradata FastLoad example):
long _dynamn(FLNotifyExitParm *P)
The procedures for creating and using an exit routine are the same as for
creating and using an INMOD routine, as described in “INMOD and Notify
Exit Routines” on page 63 and Appendix D: “Compile, Link, and Execute
INMOD and Notify Exit Routines.”
Message Examples
Table 41 lists example messages for Teradata FastLoad events. In each case, the message is
preceded by the text string specified with the MSG option of the NOTIFY command.
Table 41: NOTIFY Command Message Examples
Teradata FastLoad Event
Message
Notify processed
- FastLoad notify processed.
Teradata FastLoad Reference
127
Chapter 3: Teradata FastLoad Commands
NOTIFY
Table 41: NOTIFY Command Message Examples (continued)
128
Teradata FastLoad Event
Message
Phase 1 is about to begin
- FastLoad phase one starting for table [N]
XXXXXXX.XXXXXXX.
Each checkpoint
- FastLoad checkpoint complete: NNNNNNNNNN
records sent.
When a data file is about to be opened
- FastLoad opening file filename
Phase 1 completes successfully
- FastLoad phase one completes: NNNNNNNNN
records sent.
Phase 2 completes successfully
- FastLoad phase two completes: NNNNNNNNN
records sent.
Teradata FastLoad Reference
Chapter 3: Teradata FastLoad Commands
OS
OS
Purpose
The OS command submits an operating system command to the client environment during a
Teradata FastLoad session.
Syntax
;
OS command
2411A025
where
Syntax Element
Description
command
Any command that is valid for the client operating system
Usage Notes
The OS command must terminate with a semicolon.
UNIX Examples
Table 42 lists examples of OS command used on a UNIX client system.
Table 42: OS Command Examples on a UNIX Client System
Command
Example
ls
The following command example lists the files in a directory on the UNIX
operating system and then returns to Teradata FastLoad:
OS ls ;
exec sh
The following command example accesses the UNIX shell:
OS exec sh ;
Then, at the client system prompt, enter other UNIX commands, such as:
$ pg myfile.one
$ cp oldfile newfile
$ cd draft
Press CTRL + D to exit the UNIX environment and return to Teradata FastLoad.
Teradata FastLoad Reference
129
Chapter 3: Teradata FastLoad Commands
OS
Windows Examples
Table 43 shows an example procedure for the OS command used on a Windows client system.
Table 43: Example OS Command on Windows Client System
Command
Example
dir
The following command example lists the files in a directory on the Windows
operating system and then returns to Teradata FastLoad:
OS dir;
command
The following command example accesses the Windows operating system:
OS command;
At the client system prompt, other commands can be entered, such as:
c:\teradata\bin>type myfile.one
c:\teradata\bin>edit myfile.one
c:\teradata\bin>exit
Enter exitto exit the Windows environment and return to Teradata
FastLoad.
z/OS Example
Table 44 shows an example procedure for the OS command used on an z/OS client system.
130
Teradata FastLoad Reference
Chapter 3: Teradata FastLoad Commands
OS
Table 44: Example Procedure for OS Command on z/OS Client System
Command
Example
TSO Setup Procedure
Before using the OS command on z/OS, the time-sharing option (TSO) must
be set up to run Teradata FastLoad interactively, as in the following example:
/
***************************************************************/
/*
*/
/* THIS CLIST INVOKE IBM_C VERSION OF FASTLOAD.
*/
/*
*/
/*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*/
/*
*/
/*
PARAMETER
USE
*/
/*
=========
===
*/
/*
DBCPFX
= HIGH LEVEL QUALIFIER FOR "APPLOAD" LIBRARY.
*/
/*
DEFAULT IS "DBC".
*/
/*
*/
/
***************************************************************/
PROC 0 DBCPFX(<APPLOAD LIBRARY>)
CONTROL NOMSG PROMPT
WRITE 'FASTLOAD CLIST TTU13.10'
ALLOC FI(CTRANS) DA('IMB_C LinkLib') SHR
ALLOC FI(SYSIN) DA(*)
ALLOC FI(SYSPRINT) DA(*)
ALLOC FI(SYSOUT)
DA(*)
ALLOC FI(SYSTERM) DA(*)
CALL '&DBCPFX..APP.L(FASTLOAD)'
FREE FI(CTRANS,SYSIN,SYSPRINT,SYSOUT,SYSTERM)
EXIT
where
• <APPLOAD LIBRARY> is the fully qualified name of the load library
containing Teradata FastLoad and CLIV2 components.
Note: Unlike batch, TSO does not support concatenated load libraries.
• <IBM C Linklib>is the fully qualified name of the IBM C link library.
Note: Input data sets can be allocated and freed.
TSO Command
After setting up TSO to run Teradata FastLoad interactively, the Teradata
FastLoad OS command can be used to enter any valid TSO command:
OS <TSO command>;
Teradata FastLoad Reference
131
Chapter 3: Teradata FastLoad Commands
QUIT
QUIT
Purpose
The QUIT command ends Teradata FastLoad sessions and exits from the Teradata Database.
The LOGOFF and QUIT commands may be used interchangeably.
Syntax
;
QUIT
LOGOFF
2411A026
Usage Notes
Table 45 describes the things to consider when using the QUIT command. For more
information about restarting a paused job, see “Restart a Paused Teradata FastLoad Job” on
page 48.
Table 45: Usage Notes for QUIT
Topic
Usage Notes
Pausing Teradata
FastLoad
If the QUIT command is entered after a BEGIN LOADING
command, but before the END LOADING command, the Teradata
FastLoad job pauses, and can be restarted later.
Locked Tables
When a Teradata FastLoad job pauses during the loading phase, the
Teradata Database locks the tables named in the BEGIN LOADING
command. The tables remain locked until an END LOADING
command is entered.
Terminating Return
Codes
When a Teradata FastLoad job terminates, the utility returns a code
indicating the way the job completed:
• Code 0—Normal completion. The job completed successfully and
according to the specified plan.
• Code 4—Warning. A warning condition occurred. Warning
conditions do not terminate the job.
• Code 8—User error. A user error, such as a syntax error in the
Teradata FastLoad job script, terminated the job.
• Code 12—Fatal error. Job is terminated. A fatal error is any error
other than a user error.
132
Teradata FastLoad Reference
Chapter 3: Teradata FastLoad Commands
QUIT
Example
The following command example ends Teradata FastLoad and exits the Teradata Database:
QUIT ;
Completion Message
The completion message indicates that the Teradata FastLoad job was either paused or
terminated, depending on whether the job was in the loading phase or not:
•
If the job is in the loading phase, then Teradata FastLoad responds:
**** 14:19:35 Logging off all sessions
**** 14:19:36 Total processor time used = '0.34 Seconds'
.
Start : Mon Aug 02 14:19:26 2010
.
End
: Mon Aug 02 14:19:36 2010
.
Highest return code encountered = '0'.
**** 14:19:36 FDL4818 FastLoad Paused
•
If the job is not in the loading phase, then Teradata FastLoad responds:
**** 14:19:35 Logging off all sessions
**** 14:19:36 Total processor time used = '0.34 Seconds'
.
Start : Mon Aug 02 14:19:26 2010
.
End
: Mon Aug 02 14:19:36 2010
.
Highest return code encountered = '0'.
**** 14:19:36 FDL4818 FastLoad Terminated
Teradata FastLoad Reference
133
Chapter 3: Teradata FastLoad Commands
RECORD
RECORD
Purpose
The RECORD command defines the records of the input data source at which Teradata
FastLoad processing starts and ends.
Syntax
;
RECORD
startrecordnumber
THRU endrecordnumber
2411A027
where
Syntax Element
Description
startrecordnumber
Record at which processing begins.
The default is record 1.
THRU
Keyword that introduces the optional endrecordnumber parameter.
endrecordnumber
Record after which processing ends.
The endrecordnumber number must be equal to or greater than
startrecordnumber.
Usage Notes
Table 46 describes the things to consider when using the RECORD command.
Table 46: Usage Notes for RECORD
134
Topic
Usage Notes
Entering the
RECORD
Command
Enter the RECORD command before the INSERT statement in the Teradata
FastLoad job.
Restarting
Teradata FastLoad
Jobs
When a job restarts, if the CHECKPOINT option is enabled, the utility begins
reading at the next record immediately after the last checkpointed record.
If a RECORD command is not used, Teradata FastLoad reads from the first
record in the data source to the last record, unless the job is restarted.
Teradata FastLoad Reference
Chapter 3: Teradata FastLoad Commands
RECORD
Table 46: Usage Notes for RECORD (continued)
Topic
Usage Notes
Invalid Record
Numbers
The RECORD command cannot specify invalid record numbers, such as:
• An endrecordnumber less than a startrecordnumber
• A negative value
If an invalid record number is specified, Teradata FastLoad returns an error
message:
• If the error occurs before the BEGIN LOADING command, then all
Teradata FastLoad sessions are logged off and the utility is exited.
• If the error occurs after BEGIN LOADING, then the job pauses (all
Teradata FastLoad sessions are logged off and the tables named in BEGIN
LOADING remain locked until END LOADING is executed).
THRU
Specification
If the THRU endrecordnumber parameter is not specified, Teradata FastLoad
begins to read at startrecordnumber and continues until it finds the last record
in the data source.
Example
The following command example specifies the records in the input data source starting at
record 1,000 and stopping at record 20,000:
RECORD 1000 THRU 20000 ;
Completion Message
The Teradata FastLoad completion message is:
Starting record number set to :1000
Ending record number set to
:20000
Example
The following command example specifies the records in the input data source starting at
record number 1 and stopping at record number 50,000:
RECORD THRU 50000 ;
Completion Message
The Teradata FastLoad completion message is:
Starting record number set to :1
Ending record number set to
:50000
Teradata FastLoad Reference
135
Chapter 3: Teradata FastLoad Commands
RUN
RUN
Purpose
The RUN command invokes a specified external source as the current source of commands
and statements.
Syntax
.RUN [FILE] fileid
;
2411B035
where
Syntax Element
Description
fileid
Data source of the external system.
The external system DD (or similar) statement specifies a file.
• In z/OS, the fileid is a DDNAME. (See the “z/OS fileid Usage Rules” topic in
“Usage Notes.”)
• In UNIX and Windows systems, the fileid is the path name for a file.
FILE
The keyword FILE is optional.
Usage Notes
Table 47 describes the things to consider when using the RUN command.
136
Teradata FastLoad Reference
Chapter 3: Teradata FastLoad Commands
RUN
Table 47: Usage Notes for Run
Topic
Usage Notes
z/OS fileid Usage
Rules
If a DDNAME is specified, Teradata FastLoad reads data records from the
specified source.
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.
The DDNAME must obey the applicable rules of the external system and may
reference a sequential or VSAM data set.
If the DDNAME represents a data source on magnetic tape, the tape may be
either labeled or nonlabeled, as supported by the operating system.
Executing the
RUN Command
After Teradata FastLoad executes the RUN command, it reads additional
commands 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 FastLoad to resume
reading its commands and DML statements from the previously active source:
• SYSIN for z/OS
• stdin (normal or redirected) for UNIX and Windows systems
Note: SYSIN/stdin remains the active input source after Teradata FastLoad
processes any user-provided invocation parameters.
Nested RUN
Commands
Teradata FastLoad Reference
The source specified by a RUN command can have up to five levels of nested
RUN commands.
137
Chapter 3: Teradata FastLoad Commands
SESSIONS
SESSIONS
Purpose
The SESSIONS command specifies how many Teradata FastLoad sessions will be logged on
when a LOGON command is entered and, optionally, the minimum number of sessions
required to run the job.
Syntax
SESSIONS
;
max
*
min
*
2411A028
where
Syntax Element
Description
max
Maximum number of sessions to log on.
The max specification must be greater than zero.
The default, if the SESSIONS command is not used, is one session for each
AMP.
min
Minimum number of sessions required for the job to continue.
The min specification must be greater than zero.
The default, if the SESSIONS command is not used, is 1.
*
Minimum and maximum number of sessions.
Using the asterisk character as the max specification logs on for the
maximum number of sessions—one for each AMP.
Using the asterisk character as the min specification logs on for at least one
session, but less than or equal to the max specification.
Note:
1) Specifying SESSIONS * * has the same effect as not using the
SESSIONS command at all.
2) On large to very large Teradata Database configurations, the
default of one session per AMP may be inappropriate.
138
Teradata FastLoad Reference
Chapter 3: Teradata FastLoad Commands
SESSIONS
Syntax Element
Description
* (continued)
There is no general method to determine the optimal number of sessions,
because it is dependent on several factors, including, but not limited to:
• Teradata Database performance and workload
• Client platform type, performance, and workload
• Channel performance, for channel-attached systems
• Network topology and performance, for network-attached systems
• Volume of data to be processed by the application
Using too few sessions is likely to unnecessarily limit throughput. On the
other hand, using too many sessions can increase session management
overhead (and also reduce the number of sessions available to any other
applications) and may, in some circumstances, degrade throughput.
Regardless of the size of the Teradata Database configuration, for large
repetitive production applications, it will usually be appropriate to
experiment with several different session configurations to determine the best
trade-off between resource utilization and throughput performance.
For larger Teradata Database configurations, it is appropriate to establish an
installation default for the maximum number of sessions that is less than one
session per AMP. This can be done either via the installation configuration
file (see “Teradata FastLoad Configuration File” on page 52) or via a standard
runtime parameter (see “Channel-Attached Runtime Parameters” on
page 35). An installation default for number of sessions, if specified in the
configuration file, can be overridden in individual Teradata FastLoad job
scripts, when necessary.
Usage Notes
Table 48 describes the things to consider when using the SESSIONS command.
Table 48: Usage Notes for SESSIONS
Topic
Usage Notes
DBS Support
TASM
If the DBS supports TASM, the SESSIONS command has no effect since the
number of sessions is determined by the DBS setup rules, Please refer to TRP
541-0007249 for DBS support TASM document. If FastLoad must connect to
the exact number of sessions required by the DBS, otherwise FastLoad will
displays the following message and terminates the job:
The number of FastLoad connections (n1) is not the same as the number of
connections returned by CHECK WORKLOAD END (n2) where n1 is the
number of sessions that FastLoad can connect and n2 is the number of
sessions that FastLoad must connect to required by the DBS.
Entering the
SESSIONS
Command
Teradata FastLoad Reference
The SESSIONS command must be entered before the LOGON command in
the Teradata FastLoad job.
139
Chapter 3: Teradata FastLoad Commands
SESSIONS
Table 48: Usage Notes for SESSIONS (continued)
Topic
Usage Notes
Session Number
Limits
Regardless of the number of sessions specified, the actual number of sessions
Teradata FastLoad uses is limited to the number of AMPs available on the
Teradata Database. Thus, there is no guarantee that the number of sessions
specified in the command will actually be logged on.
Reported Number
of Sessions
Teradata FastLoad reports the number of sessions logged on when a LOGON
command is executed.
Invalid Number of
Sessions
The maximum relevant number of sessions which can be specified is 32767.
Teradata FastLoad disregards any larger number and logs on for as many
sessions as it can—one session per available AMP, as indicated in the
Teradata FastLoad error message:
FDL4867 Invalid number of sessions requested
FastLoad will log on as many sessions as possible
Example 1
The following example specifies five Teradata FastLoad sessions:
SESSIONS 5 ;
Example 2
The following example specifies ten Teradata FastLoad sessions, with a minimum of five:
SESSIONS 10 5 ;
Completion Message
The Teradata FastLoad completion message is:
FDL4866 SESSIONS command accepted
Error Message
If an invalid value is specified, Teradata FastLoad responds with the following error message:
FDL4867 Invalid number of sessions requested
FastLoad will log on as many sessions as possible.
140
Teradata FastLoad Reference
Chapter 3: Teradata FastLoad Commands
SET RECORD
SET RECORD
Purpose
The SET RECORD command specifies the format of the input data as:
•
Formatted
•
Unformatted
•
Binary
•
Text
•
Variable-length text
The SET RECORD command:
•
Applies only to network-attached systems
•
Can be specified only one time per Teradata FastLoad job script
•
When specified, must be appear before the DEFINE command
Syntax
SET RECORD
;
FORMATTED
UNFORMATTED
BINARY
TEXT
VARTEXT
"c "
DISPLAY_ERRORS
NOSTOP
2411A012
where
Syntax Element
Description
FORMATTED
Keyword specification that the input data source is in Teradata Database
standard format.
This is the default specification, if the SET RECORD command is not used
in the Teradata FastLoad job script.
UNFORMATTED
Keyword specification that the input data source deviates from Teradata
Database standard format.
Unformatted data originates from other sources, such as.
BINARY
Keyword specification that the input data source is in binary format.
The format must be a 2-byte integer, n, followed by n bytes of data.
Teradata FastLoad Reference
141
Chapter 3: Teradata FastLoad Commands
SET RECORD
Syntax Element
Description
TEXT
Keyword specification that the input data source is in text format.
The format must be an arbitrary number of bytes, followed by an end-ofrecord marker, which is a:
• Line feed (x’0A) on UNIX platforms
• Carriage-return/line feed pair (X’0D0A’) on Windows platforms
VARTEXT
Keyword specification that the input data source is in variable-length text
record format, with each field separated by a delimiter character.
“c”
Optional specification of the delimiter character that separates fields in the
variable-length text records of the input data source.
Rules for a delimiter character are:
• No control character 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 be a multi-character sequence up to a maximum of 10
bytes.
Note: Multibyte characters can be 1 byte, 2 bytes or 3 bytes depending on
the session character set. The number of characters that can be used as
delimiters is limited by the byte size of the characters
For example: Setting 10 Japanese characters with KANJIEUC_0U code has
a string length of 20 bytes. In this case, FastLoad will fail with an error
message of “The xxxxxxxxxx string exceeds the length limit.” The number
of Japanese characters must be reduced to 5, which equals 10 bytes.
The default, if a “c” specification is not used, is the pipe character ( | ).
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 FastLoad
termination in response to an error condition associated with a variablelength text record.
Usage Notes
The following are the things to consider when using the SET RECORD command.
•
Data Formats
The input source data can be either in text or binary format, where
•
•
Text format is a data source containing characters for display on an ASCII terminal.
•
Binary format is numbers in hexadecimal
Unformatted Records
When UNFORMATTED is specified, Teradata FastLoad assumes nothing concerning the
structure of the data, end-of-record delimiters, special characters and field length
indicators. The input data can be either text or binary:
•
142
Use both an INSERT statement and a DEFINE command to define the fields
Teradata FastLoad Reference
Chapter 3: Teradata FastLoad Commands
SET RECORD
•
For binary data, manually insert the indicator bytes preceding each record
Teradata FastLoad then uses the DEFINE clause as a guide to calculate the actual length of
each record.
Data that is extraneous and not intended for use can be defined as CHAR.
Note: For ASCII data, line ending characters can differ from platform to platform. For
example, some systems might only use a carriage return character, while others might use
both a carriage return and a line feed character to end a line. Always consider the
platform-dependent characteristics when reading ASCII data from a text file.
•
VARTEXT Records
When VARTEXT is specified, Teradata FastLoad assumes that the input data is variablelength 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.
•
Data Type Specifications
When using the VARTEXT specification, VARCHAR and VARBYTE are the only valid
data type specifications which can be used in the Teradata FastLoad DEFINE
command.
•
Null Fields
Two consecutive delimiter characters direct Teradata FastLoad to null the field
corresponding to the one right after the first delimiter character.
Also, if the last character in a record is a delimiter character, and yet there was at least
one more field to be processed, Teradata FastLoad nulls the field corresponding to the
next one to be processed, as defined in the DEFINE command.
•
Input Record Requirements
The total number of fields in each input record must be equal to or greater than the
number of fields described in the Teradata FastLoad DEFINE command. If the total
number is less, Teradata FastLoad generates an error message. If the total number is
more, the Teradata Database ignores the extra fields.
•
Error Record Handling
When Teradata FastLoad encounters an error condition in an input record, it
normally discards the record and terminates. When loading variable-length text
records, either or both of these functions can be inhibited by specifying the errorhandling options:
•
DISPLAY_ERRORS
•
NOSTOP
By specifying both options and redirecting STDERR to a file location instead of the
terminal screen, the Teradata FastLoad job will run to completion and save all the
error records. They can then be manually modified using another utility such as BTEQ
or MultiLoad to load them into the table.
•
Variable-length Fields
When using variable-length fields in either formatted or unformatted records, either:
Teradata FastLoad Reference
143
Chapter 3: Teradata FastLoad Commands
SET RECORD
•
Include a two-byte binary integer indicator immediately preceding each variablelength field. Teradata FastLoad uses this indicator to determine the exact length of the
field.
•
Pad each variable-length field with blanks to produce fixed-length fields
In either case, the maximum field length as shown in the table definition cannot be
exceeded.
•
DEFINE and INSERT Specifications
Use VARCHAR specifications in the DEFINE command and INSERT statements for
variable-length data:
User.Table
Name
Co1001
Co1002
Co1003
define
Definition
Type
Size
Integer
4 bytes
Varchar(8)
up to 8 bytes
Date
4 bytes
Co1001 (integer),
Co1002 (Varchar(8)),
Co1003 (date)
file = file_path ;
insert into User.Table
values ( :Co1001,
:Co1002,
:Co1003 ) ;
To pad a variable-length field to the maximum used in the table definition (in this case
eight bytes) define column 2 as Char(8) with the table definition remaining Varchar(8).
The following table (User.Table) contains three columns of fixed-length data types. Each
record has four bytes as an integer, followed by eight bytes of characters, and then four
bytes of a date in integer format:
User.Table Definition
Name
Type
Co1001
Integer
Co1002
Char(8)
Co1003
Date
Size
4 bytes
8 bytes
4 bytes
Assuming that the fields in the record correspond exactly to the table columns, the
DEFINE command and INSERT statement specifications would be:
define
Co1001 (integer),
Co1002 (char(8)),
Co1003 (date)
file = file_path ;
insert into User.Table
values ( :Co1001,
:Co1002,
:Co1003 ) ;
Co1001 Co1002 Co1003
|00030506|4549474854202020|000CFD1F
The DEFINE and INSERT specifications to define undesirable data (such as special control
characters or carriage returns using HEX 0A as end-of-record delimiters) would be:
defineDummy(char(8)),
Co1001
(integer),
Co1002
(char(8)),
Co1003
(date),
144
Teradata FastLoad Reference
Chapter 3: Teradata FastLoad Commands
SET RECORD
Newline(char(1))
file = file_path ;
insert into User.Table
values ( :Co1001,
:Co1002,
:Co1003 ) ;
Control Char Co1001 Co1002 Co1003
0FCA037CB86BFF8A|00030506|4549474854202020|000CFD1F|0A
New line
Note: Some systems might require a Newline(char(2)) specification instead of
Newline(char(1)).
Example
The following command example sets records to unformatted mode:
set record unformatted ;
Completion Message
The Teradata FastLoad completion message is:
Now set to read “UNFORMATTED” records.
Teradata FastLoad Reference
145
Chapter 3: Teradata FastLoad Commands
SET SESSION CHARSET
SET SESSION CHARSET
Purpose
The SET SESSION CHARSET command specifies which character set is in effect during a
specific Teradata FastLoad invocation.
Note: The SET SESSION CHARSET command applies only to network-attached systems. For
channel-attached systems, see “Invoking Teradata FastLoad” on page 33 for a description of
the CHARSET parameter.
Syntax
SET SESSION CHARSET
"
ASCII
"
;
KANJIEUC _ 0 U
KANJISJIS _ 0 S
2411B029
where
Syntax Element
Description
ASCII
ASCII character set.
KANJIEUC_0U
Kanji Extended UNIX Code character set.
KANJISJIS_0S
Combined JIS-x0208 and JIS-x0201 character set developed by
Microsoft.
Usage Notes
Table 49 describes the things to consider when using the SET SESSION CHARSET command.
Table 49: Usage Notes for SET SESSION CHARSET
146
Topic
Usage Notes
Command Placement
The SET SESSION CHARSET command must appear before the
LOGON command in the Teradata FastLoad job script.
Double Quote
Characters in Character
Set Name Specifications
The names of the character sets must be enclosed in double quote
characters.
Teradata FastLoad Reference
Chapter 3: Teradata FastLoad Commands
SET SESSION CHARSET
Table 49: Usage Notes for SET SESSION CHARSET (continued)
Topic
Usage Notes
Priority of Character
Set Specifications
The order in which the character set is determined for a Teradata
FastLoad job is:
1 User specified by a:
• Runtime parameter (This specification has the highest priority on
all supported platforms.)
• SET SESSION CHARSET command on network-attached
systems
• CHARSET parameter in the Teradata FastLoad configuration file
2 System Parameter Block (SPB) specified by the:
• HSHSPB on channel-attached systems
• clispb.dat file on network-attached systems.
3 Teradata Database default, determined by a query from Teradata
FastLoad.
Teradata FastLoad Reference
147
Chapter 3: Teradata FastLoad Commands
SHOW
SHOW
Purpose
The SHOW command displays active definitions for the input data source or INMOD routine
and the field names that were established by one or more DEFINE commands.
Syntax
SHOW
;
2411A030
Usage Notes
The SHOW command displays:
•
Field names
•
Data type (integer or character) of each field
•
Internal length of each field
•
Offset of each field within the input record
•
Input data source or INMOD routine names
If a DEFINE command has not been entered, the result is blank and Teradata FastLoad
responds with this message:
TOTAL RECORD LENGTH = 0
Note: The SHOW command is processed by Teradata FastLoad. It is not transmitted to the
Teradata Database.
Example
When the following DEFINE command is active:
DEFINE EmpNo (smallint),
Name (varchar(12)),
DeptNo (decimal (3,0)),
JobTitle (varchar(12)),
Salary (decimal(8,2)),
YrsExp (byteint),
DOB (date),
Sex (char(1)),
Race (char(1)),
MStat (char(1)),
EdLev (byteint),
HCap (byteint)
FILE=EmpData ;
148
Teradata FastLoad Reference
Chapter 3: Teradata FastLoad Commands
SHOW
The Teradata FastLoad response to the SHOW command is:
FILE = EmpData
EMPNO
OFFSET=
NAME
OFFSET =
DEPTNO
OFFSET=
JOBTITLE
OFFSET=
SALARY
OFFSET=
YRSEXP
OFFSET=
DOB
OFFSET=
SEX
OFFSET=
RACE
OFFSET=
MSTAT
OFFSET=
EDLEV
OFFSET=
HCAP
OFFSET=
TOTAL RECORD LENGTH=
Teradata FastLoad Reference
0
2
16
18
32
36
37
41
42
43
44
45
46
LEN
LEN
LEN
LEN
LEN
LEN
LEN
LEN
LEN
LEN
LEN
LEN
=
=
=
=
=
=
=
=
=
=
=
=
2
12
2
12
4
1
4
1
1
1
1
1
SMALLINT
VARCHAR
DECIMAL
VARCHAR
DECIMAL
BYTEINT
DATE
CHAR
CHAR
CHAR
BYTEINT
BYTEINT
149
Chapter 3: Teradata FastLoad Commands
SHOW VERSIONS
SHOW VERSIONS
Purpose
The SHOW VERSIONS command displays the current level of all Teradata FastLoad utility
software modules.
Syntax
SHOW
VERSIONS
;
VERSION
2411A031
Usage Notes
Use the SHOW VERSIONS command to retrieve the version information when reporting
software problems.
Example
The following command example displays the current versions of software modules in use:
0001 show versions;
FastLoad Version 13.10.00.000 for SOLARIS running Socket TCP/IP
FastLoad : 13.10.00.10
FastCmds : 13.10.00.09
FastIO
: 13.10.00.02
FastMBCS : 13.00.00.02
FastNtfy : 13.10.00.00
FastPars : 13.10.00.01
FastSQL
: 13.10.00.10
FastUtil : 13.10.00.02
Fdlosdep : 13.10.00.00
Teradata Data Connector : 13.10.00.000
PMPROCS
: 13.10.00.05
PMRWFMT
: 13.01.00.03
PMTRCE
: 13.10.00.02
PMMM
: 13.00.00.01
PMHEXDMP : 13.00.00.01
PMUNXDSK : 13.10.00.05
ICUVER
: TDICU, 13.10d.00.00
CLIV2
: 13.10.00.18
MTDP
: 13.10.00.19
MOSIos
: 13.10.00.03
MOSIDEP
: 13.10.00.04
OSENCRYPT : N/A
OSERR
: 13.10.00.01
FastLoad linking date: Aug 02 2010
150
Teradata FastLoad Reference
Chapter 3: Teradata FastLoad Commands
SLEEP
SLEEP
Purpose
The SLEEP command specifies the number of minutes that Teradata FastLoad pauses before
retrying a logon operation when the maximum number of load operations is already running
on the Teradata Database.
Syntax
;
SLEEP minutes
2411A032
where
Syntax Element
Description
minutes
Number of minutes that Teradata FastLoad pauses before retrying the logon
operation.
The minutes specification must be greater than zero. If zero is entered,
Teradata FastLoad responds with an error message, and terminates.
The Teradata FastLoad default, if the SLEEP command is not used, the
number of minutes is 6.
Usage Notes
Table 50 describes the things to consider when using the SLEEP command.
Teradata FastLoad Reference
151
Chapter 3: Teradata FastLoad Commands
SLEEP
Table 50: Usage Notes for SLEEP
Topic
Usage Notes
Function
The SLEEP specification works with the TENACITY specification to control
Teradata FastLoad logon attempts.
When Teradata FastLoad tries to log on for a new session, and the Teradata
Database indicates that the maximum number of load sessions is already
running, the Teradata FastLoad utility:
1 Logs off any new sessions that were logged on
2 Waits for 6 minutes, by default, or for the amount of time specified by the
SLEEP command
3 Tries again to log on to the Teradata Database
Teradata FastLoad repeats this process until it has either logged on for the
required number of sessions or exceeded the amount of time specified by the
TENACITY command.
Command
Placement
Command placement affects the logon operation. State the SLEEP and
TENACITY commands before the LOGON command in the Teradata
FastLoad job script. Teradata FastLoad terminates with an error message if
these commands are stated after the LOGON command.
Command
Overrides
The SLEEP and TENACITY command specifications override the
corresponding SLEEP and TENACITY specifications that may be made in the
Teradata FastLoad configuration file.
Similarly, the SLEEP and TENACITY command specifications themselves are
overridden by the corresponding specifications made as runtime parameters
when invoking Teradata FastLoad.
The order of preferences for the SLEEP and TENACITY specifications, from
highest to lowest, is:
1 Runtime parameters
2 Teradata FastLoad script commands
3 Teradata FastLoad configuration file specifications
4 Teradata FastLoad default values
152
Teradata FastLoad Reference
Chapter 3: Teradata FastLoad Commands
TENACITY
TENACITY
Purpose
The TENACITY command specifies the number of hours that Teradata FastLoad continues
trying to log on when the maximum number of load operations is already running on the
Teradata Database.
Syntax
;
TENACITY hours
2411A033
where
Syntax Element
Description
hours
Number of hours that Teradata FastLoad continues trying to log on.
The hours specification must be greater than zero. If zero is entered, Teradata
FastLoad responds with an error message and terminates.
Usage Notes
Table 51 describes the things to consider when using the TENACITY command.
Teradata FastLoad Reference
153
Chapter 3: Teradata FastLoad Commands
TENACITY
Table 51: Usage Notes for TENACITY
Topic
Usage Notes
Function
The TENACITY specification works with the SLEEP specification to control
Teradata FastLoad logon attempts.
When Teradata FastLoad tries to log on for a new session, and the Teradata
Database indicates that the maximum number of load sessions is already
running, Teradata FastLoad:
1 Logs off any new sessions that were logged on
2 Waits for 6 minutes, by default, or for the amount of time specified by the
SLEEP command
3 Tries again to log on to the Teradata Database
Teradata FastLoad repeats this process until it has either logged on for the
required number of sessions or exceeded the amount of time specified by the
TENACITY command.
Note: The utility default for TENACITY is no tenacity. A Teradata FastLoad
configuration file entry, the runtime parameter, or a TENACITY command
must be used in the Teradata FastLoad job script to enable the tenacity feature
for the Teradata FastLoad logon operation.
Command
Placement
Command placement affects the logon operation. State the TENACITY and
SLEEP commands before the LOGON command in the Teradata FastLoad job
script. Teradata FastLoad terminates with an error message if the Teradata
FastLoad job script states the TENACITY or SLEEP command after the
LOGON command.
Command
Overrides
The TENACITY and SLEEP command specifications override the
corresponding TENACITY and SLEEP specifications that may be made in the
Teradata FastLoad configuration file.
Similarly, the TENACITY and SLEEP command specifications themselves are
overridden by the corresponding specifications made as runtime parameters
when invoking Teradata FastLoad.
The order of preferences for the TENACITY and SLEEP specifications, from
highest to lowest, is:
1 Runtime parameters
2 Teradata FastLoad script commands
3 Teradata FastLoad configuration file specifications
4 Teradata FastLoad default values
154
Teradata FastLoad Reference
APPENDIX A
How to Read Syntax Diagrams
This appendix describes the conventions that apply to reading the syntax diagrams used in
this book.
Syntax Diagram Conventions
Notation Conventions
Item
Definition / Comments
Letter
An uppercase or lowercase alphabetic character ranging from A through Z.
Number
A digit ranging from 0 through 9.
Do not use commas when typing a number with more than 3 digits.
Word
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.
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.
Teradata FastLoad Reference
155
Appendix A: How to Read Syntax Diagrams
Syntax 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:
A
A
FE0CA002
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:
SHOW
FE0CA003
If you can choose from more than one entry, the choices appear vertically, in a stack. The first
entry appears on the main path:
SHOW
CONTROLS
VERSIONS
FE0CA005
Optional Entries
You may choose to include or disregard optional entries. Optional entries appear below the
main path:
SHOW
CONTROLS
FE0CA004
If you can optionally choose from more than one entry, all the choices appear below the main
path:
156
Teradata FastLoad Reference
Appendix A: How to Read Syntax Diagrams
Syntax Diagram Conventions
READ
SHARE
ACCESS
JC01A010
Some commands and statements treat one of the optional choices as a default value. This
value is UNDERLINED. It is presumed to be selected if you type the command or statement
without specifying one of the options.
Strings
Strings appear in single quotes:
'msgtext'
JC01A004
If the string text includes a single quote or a blank space, the string appears in double quotes:
''abc'd"
''abc d"
JC01A005
Abbreviations
If a keyword or a reserved word has a valid abbreviation, the unabbreviated form always
appears on the main path. The shortest valid abbreviation appears beneath.
SHOW
CONTROLS
CONTROL
FE0CA042
In the above syntax, the following formats are valid:
•
SHOW CONTROLS
•
SHOW CONTROL
Loops
A loop is an entry or a group of entries that you can repeat one or more times. Syntax
diagrams show loops as a return path above the main path, over the item or items that you can
repeat:
Teradata FastLoad Reference
157
Appendix A: How to Read Syntax Diagrams
Syntax Diagram Conventions
,
,
(
cname
3
4
)
JC01B012
Read loops from right to left.
The following conventions apply to loops:
Loop Convention
Description
A maximum number of entries is
allowed.
The number appears in a circle on the return path.
A minimum number of entries is
required.
The number appears in a square on the return path.
A separator character is required
between entries.
The character appears on the return path.
In the example, you may type cname a maximum of 4 times.
In the example, you must type at least three groups of column
names.
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.
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.
158
Teradata FastLoad Reference
Appendix A: How to Read Syntax Diagrams
Syntax 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:
LOCKING
excerpt
A
A
HAVING
con
excerpt
where_cond
,
cname
,
col_pos
JC01A014
Multiple Legitimate Phrases
In a syntax diagram, it is possible for any number of phrases to be legitimate:
dbname
DATABASE
tname
TABLE
vname
VIEW
JC01A016
In this example, any of the following phrases are legitimate:
•
dbname
•
DATABASE dbname
•
tname
•
TABLE tname
•
vname
•
VIEW vname
Teradata FastLoad Reference
159
Appendix A: How to Read Syntax Diagrams
Syntax Diagram Conventions
Sample Syntax Diagram
,
viewname
CREATE VIEW
AS
cname
CV
A
LOCKING
LOCK
ACCESS
dbname
A
DATABASE
SHARE
FOR
IN
tname
READ
TABLE
WRITE
EXCLUSIVE
vname
VIEW
EXCL
,
B
SEL
B
MODE
expr
,
FROM
tname
qual_cond
C
.aname
C
HAVING cond
;
qual_cond
,
WHERE cond
GROUP BY
cname
,
col_pos
JC01A018
Diagram Identifier
The alphanumeric string that appears in the lower right corner of every diagram is an internal
identifier used to catalog the diagram. The text never refers to this string.
160
Teradata FastLoad Reference
APPENDIX B
Multifile Teradata FastLoad Job Script
Examples
This appendix provides three example multifile Teradata FastLoad job scripts. The third script
includes the END LOADING command.
The following subsections show the output from the three Teradata FastLoad job scripts.
Note: The third output file contains the final statistics.
First Output File
===================================================================
=
=
=
FASTLOAD UTILITY
VERSION 13.10.00.000
=
=
PLATFORM SOLARIS/SPARC
=
=
=
===================================================================
===================================================================
=
=
=
Copyright 1984-2010, Teradata Corporation.
=
=
ALL RIGHTS RESERVED.
=
=
=
===================================================================
**** 17:37:09 Processing starting at: Mon Aug 02 17:37:09 2010
0001 RECORD 1 THRU 10;
**** 17:37:09 Starting record number set to
**** 17:37:09 Ending record number set to
: 1
: 10
0002 .SESSIONS 10;
**** 17:37:09 FDL4866 SESSIONS command accepted
0003 SHOW VERSION;
FastLoad Version 13.10.00.000 for SOLARIS running Socket TCP/IP
FastLoad : 13.10.00.10
FastCmds : 13.10.00.09
FastIO
: 13.10.00.02
FastMBCS : 13.00.00.02
FastNtfy : 13.10.00.00
FastPars : 13.10.00.01
Teradata FastLoad Reference
161
Appendix B: Multifile Teradata FastLoad Job Script Examples
First Output File
FastSQL
: 13.10.00.10
FastUtil : 13.10.00.02
Fdlosdep : 13.10.00.00
Teradata Data Connector : 13.10.00.000
PMPROCS
: 13.10.00.05
PMRWFMT
: 13.01.00.03
PMTRCE
: 13.10.00.02
PMMM
: 13.00.00.01
PMHEXDMP : 13.00.00.01
PMUNXDSK : 13.10.00.05
ICUVER
: TDICU, 13.10d.00.00
CLIV2
: 13.10.00.18
MTDP
: 13.10.00.19
MOSIos
: 13.10.00.03
MOSIDEP
: 13.10.00.04
OSENCRYPT : N/A
OSERR
: 13.10.00.01
FastLoad linking date: Aug 02 2010
===================================================================
=
=
=
Logon/Connection
=
=
=
===================================================================
0004 LOGON dbs103/amazon,
****
****
****
****
****
****
****
17:37:09
17:37:09
17:37:09
17:37:09
17:37:11
17:37:11
17:37:11
Teradata Database Release: 13.00.00.00
Teradata Database Version: 13.00.00.00
Current CLI or RDBMS allows maximum row size: 64K
Character set for this job: ASCII
Number of FastLoad sessions requested = 10
Number of FastLoad sessions connected = 2
FDL4808 LOGON successful
0005 DROP TABLE Error_1;
**** 17:37:11 Command completed successfully
0006 DROP TABLE Error_2;
**** 17:37:11 Command completed successfully
0007 DROP TABLE test2;;
**** 17:37:11 Command completed successfully
0008 CREATE TABLE test2, fallback
(Counter INTEGER,
text CHAR(10))
UNIQUE PRIMARY INDEX (Counter);
**** 17:37:11 Command completed successfully
0009 BEGIN LOADING test2 ErrorFiles Error_1, Error_2;
**** 17:37:12 Number of AMPs available: 2
162
Teradata FastLoad Reference
Appendix B: Multifile Teradata FastLoad Job Script Examples
Second Output File
**** 17:37:12 BEGIN LOADING COMPLETE
0010 DEFINE Counter (int),
text (char(10))
FILE=test.data;
**** 17:37:12 FDL4803 DEFINE statement processed
===================================================================
=
=
=
Insert Phase
=
=
=
===================================================================
0011 INSERT INTO test2 (Counter, text) VALUES (:Counter, :text);
****
****
****
****
17:37:12
17:37:12
17:37:12
17:37:12
Number of recs/msg: 1587
Starting to send to RDBMS with record 1
Sending row 10
Finished sending rows to the RDBMS
0012 LOGOFF;
===================================================================
=
=
=
Logoff/Disconnect
=
=
=
===================================================================
**** 17:37:12 Logging off all sessions
**** 17:37:12 Total processor time used = '1.53 Seconds'
.
Start : Mon Aug 02 17:37:09 2010
.
End
: Mon Aug 02 17:37:12 2010
.
Highest return code encountered = '4'.
**** 17:37:12 FastLoad Paused
Second Output File
===================================================================
=
=
=
FASTLOAD UTILITY
VERSION 13.10.00.000
=
=
PLATFORM SOLARIS/SPARC
=
=
=
===================================================================
===================================================================
=
=
=
Copyright 1984-2010, Teradata Corporation.
=
=
ALL RIGHTS RESERVED.
=
=
=
===================================================================
**** 17:37:29 Processing starting at: Mon Aug 02 17:37:29 2010
0001 RECORD 101 THRU 110;
Teradata FastLoad Reference
163
Appendix B: Multifile Teradata FastLoad Job Script Examples
Second Output File
**** 17:37:29 Starting record number set to
**** 17:37:29 Ending record number set to
: 101
: 110
0002 .SESSIONS 10;
**** 17:37:29 FDL4866 SESSIONS command accepted
0003 SHOW VERSION;
FastLoad Version 13.10.00.000 for SOLARIS running Socket TCP/IP
FastLoad : 13.10.00.10
FastCmds : 13.10.00.09
FastIO
: 13.10.00.02
FastMBCS : 13.00.00.02
FastNtfy : 13.10.00.00
FastPars : 13.10.00.01
FastSQL
: 13.10.00.10
FastUtil : 13.10.00.02
Fdlosdep : 13.10.00.00
Teradata Data Connector : 13.10.00.000
PMPROCS
: 13.10.00.05
PMRWFMT
: 13.01.00.03
PMTRCE
: 13.10.00.02
PMMM
: 13.00.00.01
PMHEXDMP : 13.00.00.01
PMUNXDSK : 13.10.00.05
ICUVER
: TDICU, 13.10d.00.00
CLIV2
: 13.10.00.18
MTDP
: 13.10.00.19
MOSIos
: 13.10.00.03
MOSIDEP
: 13.10.00.04
OSENCRYPT : N/A
OSERR
: 13.10.00.01
FastLoad linking date: Aug 02 2010
===================================================================
=
=
=
Logon/Connection
=
=
=
===================================================================
0004 LOGON dbs103/amazon,
****
****
****
****
****
****
****
17:37:29
17:37:29
17:37:29
17:37:29
17:37:31
17:37:31
17:37:31
Teradata Database Release: 13.00.00.00
Teradata Database Version: 13.00.00.00
Current CLI or RDBMS allows maximum row size: 64K
Character set for this job: ASCII
Number of FastLoad sessions requested = 10
Number of FastLoad sessions connected = 2
FDL4808 LOGON successful
0005 BEGIN LOADING test2 ErrorFiles Error_1, Error_2;
**** 17:37:32 FastLoad is continuing a multifile job
**** 17:37:32 Number of AMPs available: 2
**** 17:37:32 BEGIN LOADING COMPLETE
164
Teradata FastLoad Reference
Appendix B: Multifile Teradata FastLoad Job Script Examples
Third Output File
006 DEFINE Counter (int),
text (char(10))
FILE=test.data;
**** 17:37:32 FDL4803 DEFINE statement processed
===================================================================
=
=
=
Insert Phase
=
=
=
===================================================================
0007 INSERT INTO test2 (Counter, text) VALUES (:Counter, :text);
****
****
****
****
17:37:32
17:37:32
17:37:32
17:37:32
Number of recs/msg: 1587
Starting to send to DBS with record 101
Sending row 110
Finished sending rows to the DBS
0008 LOGOFF;
===================================================================
=
=
=
Logoff/Disconnect
=
=
=
===================================================================
**** 17:37:32 Logging off all sessions
**** 17:37:32 Total processor time used = '1.53 Seconds'
.
Start : Mon Aug 02 17:37:29 2010
.
End
: Mon Aug 02 17:37:32 2010
.
Highest return code encountered = '4'.
**** 17:37:32 FastLoad Paused
Third Output File
===================================================================
=
=
=
FASTLOAD UTILITY
VERSION 13.10.00.000
=
=
PLATFORM SOLARIS/SPARC
=
=
=
===================================================================
===================================================================
=
=
=
Copyright 1984-2010, Teradata Corporation.
=
=
ALL RIGHTS RESERVED.
=
=
=
===================================================================
**** 17:37:44 Processing starting at: Mon Aug 02 17:37:44 2010
0001 RECORD 201 THRU 210;
**** 17:37:44 Starting record number set to
Teradata FastLoad Reference
: 201
165
Appendix B: Multifile Teradata FastLoad Job Script Examples
Third Output File
**** 17:37:44 Ending record number set to
: 210
0002 .SESSIONS 10;
**** 17:37:44 FDL4866 SESSIONS command accepted
0003 SHOW VERSION;
FastLoad Version 13.10.00.000 for SOLARIS running Socket TCP/IP
FastLoad : 13.10.00.10
FastCmds : 13.10.00.09
FastIO
: 13.10.00.02
FastMBCS : 13.00.00.02
FastNtfy : 13.10.00.00
FastPars : 13.10.00.01
FastSQL
: 13.10.00.10
FastUtil : 13.10.00.02
Fdlosdep : 13.10.00.00
Teradata Data Connector : 13.10.00.000
PMPROCS
: 13.10.00.05
PMRWFMT
: 13.01.00.03
PMTRCE
: 13.10.00.02
PMMM
: 13.00.00.01
PMHEXDMP : 13.00.00.01
PMUNXDSK : 13.10.00.05
ICUVER
: TDICU, 13.10d.00.00
CLIV2
: 13.10.00.18
MTDP
: 13.10.00.19
MOSIos
: 13.10.00.03
MOSIDEP
: 13.10.00.04
OSENCRYPT : N/A
OSERR
: 13.10.00.01
FastLoad linking date: Aug 02 010
===================================================================
=
=
=
Logon/Connection
=
=
=
===================================================================
0004 LOGON dbs103/amazon,
****
****
****
****
****
****
****
17:37:44
17:37:44
17:37:44
17:37:44
17:37:46
17:37:46
17:37:46
Teradata Database Release: 13.00.00.00
Teradata Database Version: 13.00.00.00
Current CLI or RDBMS allows maximum row size: 64K
Character set for this job: ASCII
Number of FastLoad sessions requested = 10
Number of FastLoad sessions connected = 2
FDL4808 LOGON successful
0005 BEGIN LOADING test2 ErrorFiles Error_1, Error_2;
**** 17:37:47 FastLoad is continuing a multifile job
**** 17:37:47 Number of AMPs available: 2
**** 17:37:47 BEGIN LOADING COMPLETE
0006 DEFINE Counter (int),
166
Teradata FastLoad Reference
Appendix B: Multifile Teradata FastLoad Job Script Examples
Third Output File
text (char(10))
FILE=test.data;
**** 17:37:48 FDL4803 DEFINE statement processed
===================================================================
=
=
=
Insert Phase
=
=
=
===================================================================
0007 INSERT INTO test2 (Counter, text) VALUES (:Counter, :text);
****
****
****
****
****
17:37:48
17:37:48
17:37:48
17:37:48
17:37:48
Number of recs/msg: 1587
Starting to send to DBS with record 201
Sending row 205
Sending row 210
Finished sending rows to the DBS
===================================================================
=
=
=
End Loading Phase
=
=
=
===================================================================
0008 END LOADING;
**** 17:37:49 END LOADING COMPLETE
Total Records Read
- skipped by RECORD command
- sent to the DBS
Total Error Table 1
Total Error Table 2
Total Inserts Applied
Total Duplicate Rows
= 230
= 200
= 30
= 0 ---- Table has been dropped
= 0 ---- Table has been dropped
= 30
= 0
Start: Mon Aug 02 17:37:49 2010
End : Mon Aug 02 17:37:55 2010
0009 LOGOFF;
===================================================================
=
=
=
Logoff/Disconnect
=
=
=
===================================================================
**** 17:37:55 Logging off all sessions
**** 17:37:59 Total processor time used = '2.25 Seconds'
.
Start : Mon Aug 02 17:37:47 2010
.
End
: Mon Aug 02 17:37:59 2010
.
Highest return code encountered = '0'.
**** 17:37:47 FDL4818 FastLoad Terminated
Teradata FastLoad Reference
167
Appendix B: Multifile Teradata FastLoad Job Script Examples
Third Output File
168
Teradata FastLoad Reference
APPENDIX C
INMOD and Notify Exit Routine
Examples
This appendix provides program listings of sample INMOD and notify exit routines for the
following Teradata client platforms:
•
z/OS—example INMOD routines written in:
•
•
•
IBM C
UNIX OS—the sample INMOD routines that are provided with Teradata FastLoad
software:
•
BLKEXIT.C
•
BLKEXITR.C
All Platforms—the notify exit routine:
flnfyext.c
z/OS
IBM C INMOD Example
Refer to “BLKEXITR.C Sample INMOD” on page 174. The BLKEXITR.C sample, because it is
written in C and the entry point is written for all platforms, would work on the mainframe for
an IBM C INMOD.
UNIX OS
BLKEXIT.C Sample INMOD
Following is the listing of the BLKEXIT.C sample INMOD routine that is provided with the
Teradata FastLoad utility software:
/*************************************************************************
*
* Title: BLKEXIT - sample INMOD routine
*
* COPYRIGHT (C) Teradata Corporation. 2010
*
* This copyrighted material is the Confidential, Unpublished
* Property of the Teradata Corporation. This copyright notice and
* any other copyright notices included in machine readable
Teradata FastLoad Reference
169
Appendix C: INMOD and Notify Exit Routine Examples
UNIX OS
* copies must be reproduced on all authorized copies.
*
*
* Description This file contains a sample INMOD, written in C.
*
This file does not support DBS restarts.
*
*
* History Information
*
* Revision
Date
DCR
DID
Comments
* ----------- -------- ----- ------- --------------------------------------* 13.00.00.01 09072007 114414 NT185003 Teradata Corporation Copyright
* 13.00.00.00 09012007 100894 SV185048 Visual Studio 8.0 build
* 07.07.00.01 06/22/05 96206 CSG
Port to HP-UX-11.23 on Itanium
* 07.01.00.01 11/12/98 44120 SF3
Release for FastLoad 7.1
* 06.00.00.00 07/18/96 34208 SF3
Release for FastLoad 6.0
*
*
* How to build this INMOD on a UNIX operating system:
*
*
Compile and link it into a shared object:
*
*
cc -G -KPIC <inmod-name>.c -o <shared-object-name>
*
*
* How to use this program:
*
*
This INMOD routine will generate 2 columns of data:
*
*
4-byte integer counter for the Unique Primary Index
*
10-byte character string
*
* This sample INMOD will generate 100,000 rows, if no RECORD
* statement is used in the FastLoad job script.
*
* A sample of the job script for this INMOD would be as follows:
*
*
* use your own system, account and password here.
*
LOGON tdpid/user,password;
DROP TABLE Error_1;
DROP TABLE Error_2;
DROP TABLE TestTable;
CREATE TABLE TestTable AS (
Counter Integer,
text
char(10) )
UNIQUE PRIMARY INDEX(Counter);
BEGIN LOADING TestTable ErrorFiles Error_1, Error_2;
DEFINE
Counter (Integer),
text
(char(10))
INMOD=<shared-object-name>;
INSERT INTO TestTable
170
Teradata FastLoad Reference
Appendix C: INMOD and Notify Exit Routine Examples
UNIX OS
(Counter, text)
VALUES
(:Counter, :text);
END LOADING;
LOGOFF;
*************************************************************************/
#include <stdio.h>
#include <string.h>
#define FILEOF
#define EM_OK
401
0
#define NUMROWS
#define ROWSIZE
100000
64000
typedef int Int32; /* */
typedef unsigned int UInt32; /* */
typedef short Int16;
typedef struct inmod_struct {
Int32 ReturnCode;
Int32 Length;
char Body[ROWSIZE];
} inmdtyp,*inmdptr;
inmdptr inmodptr;
char *str = "123test890";
Int32 reccnt = 0;
/*************************************************************************
*
* MakeRecord - Generate a record
*
*
This module creates the data record
*
*
In this example, we are just generating dummy records
*
with canned data, only we change the first column,
*
essentially a record number, so that each row is unique.
*
*
For performance reasons, we do not change the 2nd column.
*
*************************************************************************/
Int32 MakeRecord()
{
char *p;
/* have we reached EOF yet? */
if (reccnt >= NUMROWS)
return(FILEOF);
/* nope. get start of buffer */
p = inmodptr->Body;
Teradata FastLoad Reference
171
Appendix C: INMOD and Notify Exit Routine Examples
UNIX OS
/* place column 1, a unique primary index */
memcpy(p, &reccnt, (UInt32)sizeof(reccnt));
p += sizeof(reccnt);
/* place column 2, a string */
memcpy(p, str, strlen(str));
p += strlen(str);
inmodptr->ReturnCode = 0;
inmodptr->Length = p - inmodptr->Body;
reccnt++;
return(EM_OK);
}
/*************************************************************************
*
* HostRestart - Host restarted
*
*
Reset and start sending data from the begining.
*
*************************************************************************/
Int32 HostRestart()
{
return(EM_OK);
}
/*************************************************************************
*
* CheckPoint - Save checkpoint
*
*************************************************************************/
Int32 CheckPoint()
{
return(EM_OK);
}
/*************************************************************************
*
* DBSRestart - DBS restarted
*
*
Do what you have to do.
*
Reset record counter to checkpoint value
*
*************************************************************************/
Int32 DBSRestart()
{
return(EM_OK);
}
/*************************************************************************
*
* CleanUp - Do cleanup.
*
*************************************************************************/
172
Teradata FastLoad Reference
Appendix C: INMOD and Notify Exit Routine Examples
UNIX OS
Int32 CleanUp()
{
return(EM_OK);
}
/*************************************************************************
*
* InvalidCode - Invalid INMOD code returned.
*
*************************************************************************/
Int32 InvalidCode()
{
fprintf(stderr, "**** Invalid code received by INMOD\n");
return(EM_OK);
}
/*************************************************************************
*
* Init - initialize some stuff
*
*
Do any initialization necessary
*
*************************************************************************/
Int32 Init()
{
return(EM_OK);
}
/*************************************************************************
*
* BLKEXIT - Start processing
*
*
This is the main module which contains the checks for
*
number of records generated and buffer filling. This
*
module also sends the filled buffer to the DBS.
*
*************************************************************************/
#if defined WIN32
__declspec(dllexport) Int32 BLKEXIT(tblptr)
#elif defined I370
Int32 _dynamn(tblptr)
#else
Int32 BLKEXIT(tblptr)
#endif
char *tblptr;
{
Int32 result;
inmodptr = (struct inmod_struct *)tblptr;
/* process the function passed to the INMOD */
switch (inmodptr->ReturnCode) {
case 0: result = Init();
if (result)
break;
result = MakeRecord();
break;
case 1: result = MakeRecord();
Teradata FastLoad Reference
173
Appendix C: INMOD and Notify Exit Routine Examples
UNIX OS
break;
result
break;
case 3: result
break;
case 4: result
break;
case 5: result
break;
default: result
case 2:
= HostRestart();
= CheckPoint();
= DBSRestart();
= CleanUp();
= InvalidCode();
}
/* see if we have reached EOF condition */
if (result == FILEOF) {
inmodptr->Length = 0;
result = EM_OK;
}
return(result);
}
BLKEXITR.C Sample INMOD
Following is the listing of the BLKEXITR.C sample INMOD routine that is provided with the
Teradata FastLoad utility software:
/*************************************************************************
*
* Title: BLKEXITR - sample INMOD routine
*
* COPYRIGHT (C) Teradata Corporation. 2010
*
* 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.
*
*
* Description This file contains a sample INMOD, written in C.
*
This file supports DBS restarts.
*
*
* History Information
*
* Revision
Date
DCR
DID
Comments
* ----------- -------- ----- ------- --------------------------------------* 13.00.00.01 09072007 114414 NT185003 Teradata Corporation Copyright
* 13.00.00.00 09012007 100894 SV185048 Visual Studio 8.0 build
* 07.07.00.01 06/23/05 96206 CSG
Port to HPUX-11.23 on Itanium
* 07.01.00.01 11/12/98 44120 SF3
Release for FastLoad 7.1
* 06.00.00.00 07/18/96 34208 SF3
Release for FastLoad 6.0
*
*
* How to build this INMOD on a UNIX operating system:
*
*
Compile and link it into a shared object:
*
174
Teradata FastLoad Reference
Appendix C: INMOD and Notify Exit Routine Examples
UNIX OS
*
cc -G -KPIC <inmod-name>.c -o <shared-object-name>
*
*
* How to use this program:
*
*
This INMOD routine will generate 2 columns of data:
*
*
4-byte integer counter for the Unique Primary Index
*
10-byte character string
*
* This sample INMOD will generate 100,000 rows, if no RECORD
* statement is used in the FastLoad job script.
*
* A sample of the job script for this INMOD would be as follows:
*
*
* use your own system, account and password here.
*
LOGON tdpid/user,password;
DROP TABLE Error_1;
DROP TABLE Error_2;
DROP TABLE TestTable;
CREATE TABLE TestTable AS (
Counter Integer,
text
char(10) )
UNIQUE PRIMARY INDEX(Counter);
BEGIN LOADING TestTable ErrorFiles Error_1, Error_2;
DEFINE
Counter (Integer),
text
(char(10))
INMOD=<shared-object-name>;
INSERT INTO TestTable
(Counter, text)
VALUES
(:Counter, :text);
END LOADING;
LOGOFF;
*************************************************************************/
#include <stdio.h>
#include <string.h>
#define FILEOF
#define EM_OK
401
0
#define NUMROWS
#define ROWSIZE
100000
64000
typedef int Int32; /* */
typedef unsigned int UInt32; /* */
typedef short Int16;
Teradata FastLoad Reference
175
Appendix C: INMOD and Notify Exit Routine Examples
UNIX OS
typedef struct inmod_struct {
Int32 ReturnCode;
Int32 Length;
char Body[ROWSIZE];
} inmdtyp,*inmdptr;
inmdptr inmodptr;
char *str = "123test890";
char *fname = "chkpoint.dat";
FILE *fp = NULL;
Int32 reccnt = 0;
Int32 chkpnt;
/*************************************************************************
*
* MakeRecord - Generate a record
*
*
This module creates the data record
*
*
In this example, we are just generating dummy records
*
with canned data, only we change the first column,
*
essentially a record number, so that each row is unique.
*
*************************************************************************/
Int32 MakeRecord()
{
char *p;
/* have we reached EOF yet? */
if (reccnt >= NUMROWS)
return(FILEOF);
/* nope. get start of buffer */
p = inmodptr->Body;
/* place column 1, a unique primary index */
memcpy(p, &reccnt, (UInt32)sizeof(reccnt));
p += sizeof(reccnt);
/* place column 2, a string */
memcpy(p, str, strlen(str));
p += strlen(str);
inmodptr->ReturnCode = 0;
inmodptr->Length = p - inmodptr->Body;
reccnt++;
return(EM_OK);
}
/*************************************************************************
176
Teradata FastLoad Reference
Appendix C: INMOD and Notify Exit Routine Examples
UNIX OS
*
* HostRestart - Host restarted
*
*
Retrieve the checkpoint information from the checkpoint file.
*
Reset record counter to checkpoint value
*
*************************************************************************/
Int32 HostRestart()
{
Int32 result;
/* see if the file is already open */
if (!fp) {
fp = fopen(fname, "r+");
if (!fp)
return(!EM_OK);
}
rewind(fp);
result = fread(&chkpnt, sizeof(chkpnt), 1, fp);
if (result != 1) {
fprintf(stderr, "INMOD: ERROR READING CHECKPOINT FILE\n");
fprintf(stderr, "INMOD: %d ELEMENTS WERE READ\n", result);
perror("INMOD");
return(!EM_OK);
}
fprintf(stderr, "INMOD: HOST RESTARTED. CHECKPOINT: %d\n", chkpnt);
reccnt = chkpnt;
return(EM_OK);
}
/*************************************************************************
*
* CheckPoint - Save checkpoint
*
*************************************************************************/
Int32 CheckPoint()
{
Int32 result;
chkpnt = reccnt;
rewind(fp);
result = fwrite(&chkpnt, sizeof(chkpnt), 1, fp);
if (result != 1) {
fprintf(stderr, "INMOD: ERROR WRITING TO CHECKPOINT FILE\n");
fprintf(stderr, "INMOD: %d ELEMENTS WERE WRITTEN\n", result);
perror("INMOD");
return(!EM_OK);
}
fprintf(stderr, "INMOD: CHECKPOINT AT ROW: %d\n", chkpnt);
return(EM_OK);
}
Teradata FastLoad Reference
177
Appendix C: INMOD and Notify Exit Routine Examples
UNIX OS
/*************************************************************************
*
* DBSRestart - DBS restarted
*
*
Retrieve the checkpoint information from the checkpoint file.
*
Reset record counter to checkpoint value
*
*************************************************************************/
Int32 DBSRestart()
{
Int32 result;
/* see if the file is already open */
if (!fp) {
fp = fopen(fname, "r+");
if (!fp)
return(!EM_OK);
}
rewind(fp);
result = fread(&chkpnt, sizeof(chkpnt), 1, fp);
if (result != 1) {
fprintf(stderr, "INMOD: ERROR READING CHECKPOINT FILE\n");
fprintf(stderr, "INMOD: %d ELEMENTS WERE READ\n", result);
perror("INMOD");
return(!EM_OK);
}
fprintf(stderr, "INMOD: DBS RESTARTED. CHECKPOINT: %d\n", chkpnt);
reccnt = chkpnt;
return(EM_OK);
}
/*************************************************************************
*
* CleanUp - Do cleanup.
*
*
Here we close the file and then remove it.
*
*************************************************************************/
Int32 CleanUp()
{
fclose(fp);
remove(fname);
return(EM_OK);
}
/*************************************************************************
*
* InvalidCode - Invalid INMOD code returned.
*
*************************************************************************/
Int32 InvalidCode()
{
fprintf(stderr, "**** Invalid code received by INMOD\n");
178
Teradata FastLoad Reference
Appendix C: INMOD and Notify Exit Routine Examples
UNIX OS
return(EM_OK);
}
/*************************************************************************
*
* Init - initialize some stuff
*
*
Do any initialization necessary
*
*
For this example, we will open a disk file to hold
*
the checkpoint information. For this example, we
*
will just store the row number. If this INMOD was
*
reading data from a file, then the file position
*
would need to be stored.
*
*************************************************************************/
Int32 Init()
{
fp = fopen(fname, "w");
if (!fp)
return(!EM_OK);
return(EM_OK);
}
/*************************************************************************
*
* BLKEXIT - Start processing
*
*
This is the main module which contains the checks for
*
number of records generated and buffer filling. This
*
module also sends the filled buffer to the DBS.
*
*************************************************************************/
#if defined WIN32
__declspec(dllexport) Int32 BLKEXIT(tblptr)
#elif defined I370
Int32 _dynamn(tblptr)
#else
Int32 BLKEXIT(tblptr)
#endif
char *tblptr;
{
Int32 result;
inmodptr = (struct inmod_struct *)tblptr;
/* process the function passed to the INMOD */
switch (inmodptr->ReturnCode) {
case 0: result = Init();
if (result)
break;
result = MakeRecord();
break;
case 1: result = MakeRecord();
break;
case 2: result = HostRestart();
break;
Teradata FastLoad Reference
179
Appendix C: INMOD and Notify Exit Routine Examples
All Platforms
case 3:
result
break;
case 4: result
break;
case 5: result
break;
default: result
= CheckPoint();
= DBSRestart();
= CleanUp();
= InvalidCode();
}
/* see if we have reached EOF condition */
if (result == FILEOF) {
inmodptr->Length = 0;
result = EM_OK;
}
return(result);
}
All Platforms
Notify Exit Routine Example
The user exit routine in the following example processes events specified by the NOTIFY
command.
/***************************************************************************
*
* TITLE: flnfyext.c .... an example notify exit...
*
* Copyright(C) 1996-2005, 2010 by 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.
*
*
* Description This file is a sample user exit routine for
*
processing NOTIFY events
*
* History Information
*
* Revision
Date
DCR
DID
Comments
* ----------- -------- ----- -------- -------------------------------------* 13.00.00.01 09072007 114414 NT185003 Teradata Corporation Copyright
* 13.00.00.00 09012007 100894 SV185048 Visual Studio 8.0 build
* 07.07.00.01 09292005 96206 CSG
Port to HPUX-IA64 platform
* 07.06.00.02 06182004 68859 XX151000 Back out branding changes
* 07.06.00.01 01142004 68859 XX151000 Change DBS to Teradata Database
* 07.01.00.01 07/10/98 42517 SF3
Redesign User Exit Interface
* 06.01.00.01 04/04/97 34579 SF3
Initial Version
*
*
180
Teradata FastLoad Reference
Appendix C: INMOD and Notify Exit Routine Examples
All Platforms
* Notes
The entry point to this User Exit must
*
be called "_dynamn"
*
***************************************************************************/
#include <stdio.h>
/* --> */
typedef int Int32;
typedef unsigned int UInt32;
/* <-- */
typedef enum { NFEventInitialize
NFEventFileInmodOpen
NFEventPhaseIBegin
NFEventCheckPoint
NFEventPhaseIEnd
NFEventPhaseIIBegin
NFEventPhaseIIEnd
NFEventDropErrTableI
NFEventDropErrTableII
NFEventDBSRestart
NFEventCLIError
NFEventDBSError
NFEventExit
} NfyFLDEvent;
#define
#define
#define
#define
#define
ID_FASTLOAD
ID_MULTILOAD
ID_FASTEXPORT
ID_BTEQ
ID_TPUMP
#define
#define
#define
#define
#define
#define
MAXVERSIONIDLEN
MAXUTILITYNAMELEN
MAXUSERNAMELEN
MAXUSERSTRLEN
MAXTABLENAMELEN
MAXFILENAMELEN
= 0 ,
= 1 ,
= 2 ,
= 3 ,
= 4 ,
= 5 ,
= 6 ,
= 7 ,
= 8 ,
= 9 ,
= 10 ,
= 11 ,
= 12
1
2
3
4
5
32
32
64
80
128
256
typedef struct _FLNotifyExitParm {
Int32 Event;
union {
struct {
UInt32 VersionLen;
char
VersionId[MAXVERSIONIDLEN];
UInt32 UtilityId;
UInt32 UtilityNameLen;
char
UtilityName[MAXUTILITYNAMELEN];
UInt32 UserNameLen;
char
UserName[MAXUSERNAMELEN];
UInt32 UserStringLen;
char
UserString[MAXUSERSTRLEN];
} Initialize;
struct {
UInt32 FileNameLen;
char
FileOrInmodName[MAXFILENAMELEN];
} FileInmodOpen ;
struct {
UInt32 TableNameLen;
Teradata FastLoad Reference
181
Appendix C: INMOD and Notify Exit Routine Examples
All Platforms
char
TableName[MAXTABLENAMELEN];
UInt32 dummy;
} PhaseIBegin ;
struct {
UInt32 RecordCount;
} CheckPoint;
struct {
UInt32 RecsRead;
UInt32 RecsSkipped;
UInt32 RecsRejected;
UInt32 RecsSent;
} PhaseIEnd ;
struct {
UInt32 dummy;
} PhaseIIBegin;
struct {
UInt32 Inserts;
UInt32 dummy1;
UInt32 dummy2;
UInt32 dummy3;
} PhaseIIEnd;
struct {
UInt32 Rows;
UInt32 dummy;
} DropErrTableI;
struct {
UInt32 Rows;
UInt32 dummy;
} DropErrTableII ;
struct {
UInt32 dummy;
} DBSRestart;
struct {
UInt32 ErrorCode;
} CLIError;
struct {
UInt32 ErrorCode;
} DBSError;
struct {
UInt32 ReturnCode;
} Exit;
} Vals;
} FLNotifyExitParm;
/*************************************************************************
*
*
CODE STARTS HERE
*
*************************************************************************/
#ifdef WIN32
__declspec(dllexport) Int32 _dynamn(FLNotifyExitParm *P)
#else
Int32 _dynamn(FLNotifyExitParm *P)
#endif
{
static FILE *fp;
if (!fp) {
#ifdef I370
182
Teradata FastLoad Reference
Appendix C: INMOD and Notify Exit Routine Examples
All Platforms
if (!(fp = fopen("NFYEXIT", "w")))
return(1);
#else
if (!(fp = fopen("NFYEXIT.OUT", "w")))
return(1);
#endif
}
switch(P->Event) {
case NFEventInitialize :
fprintf(fp,
"exit called @ FastLoad Notify initialization.\n");
fprintf(fp,
"
Version Id:
%s.\n",
P->Vals.Initialize.VersionId);
fprintf(fp,
"
Utility Id:
%d.\n",
P->Vals.Initialize.UtilityId);
fprintf(fp,
"
Utility Name: %s.\n",
P->Vals.Initialize.UtilityName);
fprintf(fp,
"
User Name:
%s.\n",
P->Vals.Initialize.UserName);
break;
case NFEventFileInmodOpen :
fprintf(fp,
"exit called @ FastLoad file/inmod open: %s.\n",
P->Vals.FileInmodOpen.FileOrInmodName);
break;
case NFEventPhaseIBegin :
fprintf(fp,
"exit called @ FastLoad phase I (start) for table %s.\n",
P->Vals.PhaseIBegin.TableName);
break;
case NFEventCheckPoint :
fprintf(fp,
"exit called @ FastLoad checkpoint : %d records loaded.\n",
P->Vals.CheckPoint.RecordCount);
break;
case NFEventPhaseIEnd :
fprintf(fp,
"exit called @ FastLoad phase I (end).\n");
fprintf(fp,
"
Records read:
%d\n",
P->Vals.PhaseIEnd.RecsRead);
fprintf(fp,
"
Records skipped: %d\n",
P->Vals.PhaseIEnd.RecsSkipped);
fprintf(fp,
"
Records rejected: %d\n",
P->Vals.PhaseIEnd.RecsRejected);
fprintf(fp,
"
Records sent:
%d\n",
P->Vals.PhaseIEnd.RecsSent);
Teradata FastLoad Reference
183
Appendix C: INMOD and Notify Exit Routine Examples
All Platforms
break;
case NFEventPhaseIIBegin :
fprintf(fp,
"exit called @ FastLoad phase II (start).\n");
break;
case NFEventPhaseIIEnd :
fprintf(fp,
"exit called @ FastLoad phase II (end): %d records loaded.\n",
P->Vals.PhaseIIEnd.Inserts);
break;
case NFEventDropErrTableI :
fprintf(fp,
"exit called @ FastLoad ET 1 Drop : %d records in table.\n",
P->Vals.DropErrTableI.Rows);
break;
case NFEventDropErrTableII :
fprintf(fp,
"exit called @ FastLoad ET 2 Drop : %d records in table.\n",
P->Vals.DropErrTableII.Rows);
break;
case NFEventDBSRestart :
fprintf(fp,
"exit called @ FastLoad detects DBS restart.\n");
break;
case NFEventCLIError :
fprintf(fp,
"exit called @ FastLoad detects CLI error: %d.\n",
P->Vals.CLIError.ErrorCode);
break;
case NFEventDBSError :
fprintf(fp,
"exit called @ FastLoad detects DBS error: %d.\n",
P->Vals.DBSError.ErrorCode);
break;
case NFEventExit :
fprintf(fp,
"exit called @ FastLoad exiting. Return code: %d.\n",
P->Vals.Exit.ReturnCode);
fclose(fp);
break;
}
return(0);
}
/******************************************************************************
*
* End of FlNfyExt.c
*
******************************************************************************/
184
Teradata FastLoad Reference
APPENDIX D
Compile, Link, and Execute INMOD
and Notify Exit Routines
This appendix provides examples of compiling, linking, and executing INMOD and notify
exit routines written in the supported programming languages for the following client system
platforms.
•
z/OS
•
IBM C or C++ INMODs
•
UNIX OS
•
Windows
Listings are provided of sample INMOD routines and notify exit routines written in:
•
C or C++
•
IBM C
Channel-attached z/OS client systems support INMOD and notify exit routines written in any
of the languages listed. Network-attached UNIX and Windows client systems support
routines written in C.
z/OS
IBM C
INMOD and notify exit routines written in IBM C must:
•
Contain the entry point name _dynamn
•
Be stored as an z/OS load library file
To create and use an IBM C INMOD or notify exit routine on z/OS
1
Prepare the INMOD routine source file.
2
Compile the INMOD routine.
3
Link-edit the INMOD program and store the results as an z/OS load library file.
4
Invoke the Teradata FastLoad utility to execute the INMOD routine.
Teradata FastLoad Reference
185
Appendix D: Compile, Link, and Execute INMOD and Notify Exit Routines
z/OS
Example
The INMOD routine in the following example reads the data from the input source and
presents it, as read, to the Teradata FastLoad utility. BTEQ1 creates a table on the Teradata
Database and BTEQ2 selects rows from the table to check for properly loaded data.
This basic program can be modified to select records that meet a specified criteria, convert
certain fields, or perform other preprocessing functions.
//*
Compile and link-edit the INMOD
//******************************************************************
//IBMCOMPL EXEC LC370CL,ENTRY=DYNNR,PARM.C='DYNAMNDEF,OPTIMIZE'
//C.SYSLIB DD
//
DD DISP=SHR,DSN=<Your macro library>
//C.SYSIN
DD
*
//******************************************************************
//* Link-edit the INMOD
*
//******************************************************************
//LKED.SYSLMOD DD DISP=SHR,DSN=<Your load library>
//LKED.SYSIN DD *
NAME MYINMOD(R)
//****************************************************************
//*
Execute BTEQ to create a Teradata DBS table
*
//*
*
//* The BTEQ statement .run ddname=logon allows the user to
*
//* place sensitive logon information in a secure data set (in
*
//* this case, the ddname is logon). Logging on from a data
*
//* set prevents this sensitive information from appearing in
*
//*the SYSIN file.
*
//****************************************************************
//BTEQ1 EXEC TDSBTEQ
//LOGON DD DSN=JLH.CNTL(JLHLOGON),DISP=SHR
//SYSIN DD DATA,DLM=##
.run ddname=logon
drop table stuff;
drop table stuff_error1;
drop table stuff_error2;
create table stuff (t1 char(40), t2 char(40))
primary index(t1);
.quit
##
//*
//*
//FAST EXEC TDSFAST
//FASTLOAD.STEPLIB DD
//
DD
//
DD DISP=SHR,DSN=<your load library>
//FASTLOAD.SYSIN
DD DATA,DLM=$$
LOGON <Logon userid and password>
BEGIN LOADING stuff ERRORFILES stuff_error1,stuff_error2;
DEFINE t1 (char(40)),
t2 (char(40))
INMOD=MYINMOD;
INSERT INTO stuff (:t1,:t2);
186
Teradata FastLoad Reference
Appendix D: Compile, Link, and Execute INMOD and Notify Exit Routines
IBM C or C++ INMODs
END LOADING;
logoff;
$$
//FASTLOAD.EXPORT DD DSN=JLH.STUFF.DATA,DISP=SHR
//*
//****************************************************************
//*
Using BTEQ, select the rows loaded by FastLoad
*
//****************************************************************
//BTEQ2
EXEC TDSBTEQ
//LOGON
DD DSN=JLH.CNTL(JLHLOGON),DISP=SHR
//SYSIN DD DATA,DLM=##
.run ddname=logon
select * from stuff order by 1;
.quit
IBM C or C++ INMODs
Inmods can be written using the various flavors of IBM C or C++ (for example, C/370, AD/
Cycle, OS/390 C/C++, and so on). Teradata FastLoad provides source code for an assembler
language stub that invokes the appropriate CEEPIPI calls to support pre-initialization,
repeatable invocation, and termination.
The procedure follows:
1
Modify the supplied sample source module called LIBINIT3 such that the name of the
load module representing the actual INMOD is specified as the first argument of the
CEEXPITY macro, as follows:
CEEXPITY CINMODCL,0
In the above example, the name of the load module representing the actual INMOD is
CINMODCL.
2
Assemble the supplied sample source module called LIBINIT3. Use the high-level
assembler (batch or interactive) with default attributes for this purpose.
3
Link-edit the object code derived from Step 2 into an executable load module. The name
of this load module must be different from the name of the load module representing the
actual INMOD. Use the linkage editor or binder (batch or interactive) with default
attributes for this purpose.
4
Within the utility script, substitute the name of the load module representing the interface
(LIBINIT3) where the name of the load module representing the actual INMOD would be
specified.
The flow of control is as follows:
utility --> interface --> inmod
For example:
FASTLOAD --> LIBINIT3 --> CINMODCL
Teradata FastLoad Reference
187
Appendix D: Compile, Link, and Execute INMOD and Notify Exit Routines
UNIX OS
UNIX OS
Sun Solaris SPARC
Use the following syntax to compile source files into a shared object module for INMOD or
notify exit routines on Sun Solaris SPARC:
cc -G
-KPIC
sourcefile
-o shared-object-name
2409A051
where
Syntax Element
Description
cc
Call to the program that invokes the native UNIX C compiler
-G
Linker option that generates a shared object file
-KPIC
Compiler option that generates Position Independent Code (PIC) for all user
exit routines
-o
Switch to the linker
shared-object-name
Name of the shared object file
This is the name specified as the:
• INMOD= name parameter in the DEFINE command of the Teradata
FastLoad job script
• EXIT name parameter of the NOTIFY command of the Teradata FastLoad
job script
The shared-object-name can be any valid UNIX file name.
Note: When creating a shared object module for an INMOD routine, if the
INMOD uses functions from an external library, then that library must be
statically linked with the INMOD routine so that the Teradata FastLoad
utility can resolve the external references.
sourcefile
UNIX file name(s) of the source file(s) for the INMOD or notify exit routine
Sun Solaris Opteron
Use the following syntax to compile source files into a shared object module for INMOD or
notify exit routines on Sun Solaris Opteron:
cc -dy
-G
sourcefile.c
-o shared-object-name
2409A055
where
188
Teradata FastLoad Reference
Appendix D: Compile, Link, and Execute INMOD and Notify Exit Routines
UNIX OS
Syntax Element
Description
cc
Call to the program that invokes the native UNIX 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 as:
• The INMOD modulename parameter of the DEFINE command of
the Teradata FastLoad job script
• The EXIT name parameter for the NOTIFY command of the
Teradata FastLoad job script
The shared-object-name can be any valid UNIX file name
HP-UX PA RISC
Use the following syntax to compile and link source files into a shared object module for
INMOD notify exit routines on HP-UX PA RISC client systems:
Compile Syntax
c
-Aa
+z
-D_HPUX_SOURCE
+u1
-c
sourcefile.c
3021B002
Link Syntax
ld
-b
objectfile.o
-o shared-object-name
2411A002
where
Syntax Element
Description
-Aa
Compiler option which enables compiler to conform to the ANSI standard
-b
Linker option that generates a shared object file
-c
Compile-only option (does not link)
Teradata FastLoad Reference
189
Appendix D: Compile, Link, and Execute INMOD and Notify Exit Routines
UNIX OS
Syntax Element
Description
cc
Call to the program that invokes the native UNIX C compiler
-D_HPUX_SOURCE
Symbol that enables the compiler to access macros and typedefs that are
not defined by the ANSI Standard but are provided by the HPUX
Operating System
ld
Call to the program that invokes the native UNIX linker
objectfile
File that the compiler generates and linker uses to generate shared-objectname
-o
Switch to the linker
shared-object-name
Name of the shared object file
This is the name specified as the:
• INMOD modulename parameter of the DEFINE command
• EXIT name parameter for the NOTIFY command of the Teradata
FastLoad job script
The shared-object-name can be any valid UNIX file name.
Note: When creating a shared object module for an INMOD routine, if the
INMOD uses functions from an external library, then that library must be
statically linked with the INMOD routine so that the Teradata FastLoad
utility can resolve the external references.name.
+z
Compiler option that generates Position Independent Code (PIC) for all
user exit routines
sourcefile
UNIX file name(s) of the source file(s) for the INMOD or notify exit
routine
+u1
Compiler option that allows pointers to access non-natively aligned data
HP-UX Itanium
Use the following syntax examples to compile and link a C INMOD on an HP-UX
Itanium-based client.
Compile Syntax
cc
+u1
-D_REENTRANT
+DD64
-c
inmod.c
2409A057
where
190
Syntax Element
Description
cc
Invokes the MetaWare High C compiler
Teradata FastLoad Reference
Appendix D: Compile, Link, and Execute INMOD and Notify Exit Routines
UNIX OS
Syntax Element
Description
+u1
Is a compiler option that allows pointers to access nonnatively 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
Link Syntax
ld
-n
-b
inmod.o
-lc
-o
inmod.so
2409A056
where
Syntax Element
Description
ld
Invokes the UNIX linker editor
-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 (for example, .so or .sl extension respectively)
on HP-UX Itanium.
Linux
Use the following syntax to compile and link source files into a shared object module for
INMOD, OUTMOD, or notify exit routines on Linux 32-bit client systems. On Linux 64-bit
client systems compile in 32-bit mode.
Note: Be sure to compile the INMOD and notify exit routines in 32-bit mode so they are
compatible with Teradata FastLoad.
Teradata FastLoad Reference
191
Appendix D: Compile, Link, and Execute INMOD and Notify Exit Routines
UNIX OS
Compile Syntax
gcc
-I/usr/include
-shared
-fPIC
-o shared-object-name
sourcefile.c
-m32
2409B023
where:
Syntax Element
Description
gcc
Call to the program that invokes the native C compiler
-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 (PIC) for
all user exit routines
-o
Output file name
inmod.c
An INMOD source file name
inmod.so
An INMOD shared object name
z/Linux
z/Linux
To compile and link source files into a shared object module for INMOD and notify exit
routines on z/Linux client systems, use the following syntax:
gcc
-I/usr/include
-m31
-shared
-fPIC
sourcefile.c
-o
shared-object-name
2409A059
where
192
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
-o
Output file name
sourcefile
UNIX file name(s) of the source file(s) for the INMOD or notify exit routine
Teradata FastLoad Reference
Appendix D: Compile, Link, and Execute INMOD and Notify Exit Routines
Windows
Syntax Element
Description
shared-object-name
Name of the shared object file
This is the name specified as:
• The INMOD modulename parameter of the DEFINE command of the
Teradata FastLoad job script.
• The EXIT name parameter for the NOTIFY command of the Teradata
FastLoad job script.
Windows
The Teradata FastLoad INMOD routine is implemented as a dynamic load library (.dll) in C.
A make file blkexit.mak is included to allow this DLL to be modified and rebuilt. Enter this
command:
nmake -f blkexit.mak
When the DLL, blkexit.dll, is rebuilt, put the DLL in the same directory as fastload.exe.
Teradata FastLoad Reference
193
Appendix D: Compile, Link, and Execute INMOD and Notify Exit Routines
Windows
194
Teradata FastLoad Reference
APPENDIX E
User-Defined-Types
and User-Defined-Methods
This appendix provides information on User-Defined-types (UDFs) and User-DefinedMethods (UDMs):
•
User-Defined-Types and User-Defined-Methods
•
User-Defined-Methods (UDMs)
•
Creating UDTs with FastLoad
•
Inserting and Retrieving UDTs with Client Products
•
External Types
•
Inserting UDTs with FastLoad
•
Retrieving UDTs with FastLoad
•
Retrieving UDT Metadata with FastLoad
User-Defined-Types and User-Defined-Methods
This section provides a brief overview of how Teradata Database client products support userdefined 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-mmyx, SQL External Routine Programming B035-1147-mmyx and SQL
Fundamentals, B035-1141-mmyx.
User-Defined-Types (UDTs)
UDTs can be created to provide representations of real world entities within the 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
the Teradata Database.
Teradata FastLoad Reference
195
Appendix E: User-Defined-Types and User-Defined-Methods
User-Defined-Types and User-Defined-Methods
User-Defined-Methods (UDMs)
Teradata Database developer-created custom functions, which are explicitly connected to
UDTs are known as User-Defined-Methods (UDMs). All UDMs must reside on server.
UDMs can be used to create an interface to the UDT that is independent of the UDT's internal
representation. This makes it possible to later enhance a given UDT even in cases where the
internal representation of the UDT must be changed to support the enhancement, without
changing all of the database applications which use the UDT.
Creating UDTs with FastLoad
Teradata FastLoad 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 predefined type. This pre-defined type is called the external type of a UDT. A client application
only deals with the external type; it does not deal with UDT value directly.
External Type Example
For example, if the following conditions exist:
•
UDT named FULLNAME exists
•
The external type associated with FULLNAME is VARCHAR(46)
Then, during an retrieve of FULLNAME values, the Teradata Database server converts the
values from FULLNAME values to VARCHAR(46) values by invoking the “from-sql routine”
associated with the FULLNAME UDT.
Note: The client must expect to receive the data in the same format as it receives
VARCHAR(46) values.
Similarly, when values are provided by the client for insert into a FULLNAME UDT, the client
must provide values in the same way it would provide values for a VARCHAR(46) field. The
Teradata Database server will convert the values from VARCHAR(46) to FULLNAME values
using the “to-sql routine” associated with the FULLNAME UDT.
196
Teradata FastLoad Reference
Appendix E: User-Defined-Types and User-Defined-Methods
User-Defined-Types and User-Defined-Methods
Inserting UDTs with FastLoad
Teradata FastLoad inserts values into tables containing UDT columns in the same manner as
is done for other tables, and handles the column data in its external type format.
•
Data in External Type Format - Data must be in the external type format in the input data
source identified in the DEFINE command in the Teradata FastLoad job script.
•
Name of the External Type - Specify the name of the external type for the data type of the
field in the DEFINE command.
Retrieving UDTs with FastLoad
UDTs cannot be retrieved with FastLoad
Retrieving UDT Metadata with FastLoad
UDT Metadata cannot be retrieved with FastLoad.
Teradata FastLoad Reference
197
Appendix E: User-Defined-Types and User-Defined-Methods
User-Defined-Types and User-Defined-Methods
198
Teradata FastLoad Reference
Glossary
A
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.
access lock: A lock that allows selection of data from a table that may be locked for write
access. The Teradata MultiLoad utility maintains access locks against the target tables during
the Acquisition Phase.
access module: A software component that provides a standard set of I/O functions to
access data on a specific device.
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.
acquisition phase: Responsible for populating the primary data subtables of the work
tables. Data are received from the host, converted into internal format, and inserted into the
work tables. The work tables will be 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.
allocation group: (AG) A set of parameters that determine the amount of resources
available to the sessions assigned to a PG referencing a specific AG. Has an assigned weight
that is compared to other AG weights. An AG can limit the total amount of Central Processing
Unit (CPU) used by sessions under its control.
ANSI: American National Standards Institute. ANSI maintains a standard for SQL. For
information about Teradata compliance with ANSI SQL, see the SQL Fundamentals.
AP:
Application Processor
Application Phase: Responsible for turning rows from a work table into updates, deletes,
and inserts and applying them to a single target table.
API: Application Program Interface. An interface (calling conventions) by which an
application program accesses an operating system and other services. An API is defined at
source code level and provides a level of abstraction between the application and the kernel
(or other privileged utilities) to ensure the portability of the code.
An API can also provide an interface between a high level language and lower level utilities
and services written without consideration for the calling conventions supported by compiled
Teradata FastLoad Reference
199
Glossary
languages. In this case, the API may translate the parameter lists from one format to another
and the interpret call-by-value and call-by-reference arguments in one or both directions.
architecture: A definition and preliminary design which describes the components of a
solution and their interactions. An architecture is the blueprint by which implementers
construct a solution which meets the users’ needs.
ASCII: American Standard Code for Information Interchange, a character set used
primarily on personal computers.
B
BTEQ: Basic Teradata Query facility. A utility that allows users on a workstation to access
data on a Teradata Database, and format reports for both print and screen output.
C
capture:
The process of capturing a production data source.
change data capture: The process of capturing changes made to a production data source.
Change data capture is typically performed by reading the source DBMS log. It consolidates
units of work, ensures data is synchronized with the original source, and reduces data volume
in a data warehousing environment.
channel-attached: A mainframe computer that communicates with a server (for example, a
Teradata Database) through a channel driver.
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).
Client:
A computer that can access the Teradata Database.
CLOB: An acronym for character large object. A CLOB is a pure character-based large
object in a database. It can be a large text file. HTML, RTF or other character-based file.
CLOBs can be up 2 GB in size. Also see BLOB and LOB.
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.
COP: Communications Processor. One kind of interface processor (IFP) on the Teradata
Database. A COP contains a gateway process for communicating with workstations via a
network.
COP Interface: Workstation-resident software and hardware, and Teradata Databaseresident software and hardware, that allows workstations and the Teradata Database to
communicate over networks.
200
Teradata FastLoad Reference
Glossary
D
database: A related set of tables that share a common space allocation and owner. A
collection of objects that provide a logical grouping for information. The objects include,
tables, views, macros, triggers, and stored procedures.
Data Dictionary: In the Teradata Database, the information automatically maintained
about all tables, views, macros, databases, and users known to the Teradata Database system,
including information about ownership, space allocation, accounting, and privilege
relationships between those objects. Data Dictionary information is updated automatically
during the processing of Teradata SQL data definition statements, and is used by the parser to
obtain information needed to process all Teradata SQL statements.
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 Model: A logical map that represents the inherent properties of the data independent
of software, hardware, or machine performance considerations. The model shows data
elements grouped into records, as well as the association around those records.
data streams: Buffers in memory for temporarily holding data. A data stream is not a
physical file; instead, it is more like a pipe (in UNIX or Windows systems), or a batch pipe in
MVS.
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:
DD:
Database Administrator
Data dictionary or data definition.
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.
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.
domain name: A group of computers whose host names (the unique name by which a
computer is known on a network) share a common suffix, that is the domain name.
Teradata FastLoad Reference
201
Glossary
DSN: Digital Switched Network. The completely digital version of the PSTN.
Duplicate Row Check: A logic within the Teradata Database used to check for duplicate
rows while processing each primary data row for INSERTs and UPDATEs.
DWM: Dynamic Workload Manager. The product described in this document, which
manages access to the Teradata Database.
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 the Preliminary Phase used to store errors detected
while processing a MultiLoad job. There are two error tables, ET and UV, that contains errors
found during the Acquisition Phase and Application Phase, respectively.
EOF:
End of File
execution time frame:
are waiting to run.
A period of time when DWM can execute scheduled requests that
Exit Routines: Specifies a predefined action to be performed whenever certain significant
events occur during a MultiLoad job.
F
FastExport: Teradata FastExport utility. A program that quickly transfers large amounts of
data from tables and views of the Teradata Database to a client-based application.
FastLoad: Teradata FastLoad utility. A program that loads empty tables on the Teradata
Database with data from a network-attached or channel-attached client.
field: The basic unit of information stored in the Teradata Database. A field is either null, or
has a single numeric or string value. See also column, database, row, table.
foreign key: The primary key of a parent data subject that is placed in a subordinate data
subject. Its value identifies the data occurrence in the parent data subject that is the parent of
the data occurrence in the subordinate data subject.
formatted records:
See Records.
function: User Defined Functions (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.
G
gateway:
202
A device that connects networks having different protocols.
Teradata FastLoad Reference
Glossary
global rule: Object Access and Query Resource rules can be specified as being global, that is,
they apply to all objects, and therefore to all requests. When a rule is specified as being global,
no query objects need be (or can be) associated with the rule because all objects are implicitly
included. Care should be taken defining a global access rule, as it causes all requests to be
rejected except those from the DBC user and any bypassed objects.
globally distributed objects (GDO): A data structure that is shared by all of the virtual
processors in the Teradata Database system configuration.
I
import: This refers to 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.
Import Task: A task that quickly applies large amounts of client data to one or more tables
or views on the Teradata Database. Composed of four major phases: Preliminary, Acquisition,
Application, and End. The phases are a collection of one or more transactions that are
processed in a predefined order according to the MLOAD protocol. An import task references
up to five target tables.
INMOD: Input Module, a program that administrators can develop to select, validate, and
preprocess input data.
INMOD Routine: User-written routines that Teradata MultiLoad and other load/export
utilities use to provide enhanced processing functions on input records before they are sent to
the Teradata Database. Routines can be written in C language (for network-attached
platforms), or SAS/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.
inner join: In Teradata SQL, a join operation on two or more tables, according to a join
condition, that returns the qualifying rows from each table.
instance: In object-oriented programming, refers to the relationship between an object and
its class. The object is an instance of the class. In Teradata PT, an instance is an occurrence of
a fully defined Teradata PT operator, with its source and target data flows, number of sessions,
and so on. Teradata PT can process multiple instances of operators.
interface processor (IFP): Used to manage the dialog between the Teradata Database and
the host. Its components consist of session control, client interface, the parser, the dispatcher,
and the BYNET. One type of IFP is a communications processor (COP). A COP contains a
gateway process for communicating with workstations via a network.
Intermediary: A computer software process written by a third party which interfaces to one
or more Teradata servers and initiates a change data capture or change data apply operation
with replication services.
internet protocol (IP): Data transmission standard; the standard that controls the routing
and structure of data transmitted over the Internet.
Teradata FastLoad Reference
203
Glossary
I/O:
Input/output.
ISO:
International Standards Organization
J
JCL: Job Control Language is 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 their time and space resources
among the total number of jobs that have been started in the computer. Jobs in turn break
down into job steps. All the statements required to run a particular program constitute a job
step. 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.
JIS: Japanese Industrial Standards specify the standards used for industrial activities in
Japan. The standardization process is coordinated by Japanese Industrial Standards
Committee and published through Japanese Standards Association.
Job Script: A job script, or program, is a set of Teradata MultiLoad commands and Teradata
SQL statements that make changes to specified target tables and views in the Teradata
Database. These changes can include inserting new rows, updating the contents of existing
rows, and deleting existing rows.
join: A select operation that combines information from two or more tables to produce a
result.
L
LAN: Local Area Network. LANs supported by Teradata products must conform to the
IEEE 802.3 standard (Ethernet LAN).
Least Used: Least used (-lu) in a command line parameter that tells Teradata QD to route
queries to the least used database.
Load operator: A Teradata PT consumer-type operator that emulates some of the functions
of the Teradata FastLoad utility in the Teradata PT infrastructure.
LOB: An acronym for large object. A large object is a database object that is large in size.
LOBs can be up to 2 gigabytes. There are two types of LOBs, CLOBs and BLOBs. CLOBs are
character-based objects, BLOBs are binary-based objects.
Locks: Teradata FastLoad automatically locks any table being loaded and frees a lock only
after an END LOADING statement is entered. Therefore, access to a table is available when
Teradata FastLoad completes.
log: A record of events. A file that records events. Many programs produce log files. Often a
log file determines what is happening when problems occur. Log files have the extension
“.log”.
204
Teradata FastLoad Reference
Glossary
logical action: A named action that is defined on the Alert Policy Editor's Actions tab.
Logical actions can be assigned to events in the alert policy.
Logical Data Model: A data model that represents the normalized design of data needed to
support an information system. Data are drawn from the common data model and
normalized to support the design of a specific information system.
Actual implementation of a conceptual module in a database. It may take multiple logical data
models to implement one conceptual data model.
loner value: A value that has a frequency greater than the total number of table rows
divided by the maximum interval times 2.
M
macro: a file that is created and stored on the Teradata Database, and is executed in
response to a Teradata SQL EXECUTE statement
merge join: In Teradata SQL, the type of join that occurs when the WHERE conditional of a
SELECT statement causes the system first to sort the rows of two tables based on a join field
(specified in the statement), then traverse the result while performing a merge/match process.
Metadata: Data about data. For example, information about where the data is stored, who is
responsible for maintaining the data, and how often the data is refreshed.
methods: In object-oriented programming, methods are the programming routines by
which objects are manipulated.
NFS:
Network file system.
MIB:
Management Information Base
MOSI: Micro Operating System Interface. A library of routines that implement operating
system dependent and protocol dependent operations on the workstation.
MTDP: Micro Teradata Director Program. A library of routines that implement the session
layer on the workstation. MTDP is the interface between CLI and the Teradata Database.
MultiLoad: Teradata MultiLoad. A command-driven utility that performs fast, highvolume maintenance functions on multiple tables and views of the Teradata Database.
Multiset Tables: Tables that allow duplicate rows.
MVS (Multiple Virtual Storage): One of the primary operating systems for large IBM
computers.
N
name: A word supplied by the user that refers to an object, such as a column, database,
macro, table, user, or view.
Teradata FastLoad Reference
205
Glossary
nested join: In Teradata SQL, this join occurs when a field is a unique primary index for
one table of the join and an index (unique or non-unique primary or secondary index) for the
second table in the join.
Network:
In the context of the Teradata Database, a LAN (see LAN).
network attached: A computer that communicates over the LAN with a server (for
example, a Teradata Database).
notify exit: A user-defined exit routine that specifies a predefined action to be performed
whenever certain significant events occur during a Teradata FastLoad job.
For example, by writing an exit in C (without using CLIv2) and using the NotifyExit attribute
in an operator definition, a routine to detect whether a Teradata FastLoad job succeeds or
fails, how many records were loaded, what the return code is for a failed job, and so on can be
provided.
null:
The absence of a value for a field.
Nullif Option: This option allows the user to null a column in a table under certain
conditions; it is only used in conjunction with DEFINE statements.
NUSI: Non-unique secondary index; an NUSI is efficient for range query access, while a
unique secondary index (USI) is efficient for accessing a single value.
O
object: In object-oriented programming, a unique instance of a data structure defined
according to the template provided by its class. Each object has its own values for the variables
belonging to its class and can respond to the messages, or methods, defined by its class.
object access rule: An Object Access filter allows defining the criteria for limiting access to
issuing objects and/or query objects. Queries that reference objects associated with the rule
(either individually or in combination) during the specified dates and times are rejected.
Global rules are not applicable for this type.
object definition: The details of the structure and instances of the objects used by a given
query. Object definitions are used to create the tables, views, and macros, triggers, join
indexes, and stored procedures in a database.
operator routine:
method.
In object-oriented programming, refers to a function that implements a
The terms operator routine and operator function may be used interchangeably.
OS/390
Operating System 390
outer join: In Teradata SQL, an extension of an inner join operation. In addition to
returning qualifying rows from tables joined according to a join condition (the inner join), an
outer join returns non-matching rows from one or both of its tables. Multiple tables are
joined two at a time.
206
Teradata FastLoad Reference
Glossary
owner: In Teradata SQL, the user who has the ability to grant or revoke all privileges on a
database to and from other users. By default, the creator of the database is the owner, but
ownership can be transferred from one user to another by the GIVE statement.
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.
parsing engine (PE): An instance (virtual processor) of the database management session
control, parsing, and dispatching processes and their data context (caches).
Paused MultiLoad Job: A job that was halted, before completing, during the Acquisition
Phase of the Teradata MultiLoad operation. The paused condition can be intentional, or the
result of a system failure or error condition.
peak perm:
Highest amount of permanent disk space, in bytes, used by a table.
performance groups: A performance group is a collection of parameters used to control
and prioritize resource allocation for a particular set of Teradata Database sessions within the
Priority Scheduler. Every Teradata Database session is assigned to a performance group
during the logon process. Performance groups are the primary consideration in partitioning
the working capacity of the Teradata Database. To learn more about performance groups, see
the Priority Scheduler section of Utilities.
performance periods: A threshold or limit value that determines when a session is under
the control of that performance period. A performance period links PGs/Teradata Database
sessions under its control to an AG that defines a scheduling strategy. A performance period
allows AG assignments based on time-of-day or resource usage to be changed.
Physical Data Model: A data model that represents the denormalized physical
implementation of data that support an information system. The logical data model is
denormalized to a physical data model according to specific criteria that do not compromise
the logical data model but allow the database to operate efficiently in a specific operating
environment.
Primary server: A Teradata server in which client applications execute transactions through
use of Teradata SQL or utilities such as Teradata MultiLoad and update the tables of one or
more replication groups. The changes are captured by replication services and given to an
intermediary connected to the server.
priority definition set: A collection of data that includes the resource partition,
performance group, allocation group, performance period type, and other definitions that
control how the Priority Scheduler manages and schedules session execution.
product join: In Teradata SQL, the type of join that occurs when the WHERE conditional
of a SELECT statement causes the Teradata Database system to compare all qualifying rows
Teradata FastLoad Reference
207
Glossary
from one table to all qualifying rows from another table. Because each row of one table is
compared to each row of another table, this join can be costly in terms of system performance.
Note that product joins without an overall WHERE constraint are considered unconstrained
(Cartesian). If the tables to be joined are small, the effect of an unconstrained join on
performance may be negligible, but if they are large, there may be a severe negative effect on
system performance.
profiles: A profile is a set of parameters assigned to a user, group of users, or an account that
determines which scheduling capabilities are available and how the Teradata Query Scheduler
scheduled requests server handles their scheduled requests.
physical action: A basic action type, such as <Send a Page>, <Send an E-Mail>, etc.
Physical actions must be encapsulated by logical actions in order to be used in the alert policy.
PIC:
Position independent code
PL/I: Programming Language/1, a programming language supported for MultiLoad
development.
PP2:
Preprocessor2
PPP:
Point-to-Point Protocol
Primary Key: A set of one or more data characteristics whose value uniquely identifies each
data occurrence in a data subject. A primary key is also known as a unique identifier.
privilege: A user’s right to perform the Teradata SQL statements granted to him against a
table, database, user, macro, or view.
procedure: Short name for Teradata stored procedure. Teradata provides Stored Procedural
Language (SPL) to create stored procedures. A stored procedure contains SQL to access data
from within Teradata and SPL to control the execution of the SQL.
production system: A database used in a live environment. A system that is actively used for
day to day business operations. This differs from a test or development system that is used to
create new queries or test new features before using them on the production system.
Protocol:
network.
The rules for the format, sequence and relative timing of messages exchanged on a
Q
query analysis: A feature that estimates the answer set size (number of rows) and processing
time of a SELECT type query.
query:
A Teradata SQL statement, particularly a SELECT statement.
Query Director: A Teradata client application used to balance sessions between systems
according to user provided algorithms.
query management: The primary function of DWM is to manage logons and queries. This
feature examines logon and query requests before they are dispatched for execution within the
208
Teradata FastLoad Reference
Glossary
Teradata Database, and may reject logons, and may reject or delay queries. It does this by
comparing the objects referenced in the requests to the types of DBA-defined rules.
R
Records: When using the Teradata MultiLoad utility, 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 Database utility, such as Basic Teradata Query (BTEQ),
where the record is packaged with begin- and end-record bytes specific to the Teradata
Database. Unformatted records are any records not originating on a Teradata Database, such
as Fortran files. These files contain records that must be defined before loading onto the
Teradata Database.
Replication Group: A set of tables for which either data changes are being captured on a
primary server or applied on a subscriber server.
Replication Services: A set of software functions implemented in the Teradata server that
interact with an intermediary to capture or apply change data to the tables of a replication
group.
request: In host software, a message sent from an application program to the Teradata
Database.
resource partition: A collection of prioritized PGs related by their users’ associations. Has
an assigned weight that determines the proportion of resources available to that partition
relative to the other partitions defined for that Teradata Database.
Restart Log Table: One of four restart tables the Teradata MultiLoad utility creates that are
required for restarting a paused Teradata MultiLoad job.
result: The information returned to the user to satisfy a request made of the Teradata
Database.
results table/file: In the Schedule Request environment, a results table or file is a database
table or a Windows file into which result data for a schedule request that is not self-contained
are stored.
results file storage: A symbolic name to a root directory where scheduled requests results
are stored. A file storage location can be mapped to a Windows root directory where results
are stored.
row: Whether null or not, that represent one entry under each column in a table. The row is
the smallest unit of information operated on by data manipulation statements.
RowID join: In Teradata SQL, this join occurs when one of the join tables has a non-unique
primary index constant, and another column of that table matches weakly with a non-unique
secondary index column of the second table.
RT:
Response Time
RTF:
Rich Text File
Teradata FastLoad Reference
209
Glossary
rule: Rules are the name given to the method used by DWM to define what requests are
prohibited from being immediately executed on the Teradata Database. That is, the rules
enforced by DWM provide the Query Management capabilities.
run file: A script that is not contained within the SYSIN file, but rather executed through
use of the .RUN BTEQ command.
S
scheduled requests: The capability to store scripts of SQL requests and execute them at a
scheduled later time.
schema: Schemas are used to identify the structure of the 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 will be read from the data stream. If the input and output
schemas are the same, only define the schema once.
script:
A file that contains a set of BTEQ commands and/or SQL statements.
Security token: A binary string generated by a server when a replication group is created or
altered that must be input to secure a change data capture or apply operation.
separator: A character or group of characters that separates words and special symbols in
Teradata SQL. Blanks and comments are the most common separators.
server: A computer system running the 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 the Teradata Database and ends when the
user logs off the Teradata Database. Also called a Teradata Database session.
session: In client software, a logical connection between an application program on a host
and the Teradata Database that permits the application program to send one request to and
receive one response from the Teradata Database at a time.
skew: This value is calculated based on a single Database collection interval. If the Session
Collection rate is 60, then the skew is calculated for a 60-second period.
The value is calculated using 'current' data values. For example, the Max CPU used during the
past 60 seconds relative to the Average used over that same 60 seconds:
skew = 100 * (1 - avg / max)
Source Database: The database from which data will be extracted or copied into the Data
Warehouse.
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.
Programming language used to communicate with the Teradata Database.
210
Teradata FastLoad Reference
Glossary
SSO: Single sign-on, an authentication option that allows users of the Teradata Database on
Windows 2000 systems to access the Teradata Database based on their 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 via client
applications.
statement: A request for processing by the Teradata Database that consists of a keyword
verb, optional phrases, operands and is processed as a single entity.
statistics: These are the details of the processes used to collect, analyze, and transform the
database objects used by a given query.
stored procedure: Teradata Version 2 Release 4 and later supports stored procedures. A
stored procedure is a combination of SQL statements and control and conditional handling
statements that run using a single call statement.
Subscriber server: A Teradata server in which changes captured from a primary server by
an intermediary are applied to tables that duplicate those of the primary. Replication services
executing on the servers provide the capture and apply functions.
supervisory user: In Data Dictionary, a user who has been delegated authority by the
administrator to further allocate Teradata Database resources such as space and the ability to
create, drop, and modify users within the overall user community.
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 in which data will be loaded or inserted.
Target table: A user table where changes are to be made by a Teradata MultiLoad task.
TCP/IP:
Transmission Control Protocol/Internet Protocol.
Teradata SQL: The Teradata Database dialect of the relational language SQL, having data
definition and data manipulation statements. A data definition statement would be a
CREATE TABLE statement and a data manipulation statement would be a data retrieval
statement (a SELECT statement).
TDP: Teradata Director Program; TDP provides a high-performance interface for messages
communicated between the client and the Teradata system.
TDPID: Teradata Director Program Identifier. The name of the Teradata Database being
monitored.
Target Level Emulation (TLE): Permits emulation of a target environment (target system)
by capturing system-level information from that environment. The captured information is
stored in the relational tables SystemFE.Opt_Cost_Table and SystemFE.Opt_RAS_Table. The
information in these tables can be used on a test system with the appropriate column and
Teradata FastLoad Reference
211
Glossary
indexes to make the Optimizer generate query plans as if it were operating in the target system
rather than the test system.
test system: A Teradata Database where Optimizer-specific information is imported to
emulate a target system and create new queries or test new features.
title: In Teradata SQL, a string used as a column heading in a report. By default, it is the
column name, but a title can also be explicitly declared by a TITLE phrase.
TPA:
Trusted Parallel Application.
Transport: The process of extracting data from a source, interfacing with a destination
environment, and then loading data to the destination.
transaction: A set of Teradata SQL statements that is performed as a unit. Either all of the
statements are executed normally or else any changes made during the transaction are backed
out and the remainder of the statements in the transaction are not executed. The 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.
TTU: Teradata Tools and Utilities is a robust suite of tools and utilities that enables users
and system administrators to enjoy optimal response time and system manageability with
there Teradata system. Teradata FastLoad is included in Teradata Tools and Utilities.
tuple: In a database table (relation), a set of related values one for each attribute (column).
A tuple is stored as a row in a relational database management system. It is analogous to a
record in a non relational file.
type: An attribute of a column that specifies the representation of data values for fields in
that column. Teradata SQL data types include numerics and strings.
U
UDF
User Defined Functions
UDM User-Defined Methods. The database developer can create custom functions that are
explicitly connected to UDTs; these are known as UDMs. Functionalities directly applicable to
a UDT can be located within the UDMs associated with that UDT rather than being replicated
to all of the applications that use that UDT, resulting in increased maintainability.
UDT A custom data type, known as a user-defined type. By creating UDTs, a database
developer can augment the Teradata Database with data types having capabilities not offered
by Teradata predefined (built-in) data types. Use Teradata FastLoad to import values into
tables containing UDT columns in the same manner as is done for other tables. The input
records to Teradata FastLoad must have the column data for UDT columns in its external
type format.
Unicode: A fixed-width (16 bits) encoding of virtually all characters present in all languages
in the world.
212
Teradata FastLoad Reference
Glossary
unique secondary index (USI): One of two types of secondary indexes. A secondary index
may be specified at table creation or at any time during the life of the table. It may consist of
up to 16 columns. To get the benefit of the index, the query has to specify a value for all
columns in the secondary index. A USI has two purposes: It can speed up access to a row
which otherwise might require a full table scan without having to reply on the primary index,
and it can be used to enforce uniqueness of a column or set of columns.
user: In Teradata SQL, a database associated with a person who uses the 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 database associated with a person who uses the Teradata Database. The database
stores the person’s private information and accesses other Teradata Databases.
user groups: A group of users can be specified within DWM as either as a collection of
individual users, or as all user names which satisfy a character string pattern (such as SALE*).
The Teradata concept of roles is not used to define user groups, as it applies to privileges. User
groups can generally be employed wherever an issuing object can be specified, and any
condition applied to a group implicitly applies to all users within that group.
UTF-8: In simple terms, UTF-8 is an 8 bit encoding of 16-bit Unicode to achieve an
international character representation.
In more technical terms, in UTF-8, characters are encoded using sequences of 1 to 6 octets.
The only octet of a sequence of one has the higher-order bit set to 0, the remaining 7 bits are
used to encode the character value. UTF-8 uses all bits of an octet, but has the quality of
preserving the full US-ASCII range. The UTF-8 encoding of Unicode and UCS avoids the
problems of fixed-length Unicode encodings because an ASCII file encoded in UTF is exactly
same as the original ASCII file and all non-ASCII characters are guaranteed to have the most
significant bit set (bit 0x80). This means that normal tools for text searching work as expected.
UTF16
A 16-bit Unicode Translation Format.
V
Varbyte:
A data type that represents a variable-length binary string.
Varchar:
A data type that represents a variable-length non-numeric character.
Vargraphic:
A data type that represents a variable-length string of characters.
view: An alternate way of organizing and presenting information in a Teradata Database. A
view, like a table, has rows and columns. However, the rows and columns of a view are not
directly stored by the Teradata Database. They are derived from the rows and columns of
tables (or other views) whenever the view is referenced.
VM (Virtual Machine):
VM/CMS
Teradata FastLoad Reference
One of the primary operating systems for large IBM computers.
Virtual Machine/Conversational Monitor System
213
Glossary
W
workgroups: Workgroups represent collections of related scheduled request work for users,
user groups, or accounts. Each workgroup is assigned a maximum number of requests that
can be executing from that workgroup simultaneously thereby ensuring that requests for all
workgroups get a fair share of their scheduled work done within the execution time frames.
workload limits rule A Workload Limits rule allows limiting the number of logon sessions
and all-AMP queries, as well as reject or delay queries when workload limits are encountered.
Which users, accounts, performance groups, or users within performance groups that are
associated with this type of rule can be defined.
Workstation:
A network-attached client.
Work Table: A table created during the Preliminary Phase used to store intermediate data
acquired from the host during an MLOAD task. These data will eventually be applied to a
target table.
Write Lock: A write lock enables a single user to modify a table. The Teradata MultiLoad
utility maintains write locks against each target table during the Application Phase, and work
tables and error tables for each task transaction.
X
XML: XML is the eXtensible Markup Language—a system created to define other markup
languages. For this reason, it can also be referred to as a metalanguage. XML is commonly
used on the Internet to create simple methods for the exchange of data among diverse clients.
Z
z/Linux: Linux operating system (RedHat or SuSE) compiled to run on IBM System z
machines.
z/OS (MVS (Multiple Virtual Storage) ) One of the primary operating systems for large
IBM computers.
214
Teradata FastLoad Reference
Index
Symbols
C
* (asterisk character), as the minimum and maximum
sessions specification, SESSIONS command 138
.* default VALUES clause, INSERT statement 113
c specification, SET RECORD command 142
character set codes
ASCII 55
EBCDIC 55
kanji 55
character sets
AXSMOD 56
determining 147
programming considerations 54
supported 19
Unicode 56
UTF-16 57
UTF-8 57
CHARACTERS data type specification, DEFINE command
NULLIF restrictions and limitations 100
character-to-date data conversions 20
character-to-numeric data conversions 20
CHARSET
configuration file specification 53
CHECKPOINT keyword, BEGIN LOADING command 88,
89
checkpoints
description 20
internal 105
trade-offs 57
with access modules 58
CLEAR command
defined 25
syntax 91
using with HELP TABLE commands 112
cname specification
INSERT statement 113
command specification, OS command 129
commands
defined 24
functions 24
syntax, see individual commands
comments, programming considerations 58
compiling and linking routines
HP-UX 189
HP-UX Itanium 190
HP-UX PA RISC 189
Linux 191
Solaris 192
Sun Solaris Opteron 188
Numerics
3944 error message 59
A
abort, defined 199
access privileges, required, INSERT statement 114
accounts, defined 199
acctid specification, LOGON command 122
administrator, defined 199
ANSI/SQL DateTime data types 57
DEFINE command 104
INSERT statement 114
specifications 57
ANSIDATE keyword, DATEFORM command 92
API, defined 199
ASCII
character set code 55
specification, SET SESSION CHARSET command 146
AXSMOD
character set 56
checkpoint support 58
command
defined 25
syntax 85
B
BEGIN LOADING command
defined 25
example 90
syntax 87
BINARY specification, SET RECORD command 141
BLKEXIT.C INMOD routine, calling 69
BUFSIZE, configuration file specification 53
bypass-label (BPL) tapes, not supported 24
BYTE data type specification, DEFINE command
NULLIF restrictions and limitations 100
BYTEINT data type specification, DEFINE command
NULLIF restrictions and limitations 100
Teradata FastLoad Reference
215
Index
Sun Solaris Sparc 188
UNIX OS 188, 189, 190, 191, 192
z/Linux 192
concatenated data sets, not supported 24
concurrent load utility tasks, restrictions and limitations 58
configuration file 53
contents 53
file name and location 53
optional specification 33
overriding internal utility defaults 52
processing by the FastLoad utility 54
specifications 52
using 52
configuration parameters
overridden by runtime parameters 52
BUFSIZE 36
CHARSET 37
ERRORLOG 38
MAXSESS 38
MINSESS 38
RATE 38
SLEEP 38
TENACITY 39
VERBOSE 39
overridden by utility commands 52
SESSIONS 138
SET SESSION CHARSET 146
SLEEP 151
TENACITY 153
CREATE TABLE statement
defined 26
D
data
formats, SET RECORD command 142
handling, defined 24
length field, input record 21
transfer capabilities 19
type specifications, DEFINE command 95
data conversions
capabilities 19
example 59
capabilities, limiting factors 58
character-to-date 19
character-to-numeric 19
date-to-character 19
integer-to-decimal 19
numeric-to-numeric 19
data dictionary, defined 201
data encryption
runtime option specification 44
data manipulation, defined 201
data types, ANSI/SQL DateTime 57
216
DATABASE statement, defined 26
DATAENCRYPTION
BEGIN LOADING command 88
configuration file setting 53
datatype specification, DEFINE command 94
DATEFORM command
defined 25
syntax 92
DateTime specifications 57
date-to-character data conversions 20
dbname specification
BEGIN LOADING command 87
HELP TABLE command 111
DDNAME=filename data source specification, DEFINE
command 93, 94
decimal
format 59
zoned 20
DECIMAL data type specification, DEFINE command
NULLIF restrictions and limitations 101
DEFINE command
defined 25
syntax 93
using with HELP TABLE command 111
using with INSERT statements 114
DELETE statement, defined 26
delimiters, defined 201
DISPLAY_ERRORS keyword specification, SET RECORD
command 142
DROP TABLE statement, defined 26
duplicate rows
not inserted by the FastLoad utility 18, 60
DWM
defined 202
E
EBCDIC character set codes 55
END LOADING command
defined 25
syntax 105
end-loading phase 105
end-of-record field, input record 21
endrecordnumber specification, RECORD command 134
ERRLIMIT command
defined 25
syntax 107
error tables
correcting errors recorded in 80
dropped if empty 105
format of 78
multiple databases 87
reusing table names 89
ERRORFILES keyword, BEGIN LOADING command 87
Teradata FastLoad Reference
Index
errorname1 specification, BEGIN LOADING command 88,
89
errors
correcting 78
in the first error table 78
in the second error table 80
data conversion 59
error recording 77
error table format 77, 89
handling 76
NOTIFY implications 127
insertion errors
limiting 107
restarting after 107
specifying the ERRLIMIT value 59
errortname1 specification, BEGIN LOADING command 88
errortname2 specification, BEGIN LOADING command 89
execution time frame, defined 202
EXIT name specification, NOTIFY command 124, 125
exit routines, creating for NOTIFY 127
F
FastLoad job scripts
programming considerations 52
checkpoint trade-offs 57
data conversion factors 58
defined triggers limitation 62
nonunique index sorts 60
range constraints 60
record mode load anomaly 61
referential integrity 62
session limits 61
space requirements and limitations 62
writing 71
FastLoad utility
character set specifications 54
data conversion capabilities 19
data transfer capabilities 19
file requirements 33
file types supported 20
formatted data 21
input data formats 20
input record fields 21
invoking 33
in batch mode 34
in interactive mode 34
operating features and capabilities 18
operating modes 19
overview 17
programming considerations
character set specifications 54
comments 58
restarting 134
Teradata FastLoad Reference
NOTIFY implications 127
starting, LOGON command 122
terminating 47
abort 48
normal 47
unformatted data 21
unsupported data sets and tapes 24
variable-length text 23
field values, inserting 114
field, defined 202
fieldname specification
DEFINE command 93
INSERT statement 113
file types supported 20
FILE=filename data source specification, DEFINE command
93, 94
fileid specifications
RUN command 136
usage rules for z/OS 137
FLOADCFG, configuration file name 53
floadcfg.dat, configuration file name 53
foreign key references 62
formatted data 21
FORMATTED keyword specification, SET RECORD
command 141
G
global rule, defined 203
GRAPHIC data type specifications
DEFINE command 98
NULLIF restrictions and limitations 102
H
HELP command
defined 24
syntax 109
HELP TABLE command
defined 24
syntax 111
HIGH specification, NOTIFY command 124
hours specification, TENACITY command 153
HP-UX Itanium
compiling and linking routines 190
HP-UX PA RISC
compiling and linking routines 189
I
IBM C program examples
compiling, linking and executing
on z/OSsystems 185
INMOD routine 169
indicator
217
Index
bit positions, illustration 90
bytes field, input record 21
INDICATORS keyword, BEGIN LOADING command 88, 90
init-string specification, AXSMOD command 85
INMOD routines and programs
BLKEXIT.C, calling 69
compiling, linking and executing
C on Windows 193
IBM C on z/OS 185
creating your own 70
definition 63
entry points 65
examples 69
FastLoad-to-INMOD interface 65
IBM C program listing 169
INMOD type specification 43
INMOD-to-FastLoad interface 66
platforms and programming languages 64
programming structure 64
using 63
INMOD=name specification, DEFINE command 94
INMODRETURN
configuration file specification 53
inner join, defined 203
input
data fields, input record 21
record fields 21
INSERT statement 113
defined 26
insertion errors
limiting 107
restarting after 107
integer, CHECKPOINT specification, BEGIN LOADING
command 87, 88, 89
INTEGERDATE keyword, DATEFORM command 92
integer-to-decimal data conversions 20
INTO tname specification, INSERT statement 113
invalid record numbers 135
J
JIS, defined 204
job scripts
example 71
multifile example
first output file 161
second output file 163
third output file 165
programming considerations, error limits 59
JOB, SCOPE parameter specification, NOTIFY command
125
join index, restrictions 62
join, defined 204
218
K
kanji character set codes 55
KANJIEUC_0U specification, SET SESSION CHARSET
command 146
KANJISJIS_0S specification, SET SESSION CHARSET
command 146
L
Linux, compiling and linking routines 191
loading 63
LOGDATA command syntax 117
LOGMECH command syntax 118
LOGOFF command
defined 24
syntax 119
LOGON command
defined 24
syntax 121
LOW specification, NOTIFY command 124
M
max, session specification, SESSIONS command 138
maximum sessions 43
MAXSESS 54
configuration file specification 53
MEDIUM specification, NOTIFY command 124
merge join, defined 205
min, sessions specification, SESSIONS command 138
minimum sessions 43
MINSESS 54
configuration file setting 53
minutes specification, SLEEP command 151
MSG string specification, NOTIFY command 125
multifile FastLoad jobs
output file examples
first output file 161
second output file 163
third output file 165
running 73
multiple databases 87
MULTISET tables
duplicate rows not inserted 18, 60
using the MultiLoad utility 30
N
name specification
AXSMOD command 85
DEFINE command 93
NOTIFY command 125
name, defined 205
Named Pipes Access Module 85
nested join, defined 206
Teradata FastLoad Reference
Index
new-line characters in ASCII text files, accommodating 22
NFS. See Network File System
No Primary Index tables 63
NOBLOCK parameter, NOTIFY command 125
nonlabel (NL) tapes, not supported 24
nonunique
index sorts 60
secondary indexes 31
NoPI tables 63
NOSTOP keyword specification, SET RECORD command
142
NOTIFY command
defined 24
syntax 124
null, defined 206
NULLIF option, DEFINE command 94
numeric fields, DEFINE command 102
numeric-to-numeric data conversions 20
O
Object Access filter, defined 206
OFF specification, NOTIFY command 124
OLE DB Access Module 85
operating modes, supported 19
option specification, NOTIFY command 125
order of preference, utility variables 52
OS command, defined 24
outer join, defined 206
output buffer size specification 36
owner, defined 207
P
parser, defined 207
parsing engine (PE), defined 207
password specification, LOGON command 121
paused FastLoad jobs
definition 48
restarting 48
after a database overfill 49
after a system or FastLoad failure 49
after a Teradata Database failure 49
after an AP reset 50
after an unrecoverable error 50
factors affecting 51
performance group, defined 207
privileges, required
BEGIN LOADING command 89
procedures, defined 208
product join, defined 207
product version numbers 3
profiles, defined 208
Teradata FastLoad Reference
Q
queries, defined 208
query analysis, defined 208
query management, defined 208
QUEUE option specification, NOTIFY command 125
using with LOW 126
QUIT command
defined 24
syntax 132
R
range constraints 60
examples 60
types 60
RECORD command
defined 25
entering before INSERT statements 134
syntax 134
record mode load anomaly 61
record numbers, invalid 135
redundant conversions
example 59
supported 20
referential integrity 62
request, defined 209
required access privileges, INSERT statement 114
required privileges
BEGIN LOADING command 89
restart log table, PUBLIC access for BEGIN LOADING
command 89
restrictions and limitations, concurrent load tasks 58
result, defined 209
results file storage, defined 209
results files, defined 209
results tables, defined 209
RETRY command. See TENACITY runtime option
specification
return codes 47
RNAME parameter, NOTIFY command 125
row, defined 209
RowID join, defined 209
rule, defined 210
RUN command
defined 25
executing 137
nesting 137
syntax 136
S
sample procedure, invoking FastLoad
on z/OS systems 45
scheduled requests, defined 210
219
Index
SCOPE parameter, NOTIFY command 125
secondary indexes
not supported by the FastLoad utility 18, 19, 62
using the MultiLoad utility 31
semicolon characters, in FastLoad commands and Teradata
SQL statements 83
separator, defined 210
session character set, AXSMOD 56
sessions 139
control commands, defined 24
defined 210
limits 61, 140
maximum 43
minimum 43
number of 122
invalid 140
reported 123, 140
optimal number 139
SESSIONS command
defined 25
entering before the LOGON command 139
syntax 138
SET RECORD command 141, 142
defined 26
SET SESSION CHARSET command
defined 26
syntax 146
SHOW command
defined 25
syntax 148
SHOW TABLE statement, Teradata SQL. Not supported 114
SHOW VERSIONS command
defined 25
syntax 150
single sign-on
LOGON syntax 121
single sign-on, SSO LOGON command, single sign-on 122
SLEEP
configuration file specification 53
run-time option specification 38, 44
SLEEP command
defined 25
syntax 151
software releases, supported 3
Solaris, compiling and linking routines 192
space requirements and limitations 62
SQL, defined 210
standard
error file 33
input file 33
name specification 43
output file 33
name specification 43
startrecordnumber specification, RECORD command 134
220
statement, defined 211
status codes
FastLoad-to-INMOD interface 65
INMOD-to-FastLoad interface 66
stored procedures, defined 211
string specification, NOTIFY command 125
Sun Solaris Opteron, compiling and linking routines 188
Sun Solaris Sparc, compiling and linking routines 188
supervisory user, defined 211
syntax and use 113
Syntax, how to read 155
SYSTEM/SYSTEMS specification
SCOPE parameter
NOTIFY command 125
T
table definitions, using to define data 103
table, defined 211
TASM 25
tdpid specification, LOGON command 121
TENACITY
command
defined 25
syntax 153
configuration file specification 53
runtime option specification 39, 44
Teradata SQL statements
CREATE TABLE 26
DATABASE 26
DELETE 26
DROP TABLE 26
INSERT 26, 113
using BTEQ to enter 105
terminating FastLoad 47
termination return codes 47
TEXT
keyword specification 142
string specification, NOTIFY command 125
THRU
endrecordnumber specification, RECORD command 135
keyword, RECORD command 134
title, defined 212
tname specification
BEGIN LOADING command 87
HELP TABLE command 111
INSERT statement 113
transaction, defined 212
triggers, defined limitation 62
type, defined 212
U
unformatted
data 21
Teradata FastLoad Reference
Index
records 142
UNFORMATTED keyword specification, SET RECORD
command 141
Unicode
character sets 41, 42, 56
Unicode data, using 103, 115
UNIX OS
compiling and linking routines 188, 189, 190, 191, 192
unsupported data sets and tapes 24
user 213
user groups, defined 213
username specification, LOGON command 121
UTF-16
character sets 41, 42, 57
defined 213
UTF-8
character sets 41, 42, 57
defined 213
utility variables, order of preference 52
V
value, NULLIF specification, DEFINE command 93
VALUES keyword, INSERT statement 113
VARGRAPHIC data type specification, DEFINE command
NULLIF restrictions and limitations 102
variable-length
fields, using 143
text 23
VARTEXT
keyword specification, SET RECORD command 142
records 143
version numbers 3
VERSIONS keyword, SHOW VERSIONS command 150
W
WebSphere MQ Access Module for Teradata
client version 85
server version 85
workgroups, defined 214
workload limits rule, defined 214
Z
z/Linux, compiling and linking routines 192
z/OS program examples
for creating and using INMOD routines
in IBM C 185
for invoking FastLoad 45
INMOD routines
using IBM C 169
zoned decimal 59
formats, supported 20
Teradata FastLoad Reference
221
Index
222
Teradata FastLoad Reference