2424

Teradata Tools and Utilities Access Module
Programmer Guide
Release 13.00.00 B035-2424-088A August 2008
The product or products described in this book are licensed products of Teradata Corporation or its affiliates. Teradata, BYNET, DBC/1012, DecisionCast, DecisionFlow, DecisionPoint, Eye logo design, InfoWise, Meta Warehouse, MyCommerce, SeeChain, SeeCommerce, SeeRisk, Teradata Decision Experts, Teradata Source Experts, WebAnalyst, and Youve Never Seen Your Business Like This Before are trademarks or registered trademarks of Teradata Corporation or its affiliates. Adaptec and SCSISelect are trademarks or registered trademarks of Adaptec, Inc. AMD Opteron and Opteron are trademarks of Advanced Micro Devices, Inc. BakBone and NetVault are trademarks or registered trademarks of BakBone Software, Inc. EMC, PowerPath, SRDF, and Symmetrix are registered trademarks of EMC Corporation. GoldenGate is a trademark of GoldenGate Software, Inc. Hewlett-Packard and HP are registered trademarks of Hewlett-Packard Company. Intel, Pentium, and XEON are registered trademarks of Intel Corporation. IBM, CICS, RACF, Tivoli, z/OS, and z/VM are registered trademarks of International Business Machines Corporation. Linux is a registered trademark of Linus Torvalds. LSI and Engenio are registered trademarks of LSI Corporation. Microsoft, Active Directory, Windows, Windows NT, and Windows Server are registered trademarks of Microsoft Corporation in the United States and other countries. Novell and SUSE are registered trademarks of Novell, Inc., in the United States and other countries. QLogic and SANbox trademarks or registered trademarks of QLogic Corporation. SAS and SAS/C are trademarks or registered trademarks of SAS Institute Inc. SPARC is a registered trademarks of SPARC International, Inc. Sun Microsystems, Solaris, Sun, and Sun Java are trademarks or registered trademarks of Sun Microsystems, Inc., in the United States and other countries. Symantec, NetBackup, and VERITAS are trademarks or registered trademarks of Symantec Corporation or its affiliates in the United States and other countries. Unicode is a collective membership mark and a service mark of Unicode, Inc. UNIX is a registered trademark of The Open Group in the United States and other countries. Other product and company names mentioned herein may be the trademarks of their respective owners.
THE INFORMATION CONTAINED IN THIS DOCUMENT IS PROVIDED ON AN AS-IS BASIS, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION OF IMPLIED WARRANTIES, SO THE ABOVE EXCLUSION MAY NOT APPLY TO YOU. IN NO EVENT WILL TERADATA CORPORATION BE LIABLE FOR ANY INDIRECT, DIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS OR LOST SAVINGS, EVEN IF EXPRESSLY ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
The information contained in this document may contain references or cross-references to features, functions, products, or services that are not announced or available in your country. Such references do not imply that Teradata Corporation intends to announce such features, functions, products, or services in your country. Please consult your local Teradata Corporation representative for those features, functions, products, or services available in your country. Information contained in this document may contain technical inaccuracies or typographical errors. Information may be changed or updated without notice. Teradata Corporation may also make improvements or changes in the products or services described in this information at any time without notice. To maintain the quality of our products and services, we would like your comments on the accuracy, clarity, organization, and value of this document. Please e-mail: [email protected] Any comments or materials (collectively referred to as Feedback) sent to Teradata Corporation will be deemed non-confidential. Teradata Corporation will have no obligation of any kind with respect to Feedback and will be free to use, reproduce, disclose, exhibit, display, transform, create derivative works of, and distribute the Feedback and derivative works thereof without limitation on a royalty-free basis. Further, Teradata Corporation will be free to use any ideas, concepts, know-how, or techniques contained in such Feedback for any purpose whatsoever, including developing, manufacturing, or marketing products or services incorporating Feedback. Copyright 1995-2008 by Teradata Corporation. All Rights Reserved.
Preface
Purpose
Teradata Tools and Utilities is a group of products designed to work with Teradata Database. This manual describes the access module component of the Teradata Tools and Utilities infrastructure that links client utilities to external data source/destination storage devices. Explained are the standard software functions and protocols for providing a block-level I/O interface between the external devices and the client utility Data Connector Application Program Interface (API).
Audience
This book is intended for use by: Systems programmers Application programmers
Supported Releases
This book supports the following releases: Teradata Database 13.00.00 Teradata Tools and Utilities 13.00.00 Data Connector 13.00.00
For the most current information about supported releases, do the following:
1 2 3 4 5 6
Go to www.info.teradata.com. Under Online Publications, click General Search. Type 3119 in the Publication Product ID box. Under Sort By, select Date. Click Search. Open the version of the Teradata Tools and Utilities xx.xx.xx Supported Versions spreadsheet associated with this release.
The spreadsheet includes supported Teradata Database versions, platforms, and product release numbers.
Teradata Tools and Utilities Access Module Programmer Guide
Preface Prerequisites
Prerequisites
This guide is a reference document. Prerequisite knowledge required to use this guide includes familiarity with computer I/O technology, relational database management systems, and utilities that load and retrieve data.
Changes to This Book

The following changes were made to this guide to support the current release.
Date/Release August 2008 Teradata Tools and Utilities 13.00.00 Description Updated version numbers Updated header file examples to reflect that the standalone DataConnector (PIOM) and the Teradata PT DataConnector Operator now use the same header file. See Chapter 4: Header File Examples Updated the sample program and makefile example. See Appendix A: Sample Program and Makefile.
Additional Information
Additional information that supports this product and Teradata Tools and Utilities is available at the Web sites listed in the table that follows. In the table, mmyx represents the publication date of a manual, where mm is the month, y is the last digit of the year, and x is an internal publication code. Match the mmy of a related publication to the date on the cover of this book. This ensures that the publication selected supports the same release.
Type of Information Release overview Late information Description Use the Release Definition for the following information: Overview of all of the products in the release Information received too late to be included in the manuals Operating systems and Teradata Database versions that are certified to work with each product Version numbers of each product and the documentation for each product Information about available training and the support center Access to Information
1 Go to http://www.info.teradata.com. 2 Under Online Publications, click General Search 3 In the Publication Product ID box, type 2029. 4 Click Search. 5 Select the appropriate Release Definition from
the search results.
Preface Additional Information
Type of Information Additional product information
Description Use the Teradata Information Products web site to view or download specific manuals that supply related or additional information to this manual.
Access to Information
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 the Access Module products are as follows: Teradata Tools and Utilities Access Module Reference B035-2425-mmyx CD-ROM images Access a link to a downloadable CD-ROM image of all customer documentation for this release. Customers are authorized to create CD-ROMs for their use from this image. Use the Teradata Information Products web site to order printed versions of manuals.
1 Go to http://www.info.teradata.com. 2 Under the Online Publications subcategory,
Browse by Category, click Data Warehousing.

3 Click CD-ROM List and Images. 4 Follow the ordering instructions.
Ordering information for manuals
1 Go to http://www.info.teradata.com. 2 Under Print & CD Publications, click How to
Order.
3 Follow the ordering instructions. 1 Go to Teradata.com. 2 Select a link.
General information about Teradata
The Teradata home page provides links to numerous sources of information about Teradata. Links include: Executive reports, case studies of customer experiences with Teradata, and thought leadership Technical information, solutions, and expert advice Press releases, mentions, and media resources
Preface Additional Information
Table of Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 Supported Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4 Changes to This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4 Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4
Chapter 1: Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Record Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Chapter 2: Creating Access Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Attribute Exchange Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Version Identification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Get Attribute Requests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Put Attribute Requests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 18 19 19
Attributes Provided by Teradata Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Access Modules with the Teradata PT DataConnector Operator . . . . . . . . . . . . . . . . . . . . . . 20 Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Checkpoint/Restart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Function-Independent Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Table of Contents
Chapter 3: Access Module Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25

File Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25 File Get Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26 File Open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27 File Read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29 File Set Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30 File Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31 Get Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31 Identification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33 Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34 Put Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .35 Shutdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36
Chapter 4: Header File Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39

pmdcomt.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39 pmddamt.h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44
Appendix A: Sample Program and Makefile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49

Sample Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49 amsample.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49 Sample Makefile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65
List of Figures
Figure 1: Access Module Linkage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
List of Figures
10
List of Tables
Table 1: Supported Record Formats for Client Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Table 2: Record Formats for the Teradata PT DataConnector Operator . . . . . . . . . . . . . . . . 15 Table 3: Teradata Utility Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Table 4: Reqtype Function Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Table 5: Typical Interface Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
11
List of Tables
12
Overview
CHAPTER 1
This chapter provides a general overview of access modules, including the following: Description Record Formats
Description
An access module is a software component of the Teradata client utility infrastructure that provides a block-level I/O interface to data residing on a specific external data storage device. Each access module is tailored to a specific type of external data storage device and can be dynamically linked to one or more Teradata client utilities by the Data Connector Application Program Interface (API). The Data Connector API is a software component in each Teradata client utility infrastructure that provides a block-level I/O interface to one or more access modules. Each Data Connector API supports the logical record level I/O of the Teradata client utility, and is statically linked to the utility, as shown in Figure 1. Note: When using Teradata Parallel Transporter (Teradata PT) to interface with an access modules, the Teradata PT DataConnector operator must be used. For more information, see Access Modules with the Teradata PT DataConnector Operator on page 20.
13
Chapter 1: Overview Record Formats Figure 1: Access Module Linkage
Tape
Storage Device
OLE D ProvB ider
JMS Provider Teradata OLE DB Access Module
Customer Access Module Teradata Access Module For JMS
OLE D ProvB ider
Data Connector
IBM Websphere MQ Series
Teradata Websphere MQ Access Module
Client Utility
Client Utility
Statically Linked Data Stream Dynamically Linked Data Stream

2424C001
Record Formats
The Data Connector API blocks data for write operations and unblocks data for read operations according to the record format specified by the client utility or the Teradata PT DataConnector operator. See Table 1 for the supported formats for client utilities; see Table 2 for the formats for the Teradata PT DataConnector operator. Formats are determined at runtime by users. When developing an access module, users need to know the following: The format of the source data for both read and write operations That the access module supports the required format and operation
Always provide user documentation that clearly identifies the record formats and operations (read, write, or both) that are supported by the access module. The flow of data is as follows:
14
Chapter 1: Overview Record Formats
For read operations, data flows from the access module to the client Data Connector API. The Data Connector API expects, but does not require, the access module to provide data in blocks that are comprised of one or more logical records. For write operations, data flows from the Data Connector API to the access module. The Data Connector API in most cases provides data in blocks that are comprised of one or more logical records.
Table 1: Supported Record Formats for Client Utilities
Format pmIDFtext pmIDFBin1 pmIDFBin1Plus pmIDFBin2 pmIDFBin2Plus pmIDFnone
Description Records are separated by end-of-record markers. Data is prefixed by a two-byte record length. This length does not include the two bytes used for the record length. Same as pmIDFBin1 except that each record is followed by an end-of-record marker. Same as pmIDFBin1 except that the 2 bytes containing the record length include the 2 bytes used for the record length itself. Same as pmIDFBin2 except that each record is followed by an end-of-record marker. Data has no internal formatting. In this case, it is the responsibility of the utility to determine record separation, if any.
The mnemonics, such as pmIDFBin1, are used for clarity and reference purposes only. End-of-record markers are one-byte fields containing either decimal '10' (x'0a') or decimal '13' (x'0d').
Table 2: Record Formats for the Teradata PT DataConnector Operator
Format Binary
Description Each record contains a 2-byte integer data length, n, followed by n bytes of data. For example, a record containing 6 bytes of text "abcdef "is: Hexadecimal: x'00 06 61 62 63 64 65 66' Character:"...abcdef "
Text
Each record contains character data only. Records are separated by an end-of-record (EOR) marker. Note: The EOR marker can be either a single-byte line feed (X'0A') or a double-byte carriage-return/line feed pair (X'0D0A'). The first EOR marker in the data marks the end of the first record; the end of each remaining record should also be marked with an EOR marker. For example, a record containing the text "acdc" is: Hexadecimal: x'61 63 64 63 0a' Character: "abcd."
15
Chapter 1: Overview Record Formats

