Teradata Parallel Transporter
Operator Programmer Guide
Release 14.00
B035-2435-071A
June 2012
The product or products described in this book are licensed products of Teradata Corporation or its affiliates.
Teradata, Active Enterprise Intelligence, Applications-Within, Aprimo, Aprimo Marketing Studio, Aster, BYNET, Claraview, DecisionCast,
Gridscale, Managing the Business of Marketing, MyCommerce, Raising Intelligence, Smarter. Faster. Wins., SQL-MapReduce, Teradata Decision
Experts, "Teradata Labs" logo, "Teradata The Best Decision Possible" logo, "Teradata Raising Intelligence" logo, Teradata Source Experts,
WebAnalyst, and Xkoto are trademarks or registered trademarks of Teradata Corporation or its affiliates in the United States and other countries.
Adaptec and SCSISelect are trademarks or registered trademarks of Adaptec, Inc.
AMD Opteron and Opteron are trademarks of Advanced Micro Devices, Inc.
Axeda is a registered trademark of Axeda Corporation. Axeda Agents, Axeda Applications, Axeda Policy Manager, Axeda Enterprise, Axeda
Access, Axeda Software Management, Axeda Service, Axeda ServiceLink, and Firewall-Friendly are trademarks and Maximum Results and
Maximum Support are servicemarks of Axeda Corporation.
Data Domain, EMC, PowerPath, SRDF, and Symmetrix are registered trademarks of EMC Corporation.
GoldenGate is a trademark of Oracle.
Hewlett-Packard and HP are registered trademarks of Hewlett-Packard Company.
Intel, Pentium, and XEON are registered trademarks of Intel Corporation.
IBM, CICS, RACF, Tivoli, and z/OS are registered trademarks of International Business Machines Corporation.
Linux is a registered trademark of Linus Torvalds.
LSI is a registered trademark of LSI Corporation.
Microsoft, Active Directory, Windows, Windows NT, and Windows Server are registered trademarks of Microsoft Corporation in the United
States and other countries.
NetVault is a trademark or registered trademark of Quest Software, Inc. in the United States and/or other countries.
Novell and SUSE are registered trademarks of Novell, Inc., in the United States and other countries.
Oracle, Java, and Solaris are registered trademarks of Oracle and/or its affiliates.
QLogic and SANbox are trademarks or registered trademarks of QLogic Corporation.
SAS and SAS/C are trademarks or registered trademarks of SAS Institute Inc.
SPARC is a registered trademark of SPARC International, Inc.
Symantec, NetBackup, and VERITAS are trademarks or registered trademarks of Symantec Corporation or its affiliates in the United States
and other countries.
Unicode is a registered trademark of Unicode, Inc. in the United States and other countries.
UNIX is a registered trademark of The Open Group in the United States and other countries.
Other product and company names mentioned herein may be the trademarks of their respective owners.
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROVIDED ON AN "AS-IS" BASIS, WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR
NON-INFRINGEMENT. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO THE ABOVE EXCLUSION
MAY NOT APPLY TO YOU. IN NO EVENT WILL TERADATA CORPORATION BE LIABLE FOR ANY INDIRECT, DIRECT, SPECIAL, INCIDENTAL,
OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS OR LOST SAVINGS, EVEN IF EXPRESSLY ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.
The information contained in this document may contain references or cross-references to features, functions, products, or services that are
not announced or available in your country. Such references do not imply that Teradata Corporation intends to announce such features,
functions, products, or services in your country. Please consult your local Teradata Corporation representative for those features, functions,
products, or services available in your country.
Information contained in this document may contain technical inaccuracies or typographical errors. Information may be changed or updated
without notice. Teradata Corporation may also make improvements or changes in the products or services described in this information at any
time without notice.
To maintain the quality of our products and services, we would like your comments on the accuracy, clarity, organization, and value of this
document. Please email: [email protected].
Any comments or materials (collectively referred to as "Feedback") sent to Teradata Corporation will be deemed non-confidential. Teradata
Corporation will have no obligation of any kind with respect to Feedback and will be free to use, reproduce, disclose, exhibit, display, transform,
create derivative works of, and distribute the Feedback and derivative works thereof without limitation on a royalty-free basis. Further, Teradata
Corporation will be free to use any ideas, concepts, know-how, or techniques contained in such Feedback for any purpose whatsoever, including
developing, manufacturing, or marketing products or services incorporating Feedback.
Copyright © 1999-2012 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
Go to http://www.info.teradata.com
2
Under Online Publications, click General Search.
3
Type 3119 in the Publication Product ID box.
4
Under Sort By, select Date.
Teradata Parallel Transporter Operator Programmer Guide
3
Preface
Prerequisites
5
Click Search.
6
Open the version of the Teradata Tools and Utilities ##.# Supported Platforms and Product
Versions spreadsheet associated with this release.
The spreadsheet includes supported Teradata Database versions, platforms, and product
release numbers.
Prerequisites
The following prerequisite knowledge is required for this product:
•
Computer technology and terminology
•
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
Description
June 2012
14.00
Changed instances of channel-attached to mainframe-attached.
November 2011
14.00
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.
4
Teradata Parallel Transporter Operator Programmer Guide
Preface
Additional Information
Type of Information
Description
Source
Release overview
Use the Release Definition for the following
information:
1 Go to http://www.info.teradata.com/.
• 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
3 Type 2029 in the Publication Product ID box.
Late information
Teradata Parallel Transporter Operator Programmer Guide
2 Under Online Publications, click General Search
4 Click Search.
5 Select the appropriate Release Definition from
the search results.
5
Preface
Additional Information
Type of Information
Description
Source
Additional product
information
Use the Teradata Information Products web
site to view or download specific manuals
that supply related or additional
information to this manual.
1 Go to http://www.info.teradata.com/.
2 Under the Online Publications subcategory,
Browse by Category, click Data Warehousing.
3 Do one of the following:
• For a list of Teradata Tools and Utilities
documents, click Teradata Tools and Utilities,
and then select an item under Releases or
Products.
• Select a link to any of the data warehousing
publications categories listed.
Specific books related to Teradata PT are as follows:
• Teradata Tools and Utilities Access Module
Programmer Guide
B035-2424
• Teradata Tools and Utilities Access Module
Reference
B035-2425
• Teradata Parallel Transporter Application
Programming Interface Programmer Guide
B035-2516
• Teradata Parallel Transporter Operator
Programmer Guide
B035-2435
• Teradata Parallel Transporter Quick Start Guidee
B035-2501
• Teradata Parallel Transporter Reference
B035-2436
• Teradata Parallel Transporter User Guide
B035-2445
• Teradata Tools and Utilities for IBM z/OS
Installation Guide
B035-3128
• Teradata Tools and Utilities Installation Guide for
Microsoft Windows
B035-2407
• Teradata Tools and Utilities for Red Hat
Enterprise Linux Installation Guide
B035-3121
• Teradata Tools and Utilities for SUSE Linux
Installation Guide
B035-3122
• Teradata Tools and Utilities for s390x Linux
Installation Guide
B035-3123
• Teradata Tools and Utilities for HP-UX
Installation Guide
B025-3124
6
Teradata Parallel Transporter Operator Programmer Guide
Preface
Additional Information
Type of Information
Description
Source
• Teradata Tools and Utilities for IBM AIX
Installation Guide
B035-3125
• Teradata Tools and Utilities for Oracle Solaris on
AMD Opteron Systems Installation Guide
B035-3126
• Teradata Tools and Utilities for Oracle Solaris on
SPARC Systems Installation Guide
B035-3127
CD-ROM images
Access a link to a downloadable CD-ROM
image of all customer documentation for
this release. Customers are authorized to
create CD-ROMs for their use from this
image
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
Use the Teradata Information Products web
site to order printed versions of manuals.
1 Go to http://www.info.teradata.com/.
2 Under Print & CD Publications, click How to
Order.
3 Follow the ordering instructions.
General information
about Teradata
The Teradata home page provides links to
numerous sources of information about
Teradata. Links include:
• Go to Teradata.com/t/resources.
• Select a link.
• Executive reports, case studies of
customer experiences with Teradata,
and thought leadership
• Technical information, solutions, and
expert advice
• Press releases, mentions and media
resources
Teradata Parallel Transporter Operator Programmer Guide
7
Preface
Additional Information
8
Teradata Parallel Transporter Operator Programmer Guide
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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33
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
Teradata Parallel Transporter Operator Programmer Guide
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
Teradata Parallel Transporter Operator Programmer Guide
11
Table of Contents
12
Teradata Parallel Transporter Operator Programmer Guide
List of Figures
Figure 1: Teradata PT Infrastructure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Figure 2: Parallel Plan Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Figure 3: Operator Object Class Hierarchy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Teradata Parallel Transporter Operator Programmer Guide
13
List of Figures
14
Teradata Parallel Transporter Operator Programmer Guide
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
Teradata Parallel Transporter Operator Programmer Guide
15
List of Tables
16
Teradata Parallel Transporter Operator Programmer Guide
CHAPTER 1
Introduction
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 storage—data 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
Teradata Parallel Transporter Operator Programmer Guide
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
Parses the statements in the Teradata PT job script.
2
Initializes its internal components.
3
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
Coordinates checkpoint and restart processing.
5
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
Data
Source/
Destination
Files,
Devices,
and
Databases
Teradata
Database
Teradata Parallel Transporter Processor
Teradata Parallel Transporter Operator Interface
INMOD
Routines
INMOD
Adapter
Operator
Cleanse/Filter/
Condense
Operators
OUTMOD
Routines
OUTMOD
Adapter
Operator
Consumer
Operators
Access
Modules
Data
Connector
Operator
Producer
Operators
2435C001
18
Teradata Parallel Transporter Operator Programmer Guide
Chapter 1: Introduction
Infrastructure
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 interface—there 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.
Teradata Parallel Transporter Operator Programmer Guide
19
Chapter 1: Introduction
Infrastructure
Table 1: Operator Interface Functions
User-Provided Functions
Service Functions
Initiate
Terminate
Execute
Checkpoint
Restart
Event
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
Teradata Parallel Transporter Operator Programmer Guide
Chapter 1: Introduction
Infrastructure
Table 2: Metadata Use
Metadata Type
Purpose
Attributes of data sources and targets
Determines the fastest access path for the
Parallel Execution Plan
Table and column definitions
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)
Teradata Parallel Transporter Operator Programmer Guide
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
Uses the Teradata PT metadata to establish the data streams between operators
2
Validates the user’s access privileges for the data source and destination objects
3
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
Teradata Parallel Transporter Operator Programmer Guide
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
Operator
Operator
Operator
Interface
Interface
Interface
Interface
Stand-Alone
Consumer
Filter
Producer
Operator
Operator
Operator
Operator
DB
DB
CLI
DB
CLI
Legend
Teradata
Database
Function Call
Data Stream
Teradata Parallel
Channels/
Transport Message
Gateways
2435E002
Teradata Parallel Transporter Operator Programmer Guide
23
Chapter 1: Introduction
Parallel Execution Plan
24
Teradata Parallel Transporter Operator Programmer Guide
CHAPTER 2
Customized Operators
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
Teradata Parallel Transporter Operator Programmer Guide
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
Producer
Class
Projector
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
Description
Access Class
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.
26
Consumer Class
Accepts data from other operators and stores it in an external data
store such as a file or a database table.
Filter Class
Filters and cleanses the input data stream, producing a specified
output data stream.
Teradata Parallel Transporter Operator Programmer Guide
Chapter 2: Customized Operators
Multiphase Coordination Protocol
Table 3: Object Class Descriptions (continued)
Operator Object Class
Description
Producer Class
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
Function
PXSTC_SamePhase
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.
Teradata Parallel Transporter Operator Programmer Guide
27
Chapter 2: Customized Operators
Multiphase Coordination Protocol
Table 4: Function Return Codes (continued)
Return Code
Function
PXSTC_NextPhase
The method should be invoked again for additional processing, but in
the next phase.
PXSTC_EndMethod
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
Phase Master Operator Object
Slave 1 Operator Object
Slave 2 Operator Object
Initiate
1
Allocate global variables
Create/connect a
Teradata SQL session
Create/connect a
Teradata SQL session
Create/connect a Teradata
SQL session for obtaining
the LSN parcel
Return NextPhase
Return NextPhase
Extract LSN from the LSN
parcel
Save LSN as a global
variable
Create/connect a Teradata
SQL session
28
Teradata Parallel Transporter Operator Programmer Guide
Chapter 2: Customized Operators
Multiphase Coordination Protocol
Table 5: Using Multiphase Coordination Protocol (continued)
Method
Phase Master Operator Object
Slave 1 Operator Object
Slave 2 Operator Object
Create/connect Load
sessions using the LSN
global variable
Create/connect Load
sessions using the LSN
global variable
Create/connect Load
sessions using the LSN
global variable
Return NextPhase
Return EndMethod
Return EndMethod
Read record from a data
source
Read a record from a
data source
Read a record from a
data source
IF end-of-file, return
NextPhase
IF end-of-file, return
EndMethod
IF end-of-file, return
EndMethod
ELSE return SamePhase
ELSE return SamePhase
ELSE return SamePhase
Return NextPhase
2
3
Issue Begin Loading
Return EndMethod
Execute
1
2
Issue End Loading (if
specified by the user)
Return EndMethod
Checkpoint 1
2
Write statistics to Global
Variable
Write statistics to Global Write statistics to
Variable
Global Variable
Return NextPhase
Return EndMethod
Return EndMethod
Process checkpoint
records
Process checkpoint
records
Process checkpoint
records
Return NextPhase
Return EndMethod
Return EndMethod
Disconnect Load sessions
Disconnect Load
sessions
Disconnect Load
Sessions
Return NextPhase
Return NextPhase
Return NextPhase
Disconnect Teradata SQL
session
Disconnect Teradata
SQL session
Disconnect Teradata
SQL session
Deallocate Global
Variables
Return EndMethod
Return EndMethod
Write checkpoint records
to the restart log file
Return EndMethod
Restart
1
2
Write a restart record to
the restart log file to
indicate end-of-restart
Return EndMethod
Terminate
1
2
Return EndMethod
Teradata Parallel Transporter Operator Programmer Guide
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:
30
•
PX_Initiate
•
PX_Execute
Teradata Parallel Transporter Operator Programmer Guide
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);
Teradata Parallel Transporter Operator Programmer Guide
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
Process
Initiate
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.
32
Teradata Parallel Transporter Operator Programmer Guide
Chapter 2: Customized Operators
Design Guidelines
Designing a Filter Operator
Use the following process guidelines for implementing the Initiate, Execute, and Terminate
functions for a filter operator:
Function
Process
Initiate
None.
Execute
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
Process
Initiate
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
Teradata Parallel Transporter Operator Programmer Guide
33
Chapter 2: Customized Operators
Design Guidelines
Table 6: Processing the Apply Statement (continued)
Function
Process
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.
Terminate
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 Teradata Parallel
Transporter Reference.
34
Teradata Parallel Transporter Operator Programmer Guide
CHAPTER 3
Operator Interface Functions
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();
Teradata Parallel Transporter Operator Programmer Guide
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
Use
Initiate
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:
•
•
•
•
•
•
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
Checkpoint
Writing checkpoint records to a restart log table that the operator can use to restart
in case of a hardware or software system failure.
Restart
Restarting operators using the most recently written checkpoint records.
Event
Performing event processing or notification based on caller-specified event.
Terminate
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
Teradata Parallel Transporter Operator Programmer Guide
Chapter 3: Operator Interface Functions
Data Types
Table 7: Teradata PT Operator Data Types
Data Type
Definition
PX_Addr
The address of a memory location.
PX_AttributeCode
An integer that represents the name of an object attribute.
PX_AttributeName
Pointer to a null-terminated character string that provides the name of an
object attribute.
PX_AttributeValue
Pointer to an area for storage of an attribute value.
PX_ByteOffset
Integer that specifies the displacement in bytes from the first byte of a row.
PX_Code
Integer code that represents either:
• System code
• System reason code
PX_ColumnCount
Integer that specifies the column count.
PX_ColumnHandle
Integer that identifies the instance of a column.
PX_ColumnName
Pointer to a null-terminated character string that provides a column name.
PX_ColumnSchemaHa
ndle
Integer that represents the instance of the column schema.
PX_ColumnSchemaList Array of column schema handles.
PX_Count
Integer that specifies the count of some object.
PX_DataAddr
Address of the data.
PX_DataType
Integer code that represents the following defined data types of a column:
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
Teradata Parallel Transporter Operator Programmer Guide
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
Chapter 3: Operator Interface Functions
Data Types
Table 7: Teradata PT Operator Data Types (continued)
Data Type
Definition
PX_ErrorProc
Function pointer that specifies an error exit function.
PX_ErrorText
Pointer to a character string that provides the error message.
PX_FilterHandle
Integer that identifies the instance of a filter.
PX_GlobalHandle
Integer that identifies the instance of a global.
PX_Indicator
Pointer to the array of indicator bytes specifying whether or not the
corresponding column value is NULL.
PX_Length
Integer that specifies the size, in bytes, of an object.
PX_LogHandle
Integer that specifies a log stream definition. The structure is allocated by
the Logger API.
PX_LongInt
Four-byte signed integer.
PX_Name
Pointer to a null-terminated character string that provides the name of an
object.
PX_Number
Integer that specifies the number (instance) of an object.
PX_OperatorHandle
Integer code that identifies the instance of an operator.
PX_Precision
Integer that specifies a precision value (number of digits) for a numeric
data type.
PX_Scale
Integer that specifies a scale value (number of digits to the right of the
decimal point) for a numeric data type.
PX_SchemaType
Integer code that identifies one of the following schema types:
• PX_InputSchema
• PX_InputOutputSchema
• PX_OutputSchema
PX_TableSchemaHandl
e
Integer code that identifies the instance of the table schema.
PX_TableSchemaList
Array of table schema handles.
PX_TruthValue
Integer that specifies one of the following values:
• PX_True
• PX_False
38
Teradata Parallel Transporter Operator Programmer Guide
Chapter 3: Operator Interface Functions
Data Types
Table 7: Teradata PT Operator Data Types (continued)
Data Type
Definition
PXSTC_Code
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.
Teradata Parallel Transporter Operator Programmer Guide
39
Chapter 3: Operator Interface Functions
Data Types
Table 7: Teradata PT Operator Data Types (continued)
40
Data Type
Definition
(PXSTC_Code,
continued)
• 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.
Teradata Parallel Transporter Operator Programmer Guide
Chapter 3: Operator Interface Functions
Service Functions
Table 7: Teradata PT Operator Data Types (continued)
Data Type
Definition
PXSTC_Code
(continued)
• 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
Use
Allocate Storage
Free Storage
Allocating and freeing Teradata PT storage for your operator.
Create Global Variable
Read Global Variable
Update Global Variable
Delete Global Variable
Creating, accessing, and deleting global variables.
Put Attribute
Get Attribute
Storing and retrieving attribute values.
Put Row
Get Row
Storing and retrieving data rows.
Put Column Value
Get Column Value
Storing and retrieving column values.
Write Checkpoint Record
Read Checkpoint Record
Storing and retrieving checkpoint records.
Teradata Parallel Transporter Operator Programmer Guide
41
Chapter 3: Operator Interface Functions
Service Functions
Table 8: Service Functions (continued)
Function
Use
Create Column Schema
Get Column Schema
Creating and accessing column schemas.
Begin Table Schema
Definition
Finalize Table Schema
Definition
Creating table schemas.
Get Table Schema List
Get Column Schema List
Retrieving lists of table and column schemas.
Set Error Message
Creating error messages.
Initiate Log Stream
Write to Log Stream
Terminate Log Stream
Initiating, writing, and terminating a log stream function.
Define Error Handler
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
Teradata Parallel Transporter Operator Programmer Guide
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
Function
Specification
operator
input
Instance of the operator for which the storage is to be allocated.
storageSize
input
Amount of storage you want to allocate to the named operator.
storageAddr
output
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
Signifies
PXSTC_InvalidArgument
One or more bad input arguments.
PXSTC_BadHandle
An undefined object handle.
PXSTC_NotEnough
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
Usage Note
Status
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.
Teradata Parallel Transporter Operator Programmer Guide
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
Function
Specification
operator
input
Instance of the operator for which the table schema is being
defined.
schemaType
input
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
Signifies
PXSTC_InvalidArgument
One or more bad input arguments.
PXSTC_BadHandle
An undefined object handle.
PXSTC_Success
Successful initiation of the table schema definition.
Usage Notes
Consider the following when using the Begin Table Schema Definition function.
44
Teradata Parallel Transporter Operator Programmer Guide
Chapter 3: Operator Interface Functions
Begin Table Schema Definition
Topic
Usage Note
Status
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.
Teradata Parallel Transporter Operator Programmer Guide
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
Function
Specification
operator
input
Operator handles associated with the Checkpoint function.
phase
input
Current processing phase number
Return Codes
The following Checkpoint function status codes are defined by the Teradata PT operator
interface:
Status Code
Signifies
PXSTC_EndMethod
Successful checkpoint processing.
This status condition indicates that the checkpoint record was successfully
written to the restart log by this function.
PXSTC_NextPhase
Proceed with the next processing phase.
PXSTC_SamePhase
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.
46
Topic
Usage Note
Description
Use the Checkpoint function to record the checkpoint information
identified by the operator parameter. See also the Restart function.
Teradata Parallel Transporter Operator Programmer Guide
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
Function
Specification
columnHandle
output
Column handle for which the schema is being created.
columnName
input
Column-name attribute of the column schema.
dataLength
input
Column length for both numeric and nonnumeric data types.
dataType
input
Data type attribute of the column schema.
nullIndicator
input
Truth value indicating whether or not the column value can be
NULL.
offset
input
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
input
Precision value (number of digits) for a numeric data type.
The precision specification can range from 1 to 38.
scale
input
Scale value (number of digits to the right of the decimal point)
for a numeric data type.
tableSchemaHandle
input
Data schema handle by which the column schema will be created.
Return Codes
The following Create Column Schema function status codes are defined by the Teradata PT
operator interface:
Teradata Parallel Transporter Operator Programmer Guide
47
Chapter 3: Operator Interface Functions
Create Column Schema
Status Code
Signifies
PXSTC_InvalidArgument
One or more bad input arguments.
PXSTC_BadHandle
An undefined data schema handle.
PXSTC_Success
Successful creation of the column schema definition.
Usage Notes
Consider the following when using the Create Column Schema function.
Topic
Usage Notes
Data Type Specifications
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
48
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.
Teradata Parallel Transporter Operator Programmer Guide
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
Function
Specification
operator
input
Instance of the operator handle for which the global variable is being
created.
varCount
input
Maximum number items to be created for the global variable.
varName
input
Name of the global variable.
varSize
input
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
Signifies
PXSTC_InvalidArgument
One or more bad input arguments.
PXSTC_BadHandle
An undefined object handle.
PXSTC_NotEnough
The global variable size is too large
PXSTC_Success
Successful creation of the global variable.
Usage Notes
Consider the following when using the Create Global Variable function.
Topic
Usage Notes
Status
If the function status is PXSTC_Success, all items of the global variable
were created successfully.
Teradata Parallel Transporter Operator Programmer Guide
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
Function
Specification
operator
input
Instance of the operator handle for which the global variable is being
deleted.
varName
input
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
Signifies
PXSTC_InvalidArgument
One or more bad input arguments.
PXSTC_BadHandle
An undefined object handle.
PXSTC_Success
Successful deletion of the global variable.
Usage Notes
Consider the following when using the Delete Global Variable function.
50
Topic
Usage Notes
Status
If the function status is PXSTC_Success, all items of the global variable
were deleted successfully. See also the Create Global Variable function.
Teradata Parallel Transporter Operator Programmer Guide
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
Function
Specification
loghandle
input
The handle to the log stream. The structure is allocated by the
Logger API.
errorproc
input
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
Signifies
void*
The address of the error procedure previously used.
Usage Notes
Consider the following when using the Define Error Handler function.
Topic
Usage Notes
See Also
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);
Teradata Parallel Transporter Operator Programmer Guide
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
Function
Specification
operator
input
Operator handle that is associated with the Event function.
phase
input
Current processing phase number.
Return Codes
The following Event function status codes are defined by the Teradata PT operator interface:
Status Code
Signifies
PXSTC_EndMethod
Successful execution of the operator.
This status condition indicates that the event was successfully
processed by this function.
PXSTC_NextPhase
Proceed with the next processing phase.
PXSTC_SamePhase
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
Usage Notes
Description
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
Teradata Parallel Transporter Operator Programmer Guide
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
Function
Specification
operator
input
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
Signifies
PXSTC_EndMethod
Successful execution of the operator.
PXSTC_EndOfData
End of data
PXSTC_NextPhase
Proceed with the next processing phase.
PXSTC_SamePhase
Continue with the current processing phase.
Usage Notes
Define additional Execute function status codes as required to support your operator.
Topic
Usage Notes
Description
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
Teradata Parallel Transporter Operator Programmer Guide
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
Function
Specification
tableSchemaHandle
input
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
Signifies
PXSTC_Conflict
Mismatching type of operations, data, or protocols.
PXSTC_CountError
The specified number of objects does not match some predefined value.
PXSTC_LengthError
The length of the data to be stored does not match the length of the
internal buffer.
PXSTC_BadHandle
An undefined table schema handle.
PXSTC_SchemaError
An error was detected in the data schema.
PXSTC_Success
Successful creation of the table schema.
Usage Notes
Consider the following when using the Finalize Table Schema Definition function.
54
Topic
Usage Notes
Description
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.
Status
If the function status is PXSTC_Success, the defined table schema can be
used by Teradata PT operators. See also Begin Table Schema Definition.
Teradata Parallel Transporter Operator Programmer Guide
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
Function
Specification
operator
input
Operator handle for which the storage is to be freed.
storageAddr
input
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
Signifies
PXSTC_InvalidArgument
One or more bad input arguments.
PXSTC_BadHandle
An undefined object handle.
PXSTC_Success
Successful access to the object attribute.
Usage Notes
Consider the following when defining the Free Storage function.
Topic
Usage Notes
Status
If the function status is PXSTC_Success, the storage at the location
indicated by the storageAddr pointer was successfully freed. See also
Allocate Storage.
Teradata Parallel Transporter Operator Programmer Guide
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
Function
Specification
attributeName
input
Name of the object attribute.
attributeValue
output
Retrieved value of the specified attribute.
operator
input
Operator handle from which the attribute is to be
retrieved.
valueLength
output
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
Signifies
PXSTC_InvalidArgument
One or more bad input arguments.
PXSTC_BadHandle
An undefined object handle.
PXSTC_NotFound
The specified attribute was not found in the specified object.
PXSTC_Success
Successful access to the specified attribute.
Usage Notes
Consider the following when defining the Get Attribute function.
56
Topic
Usage Notes
System Attributes
Table 9 on page 57 lists the Teradata PT system attributes that you can
retrieve with the Get Attributes function. See also Put Attribute.
Teradata Parallel Transporter Operator Programmer Guide
Chapter 3: Operator Interface Functions
Get Attribute
Topic
Usage Notes
Status
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
Data Type
Data
Length
(in bytes)
SYSTEM_Code
PX_Code
4
System ABEND code
SYSTEM_FilterHandle
PX_FilterHandle
4
Handle of the filter object
SYSTEM_GlobalHandle
PX_GlobalHandle
4
Handle of the global anchor
SYSTEM_InstanceNumber PX_Number
4
Instance number of the operator,
starting from 1
SYSTEM_MaxInstances
PX_Count
4
Maximum number of instances
that can be created for the operator
SYSTEM_OperatorName
PX_Addr
4
Address of string containing the
operator name
SYSTEM_OperatorType
PX_Number
4
Code indicating type of operator:
producer=1, consumer=2, filter=3
SYSTEM_PhaseNumber
PX_Count
4
Current processing phase number
SYSTEM_UserAreaAddr
PX_Addr
4
Address of the user area
Teradata Parallel Transporter Operator Programmer Guide
Description
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
Function
Specification
columnHandle
output
Column handle from which the column schema is to be obtained.
columnName
output
Column-name attribute of the column schema.
dataLength
output
Column length for both numeric and nonnumeric data types.
dataType
output
Data type attribute of the column schema.
nullIndicator
output
Truth value indicating whether or not the column value can be
NULL.
offset
output
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
Teradata Parallel Transporter Operator Programmer Guide
Chapter 3: Operator Interface Functions
Get Column Schema
Status Code
Signifies
PXSTC_InvalidArgument
One or more bad input arguments.
PXSTC_BadHandle
An undefined column schema handle.
PXSTC_Success
Successful retrieval of the column schema.
Usage Notes
Consider the following when defining thee Get Column Schema function.
Topic
Usage Notes
Status
If the function status is PXSTC_Success the values of the output
parameters are returned. See also Create Column Schema.
Teradata Parallel Transporter Operator Programmer Guide
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
Function
Specification
columnSchemaCount
output
Number of column schemas in the list.
columnSchemaList
output
Pointer to the location of the retrieved column schema list.
tableSchemaHandle
input
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
Signifies
PXSTC_InvalidArgument
One or more bad input arguments.
PXSTC_BadHandle
An undefined data schema handle.
PXSTC_NotFound
The specified column schema list was not found in the specified
object.
PXSTC_Success
Successful retrieval of the list of column handles.
Usage Notes
Consider the following when defining the Get Column Schema List function.
60
Topic
Usage Notes
Status
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.
Teradata Parallel Transporter Operator Programmer Guide
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
Function
Specification
columnHandle
input
Column handle from which the column value is to be retrieved.
dataAddr
output
Pointer to the address of the column value.
dataLength
output
Pointer to the length of the column value.
nullIndicator
output
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
Signifies
PXSTC_InvalidArgument
One or more bad input arguments.
PXSTC_BadHandle
An undefined column handle.
PXSTC_Success
Successful projection of data value to the column.
Usage Notes
Consider the following when defining the Get Column Value function.
Teradata Parallel Transporter Operator Programmer Guide
61
Chapter 3: Operator Interface Functions
Get Column Value
Topic
Usage Notes
Status
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
Teradata Parallel Transporter Operator Programmer Guide
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
Function
Specification
columnCount
output
Pointer to the number of columns associated with the data row.
lengths
output
Pointer to the array of integers representing the length of the
corresponding column value.
nullIndicator
output
Pointer to the array of indicator bytes specifying whether or not
the corresponding column value is NULL.
offsets
output
Pointer to the array of integers representing the corresponding
column positions in terms of the number of bytes into the data
row.
rowAddr
output
Pointer to the address of the data row.
rowLength
output
Pointer to the length of the data row.
tableSchemaHandle
input
Table schema handle by which the data row is to be obtained.
Return Codes
The following Get Row function status codes are defined by the Teradata PT operator
interface:
Status Code
Signifies
PXSTC_BadHandle
An undefined data schema handle.
PXSTC_Success
Successful retrieval of the data row.
PXSTC_EndOfData
End of data.
Teradata Parallel Transporter Operator Programmer Guide
63
Chapter 3: Operator Interface Functions
Get Row
Usage Notes
Consider the following when defining the Get Row function.
Topic
Usage Notes
Return Data Format
Data rows returned by the Get Row function are always prefixed with
NULL indicator bytes.
Status
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
64
• Begin Table Schema Definition function
• Finalize Table Schema Definition function
• Put Row function
Teradata Parallel Transporter Operator Programmer Guide
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
Function
Specification
operator
input
Operator handle from which the list of table schemas is to be
retrieved.
schemaType
input
Schema type, which can be either:
• PX_InputSchema
• PX_OutputSchema
• PX_InputOutputSchema
tableSchemaList
output
Pointer to the address of the list of table schemas.
tableSchemaCount
output
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
Signifies
PXSTC_InvalidArgument
One or more bad input arguments.
PXSTC_BadHandle
An undefined operator handle.
PXSTC_NotFound
The specified table list was not found in the specified object.
PXSTC_Success
Successful fetching of the table schema list.
Usage Notes
Consider the following when defining the Get Table Schema List function.
Teradata Parallel Transporter Operator Programmer Guide
65
Chapter 3: Operator Interface Functions
Get Table Schema List
Topic
Usage Notes
Status
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
66
• Begin Table Schema Definition function
• Finalize Table Schema Definition function
Teradata Parallel Transporter Operator Programmer Guide
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
Function
Specification
operator
input
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
Signifies
PXSTC_EndMethod
Successful initialization of the operator.
PXSTC_NextPhase
Proceed with the next processing phase.
PXSTC_SamePhase
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
Usage Notes
Status
If the function status is PXSTC_EndMethod, the processing
environment was successfully established by this function. See also the
Terminate function.
Teradata Parallel Transporter Operator Programmer Guide
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
Function
Specification
componentname
input
Name of the component.
instancenumber
input
Number of the operator instance.
loghandle
output
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
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.
oprhandle
input
Handle to the operator.
outputlogreport
input
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:
68
Status Code
Signifies
PXSTC_Success
The call succeeded.
Teradata Parallel Transporter Operator Programmer Guide
Chapter 3: Operator Interface Functions
Initiate Log Stream
Status Code
Signifies
PXSTC_LogInsuff
MemError
Memory allocation failure.
PXSTC_CatalogError
No message catalog specified.
PXSTC_Log
CommunicationError
Error from socket communication with the Node Logger.
PXSTC_LogPassword
The Logger API has supplied a wrong password for the logger (indicates
an attempt to access the logger without using the supplied API).
PXSTC_InvalidData
Type
The type of some of the parameters is unknown to the Logger API.
PXSTC_NoMessage
Catalog
The requested message catalog is not present.
PXSTC_Unknown
Error
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
Usage Note
Status
If the function status is PXSTC_Success, the message catalog for the
operator was successfully initialized by this function
See Also
• 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);
Teradata Parallel Transporter Operator Programmer Guide
69
Chapter 3: Operator Interface Functions
Initiate Log Stream
.
/* 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
Teradata Parallel Transporter Operator Programmer Guide
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
Function
Specification
attributeName
input
Name of the operator attribute to be assigned the value.
attributeValue
input
Address of the location containing the value to be assigned to the
operator attribute.
operator
input
Operator handle to which the attribute value is to be assigned.
valueLength
input
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
Signifies
PXSTC_InvalidArgument
One or more bad input arguments.
PXSTC_BadHandle
An undefined object handle.
PXSTC_NotFound
The specified attribute was not found in the specified object.
PXSTC_Success
Successful access to the specified attribute.
Usage Notes
Consider the following when defining the Put Attribute function.
Topic
Usage Notes
System Attributes
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.
Teradata Parallel Transporter Operator Programmer Guide
71
Chapter 3: Operator Interface Functions
Put Attribute
Topic
Usage Notes
Status
If the function status is PXSTC_Success the value was successfully
assigned to the operator attribute.
Table 10: Put-Accessible System Attributes
72
Attribute Name
Data Type
Data
Length
(in bytes)
SYSTEM_Code
PX_Code
4
System ABEND code
SYSTEM_UserAreaAddr
PX_Addr
4
Address of the user area
Description
Teradata Parallel Transporter Operator Programmer Guide
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
Function
Specification
columnHandle
input
Column handle where the value is to be stored.
dataAddr
input
The address of the value.
dataLength
input
Length of the value.
nullIndicator
input
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
Signifies
PXSTC_InvalidArgument
One or more bad input arguments.
PXSTC_BadHandle
An undefined column handle.
PXSTC_Success
Successful storage of the specified column value.
Usage Notes
Consider the following when defining the Put Column Value function.
Topic
Usage Notes
Status
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.
Teradata Parallel Transporter Operator Programmer Guide
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
Function
Specification
columnCount
input
Number of columns associated with the data row.
lengths
output
Pointer to the array of integers representing the length of the
corresponding column value.
nullIndicator
output
Pointer to the array of indicator bytes specifying whether or not
the corresponding column value is NULL.
offsets
output
Pointer to the array of integers representing the corresponding
column positions in terms of the number of bytes into the data
row.
rowAddr
input
Pointer to the address of the data row to be stored.
rowLength
input
Pointer to the length of the data row.
tableSchemaHandle
input
Table schema handle by which the data row is to be stored.
Return Codes
The following Put Row function status codes are defined by the Teradata PT operator
interface:
74
Status Code
Signifies
PXSTC_InvalidArgument
One or more bad input arguments.
PXSTC_BadHandle
An undefined table schema handle.
PXSTC_LengthError
Length of data to be stored does not match length of internal buffer.
PXSTC_Success
Successful storage of the data row.
Teradata Parallel Transporter Operator Programmer Guide
Chapter 3: Operator Interface Functions
Put Row
Usage Notes
Consider the following when defining the Put Row function.
Topic
Usage Notes
Indicator Mode Data
If the data row is in indicator mode, then the columnCount parameter
must be zero and the following parameters must all be NULL:
•
•
•
•
nullIndicators
offsets
lengths
Teradata Call-Level Interface Version2 for Mainframe-Attached
Systems
• Teradata Call-Level Interface Version2 for Network-Attached Systems
Status
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.
See Also
• Begin Table Schema Definition function
• Finalize Table Schema Definition function
• Get Row function
Teradata Parallel Transporter Operator Programmer Guide
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
Function
Specification
dataAddr
output
Pointer to the address of the checkpoint record.
dataLength
output
Pointer to the length of the checkpoint record.
operator
input
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
Signifies
PXSTC_InvalidArgument
One or more bad input arguments.
PXSTC_BadHandle
An undefined operator handle.
PXSTC_Success
Successful read of the checkpoint record.
Usage Notes
Consider the following when defining the Read Checkpoint Record function.
76
Topic
Usage Notes
Status
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.
Teradata Parallel Transporter Operator Programmer Guide
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
Function
Specification
itemBufferAddr
output
Pointer to the address of the buffer where the value of the global
variable is stored.
itemBufferSize
output
Pointer to the size of the item buffer.
itemIndex
input
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
input
Operator handle by which the global variable is to be read.
varName
input
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
Signifies
PXSTC_InvalidArgument
One or more bad input arguments.
PXSTC_BadHandle
An undefined object handle.
PXSTC_Success
A successful read access of the global variable.
Usage Notes
Consider the following when defining the Read Global Variable function.
Teradata Parallel Transporter Operator Programmer Guide
77
Chapter 3: Operator Interface Functions
Read Global Variable
Topic
Usage Notes
Status
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
78
• Update Global Variable function
• Create Global Variable function
Teradata Parallel Transporter Operator Programmer Guide
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
Function
Specification
operator
input
Name of the operator handle to be restarted.
phase
input
Current processing phase number
Return Codes
The following Restart function status codes are defined by the Teradata PT operator interface:
Status Code
Signifies
PXSTC_EndMethod
Successful restart of the operator.
PXSTC_NextPhase
Proceed with the next processing phase.
PXSTC_SamePhase
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
Usage Notes
Status
If the function status is PXSTC_EndMethod, the restart operation was
successfully established by this function. See also the Checkpoint
function.
Teradata Parallel Transporter Operator Programmer Guide
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
Function
Specification
message
input
Location of the error message text.
messageLength
input
Length of the error message text.
operator
input
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
Signifies
PXSTC_InvalidArgument
One or more bad input arguments.
PXSTC_BadHandle
An undefined object handle.
PXSTC_Success
Successful setting of the error message.
Usage Notes
Consider the following when defining the Set Error Message function.
Topic
Usage Notes
Status
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
Teradata Parallel Transporter Operator Programmer Guide
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
Function
Specification
operator
input
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
Signifies
PXSTC_EndMethod
Successful termination of the operator.
PXSTC_NextPhase
Proceed with the next processing phase.
PXSTC_SamePhase
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
Usage Notes
Status
If the function status is PXSTC_EndMethod, the processing
environment was successfully terminated by this function. See also
Initiate function.
Teradata Parallel Transporter Operator Programmer Guide
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
Function
Specification
loghandle
input
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
Signifies
PXSTC_Success
The call succeeded.
PXSTC_LogCommunicati
onError
An error occurred from socket communication with the node Logger.
PXSTC_UnknownError
Unknown termination error.
Usage Notes
Consider the following when defining the Terminate Log Stream function.
Topic
Usage Notes
Status
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
Teradata Parallel Transporter Operator Programmer Guide
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
Function
Specification
itemBufferAddr
input
Address of the buffer where the value to be assigned to the global
variable is stored.
itemBufferSize
input
Size of the value in the item buffer.
itemIndex
input
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
input
Operator handle by which the global variable is to be updated.
varName
input
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
Signifies
PXSTC_InvalidArgument
One or more bad input arguments.
PXSTC_BadHandle
An undefined operator handle.
PXSTC_LengthError
The length of the update value does not match the length of the
global variable buffer.
PXSTC_NotEnough
The global variable is too large.
PXSTC_Success
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
84
Topic
Usage Notes
Status
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.
See Also
• Read Global Variable function
• Create Global Variable function
Teradata Parallel Transporter Operator Programmer Guide
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);
where
Parameter
Function
Specification
dataAddr
input
Address of the checkpoint record to be written.
dataLength
input
Length of the checkpoint record.
operator
input
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
Signifies
PXSTC_InvalidArgument
One or more bad input arguments.
PXSTC_BadHandle
An undefined operator handle.
PXSTC_Success
Successful write of the checkpoint record.
Usage Notes
Consider the following when defining the Write Checkpoint Record function.
Topic
Usage Notes
Status
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.
Teradata Parallel Transporter Operator Programmer Guide
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
Function
Specification
destination
input
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
or’ing the values (LOG_DEST_CONS | LOG_DEST_LOG)
loghandle
input
Handle to the log stream (returned from PX_LogInit())
messagecategory
input
Category of the message. The valid message categories are:
•
•
•
•
•
•
messagenumber
input
LOG_DEBUG
LOG_TRACE
LOG_INFO
LOG_WARNING
LOG_FATALERROR
LOG_USERERROR
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
Teradata Parallel Transporter Operator Programmer Guide
Chapter 3: Operator Interface Functions
Write to Log Stream
Parameter
Function
Specification
...
input
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
Signifies
PXSTC_Success
The call succeeded.
PXSTC_Log
CommunicationError
An error occurred from socket communication with the Node
Logger.
PXSTC_LogInsuffMem
Error
A memory allocation failure.
PXSTC_InvalidDataType
The type of some of the parameters is unknown to the Logger API.
PXSTC_NoMessage
Catalog
The requested message catalog is not present.
PXSTC_UnknownError
Unknown error encountered when writing a log record.
Teradata Parallel Transporter Operator Programmer Guide
87
Chapter 3: Operator Interface Functions
Write to Log Stream
Usage Notes
Consider the following when defining the Write to Log Stream function.
Topic
Usage Notes
Status
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 Parallel Transporter Operator Programmer Guide
APPENDIX A
Teradata PT Publications
User documentation for Teradata PT is distributed among the following books.
Teradata PT Publications
Publication
Contents
Teradata Parallel Transporter Quick
Start Guide
B035-2501
Provides getting-started information for using Teradata PT.
Includes Teradata PT job examples for:
Teradata Parallel Transporter User
Guide
B035-2445
Detailed strategies for planning, implementing, and
debugging Teradata PT.
• 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.
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
Teradata Parallel Transporter Operator Programmer Guide
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.
89
Appendix A: Teradata PT Publications
Teradata PT Publications
90
Publication
Contents
Teradata Parallel Transporter
Application Programming Interface
Programmer Guide
B035-2435
Provides information about:
Teradata Parallel Transporter
Operator Programmer Guide
B035-2435
Provides information on developing custom operators,
including all interface functions that allow communication
between the Teradata PT operators and the Teradata PT
infrastructure.
•
•
•
•
Setting up the interface.
Coding.
Error reporting.
Checkpointing and restarting.
Teradata Parallel Transporter Operator Programmer Guide
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
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
Teradata Parallel Transporter Operator Programmer Guide
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
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 34
91
Index
F
Filter Class, operator object subclass 26
filter operators, designing 33
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
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
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
92
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
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
O
objects
classes
description 25
structure 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
control function data types, description 36
Teradata Parallel Transporter Operator Programmer Guide
Index
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
Teradata Parallel Transporter Operator Programmer Guide
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
Initiate Log Stream function 69
93
Index
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
94
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
Allocate Storage function 43
Teradata Parallel Transporter Operator Programmer Guide
Index
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
Teradata Parallel Transporter Operator Programmer Guide
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
function 65
95
Index
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
Teradata Parallel Transporter Operator Programmer Guide