A

Teradata Parallel Transporter
Operator Programmer Guide
Release 14.00 B035-2435-071A November 2011
The product or products described in this book are licensed products of Teradata Corporation or its affiliates. Teradata, Active Enterprise Intelligence, Applications Within, Aprimo, Aprimo Marketing Studio, Aster, BYNET, Claraview, DecisionCast, Gridscale, Managing the Business of Marketing, MyCommerce, Raising Intelligence, Smarter. Faster. Wins., SQL-MapReduce, Teradata Decision Experts, Teradata Labs Logo, Teradata Raising Intelligence Logo, Teradata Source Experts, WebAnalyst, and Xkoto are trademarks or registered trademarks of Teradata Corporation or its affiliates in the United States and other countries. Adaptec and SCSISelect are trademarks or registered trademarks of Adaptec, Inc. AMD Opteron and Opteron are trademarks of Advanced Micro Devices, Inc. EMC, PowerPath, SRDF, and Symmetrix are registered trademarks of EMC Corporation. GoldenGate is a trademark of Oracle. Hewlett-Packard and HP are registered trademarks of Hewlett-Packard Company. Intel, Pentium, and XEON are registered trademarks of Intel Corporation. IBM, CICS, RACF, Tivoli, and z/OS are registered trademarks of International Business Machines Corporation. Linux is a registered trademark of Linus Torvalds. LSI is a registered trademark of LSI Corporation. Microsoft, Active Directory, Windows, Windows NT, and Windows Server are registered trademarks of Microsoft Corporation in the United States and other countries. NetVault is a trademark or registered trademark of Quest Software, Inc. in the United States and/or other countries. Novell and SUSE are registered trademarks of Novell, Inc., in the United States and other countries. Oracle, Java, and Solaris are registered trademarks of Oracle and/or its affiliates. QLogic and SANbox are trademarks or registered trademarks of QLogic Corporation. SAS and SAS/C are trademarks or registered trademarks of SAS Institute Inc. SPARC is a registered trademark of SPARC International, Inc. Symantec, NetBackup, and VERITAS are trademarks or registered trademarks of Symantec Corporation or its affiliates in the United States and other countries. Unicode is a registered trademark of Unicode, Inc. in the United States and other countries. UNIX is a registered trademark of The Open Group in the United States and other countries. Other product and company names mentioned herein may be the trademarks of their respective owners.
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROVIDED ON AN AS-IS BASIS, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO THE ABOVE EXCLUSION MAY NOT APPLY TO YOU. IN NO EVENT WILL TERADATA CORPORATION BE LIABLE FOR ANY INDIRECT, DIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS OR LOST SAVINGS, EVEN IF EXPRESSLY ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
The information contained in this document may contain references or cross-references to features, functions, products, or services that are not announced or available in your country. Such references do not imply that Teradata Corporation intends to announce such features, functions, products, or services in your country. Please consult your local Teradata Corporation representative for those features, functions, products, or services available in your country. Information contained in this document may contain technical inaccuracies or typographical errors. Information may be changed or updated without notice. Teradata Corporation may also make improvements or changes in the products or services described in this information at any time without notice. To maintain the quality of our products and services, we would like your comments on the accuracy, clarity, organization, and value of this document. Please email: teradata-books@lists.teradata.com. Any comments or materials (collectively referred to as Feedback) sent to Teradata Corporation will be deemed non-confidential. Teradata Corporation will have no obligation of any kind with respect to Feedback and will be free to use, reproduce, disclose, exhibit, display, transform, create derivative works of, and distribute the Feedback and derivative works thereof without limitation on a royalty-free basis. Further, Teradata Corporation will be free to use any ideas, concepts, know-how, or techniques contained in such Feedback for any purpose whatsoever, including developing, manufacturing, or marketing products or services incorporating Feedback. Copyright 1999-2011 by Teradata Corporation. All Rights Reserved.
Preface
Purpose
This book provides information about Teradata Parallel Transporter (Teradata PT), which is a Teradata Tools and Utilities product. Teradata Tools and Utilities is a group of client products designed to work with the Teradata Database. Teradata PT provides high-performance extraction, transformation, and loading operations on the Teradata Database. This programmer guide provides information: Necessary develop custom Teradata PT operators Related to the operator interface functions that support all functional intercommunication between operators and the Teradata PT infrastructure.
Audience
This book is intended for use by: System and application programmers System administrators Data administrators Relational database developers System operators Other database specialists using Teradata PT
Supported Releases
This book supports the following releases: Teradata Database 14.0 Teradata Tools and Utilities 14.00 Teradata Parallel Transporter 14.00
To locate detailed supported release information:

1 2 3 4
Go to http://www.info.teradata.com Under Online Publications, click General Search. Type 3119 in the Publication Product ID box. Under Sort By, select Date.
3
Teradata Parallel Transporter Operator Programmer Guide
Preface Prerequisites 5 6
Click Search. Open the version of the Teradata Tools and Utilities ##.# Supported Platforms and Product Versions spreadsheet associated with this release.
The spreadsheet includes supported Teradata Database versions, platforms, and product release numbers.
Prerequisites
The following prerequisite knowledge is required for this product: Computer technology and terminology Relational database management systems SQL and Teradata SQL Basic concepts and facilities of the Teradata Database Connectivity software, such as ODBC or CLI Teradata utilities that load and retrieve data
Changes to This Book

The following changes were made to this book in support of the current release. Changes since the last publication 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. Some new functions and features for the current release of Teradata PT might not be documented in this manual. New Teradata PT features and functions are also documented in the other manuals listed in Additional Information on page 4.
Date and Release November 2011 14.00 Description Added appendix A (Teradata PT Publications)
Additional Information
Additional information that supports this product and the Teradata Tools and Utilities is available at the following web sites. 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.
Preface Additional Information
Type of Information Release overview Late information
Description Use the Release Definition for the following information: Overview of all the products in the release Information received too late to be included in the manuals Operating systems and Teradata Database versions that are certified to work with each product Version numbers of each product and the documentation for each product Information about available training and support center
Source
1 Go to http://www.info.teradata.com/. 2 Under Online Publications, click General Search 3 Type 2029 in the Publication Product ID box. 4 Click Search. 5 Select the appropriate Release Definition from
the search results.
Type of Information Additional product information
Description Use the Teradata Information Products web site to view or download specific manuals that supply related or additional information to this manual.
Source
1 Go to http://www.info.teradata.com/. 2 Under the Online Publications subcategory,
Browse by Category, click Data Warehousing.

3 Do one of the following:
For a list of Teradata Tools and Utilities documents, click Teradata Tools and Utilities, and then select an item under Releases or Products. Select a link to any of the data warehousing publications categories listed. Specific books related to Teradata PT are as follows: Teradata Tools and Utilities Access Module Programmer Guide B035-2424-mmyA Teradata Tools and Utilities Access Module Reference B035-2425-mmyA Teradata Parallel Transporter Application Programming Interface Programmer Guide B035-2516-mmyA Teradata Parallel Transporter Operator Programmer Guide B035-2435-mmyA Teradata Parallel Transporter Quick Start Guidee B035-2501-mmyA Teradata Parallel Transporter Reference B035-2436-mmyA Teradata Parallel Transporter User Guide B035-2445-mmyA Teradata Tools and Utilities Installation Guide for IBM z/OS B035-3128-mmyA Teradata Tools and Utilities Installation Guide for Microsoft Windows B035-2407-mmyA Teradata Tools and Utilities Installation Guide for Red Hat Enterprise Linux B035-3121-mmyA Teradata Tools and Utilities Installation Guide for SUSE Linux B035-3122-mmyA Teradata Tools and Utilities Installation Guide for IBM s390x Linux B035-3123-mmyA Teradata Tools and Utilities Installation Guide for HP-UX B025-3124-mmyA
Type of Information
Description
Source Teradata Tools and Utilities Installation Guide for IBM AIX B035-3125-mmyA Teradata Tools and Utilities Installation Guide for Oracle Solaris on AMD Opteron Systems B035-3126-mmyA Teradata Tools and Utilities Installation Guide for Oracle Solaris on SPARC Systems B035-3127-mmyA
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 Use the Teradata Information Products web site to order printed versions of manuals.
1 Go to http://www.info.teradata.com/. 2 Under the Online Publications subcategory,
Browse by Category, click Data Warehousing.

3 Click CD-ROM Images. 4 Follow the ordering instructions.
Ordering information for manuals
1 Go to http://www.info.teradata.com/. 2 Under Print & CD Publications, click How to
Order.
3 Follow the ordering instructions.
General information about Teradata
The Teradata home page provides links to numerous sources of information about Teradata. Links include: Executive reports, case studies of customer experiences with Teradata, and thought leadership Technical information, solutions, and expert advice Press releases, mentions and media resources
Go to Teradata.com/t/resources. Select a link.
Table of Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 Supported Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4 Changes to This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4 Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4
Chapter 1: Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Infrastructure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Key Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Teradata PT Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Operator Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Script Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Schemas. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 17 17 18 19 19 19 20 21 21
Parallel Execution Plan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Chapter 2: Customized Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Object Class Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Operator Object Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Multiphase Coordination Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Function Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Designing and Packaging Custom Operators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Teradata Parallel Transporter Operator Programmer Guide 9
Table of Contents
Binding Methods to an Operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30 Defining Implementations for Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30 Design Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32 Designing a Sequential Producer Operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32 Designing a Filter Operator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32 Executing the Teradata PT APPLY Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33
Chapter 3: Operator Interface Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35

Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35 User-Provided Control Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36 Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36 Service Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41 Allocate Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43 Begin Table Schema Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44 Checkpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46 Create Column Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47 Create Global Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49 Delete Global Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50 Define Error Handler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51 Event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52 Execute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53 Finalize Table Schema Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54 Free Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55 Get Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56 Get Column Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58 Get Column Schema List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60 Get Column Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61 Get Row . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63 Get Table Schema List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65 Initiate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67 Initiate Log Stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .68 Put Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71 Put Column Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73 Put Row . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74 Read Checkpoint Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76 Read Global Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77 Restart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .79 Set Error Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .80 Terminate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81
10
Table of Contents
Terminate Log Stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Update Global Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Write Checkpoint Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Write to Log Stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
82 83 85 86
Appendix A: Teradata PT Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
11
Table of Contents
12
List of Figures
Figure 1: Teradata PT Infrastructure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Figure 2: Parallel Plan Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Figure 3: Operator Object Class Hierarchy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
13
List of Figures
14
List of Tables
Table 1: Operator Interface Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Table 2: Metadata Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Table 3: Object Class Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Table 4: Function Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Table 5: Using Multiphase Coordination Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Table 6: Processing the Apply Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Table 7: Teradata PT Operator Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Table 8: Service Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Table 9: Get-Accessible System Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Table 10: Put-Accessible System Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
15
List of Tables
16
Introduction
CHAPTER 1
This chapter provides the following information: Infrastructure Parallel Execution Plan
Infrastructure
Teradata Parallel Transporter (Teradata PT) is an object-oriented software system that executes multiple instances of data extraction, transformation, and load functions in a scalable, high-speed parallel processing environment.
Key Features
The three key Teradata PT performance features are: Ability to execute multiple instances of an operator. Ability to simultaneously read/transform/load data. As data is placed in the data buffer, the next operator can start performing its task without waiting for the prior process to complete. Eliminates the need for intermediate storagedata is streamed through the process without being written to disk.
Capabilities
Teradata PT can load data into and export data from any accessible database object in the Teradata Database or other data store for which there exists an access operator or an access module. (Producer and consumer operators are collectively known as access operators.) The data source or destination for Teradata PT jobs can be any type: Database (both relational and nonrelational) or database server File or data storage device Object, such as images, pictures, voice, texts, and so on
Between the data source and destination, Teradata PT jobs perform the following processes: Retrieving, storing and transporting specific data objects via parallel data streams Merging or splitting multiple parallel data streams Filtering, conditioning and cleansing of data
17
Chapter 1: Introduction Infrastructure
Operation
The Teradata PT infrastructure provides a simple, declarative SQL-like scripting language for specifying: The load, export, and update processing The data source and destination Any transformation and filtering functions The number of parallel instances of the load, export, update, and transformation operators
In response to a Teradata PT job script, the Teradata PT infrastructure:

1 2 3
Parses the statements in the Teradata PT job script. Initializes its internal components. Creates, optimizes, and executes a parallel plan for completing the Teradata PT job by: Creating instances of the required operator objects Creating a network of data streams which interconnect the operator instances Coordinating the execution of the operators
4 5
Coordinates checkpoint and restart processing. Terminates the processing environment.
Figure 1 illustrates the main components of the Teradata PT infrastructure.