Table 2: Record Formats for the Teradata PT DataConnector Operator (continued)
Format Delimited
Description Each record is in text format and contains fields (columns) separated by a delimiter character. This delimiter character is provided to the Teradata PT DataConnector operator through its TextDelimiter attribute. If not provided, the TextDelimiter attribute defaults to the pipe character ('|'). Note: The final delimiter (of the last column) is optional. For example, using a colon as the delimiter (TextDelimeter = ':'), a record with two fields, text "1234" and "abcd", would be: Hexadecimal: x'31 32 33 34 3a 61 62 63 64 3a 0a' Character: "1234:abcd:."
Formatted
Each record is in a format traditionally known as FastLoad or Teradata format. The data is prefixed with the data length (as with binary format) and followed by an endof-record (EOR) marker (as with text format). For example, a record containing 6 bytes of text "abcdef " is: Hexadecimal: x'00 06 61 62 63 64 65 66 0a' Character: "...abcdef."
Unformatted
The data does not conform to any predefined format. The data is entirely described by the specified Teradata PT schema or utility LAYOUT command. For example:
DEFINE SCHEMA PRODUCT_SOURCE_SCHEMA DESCRIPTION 'PRODUCT INFORMATION SCHEMA' ( COL1 INTEGER, COL2 CHAR(4), COL3 VARCHAR(8) );
A record containing the data: integer 20, char "1234", varchar "abcde" is; x'00 00 00 14 31 32 33 34 00 05 61 62 63 64 65' where: x'00 00 00 14' is the integer 20, x'31 32 33 34' is the fixed length character "1234" x'00 05' is the length of the varchar field and x'61 62 63 64 65' is the varchar character data "abcde" Note: When using UNFORMATED formatting in MVS, ensure that the actual input data is consistent with the layout defined in the utility script. Discrepancies in the length of logical records could result in data corruption.
For more information about how to use access modules with Teradata PT, see Access Modules with the Teradata PT DataConnector Operator on page 20.
16
Creating Access Modules
CHAPTER 2
This chapter describes the functional aspects of the access module interface with the data connector component of a Teradata utility, such as the Data Connector APIs or the Teradata PT DataConnector operator. Structure Parameters Attribute Exchange Functions Attributes Provided by Teradata Utilities Access Modules with the Teradata PT DataConnector Operator Considerations Checkpoint/Restart Function-Independent Structure
Structure
Each access module must be packaged as a single main function that is called for all devicespecific I /O functions by the data connector component of the Teradata utility or the DataConnector Operator in Teradata PT. The structure for the main function is:
void PIDMMain ( pmiCmdBlock_t *Opts, void *OptParms )
Appendix A provides a sample program that supports the access module interface.
Parameters
The Teradata Access Module interface is supported by two parameters; there are no other elements or global or environmental variables. Each parameter is a structure pointer, and the structures provide the communication between an access module and a Teradata utility: The first parameter specifies a general, function-independent structure that contains the common fields required for all access module functions. The second parameter specifies a function-dependent structure that contains the unique fields required for a specific access module function: File Close File Get Position
17
Chapter 2: Creating Access Modules Attribute Exchange Functions
File Open File Read File Set Position File Write Get Attribute Identification Initialization Put Attribute Shutdown
The second parameter is passed as a void. Chapter 3 provides a detailed description of each access module function, as well as an explanation of the corresponding function-dependent structure.
Attribute Exchange Functions

The following function-dependent access module structures provide a method of exchanging informational attribute values between an access module and a Teradata utility or the Teradata PT DataConnector operator:
Function Name Identification Get Attribute Put Attribute Teradata utility or Teradata PT DataConnector operator Transfer From access module Transfer To Teradata utility or Teradata PT DataConnector operator access module
The attribute exchange functions provide only an exchange of information. No control is implied. The use and disposition of the requested information is the responsibility of the destination module. For example, these functions typically exchange identification of the following: A Teradata Database table that is currently being addressed from a Teradata utility to an access module VOLSER of the currently mounted media from an access module to a Teradata utility
Version Identification
Use the Identification Function to obtain version information about the access module. This function is requested as the second parameter (OptParms) in the main function called PIDMMain(). This main function is called by the Teradata Data Connector. The Data Connector displays this information in its log file and is available to the client utility to record in its log file.
18 Teradata Tools and Utilities Access Module Programmer Guide
Chapter 2: Creating Access Modules Attributes Provided by Teradata Utilities
On a Windows-based system, access module product information can be found by accessing Start>Control Panel>Add or Remove Programs.
Get Attribute Requests

Examples of Get Attribute functions are: DeviceState MediaMounted VolID DegreesC
In response to a Get Attribute request, an access module must respond with either: The value of the requested information A return code indicating that the attribute name was not recognized
This is a passive function, meaning that an access module can only accumulate and maintain the value of the requested information. It can only send a value to a client utility in response to a specific request. If, for example, an access module needs to provide a client utility with a value of several attributes that describe its state of operation, the access module cannot actively send this information to the client utility. Instead, the access module must wait for a utility to request the information with a Get Attribute request before it responds with the value for the requested attribute.
Put Attribute Requests

In response to a Put Attribute request, which includes a value for an attribute previously defined by the Teradata utility, an access module must respond with a return code indicating whether the attribute name was recognized. This is a passive function, meaning that an access module can only receive the value of the provided information. An access module cannot actively retrieve information from a Teradata utility. For example, if a Teradata utility needs to provide an access module with the value of several attributes that describe its state of operation (such as DBSVersion, ClientState, CurrDBS, or CurrTable), the Teradata utility can perform a Put Attribute function whenever one of these attributes is first defined or changed. The access module then receives each Put Attribute request and responds each time, indicating whether the attribute name was recognized. Note: If an attribute that is needed by an access module is not already defined by a Put Attribute function from the client utility, the access module might fail, in which case it will respond with an appropriate return code and error message.
Attributes Provided by Teradata Utilities

The Teradata utilities can provide the following attributes to access modules. CHARSET_NAME and CHARSET_NUMBER, for example, are part of the session character set that is passed by pmAPutAttr() from the client utility to an access module.
19
Chapter 2: Creating Access Modules Access Modules with the Teradata PT DataConnector Operator
Table 3: Teradata Utility Attributes
Name of Attribute BYTE_ORDER
Provided by FastExport, FastLoad, MultiLoad, and TPump job scripts
Attribute Value Allows explicit ordering of the byte sequences that are unique to character sets found at the beginning of a file. This attribute allows you to explicitly define the byte order for a specific platform. Attribute values are LITTLE_ENDIAN or BIG_ENDIAN.
CHARSET_NAME
FastExport, FastLoad, MultiLoad, and TPump job scripts FastExport, FastLoad, MultiLoad, and TPump job scripts Teradata PT DataConnector operator
Character set name. This attribute is optional. Attribute values are UTF16, UTF8 or ASCII. One-byte ID of the character set. This attribute is optional. Pointer to Teradata PT operator handle. The pointer communicates with Teradata PT functions. The Teradata PT DataConnector operator always sends this attribute, although the access module does not have to use it.
CHARSET_NUMBER
TBR_OP_HANDLE
TIMEOUT_SECONDS
Teradata PT, TPump, and DataConnector operator FastExport, FastLoad, MultiLoad, and TPump job scripts
An I/O time-out value in seconds. This value is in character form and must be converted to an integer value for use. Byte order marker. This attribute is optional. Attribute values are YES or NO, where YES causes a Byte Order mark to be written to the beginning of the file.
WRITE_BOM
Access Modules with the Teradata PT DataConnector Operator

Teradata PT operators, which simulate some of the functions of Teradata FastExport, Teradata FastLoad, and others, interface with access modules through the Teradata PT DataConnector operator. Access modules can be incorporated into a Teradata PT job as long as the access module are defined for a job script.
20
Chapter 2: Creating Access Modules Considerations
To define an access module in a Teradata PT job script

1
Include the following program text within the DEFINE OPERATOR ATTRIBUTES clause of the DataConnector definition (in addition to the other attributes being defined):
( VARCHAR AccessModuleName, VARCHAR AccessModuleInitStr )
where: AccessModuleName specifies the file name of the dynamically loadable module that provides the access module software. AccessModuleInitStr specifies the access module initialization string, which is a list of operational parameters that you can specify for an access module. The contents of the initialization string are determined by the requirements of the specified access module.
Define the access module attributes within the APPLY or SELECT clause in which you are using the DataConnector operator. For example:
SELECT * FROM OPERATOR ( DC_FILE_READER() [1] ATTR ( PrivateLogName = 'dcR.log', FileName = './dummy', OpenMode = 'Read', Format = 'Text', IndicatorMode = 'No', AccessModuleName = 'libmqs.so', AccessModuleInitStr = '-qmgr SYSQ1 -qnm MyQ -TRCL 2 MQTRCE.txt' ) );
Note: For the appropriate value to assign to the Format attribute, refer to specific access module documentation.
Considerations
When writing an access module, the following rules apply: All functions are invoked with support of two parameters: General function-independent specifications Function-dependent specifications
Use an initialization function first, before any other. Specify all buffer and record lengths as multiples of the sizeof(pmChar_t) value. Free all buffer areas that are created by an access module when they are no longer needed. The passing of error text to the Data Connector API (for display by the client) is supported by a buffer allocated by the access module. The access module can assume the buffer is no
21
Chapter 2: Creating Access Modules Checkpoint/Restart
longer required on the next entry to the access module; that is, the buffer is freed the next time the access module is called. UNIX signals are predefined messages sent between two UNIX processes to communicate the occurrence of unexpected external events or exceptions. If UNIX signals are incorporated into an access module or routine, an error results. For a list of UNIX signals used by a particular Teradata utility, see the corresponding Teradata documentation. For example, one of the signals used by Teradata FastLoad is SIGUSR1, which is documented in Teradata FastLoad Reference.
Checkpoint/Restart
The Teradata Database checkpoint/restart feature must be supported by customized access modules whenever possible. Checkpoints are supported by the File Get Position calls that specify Reqtype pmiPIDMOptGetPos. Restarts are supported by File Set Position calls that specify Reqtype pmiPIDMOptSetPos.
If an access module cannot support checkpoints and restarts, a pmrcUnsupported return code needs to be returned for all calls when Reqtype is either pmiPIDMOptGetPos or pmiPIDOptSetPos. The contents of the buffer returned in response to a File Get Position call depends on the access module. However, the contents must configure the access module so that the next File Read function (Reqtype pmiPIDMOptRead) returns the same data block that is returned prior to the File Get position call. If a restart is attempted, the same data must be returned to the access module from the File Set Position function request. Note: The buffer is maintained by the client in the job-specific checkpoint information. For example, assume that three record blocks were read by an access module prior to receiving a File Get Position call, and that record block #3was the last block returned. If that reading continued, and then a File Set Position function was received, the information provided is that which was previously returned by the access module in the previous File GetPosition function call. The access module reconfigures its internal state so that the next record block returned by the next File Read function call is record block #3. See File Read on page 29, File Get Position on page 26, and File Set Position on page 30 for details.
Function-Independent Structure
The general, function-independent structure identifies a requested function and provides the specifications required by all access module function calls. For detailed examples, refer to the pmdcomt.h and pmddamt.h header files in Chapter 4: Header File Examples.
22
Chapter 2: Creating Access Modules Function-Independent Structure

typedef struct { char pmUInt32 pmUInt32 pmReturnType pmTrceLvl_t _pmiCmdBlock */ */ */ */ */ */ */
EyeCatcher[pmiMAX_EC_LEN];/* Struct eyecatcher string StructLength; /* Length of this structure Reqtype; /* function request indicator Retcode; /* identical to function return value TraceLvl; /* Requested diagnostic trace level /* Descriptive error text pmNameBuf_t ErrMsg; /* when Retcode is pmrcFailure } pmiCmdBlock_t;
where:
Parameter EyeCatcher StructLength Reqtype Retcode Field input input input output Description Structure description string, such as pmCmdBlock. Total structure length, including the EyeCatcher string. Specific function request, as listed in Table 4. Value assigned by the access module function as one of those defined in the pmdcomt.h. header file. Although additional function-specific return codes are defined with each function, typical interface return codes are listed in Table 5. Default trace level to be associated with all functions related to this operation. Two-field value assigned by the access module function when Retcode is set to pmrcFailure. These fields provide the following: Descriptive error text of up to 32,000 bytes, maximum Length of the text Whenever an error condition is detected, the access module must map the error to one of the error codes defined in the pmdcomt.h header file. If a well-defined match is not found, the access module must return a value of pmrcFailure and provide an error description string in this ErrMsg field. The client utility then presents the error message to the user.
TraceLvl ErrMsg
input output
The following table lists the function requests for Reqtype.

Table 4: Reqtype Function Requests
Reqtype pmiPIDMOptInit pmiPIDMOptOpen pmiPIDMOptClose pmiPIDMOptCloseR pmiPIDMOptRead
Description Access module initialization File open File close File close and release media File read
23
Chapter 2: Creating Access Modules Function-Independent Structure

Table 4: Reqtype Function Requests (continued)
Reqtype pmiPIDMOptWrite pmiPIDMOptGetPos pmiPIDMOptSetPos pmiPIDMOptShut pmiPIDMOptID pmiPIDMOptGetA_A pmiPIDMOptGetF_A pmiPIDMOptPutA_A pmiPIDMOptPutF_A
Description File write Get position of currently open file Set position of currently open file Access module shutdown (cleanup) Access module identification Get (obtain) an access module attribute Get (obtain) a file attribute Put (provide) an access module attribute Put (provide) a file attribute
The following table lists typical interface return codes.

Table 5: Typical Interface Return Codes
Return Code pmrcOK pmrcUnsupported pmrcBadTraceLvl pmrcBadParm pmrcAPInotReady pmrcAllocErr pmrcFailure
Description No error conditions encountered. The function requested by Reqtype is not supported. The value of TraceLvl is out of range. One or more of the supplied parameters is invalid. The access module has not been initialized. A memory allocation error occurred. General failure return code. See the description of the ErrMsg parameter.
See Chapter 3: Access Module Functions for more information about access module functions.
24
Access Module Functions
CHAPTER 3
This chapter describes the functions required from an access module and the supporting data structures for those functions. This information is necessary for writing an access module to support an I/O subsystem that is not currently supported by Teradata, such as a module to access a CD/ROM burner or an automated satellite up/downlink. All of the program examples and descriptions use the C programming language. Note: In the following text, all references to access module file operations mean any data source or destination, as well as a file.
File Close
The File Close function closes a file that is currently open for read or write operations. The term file refers to a data source or destination on any sort of data storage device (such as magnetic tape, disk, CD-ROM, or another database) that an access module supports. The terms read and write refer to data moving from (read) and to (write) the data source or destination. The structure follows:
typedef struct _pmiClose { char EyeCatcher[pmiMAX_EC_LEN];/* Struct eyecatcher string */ pmUInt32 StructLength; /* Length of this structure */ void *FIData; } pmiClose_t;
where:
Parameter EyeCatcher StructLength FIData Field input input input Description Structure description string, such as pmCloseParms. Total structure length, including the EyeCatcher string. Value provided by the access module in response to a previous file open request call.
Return Codes
The following File Close return code supplements those listed in Table 5 on page 24.
25
Chapter 3: Access Module Functions File Get Position
Return Code pmrcBadFp
Description Invalid or meaningless value in FIData.
Usage Notes
Consider the following when specifying File Close parameters: Requirements - A File Close function is required when the Reqtype field of the pmiCmdBlock_t structure is either: pmiPIDMOptClose pmiPIDMOptCloseR
Removing and Releasing Media - If Reqtype is pmiPIDMOptCloseR, then an access module must also release and remove any associated removable media, such as dismounting a tape from a drive.
File Get Position

The File Get Position function determines and returns the media position of an open file. The structure follows:
typedef struct _pmPosData ( pmUInt32 Length; char *Data; } pmPos_t; typedef struct _pmiPos { char EyeCatcher[pmiMAX_EC_LEN];/* Struct eyecatcher string */ pmUInt32 StructLength; /* Length of this structure */ void *FIData; pmPos_t Position; } pmiPos_t;
where:
Parameter EyeCatcher StructLength FIData Position Field input input input output Description Structure description string, such as pmGetParms. Total structure length, including the EyeCatcher string. Value provided by the access module in response to a previous open request call. A two-field structure as follows: Length - The length, in bytes, of the Data field Data - A pointer to the media position information
26
Chapter 3: Access Module Functions File Open
Return Codes
The File Get Position return codes are listed in Table 5 on page 24.
Usage Notes
Consider the following when specifying File Get Position parameters: Requirements - A File Get Position function is required when the Reqtype field of the pmiCmdBlock_t structure is pmiPIDMOptGetPos. Position Data Length - Always minimize the length of the position data stored in the Length field of the pmPos_t structure, as certain arbitrary limits can be encountered.
File Open
The File Open function opens a file for subsequent read and write operations. The term file refers to a data source or destination on any sort of data storage device (such as magnetic tape, disk, CD-ROM, or another database) that an access module supports. The terms read and write refer to data moving from (read) and to (write) the data source/ destination. The structure follows:
typedef struct _pmiOpen { char EyeCatcher[pmiMAX_EC_LEN]; /* Struct eyecatcher string pmUInt32 StructLength; /* Length of this structure void *PIData; /* Access module Internal Data Pointer pmOpenMode_t OpenMode; /* provided to Access Module pmUInt16 BlkHeaderLen; /* defined by Access Module pmUInt32 BlkSize; /* defined by Access Module /* File Internal Data void *FIData; /*(returned/used by Access Module) /* File (data stream) supplied to Access Module pmUInt16 FileNameL; /* Name length har FileName[pmiMAX_DDNAME_LEN+1]; /* Name } pmiOpen_t;
*/ */ */ */ */ */ */ */ */ */ */
where:
Parameter EyeCatcher StructLength PIData Field input input input Description Structure description string, such as pmOpenParms. Total structure length, including the EyeCatcher string. Value provided by the access module in response to a previous initialization request call. This value identifies the instance of the access module opening the file.
27
Chapter 3: Access Module Functions File Open
Parameter OpenMode
Field input
Description Indicates the intended use of the file to be opened. The following values are supported. pmOpenModeR opens the file for read-only access. pmOpenModeW opens the file for write-only access. pmOpenModeRW opens the file for write-only access, appending to the end of the file.
BlkHeaderLen BlkSize FIData
output output output
Number of device-dependent bytes that prefix the user data in each block. Size, in bytes, of the data blocks to be either read from or written to the file. Handle/pointer to internal access module data. There are no restrictions on the FIData value, and the assigned value will be returned in a subsequent call to the access module. Length of FileName parameter. Name of the file to be opened.
FileNameL FileName
input input
Return Codes
The following File Open return codes supplement those listed in Table 5 on page 24.
Return Code pmrcFNameTooLong pmrcBadFormat Description File name specified by the FileName parameter is too long. Value specified by the Format parameter is invalid.
Usage Notes
Consider the following when specifying File Open parameters: Requirements - A File Open function is required when the Reqtype field of the pmiCmdBlock_t structure is pmiPIDMOpOpen. BlkSize Value - The returned BlkSize value determines client buffering requirements. This value represents the maximum block size that is sent to or received from an access module. On read operations, record lengths greater than the BlkSize specification are considered an error condition that overwrites client memory. On write operations, however, if the Teradata client utility needs to avoid spanned logical records, the access module typically receives blocks that are smaller than the BlkSize specification. BlkHeaderLen Value - The returned BlkHeaderLen value indicates the number of bytes at the beginning of each block returned on read operations that are specific to an access module. If, for example, an access module needs to prefix each record with a four-byte block length, and that block length was present at the beginning of the returned read
28
Chapter 3: Access Module Functions File Read
buffer, then the BlkHeaderLen is set to 4. If, however, the access module does not include that field in its returned data, then the BlkHeaderLen value is set to 0.
File Read
The File Read function reads a block of data from an open file. The structure follows:
typedef struct _pmiRW { char EyeCatcher[pmiMAX_EC_LEN];/* Struct eyecatcher string */ pmUInt32 StructLength; /* Length of this structure */ void *FIData; pmUInt32 BufferLen; char *Buffer; } pmiRW_t;
where:
Parameter EyeCatcher StructLength FIData BufferLen Buffer Field input input input output input Description Structure description string, such as pmReadParms. Total structure length, including the EyeCatcher string. Value provided by the access module in response to a previous file open request call. Length of the returned data block. Pointer to the buffer area into which the access module is to return the data block.
Return Codes
The following File Read return codes supplement those listed in Table 5 on page 24.
Return Code. pmrcBadFp pmrcWriteOnly pmrcEOF Description An invalid or meaningless value in FIData. The file specified by FIData is opened for write operations only. An end-of-file was encountered. BufferLen is zero.
Usage Notes
Consider the following when specifying the File Read parameters: Requirements - A File Read function is required when the Reqtype field of the pmiCmdBlock_t structure is pmiPIDMOptRead. BlkHeaderLen Value - The returned BlkHeaderLen value indicates the number of bytes at the beginning of each block returned on read operations that are access module specific. If,
29
Chapter 3: Access Module Functions File Set Position
for example, the access module needs to prefix each record with a four-byte block length and that block length was present at the beginning of the returned read buffer, then the BlkHeaderLen is set to 4. If, however, the access module does not include that field in its returned data, then the BlkHeaderLen value is set to 0.
File Set Position

The File Set Position function repositions the media of an open file. The structure follows:
typedef struct _pmPosData { pmUInt32 Length; char *Data; } pmPos_t; typedef struct _pmiPos { char EyeCatcher[pmiMAX_EC_LEN];/* Struct eyecatcher string */ pmUInt32 StructLength; /* Length of this structure */ void *FIData; pmPos_t Position; } pmiPos_t;
where:
Parameter EyeCatcher StructLength FIData Position Field input input input input Description Structure description string, such as pmSetParms. Total structure length, including the EyeCatcher string. Value provided by the access module in response to a previous open request call. A two-field structure as follows: Length - The length, in bytes, of the Data field Data - A pointer to the media position information
Return Codes
The file set position return codes are listed in Table 5 on page 24.
Usage Notes
Consider the following requirements when specifying File Set Position parameters: Requirement - A File Set Position function is required when the Reqtype field of the pmiCmdBlock_t structure is pmiPIDMOptSetPos. Data Return - An access module must return the same block of data after a File Set Position request as is returned before the corresponding File Get Position request.
30
Chapter 3: Access Module Functions File Write
File Write
The File Write function writes the provided block of data to a currently open file. The structure of the File Write function follows:
typedef struct _pmiRW { char EyeCatcher[pmiMAX_EC_LEN];/* Struct eyecatcher string */ pmUInt32 StructLength; /* Length of this structure */ void *FIData; pmUInt32 BufferLen; char *Buffer; } pmiRW_t;
where:
Parameter EyeCatcher StructLength FIData BufferLen Buffer Field input input input input input Description Structure description string, such as pmWriteParms. Total structure length, including the EyeCatcher string. Value provided by the access module in response to a previous open request call. Length of the data block to be written. Pointer to the data block to be written.
Return Codes
The following File Write return codes supplement those listed in Table 5 on page 24.
Return Code pmrcBadFp pmrcReadOnly Description An invalid or meaningless value in FIData. The file indicated via FIData is opened for read operations only.
Usage Notes
Consider the following when specifying the File Write parameters: Requirements - A File Write function is required when the Reqtype field of the pmiCmdBlock_t structure is pmiPIDMOptWrite.
Get Attribute
The Get Attribute function retrieves an arbitrary data value from an access module. The structure follows:
31
Chapter 3: Access Module Functions Get Attribute

typedef struct _pmiAttribute { char EyeCatcher[pmiMAX_EC_LEN]; /* Struct eyecatcher string */ pmUInt32 StructLength; /* Length of this structure */ void *ObjData; /* Object pointer (PIData or FIData) */ pmUInt32 AttrNameLen; /* Length of attribute name */ char AttrName[pmiMAX_ATR_NAME_LEN]; /* Attribute name */ pmUInt32 AttrValueLen; /* Length of attribute value */ char AttrValue[pmiMAX_ATR_VAL_LEN]; /* Attribute value */ } pmiAttr_t;
where:
Parameter EyeCatcher StructLength ObjData Field input input input Description Structure description string, such as pmGetAParms. Total structure length, including the EyeCatcher string. Pointer to one of two forms of data. The type of data depends on the value of Reqtype as follows: pmiPIDMOptGetA_A - ObjData is a value provided by an access module in response to a previous initialization request call (as in PIData fields, noted earlier). pmiPIDMOptGetF_A - ObjData is a value provided by an access module in response to a previous open request call (as in FIData fields, noted earlier). AttrNameLen AttrName AttrValueLen AttrValue input input output output Length of the AttrName field. Name of the attribute. Length of the AttrValue field. Value of the attribute.
Return Codes
The following Get Attribute return code supplements those listed in Table 5 on page 24.
Return Code. pmrcBadAttrName Description The AttrName is not recognized.
Usage Notes
Consider the following when specifying Get Attribute parameters: Requirements - A Get Attribute function is required when the Reqtype field of the pmiCmdBlock_t structure is pmiPIDMOptGetA_A or pmiPIDMOptGetF_A. Communication - The Get Attribute function facilitates communication to the client utility from the access module. It might be used, for example, to send a physical volume identification to the client utility.
32
Chapter 3: Access Module Functions Identification
Identification
The Identification function identifies an access module, and the name and version number of all internal modules. The structure follows:
#define pmMAX_VER_STR_LEN 31 typedef struct _pmVerLst_t { char ModuleName[pmMAX_VER_STR_LEN+1]; char ModuleVers[pmMAX_VER_STR_LEN+1]; struct _pmVerLst_t *Next; } pmVerLst_t; typedef struct _pmiID { char EyeCatcher[pmiMAX_EC_LEN];/* Struct eyecatcher string */ pmUInt32 StructLength; /* Length of this structure */ pmVerLst_t VerIDList; } pmiID_t;
where:
Parameter EyeCatcher StructLength VerIDList Field input input output Description Structure description string, such as pmIDParms. Total structure length, including the EyeCatcher string. First of a singly linked list of module identifications.
Return Codes
For return code information, see Table 5 on page 24.
Usage Notes
Consider the following when specifying Identification parameters: Requirements - The Identification function is required when the Reqtype field of the pmiCmdBlock_t structure is pmiPIDMOptId. Version Information - The Identification function produces version information. This function is requested as the second parameter (OptParms) in the main function called PIDMMain(). This main function is called by the Data Connector API, then displays the information in its log file. The information is also available to the client utility to record in its log file. Note: For access module product information on a Windows-based system, go to Start>Control Panel>Add or Remove Programs. Modules to List - Include all of the source modules in the list.
33
Chapter 3: Access Module Functions Initialization
Initialization
The Initialization function initializes an access module. The structure follows:
typedef struct _pmiInit { char EyeCatcher[pmiMAX_EC_LEN]; /* Struct eyecatcher string pmUInt32 StructLength; /* Length of this structure void *PIData; /* Access module Internal Data Pointer pmUInt16 InterfaceVerNo; /* pmdcomt.h version identifier pmUInt16 InterfaceVerNoD; /* pmddamt.h version identifier pmUInt32 ClientIDL; /* Length of ClientID field pmUInt32 InitStrL; Length of InitStr field /* Client Utility char ClientID[pmMAX_CLIENT_ID+1]; /* identifier /* Access module char InitStr[pmiMAX_INIT_STR_LEN+1]; /* initialization field } pmiInit_t;
*/ */ */ */ */ */ */ */ */ */ */
where:
Parameter EyeCatcher StructLength PIData Field input input output Description Structure description string, such as pmInitParms. Total structure length, including the EyeCatcher string. A handle/pointer to internal access module data. No restrictions exist on the PIData value, and the assigned value is returned in a subsequent call to the access module. Identifying value for the expected version of the general access module interface header file, pmdcomt.h. This value should match the pmInterfaceVersion value defined in pmdcomt.h. If the match fails, set the access module Retcode to pmrcBadVer and return. Identifying value for the expected version of the devicedependent access module interface header file, pmddamt.h. This value should match the pmiInterfaceVersion value defined in pmddamt.h. If the match fails, set the access module Retcode to pmrcBadVer and return. Length of ClientID. Length of InitStr. Identifier of the using program, such as Teradata FastLoad. A string of access module-specific initialization information that is meaningful only to the access module. The customer provides the initialization string, by way of the client utility, which passes the string unaltered to the access module.
InterfaceVerNo
input
InterfaceVerNoD
input
ClientIDL InitStrL ClientID InitStr
input input input input
34
Chapter 3: Access Module Functions Put Attribute
Return Codes
The following Initialization return codes supplement those listed in Table 5 on page 24.
Return Code pmrcBadVer pmrcRedundant Description An invalid parameter value for InterfaceVerNo or InterfaceVerNoD. Specifies that the access module is already initialized.
Usage Notes
Consider the following when specifying Initialization parameters: Initialization Requirements - Access module initialization is required when the Reqtype field of the pmiCmdBlock_t structure is pmiPIDMOptInit. Supporting Multiple Interactions - When supporting more than one iteration, use the PIData field to distinguish between iterations and between the files opened by each iteration. To distinguish between iterations, use a different PIData value with each initialization request. To distinguish between the files opened by each iteration, use the same PIData value with each file open request.
Put Attribute
The Put Attribute function provides an arbitrary data value to an access module. The structure follows:
typedef struct _pmiAttribute { char EyeCatcher[pmiMAX_EC_LEN]; /* Struct eyecatcher string */ pmUInt32 StructLength; /* Length of this structure */ void *ObjData; /* Object pointer (PIData or FIData) */ pmUInt32 AttrNameLen; /* Length of attribute name */ char AttrName[pmiMAX_ATR_NAME_LEN]; /* Attribute name */ pmUInt32 AttrValueLen; /* Length of attribute value */ char AttrValue[pmiMAX_ATR_VAL_LEN]; /* Attribute value */ } pmiAttr_t;
where:
Parameter EyeCatcher StructLength Field input input Description Structure description string, such as pmPutAParms. Total structure length, including the EyeCatcher string.
35
Chapter 3: Access Module Functions Shutdown
Parameter ObjData
Field input
Description Pointer to one of two forms of data. The type of data depends on the value of Reqtype, as follows: pmiPIDMOptPutA_A - ObjData is a value provided by an access module in response to a previous access module initialization request call (as in PIData fields, noted earlier). pmiPIDMOptPutF_A - ObjData is a value provided by an access module in response to a previous access module open request call (as in FIData fields, noted earlier).
AttrNameLen AttrName AttrValueLen AttrValue
input input input input
Length of the AttrName field. Name of the attribute. Length of the AttrValue field. Value of the attribute.
Return Codes
The following Put Attribute return code supplements those listed in Table 5 on page 24.
Return Code. pmrcBadAttrName Description The AttrName is not recognized.
Usage Notes
Consider the following when specifying Put Attribute parameters: Requirements - A Put Attribute function is required when the Reqtype field of the pmiCmdBlock_t structure is pmiPIDMOptPutA_A or pmiPIDMOptPutF_A. Communication - The Put Attribute function facilitates communication from a client utility to an access module. It might be used, for example, to send the name of the currently active database table to the access module. Character Sets - Session character set is passed by pmAPutAttr() from the client utility to the access module for possible use. The attribute value is a variable-length character string with either the character set name or the character representation of the character set ID. The attribute varies based on how you specify the character set: If specified by name, the attribute name is CHARSET_NAME. If specified by ID, the attribute name is CHARSET_NUMBER.
Shutdown
The Shutdown function terminates an access module. The structure follows:
36

typedef struct _pmiShut { char EyeCatcher[pmiMAX_EC_LEN];/* Struct eyecatcher string */ pmUInt32 StructLength; /* Length of this structure */ void *PIData; pmUInt16 Mode; } pmiShut_t;
where:
Parameter EyeCatcher StructLength PIData Mode Field input input input input Description Structure description string, such as pmShutParms. Total structure length, including the EyeCatcher string. Value provided by an access module in response to a previous open request call. Shutdown mode/option as follows: pmShutDownNormal - Normal error checking. If anything prevents a clean termination (such as files still open), then exit without action with a non-pmrcOK in Retcode. pmShutDownBrute - Take arbitrary action for unexpected conditions.
Return Codes
The following Shutdown return code supplements those listed in Table 5 on page 24:
Return Code. pmrcOpenFiles Description Files are open.
Usage Notes
Consider the following when specifying the Shutdown parameters: Requirements - A Shutdown function is required when the Reqtype field of the pmiCmdBlock_t structure is pmiPIDMOptShut. Housekeeping Operations - The Shutdown function also performs the following housekeeping operations: Terminating subprocesses Closing open files Freeing memory
Error Conditions - The Shutdown function needs to proceed despite file close errors.
37
38
Header File Examples
CHAPTER 4
This chapter provides the following header file examples: pmdcomt.h for the Data Connector application program interface (API) pmddamt.h for the Data Connector and access module interface values
pmdcomt.h
This header file shows example client-related structure and symbol definitions relating to the Data Connector API.
/* % TITLE pmdcomt.h ... Independent/Dependent Access Module */ /* common struct/types */ ***********************************************************************/ /* Copyright 1997-2008 Teradata Corporation. */ /* ALL RIGHTS RESERVED. */ /* Teradata Corporation CONFIDENTIAL AND TRADE SECRET */ /* */ /* This copyrighted material is the Confidential, Unpublished */ /* Property of the Teradata Corporation. This copyright notice */ /* and any other copyright notices included in machine readable */ /* copies must be reproduced on all authorized copies. */ /* */ /* CRITICAL USAGE NOTE: */ /* This header file is to be the EXACT same file for both SA & TPT. */ /* The cooresponding versions in /vob/tdcli & /vob/paralx must match */ /* The identiy will insure that the same access module will work with */ /* the standalone utilities AND the TPT DC operator */ /**********************************************************************/ #ifndef PMDCOMT_H #define PMDCOMT_H #define pmMAX_CLIENT_ID 255 #define pmMAX_ATR_NAME_LEN 255 #define pmMAX_ATR_VAL_LEN 255 #define PM_COPYRIGHT_NOTICE \ "COPYRIGHT 2001-2008, Teradata Corporation. #define #define #define #define #define #define ALL RIGHTS RESERVED."
PM_ATR_NAME_TIMEOUT "TIMEOUT_SECONDS" PM_ATR_NAME_CHARSET_NAME "CHARSET_NAME" PM_ATR_NAME_CHARSET_NUMBER "CHARSET_NUMBER" PM_ATR_NAME_WR_BOM "WRITE_BOM" PM_ATR_NAME_ENHANCED_RESTART "Restart_Validation" PM_ATR_VALU_UTF32 "UTF32"
39
Chapter 4: Header File Examples pmdcomt.h

#define #define #define #define #define #define #define #define #define /* /* /* /* /* /* /* /* PM_ATR_VALU_UTF16 "UTF16" PM_ATR_VALU_UTF8 "UTF8" PM_ATR_VALU_ASCII "ASCII" PM_ATR_NAME_BYTE_ORDER "BYTE_ORDER" PM_ATR_VALU_BIG "BIG_ENDIAN" PM_ATR_VALU_LITTLE "LITTLE_ENDIAN" PM_ATR_VALU_YES "YES" PM_ATR_VALU_NO "NO" PM_ATR_VALU_DEFAULT "DEFAULT" */ */ */ */ */ */ */ */
Used to pass the CHECKPOINT value from the client load utility (i.e. FastLoad, MultiLoad, TPump) to the access module. The attribute value is a string containing ASCII encoding of the decimal textual representation of CHECKPOINT value. Value of "0" indicates that checkpoint/restart processing is not enabled; a file opened by an access module instance for which CHECKPOINT_INTERVAL attribute is "0" (at the time of the File Open request) will not receive a File Get Position request.
#define PM_ATR_NAME_CHECKPOINT_OPTION "CHECKPOINT_INTERVAL" #define PM_ATR_NAME_EXPORT_WIDTH "EXPORT_WIDTHS" /* /* /* /* The list of server character type codes. These values are used in the CharType field of pmExp Width_t structures. The values should match the corresponding values from dbsv2/src/par/evl/evltypes.h. pmEVLLATIN1 pmEVLUNICODE pmEVLSJIS pmEVLGRAPHIC pmEVLKANJI1 1 /* 8-bit Latin1 character data type 2 /* 16-bit Unicode character data type 3 /* KanjiSJIS character data type 4 /* Graphic character data type (in Unicode) 5 /* Kanji1 character data type */ */ */ */ */ */ */ */ */
#define #define #define #define #define
#if defined(HPUX) && defined(PIOM64) && !defined(HPUX_IA64) #ifdef __cplusplus #define pmdcomt_packing "pack 8" #pragma pack 8 #else #define pmdcomt_packing "HP_ALIGN NATURAL PUSH" #pragma HP_ALIGN NATURAL PUSH #endif #elif defined(HPUX_IA64) && defined(PIOM64) #define pmdcomt_packing "pack(8)" #pragma pack(8) #elif defined(SOLARIS) && defined(PIOM64) #define pmdcomt_packing "pack(8)" #pragma pack(8) #elif defined (AIX) #define pmdcomt_packing "options align=packed" #pragma options align=packed #elif !defined(HPUX) && !defined(SOLARIS) && !defined(__MVS__) \ && !defined(_WIN64) #define pmdcomt_packing "pack (push, 1)" #pragma pack (push, 1) #endif #if !defined (pmdcomt_packing) #define pmdcomt_packing "none" #endif
40
#define pmdcomt_HeaderVersion "Common 13.00.00.02" #define pmdcomt_ID "pmdcomt header version '" pmdcomt_HeaderVersion \ "', packing '" pmdcomt_packing "'" #ifdef PIOM64 #define pmInterfaceVersionD 1001 typedef unsigned int pmUInt32; #else #define pmInterfaceVersionD 1000 typedef unsigned long pmUInt32; #endif typedef unsigned short typedef pmUInt32 typedef short typedef int /* /* /* /* /* /* /* /* /* /* /* /* /* pmUInt16; pmReturnType;
/* 32-bit unsigned integer */ /* 32-bit unsigned integer */
/* 16-bit unsigned integer */ /* Return value type for */ /* all API functions */ pmOpenMode_t; /* Access Module mode for pmOpen */ pmTrceLvl_t; /* Trace level type */ */ */ */ */ */ */ */ */ */ */ */ */
Export widths information structure. An array of the structures is passed as the attribute value in EXPORT_WIDTHS put attribute request. In this case the attribute value length is the number of bytes occupied by the entire array. The export width information is used to calculate size in bytes of exported fixed-length character columns. This size depends not only on the number of characters in the data type (the n in CHAR(n)), but also on the selected session character set (for example, "UTF8"), and the server character type (specified in CHARACTER SET clause of the CREATE TABLE statement). The export width information passed in an EXPORT_WIDTHS instance put attribute request pertains to current session character set. Each structure passed in the array has information for one server character type. */
typedef struct pmExpWidth { pmUInt16 CharType; /* Server character type code. */ pmUInt16 ExpWidth; /* Export width. Contains the scale value that */ /* is to be multiplied by the number of */ /* characters in the data type. */ pmUInt16 ExpWidthAdj; /* Export width adjustment. Contains offset /* value added to the product of ExpWidth /* and number of characters in the data type in /* order to obtain the export width. } pmExpWidth_t; /* Media Position description structure typedef struct _pmPosData { pmUInt32 Length; char *Data; } pmPos_t; typedef struct _pmNameBuf { pmUInt32 DataLength; char *Data; } pmNameBuf_t; */ */ */ */ */
41

/* Access Module Version Identification structure #define pmMAX_VER_STR_LEN 31 typedef struct _pmVerLst_t { char ModuleName[pmMAX_VER_STR_LEN+1]; char ModuleVers[pmMAX_VER_STR_LEN+1]; struct _pmVerLst_t *Next; } pmVerLst_t; /* List #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define #define /* #define #define #define #define #define #define #define #define #define #define */
of return codes generated by any call to the API */ pmrcOK 0 /* All's well :: MUST BE ZERO !! :: */ pmrcBadpmHandle 1 /* Invalid pmHandle parameter passed */ pmrcBadParm 2 /* Bad parameter passed to API */ pmrcAXMNotFound 3 /* Requested Access Module not found */ pmrcFileNotFound 4 /* Requested file not found */ pmrcWriteOnly 5 /* Access Module is write only */ pmrcReadOnly 6 /* Access Module is read only */ pmrcBadFp 7 /* Invalid pmFp parameter passed */ pmrcOpenFiles 8 /* Access Module still has open files */ pmrcEOF 9 /* Access Module reached EOF */ pmrcCPReady 10 /* Access Module ready to checkpoint */ pmrcInvUtil 11 /* Invalid utility ID passed to pmInit */ pmrcAllocErr 12 /* Error encountered during memory mgmt */ pmrcBadOpenMode 13 /* Unsupported mode */ pmrcBadFormat 14 /* Unsupported format */ pmrcBadBlksize 15 /* Unsupported block size */ pmrcDataFormatErr 16 /* Unexpected data format */ pmrcBufferOverFlow 17 /* Record beyond buffer */ pmrcBadVer 18 /* info>InterfaceVerNo!=pmInterfaceVersion */ pmrcFNameTooLong 19 /* File name too long * / pmrcInitCmdSyntax 20 /* Access Module Init string syntax error */ pmrcInitInvCmd 21 /* Init string invalid command char */ pmrcInitInvOpt 22 /* Init string invalid cmd option */ pmrcPosDataInvL 23 /* Invalid positioning data length */ pmrcUnsupported 24 /* Unsupported feature */ pmrcKeepReading 25 /* Continue reading till end-of-buffer */ pmrcAXMnotReady 26 /* pmInit has not been called */ pmrcBadTraceLvl 27 /* Invalid diagnostic trace level */ pmrcOpenAXMs 28 /* Access Modules still open */ pmrcEmptyFile 29 /* Empty file on read open */ pmrcRedundant 30 /* Redundant pmInit call */ pmrcBadFormatInfo 31 /* Invalid Supplemental Format Info */ pmrcBadChkPtMode 32 /* Invalid Checkpointing mode */ pmrcBadAttrName 33 /* Unrecognized attribute name */ pmrcFailure 34 /* Indeterminate error. pmGetErrText() */ pmrcNoEOR 35 /* EOF before EOR on text data */ pmrcBufferSizeExcess 36 /* BufferSize exceeded by axsmod */ pmrcAMsymbolError 37 /* AM symbol resolution error */ shifted values for compatibility */ pmrcLRECLMismatch 38 /* USS: LRECL!=TWB schema length */ pmrcBadMBC 39 /* Bad multi-byte character found */ pmrcBadAttrValue 40 /* Invalid attribute value */ pmrcOnlyAfterAttach 41 /* Can't set AM attr after file open */ pmrcSignatureFailed 42 /* Unable to obtain data signature */ pmrcRestartDataMismatch 43 /*Data after restart doesn't match */ pmrcOnlyAfterOpen 44 /* Open attribute setting timing error */ pmrcEndianConflict 45 /* Requested endianess vs. file */ pmrcCharacterSetConflict 46 /*file UTF control v. characterset*/ pmrcBadAttrNameDC 50 /* attribute name unrecognized by DC */
42

#define pmrcBadAttrValueDC 51 #define pmrcTimeout 55 /* #define pmOpenModeR 1 #define pmOpenModeW 2 #define pmOpenModeRW 3 #define pmOpenMode_MAX 3 /* Shutdown modes */ #define pmShutDownNormal #define pmShutDownBrute /* Trace levels */ #define pmTrceNone #define pmTrceEvents #define pmTrceIOcounts #define pmTrceIObufs #define pmTrceInfo #define pmTrce_MAX 1 2 3 4 5 5 1 2 /* issue no trace messages */ /* attribute value rejected by DC */ /* An I/O has timed out */ Open modes (Read, Write, or ReadWrite) */ /* Read only */ /* Write only */ /* Read first, then write only */
/* Identify compiling platform */ #ifdef PIOM64 #define MODE "64-bit " #else #define MODE "32-bit " #endif /* For Solaris, get flavor. */ #ifdef SOLARIS #ifdef INTEL #define PLATFORM_ID MODE "Solaris/Intel" #endif #ifdef SPARC #define PLATFORM_ID MODE "Solaris/SPARC" #endif #ifdef OPTERON #define PLATFORM_ID MODE "Solaris/Opteron" #endif #ifndef PLATFORM_ID #define PLATFORM_ID MODE "Solaris" #endif #endif #ifdef I370 #define PLATFORM_ID MODE "IBM 370" #endif #ifdef MPRAS #define PLATFORM_ID MODE "MPRAS" #endif #ifdef WIN32 #define PLATFORM_ID MODE "WIN32" #endif #ifdef __MVS__ #ifdef PLATFORM_ID #undef PLATFORM_ID #endif #define PLATFORM_ID MODE "OS/390 USS" #endif #ifdef HPUX #define PLATFORM_ID MODE "HP-UX" #endif #ifdef AIX #define PLATFORM_ID MODE "IBM AIX" #endif
43
Chapter 4: Header File Examples pmddamt.h

#ifdef LINUX #define PLATFORM_ID MODE "LINUX" #endif #ifndef PLATFORM_ID #define PLATFORM_ID MODE "MPRAS (default)" #endif #ifdef UNIX5 #define UNIX5_compatible "yes" #else #define UNIX5_compatible "no" #endif #if defined(HPUX) && defined(PIOM64) && !defined(HPUX_IA64) #ifdef __cplusplus #pragma pack #else #pragma HP_ALIGN POP #endif #elif defined(HPUX_IA64) && defined(PIOM64) #pragma pack() #elif defined(SOLARIS) && defined(PIOM64) #pragma pack() #elif defined (AIX) #pragma options align=reset #elif !defined(HPUX) && !defined(SOLARIS) && !defined (__MVS__) \ && !defined(_WIN64) #pragma pack (pop) #endif #endif /* PMDCOMT_H */
pmddamt.h
This header file shows structure and symbol definitions required to interface with the Teradata PT DataConnector operator or an access module.
/* % TITLE pmddamt.h ... Device Dependent Access module structs/types */ / ***********************************************************************/ /* */ /* Copyright 1997-2008 Teradata Corporation. */ /* ALL RIGHTS RESERVED. */ /* Teradata Corporation CONFIDENTIAL AND TRADE SECRET */ /* */ /* This copyrighted material is the Confidential, Unpublished */ /* Property of the Teradata Corporation. This copyright notice */ /* and any other copyright notices included in machine readable */ /* copies must be reproduced on all authorized copies. */ /* */ /* CRITICAL USAGE NOTE: */ /* This header file is to be the EXACT same file for both SA & TPT. */ /* The cooresponding versions in /vob/tdcli & /vob/paralx must match */ /* The identiy will insure that the same access module will work with */ /* the standalone utilities AND the TPT DC operator */ /* */ /**********************************************************************/
44

#ifndef PMDDAMT_H #define PMDDAMT_H /#if defined(HPUX) && defined(PIOM64) && !defined(HPUX_IA64) #ifdef __cplusplus #define pmddamt_packing "pack 8" #pragma pack 8 #else #define pmddamt_packing "HP_ALIGN NATURAL PUSH" #pragma HP_ALIGN NATURAL PUSH #endif #elif defined(HPUX_IA64) && defined(PIOM64) #define pmddamt_packing "pack(8)" #pragma pack(8) #elif defined(SOLARIS) && defined(PIOM64) #define pmddamt_packing "pack(8)" #pragma pack(8) #elif defined (AIX) #define pmdcomt_packing "options align=packed" #pragma options align=packed #elif !defined(HPUX) && !defined(SOLARIS) && !defined(__MVS__) \ && !defined(_WIN64) #define pmddamt_packing "pack (push, 1)" #pragma pack (push, 1) #endif #if !defined (pmddamt_packing) #define pmddamt_packing "none" #endif #define pmddamt_HeaderVersion "Common 13.00.00.02" /* SRC_ID */ #define pmddamt_ID "pmddamt header version '" pmddamt_HeaderVersion \ "', packing '" pmddamt_packing "'" #ifdef PIOM64 #define pmiInterfaceVersion #else #define pmiInterfaceVersion #endif 2001 2000
#define pmiMAX_EC_LEN 30 /* EyeCatcher strings for each structure type */ #define pmiEC_CmdBlock_t "AXSMOD block:CmdBlock_t" #define pmiEC_Init_t "AXSMOD block:Init_t" #define pmiEC_Open_t "AXSMOD block:Open_t" #define pmiEC_Close_t "AXSMOD block:Close_t" #define pmiEC_RW_t "AXSMOD block:RW_t" #define pmiEC_Pos_t "AXSMOD block:Pos_t" #define pmiEC_Shut_t "AXSMOD block:Shut_t" #define pmiEC_ID_t "AXSMOD block:ID_t" #define pmiEC_Attr_t "AXSMOD block:Attr_t" #define pmiMAX_INIT_STR_LEN 512 #define pmiMAX_FNAME_LEN 255 #define pmiMAX_ETEXT_LEN 32000 /* the following defines are required only for */ /* communications between the DIAM and the DDAM */ #define pmiPIDMOptInit 1
45

#define #define #define #define #define #define #define #define #define #define #define #define #define pmiPIDMOptOpen pmiPIDMOptClose pmiPIDMOptCloseR pmiPIDMOptRead pmiPIDMOptWrite pmiPIDMOptGetPos pmiPIDMOptSetPos pmiPIDMOptShut pmiPIDMOptID pmiPIDMOptGetA_A pmiPIDMOptGetF_A pmiPIDMOptPutA_A pmiPIDMOptPutF_A 2 3 10 4 5 6 7 8 9 11 12 13 14
typedef struct _pmiInit { char EyeCatcher[pmiMAX_EC_LEN]; /* Struct eyecatcher string pmUInt32 StructLength; /* Length of this structure void *PIData; /* Access module Internal Data Pointer pmUInt16 InterfaceVerNo; /* pmdcomt.h version identifier pmUInt16 InterfaceVerNoD; /* pmddamt.h version identifier pmUInt32 ClientIDL; /* Length of ClientID field pmUInt32 InitStrL; /* Length of InitStr field char ClientID[pmMAX_CLIENT_ID+1]; /* Client identifier char InitStr[pmiMAX_INIT_STR_LEN+1]; /* Initialization field } pmiInit_t;
*/ */ */ */ */ */ */ */ */
typedef struct _pmiOpen { char EyeCatcher[pmiMAX_EC_LEN]; /* Struct eyecatcher string pmUInt32 StructLength; /* Length of this structure void *PIData; /* Access module Internal Data Pointer pmOpenMode_t OpenMode; /* provided to PIDM pmUInt16 BlkHeaderLen; /* defined by PIDM pmUInt32 BlkSize; /* defined by PIDM void *FIData; /* File Internal Data (returned/used by PIDM) pmUInt16 FileNameL; /* provided to PIDM char FileName[pmiMAX_FNAME_LEN+1]; /* provided to PIDM } pmiOpen_t; typedef struct _pmiClose { char EyeCatcher[pmiMAX_EC_LEN]; pmUInt32 StructLength; void *FIData; } pmiClose_t; typedef struct _pmiRW { char EyeCatcher[pmiMAX_EC_LEN]; pmUInt32 StructLength; void *FIData; pmUInt32 BufferLen; char *Buffer; } pmiRW_t; typedef struct _pmiPos { char EyeCatcher[pmiMAX_EC_LEN];
*/ */ */ */ */ */ */ */ */
/* Struct eyecatcher string */ /* Length of this structure */
/* Struct eyecatcher string */
46

pmUInt32 StructLength; void *FIData; pmPos_t Position; } pmiPos_t; typedef struct _pmiShut { char EyeCatcher[pmiMAX_EC_LEN]; pmUInt32 StructLength; void *PIData; pmUInt16 Mode; } pmiShut_t; typedef struct _pmiID { char EyeCatcher[pmiMAX_EC_LEN]; pmUInt32 StructLength; pmVerLst_t VerIDList; } pmiID_t; /* Length of this structure */
typedef struct _pmiAttribute { char EyeCatcher[pmiMAX_EC_LEN]; /* Struct eyecatcher string pmUInt32 StructLength; /* Length of this structure void *ObjData; /* Object pointer (PIData or FIData) pmUInt32 AttrNameLen; /* Length of attribute name char AttrName[pmMAX_ATR_NAME_LEN]; /* Attrribute name pmUInt32 AttrValueLen; /* Length of attribute value char AttrValue[pmMAX_ATR_VAL_LEN]; /* Attribute value } pmiAttr_t;
*/ */ */ */ */ */ */
typedef struct _pmiCmdBlock { char EyeCatcher[pmiMAX_EC_LEN]; /* Struct eyecatcher string pmUInt32 StructLength; /* Length of this structure pmUInt32 Reqtype; pmReturnType Retcode; /* set by DDAM pmTrceLvl_t TraceLvl; pmNameBuf_t ErrMsg; /* Set by DDAM if retcode is pmrcFailure } pmiCmdBlock_t;
*/ */ */ */
#ifdef WIN32 #ifdef CPP extern "C" { __declspec(dllexport) void PIDMMain ( pmiCmdBlock_t *, void * ); } #else __declspec(dllexport) void PIDMMain ( pmiCmdBlock_t *, void * ); #endif #else void PIDMMain ( pmiCmdBlock_t *, void * ); #endif #if defined(HPUX) && defined(PIOM64) && !defined(HPUX_IA64) #ifdef __cplusplus #pragma pack #else #pragma HP_ALIGN POP
47

#endif #elif defined(HPUX_IA64) && defined(PIOM64) #pragma pack() #elif defined(SOLARIS) && defined(PIOM64) #pragma pack() #elif defined (AIX) #pragma options align=reset #elif !defined(HPUX) && !defined(SOLARIS) && !defined(__MVS__) \ && !defined(_WIN64) #pragma pack (pop) #endif #endif /* PMDDAMT_H */
48
Sample Program and Makefile
APPENDIX A
This appendix provides a sample access module program and a makefile.
Sample Program
amsample.c
/****************************************************************************/ /* */ /* Copyright 1997-2008 Teradata Corporation. */ /* ALL RIGHTS RESERVED. */ /* Teradata Corporation CONFIDENTIAL AND TRADE SECRET */ /* */ /* This copyrighted material is the Confidential, Unpublished */ /* Property of the Teradata Corporation. This copyright notice */ /* and any other copyright notices included in machine readable */ /* copies must be reproduced on all authorized copies. */ /* */ /* Purpose: Present a sample access module that */ /* generates arbitrary data blocks without I/O */ /* */ /* Max reads accepted is 100000000 */ /* Max logical records per block is 100000 */ /* */ /* */ /* Data returned conforms to the following TeraBuilder schema: */ /* DEFINE SCHEMA PRODUCT_SOURCE_SCHEMA */ /* DESCRIPTION 'PRODUCT INFORMATION SCHEMA' */ /* ( */ /* COL1 INTEGER, */ /* COL2 INTEGER, */ /* COL3 INTEGER, */ /* COL4 VARCHAR(7) */ /* ); */ /* */ /* Initialization string: */ /* "BLOCKCOUNT=<i>,RECORDCOUNT=<j>,TRACE <filename> <tracelevel>" */ /* */ /* Contents: */ /* PIDMMain - receives all Access Module calls from the */ /* Teradata Client Utility via the Data Connector. */ /* */ /****************************************************************************/ #include <stdio.h> #include <string.h>
49
Appendix A: Sample Program and Makefile Sample Program

#include "pmdcomt.h" #include "pmddamt.h" /*#define TPT_VERSION 1 */ #ifdef TPT_VERSION #define MODULE_NAME "amsample_TPT" #define ENVIRONMENT "Teradata Parallel Transporter" #else #define MODULE_NAME "amsample_SA" #define ENVIRONMENT "Teradata Standalone Utilities" #endif #define MODULE_VERS "13.00.00.02" /*#define TEST_TIMEOUT 1 */ /* Initialization string keywords */ #define MAX_PARMS 256 /* maximum init string parms accepted */ #define Help_KEYWORD "HELP" /* SRC_ID */
/* Number of blocks to return */ #define BlockCount_KEYWORD "BLOCKCOUNT" #define BlockCount_MAX 100000000 #define BlockCount_DEFAULT 10 /* Number of records returned per block */ #define RecordsPerBlock_KEYWORD "RECORDCOUNT" #define RecordsPerBlock_MAX 100000 #define RecordsPerBlock_DEFAULT 10 /* Log file name */ #define Trace_KEYWORD "TRACE" static static static static char size_t pmTrceLvl_t FILE SG_ErrorText[pmiMAX_ETEXT_LEN+1]; SG_ErrorTextLen=0; SG_TraceLevel=pmTrceEvents; *SG_AMlogFp=NULL; AXMAttr_1[] = "AXSM AXM attribute #1 value"; FileAttr_1[] = "AXSM File attribute #1 value";
static char static char static static static static
unsigned long SG_BlocksToEOF; unsigned long SG_RecsPerBlock; char AMlogFName[pmiMAX_FNAME_LEN+1]; long SG_TimeOutSeconds;
typedef struct _LogRec { pmUInt16 RecLength; pmUInt16 Filler1; pmUInt32 I_RecNum; pmUInt32 I_block; pmUInt32 I_Dummy; pmUInt16 Filler2; pmUInt16 I_charlen; char V_char[7]; char EOR; } LogRec_t;
50

#define MAX_MSGSTR_LEN 1024 #define TRACE_LOG_MAX_LENGTH MAX_MSGSTR_LEN+256 static char MsgStr[MAX_MSGSTR_LEN]; /* MACRO definitions */ #define TRCELOG(MsgTraceLevel,Format,variable) if ( SG_TraceLevel>=MsgTraceLevel ) { char Trcetext[TRACE_LOG_MAX_LENGTH]; sprintf (Trcetext,Format,variable); AMlog(Trcetext); } #define EXIT_FAILURE() \ SG_ErrorTextLen = strlen(SG_ErrorText); \ AMstdout(SG_ErrorText); \ return pmrcFailure; #define CHECK_ARG_PRESENT(index) \ if ( index+1 >= argc )\ {\ sprintf (SG_ErrorText,"option %s: argument missing",argv[index]);\ EXIT_FAILURE();\ }\ if ( strlen(argv[index+1]) == 0 )\ {\ sprintf (SG_ErrorText,"option %s: argument missing",argv[index]);\ EXIT_FAILURE();\ } ***********************************************************************/ /* AMlog */ ***********************************************************************/ static void AMlog ( char *str ) { if ( SG_AMlogFp != NULL ) { fprintf (SG_AMlogFp,"%s\n",str); fflush (SG_AMlogFp); } return; } /***********************************************************************/ /* AMstdout */ /* (Access Module standard output) */ /* Used when trace file not open. */ /***********************************************************************/ static void AMstdout ( char *str ) { /* If used with Teradata Parallel Transporter, */ /* stdout may by blocked (bit-bucket) */ /* Send all stdout to a predefined file. */ /* (could be a parameter) */ #if defined (TPT_VERSION) #define AMstdoutFName "AMstdout.txt" static FILE *AMstdoutFp=NULL; \ \ \ \ \ \
51
if ( AMstdoutFp == NULL ) AMstdoutFp = fopen(AMstdoutFName,"w"); if ( AMstdoutFp != NULL ) { fprintf (AMstdoutFp,"%s: %s\n",MODULE_NAME,str); fflush (AMstdoutFp); } /* If used with Standalone Utilities, stdout is available */ #else printf ( "%s: %s\n",MODULE_NAME,str ); #endif AMlog(str); /* ALL stdout should be in log */ return; } /**********************************************************************/ /* ShowParms */ /* Display AM parameters */ /**********************************************************************/ #undef CurrentFunction #define CurrentFunction "ShowParms" static void ShowParms ( ) { AMstdout("Parameters:"); /* Help */ sprintf(MsgStr,"%s: Show this information\n\tsyntax %s", Help_KEYWORD,Help_KEYWORD); AMstdout(MsgStr); /* BLOCKCOUNT <value> */ sprintf(MsgStr,"%s: %s\n\t%s\n\tsyntax: %s %s %d\n\t%s %d", BlockCount_KEYWORD, "Specifies the number of record blocks to return.", "When this value has been satisfied, an end-of-file will be returned.", BlockCount_KEYWORD, "<count> where <count> is within the range of 1 to", BlockCount_MAX, "the default is", BlockCount_DEFAULT); AMstdout(MsgStr); /* RECORDCOUNT <value> */ sprintf(MsgStr,"%s: %s\n\tsyntax: %s %s %d\n\t%s %d", RecordsPerBlock_KEYWORD, "Specifies the number of records returned in each block.", RecordsPerBlock_KEYWORD, "<count> where <count> is within the range of 1 to", RecordsPerBlock_MAX, "the default is", RecordsPerBlock_DEFAULT); AMstdout(MsgStr); /* TRACE <filename> <tracelevel> */ sprintf(MsgStr,"%s: %s\n\tsyntax: %s %s \n\t%s \n\t%s %d and %d", Trace_KEYWORD, "Specifies both the filename and trace level for the log", Trace_KEYWORD,
52

"<filename> <tracelevel>", "where <filename> is any valid file system object", "and <tracelevel> is between", pmTrceNone,pmTrceInfo); AMstdout(MsgStr); return; } /**********************************************************************/ /* ParseParms */ /* parse init string */ /**********************************************************************/ #undef CurrentFunction #define CurrentFunction "ParseParms" static pmReturnType ParseParms ( pmiInit_t* Parms ) { char *pParameter; int i, j, ipos, ioffs, rc; pmReturnType retcode; char int int int *argv[MAX_PARMS]; argc; initstrl; bUseParmFile = 0;
if ((initstrl = Parms->InitStrL) > 0) pParameter = Parms->InitStr; else { sprintf(SG_ErrorText,"!ERROR! Empty initialization string"); EXIT_FAILURE(); } /* =================================== convert initstr to argc argv */ ipos = ioffs = 0; argc = 0; for (i=0;i<MAX_PARMS;i++) argv[i] = 0; while (ipos < initstrl) { /* get offset to next non-whitespace */ ioffs = strspn(&pParameter[ipos]," \n\t\r\f"); ipos = ipos + ioffs; if (ipos >= initstrl) break; /* get offset to next whitespace */ ioffs = strcspn(&pParameter[ipos]," \n\t\r\f\0"); if ( argc > MAX_PARMS-1 ) { sprintf(SG_ErrorText,"Too many initialization string parameters"); EXIT_FAILURE(); } argv[argc] = (char*)malloc(ioffs+1); strncpy(argv[argc],&(pParameter[ipos]),ioffs); memcpy(argv[argc]+(ioffs),"\0",1); ipos = ipos+ioffs; argc++; } if ( argc < 1 ) { sprintf(SG_ErrorText,"Empty initialization string"); EXIT_FAILURE();
53

} argv[argc] = 0; SG_BlocksToEOF = 0; SG_RecsPerBlock = 0; AMlogFName[0] = '\0'; SG_TraceLevel = pmTrceNone; /* ============================ process initstr arguments and values */ i=0; retcode = pmrcOK; do { int bValidKeywordFound = 0; char KeyWord[100]; for (j=0;j<strlen(argv[i]);j++) argv[i][j] = toupper(argv[i][j]); strcpy(KeyWord,argv[i]); sprintf(MsgStr,"Parameter Keyword: '%s'",KeyWord); AMstdout(MsgStr); if ( !strcmp(KeyWord,Help_KEYWORD) ) { ShowParms(); bValidKeywordFound = 1; i++; } if ( !strcmp(KeyWord,BlockCount_KEYWORD) ) { CHECK_ARG_PRESENT (i); SG_BlocksToEOF = atol (argv[i+1]); if ( SG_BlocksToEOF > BlockCount_MAX || SG_BlocksToEOF < 1 ) { sprintf SG_ErrorText,"Invalid '%s' keyword value (%d). %s %d", KeyWord,SG_BlocksToEOF, "Valid range is 1 to",BlockCount_MAX); EXIT_FAILURE(); } bValidKeywordFound = 1; i = i + 2; } if ( !strcmp(KeyWord,RecordsPerBlock_KEYWORD) ) { CHECK_ARG_PRESENT (i); SG_RecsPerBlock = atol (argv[i+1]); if ( SG_RecsPerBlock > RecordsPerBlock_MAX || SG_RecsPerBlock < 1 ) { sprintf (SG_ErrorText,"Invalid '%s' keyword value (%d). %s %d", KeyWord,SG_RecsPerBlock, "Valid range is 1 to",RecordsPerBlock_MAX); EXIT_FAILURE(); } bValidKeywordFound = 1; i = i + 2; } if ( !strcmp(KeyWord,Trace_KEYWORD) ) { CHECK_ARG_PRESENT (i);
54

if ( strlen(argv[i+1]) > pmiMAX_FNAME_LEN ) { sprintf (SG_ErrorText,"Invalid '%s' keyword value (%s). %s %d", KeyWord,argv[i+1], "Maximum length is",pmiMAX_FNAME_LEN ); EXIT_FAILURE(); } strcpy(AMlogFName,argv[i+1]); if ( argc < i+2 ) { sprintf (SG_ErrorText,"Keyword '%s' %s (trace level) expected", KeyWord,"second parmameter"); EXIT_FAILURE(); } SG_TraceLevel = atol (argv[i+2]); if ( SG_TraceLevel < pmTrceNone || SG_TraceLevel> pmTrceInfo ) { sprintf (SG_ErrorText,"Invalid '%s' %s (%d). %s %d to %d", KeyWord,"keyword value",SG_TraceLevel, "Valid range is",pmTrceNone,pmTrceInfo); EXIT_FAILURE(); } bValidKeywordFound = 1; i = i + 3; } if ( !bValidKeywordFound ) { sprintf(MsgStr,"Keyword '%s' ignored - not recognized",KeyWord); AMstdout(MsgStr); i++; } while ( i<argc && retcode == pmrcOK ); free(argv[i]);}
/* free up memory */ for (i=0;i<MAX_PARMS;i++) {if (argv[i] != 0)
/* =============== Confirm that required parameters have been defined */ /* and display parameters in effect */ if ( !SG_BlocksToEOF ) { SG_BlocksToEOF = BlockCount_DEFAULT; sprintf(MsgStr,"Keyword '%s' not provided. %s.",BlockCount_KEYWORD, "It's value will be set to the default"); AMstdout(MsgStr); } sprintf(MsgStr,"Keyword '%s' value defined as %d.", BlockCount_KEYWORD,SG_BlocksToEOF); AMstdout(MsgStr); if ( !SG_RecsPerBlock ) { SG_RecsPerBlock = RecordsPerBlock_DEFAULT; sprintf(MsgStr,"Keyword '%s' not provided. %s.",RecordsPerBlock_KEYWORD, "It's value will be set to the default"); AMstdout(MsgStr); }
55

sprintf(MsgStr,"Keyword '%s' value defined as %d.", RecordsPerBlock_KEYWORD,SG_RecsPerBlock); AMstdout(MsgStr); if ( strlen(AMlogFName) ) { sprintf(MsgStr,"Keyword '%s' value defined as '%s' '%d'", Trace_KEYWORD,AMlogFName,SG_TraceLevel); } else sprintf(MsgStr,"Keyword '%s' not defined",Trace_KEYWORD); AMstdout(MsgStr); return pmrcOK; } /****************************************************************************/ /****************************************************************************/ /* Main routine */ /****************************************************************************/ /****************************************************************************/ #ifdef WIN32 __declspec(dllexport) #endif void PIDMMain ( pmiCmdBlock_t *Opts, void *OptParms ) { pmReturnType retcode=pmrcOK; static pmUInt32 SG_BufferLen; static pmUInt32 SG_rec_cnt; static pmUInt32 SG_block_cnt; static LogRec_t SG_LogicalRecords[RecordsPerBlock_MAX]; pmUInt32 i; pmUInt16 RecLength; char *cptr; static bHeadersAnnounced = 0; char AtrName[pmMAX_ATR_NAME_LEN+1]; /* /* /* /* /* Announce which version of the header files were used at compile time. If the wrong headers, or packing option, were used, everything goes south without explanation. We do this before any of the parameters are referenced. So, if things go awry, we'll know if this was the problem. */ */ */ */ */
if ( !bHeadersAnnounced ) { AMstdout(PM_COPYRIGHT_NOTICE); sprintf ( MsgStr,"Sample Access Module ('%s') Version: %s.", MODULE_NAME,MODULE_VERS); AMstdout(MsgStr); sprintf (MsgStr,"Compiled for %s (%s).",PLATFORM_ID,ENVIRONMENT); AMstdout(MsgStr); AMstdout(pmdcomt_ID); AMstdout(pmddamt_ID); bHeadersAnnounced = 1; } /****************************************************************************/ /* This is the main decision block */ /* Specific action taken is determined by the value */ /* of the Reqtype field in the Opts parameter */
56

/****************************************************************************/ switch (Opts->Reqtype) /* switch on request type */ { /*--------------------------------------------------------------------------*/ /* AXSM Initialization */ /*--------------------------------------------------------------------------*/ case pmiPIDMOptInit: TRCELOG(pmTrceInfo,"%s","Entry pmiPIDMOptInit"); /* Make sure the the headers used by the DataConnector /* are the same versions that this AXSM used /* when compiling! */ */ */
if ( ((pmiInit_t*)OptParms)->InterfaceVerNo != pmInterfaceVersionD || ((pmiInit_t*)OptParms)->InterfaceVerNoD != pmiInterfaceVersion ) retcode = pmrcBadVer; /* Set that all important AXSM identifying void pointer /* that the AXSM can use for anything ((pmiInit_t*)OptParms)->PIData = 0; /* Examine init string */ retcode = ParseParms( (pmiInit_t*)OptParms ); if ( retcode ) break; if ( SG_TraceLevel > pmTrceNone ) { SG_AMlogFp = fopen(AMlogFName,"w"); if ( SG_AMlogFp == NULL ) AMstdout("Trace log file open failed!"); } AMlog(PM_COPYRIGHT_NOTICE); sprintf (MsgStr,"Sample Access Module ('%s') Version: %s.", MODULE_NAME,MODULE_VERS); AMlog(MsgStr); sprintf (MsgStr,"Compiled for %s (%s).",PLATFORM_ID,ENVIRONMENT); AMlog(MsgStr); AMlog(pmdcomt_ID); AMlog(pmddamt_ID); switch ( SG_TraceLevel ) { case pmTrceNone: sprintf (MsgStr,"Trace level set to 'None' (%d)",pmTrceNone); break; case pmTrceEvents: sprintf (MsgStr,"Trace level set to 'Events' (%d)", pmTrceEvents); break; case pmTrceIOcounts: sprintf (MsgStr,"Trace level set to 'IOcounts' (%d)", pmTrceIOcounts); break; case pmTrceIObufs: sprintf (MsgStr,"Trace level set to 'IObufs' (%d)", pmTrceIObufs); break; case pmTrceInfo: sprintf (MsgStr,"Trace level set to 'Info' (%d)",pmTrceInfo); */ */
57

break; default: sprintf (MsgStr,"%s (%d) %s (%d)", "Invalid trace level",SG_TraceLevel, "reset to 'Events'",pmTrceEvents); SG_TraceLevel = pmTrceEvents; } AMlog(MsgStr); sprintf (MsgStr,"AM will provide %d blocks of %d records each %s", SG_BlocksToEOF,SG_RecsPerBlock, "in 'FastLoad' format (pmIDFBin1Plus)"); AMstdout(MsgStr); break; /*--------------------------------------------------------------------------*/ /* File Open */ /*--------------------------------------------------------------------------*/ case pmiPIDMOptOpen: TRCELOG(pmTrceInfo,"%s","Entry pmiPIDMOptOpen"); SG_block_cnt = 0; SG_BufferLen = 0; SG_rec_cnt = 0; /* /* /* set 'blocks read' to zero */ /* Initialize 'actual' buffer length */ /* set 'records generated' to zero */
Fill in 'SG_LogicalRecords' for subsequent reads */ Format as 'text' data (trailing EOR byte) */ RecLength = sizeof(SG_LogicalRecords[0]) sizeof(SG_LogicalRecords[0].RecLength) sizeof(SG_LogicalRecords[0].EOR); for (i=0;i<SG_RecsPerBlock;i++) { SG_LogicalRecords[i].RecLength = RecLength; SG_LogicalRecords[i].I_RecNum = 0; SG_LogicalRecords[i].I_block = 1; SG_LogicalRecords[i].I_Dummy = 222; SG_LogicalRecords[i].I_charlen = 7; strcpy(SG_LogicalRecords[i].V_char,"XasciiX"); SG_LogicalRecords[i].EOR = 0x0a; } SG_BufferLen = SG_RecsPerBlock*sizeof(SG_LogicalRecords[0]);
/* Fill in device max block size, internal header length /* and that all important file identifying void pointer /* that the Access Module can use for anything
*/ */ */
((pmiOpen_t*)OptParms)->BlkSize = SG_BufferLen; ((pmiOpen_t*)OptParms)->BlkHeaderLen = 0; ((pmiOpen_t*)OptParms)->FIData = 0; break; /*--------------------------------------------------------------------------*/ /* File Close */ /*--------------------------------------------------------------------------*/ case pmiPIDMOptClose: case pmiPIDMOptCloseR: TRCELOG(pmTrceInfo,"%s","Entry pmiPIDMOptClose[R]"); break;
58

/*--------------------------------------------------------------------------*/ /* Read */ /*--------------------------------------------------------------------------*/ case pmiPIDMOptRead: TRCELOG(pmTrceInfo,"%s","Entry pmiPIDMOptRead"); /* EOF? */ SG_block_cnt++; if ( SG_block_cnt > SG_BlocksToEOF ) { TRCELOG(pmTrceEvents,"%s","End-of-File"); ((pmiRW_t*)OptParms)->BufferLen = 0; retcode = pmrcEOF; break; } #ifdef TEST_TIMEOUT if ( SG_block_cnt > 1 ) { TRCELOG(pmTrceEvents,"%s","Arbitrary timeout"); ((pmiRW_t*)OptParms)->BufferLen = 0; retcode = pmrcTimeout; break; } #endif /* Update MyBuffer for this read */ for (i=0;i<SG_RecsPerBlock;i++) { SG_rec_cnt++; SG_LogicalRecords[i].I_RecNum = SG_rec_cnt; SG_LogicalRecords[i].I_block = SG_block_cnt; } /* Copy generated block to DataConnector buffer */ memcpy( ((pmiRW_t*)OptParms)->Buffer,SG_LogicalRecords,SG_BufferLen); /* Return the record length */ ((pmiRW_t*)OptParms)->BufferLen = SG_BufferLen; if ( SG_AMlogFp != NULL ) { TRCELOG(pmTrceInfo,"%s","calling amHexDmp() for local copy"); amHexDmp ( SG_AMlogFp,(char *)SG_LogicalRecords, (unsigned)SG_BufferLen,"i->",1); TRCELOG(pmTrceInfo,"%s","calling amHexDmp() for interface copy"); amHexDmp ( SG_AMlogFp,(char *)((pmiRW_t*)OptParms)->Buffer, (unsigned)((pmiRW_t*)OptParms)->BufferLen,"x->",1); } TRCELOG(pmTrceInfo,"%s","Exit pmiPIDMOptRead"); break; /*--------------------------------------------------------------------------*/ /* Get and Put Access Module or File attributes */ /*--------------------------------------------------------------------------*/ case pmiPIDMOptGetA_A: TRCELOG(pmTrceInfo,"%s","Entry pmiPIDMOptGetA_A"); strcpy (AtrName,((pmiAttr_t*)OptParms)->AttrName); if ( strcmp(AtrName,"AXMAttribute#1") ) {
59

sprintf(MsgStr,"Attribute '%s' not recognized. %s", AtrName,"Value can not be supplied"); retcode = pmrcBadAttrName; } else { sprintf(MsgStr,"Attribute '%s' recognized. %s '%s' returned", AtrName,"Value",AXMAttr_1); strcpy(&((pmiAttr_t*)OptParms)->AttrValue[0],AXMAttr_1); ((pmiAttr_t*)OptParms)->AttrValueLen = strlen(AXMAttr_1); } break; case pmiPIDMOptGetF_A: TRCELOG(pmTrceInfo,"%s","Entry pmiPIDMOptGetF_A"); strcpy (AtrName,((pmiAttr_t*)OptParms)->AttrName); if ( strcmp(AtrName,"FileAttribute#1") ) { sprintf(MsgStr,"Attribute '%s' not recognized. %s", AtrName,"Value can not be supplied"); retcode = pmrcBadAttrName; } else { sprintf(MsgStr,"Attribute '%s' recognized. %s '%s' returned", AtrName,"Value",FileAttr_1); strcpy(&((pmiAttr_t*)OptParms)->AttrValue[0],FileAttr_1); ((pmiAttr_t*)OptParms)->AttrValueLen = strlen(FileAttr_1); } AMstdout(MsgStr); break; /* Handle/receive attributes with access module scope */ case pmiPIDMOptPutA_A: TRCELOG(pmTrceInfo,"%s","Entry pmiPIDMOptPutA_A"); strcpy (AtrName,((pmiAttr_t*)OptParms)->AttrName); sprintf (MsgStr,"Received AXSMOD attribute '%s'",AtrName); TRCELOG(pmTrceEvents,"%s",MsgStr); sprintf (MsgStr,"Checking for valid %s attributes",ENVIRONMENT); TRCELOG(pmTrceEvents,"%s",MsgStr); /* TPT_VERSION symbol */ /* tells us that we're compiling for use with the */ /* Teradata Parallel Transporter environment */ #ifdef TPT_VERSION { #include "pxoper.h" PX_OperatorHandle operatorHandle; char *cPtr; PX_Length PX_Len; PXSTC_Code PX_rc; /* TPT operator handle */ #define MY_TPT_DC_ATTR_VALUE "SAMPLE_ATTR_CHAR_VALUE" #define AM_ATTR_TPT_DCOP_AM_NAME "AccessModuleName" if ( strcmp(AtrName,PM_ATR_TPT_OP_HANDLE)) { sprintf (MsgStr,"Rejected attribute: '%s'",AtrName); AMstdout(MsgStr); retcode = pmrcBadAttrName; break; }
60

sprintf (MsgStr,"Recognized attribute: '%s'",AtrName); AMstdout(MsgStr); memcpy((char*)&operatorHandle,((pmiAttr_t*)OptParms)->AttrValue, ((pmiAttr_t*)OptParms)->AttrValueLen); sprintf(MsgStr,"%s: operatorHandle=x'%x'",MODULE_NAME,operatorHandle); TRCELOG(pmTrceEvents,"%s",MsgStr); /* With the Teradata Parallel Transporter operator handle, /* All the TPT DataConnector operator attributes are available. /* /* /* /* First, we get the access module name attribute. This attribute is the name of this module and must have existed in order to get this access module running. The symbol AM_ATTR_TPT_DCOP_AM_NAME is defined in pxoper.h sprintf (MsgStr,"Retrieving attribute '%s'",AM_ATTR_TPT_DCOP_AM_NAME); AMstdout(MsgStr); PX_rc = PX_GetAttribute(operatorHandle, AM_ATTR_TPT_DCOP_AM_NAME, (PX_AttributeValue*)&cPtr,&PX_Len); if ( PX_rc == PX_NotFound ) sprintf (MsgStr,"Attribute '%s' not found.", AM_ATTR_TPT_DCOP_AM_NAME); else if ( PX_rc ) sprintf (MsgStr,"PX_GetAttribute failed, rc=%d", AM_ATTR_TPT_DCOP_AM_NAME); else sprintf (MsgStr,"Retrieved attribute value '%s'",cPtr); AMstdout(MsgStr); /* /* /* /* The symbol MY_TPT_DC_ATTR_VALUE is defined within this access module. As it is used here, it is a VARCHAR and appears in the DataConnector's attribute definition list as: VARCHAR SAMPLE_ATTR_CHAR_VALUE, */ */ */ */ */ */ */ */ */ */
sprintf (MsgStr,"Retrieving attribute '%s'",MY_TPT_DC_ATTR_VALUE); AMstdout(MsgStr); PX_rc = PX_GetAttribute(operatorHandle, MY_TPT_DC_ATTR_VALUE, (PX_AttributeValue*)&cPtr,&PX_Len); if ( PX_rc == PX_NotFound ) sprintf (MsgStr,"Attribute '%s' not found.",MY_TPT_DC_ATTR_VALUE); else if ( PX_rc ) sprintf (MsgStr,"PX_GetAttribute failed, rc=%d", MY_TPT_DC_ATTR_VALUE,PX_rc); else sprintf (MsgStr,"Retrieved attribute value '%s'",cPtr); AMstdout(MsgStr); } #else /* Handle attributes received from the standalone utilities { /* ATTRIBUTE DEFINES SHOULD (but do not have to) BE IN HEADER /* pmdcomt.h - available to AMs and DC clients if (!strcmp(AtrName,PM_ATR_NAME_TIMEOUT)) { char AtrValue[100]; strcpy (AtrValue,((pmiAttr_t*)OptParms)->AttrValue); SG_TimeOutSeconds = atol (AtrValue); sprintf (MsgStr,"Recognized attribute: '%s' = %d seconds", AtrName,SG_TimeOutSeconds); */ */ */
61

} else if (!strcmp(AtrName,PM_ATR_NAME_CHARSET_NAME) || !strcmp(AtrName,PM_ATR_NAME_CHARSET_NUMBER) || !strcmp(AtrName,PM_ATR_NAME_WR_BOM) || !strcmp(AtrName,PM_ATR_NAME_BYTE_ORDER) ) { sprintf (MsgStr,"Recognized attribute: '%s' %s", AtrName,"(no action taken)"); } else { sprintf (MsgStr,"Unrecognized attribute: '%s'",AtrName); retcode = pmrcBadAttrName; } AMstdout(MsgStr); } #endif break; case pmiPIDMOptPutF_A: TRCELOG(pmTrceInfo,"%s","Entry pmiPIDMOptPutF_A"); strcpy (AtrName,((pmiAttr_t*)OptParms)->AttrName); sprintf (MsgStr,"Received FILE attribute '%s'",AtrName); TRCELOG(pmTrceEvents,"%s",MsgStr); if ( !strcmp( AtrName,"FileAttribute#1") ) { sprintf (MsgStr,"Recognized attribute: '%s' %s", AtrName,"(no action taken)"); } else { sprintf (MsgStr,"Unrecognized attribute: '%s'",AtrName); retcode = pmrcBadAttrName; } AMstdout(MsgStr); break; /*--------------------------------------------------------------------------*/ /* Access Module shutdown */ /*--------------------------------------------------------------------------*/ case pmiPIDMOptShut: TRCELOG(pmTrceInfo,"%s","Entry pmiPIDMOptShut"); /* If any files are currently open, close them */ retcode = pmrcOK; break; /*--------------------------------------------------------------------------*/ /* Access Module identification */ /*--------------------------------------------------------------------------*/ case pmiPIDMOptID: TRCELOG(pmTrceInfo,"%s","Entry pmiPIDMOptID"); /* /* /* Supply the single module name for this Access Module identification */ If more modules are added, their identifying information */ must be appended to the list via VerIDList.Next */
strcpy( ((pmiID_t*)OptParms)->VerIDList.ModuleName,MODULE_NAME); strcpy( ((pmiID_t*)OptParms)->VerIDList.ModuleVers,MODULE_VERS); ((pmiID_t*)OptParms)->VerIDList.Next = 0; break; /*--------------------------------------------------------------------------*/ /* NULL ops for checkpoint */
62
Appendix A: Sample Program and Makefile Sample Makefile