Figure 1: Teradata PT Infrastructure
Teradata Client System Teradata Parallel Transporter Job Script Teradata Parallel Transporter Processor
Teradata Database
Data Source/ Destination Files, Devices, and Databases
Teradata Parallel Transporter Operator Interface
INMOD Routines
INMOD Adapter Operator OUTMOD Adapter Operator Data Connector Operator
Cleanse/Filter/ Condense Operators Consumer Operators
OUTMOD Routines
Access Modules
Producer Operators
2435C001
18
The INMOD and OUTMOD routines are custom software modules that interface with Teradata standalone load and export utilities. These are user exit routines that the load/export operators can call to provide enhanced processing functions on: Input records before they are sent to the Teradata Database (INMOD routines) Output records before they are sent to the client system (OUTMOD routines)
Adapter operators support these routines by allowing you to use the utilities within the Teradata PT infrastructure.
Teradata PT Processor
The Teradata PT processor parses, compiles, and executes a series of statements submitted as a Teradata PT job script. Functional components of the Teradata PT processor include: An interface for submitting user requests A compiler that validates the Teradata PT job script statements and generates and optimizes an internal operating plan An internal metadata manager A data stream controller that uses parallel launch and interprocess communication facilities for routing data between operators A checkpoint-restart manager that provides recovery functions for a Teradata PT job
Operators
Operators are the software components of the Teradata PT infrastructure that provide the actual data extraction, transformation, and load functions in support of various data stores. Teradata PT supports four types of operators: consumer, producer, filter, and standalone. For more information about operators, see the Teradata Parallel Transporter Reference.
Operator Interface
The Teradata PT operator interface is a bidirectional call-level interface that provides the intercommunication between the Teradata PT processor and the operators. All functional communication within the Teradata PT infrastructure is through the Teradata PT operator interfacethere is no direct communication between operators, or between operators and the Teradata PT processor. The interface is defined by the following user-provided and service functions.
19
Table 1: Operator Interface Functions
User-Provided Functions Initiate Terminate Execute Checkpoint Restart Event
Service Functions Allocate Storage Free Storage Begin Table Schema Definition Finalize Table Schema Definition Get Table Schema List Create Column Schema Get Column Schema Get Column Schema List Create Global Variable Read Global Variable Update Global Variable Delete Global Variable Get Attribute Put Attribute Get Column Value Put Column Value Get Row Put Row Read Checkpoint Record Write Checkpoint Record Initiate Log Stream Write to Log Stream Terminate Log Stream Define Error Handler Set Error Message
Refer to Chapter 3: Operator Interface Functions for a complete description of each operator interface function.
Metadata
Teradata PT metadata describes the characteristics of data and processing objects, such as: Data sources and targets Table, column, and file formats Operators
These descriptions provide the basis for all Teradata PT operations, as shown in Table 2.
20
Table 2: Metadata Use
Metadata Type Attributes of data sources and targets Table and column definitions
Purpose Determines the fastest access path for the Parallel Execution Plan Transforms, filters, or cleanses data
Teradata PT components, in effect, are metadata driven, as they are created, optimized, and executed based on guidance derived from the metadata definitions.
Script Language
Teradata PT uses a script language based on ANSI SQL and Teradata utility script languages that allows direct control of scalability. It references extensible, reusable metadata objects. The metadata provides the description of the Teradata PT components and external resources. The declarative script language emphasizes the goal (what) rather than the method (how). It allows seamless integration of extraction, transformation, and loading of data.
Schemas
A schema is a set of metadata definitions about the columns and rows of a data source or destination object, such as: Data types and column sizes Precision, scale, and null-value indicators Database tables, columns and rows
Teradata PT uses schema definitions, which are similar to SQL table definitions. The schema definitions used in Teradata PT: Represent virtual tables. They do not have to correspond to any actual tables in the Teradata Database. Contain column definitions: names, and data types. Act as reusable templates Describe the contents of various data sources and targets, such as files, relational tables, etc. Are similar to record layout definitions used by the Teradata standalone load and unload utilities.
An example of a schema definition follows:

DEFINE SCHEMA FREQ_FLYER_SRC DESCRIPTION SCHEMA FOR FREQUENT FLYER SOURCE FILE ( RES_ID VARACHAR(14), FLIGHT_NO SMALLINT, ORIGIN CHAR(3), DEST CHAR(3), TKT_ID CHAR(12)
21
Chapter 1: Introduction Parallel Execution Plan

TKT_ISSUE_DATE TKT_AMT TRAVEL_AGCY_ID FREQ_MILES_ID ); ANSIDATE, DECIMAL(5,2), CHAR(4), CHAR(8)
Parallel Execution Plan

As shown in Figure 1 on page 18, the Teradata PT processor is the nucleus of the Teradata PT infrastructure. All user requests for importing, exporting, or updating data are submitted to the Teradata PT processor as a job script using high-level, nonprocedural Teradata PT statements. (See Teradata Parallel Transporter Reference for a description of the Teradata PT statements.) The Teradata PT processor parses the statements in the job script, validates their syntax, and creates instances of the specified operators, connected by data streams and a plan for coordinating their execution, called a parallel execution plan. During job execution, the Teradata PT processor:
1 2 3
Uses the Teradata PT metadata to establish the data streams between operators Validates the users access privileges for the data source and destination objects Establishes the optimum path for accessing data within the enterprise
As shown in Figure 2 on page 23, the Teradata PT processor calls the five operator entry points of each operator defined in the job script in a coordinated manner that optimizes job data flow. These entry points (Initiate, Execute, Checkpoint, Restart, and Terminate) are implemented as functions of the Teradata PT operator interface. Note also that the Teradata PT processor can launch multiple instances of any operator defined for parallel execution to scale up performance through parallel processing.
22
Chapter 1: Introduction Parallel Execution Plan Figure 2: Parallel Plan Implementation

Teradata Parallel Transporter Job Script
Initiate Execute Teradata Parallel Transporter Processor Terminate Checkpoint Restart
Operator Interface Stand-Alone Operator
Operator Interface Consumer Operator
Operator Interface Filter Operator
Operator Interface Producer Operator DB DB
CLI
CLI
DB
Legend Teradata Database Function Call Teradata Parallel Transport Message Data Stream Channels/ Gateways
2435E002
23
Chapter 1: Introduction Parallel Execution Plan
24
Customized Operators
CHAPTER 2
This chapter describes the functional aspects of the Teradata PT operator interface and considerations for designing custom operators: Object Class Structure Multiphase Coordination Protocol Designing and Packaging Custom Operators Design Guidelines
Object Class Structure

An object is a software module that consists of data attributes and methods, or functional routines, that operate on the data attributes. Some of the methods define an interface that can be used by other software modules or objects. Adherence to a consistent interface isolates the inner functionality of an object from that of any other interfacing software module or objects. As long as the interface remains the same, the following are true: Changes to the inner workings of an object do not impact referencing applications. Changes to referencing applications do not impact the inner workings of an object.
Description
Objects that adhere to the same interface define an object class. An object that is defined as an instance of an existing object class, with no variations, automatically includes all of the data attributes and methods defined for that object class. An object class that adheres to the interface of another class, yet extends it or includes variations, defines a new subclass, or a derived class. In this case, the original (unmodified) class is sometimes called a super class, or a base class with respect to the derived class. An object that is defined as an instance of a subclass automatically includes (inherits) all of the data attributes and methods defined for the base class, plus all the extensions and variations defined by the subclass. The base class/subclass relationship can be nested to any degree, producing a tree-like structure in which the following occurs: The data attributes and methods of one object define the base class
25
Chapter 2: Customized Operators Object Class Structure
Each subclass object inherits the data attributes and methods of the base class, but includes data attributes and that methods that override the inherited data attributes and methods, and add new object functionality.
Operator Object Classes

Within the Teradata PT infrastructure, every operator is an object. The operator interface provides the base class attributes and methods that are inherited by every defined operator object, as shown in Figure 3. Custom operator objects must use the inherited attributes and methods of the Teradata PT operator interface for functional interaction with other operator objects and with the Teradata PT processor.
Figure 3: Operator Object Class Hierarchy
Operator Class
Filter Class
Access Class
Projector Class
Producer Class
Consumer Class
KY01A090
Within the Teradata PT object class hierarchy, object classes provide the attributes and functions to other objects as described in Table 3.
Table 3: Object Class Descriptions
Operator Object Class Access Class
Description Accesses data objects. The interface functions of this class disregard all of the operational peculiarities of how the data is accessed, and remain consistent for any type of access operator object. As shown in Figure 3, the Access Class object provides the base class functions for the Producer Class and Consumer Class objects.
Consumer Class Filter Class
Accepts data from other operators and stores it in an external data store such as a file or a database table. Filters and cleanses the input data stream, producing a specified output data stream.
26
Chapter 2: Customized Operators Multiphase Coordination Protocol

Table 3: Object Class Descriptions (continued)
Operator Object Class Producer Class
Description Retrieves data from an external data store such as a file or a database table and provides it to other operators. As shown in Figure 3 on page 26, the Producer Class object is a subclass of the Access Class object.
Projector Class
Projects the values of specified attributes from the input data stream. Projector Class operator objects can handle any type of data such as images and pictures, voice, text, and so on.
Multiphase Coordination Protocol

The multiphase coordination protocol is a scalable, flexible, platform-independent technique that synchronizes the functions of multiple parallel instances of Teradata PT operators. Common examples of this technique are to use multiple instances of either of the following operators: Producer operator to access a partitioned table, where each instance of the operator is responsible for reading one partition Consumer operator to write data rows to a database using multiple database sessions
In either case, the access operator must be written to support multiple instances of itself, and they must all be synchronized so they can share, access, or manage resources in a coordinated fashion under the parallel execution environment. The most common coordination methods, such as WAIT, POST, LOCK, UNLOCK, GROUP, and BARRIER functions are usually platform-dependent. They require multiple implementations to support applications in a heterogeneous system environment. The Teradata PT multiphase coordination protocol, however, is platform-independent and functions without modification on any platform that supports the Teradata PT infrastructure.
Function Return Codes

Teradata PT uses the following function return codes to implement the multiphase coordination protocol.
Table 4: Function Return Codes
Return Code PXSTC_SamePhase
Function The method should be invoked again for additional processing, but with no change in phase. This code is usually used in the Execute method for processing data rowby-row.
27

Table 4: Function Return Codes (continued)
Return Code PXSTC_NextPhase PXSTC_EndMethod
Function The method should be invoked again for additional processing, but in the next phase. The method has completed processing and should not be invoked again.
Example
Table 5 shows a simplified example of using the multiphase coordination protocol with three instances of the Load operator running in a master-slave relationship. In this execution, the slave operators behave as if they are in an idle mode while the master operator establishes the processing environment. Independent parallel processing then begins when all operators reach the synchronization point. Upon execution, the Teradata PT processor invokes each operator in the parallel execution plan using the Initiate, Execute, Checkpoint, Restart, or Terminate functions. In return, each operator returns its status with either a SamePhase, NextPhase, or EndMethod response. Method processing continues in the first phase until each instance of the operator has returned a NextPhase status, which signifies the end of the first phase and the beginning of the second. This phase processing continues, with no limit to the number of phases allowed, until each instance of the operator has returned an EndMethod status. The entire process repeats for each method, with the SamePhase, NextPhase, and EndMethod status returns providing the synchronization points for the multiphase coordination. Note: The multiphase coordination protocol is also available for operators that are not master/slave oriented. As indicated, the phase coordination process is implemented and controlled by the operators themselves, not by the Teradata PT processor. Under this protocol, operators are free to coordinate operations among themselves by using the appropriate status returns to guide the Teradata PT processor.
Table 5: Using Multiphase Coordination Protocol
Method Initiate
Phase Master Operator Object 1 Allocate global variables Create/connect a Teradata SQL session for obtaining the LSN parcel Extract LSN from the LSN parcel Save LSN as a global variable Create/connect a Teradata SQL session
Slave 1 Operator Object Create/connect a Teradata SQL session Return NextPhase
Slave 2 Operator Object Create/connect a Teradata SQL session Return NextPhase
28

Table 5: Using Multiphase Coordination Protocol (continued)
Method
Phase Master Operator Object Return NextPhase 2 Create/connect Load sessions using the LSN global variable Return NextPhase 3 Issue Begin Loading Return EndMethod
Slave 1 Operator Object
Slave 2 Operator Object
Create/connect Load sessions using the LSN global variable Return EndMethod
Create/connect Load sessions using the LSN global variable Return EndMethod
Execute
Read record from a data source IF end-of-file, return NextPhase ELSE return SamePhase
Read a record from a data source IF end-of-file, return EndMethod ELSE return SamePhase
Read a record from a data source IF end-of-file, return EndMethod ELSE return SamePhase
Issue End Loading (if specified by the user) Return EndMethod
Checkpoint 1
Write statistics to Global Variable Return NextPhase
Write statistics to Global Write statistics to Variable Global Variable Return EndMethod Return EndMethod
Write checkpoint records to the restart log file Return EndMethod
Restart
Process checkpoint records Return NextPhase
Process checkpoint records Return EndMethod
Process checkpoint records Return EndMethod
Write a restart record to the restart log file to indicate end-of-restart Return EndMethod
Terminate
Disconnect Load sessions Return NextPhase
Disconnect Load sessions Return NextPhase Disconnect Teradata SQL session Return EndMethod
Disconnect Load Sessions Return NextPhase Disconnect Teradata SQL session Return EndMethod
Disconnect Teradata SQL session Deallocate Global Variables Return EndMethod
29
Chapter 2: Customized Operators Designing and Packaging Custom Operators
Designing and Packaging Custom Operators

You can develop customized Teradata PT operators using the Teradata PT operator API that fits your specific needs. The Teradata PT operator interface supports operators written in: C (the preferred language for coding custom operators) C++
Use the following statement to include the Teradata PT operator interface header file in your operator object module:
#include <pxoper.h>
Binding Methods to an Operator

Teradata PT operators are packaged according to type (consumer, producer, filter, or standalone). Each operator type corresponds to a load module that is read by the Teradata PT processor and dynamically loaded into memory at execution time. Each operator load module is referenced by the Teradata PT processor using the operator object name, which must be defined in the Teradata PT metadata. Use the following function to define your operator:
PX_DefineOperator(operatorModuleName, phaseIndicator);
where: operatorModuleName - a character string that uniquely identifies the operator to which the methods are to be bound phaseIndicator - the indication of whether or not the operator uses the multiphase coordination protocol: PX_MultiPhase PX_NonMultiPhase
Example 1
PX_DefineOperator(liboperator1, PX_MultiPhase);
Defining Implementations for Methods

Use the following model to define an implementation for a method:
PXSTC_Code PX_Method(PXOperatorHandle operatorHandle, PX_LongInt phase) { . return(PXSTC_EndMethod); }
where PX_Method can be one of the following: PX_Initiate PX_Execute
30
Chapter 2: Customized Operators Designing and Packaging Custom Operators
PX_Checkpoint PX_Restart PX_Event PX_Terminate
Example The following example shows how to define methods for an access operator:
/**** INITIATE method ****/ PXSTC_Code PX_Initiate(PX_OperatorHandle operatorHandle, PX_LongInt phase) { . return(PXSTC_EndMethod); } /**** EXECUTE method ****/ PXSTC_Code PX_Execute(PX_OperatorHandle operatorHandle, PX_LongInt phase) { . return(PXSTC_EndMethod); } /**** TERMINATE method ****/ PXSTC_Code PX_Terminate(PX_OperatorHandle operatorHandle, PX_LongInt phase) { . return(PXSTC_EndMethod); } /**** CHECKPOINT method ****/ PXSTC_Code PX_Checkpoint(PX_OperatorHandle operatorHandle, PX_LongInt phase) { . return(PXSTC_EndMethod); } /**** RESTART method ****/ PXSTC_Code PX_Restart(PX_OperatorHandle operatorHandle, PX_LongInt phase) { . return(PXSTC_EndMethod); } /**** EVENT method ****/ PXSTC_Code PX_Event(PX_OperatorHandle operatorHandle, PX_LongInt phase) { . return(PXSTC_EndMethod); } } PX_DefineOperator(MyOperatorName, PX_MultiPhase);
31
Chapter 2: Customized Operators Design Guidelines
Design Guidelines
Regardless of type, all Teradata PT operators must be re-entrant. This allows the operator to be loaded once and then referenced by multiple applications within the same address space.
Designing a Sequential Producer Operator

Use the following process guidelines for implementing the Initiate, Execute, and Terminate functions for a sequential producer operator.
Function Initiate Process
1 Use the Get Attribute function to get the path name of the sequential file. 2 Use the path name to open the file and get the file handle. 3 Use the Allocate Storage function to allocate a user area. 4 Save the file handle in the user area. 5 Use the Allocate Storage function to allocate a data buffer area big enough to hold
the maximum size of a row in the sequential file.

6 Save the data buffer address and the buffer length in the user area. 7 Use the Put Attribute function to save the user area.
Execute
1 Get the output table handle. 2 Use the Get Attribute function to get the user area. 3 Get the file handle and the data buffer address from the user area. 4 Use the file handle to read the next row into the data buffer. 5 Use the Get Table Schema List function to get the output data schema. 6 If the read is successful, use the Put Row function to write the row to the output
data stream and return the PXSTC_SamePhase status.

7 If the read/write is not successful, return bad status. 8 If end-of-file is encountered, return either PXSTC_EndOfData or
PXSTC_EndMethod status. Terminate

1 Use the Get Attribute function to get the user area. 2 Get the file handle from the user area. 3 Use the file handle to close the sequential file. 4 Use the Free Storage function to free the data buffer. 5 Use the Free Storage function to free the user area.
Designing a Filter Operator

Use the following process guidelines for implementing the Initiate, Execute, and Terminate functions for a filter operator:
32
Function Initiate Execute
Process None.
1 Use the Get Table Schema List function to get the input data schema handle. 2 Use the Get Row function to read a row. 3 Use the Get Column Schema function to get the column handles associated with
the input data schema.

4 For each of the column handles involved in the filter task: a Use the Get Column Value function to get the column value. b Compare the column value with the filter value. 5 If all column values satisfy the filter criteria, return PXSTC_EndMethod status,
otherwise return PXSTC_DiscardRow status. Terminate None.
Sample Filter Operator On Windows, see the following text file in the Teradata Parallel Transporter installation folder for a sample filter operator: %TWB_ROOT%\sdk\src\samplefilter.cpp. (%TWB_ROOT% is the Teradata Parallel Transporter installation folder.)
Executing the Teradata PT APPLY Statement

Use the following Teradata PT APPLY statement to provide the Load operator with selected and filtered data rows:
APPLY ( <DML statement(s)> ) TO OPERATOR (LOAD_OPER) VIA OPERATOR (MYFILTER) SELECT * FROM SEQTAB;
Following is the Teradata PT processing that occurs in response to this command:

Table 6: Processing the Apply Statement
Function Initiate
Process Sequential producer operator: Open the sequential file. Filter operator: No operation. Load consumer operator:
1 Create logical sessions to communicate with the Teradata Database. 2 Allocate resources and set up the processing environment
Execute
Sequential producer operator: Read the next row. Filter Operator: Perform the filter processing. Load consumer operator: Get the qualified row from the data stream and send it to the Teradata Database.
33

Table 6: Processing the Apply Statement (continued)
Function Terminate
Process Sequential producer operator: Close the sequential file. Filter operator: No operation. Load consumer operator: Deallocate resources and terminate the processing environment. Destroy logical sessions.
For more information about the APPLY statement, see the APPLY topic in Chapter 3 of the Teradata Parallel Transporter Reference.
34
Operator Interface Functions
CHAPTER 3
This chapter describes the following functions of the Teradata PT operator interface: Description User-Provided Control Functions Data Types Service Functions
Description
The Teradata PT operator interface is defined by the functions of the PX_Operator class, which are either user-provided control functions or service functions. In the following example, functions with a prefix of virtual and ending with =0 are userprovided control functions that must be overridden by each interfacing operator. All other functions are service functions that provide the operational interface to the Teradata PT infrastructure.
( public: virtual PXSTC_Code PX_Initiate() = 0; virtual PXSTC_Code PX_Terminate() = 0; virtual PXSTC_Code PX_Execute() = 0; virtual PXSTC_Code PX_Checkpoint() = 0; virtual PXSTC_Code PX_Restart() = 0; virtual PXSTC_Code PX_Event() = 0; PXSTC_Code PX_GetAttribute(); PXSTC_Code PX_PutAttribute(); PXSTC_Code PX_AllocateStorage(); PXSTC_Code PX_FreeStorage(); PXSTC_Code PX_CreateGlobalVar(); PXSTC_Code PX_DeleteGlobalVar(); PXSTC_Code PX_ReadGlobalVar(); PXSTC_Code PX_UpdateGlobalVar(); PXSTC_Code PX_SetErrorMessage(); PXSTC_Code PX_ReadCheckpointRecord(); PXSTC_Code PX_WriteCheckpointRecord(); PXSTC_Code PX_BeginTableSchemaDefinition(); PXSTC_Code PX_FinalizeTableSchemaDefinition(); PXSTC_Code PX_CreateColumnSchema(); PXSTC_Code PX_GetTableSchemaList(); PXSTC_Code PX_GetColumnSchemaList(); PXSTC_Code PX_GetColumnSchema(); PXSTC_Code PX_GetColumnValue();
35
Chapter 3: Operator Interface Functions User-Provided Control Functions

PXSTC_Code PXSTC_Code PXSTC_Code PXSTC_Code PXSTC_Code PXSTC_Code PXSTC_Code } PX_PutColumnValue(); PX_GetRow(); PX_PutRow(); PX_LogInit(); PX_LogWrite(); PX_LogTerminate(); PX_SetLogError();
User-Provided Control Functions

At a minimum, each customized operator must define the following user-provided control functions:
Function Initiate Use Preparing the operating environment for executing operators by performing the following tasks: Establishing a connection with a target database Allocating storage for processing data rows or for subsequent Teradata PT operations Opening a data set for row retrieval or update Parsing input parameters Specifying the cursor position for reading a file Locking a table for exclusive update operations Execute Performing the following data access and manipulation tasks: Checkpoint Restart Event Terminate Reading rows from a data source Writing data to a data target Projecting column values Filtering data Converting data types Merging and splitting data streams
Writing checkpoint records to a restart log table that the operator can use to restart in case of a hardware or software system failure. Restarting operators using the most recently written checkpoint records. Performing event processing or notification based on caller-specified event. Releasing system resources allocated by the corresponding Initiate function.
Data Types
Table 7 on page 37 defines the parameter data types of Teradata PT operator interface control functions.
36
Chapter 3: Operator Interface Functions Data Types
Table 7: Teradata PT Operator Data Types
Data Type PX_Addr PX_AttributeCode PX_AttributeName PX_AttributeValue PX_ByteOffset PX_Code
Definition The address of a memory location. An integer that represents the name of an object attribute. Pointer to a null-terminated character string that provides the name of an object attribute. Pointer to an area for storage of an attribute value. Integer that specifies the displacement in bytes from the first byte of a row. Integer code that represents either: System code System reason code
PX_ColumnCount PX_ColumnHandle PX_ColumnName PX_ColumnSchemaHa ndle
Integer that specifies the column count. Integer that identifies the instance of a column. Pointer to a null-terminated character string that provides a column name. Integer that represents the instance of the column schema.
PX_ColumnSchemaList Array of column schema handles. PX_Count PX_DataAddr PX_DataType Integer that specifies the count of some object. Address of the data. Integer code that represents the following defined data types of a column: PX_DataType_Integer PX_DataType_SmallInt PX_DataType_Float PX_DataType_Decimal PX_DataType_Char PX_DataType_ByteInt PX_DataType_VarChar PX_DataType_Byte PX_DataType_VarByte PX_DataType_Date PX_DataType_Graphic PX_DataType_VarGraphic PX_DataType_Date_ANSI PX_DataType_Boolean PX_DataType_BigInt PX_DataType_LongVarChar PX_CataType_LongVarGraphic
37

Table 7: Teradata PT Operator Data Types (continued)
Data Type PX_ErrorProc PX_ErrorText PX_FilterHandle PX_GlobalHandle PX_Indicator PX_Length PX_LogHandle PX_LongInt PX_Name PX_Number PX_OperatorHandle PX_Precision PX_Scale PX_SchemaType
Definition Function pointer that specifies an error exit function. Pointer to a character string that provides the error message. Integer that identifies the instance of a filter. Integer that identifies the instance of a global. Pointer to the array of indicator bytes specifying whether or not the corresponding column value is NULL. Integer that specifies the size, in bytes, of an object. Integer that specifies a log stream definition. The structure is allocated by the Logger API. Four-byte signed integer. Pointer to a null-terminated character string that provides the name of an object. Integer that specifies the number (instance) of an object. Integer code that identifies the instance of an operator. Integer that specifies a precision value (number of digits) for a numeric data type. Integer that specifies a scale value (number of digits to the right of the decimal point) for a numeric data type. Integer code that identifies one of the following schema types: PX_InputSchema PX_InputOutputSchema PX_OutputSchema
PX_TableSchemaHandl e PX_TableSchemaList PX_TruthValue
Integer code that identifies the instance of the table schema. Array of table schema handles. Integer that specifies one of the following values: PX_True PX_False
38

Data Type PXSTC_Code
Definition Integer that indicates the success or failure of a Teradata PT service function or operator routine. The defined codes are: PXSTC_BadHandle - an invalid object handle. This can happen if the object is of the wrong type or if the object is not accessible by the application. PXSTC_CatalogError - unable to open the message catalog. PXSTC_CheckPoint - request a checkpoint processing. PXSTC_CheckPointNotReady - the operator is not ready for checkpoint processing. PXSTC_CheckPointReady - the operator is ready for checkpoint processing. PXSTC_CommunicationError - an error was detected during the communication between a client and a service. PXSTC_Conflict - mismatching type of operations, data, or protocols. PXSTC_CountError - the specified number of objects does not match some predefined value. PXSTC_DataStreamError - an error was encountered in the Teradata PT data stream. PXSTC_DiscardRow - delete the current row. PXSTC_Duplicate - a duplicate component or resource. PXSTC_EndMethod - the end of a function in multiphase operations. PXSTC_EndOfData - end of data encountered. PXSTC_EndOfProcessing - end of a request processing was encountered. PXSTC_FatalError - an unrecoverable system error was encountered and a restart of the Teradata PT job is required. PXSTC_Full - the specified resource is full. PXSTC_GroupError - an error was detected during the system group processing. PXSTC_InvalidArgument - bad input arguments provided to the operator. PXSTC_InvalidDataType - the data type of some column value or parameter is invalid. PXSTC_InvalidName - the specified name of the object is invalid. PXSTC_IOError - an error occurred during I/O processing. PXSTC_LengthError - conflicting lengths between two objects. PXSTC_LogCommunicationError - error from socket communication with the node Logger. PXSTC_LogFileError - the specified log file name is either invalid or not accessible. PXSTC_LogHandle - an invalid log handle was used to request for log services. PXSTC_LogInsuffMemError - memory allocation failure with the node Logger.
39