/*--------------------------------------------------------------------------*/ case pmiPIDMOptGetPos: case pmiPIDMOptSetPos: break; default: /* Handle unknown request type */ retcode = pmrcUnsupported; } /* end switch on request type */ /* Insert the established return code into the command block /* for return DataConnector Opts->Retcode = retcode; /* If there's a Access Module specific error, indicated by a return code /* of pmrcFailure, insert the associated error text into /* the command block for return to the DataConnector if ( retcode == pmrcFailure ) { Opts->ErrMsg.Data = &SG_ErrorText[0]; Opts->ErrMsg.DataLength = SG_ErrorTextLen; } else { Opts->ErrMsg.Data = 0; Opts->ErrMsg.DataLength = 0; } sprintf(MsgStr,"Returnning retcode=%d",retcode); if ( retcode ) { TRCELOG(pmTrceEvents,"%s",MsgStr); } else { TRCELOG(pmTrceInfo,"%s",MsgStr); } return; } */ */ */ */ */
Sample Makefile
Before running the makefile, set the symbol INCDIR to the directory in which pmddamt.h and pmdcomt.h are stored. Set the symbol SRCDIR to the directory in which the sample source (or yours) is stored.
#********************************************************************** #* #* TITLE: amsample.mak - Sample ACCESS MODULE MAKE #* #* This file builds a sample access module. #* #* Invoke this makefile directly. Do NOT use the toplevel makefile! #* This makefile is intended to be useable in customer environments. #* #********************************************************************** OBJS = amsample.o INCDIR = ../inc SRCDIR = ../src
63
Appendix A: Sample Program and Makefile Sample Makefile