Data Type (PXSTC_Code, continued)
Definition PXSTC_LogPassword - the Logger API has supplied a wrong password for the logger. (attempt to access the logger without using the supplied API). PXSTC_LogXDRError - an error was detected by the Logger Services during XDR processing. PXSTC_MetadataError - an error was detected during the processing of metadata. PXSTC_Mismatch - mismatching lengths, components, or data types. PXSTC_MultiphaseError - an error was encountered during multiphase processing. PXSTC_NoMessageCatalog - the requested message catalog is not present. PXSTC_NextPhase -a phase change in multiphase operations. PXSTC_NodeError - a problem with the specified node. PXSTC_NoLogRec - no log record was found in the log file. PXSTC_NotActive - the requested system resource is down or not active. PXSTC_NotEnough - insufficient resources to complete the requested task. PXSTC_NotFound - a requested resource does not exist. PXSTC_NotSupported - the requested resource is not supported. PXSTC_NullHandle - the specified object handle has no value associated with it. PXSTC_NullPointer - a missing value was detected in a pointer type of data. PXSTC_NullRow - a row has no column values associated with it. PXSTC_NullTable - a table with no rows was encountered. PXSTC_ObjectBusy - the requested object is busy or occupied by another resource or user. PXSTC_OpenError - an error was detected during the accessing of a file or a resource. PXSTC_OperatorError - an error was encountered when processing an operator. PXSTC_PathError - an invalid specification of a resource location. PXSTC_ParserError - an error was detected during the parsing of a script. PXSTC_ProtocolError - an invalid sequence of operations or illegal use of processing protocol PXSTC_RetryError - an error that allows the system to retry the job execution again. PXSTC_RowError - an error was detected when processing a row. PXSTC_SamePhase - no phase change in multi-phase operations. PXSTC_SchemaError - an error was detected in the data schema.
40
Chapter 3: Operator Interface Functions Service Functions

Data Type PXSTC_Code (continued)
Definition PXSTC_Size - invalid size of an object. PXSTC_Storage - an error was encountered during storage allocation or deallocation. PXSTC_Success - successful completion of the operation. PXSTC_SyntaxError - a syntax error was encountered in a command or script. PXSTC_SystemError - a Teradata PT error while processing a Teradata PT operator function. PXSTC_TaskError - an error was encountered at the task/process level. PXSTC_TimeOut - a specific usage time value for a resource has expired. PXSTC_UnknownError - an error condition that has no defined explanation. PXSTC_Warning - the operation completed, but with a minor error condition.
Service Functions
Each customized operator must use the following service functions for interfacing with Teradata PT or with other Teradata PT operators. Descriptions for each of these service functions following this summary.
Table 8: Service Functions
Function Allocate Storage Free Storage Create Global Variable Read Global Variable Update Global Variable Delete Global Variable Put Attribute Get Attribute Put Row Get Row Put Column Value Get Column Value Write Checkpoint Record Read Checkpoint Record
Use Allocating and freeing Teradata PT storage for your operator. Creating, accessing, and deleting global variables.
Storing and retrieving attribute values. Storing and retrieving data rows. Storing and retrieving column values. Storing and retrieving checkpoint records.
41
Chapter 3: Operator Interface Functions Service Functions

Table 8: Service Functions (continued)
Function Create Column Schema Get Column Schema Begin Table Schema Definition Finalize Table Schema Definition Get Table Schema List Get Column Schema List Set Error Message Initiate Log Stream Write to Log Stream Terminate Log Stream Define Error Handler
Use Creating and accessing column schemas. Creating table schemas.
Retrieving lists of table and column schemas. Creating error messages. Initiating, writing, and terminating a log stream function.
Redirecting a call after an error occurs in the Logger API.
Complete descriptions for each of the above functions follow in the next section.
42
Chapter 3: Operator Interface Functions Allocate Storage
Allocate Storage
Purpose Allocate Storage is the service function that allocates Teradata PT storage for the operator. Structure
#include <pxoper.h> PXSTC_Code PX_AllocateStorage(PX_OperatorHandle operator, PX_Length storageSize, PX_Addr * storageAddr);
where:
Parameter operator storageSize storageAddr Function input input output Specification Instance of the operator for which the storage is to be allocated. Amount of storage you want to allocate to the named operator. Pointer to the address of the allocated storage.
Return Codes The following Allocate Storage function status codes are defined by the Teradata PT operator interface.
Status Code PXSTC_InvalidArgument PXSTC_BadHandle PXSTC_NotEnough Signifies One or more bad input arguments. An undefined object handle. Either: Not enough storage can be allocated The requested storage size is too large PXSTC_Success Successful access to the object attribute.
Usage Notes Consider the following when using the Allocate Storage function.
Topic Status Usage Note If the function status is PXSTC_Success, the storage address will be stored in the location indicated by the storageAddr pointer. See also the Free Storage function.
43
Chapter 3: Operator Interface Functions Begin Table Schema Definition
Begin Table Schema Definition

Purpose Begin Table Schema Definition is the service function that starts the definition of a table schema for the operator. Structure
#include <pxoper.h> PXSTC_Code PX_BeginTableSchemaDefinition( PX_OperatorHandle operator, PX_SchemaType schemaType, PX_TableSchemaHandle * tableSchemaHandle);
where
Parameter operator schemaType Function input input Specification Instance of the operator for which the table schema is being defined. Schema type, which can be either: PX_InputSchema PX_OutputSchema PX_InputOutputSchema tableSchemaHandle output Pointer to the defined table schema.
Return Codes The following Begin Table Schema Definition function status codes are defined by the Teradata PT operator interface:
Status Code PXSTC_InvalidArgument PXSTC_BadHandle PXSTC_Success Signifies One or more bad input arguments. An undefined object handle. Successful initiation of the table schema definition.
Usage Notes Consider the following when using the Begin Table Schema Definition function.
44
Chapter 3: Operator Interface Functions Begin Table Schema Definition
Topic Status
Usage Note If the function status is PXSTC_Success, the table schema handle will be stored in the location indicated by the tableSchemaHandle pointer. See also the Finalize Table Schema Definition function.
45
Chapter 3: Operator Interface Functions Checkpoint
Checkpoint
Purpose Checkpoint is a user-provided function that creates a checkpoint record for operators. Structure
#include <pxoper.h> PXSTC_Code PX_Checkpoint(PX_OperatorHandle operator, PX_LongInt phase);
where
Parameter operator phase Function input input Specification Operator handles associated with the Checkpoint function. Current processing phase number
Return Codes The following Checkpoint function status codes are defined by the Teradata PT operator interface:
Status Code PXSTC_EndMethod Signifies Successful checkpoint processing. This status condition indicates that the checkpoint record was successfully written to the restart log by this function. PXSTC_NextPhase PXSTC_SamePhase Proceed with the next processing phase. Continue with the current processing phase.
Define additional Checkpoint function status codes as required to support your operator. Usage Notes Consider the following when using the Checkpoint function.
Topic Description Usage Note Use the Checkpoint function to record the checkpoint information identified by the operator parameter. See also the Restart function.
46
Chapter 3: Operator Interface Functions Create Column Schema
Create Column Schema

Purpose Create Column Schema is the service function that creates the schema for a column. Structure
#include <pxoper.h> PXSTC_Code PX_CreateColumnSchema( PX_TableSchemaHandle tableSchemaHandle, PX_ColumnName columnName, PX_DataType dataType, PX_Length dataLength, PX_ByteOffset offset, PX_Precision precision, PX_Scale scale, PX_TruthValue nullIndicator, PX_ColumnSchemaHandle * columnHandle);
where
Parameter columnHandle columnName dataLength dataType nullIndicator offset Function output input input input input input Specification Column handle for which the schema is being created. Column-name attribute of the column schema. Column length for both numeric and nonnumeric data types. Data type attribute of the column schema. Truth value indicating whether or not the column value can be NULL. Column position in terms of the number of bytes into the data row. An offset specification of -1 signifies that no column position is defined. Precision value (number of digits) for a numeric data type. The precision specification can range from 1 to 38. scale tableSchemaHandle input input Scale value (number of digits to the right of the decimal point) for a numeric data type. Data schema handle by which the column schema will be created.
precision
input
Return Codes The following Create Column Schema function status codes are defined by the Teradata PT operator interface:
47
Chapter 3: Operator Interface Functions Create Column Schema
Status Code PXSTC_InvalidArgument PXSTC_BadHandle PXSTC_Success
Signifies One or more bad input arguments. An undefined data schema handle. Successful creation of the column schema definition.
Usage Notes Consider the following when using the Create Column Schema function.
Topic Data Type Specifications Usage Notes Teradata PT supports the following data type specifications: PX_DataType_Integer PX_DataType_SmallInt PX-DataType_LongInt PX_DataType_Float PX_DataType_Decimal PX_DataType_Char PX_DataType_ByteInt PX_DataType_VarChar PX_DataType_Byte PX_DataType_VarByte PX_DataType_Graphic PX_DataType_VarGraphic PX_DataType_Date PX_DataType_Date_ANSI PX_DataType_Boolean Valid abbreviations in data type specifications: CHARACTERS as: CHARACTER CHARS CHAR DECIMAL as DEC INTEGER as INT Status If the function status is PXSTC_Success, the column schema will be stored in the location indicated by the columnHandle pointer. See also the Get Column Schema function.
48
Chapter 3: Operator Interface Functions Create Global Variable
Create Global Variable

Purpose Create Global Variable is the service function that creates a global variable for the operator. Structure
#include <pxoper.h> PXSTC_Code PX_CreateGlobalVar(PX_OperatorHandle operator, PX_Name varName, PX_Length varSize, PX_Count varCount);
where
Parameter operator varCount varName varSize Function input input input input Specification Instance of the operator handle for which the global variable is being created. Maximum number items to be created for the global variable. Name of the global variable. Item size of the global variable, in bytes.
Return Codes The following Create Global Variable function status codes are defined by the Teradata PT operator interface:
Status Code PXSTC_InvalidArgument PXSTC_BadHandle PXSTC_NotEnough PXSTC_Success Signifies One or more bad input arguments. An undefined object handle. The global variable size is too large Successful creation of the global variable.
Usage Notes Consider the following when using the Create Global Variable function.
Topic Status Usage Notes If the function status is PXSTC_Success, all items of the global variable were created successfully.
49
Chapter 3: Operator Interface Functions Delete Global Variable
Delete Global Variable

Purpose Delete Global Variable is the service function that deletes a global variable that had been created for the operator. Structure
#include <pxoper.h> PXSTC_Code PX_DeleteGlobalVar(PX_OperatorHandle operator, PX_Name varName);
where
Parameter operator varName Function input input Specification Instance of the operator handle for which the global variable is being deleted. Name of the global variable.
Return Codes The following Delete Global Variable function status codes are defined by the Teradata PT operator interface:
Status Code PXSTC_InvalidArgument PXSTC_BadHandle PXSTC_Success Signifies One or more bad input arguments. An undefined object handle. Successful deletion of the global variable.
Usage Notes Consider the following when using the Delete Global Variable function.
Topic Status Usage Notes If the function status is PXSTC_Success, all items of the global variable were deleted successfully. See also the Create Global Variable function.
50
Chapter 3: Operator Interface Functions Define Error Handler
Define Error Handler

Purpose Define Error Handler is the service function that identifies the function to be called if an error occurs in the Logger API. The return value is a pointer to the function previously called when an error occurred. Structure
#include <pxoper.h> PXSTC_Code PX_SetLogError(PX_LogHandle loghandle, PX_ErrorProc errorproc);
where
Parameter loghandle errorproc Function input input Specification The handle to the log stream. The structure is allocated by the Logger API. The function to be called when an error occurs.
Return Codes The Define Error Handler function returns the address of the function previously defined.
Status Code void* Signifies The address of the error procedure previously used.
Usage Notes Consider the following when using the Define Error Handler function.
Topic See Also Usage Notes Initiate Log Stream
Example
#include <pxoper.h> PX_ErrorProc myerror1, myerror2; PX_LogHandle loghandle; PX_LogInit(oprhandle, "mycomponent", 75, NULL, myerror1, &loghandle); . PX_SetLogError(loghandle, myerror2); . PX_Terminate(loghandle);
51
Chapter 3: Operator Interface Functions Event
Event
Purpose Event is a user-provided function that allows operators to perform event processing or notification. Structure
#include <pxoper.h> PXSTC_Code PX_Event(PX_OperatorHandle operator, PX_LongInt phase);
where
Parameter operator phase Function input input Specification Operator handle that is associated with the Event function. Current processing phase number.
Return Codes The following Event function status codes are defined by the Teradata PToperator interface:
Status Code PXSTC_EndMethod Signifies Successful execution of the operator. This status condition indicates that the event was successfully processed by this function. PXSTC_NextPhase PXSTC_SamePhase Proceed with the next processing phase. Continue with the current processing phase.
Define additional Event function status codes as required to support your operator. Usage Notes Consider the following when using the Event function.
Topic Description Usage Notes This function requires the caller to user the PutAttribute function to specify the event to be processed by the operator. Also see Put Attribute on page 71.
52
Chapter 3: Operator Interface Functions Execute
Execute
Purpose Execute is a user-provided function that executes a data processing function for the operator. Structure
#include <pxoper.h> PXSTC_Code PX_Execute(PX_OperatorHandle operator, PX_LongInt phase);
where
Parameter operator Function input Specification Operator handle associated with the Execute function. The operator parameter is a handle that identifies the operator that the Execute function is bound to. You can use this handle to invoke any of the Teradata PT service functions described in this chapter. phase input Current processing phase number
Return Codes The following Execute function status codes are defined by the Teradata PT operator interface. Define additional Execute function status codes required to support your operator.
Status Code PXSTC_EndMethod PXSTC_EndOfData PXSTC_NextPhase PXSTC_SamePhase Signifies Successful execution of the operator. End of data Proceed with the next processing phase. Continue with the current processing phase.
Usage Notes Define additional Execute function status codes as required to support your operator.
Topic Description Usage Notes Use the Execute function to process data row-by-row, as specified by the operator parameter. The following results occur: PXSTC_EndMethod - all rows were successfully processed. PXSTC_NextPhase - advance to the next phase in the same method PXSTC_SamePhase - a row was successfully processed. See also the Initiate function and the Terminate function
53
Chapter 3: Operator Interface Functions Finalize Table Schema Definition
Finalize Table Schema Definition

Purpose Finalize Table Schema Definition is the service function that finalizes the process of creating the table schema. Structure
#include <pxoper.h> PXSTC_Code PX_FinalizeTableSchemaDefinition(PX_TableSchemaHandle tableSchemaHandle);
where
Parameter tableSchemaHandle Function input Specification Table schema handle function to be finalized.
Return Codes The following Finalize Table Schema Definition function status codes are defined by the Teradata PT operator interface:
Status Code PXSTC_Conflict PXSTC_CountError PXSTC_LengthError PXSTC_BadHandle PXSTC_SchemaError PXSTC_Success Signifies Mismatching type of operations, data, or protocols. The specified number of objects does not match some predefined value. The length of the data to be stored does not match the length of the internal buffer. An undefined table schema handle. An error was detected in the data schema. Successful creation of the table schema.
Usage Notes Consider the following when using the Finalize Table Schema Definition function.
Topic Description Usage Notes You must use the Finalize Data Schema Definition function to finalize a data schema before it can be used by Teradata PT operators for subsequent data manipulation functions. If the function status is PXSTC_Success, the defined table schema can be used by Teradata PT operators. See also Begin Table Schema Definition.
Status
54
Chapter 3: Operator Interface Functions Free Storage
Free Storage
Purpose Free Storage is the service function that frees the operator storage that was previously allocated. Structure
#include <pxoper.h> PXSTC_Code PX_FreeStorage(PX_OperatorHandle operator, PX_Addr storageAddr);
where
Parameter operator storageAddr Function input input Specification Operator handle for which the storage is to be freed. Address of the storage to be freed.
Return Codes The following Free Storage function status codes are defined by the Teradata PT operator interface:
Status Code PXSTC_InvalidArgument PXSTC_BadHandle PXSTC_Success Signifies One or more bad input arguments. An undefined object handle. Successful access to the object attribute.
Usage Notes Consider the following when defining the Free Storage function.
Topic Status Usage Notes If the function status is PXSTC_Success, the storage at the location indicated by the storageAddr pointer was successfully freed. See also Allocate Storage.
55
Chapter 3: Operator Interface Functions Get Attribute
Get Attribute
Purpose Get Attribute is the service function that retrieves the value of a specific attribute associated with the operator. Structure
#include <pxoper.h> PXSTC_Code PX_GetAttribute(PX_OperatorHandle operator, PX_AttributeName attributeName, PX_AttributeValue * attributeValue, PX_Length * valueLength);
where
Parameter attributeName attributeValue operator valueLength Function input output input output Specification Name of the object attribute. Retrieved value of the specified attribute. Operator handle from which the attribute is to be retrieved. Length of the retrieved attribute value.
Return Codes The following Get Attribute function status codes are defined by the Teradata PT operator interface:
Status Code PXSTC_InvalidArgument PXSTC_BadHandle PXSTC_NotFound PXSTC_Success Signifies One or more bad input arguments. An undefined object handle. The specified attribute was not found in the specified object. Successful access to the specified attribute.
Usage Notes Consider the following when defining the Get Attribute function.
Topic System Attributes Usage Notes Table 9 on page 57 lists the Teradata PT system attributes that you can retrieve with the Get Attributes function. See also Put Attribute.
56
Chapter 3: Operator Interface Functions Get Attribute
Topic Status
Usage Notes If the function status is PXSTC_Success: The address of the attribute value is stored as the attributeValue parameter. The valueLength parameter indicates the length of the attribute value.
Table 9: Get-Accessible System Attributes
Attribute Name SYSTEM_Code SYSTEM_FilterHandle SYSTEM_GlobalHandle
Data Type PX_Code PX_FilterHandle PX_GlobalHandle
Data Length (in bytes) 4 4 4 4 4 4 4 4 4
Description System ABEND code Handle of the filter object Handle of the global anchor Instance number of the operator, starting from 1 Maximum number of instances that can be created for the operator Address of string containing the operator name Code indicating type of operator: producer=1, consumer=2, filter=3 Current processing phase number Address of the user area
SYSTEM_InstanceNumber PX_Number SYSTEM_MaxInstances SYSTEM_OperatorName SYSTEM_OperatorType SYSTEM_PhaseNumber SYSTEM_UserAreaAddr PX_Count PX_Addr PX_Number PX_Count PX_Addr
57
Chapter 3: Operator Interface Functions Get Column Schema
Get Column Schema

Purpose Get Column Schema is the service function that retrieves the column schema associated with a column. Structure
#include <pxoper.h> PXSTC_Code PX_GetColumnSchema( PX_ColumnSchemaHandle columnHandle, PX_ColumnName *columnName, PX_DataType * dataType, PX_Length * dataLength, PX_ByteOffset * offset, PX_Precision * precision, PX_Scale * scale, PX_TruthValue * nullIndicator);
where
Parameter columnHandle columnName dataLength dataType nullIndicator offset Function output output output output output output Specification Column handle from which the column schema is to be obtained. Column-name attribute of the column schema. Column length for both numeric and nonnumeric data types. Data type attribute of the column schema. Truth value indicating whether or not the column value can be NULL. Column position in terms of the number of bytes into the data row. An offset specification of -1 signifies that no column position is defined. precision output Precision value (number of digits) for a numeric data type. The precision specification can range from 1 to 38. scale output Scale value (number of digits to the right of the decimal point) for a numeric data type.
Return Codes The following Get Column Schema function status codes are defined by the Teradata PT operator interface:
58
Chapter 3: Operator Interface Functions Get Column Schema
Status Code PXSTC_InvalidArgument PXSTC_BadHandle PXSTC_Success
Signifies One or more bad input arguments. An undefined column schema handle. Successful retrieval of the column schema.
Usage Notes Consider the following when defining thee Get Column Schema function.
Topic Status Usage Notes If the function status is PXSTC_Success the values of the output parameters are returned. See also Create Column Schema.
59
Chapter 3: Operator Interface Functions Get Column Schema List
Get Column Schema List

Purpose Get Column Schema List is the service function that retrieves the list of column handles associated with a table schema. Structure
#include <pxoper.h> PXSTC_Code PX_GetColumnSchemaList( PX_TableSchemaHandle tableSchemaHandle, PX_ColumnSchemaList * columnSchemaList, PX_Count * columnSchemaCount);
where
Parameter columnSchemaCount columnSchemaList tableSchemaHandle Function output output input Specification Number of column schemas in the list. Pointer to the location of the retrieved column schema list. Table schema handle from which the column schema list is to be retrieved.
Return Codes The following Get Column Schema List function status codes are defined by the Teradata PT operator interface:
Status Code PXSTC_InvalidArgument PXSTC_BadHandle PXSTC_NotFound PXSTC_Success Signifies One or more bad input arguments. An undefined data schema handle. The specified column schema list was not found in the specified object. Successful retrieval of the list of column handles.
Usage Notes Consider the following when defining the Get Column Schema List function.
Topic Status Usage Notes If the function status is PXSTC_Success, the address of the column schema list is stored in the location pointed to by the columnSchemaList parameter. See also Get Table Schema List.
60
Chapter 3: Operator Interface Functions Get Column Value
Get Column Value

Purpose Get Column Value is the service function that retrieves the data value associated with a column. Structure
#include <pxoper.h> PXSTC_Code PX_GetColumnValue(PX_ColumnHandle columnHandle, PX_Indicator * nullIndicator, PX_DataAddr * dataAddr, PX_Length * dataLength);
where
Parameter columnHandle dataAddr dataLength nullIndicator Function input output output output Specification Column handle from which the column value is to be retrieved. Pointer to the address of the column value. Pointer to the length of the column value. Pointer to the indication of whether or not the column value is NULL.
Return Codes The following Get Column Value function status codes are defined by the Teradata PT operator interface:
Status Code PXSTC_InvalidArgument PXSTC_BadHandle PXSTC_Success Signifies One or more bad input arguments. An undefined column handle. Successful projection of data value to the column.
Usage Notes Consider the following when defining the Get Column Value function.
61
Chapter 3: Operator Interface Functions Get Column Value
Topic Status
Usage Notes If the function status is PXSTC_Success: The nullIndicator parameter indicates whether or not the column value is NULL. The dataAddr parameter stores the address of the column value. The dataLength parameter stores the length of the returned column value. See also the Put Column Value function.
62
Chapter 3: Operator Interface Functions Get Row
Get Row
Purpose Get Row is the service function that retrieves a data row. Structure
#include <pxoper.h> PXSTC_Code PX_GetRow(PX_TableSchemaHandle tableSchemaHandle, PX_Count * columnCount, PX_Indicator ** nullIndicator, PX_ByteOffset ** offsets, PX_Length ** lengths, PX_Addr * rowAddr, PX_Length * rowLength);
where
Parameter columnCount lengths nullIndicator offsets Function output output output output Specification Pointer to the number of columns associated with the data row. Pointer to the array of integers representing the length of the corresponding column value. Pointer to the array of indicator bytes specifying whether or not the corresponding column value is NULL. Pointer to the array of integers representing the corresponding column positions in terms of the number of bytes into the data row. Pointer to the address of the data row. Pointer to the length of the data row. Table schema handle by which the data row is to be obtained.
rowAddr rowLength tableSchemaHandle
output output input
Return Codes The following Get Row function status codes are defined by the Teradata PT operator interface:
Status Code PXSTC_BadHandle PXSTC_Success PXSTC_EndOfData Signifies An undefined data schema handle. Successful retrieval of the data row. End of data.
63
Chapter 3: Operator Interface Functions Get Row
Usage Notes Consider the following when defining the Get Row function.
Topic Return Data Format Status Usage Notes Data rows returned by the Get Row function are always prefixed with NULL indicator bytes. If the function status is PXSTC_Success: The rowAddr parameter stores the address of the data row. The rowLength parameter stores the length of the data row. The columnCount parameter stores the number of columns associated with the data row. The nullIndicators parameter is the address of the array indicating whether or not the column values are NULL. The offsets parameter is the address of the array that indicates the byte offsets into the data row. The lengths parameter is the address of the array that indicates the lengths of the column values. See Also Begin Table Schema Definition function Finalize Table Schema Definition function Put Row function
64
Chapter 3: Operator Interface Functions Get Table Schema List
Get Table Schema List

Purpose Get Table Schema List is the service function that retrieves the table schemas associated with an operator. Structure
#include <pxoper.h> PXSTC_Code PX_GetTableSchemaList( PX_OperatorHandle operator, PX_SchemaType schemaType, PX_TableSchemaList * tableSchemaList, PX_Count * tableSchemaCount);
where
Parameter operator schemaType Function input input Specification Operator handle from which the list of table schemas is to be retrieved. Schema type, which can be either: PX_InputSchema PX_OutputSchema PX_InputOutputSchema tableSchemaList tableSchemaCount output output Pointer to the address of the list of table schemas. Pointer to the number of schemas in the table schema list.
Return Codes The following Get Table Schema List function status codes are defined by the Teradata PT operator interface:
Status Code PXSTC_InvalidArgument PXSTC_BadHandle PXSTC_NotFound PXSTC_Success Signifies One or more bad input arguments. An undefined operator handle. The specified table list was not found in the specified object. Successful fetching of the table schema list.
Usage Notes Consider the following when defining the Get Table Schema List function.
65
Chapter 3: Operator Interface Functions Get Table Schema List
Topic Status
Usage Notes If the function status is PXSTC_Success: The address of the table schema list is stored at the location indicated by the tableSchemaList parameter. The tableSchemaCount parameter points to the number of table schemas in the list.
See Also
Begin Table Schema Definition function Finalize Table Schema Definition function
66
Chapter 3: Operator Interface Functions Initiate
Initiate
Purpose Initiate is the user-provided function that establishes the processing environment for an operator. Structure
#include <pxoper.h> PXSTC_Code PX_Initiate(PX_OperatorHandle operator, PX_LogInt phase);
where
Parameter operator Function input Specification Operator handle associated with the Initiate function. The operator parameter is a handle that identifies the operator that the Initiate function is bound to. You can use this handle to invoke any of the Teradata PT service functions described in this chapter. phase input Current processing phase number
Return Codes The following Initiate function status codes are defined by the Teradata PT operator interface:
Status Code PXSTC_EndMethod PXSTC_NextPhase PXSTC_SamePhase Signifies Successful initialization of the operator. Proceed with the next processing phase. Continue with the current processing phase.
Define additional Initiate function status codes as required to support your operator. Usage Notes Consider the following when defining the Initiate function.
Topic Status Usage Notes If the function status is PXSTC_EndMethod, the processing environment was successfully established by this function. See also the Terminate function.
67
Chapter 3: Operator Interface Functions Initiate Log Stream
Initiate Log Stream