NESTINC = $(INCDIR)/pmdcomt.h \ $(INCDIR)/pmddamt.h CCFlags = -c -g -I$(INCDIR) amsample.so: $(OBJS) cc -G -g $(OBJS) -o amsample.so amsample.o: $(NESTINC) $(SRCDIR)/amsample.c cc $(CCFlags) $(SRCDIR)/amsample.c # DO NOT DELETE THIS LINE -- make depend depends on it.
64
Index
A
Access modules attribute exchange functions 18 definition 13 functional description 17 functions file close 25 file get position 26 file open 27 file read 29 file set position 30 file write 31 general function-independent structure 22 get attribute 31 identification 33 interface return codes 24 put attribute 35 request type function requests 23 shutdown 36 get functions 19 interface 17 linkages, diagram 14 main function 17 programming considerations 21 put functions 19 version identification 18, 33 Attribute exchange functions, access modules 18 AttrName parameter get attribute function 32 put attribute function 36 AttrNameLen parameter get attribute function 32 put attribute function 36 AttrValue parameter get attribute function 32 put attribute function 36 AttrValueLen parameter get attribute function 32 put attribute function 36
BufferLen parameter file read function 29 file write function 31 BYTE_ORDER attribute 20
C
character sets 36 CHARSET_NAME 20, 36 CHARSET_NUMBER 20, 36 ClientID parameter, initialization function 34 ClientIDL parameter, initialization function 34
E
ErrMsg parameter, general function-independent structure 23 EyeCatcher parameter file close function 25 file get position function 26 file open function 27 file read function 29 file set position function 30 file write function 31 general function-independent structure 23 get attribute function 32 identification function 33 initialization function 34 put attribute function 35 shutdown function 37
F
FIData parameter file close function 25 file get position function 26 file open function 28 file read function 29 file set position function 30 file write function 31 File close function, access modules 25 File get position function, access modules 26 File open function, access modules 27 File read function, access modules 29 File set position function, access modules 30 File write function, access modules 31 FileName parameter, file open function 28 FileNameL parameter, file open function 28
B
BlkHeaderLen parameter, file open function 28 BlkSize parameter, file open function 28 Buffer parameter file read function 29 file write function 31
65
Index
G
General function-independent structure, access modules 22 Get attribute function, access modules 31 Get functions, access modules 19
I
Identification function access modules 33 for version information 18, 33 InitStr parameter, initialization function 34 InitStrL parameter, initialization function 34 Interface functions, access modules 17 Interface return codes, access modules 24 InterfaceVerNo parameter, initialization function 34 InterfaceVerNoD parameter, initialization function 34
M
Main function, access modules 17 Mode parameter shutdown function 37
pmrcEOF return code, file read function 29 pmrcFailure return code, general function-independent structure 24 pmrcFNameTooLong return code, file open function 28 pmrcOK return code, general function-independent structure 24 pmrcOpenFiles return code, shutdown function 37 pmrcReadOnly return code, file write function 31 pmrcRedundant return code, initialization function 35 pmrcUnsupported return code, general functionindependent structure 24 pmrcWriteOnly return code, file read function 29 Position parameter file get position function 26 file set position function 30 prerequisites 4 product version numbers 3 Programming considerations, access modules 21 Put attribute function, access modules 35 Put functions, access modules 19
R
Record formats 14 table of 15 Reqtype parameter, general function-independent structure 23 Request type function requests, access modules 23 Retcoder parameter, general function-independent structure 23 Return codes pmrcAllocErr 24 pmrcAPInotReady 24 pmrcBadAttrName 32, 36 pmrcBadFormat 28 pmrcBadFp 26, 29, 31 pmrcBadParm 24 pmrcBadTraceLvl 24 pmrcBadVer 35 pmrcEOF 29 pmrcFailure 24 pmrcFNameTooLong 28 pmrcOK 24 pmrcOpenFiles 37 pmrcReadOnly 31 pmrcRedundant 35 pmrcUnsupported 24 pmrcWriteOnly 29
O
ObjData parameter get attribute function 32 put attribute function 36 OpenMode parameter, file open function 28
P
PIData parameter file open function 27 initialization function 34 shutdown function 37 PIDMMain() 18, 33 pmrcAllocErr return code, general function-independent structure 24 pmrcAPInotReady return code, general functionindependent structure 24 pmrcBadAttrName return code get attribute function 32 put attribute function 36 pmrcBadFormat return code, file open function 28 pmrcBadFp return code file close function 26 file read function 29 file write function 31 pmrcBadParm return code, general function-independent structure 24 pmrcBadTraceLvl return code, general function-independent structure 24 pmrcBadVer return code, initialization function 35
S
Shutdown function, access modules 36 StructLength parameter file close function 25 file get position function 26
66
Index
file open function 27 file read function 29 file set position function 30 file write function 31 general function-independent structure 23 get attribute function 32 identification function 33 initialization function 34 put attribute function 35 shutdown function 37
T
TBR_OP_HANDLE attribute 20 TIMEOUT_SECONDS attribute 20 TraceLvl parameter, general function-independent structure 23
V
VerIDList parameter, identification function 33 version identification 18, 33 version numbers 3
W
WRITE_BOM attribute 20
67
Index
68