Purpose Initiate Log Stream is used for initiating a log stream. The message catalog name is supplied in the Teradata PT script to make the Log View Server or Log View Client generate the messages. The logging facility itself does not use the message catalog. Structure
#include <pxoper.h> PXSTC_Code PX_LogInit(PX_OperatorHandle oprhandle, char *componentname, PX_Number instancenumber char *outputlogreport, PX_ErrorProc errorproc, PX_LogHandle *loghandle);
where
Parameter componentname instancenumber loghandle Function input input output Specification Name of the component. Number of the operator instance. Handle to the log stream, allocated by the Logger API. The caller is responsible for passing the address of a PX_LogHandle pointer to PX_LogInit, but the Logger API is responsible for allocating the structure. errorproc oprhandle outputlogreport input input input Pointer to the function to be called if an error occurs in the Logger API, or NULL if no specific error handling is wanted. Handle to the operator. Name of the private log report, or NULL, if the log report is public. The outputlogreport parameter may contain an explicit character value, for example, PrivateFileName, or it may be NULL. If NULL is specified, the log becomes PUBLIC.
Return Codes The following Initiate Log Stream function status codes are defined by the Teradata PT operator interface:
Status Code PXSTC_Success Signifies The call succeeded.
68
Status Code PXSTC_LogInsuff MemError PXSTC_CatalogError PXSTC_Log CommunicationError PXSTC_LogPassword PXSTC_InvalidData Type PXSTC_NoMessage Catalog PXSTC_Unknown Error
Signifies Memory allocation failure. No message catalog specified. Error from socket communication with the Node Logger. The Logger API has supplied a wrong password for the logger (indicates an attempt to access the logger without using the supplied API). The type of some of the parameters is unknown to the Logger API. The requested message catalog is not present. Unknown initialization error.
Define additional Initiate Log Stream function status codes as required to support your operator. Usage Notes Consider the following when defining the Initiate Log Stream function.
Topic Status See Also Usage Note If the function status is PXSTC_Success, the message catalog for the operator was successfully initialized by this function Terminate Log Stream function Write to Log Stream function
Example
#include <pxoper.h> PX_ErrorProc myerror; PX_Operator oprhandle; PX_LogHandle *loghandle; . . . PX_Initiate(PX_Operator oprhandle) { . . . . /* Initiate a public log stream for instance 75 of "mycomponent". */ PX_LogInit(oprhandle,"mycomponent", 75, NULL, myerror, &loghandle);
69

. /* Initiate a private log stream named "myreport" for instance 75 of "mycomponent". */ PX_LogInit (oprhandle, "mycomponent", 75, "myreport", myerror, &loghandle); . . /* Initiate a private log stream named using user defined Teradata Parallel Transporter script attribute */ /* (PrivateLogName) for instance 75 of "mycomponent". */ PX_GetAttribute(oprhandle, "PrivateLogName", (PX_AttributeValue *)&value, &length); PX_LogInit (oprhandle, "mycomponent", 75, value, myerror, &loghandle); . . }
70
Chapter 3: Operator Interface Functions Put Attribute
Put Attribute
Purpose Put Attribute is the service function that assigns a value to a specific operator attribute or to an accessible Teradata PT system attribute. Structure
#include <pxoper.h> PXSTC_Code PX_PutAttribute(PX_OperatorHandle operator, PX_AttributeName attributeName, PX_AttributeValue attributeValue, PX_Length valueLength);
where
Parameter attributeName attributeValue operator valueLength Function input input input input Specification Name of the operator attribute to be assigned the value. Address of the location containing the value to be assigned to the operator attribute. Operator handle to which the attribute value is to be assigned. Length of the value to be assigned to the operator attribute.
Return Codes The following Put Attribute function status codes are defined by the Teradata PT operator interface:
Status Code PXSTC_InvalidArgument PXSTC_BadHandle PXSTC_NotFound PXSTC_Success Signifies One or more bad input arguments. An undefined object handle. The specified attribute was not found in the specified object. Successful access to the specified attribute.
Usage Notes Consider the following when defining the Put Attribute function.
Topic System Attributes Usage Notes Table 10 on page 72 lists the Teradata PT system attributes that you can set with the Put Attributes function. See also the Get Attribute function.
71
Chapter 3: Operator Interface Functions Put Attribute
Topic Status
Usage Notes If the function status is PXSTC_Success the value was successfully assigned to the operator attribute.
Table 10: Put-Accessible System Attributes
Attribute Name SYSTEM_Code SYSTEM_UserAreaAddr
Data Type PX_Code PX_Addr
Data Length (in bytes) 4 4
Description System ABEND code Address of the user area
72
Chapter 3: Operator Interface Functions Put Column Value
Put Column Value

Purpose Put Column Value is the service function that stores a value in the specified column. Structure
#include <pxoper.h> PXSTC_Code PX_PutColumnValue(PX_ColumnHandle columnHandle, PX_Indicator nullIndicator, PX_Addr dataAddr, PX_Length dataLength);
where
Parameter columnHandle dataAddr dataLength nullIndicator Function input input input input Specification Column handle where the value is to be stored. The address of the value. Length of the value. Truth value indicating whether or not the column value can be NULL.
Return Codes The following Put Column Value function status codes are defined by the Teradata PT operator interface:
Status Code PXSTC_InvalidArgument PXSTC_BadHandle PXSTC_Success Signifies One or more bad input arguments. An undefined column handle. Successful storage of the specified column value.
Usage Notes Consider the following when defining the Put Column Value function.
Topic Status Usage Notes If the function status is PXSTC_Success, the value is stored in the internal buffer associated with the specified column. See also the Get Column Value function.
73
Chapter 3: Operator Interface Functions Put Row
Put Row
Purpose Put Row is the service function that stores a data row. Structure
#include <pxoper.h> PXSTC_Code PX_PutRow(PX_TableSchemaHandle tableSchemaHandle, PX_Count columnCount, PX_Indicator * nullIndicator, PX_ByteOffset * offsets, PX_Length * lengths, PX_Addr rowAddr, PX_Length rowLength);
where
Parameter columnCount lengths nullIndicator offsets Function input output output output Specification Number of columns associated with the data row. Pointer to the array of integers representing the length of the corresponding column value. Pointer to the array of indicator bytes specifying whether or not the corresponding column value is NULL. Pointer to the array of integers representing the corresponding column positions in terms of the number of bytes into the data row. Pointer to the address of the data row to be stored. Pointer to the length of the data row. Table schema handle by which the data row is to be stored.
rowAddr rowLength tableSchemaHandle
input input input
Return Codes The following Put Row function status codes are defined by the Teradata PT operator interface:
Status Code PXSTC_InvalidArgument PXSTC_BadHandle PXSTC_LengthError PXSTC_Success Signifies One or more bad input arguments. An undefined table schema handle. Length of data to be stored does not match length of internal buffer. Successful storage of the data row.
74
Chapter 3: Operator Interface Functions Put Row
Usage Notes Consider the following when defining the Put Row function.
Topic Indicator Mode Data Usage Notes If the data row is in indicator mode, then the columnCount parameter must be zero and the following parameters must all be NULL: Status nullIndicators offsets lengths Teradata Call-Level Interface Version2 for Channel-Attached Systems Teradata Call-Level Interface Version2 for Network-Attached Systems
If the function status is PXSTC_Success, then the data row is stored in the internal buffer described by the table schema associated with the dataSchemaHandle parameter. Begin Table Schema Definition function Finalize Table Schema Definition function Get Row function
See Also
75
Chapter 3: Operator Interface Functions Read Checkpoint Record
Read Checkpoint Record

Purpose Read Checkpoint Record is the service function that reads a checkpoint record. Structure
#include <pxoper.h> PXSTC_Code PX_ReadCheckpoint(PX_OperatorHandle operator, PX_Addr * dataAddr, PX_Length * dataLength);
where
Parameter dataAddr dataLength operator Function output output input Specification Pointer to the address of the checkpoint record. Pointer to the length of the checkpoint record. Operator handle from which the checkpoint record is to be read.
Return Codes The following Read Checkpoint Record function status codes are defined by the Teradata PT operator interface:
Status Code PXSTC_InvalidArgument PXSTC_BadHandle PXSTC_Success Signifies One or more bad input arguments. An undefined operator handle. Successful read of the checkpoint record.
Usage Notes Consider the following when defining the Read Checkpoint Record function.
Topic Status Usage Notes If the function status is PXSTC_Success, then the checkpoint record is stored in the location pointed to by the dataAddr parameter. See also the Write Checkpoint Record function.
76
Chapter 3: Operator Interface Functions Read Global Variable
Read Global Variable

Purpose Read Global Variable is the service function that retrieves the value of a global variable. Structure
#include <pxoper.h> PXSTC_Code PX_ReadGlobalVar(PX_OperatorHandle operator, PX_Name varName, PX_Count itemIndex, PX_Addr * itemBufferAddr, PC_Length * itemBufferSize);
where
Parameter itemBufferAddr itemBufferSize itemIndex Function output output input Specification Pointer to the address of the buffer where the value of the global variable is stored. Pointer to the size of the item buffer. Item of the global variable to be retrieved. The itemIndex parameter can range from 1 to the maximum limit specified when the global variable was created. operator varName input input Operator handle by which the global variable is to be read. Name of the global variable.
Return Codes The following Read Global Variable function status codes are defined by the Teradata PT operator interface:
Status Code PXSTC_InvalidArgument PXSTC_BadHandle PXSTC_Success Signifies One or more bad input arguments. An undefined object handle. A successful read access of the global variable.
Usage Notes Consider the following when defining the Read Global Variable function.
77
Chapter 3: Operator Interface Functions Read Global Variable
Topic Status
Usage Notes If the function status is PXSTC_Success, then: The value of the global variable is stored in the location pointed to by the itemBufferAddr parameter The length of the global variable value is indicated by the itemBufferSize pointer
See Also
Update Global Variable function Create Global Variable function
78
Chapter 3: Operator Interface Functions Restart
Restart
Purpose Restart is a user-provided function that performs any functionality when an operator is restarted by the infrastructure. Structure
#include <pxoper.h> PXSTC_Code PX_Restart(PX_OperatorHandle operator, PX_LongInt phase);
where
Parameter operator phase Function input input Specification Name of the operator handle to be restarted. Current processing phase number
Return Codes The following Restart function status codes are defined by the Teradata PT operator interface:
Status Code PXSTC_EndMethod PXSTC_NextPhase PXSTC_SamePhase Signifies Successful restart of the operator. Proceed with the next processing phase. Continue with the current processing phase.
Define additional Restart function status codes as required to support your operator. Usage Notes Consider the following when defining the Restart function.
Topic Status Usage Notes If the function status is PXSTC_EndMethod, the restart operation was successfully established by this function. See also the Checkpoint function.
79
Chapter 3: Operator Interface Functions Set Error Message
Set Error Message

Purpose Set Error Message is the service function that assigns an error message to the operator. Structure
#include <pxoper.h> PXSTC_Code PX_SetErrorMessage(PX_OperatorHandle operator, PX_ErrorText message, PX_Length messageLength);
where
Parameter message messageLength operator Function input input input Specification Location of the error message text. Length of the error message text. Operator handle to which the error message is assigned.
Return Codes The following Set Error Message function status codes are defined by the Teradata PT operator interface:
Status Code PXSTC_InvalidArgument PXSTC_BadHandle PXSTC_Success Signifies One or more bad input arguments. An undefined object handle. Successful setting of the error message.
Usage Notes Consider the following when defining the Set Error Message function.
Topic Status Usage Notes If the function status is PXSTC_Success, then: The error message stored at the location specified by the message parameter will be saved by the operator The length of the message is indicated by the messageLength parameter
80
Chapter 3: Operator Interface Functions Terminate
Terminate
Purpose Terminate is the user-provided function that ends the operating environment of the operator. Structure
#include <pxoper.h> PXSTC_Code PX_Terminate(PX_OperatorHandle operator, PX_LongInt phase);
where
Parameter operator Function input Specification Operator handle associated with the Terminate function. The operator parameter is a handle that identifies the operator that the Terminate function is bound to. You can use this handle to terminate any of the Teradata PT service functions described in this chapter. phase input Current processing phase number
Return Codes The following Terminate function status codes are defined by the Teradata PT operator interface:
Status Code PXSTC_EndMethod PXSTC_NextPhase PXSTC_SamePhase Signifies Successful termination of the operator. Proceed with the next processing phase. Continue with the current processing phase.
Define additional Terminate function status codes as required to support your operator. Usage Notes Consider the following when defining the Terminate function.
Topic Status Usage Notes If the function status is PXSTC_EndMethod, the processing environment was successfully terminated by this function. See also Initiate function.
81
Chapter 3: Operator Interface Functions Terminate Log Stream
Terminate Log Stream