2424

Uploaded by

Copyright:

Available Formats

2424

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

2424

Uploaded by

Copyright:

Available Formats

Teradata Tools and Utilities Access Module

Teradata Tools and Utilities Access Module Programmer Guide

Changes to This Book

the search results.

Teradata Tools and Utilities Access Module Programmer Guide

Preface Additional Information

Type of Information Additional product information

Browse by Category, click Data Warehousing.

Browse by Category, click Data Warehousing.

Ordering information for manuals

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

General information about Teradata

Teradata Tools and Utilities Access Module Programmer Guide

Preface Additional Information

Teradata Tools and Utilities Access Module Programmer Guide

Chapter 2: Creating Access Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Teradata Tools and Utilities Access Module Programmer Guide

Chapter 3: Access Module Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25

Chapter 4: Header File Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .39

Appendix A: Sample Program and Makefile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49

Teradata Tools and Utilities Access Module Programmer Guide

Figure 1: Access Module Linkage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Teradata Tools and Utilities Access Module Programmer Guide

Teradata Tools and Utilities Access Module Programmer Guide

Teradata Tools and Utilities Access Module Programmer Guide

Teradata Tools and Utilities Access Module Programmer Guide

Teradata Tools and Utilities Access Module Programmer Guide

Chapter 1: Overview Record Formats Figure 1: Access Module Linkage

JMS Provider Teradata OLE DB Access Module

Customer Access Module Teradata Access Module For JMS

OLE D ProvB ider

IBM Websphere MQ Series

Teradata Websphere MQ Access Module

Statically Linked Data Stream Dynamically Linked Data Stream

Teradata Tools and Utilities Access Module Programmer Guide

Chapter 1: Overview Record Formats

Table 1: Supported Record Formats for Client Utilities

Format pmIDFtext pmIDFBin1 pmIDFBin1Plus pmIDFBin2 pmIDFBin2Plus pmIDFnone

Table 2: Record Formats for the Teradata PT DataConnector Operator

Teradata Tools and Utilities Access Module Programmer Guide

Chapter 1: Overview Record Formats

Teradata Tools and Utilities Access Module Programmer Guide

Creating Access Modules

Teradata Tools and Utilities Access Module Programmer Guide

Chapter 2: Creating Access Modules Attribute Exchange Functions

Attribute Exchange Functions

Chapter 2: Creating Access Modules Attributes Provided by Teradata Utilities

Get Attribute Requests

Put Attribute Requests

Attributes Provided by Teradata Utilities

Teradata Tools and Utilities Access Module Programmer Guide

Table 3: Teradata Utility Attributes

Name of Attribute BYTE_ORDER

Provided by FastExport, FastLoad, MultiLoad, and TPump job scripts

Access Modules with the Teradata PT DataConnector Operator

Teradata Tools and Utilities Access Module Programmer Guide

Chapter 2: Creating Access Modules Considerations

To define an access module in a Teradata PT job script

Teradata Tools and Utilities Access Module Programmer Guide

Chapter 2: Creating Access Modules Checkpoint/Restart

/* 32-bit unsigned integer / / 32-bit unsigned integer */

/* Struct eyecatcher string / / Length of this structure */

/* Struct eyecatcher string / / Length of this structure */

/* Struct eyecatcher string / / Length of this structure */