Purpose Terminate Log Stream is the service function that ends the log stream. Each initiated log stream (PX_LogInit) must be terminated with a call of PX_LogTerminate with its own specific log handle. Structure
#include <pxoper.h> PXSTC_Code PX_LogTerminate(PX_LogHandle loghandle);
where
Parameter loghandle Function input Specification Handle to the log stream, freed by the Logger API.
Return Codes The following Terminate Log Stream function status codes are defined by the Teradata PT operator interface:
Status Code PXSTC_Success PXSTC_LogCommunicati onError PXSTC_UnknownError Signifies The call succeeded. An error occurred from socket communication with the node Logger. Unknown termination error.
Usage Notes Consider the following when defining the Terminate Log Stream function.
Topic Status Usage Notes If the function status if PXSTC_Success, the message catalog for the operator was successfully terminated by this function. See also Initiate Log Stream.
Example
#include <pxoper.h> PX_ErrorProc myerror; PX_LogHandle loghandle; PX_LogInit(oprhandle, "mycomponent", 75, NULL, myerror, &loghandle); PX_LogTerminate(loghandle);
82
Chapter 3: Operator Interface Functions Update Global Variable
Update Global Variable

Purpose Update Global Variable is the service function that assigns a value to a global variable. Structure
#include <pxoper.h> PXSTC_Code PX_UpdateGlobalVar(PX_OperatorHandle operator, PX_Name varName, PX_Addr itemBufferAddr, PX_Length itemBufferSize); PX_Count itemIndex,
where
Parameter itemBufferAddr itemBufferSize itemIndex Function input input input Specification Address of the buffer where the value to be assigned to the global variable is stored. Size of the value in the item buffer. Item of the global variable to be updated. The itemIndex parameter can range from 1 to the maximum limit specified when the global variable was created. operator varName input input Operator handle by which the global variable is to be updated. Name of the global variable.
Return Codes The following Update Global Variable function status codes are defined by the Teradata PT operator interface:
Status Code PXSTC_InvalidArgument PXSTC_BadHandle PXSTC_LengthError PXSTC_NotEnough PXSTC_Success Signifies One or more bad input arguments. An undefined operator handle. The length of the update value does not match the length of the global variable buffer. The global variable is too large. A successful update access of the global variable.
Usage Notes Consider the following when defining the Update Global Variable function.
Teradata Parallel Transporter Operator Programmer Guide 83
Chapter 3: Operator Interface Functions Update Global Variable
Topic Status
Usage Notes If the function status is PXSTC_Success, the value stored at the itemBufferAddr location is assigned to the specified itemIndex of the varName global variable. Read Global Variable function Create Global Variable function
See Also
84
Chapter 3: Operator Interface Functions Write Checkpoint Record
Write Checkpoint Record

Purpose Write Checkpoint Record is the service function that writes a checkpoint record to the restart log file. Structure
#include <pxoper.h> PXSTC_Code PX_WriteCheckpoint(PX_OperatorHandle operator, PX_Addr dataAddr, PX_Length dataLength);
here
Parameter dataAddr dataLength operator Function input input input Specification Address of the checkpoint record to be written. Length of the checkpoint record. Operator handle from which the checkpoint record is to be read.
Return Codes The following Write Checkpoint Record function status codes are defined by the Teradata PT operator interface:
Status Code PXSTC_InvalidArgument PXSTC_BadHandle PXSTC_Success Signifies One or more bad input arguments. An undefined operator handle. Successful write of the checkpoint record.
Usage Notes Consider the following when defining the Write Checkpoint Record function.
Topic Status Usage Notes If the function status is PXSTC_Success, then the checkpoint record is written to the restart log table. See also the Read Checkpoint Record function.
85
Chapter 3: Operator Interface Functions Write to Log Stream
Write to Log Stream

Purpose Write to Log Stream is the service function that is used for submitting log messages. Structure
#include <pxoper.h> PXSTC_Code PX_LogWrite(PX_LogHandle loghandle, PXInt32 messagenumber, PXInt32 destination, PXInt32 messagecategory, ...);
where
Parameter destination Function input Specification Destination bit mask describing which destinations the message should go to. Any combination of LOG_DEST_CONS and LOG_DEST_LOG is valid. Multiple destinations are entered by oring the values (LOG_DEST_CONS | LOG_DEST_LOG) Handle to the log stream (returned from PX_LogInit()) Category of the message. The valid message categories are: messagenumber input LOG_DEBUG LOG_TRACE LOG_INFO LOG_WARNING LOG_FATALERROR LOG_USERERROR
loghandle messagecategory
input input
Number of the message in the message catalog. The message catalog is identified in the DEFINE OPERATOR statement in the Teradata PT script. The message described by the message number, is used as a format string when accessed from the Log View Client.
86
Parameter ...
Function input
Specification Arguments to the message (1..*). This variable list of parameters is the arguments that will go into the format string from the message catalog. Each argument is supplied with type and value. This is handled by a set of macros in the following way: LOG_INT16(val) - Short integer values. For example, LOG_INT16(5) corresponds to supplying the short value 5. LOG_INT32(val) - Long integer values. E.g. LOG_INT32(56) corresponds to supplying the long value 56. LOG_INT64(val) - Long long values. E.g. LOG_INT64(578) corresponds to supplying the long value 578. LOG_CHAR(val) - Character values. E.g. LOG_CHAR('g') corresponds to supplying the character 'g'. LOG_STRING(val) - String values. E.g. LOG_STRING("mystring") corresponds to supplying the string "mystring". LOG_FLOAT(val) - 32 bit floating point values. E.g. LOG_FLOAT(5.4) corresponds to supplying the floating point value 5.4. LOG_DOUBLE(val) - 64 bit floating point values. E.g. LOG_DOUBLE(5.7) corresponds to supplying the double precision floating point value 5.7. This list must always end with PXEOP (EndOfParameterList) as the last parameter. Failure to do so will make the program loop and eventually incur a memory fault.
Return Codes The following Write to Log Stream function status codes are defined by the Teradata PT operator interface:
Status Code PXSTC_Success PXSTC_Log CommunicationError PXSTC_LogInsuffMem Error PXSTC_InvalidDataType PXSTC_NoMessage Catalog PXSTC_UnknownError Signifies The call succeeded. An error occurred from socket communication with the Node Logger. A memory allocation failure. The type of some of the parameters is unknown to the Logger API. The requested message catalog is not present. Unknown error encountered when writing a log record.
87
Usage Notes Consider the following when defining the Write to Log Stream function.
Topic Status Usage Notes If the function status if PXSTC_Success, the message was successfully written to the message catalog by this function. See also Initiate Log Stream.
Example
#include <pxoper.h> PX_ErrorProc myerror; PX_LogHandle loghandle; PX_LogInit(oprhandle, "mycomponent", 75, NULL, myerror, &loghandle); . PX_LogWrite(loghandle, mymessagenumber, LOG_DEST_CONS | LOG_DEST_LOG, LOG_FATALERROR, ...); . PX_LogTerminate(loghandle);
88
Teradata PT Publications
APPENDIX A
User documentation for Teradata PT is distributed among the following books.
Teradata PT Publications
Publication Teradata Parallel Transporter Quick Start Guide B035-2501-mmyA Contents Provides getting-started information for using Teradata PT. Includes Teradata PT job examples for: Reading data from a flat file and loading it into a Teradata Database target table. Exporting data from a Teradata Database source table and writing it to a flat file. Exporting data from a Teradata Database source table and loading it to a Teradata Database target table. Detailed strategies for planning, implementing, and debugging Teradata PT. The book includes chapters on: Writing Teradata PT template job scripts, the kind of job scripts illustrated in the Teradata Parallel Transporter Quick Start Guide Writing Teradata PT defined schema job scripts that: Move data to and from data targets Move data within the Teradata environment Describing individual Teradata PT operators and access modules Launching, managing, and troubleshooting a Teradata PT job Teradata Parallel Transporter Reference (this book) B035-2436-mmyA A reference book that defines: Teradata PT command line utility commands. Object definition statements that make up the declarative section of a Teradata PT job script. The APPLY statement that makes up the executable section of a Teradata PT job script. Syntax for each Teradata PT operator.
Teradata Parallel Transporter User Guide B035-2445-mmyA
89
Appendix A: Teradata PT Publications Teradata PT Publications
Publication Teradata Parallel Transporter Application Programming Interface Programmer Guide B035-2435-mmyA
Contents Provides information about: Setting up the interface. Coding. Error reporting. Checkpointing and restarting.
Teradata Parallel Transporter Operator Programmer Guide B035-2435-mmyA
Provides information on developing custom operators, including all interface functions that allow communication between the Teradata PT operators and the Teradata PT infrastructure.
90
Index
A
Access Class, operator object subclass 26 Allocate Storage function description 41, 43 structure 43 attributeName parameter Get Attribute function 56 Put Attribute function 71 attributeValue parameter Get Attribute function 56 Put Attribute function 71
description 41, 49 structure 49 custom operators, object class structure 25
D
data types, operator interface control function, description 36 dataAddr parameter Get Column Value function 61 Put Column Value function 73 Read Checkpoint Record function 76 Write Checkpoint Record function 85 dataLength parameter Create Column Schema function 47 Get Column Schema function 58 Get Column Value function 61 Put Column Value function 73 Read Checkpoint Record function 76 Write Checkpoint Record function 85 dataType parameter Create Column Schema function 47 Get Column Schema function 58 Define Error Handler function description 42, 51 structure 51 Define Operator function, example 30 Delete Global Variable function description 41, 50 structure 50 destination parameter, Write to Log Stream function 86
B
Begin Table Schema Definition function description 42, 44 structure 44
C
CD-ROM images 7 Checkpoint function description 46 in multiphase coordination protocol 29 structure 46 columnCount parameter Get Row function 63 Put Row function 74 columnHandle parameter Create Column Schema function 47 Get Column Schema function 58 Get Column Value function 61 Put Column Value function 73 columnName parameter Create Column Schema function 47 Get Column Schema function 58 columnSchemaCount parameter, Get Column Schema List function 60 columnSchemaList parameter, Get Column Schema List function 60 componentname parameter, Initiate Log Stream function 68 Consumer Class, operator object subclass 26 control functions, user-provided 36 Create Column Schema function description 42, 47 structure 47 Create Global Variable function
E
errorproc parameter Define Error Handler function 51 Initiate Log Stream function 68 Event function description 52 structure 52 Execute function description 53 in filter operators 33 in multiphase coordination protocol 29 in sequential producer operators 32 structure 53 Teradata PT LOAD statement 33
91
Index
F
Filter Class, operator object subclass 26 filter operators, designing 32 Finalize Table Schema Definition function description 42, 54 structure 54 Free Storage function description 41, 55 structure 55 function return codes, multiphase coordination protocol 27
itemIndex parameter Read Global Variable function 77 Update Global Variable function 83
L
lengths parameter Get Row function 63 Put Row function 74 loghandle parameter Define Error Handler function 51 Initiate Log Stream function 68 Terminate Log Stream function 82 Write to Log Stream function 86
G
general information about Teradata 7 Get Attribute function description 41, 56 structure 56 System attributes 56 Get Column Schema function description 42, 58 structure 58 Get Column Schema List function description 42, 60 structure 60 Get Column Value function description 41, 61 structure 61 Get Row function description 41, 63 structure 63 Get Table Schema List function description 42, 65 structure 65
M
message parameter, Set Error Message function 80 messagecatagory parameter, Write to Log Stream function 86 messageLength parameter, Set Error Message function 80 messagenumber parameter, Write to Log Stream function 86 metadata, description 20 method implementations defining 30 example 31 multiphase coordination protocol description 27 example 28 function return codes 27
N
nullIndicator parameter Create Column Schema function 47 Get Column Schema function 58 Get Column Value function 61 Get Row function 63 Put Column Value function 73 Put Row function 74
I
Information Products web site 7 Initiate function description 67 in filter operators 33 in multiphase coordination protocol 28 in sequential producer operators 32 structure 67 Teradata PT LOAD statement 33 Initiate Log Stream function description 42, 68 structure 68 instancenumber parameter, Initiate Log Stream function 68 itemBufferAddr parameter Read Global Variable function 77 Update Global Variable function 83 itemBufferSize parameter Read Global Variable function 77 Update Global Variable function 83
O
objects classes description 25 structure 25 description 25 offset parameter Create Column Schema function 47 Get Column Schema function 58 offsets parameter Get Row function 63 Put Row function 74 operator interface
92
Index
control function data types, description 36 description 19 parameter Allocate Storage function 43 Begin Table Schema Definition function 44 Checkpoint function 46 Create Global Variable function 49 Delete Global Variable function 50 Event function 52 Execute function 53 Free Storage function 55 Get Attribute function 56 Get Table Schema List function 65 Initiate function 67 Put Attribute function 71 Read Checkpoint Record function 76 Read Global Variable function 77 Restart function 79 Set Error Message function 80 Terminate function 81 Update Global Variable function 83 Write Checkpoint Record function 85 operatorModuleName parameter, DefineOperator function 30 operators binding methods 30 customizing 25 description 19 oprhandle parameter, Initiate Log Stream function 68 ordering publications 7 outputlogreport parameter, Initiate Log Stream function 68
P
parallel execution plan, creating and implementing 22 phase parameter Checkpoint function 46 Event function 52 Execute function 53 Initiate function 67 Restart function 79 Terminate function 81 phaseIndicator parameter, DefineOperator function 30 precision parameter Create Column Schema function 47 Get Column Schema function 58 Producer Class, operator object subclass 27 producer operators, designing 32 product version numbers 3 Projector Class, operator object subclass 27 Put Attribute function description 41, 71 structure 71 Put Column Value function
description 41, 73 structure 73 Put Row function description 41, 74 structure 74 PX_Addr data type, description 37 PX_AttributeCode data type, description 37 PX_AttributeName data type, description 37 PX_AttributeValue data type, description 37 PX_ByteOffset data type, description 37 PX_CatalogError status code, Initiate Log Stream function 69 PX_Code data type, description 37 PX_ColumnCount data type, description 37 PX_ColumnHandle data type, description 37 PX_ColumnName data type, description 37 PX_ColumnSchemaHandle data type, description 37 PX_ColumnSchemaList data type, description 37 PX_DataAddr data type, description 37 PX_DataType data type, description 37 PX_ErrorProc data type, description 38 PX_ErrorText data type, description 38 PX_FilterHandle data type, description 38 PX_GlobalHandle data type, description 38 PX_Indicator data type, description 38 PX_InvalidDataType status code Initiate Log Stream function 69 Write to Log Stream function 87 PX_Length data type, description 38 PX_LogCommunicationError status code Initiate Log Stream function 69 Terminate Log Stream function 82 Write to Log Stream function 87 PX_LogHandle data type, description 38 PX_LogInsuffMemError status code Initiate Log Stream function 69 Write to Log Stream function 87 PX_LogPassword status code, Initiate Log Stream function 69 PX_LongInt data type, description 38 PX_Name data type, description 38 PX_NoMessage status code, Write to Log Stream function 87 PX_Number data type, description 38 PX_Operator class, description 35 PX_OperatorHandle data type, description 38 PX_Precision data type, description 38 PX_Scale data type, description 38 PX_SchemaType data type, description 38 PX_Success status code Terminate Log Stream function 82 Write to Log Stream function 87 PX_Success status code, Initiate Log Stream function 68 PX_TableSchemaHandle data type, description 38 PX_TableSchemaList data type, description 38 PX_TruthValue data type, description 38 PX_UnknownError status code
93
Index
Initiate Log Stream function 69 Terminate Log Stream function 82 Write to Log Stream function 87 PX-NoMessageCatalog status code, Initiate Log Stream function 69 PXSTC_BadHandle status code Allocate Storage function 43 Begin Table Schema Definition function 44 Create Column Schema function 48 Create Global Variable function 49 Delete Global Variable function 50 description 39 Finalize Table Schema Definition function 54 Free Storage function 55 Get Attribute function 56 Get Column Schema function 59 Get Column Schema List function 60 Get Column Value function 61 Get Row function 63 Get Table Schema List function 65 Put Attribute function 71 Put Column Value function 73 Put Row function 74 Read Checkpoint Record function 76 Read Global Variable function 77 Set Error Message function 80 Update Global Variable function 83 Write Checkpoint Record function 85 PXSTC_CatalogError status code, description 39 PXSTC_CheckPoint status code, description 39 PXSTC_CheckPointNotReady status code, description 39 PXSTC_CheckPointReady status code, description 39 PXSTC_Code data types, descriptions 39, 41 PXSTC_CommunicationError status code, description 39 PXSTC_Conflict status code, description 39 PXSTC_CountError status code, description 39 PXSTC_DataStreamError status code, description 39 PXSTC_DiscardRow status code, description 39 PXSTC_Duplicate status code, description 39 PXSTC_EndMethod status code Checkpoint function 46 description 39 Event function 52 Execute function 53 in multiphase coordination protocol 28 Initiate function 67 Restart function 79 Terminate function 81 PXSTC_EndOfData status code description 39 Execute function 53 Get Row function 63 PXSTC_EndOfProcessing status code, description 39 PXSTC_FatalError status code, description 39
PXSTC_Full status code, description 39 PXSTC_GroupError status code, description 39 PXSTC_InvalidArgument status code Allocate Storage function 43 Begin Table Schema Definition function 44 Create Column Schema function 48 Create Global Variable function 49 Delete Global Variable function 50 description 39 Free Storage function 55 Get Attribute function 56 Get Column Schema function 59 Get Column Schema List function 60 Get Column Value function 61 Get Table Schema List function 65 Put Attribute function 71 Put Column Value function 73 Put Row function 74 Read Checkpoint Record function 76 Read Global Variable function 77 Set Error Message function 80 Update Global Variable function 83 Write Checkpoint Record function 85 PXSTC_InvalidDataType status code, description 39 PXSTC_InvalidName status code, description 39 PXSTC_IOError status code, description 39 PXSTC_LengthError status code description 39 Put Row function 74 Update Global Variable function 83 PXSTC_LogCommunicationError status code, description 39 PXSTC_LogFileError status code, description 39 PXSTC_Loghandle status code, description 39 PXSTC_LogInsuffMemError status code, description 39 PXSTC_LogPassword status code, description 40 PXSTC_LogXDRError status code, description 40 PXSTC_MetadataError status code, description 40 PXSTC_Mismatch status code, description 40 PXSTC_MultiphaseError status code, description 40 PXSTC_NextPhase status code Checkpoint function 46 description 40 Event function 52 Execute function 53 in multiphase coordination protocol 28 Initiate function 67 Restart function 79 Terminate function 81 PXSTC_NodeError status code, description 40 PXSTC_NoLogRec status code, description 40 PXSTC_NoMessageCatalog status code, description 40 PXSTC_NotActive status code, description 40 PXSTC_NotEnough status code
94
Index
Allocate Storage function 43 Create Global Variable function 49 description 40 Update Global Variable function 83 PXSTC_NotFound status code description 40 Get Attribute function 56 Get Column Schema List function 60 Get Table Schema List function 65 Put Attribute function 71 PXSTC_NotSupported status code, description 40 PXSTC_NullHandle status code, description 40 PXSTC_NullPointer status code, description 40 PXSTC_NullRow status code, description 40 PXSTC_NullTable status code, description 40 PXSTC_ObjectBusy status code, description 40 PXSTC_OpenError status code, description 40 PXSTC_OperatorError status code, description 40 PXSTC_ParserError status code, description 40 PXSTC_PathError status code, description 40 PXSTC_ProtocolError status code, description 40 PXSTC_RetryError status code, description 40 PXSTC_RowError status code, description 40 PXSTC_SamePhase status code Checkpoint function 46 description 40 Event function 52 Execute function 53 in multiphase coordination protocol 27 Initiate function 67 Restart function 79 Terminate function 81 PXSTC_SchemaError status code, description 40 PXSTC_Size status code, description 41 PXSTC_Storage status code, description 41 PXSTC_Success status code Allocate Storage function 43 Begin Table Schema Definition function 44 Create Column Schema function 48 Create Global Variable function 49 Delete Global Variable function 50 description 41 Finalize Table Schema Definition function 54 Free Storage function 55 Get Attribute function 56 Get Column Schema function 59 Get Column Schema List function 60 Get Column Value function 61 Get Row function 63 Get Table Schema List function 65 Put Attribute function 71 Put Column Value function 73 Put Row function 74 Read Checkpoint Record function 76
Read Global Variable function 77 Set Error Message function 80 Update Global Variable function 83 Write Checkpoint Record function 85 PXSTC_SyntaxError status code, description 41 PXSTC_SystemError status code, description 41 PXSTC_TaskError status code, description 41 PXSTC_TimeOut status code, description 41 PXSTC_UnknownError status code, description 41 PXSTC_Warning status code, description 41
R
Read Checkpoint Record function description 41, 76 structure 76 Read Global Variable function description 41, 77 structure 77 Reentrant requirement, operator design guidelines 32 Restart function description 79 in multiphase coordination protocol 29 structure 79 rowAddr parameter Get Row function 63 Put Row function 74 rowLength parameter Get Row function 63 Put Row function 74
S
scale parameter Create Column Schema function 47 Get Column Schema function 58 schemas, description 21 schemaType parameter Begin Table Schema Definition function 44 Get Table Schema List function 65 script language 21 sequential producer operators, designing 32 service functions, Teradata PT 41 Set Error Message function description 42, 80 structure 80 storageAddr parameter Allocate Storage function 43 Free Storage function 55 storageSize parameter, Allocate Storage function 43 system attributes, Get Attribute function 56
T
tableSchemaCount parameter, Get Table Schema List
95
Index
function 65 tableSchemaHandle parameter Begin Table Schema Definition function 44 Create Column Schema function 47 Finalize Table Schema Definition function 54 Get Column Schema List function 60 Get Row function 63 Put Row function 74 tableSchemaList parameter, Get Table Schema List function 65 Teradata PT APPLY statement, executing 33 capabilities 17 Infrastructure, description 17 key performance features 17 operational description 18 operator interface, importing 30 operators, design guidelines 32 parallel execution plan 22 schemas, description 21 service functions 41 Teradata PT Processor, description 19 Terminate function description 81 in filter operators 33 in multiphase coordination protocol 29 in sequential producer operators 32 structure 81 Teradata PT LOAD statement 34 Terminate Log Stream function description 42, 82 structure 82
W
Write Checkpoint Record function description 41, 85 structure 85, 86 Write to Log Stream function, description 42
U
Update Global Variable function description 41, 83 structure 83 user-provided control functions 36
V
valueLength parameter Get Attribute function 56 Put Attribute function 71 varCount parameter, Create Global Variable function 49 varName parameter Create Global Variable function 49 Delete Global Variable function 50 Read Global Variable function 77 Update Global Variable function 83 varSize parameter, Create Global Variable function 49 version numbers 3 void status code Define Error Handler function 51
96

A

Загружено:

Сведения о документе

Исходное описание:

Оригинальное название

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

A

Загружено:

Авторское право:

Доступные форматы

Teradata Parallel Transporter

Operator Programmer Guide

Release 14.00 B035-2435-071A November 2011

To locate detailed supported release information:

Teradata Parallel Transporter Operator Programmer Guide

Changes to This Book

Teradata Parallel Transporter Operator Programmer Guide

Preface Additional Information

Type of Information Release overview Late information

the search results.

Teradata Parallel Transporter Operator Programmer Guide

Preface Additional Information

Type of Information Additional product information

Browse by Category, click Data Warehousing.

Teradata Parallel Transporter Operator Programmer Guide

Preface Additional Information

1 Go to http://www.info.teradata.com/. 2 Under the Online Publications subcategory,

Browse by Category, click Data Warehousing.

Ordering information for manuals

1 Go to http://www.info.teradata.com/. 2 Under Print & CD Publications, click How to

General information about Teradata

Go to Teradata.com/t/resources. Select a link.

Teradata Parallel Transporter Operator Programmer Guide

Preface Additional Information

Teradata Parallel Transporter Operator Programmer Guide

Parallel Execution Plan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Chapter 2: Customized Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Chapter 3: Operator Interface Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35

Teradata Parallel Transporter Operator Programmer Guide

Appendix A: Teradata PT Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Teradata Parallel Transporter Operator Programmer Guide

Teradata Parallel Transporter Operator Programmer Guide

Teradata Parallel Transporter Operator Programmer Guide

Teradata Parallel Transporter Operator Programmer Guide

Teradata Parallel Transporter Operator Programmer Guide

Teradata Parallel Transporter Operator Programmer Guide

Teradata Parallel Transporter Operator Programmer Guide

Chapter 1: Introduction Infrastructure

In response to a Teradata PT job script, the Teradata PT infrastructure:

Coordinates checkpoint and restart processing. Terminates the processing environment.

Figure 1 illustrates the main components of the Teradata PT infrastructure.

Data Source/ Destination Files, Devices, and Databases

Teradata Parallel Transporter Operator Interface

INMOD Adapter Operator OUTMOD Adapter Operator Data Connector Operator

Cleanse/Filter/ Condense Operators Consumer Operators

Teradata Parallel Transporter Operator Programmer Guide

Chapter 1: Introduction Infrastructure

Teradata Parallel Transporter Operator Programmer Guide

Chapter 1: Introduction Infrastructure

Table 1: Operator Interface Functions

User-Provided Functions Initiate Terminate Execute Checkpoint Restart Event

Teradata Parallel Transporter Operator Programmer Guide

Chapter 1: Introduction Infrastructure

Table 2: Metadata Use

An example of a schema definition follows:

Teradata Parallel Transporter Operator Programmer Guide

Chapter 1: Introduction Parallel Execution Plan

Parallel Execution Plan

Teradata Parallel Transporter Operator Programmer Guide

Chapter 1: Introduction Parallel Execution Plan Figure 2: Parallel Plan Implementation

Initiate Execute Teradata Parallel Transporter Processor Terminate Checkpoint Restart

Operator Interface Stand-Alone Operator