Chapter 3 Operator Interface Functions. Teradata Teradata Parallel Transporter
Advertentie
Advertentie
CHAPTER 3
Operator Interface Functions
This chapter describes the following functions of the Teradata PT operator interface:
•
•
User-Provided Control Functions
•
•
Description
The Teradata PT operator interface is defined by the functions of the PX_Operator class, which are either user-provided control functions or service functions.
In the following example, functions with a prefix of “virtual” and ending with “=0” are userprovided control functions that must be overridden by each interfacing operator. All other functions are service functions that provide the operational interface to the Teradata PT infrastructure.
( public: virtual PXSTC_Code PX_Initiate() = 0; virtual PXSTC_Code PX_Terminate() = 0; virtual PXSTC_Code PX_Execute() = 0; virtual PXSTC_Code PX_Checkpoint() = 0; virtual PXSTC_Code PX_Restart() = 0; virtual PXSTC_Code PX_Event() = 0;
PXSTC_Code PX_GetAttribute();
PXSTC_Code PX_PutAttribute();
PXSTC_Code PX_AllocateStorage();
PXSTC_Code PX_FreeStorage();
PXSTC_Code PX_CreateGlobalVar();
PXSTC_Code PX_DeleteGlobalVar();
PXSTC_Code PX_ReadGlobalVar();
PXSTC_Code PX_UpdateGlobalVar();
PXSTC_Code PX_SetErrorMessage();
PXSTC_Code PX_ReadCheckpointRecord();
PXSTC_Code PX_WriteCheckpointRecord();
PXSTC_Code PX_BeginTableSchemaDefinition();
PXSTC_Code PX_FinalizeTableSchemaDefinition();
PXSTC_Code PX_CreateColumnSchema();
PXSTC_Code PX_GetTableSchemaList();
PXSTC_Code PX_GetColumnSchemaList();
PXSTC_Code PX_GetColumnSchema();
PXSTC_Code PX_GetColumnValue();
Teradata Parallel Transporter Operator Programmer Guide 35
Chapter 3: Operator Interface Functions
User-Provided Control Functions
PXSTC_Code PX_PutColumnValue();
PXSTC_Code PX_GetRow();
PXSTC_Code PX_PutRow();
PXSTC_Code PX_LogInit();
PXSTC_Code PX_LogWrite();
PXSTC_Code PX_LogTerminate();
PXSTC_Code PX_SetLogError();
}
User-Provided Control Functions
At a minimum, each customized operator must define the following user-provided control functions:
Function
Use
Preparing the operating environment for executing operators by performing the following tasks:
•
Establishing a connection with a target database
•
Allocating storage for processing data rows or for subsequent Teradata PT operations
•
Opening a data set for row retrieval or update
•
Parsing input parameters
•
Specifying the cursor position for reading a file
•
Locking a table for exclusive update operations
Performing the following data access and manipulation tasks:
•
Reading rows from a data source
•
Writing data to a data target
•
Projecting column values
•
Filtering data
•
Converting data types
•
Merging and splitting data streams
Writing checkpoint records to a restart log table that the operator can use to restart in case of a hardware or software system failure.
Restarting operators using the most recently written checkpoint records.
Performing event processing or notification based on caller-specified event.
Releasing system resources allocated by the corresponding Initiate function.
Data Types
Table 7 on page 37 defines the parameter data types of Teradata PT operator interface control
functions.
36 Teradata Parallel Transporter Operator Programmer Guide
Chapter 3: Operator Interface Functions
Data Types
Table 7: Teradata PT Operator Data Types
Data Type
PX_Addr
PX_AttributeCode
PX_AttributeName
Definition
The address of a memory location.
An integer that represents the name of an object attribute.
Pointer to a null-terminated character string that provides the name of an object attribute.
PX_AttributeValue
PX_ByteOffset
PX_Code
PX_ColumnCount
PX_ColumnHandle
PX_ColumnName
PX_ColumnSchemaHa ndle
Pointer to an area for storage of an attribute value.
Integer that specifies the displacement in bytes from the first byte of a row.
Integer code that represents either:
•
System code
•
System reason code
Integer that specifies the column count.
Integer that identifies the instance of a column.
Pointer to a null-terminated character string that provides a column name.
Integer that represents the instance of the column schema.
PX_ColumnSchemaList Array of column schema handles.
PX_Count Integer that specifies the count of some object.
PX_DataAddr
PX_DataType
Address of the data.
Integer code that represents the following defined data types of a column:
•
PX_DataType_Integer
•
PX_DataType_SmallInt
•
PX_DataType_Float
•
PX_DataType_Decimal
•
PX_DataType_Char
•
PX_DataType_ByteInt
•
PX_DataType_VarChar
•
PX_DataType_Byte
•
PX_DataType_VarByte
•
PX_DataType_Date
•
PX_DataType_Graphic
•
PX_DataType_VarGraphic
•
PX_DataType_Date_ANSI
•
PX_DataType_Boolean
•
PX_DataType_BigInt
•
PX_DataType_LongVarChar
•
PX_CataType_LongVarGraphic
Teradata Parallel Transporter Operator Programmer Guide 37
Chapter 3: Operator Interface Functions
Data Types
Table 7: Teradata PT Operator Data Types (continued)
Data Type
PX_ErrorProc
PX_ErrorText
PX_FilterHandle
PX_GlobalHandle
PX_Indicator
PX_Length
PX_LogHandle
PX_LongInt
PX_Name
PX_Number
PX_OperatorHandle
PX_Precision
PX_Scale
Definition
Function pointer that specifies an error exit function.
Pointer to a character string that provides the error message.
Integer that identifies the instance of a filter.
Integer that identifies the instance of a global.
Pointer to the array of indicator bytes specifying whether or not the corresponding column value is NULL.
Integer that specifies the size, in bytes, of an object.
Integer that specifies a log stream definition. The structure is allocated by the Logger API.
Four-byte signed integer.
Pointer to a null-terminated character string that provides the name of an object.
Integer that specifies the number (instance) of an object.
Integer code that identifies the instance of an operator.
Integer that specifies a precision value (number of digits) for a numeric data type.
Integer that specifies a scale value (number of digits to the right of the decimal point) for a numeric data type.
PX_SchemaType
PX_TableSchemaList
PX_TruthValue
Integer code that identifies one of the following schema types:
•
PX_InputSchema
•
PX_InputOutputSchema
•
PX_OutputSchema
PX_TableSchemaHandl e
Integer code that identifies the instance of the table schema.
Array of table schema handles.
Integer that specifies one of the following values:
•
PX_True
•
PX_False
38 Teradata Parallel Transporter Operator Programmer Guide
Chapter 3: Operator Interface Functions
Data Types
Table 7: Teradata PT Operator Data Types (continued)
Data Type
PXSTC_Code
Definition
Integer that indicates the success or failure of a Teradata PT service function or operator routine. The defined codes are:
•
PXSTC_BadHandle - an invalid object handle. This can happen if the object is of the wrong type or if the object is not accessible by the application.
•
PXSTC_CatalogError - unable to open the message catalog.
•
PXSTC_CheckPoint - request a checkpoint processing.
•
PXSTC_CheckPointNotReady - the operator is not ready for checkpoint processing.
•
PXSTC_CheckPointReady - the operator is ready for checkpoint processing.
•
PXSTC_CommunicationError - an error was detected during the communication between a client and a service.
•
PXSTC_Conflict - mismatching type of operations, data, or protocols.
•
PXSTC_CountError - the specified number of objects does not match some predefined value.
•
PXSTC_DataStreamError - an error was encountered in the Teradata
PT data stream.
•
PXSTC_DiscardRow - delete the current row.
•
PXSTC_Duplicate - a duplicate component or resource.
•
PXSTC_EndMethod - the end of a function in multiphase operations.
•
PXSTC_EndOfData - end of data encountered.
•
PXSTC_EndOfProcessing - end of a request processing was encountered.
•
PXSTC_FatalError - an unrecoverable system error was encountered and a restart of the Teradata PT job is required.
•
PXSTC_Full - the specified resource is full.
•
PXSTC_GroupError - an error was detected during the system group processing.
•
PXSTC_InvalidArgument - bad input arguments provided to the operator.
•
PXSTC_InvalidDataType - the data type of some column value or parameter is invalid.
•
PXSTC_InvalidName - the specified name of the object is invalid.
•
PXSTC_IOError - an error occurred during I/O processing.
•
PXSTC_LengthError - conflicting lengths between two objects.
•
PXSTC_LogCommunicationError - error from socket communication with the node Logger.
•
PXSTC_LogFileError - the specified log file name is either invalid or not accessible.
•
PXSTC_LogHandle - an invalid log handle was used to request for log services.
•
PXSTC_LogInsuffMemError - memory allocation failure with the node
Logger.
Teradata Parallel Transporter Operator Programmer Guide 39
Chapter 3: Operator Interface Functions
Data Types
Table 7: Teradata PT Operator Data Types (continued)
Data Type
(PXSTC_Code, continued)
Definition
•
PXSTC_LogPassword - the Logger API has supplied a wrong password for the logger. (attempt to access the logger without using the supplied
API).
•
PXSTC_LogXDRError - an error was detected by the Logger Services during XDR processing.
•
PXSTC_MetadataError - an error was detected during the processing of metadata.
•
PXSTC_Mismatch - mismatching lengths, components, or data types.
•
PXSTC_MultiphaseError - an error was encountered during multiphase processing.
•
PXSTC_NoMessageCatalog - the requested message catalog is not present.
•
PXSTC_NextPhase -a phase change in multiphase operations.
•
PXSTC_NodeError - a problem with the specified node.
•
PXSTC_NoLogRec - no log record was found in the log file.
•
PXSTC_NotActive - the requested system resource is down or not active.
•
PXSTC_NotEnough - insufficient resources to complete the requested task.
•
PXSTC_NotFound - a requested resource does not exist.
•
PXSTC_NotSupported - the requested resource is not supported.
•
PXSTC_NullHandle - the specified object handle has no value associated with it.
•
PXSTC_NullPointer - a missing value was detected in a pointer type of data.
•
PXSTC_NullRow - a row has no column values associated with it.
•
PXSTC_NullTable - a table with no rows was encountered.
•
PXSTC_ObjectBusy - the requested object is busy or occupied by another resource or user.
•
PXSTC_OpenError - an error was detected during the accessing of a file or a resource.
•
PXSTC_OperatorError - an error was encountered when processing an operator.
•
PXSTC_PathError - an invalid specification of a resource location.
•
PXSTC_ParserError - an error was detected during the parsing of a script.
•
PXSTC_ProtocolError - an invalid sequence of operations or illegal use of processing protocol
•
PXSTC_RetryError - an error that allows the system to retry the job execution again.
•
PXSTC_RowError - an error was detected when processing a row.
•
PXSTC_SamePhase - no phase change in multi-phase operations.
•
PXSTC_SchemaError - an error was detected in the data schema.
40 Teradata Parallel Transporter Operator Programmer Guide
Chapter 3: Operator Interface Functions
Service Functions
Table 7: Teradata PT Operator Data Types (continued)
Data Type
PXSTC_Code
(continued)
Definition
•
PXSTC_Size - invalid size of an object.
•
PXSTC_Storage - an error was encountered during storage allocation or deallocation.
•
PXSTC_Success - successful completion of the operation.
•
PXSTC_SyntaxError - a syntax error was encountered in a command or script.
•
PXSTC_SystemError - a Teradata PT error while processing a Teradata
PT operator function.
•
PXSTC_TaskError - an error was encountered at the task/process level.
•
PXSTC_TimeOut - a specific usage time value for a resource has expired.
•
PXSTC_UnknownError - an error condition that has no defined explanation.
•
PXSTC_Warning - the operation completed, but with a minor error condition.
Service Functions
Each customized operator must use the following service functions for interfacing with
Teradata PT or with other Teradata PT operators. Descriptions for each of these service functions following this summary.
Table 8: Service Functions
Function
Use
Allocating and freeing Teradata PT storage for your operator.
Creating, accessing, and deleting global variables.
Storing and retrieving attribute values.
Storing and retrieving data rows.
Storing and retrieving column values.
Storing and retrieving checkpoint records.
Teradata Parallel Transporter Operator Programmer Guide 41
Chapter 3: Operator Interface Functions
Service Functions
Table 8: Service Functions (continued)
Function
Use
Creating and accessing column schemas.
Creating table schemas.
Retrieving lists of table and column schemas.
Creating error messages.
Initiating, writing, and terminating a log stream function.
Redirecting a call after an error occurs in the Logger API.
Complete descriptions for each of the above functions follow in the next section.
42 Teradata Parallel Transporter Operator Programmer Guide
Chapter 3: Operator Interface Functions
Allocate Storage
Allocate Storage
Purpose
Allocate Storage is the service function that allocates Teradata PT storage for the operator.
Structure
#include <pxoper.h>
PXSTC_Code PX_AllocateStorage(PX_OperatorHandle operator,
PX_Length storageSize,
PX_Addr * storageAddr); where:
Parameter
operator storageSize storageAddr
Function
input input output
Specification
Instance of the operator for which the storage is to be allocated.
Amount of storage you want to allocate to the named operator.
Pointer to the address of the allocated storage.
Return Codes
The following Allocate Storage function status codes are defined by the Teradata PT operator interface.
Status Code
PXSTC_InvalidArgument
PXSTC_BadHandle
PXSTC_NotEnough
Signifies
One or more bad input arguments.
An undefined object handle.
Either:
•
Not enough storage can be allocated
•
The requested storage size is too large
Successful access to the object attribute.
PXSTC_Success
Usage Notes
Consider the following when using the Allocate Storage function.
Topic
Status
Usage Note
If the function status is PXSTC_Success, the storage address will be stored in the location indicated by the storageAddr pointer. See also the
Teradata Parallel Transporter Operator Programmer Guide 43
Chapter 3: Operator Interface Functions
Begin Table Schema Definition
Begin Table Schema Definition
Purpose
Begin Table Schema Definition is the service function that starts the definition of a table schema for the operator.
Structure
#include <pxoper.h>
PXSTC_Code PX_BeginTableSchemaDefinition(
PX_OperatorHandle operator,
PX_SchemaType schemaType,
PX_TableSchemaHandle * tableSchemaHandle); where
Parameter
operator schemaType tableSchemaHandle
Function Specification
input input output
Instance of the operator for which the table schema is being defined.
Schema type, which can be either:
•
PX_InputSchema
•
PX_OutputSchema
•
PX_InputOutputSchema
Pointer to the defined table schema.
Return Codes
The following Begin Table Schema Definition function status codes are defined by the
Teradata PT operator interface:
Status Code
PXSTC_InvalidArgument
PXSTC_BadHandle
PXSTC_Success
Signifies
One or more bad input arguments.
An undefined object handle.
Successful initiation of the table schema definition.
Usage Notes
Consider the following when using the Begin Table Schema Definition function.
44 Teradata Parallel Transporter Operator Programmer Guide
Topic
Status
Chapter 3: Operator Interface Functions
Begin Table Schema Definition
Usage Note
If the function status is PXSTC_Success, the table schema handle will be stored in the location indicated by the tableSchemaHandle pointer. See also the
function.
Teradata Parallel Transporter Operator Programmer Guide 45
Chapter 3: Operator Interface Functions
Checkpoint
Checkpoint
Purpose
Checkpoint is a user-provided function that creates a checkpoint record for operators.
Structure
#include <pxoper.h>
PXSTC_Code PX_Checkpoint(PX_OperatorHandle operator, PX_LongInt phase); where
Parameter
operator phase
Function
input input
Specification
Operator handles associated with the Checkpoint function.
Current processing phase number
Return Codes
The following Checkpoint function status codes are defined by the Teradata PT operator interface:
Status Code
PXSTC_EndMethod
PXSTC_NextPhase
PXSTC_SamePhase
Signifies
Successful checkpoint processing.
This status condition indicates that the checkpoint record was successfully written to the restart log by this function.
Proceed with the next processing phase.
Continue with the current processing phase.
Define additional Checkpoint function status codes as required to support your operator.
Usage Notes
Consider the following when using the Checkpoint function.
Topic
Description
Usage Note
Use the Checkpoint function to record the checkpoint information identified by the operator parameter. See also the
46 Teradata Parallel Transporter Operator Programmer Guide
Chapter 3: Operator Interface Functions
Create Column Schema
Create Column Schema
Purpose
Create Column Schema is the service function that creates the schema for a column.
Structure
#include <pxoper.h>
PXSTC_Code PX_CreateColumnSchema(
PX_TableSchemaHandle tableSchemaHandle,
PX_ColumnName columnName,
PX_DataType dataType,
PX_Length dataLength,
PX_ByteOffset offset,
PX_Precision precision,
PX_Scale scale,
PX_TruthValue nullIndicator,
PX_ColumnSchemaHandle * columnHandle); where
Parameter
columnHandle columnName dataLength dataType nullIndicator offset precision scale tableSchemaHandle
Function Specification
output input input input input input input input input
Column handle for which the schema is being created.
Column-name attribute of the column schema.
Column length for both numeric and nonnumeric data types.
Data type attribute of the column schema.
Truth value indicating whether or not the column value can be
NULL.
Column position in terms of the number of bytes into the data row. An offset specification of -1 signifies that no column position is defined.
Precision value (number of digits) for a numeric data type.
The precision specification can range from 1 to 38.
Scale value (number of digits to the right of the decimal point) for a numeric data type.
Data schema handle by which the column schema will be created.
Return Codes
The following Create Column Schema function status codes are defined by the Teradata PT operator interface:
Teradata Parallel Transporter Operator Programmer Guide 47
Chapter 3: Operator Interface Functions
Create Column Schema
Status Code
PXSTC_InvalidArgument
PXSTC_BadHandle
PXSTC_Success
Signifies
One or more bad input arguments.
An undefined data schema handle.
Successful creation of the column schema definition.
Usage Notes
Consider the following when using the Create Column Schema function.
Topic Usage Notes
Data Type Specifications Teradata PT supports the following data type specifications:
•
PX_DataType_Integer
•
PX_DataType_SmallInt
•
PX-DataType_LongInt
•
PX_DataType_Float
•
PX_DataType_Decimal
•
PX_DataType_Char
•
PX_DataType_ByteInt
•
PX_DataType_VarChar
•
PX_DataType_Byte
•
PX_DataType_VarByte
•
PX_DataType_Graphic
•
PX_DataType_VarGraphic
•
PX_DataType_Date
•
PX_DataType_Date_ANSI
•
PX_DataType_Boolean
Valid abbreviations in data type specifications:
•
CHARACTERS as:
•
CHARACTER
•
CHARS
•
CHAR
•
DECIMAL as DEC
•
INTEGER as INT
Status If the function status is PXSTC_Success, the column schema will be stored in the location indicated by the columnHandle pointer. See also the
function.
48 Teradata Parallel Transporter Operator Programmer Guide
Chapter 3: Operator Interface Functions
Create Global Variable
Create Global Variable
Purpose
Create Global Variable is the service function that creates a global variable for the operator.
Structure
#include <pxoper.h>
PXSTC_Code PX_CreateGlobalVar(PX_OperatorHandle operator,
PX_Name varName,
PX_Length varSize,
PX_Count varCount); where
Parameter
operator varCount varName varSize
Function
input input input input
Specification
Instance of the operator handle for which the global variable is being created.
Maximum number items to be created for the global variable.
Name of the global variable.
Item size of the global variable, in bytes.
Return Codes
The following Create Global Variable function status codes are defined by the Teradata PT operator interface:
Status Code
PXSTC_InvalidArgument
PXSTC_BadHandle
PXSTC_NotEnough
PXSTC_Success
Signifies
One or more bad input arguments.
An undefined object handle.
The global variable size is too large
Successful creation of the global variable.
Usage Notes
Consider the following when using the Create Global Variable function.
Topic
Status
Usage Notes
If the function status is PXSTC_Success, all items of the global variable were created successfully.
Teradata Parallel Transporter Operator Programmer Guide 49
Chapter 3: Operator Interface Functions
Delete Global Variable
Delete Global Variable
Purpose
Delete Global Variable is the service function that deletes a global variable that had been created for the operator.
Structure
#include <pxoper.h>
PXSTC_Code PX_DeleteGlobalVar(PX_OperatorHandle operator, PX_Name
varName); where
Parameter
operator
Function
input input
Specification
Instance of the operator handle for which the global variable is being deleted.
Name of the global variable.
varName
Return Codes
The following Delete Global Variable function status codes are defined by the Teradata PT operator interface:
Status Code
PXSTC_InvalidArgument
PXSTC_BadHandle
PXSTC_Success
Signifies
One or more bad input arguments.
An undefined object handle.
Successful deletion of the global variable.
Usage Notes
Consider the following when using the Delete Global Variable function.
Topic
Status
Usage Notes
If the function status is PXSTC_Success, all items of the global variable
were deleted successfully. See also the Create Global Variable function.
50 Teradata Parallel Transporter Operator Programmer Guide
Chapter 3: Operator Interface Functions
Define Error Handler
Define Error Handler
Purpose
Define Error Handler is the service function that identifies the function to be called if an error occurs in the Logger API. The return value is a pointer to the function previously called when an error occurred.
Structure
#include <pxoper.h>
PXSTC_Code PX_SetLogError(PX_LogHandle loghandle, PX_ErrorProc
errorproc); where
Parameter
loghandle
Function
input
Specification
The handle to the log stream. The structure is allocated by the
Logger API.
The function to be called when an error occurs.
errorproc
input
Return Codes
The Define Error Handler function returns the address of the function previously defined.
Status Code
void*
Signifies
The address of the error procedure previously used.
Usage Notes
Consider the following when using the Define Error Handler function.
Topic
See Also
Usage Notes
Example
#include <pxoper.h>
PX_ErrorProc myerror1, myerror2;
PX_LogHandle loghandle;
PX_LogInit(oprhandle, "mycomponent", 75, NULL, myerror1, &loghandle);
.
PX_SetLogError(loghandle, myerror2);
.
PX_Terminate(loghandle);
Teradata Parallel Transporter Operator Programmer Guide 51
Chapter 3: Operator Interface Functions
Event
Event
Purpose
Event is a user-provided function that allows operators to perform event processing or notification.
Structure
#include <pxoper.h>
PXSTC_Code PX_Event(PX_OperatorHandle operator, PX_LongInt phase); where
Parameter
operator phase
Function
input input
Specification
Operator handle that is associated with the Event function.
Current processing phase number.
Return Codes
The following Event function status codes are defined by the Teradata PT operator interface:
Status Code
PXSTC_EndMethod
PXSTC_NextPhase
PXSTC_SamePhase
Signifies
Successful execution of the operator.
This status condition indicates that the event was successfully processed by this function.
Proceed with the next processing phase.
Continue with the current processing phase.
Define additional Event function status codes as required to support your operator.
Usage Notes
Consider the following when using the Event function.
Topic
Description
Usage Notes
This function requires the caller to user the PutAttribute function to specify the event to be processed by the operator.
Also see
52 Teradata Parallel Transporter Operator Programmer Guide
Chapter 3: Operator Interface Functions
Execute
Execute
Purpose
Execute is a user-provided function that executes a data processing function for the operator.
Structure
#include <pxoper.h>
PXSTC_Code PX_Execute(PX_OperatorHandle operator, PX_LongInt phase); where
Parameter
operator
Function
input
Specification
Operator handle associated with the Execute function.
The operator parameter is a handle that identifies the operator that the
Execute function is bound to. You can use this handle to invoke any of the Teradata PT service functions described in this chapter.
Current processing phase number
phase
input
Return Codes
The following Execute function status codes are defined by the Teradata PT operator interface.
Define additional Execute function status codes required to support your operator.
Status Code
PXSTC_EndMethod
PXSTC_EndOfData
PXSTC_NextPhase
PXSTC_SamePhase
Signifies
Successful execution of the operator.
End of data
Proceed with the next processing phase.
Continue with the current processing phase.
Usage Notes
Define additional Execute function status codes as required to support your operator.
Topic
Description
Usage Notes
Use the Execute function to process data row-by-row, as specified by the
operator parameter. The following results occur:
•
PXSTC_EndMethod - all rows were successfully processed.
•
PXSTC_NextPhase - advance to the next phase in the same method
•
PXSTC_SamePhase - a row was successfully processed.
See also the
Teradata Parallel Transporter Operator Programmer Guide 53
Chapter 3: Operator Interface Functions
Finalize Table Schema Definition
Finalize Table Schema Definition
Purpose
Finalize Table Schema Definition is the service function that finalizes the process of creating the table schema.
Structure
#include <pxoper.h>
PXSTC_Code PX_FinalizeTableSchemaDefinition(PX_TableSchemaHandle
tableSchemaHandle); where
Parameter
tableSchemaHandle
Function
input
Specification
Table schema handle function to be finalized.
Return Codes
The following Finalize Table Schema Definition function status codes are defined by the
Teradata PT operator interface:
Status Code
PXSTC_Conflict
PXSTC_CountError
PXSTC_LengthError
PXSTC_BadHandle
PXSTC_SchemaError
PXSTC_Success
Signifies
Mismatching type of operations, data, or protocols.
The specified number of objects does not match some predefined value.
The length of the data to be stored does not match the length of the internal buffer.
An undefined table schema handle.
An error was detected in the data schema.
Successful creation of the table schema.
Usage Notes
Consider the following when using the Finalize Table Schema Definition function.
Topic
Description
Status
Usage Notes
You must use the Finalize Data Schema Definition function to finalize a data schema before it can be used by Teradata PT operators for subsequent data manipulation functions.
If the function status is PXSTC_Success, the defined table schema can be used by Teradata PT operators. See also
.
54 Teradata Parallel Transporter Operator Programmer Guide
Chapter 3: Operator Interface Functions
Free Storage
Free Storage
Purpose
Free Storage is the service function that frees the operator storage that was previously allocated.
Structure
#include <pxoper.h>
PXSTC_Code PX_FreeStorage(PX_OperatorHandle operator, PX_Addr
storageAddr); where
Parameter
operator storageAddr
Function
input input
Specification
Operator handle for which the storage is to be freed.
Address of the storage to be freed.
Return Codes
The following Free Storage function status codes are defined by the Teradata PT operator interface:
Status Code
PXSTC_InvalidArgument
PXSTC_BadHandle
PXSTC_Success
Signifies
One or more bad input arguments.
An undefined object handle.
Successful access to the object attribute.
Usage Notes
Consider the following when defining the Free Storage function.
Topic
Status
Usage Notes
If the function status is PXSTC_Success, the storage at the location indicated by the storageAddr pointer was successfully freed. See also
.
Teradata Parallel Transporter Operator Programmer Guide 55
Chapter 3: Operator Interface Functions
Get Attribute
Get Attribute
Purpose
Get Attribute is the service function that retrieves the value of a specific attribute associated with the operator.
Structure
#include <pxoper.h>
PXSTC_Code PX_GetAttribute(PX_OperatorHandle operator,
PX_AttributeName attributeName,
PX_AttributeValue * attributeValue,
PX_Length * valueLength); where
Parameter
attributeName attributeValue operator
Function
input output input
Specification
Name of the object attribute.
Retrieved value of the specified attribute.
Operator handle from which the attribute is to be retrieved.
Length of the retrieved attribute value.
valueLength
output
Return Codes
The following Get Attribute function status codes are defined by the Teradata PT operator interface:
Status Code
PXSTC_InvalidArgument
PXSTC_BadHandle
PXSTC_NotFound
PXSTC_Success
Signifies
One or more bad input arguments.
An undefined object handle.
The specified attribute was not found in the specified object.
Successful access to the specified attribute.
Usage Notes
Consider the following when defining the Get Attribute function.
Topic
System Attributes
Usage Notes
lists the Teradata PT system attributes that you can
retrieve with the Get Attributes function. See also Put Attribute
.
56 Teradata Parallel Transporter Operator Programmer Guide
Chapter 3: Operator Interface Functions
Get Attribute
Topic
Status
Usage Notes
If the function status is PXSTC_Success:
•
The address of the attribute value is stored as the attributeValue parameter.
•
The valueLength parameter indicates the length of the attribute value.
Table 9: Get-Accessible System Attributes
Attribute Name
SYSTEM_Code
SYSTEM_FilterHandle
SYSTEM_GlobalHandle
Data Type
PX_Code
PX_FilterHandle
PX_GlobalHandle
SYSTEM_InstanceNumber PX_Number
SYSTEM_MaxInstances
SYSTEM_OperatorName
SYSTEM_OperatorType
SYSTEM_PhaseNumber
SYSTEM_UserAreaAddr
PX_Count
PX_Addr
PX_Number
PX_Count
PX_Addr
4
4
4
4
4
4
Data
Length
(in bytes) Description
System ABEND code
Handle of the filter object
4
Handle of the global anchor
Instance number of the operator, starting from 1
Maximum number of instances that can be created for the operator
4
4
Address of string containing the operator name
Code indicating type of operator: producer=1, consumer=2, filter=3
Current processing phase number
Address of the user area
Teradata Parallel Transporter Operator Programmer Guide 57
Chapter 3: Operator Interface Functions
Get Column Schema
Get Column Schema
Purpose
Get Column Schema is the service function that retrieves the column schema associated with a column.
Structure
#include <pxoper.h>
PXSTC_Code PX_GetColumnSchema(
PX_ColumnSchemaHandle columnHandle,
PX_ColumnName *columnName,
PX_DataType * dataType,
PX_Length * dataLength,
PX_ByteOffset * offset,
PX_Precision * precision,
PX_Scale * scale,
PX_TruthValue * nullIndicator); where
Parameter
columnHandle columnName dataLength dataType nullIndicator
Function
output output output output output
offset precision scale
output output output
Specification
Column handle from which the column schema is to be obtained.
Column-name attribute of the column schema.
Column length for both numeric and nonnumeric data types.
Data type attribute of the column schema.
Truth value indicating whether or not the column value can be
NULL.
Column position in terms of the number of bytes into the data row.
An offset specification of -1 signifies that no column position is defined.
Precision value (number of digits) for a numeric data type.
The precision specification can range from 1 to 38.
Scale value (number of digits to the right of the decimal point) for a numeric data type.
Return Codes
The following Get Column Schema function status codes are defined by the Teradata PT operator interface:
58 Teradata Parallel Transporter Operator Programmer Guide
Chapter 3: Operator Interface Functions
Get Column Schema
Status Code
PXSTC_InvalidArgument
PXSTC_BadHandle
PXSTC_Success
Signifies
One or more bad input arguments.
An undefined column schema handle.
Successful retrieval of the column schema.
Usage Notes
Consider the following when defining thee Get Column Schema function.
Topic
Status
Usage Notes
If the function status is PXSTC_Success the values of the output parameters are returned. See also
Teradata Parallel Transporter Operator Programmer Guide 59
Chapter 3: Operator Interface Functions
Get Column Schema List
Get Column Schema List
Purpose
Get Column Schema List is the service function that retrieves the list of column handles associated with a table schema.
Structure
#include <pxoper.h>
PXSTC_Code PX_GetColumnSchemaList(
PX_TableSchemaHandle tableSchemaHandle,
PX_ColumnSchemaList * columnSchemaList,
PX_Count * columnSchemaCount); where
Parameter
columnSchemaCount columnSchemaList tableSchemaHandle
Function
output output input
Specification
Number of column schemas in the list.
Pointer to the location of the retrieved column schema list.
Table schema handle from which the column schema list is to be retrieved.
Return Codes
The following Get Column Schema List function status codes are defined by the Teradata PT operator interface:
Status Code Signifies
PXSTC_InvalidArgument One or more bad input arguments.
PXSTC_BadHandle
PXSTC_NotFound
PXSTC_Success
An undefined data schema handle.
The specified column schema list was not found in the specified object.
Successful retrieval of the list of column handles.
Usage Notes
Consider the following when defining the Get Column Schema List function.
Topic
Status
Usage Notes
If the function status is PXSTC_Success, the address of the column schema list is stored in the location pointed to by the columnSchemaList
parameter. See also Get Table Schema List
.
60 Teradata Parallel Transporter Operator Programmer Guide
Chapter 3: Operator Interface Functions
Get Column Value
Get Column Value
Purpose
Get Column Value is the service function that retrieves the data value associated with a column.
Structure
#include <pxoper.h>
PXSTC_Code PX_GetColumnValue(PX_ColumnHandle columnHandle,
PX_Indicator * nullIndicator,
PX_DataAddr * dataAddr,
PX_Length * dataLength); where
Parameter
columnHandle dataAddr dataLength nullIndicator
Function
input output output output
Specification
Column handle from which the column value is to be retrieved.
Pointer to the address of the column value.
Pointer to the length of the column value.
Pointer to the indication of whether or not the column value is
NULL.
Return Codes
The following Get Column Value function status codes are defined by the Teradata PT operator interface:
Status Code
PXSTC_InvalidArgument
PXSTC_BadHandle
PXSTC_Success
Signifies
One or more bad input arguments.
An undefined column handle.
Successful projection of data value to the column.
Usage Notes
Consider the following when defining the Get Column Value function.
Teradata Parallel Transporter Operator Programmer Guide 61
Chapter 3: Operator Interface Functions
Get Column Value
Topic
Status
Usage Notes
If the function status is PXSTC_Success:
•
The nullIndicator parameter indicates whether or not the column value is NULL.
•
The dataAddr parameter stores the address of the column value.
•
The dataLength parameter stores the length of the returned column value.
See also the
62 Teradata Parallel Transporter Operator Programmer Guide
Chapter 3: Operator Interface Functions
Get Row
Get Row
Purpose
Get Row is the service function that retrieves a data row.
Structure
#include <pxoper.h>
PXSTC_Code PX_GetRow(PX_TableSchemaHandle tableSchemaHandle,
PX_Count * columnCount,
PX_Indicator ** nullIndicator,
PX_ByteOffset ** offsets,
PX_Length ** lengths,
PX_Addr * rowAddr,
PX_Length * rowLength); where
Parameter
columnCount lengths nullIndicator offsets
Function Specification
output Pointer to the number of columns associated with the data row.
output output output
Pointer to the array of integers representing the length of the corresponding column value.
Pointer to the array of indicator bytes specifying whether or not the corresponding column value is NULL.
Pointer to the array of integers representing the corresponding column positions in terms of the number of bytes into the data row.
rowAddr rowLength
output output
tableSchemaHandle
input
Pointer to the address of the data row.
Pointer to the length of the data row.
Table schema handle by which the data row is to be obtained.
Return Codes
The following Get Row function status codes are defined by the Teradata PT operator interface:
Status Code
PXSTC_BadHandle
PXSTC_Success
PXSTC_EndOfData
Signifies
An undefined data schema handle.
Successful retrieval of the data row.
End of data.
Teradata Parallel Transporter Operator Programmer Guide 63
Chapter 3: Operator Interface Functions
Get Row
Usage Notes
Consider the following when defining the Get Row function.
Topic
Return Data Format
Status
See Also
Usage Notes
Data rows returned by the Get Row function are always prefixed with
NULL indicator bytes.
If the function status is PXSTC_Success:
•
The rowAddr parameter stores the address of the data row.
•
The rowLength parameter stores the length of the data row.
•
The columnCount parameter stores the number of columns associated with the data row.
•
The nullIndicators parameter is the address of the array indicating whether or not the column values are NULL.
•
The offsets parameter is the address of the array that indicates the byte offsets into the data row.
•
The lengths parameter is the address of the array that indicates the lengths of the column values.
•
Begin Table Schema Definition function
•
Finalize Table Schema Definition function
•
function
64 Teradata Parallel Transporter Operator Programmer Guide
Chapter 3: Operator Interface Functions
Get Table Schema List
Get Table Schema List
Purpose
Get Table Schema List is the service function that retrieves the table schemas associated with an operator.
Structure
#include <pxoper.h>
PXSTC_Code PX_GetTableSchemaList(
PX_OperatorHandle operator,
PX_SchemaType schemaType,
PX_TableSchemaList * tableSchemaList,
PX_Count * tableSchemaCount); where
Parameter
operator schemaType
Function
input input
tableSchemaList
output
tableSchemaCount
output
Specification
Operator handle from which the list of table schemas is to be retrieved.
Schema type, which can be either:
•
PX_InputSchema
•
PX_OutputSchema
•
PX_InputOutputSchema
Pointer to the address of the list of table schemas.
Pointer to the number of schemas in the table schema list.
Return Codes
The following Get Table Schema List function status codes are defined by the Teradata PT operator interface:
Status Code
PXSTC_InvalidArgument
PXSTC_BadHandle
PXSTC_NotFound
PXSTC_Success
Signifies
One or more bad input arguments.
An undefined operator handle.
The specified table list was not found in the specified object.
Successful fetching of the table schema list.
Usage Notes
Consider the following when defining the Get Table Schema List function.
Teradata Parallel Transporter Operator Programmer Guide 65
Chapter 3: Operator Interface Functions
Get Table Schema List
Topic
Status
See Also
Usage Notes
If the function status is PXSTC_Success:
•
The address of the table schema list is stored at the location indicated by the tableSchemaList parameter.
•
The tableSchemaCount parameter points to the number of table schemas in the list.
•
Begin Table Schema Definition function
•
Finalize Table Schema Definition function
66 Teradata Parallel Transporter Operator Programmer Guide
Chapter 3: Operator Interface Functions
Initiate
Initiate
Purpose
Initiate is the user-provided function that establishes the processing environment for an operator.
Structure
#include <pxoper.h>
PXSTC_Code PX_Initiate(PX_OperatorHandle operator, PX_LogInt phase); where
Parameter
operator
Function
input
Specification
Operator handle associated with the Initiate function.
The operator parameter is a handle that identifies the operator that the
Initiate function is bound to. You can use this handle to invoke any of the Teradata PT service functions described in this chapter.
Current processing phase number
phase
input
Return Codes
The following Initiate function status codes are defined by the Teradata PT operator interface:
Status Code
PXSTC_EndMethod
PXSTC_NextPhase
PXSTC_SamePhase
Signifies
Successful initialization of the operator.
Proceed with the next processing phase.
Continue with the current processing phase.
Define additional Initiate function status codes as required to support your operator.
Usage Notes
Consider the following when defining the Initiate function.
Topic
Status
Usage Notes
If the function status is PXSTC_EndMethod, the processing environment was successfully established by this function. See also the
function.
Teradata Parallel Transporter Operator Programmer Guide 67
Chapter 3: Operator Interface Functions
Initiate Log Stream
Initiate Log Stream
Purpose
Initiate Log Stream is used for initiating a log stream. The message catalog name is supplied in the Teradata PT script to make the Log View Server or Log View Client generate the messages.
The logging facility itself does not use the message catalog.
Structure
#include <pxoper.h>
PXSTC_Code PX_LogInit(PX_OperatorHandle oprhandle, char *componentname,
PX_Number instancenumber char *outputlogreport,
PX_ErrorProc errorproc,
PX_LogHandle *loghandle); where
Parameter
componentname instancenumber loghandle errorproc oprhandle outputlogreport
Function Specification
input input output input input input
Name of the component.
Number of the operator instance.
Handle to the log stream, allocated by the Logger API.
The caller is responsible for passing the address of a
PX_LogHandle pointer to PX_LogInit, but the Logger API is responsible for allocating the structure.
Pointer to the function to be called if an error occurs in the Logger
API, or NULL if no specific error handling is wanted.
Handle to the operator.
Name of the private log report, or NULL, if the log report is public.
The outputlogreport parameter may contain an explicit character value, for example, PrivateFileName, or it may be NULL. If NULL is specified, the log becomes PUBLIC.
Return Codes
The following Initiate Log Stream function status codes are defined by the Teradata PT operator interface:
Status Code
PXSTC_Success
Signifies
The call succeeded.
68 Teradata Parallel Transporter Operator Programmer Guide
Chapter 3: Operator Interface Functions
Initiate Log Stream
Status Code
PXSTC_LogInsuff
MemError
PXSTC_CatalogError
PXSTC_Log
CommunicationError
PXSTC_LogPassword
Signifies
Memory allocation failure.
No message catalog specified.
Error from socket communication with the Node Logger.
The Logger API has supplied a wrong password for the logger (indicates an attempt to access the logger without using the supplied API).
The type of some of the parameters is unknown to the Logger API.
PXSTC_InvalidData
Type
PXSTC_NoMessage
Catalog
PXSTC_Unknown
Error
The requested message catalog is not present.
Unknown initialization error.
Define additional Initiate Log Stream function status codes as required to support your operator.
Usage Notes
Consider the following when defining the Initiate Log Stream function.
Topic
Status
See Also
Usage Note
If the function status is PXSTC_Success, the message catalog for the operator was successfully initialized by this function
•
function
•
function
Example
#include <pxoper.h>
PX_ErrorProc myerror;
PX_Operator oprhandle;
PX_LogHandle *loghandle;
.
.
.
PX_Initiate(PX_Operator oprhandle)
{
.
.
.
.
/* Initiate a public log stream for instance 75 of "mycomponent". */
PX_LogInit(oprhandle,"mycomponent", 75, NULL, myerror, &loghandle);
Teradata Parallel Transporter Operator Programmer Guide 69
Chapter 3: Operator Interface Functions
Initiate Log Stream
.
/* Initiate a private log stream named "myreport" for instance 75 of
"mycomponent". */
PX_LogInit (oprhandle, "mycomponent", 75, "myreport", myerror,
&loghandle);
.
.
/* Initiate a private log stream named using user defined Teradata
Parallel Transporter script attribute */
/* (PrivateLogName) for instance 75 of "mycomponent". */
PX_GetAttribute(oprhandle, "PrivateLogName", (PX_AttributeValue
*)&value, &length);
PX_LogInit (oprhandle, "mycomponent", 75, value, myerror, &loghandle);
.
.
}
70 Teradata Parallel Transporter Operator Programmer Guide
Chapter 3: Operator Interface Functions
Put Attribute
Put Attribute
Purpose
Put Attribute is the service function that assigns a value to a specific operator attribute or to an accessible Teradata PT system attribute.
Structure
#include <pxoper.h>
PXSTC_Code PX_PutAttribute(PX_OperatorHandle operator,
PX_AttributeName attributeName,
PX_AttributeValue attributeValue,
PX_Length valueLength); where
Parameter
attributeName attributeValue operator valueLength
Function
input input input input
Specification
Name of the operator attribute to be assigned the value.
Address of the location containing the value to be assigned to the operator attribute.
Operator handle to which the attribute value is to be assigned.
Length of the value to be assigned to the operator attribute.
Return Codes
The following Put Attribute function status codes are defined by the Teradata PT operator interface:
Status Code
PXSTC_InvalidArgument
PXSTC_BadHandle
PXSTC_NotFound
PXSTC_Success
Signifies
One or more bad input arguments.
An undefined object handle.
The specified attribute was not found in the specified object.
Successful access to the specified attribute.
Usage Notes
Consider the following when defining the Put Attribute function.
Topic
System Attributes
Usage Notes
lists the Teradata PT system attributes that you can set with the Put Attributes function. See also the
Teradata Parallel Transporter Operator Programmer Guide 71
Chapter 3: Operator Interface Functions
Put Attribute
Topic
Status
Usage Notes
If the function status is PXSTC_Success the value was successfully assigned to the operator attribute.
Table 10: Put-Accessible System Attributes
Attribute Name
SYSTEM_Code
SYSTEM_UserAreaAddr
Data Type
PX_Code
PX_Addr
4
4
Data
Length
(in bytes) Description
System ABEND code
Address of the user area
72 Teradata Parallel Transporter Operator Programmer Guide
Chapter 3: Operator Interface Functions
Put Column Value
Put Column Value
Purpose
Put Column Value is the service function that stores a value in the specified column.
Structure
#include <pxoper.h>
PXSTC_Code PX_PutColumnValue(PX_ColumnHandle columnHandle,
PX_Indicator nullIndicator,
PX_Addr dataAddr,
PX_Length dataLength); where
Parameter
columnHandle dataAddr dataLength nullIndicator
Function
input input input input
Specification
Column handle where the value is to be stored.
The address of the value.
Length of the value.
Truth value indicating whether or not the column value can be
NULL.
Return Codes
The following Put Column Value function status codes are defined by the Teradata PT operator interface:
Status Code
PXSTC_InvalidArgument
PXSTC_BadHandle
PXSTC_Success
Signifies
One or more bad input arguments.
An undefined column handle.
Successful storage of the specified column value.
Usage Notes
Consider the following when defining the Put Column Value function.
Topic
Status
Usage Notes
If the function status is PXSTC_Success, the value is stored in the internal buffer associated with the specified column. See also the
Teradata Parallel Transporter Operator Programmer Guide 73
Chapter 3: Operator Interface Functions
Put Row
Put Row
Purpose
Put Row is the service function that stores a data row.
Structure
#include <pxoper.h>
PXSTC_Code PX_PutRow(PX_TableSchemaHandle tableSchemaHandle,
PX_Count columnCount,
PX_Indicator * nullIndicator,
PX_ByteOffset * offsets,
PX_Length * lengths,
PX_Addr rowAddr,
PX_Length rowLength); where
Parameter
columnCount lengths nullIndicator offsets
Function
input output output output
rowAddr rowLength
input input
tableSchemaHandle
input
Specification
Number of columns associated with the data row.
Pointer to the array of integers representing the length of the corresponding column value.
Pointer to the array of indicator bytes specifying whether or not the corresponding column value is NULL.
Pointer to the array of integers representing the corresponding column positions in terms of the number of bytes into the data row.
Pointer to the address of the data row to be stored.
Pointer to the length of the data row.
Table schema handle by which the data row is to be stored.
Return Codes
The following Put Row function status codes are defined by the Teradata PT operator interface:
Status Code Signifies
PXSTC_InvalidArgument One or more bad input arguments.
PXSTC_BadHandle
PXSTC_LengthError
PXSTC_Success
An undefined table schema handle.
Length of data to be stored does not match length of internal buffer.
Successful storage of the data row.
74 Teradata Parallel Transporter Operator Programmer Guide
Usage Notes
Consider the following when defining the Put Row function.
Chapter 3: Operator Interface Functions
Put Row
Topic
Indicator Mode Data
Status
See Also
Usage Notes
If the data row is in indicator mode, then the columnCount parameter must be zero and the following parameters must all be NULL:
•
nullIndicators
•
offsets
•
lengths
•
Teradata Call-Level Interface Version2 for Mainframe-Attached
Systems
•
Teradata Call-Level Interface Version2 for Network-Attached Systems
If the function status is PXSTC_Success, then the data row is stored in the internal buffer described by the table schema associated with the
dataSchemaHandle parameter.
•
Begin Table Schema Definition function
•
Finalize Table Schema Definition function
•
function
Teradata Parallel Transporter Operator Programmer Guide 75
Chapter 3: Operator Interface Functions
Read Checkpoint Record
Read Checkpoint Record
Purpose
Read Checkpoint Record is the service function that reads a checkpoint record.
Structure
#include <pxoper.h>
PXSTC_Code PX_ReadCheckpoint(PX_OperatorHandle operator,
PX_Addr * dataAddr,
PX_Length * dataLength); where
Parameter
dataAddr dataLength operator
Function
output output input
Specification
Pointer to the address of the checkpoint record.
Pointer to the length of the checkpoint record.
Operator handle from which the checkpoint record is to be read.
Return Codes
The following Read Checkpoint Record function status codes are defined by the Teradata PT operator interface:
Status Code
PXSTC_InvalidArgument
PXSTC_BadHandle
PXSTC_Success
Signifies
One or more bad input arguments.
An undefined operator handle.
Successful read of the checkpoint record.
Usage Notes
Consider the following when defining the Read Checkpoint Record function.
Topic
Status
Usage Notes
If the function status is PXSTC_Success, then the checkpoint record is stored in the location pointed to by the dataAddr parameter. See also the
function.
76 Teradata Parallel Transporter Operator Programmer Guide
Chapter 3: Operator Interface Functions
Read Global Variable
Read Global Variable
Purpose
Read Global Variable is the service function that retrieves the value of a global variable.
Structure
#include <pxoper.h>
PXSTC_Code PX_ReadGlobalVar(PX_OperatorHandle operator,
PX_Name varName,
PX_Count itemIndex,
PX_Addr * itemBufferAddr,
PC_Length * itemBufferSize); where
Parameter Function
itemBufferAddr
output
itemBufferSize itemIndex operator varName
output input input input
Specification
Pointer to the address of the buffer where the value of the global variable is stored.
Pointer to the size of the item buffer.
Item of the global variable to be retrieved.
The itemIndex parameter can range from 1 to the maximum limit specified when the global variable was created.
Operator handle by which the global variable is to be read.
Name of the global variable.
Return Codes
The following Read Global Variable function status codes are defined by the Teradata PT operator interface:
Status Code
PXSTC_InvalidArgument
PXSTC_BadHandle
PXSTC_Success
Signifies
One or more bad input arguments.
An undefined object handle.
A successful read access of the global variable.
Usage Notes
Consider the following when defining the Read Global Variable function.
Teradata Parallel Transporter Operator Programmer Guide 77
Chapter 3: Operator Interface Functions
Read Global Variable
Topic
Status
See Also
Usage Notes
If the function status is PXSTC_Success, then:
•
The value of the global variable is stored in the location pointed to by the itemBufferAddr parameter
•
The length of the global variable value is indicated by the
itemBufferSize pointer
•
Update Global Variable function
•
Create Global Variable function
78 Teradata Parallel Transporter Operator Programmer Guide
Chapter 3: Operator Interface Functions
Restart
Restart
Purpose
Restart is a user-provided function that performs any functionality when an operator is restarted by the infrastructure.
Structure
#include <pxoper.h>
PXSTC_Code PX_Restart(PX_OperatorHandle operator, PX_LongInt phase); where
Parameter
operator phase
Function
input input
Specification
Name of the operator handle to be restarted.
Current processing phase number
Return Codes
The following Restart function status codes are defined by the Teradata PT operator interface:
Status Code
PXSTC_EndMethod
PXSTC_NextPhase
PXSTC_SamePhase
Signifies
Successful restart of the operator.
Proceed with the next processing phase.
Continue with the current processing phase.
Define additional Restart function status codes as required to support your operator.
Usage Notes
Consider the following when defining the Restart function.
Topic
Status
Usage Notes
If the function status is PXSTC_EndMethod, the restart operation was successfully established by this function. See also the
function.
Teradata Parallel Transporter Operator Programmer Guide 79
Chapter 3: Operator Interface Functions
Set Error Message
Set Error Message
Purpose
Set Error Message is the service function that assigns an error message to the operator.
Structure
#include <pxoper.h>
PXSTC_Code PX_SetErrorMessage(PX_OperatorHandle operator,
PX_ErrorText message,
PX_Length messageLength); where
Parameter
message messageLength operator
Function
input input input
Specification
Location of the error message text.
Length of the error message text.
Operator handle to which the error message is assigned.
Return Codes
The following Set Error Message function status codes are defined by the Teradata PT operator interface:
Status Code
PXSTC_InvalidArgument
PXSTC_BadHandle
PXSTC_Success
Signifies
One or more bad input arguments.
An undefined object handle.
Successful setting of the error message.
Usage Notes
Consider the following when defining the Set Error Message function.
Topic
Status
Usage Notes
If the function status is PXSTC_Success, then:
•
The error message stored at the location specified by the message parameter will be saved by the operator
•
The length of the message is indicated by the messageLength parameter
80 Teradata Parallel Transporter Operator Programmer Guide
Chapter 3: Operator Interface Functions
Terminate
Terminate
Purpose
Terminate is the user-provided function that ends the operating environment of the operator.
Structure
#include <pxoper.h>
PXSTC_Code PX_Terminate(PX_OperatorHandle operator, PX_LongInt phase); where
Parameter
operator
Function Specification
input Operator handle associated with the Terminate function.
The operator parameter is a handle that identifies the operator that the
Terminate function is bound to. You can use this handle to terminate any of the Teradata PT service functions described in this chapter.
input Current processing phase number
phase
Return Codes
The following Terminate function status codes are defined by the Teradata PT operator interface:
Status Code
PXSTC_EndMethod
PXSTC_NextPhase
PXSTC_SamePhase
Signifies
Successful termination of the operator.
Proceed with the next processing phase.
Continue with the current processing phase.
Define additional Terminate function status codes as required to support your operator.
Usage Notes
Consider the following when defining the Terminate function.
Topic
Status
Usage Notes
If the function status is PXSTC_EndMethod, the processing environment was successfully terminated by this function. See also
function.
Teradata Parallel Transporter Operator Programmer Guide 81
Chapter 3: Operator Interface Functions
Terminate Log Stream
Terminate Log Stream
82
Purpose
Terminate Log Stream is the service function that ends the log stream. Each initiated log stream (PX_LogInit) must be terminated with a call of PX_LogTerminate with its own specific log handle.
Structure
#include <pxoper.h>
PXSTC_Code PX_LogTerminate(PX_LogHandle loghandle); where
Parameter
loghandle
Function
input
Specification
Handle to the log stream, freed by the Logger API.
Return Codes
The following Terminate Log Stream function status codes are defined by the Teradata PT operator interface:
Status Code
PXSTC_Success
PXSTC_LogCommunicati onError
PXSTC_UnknownError
Signifies
The call succeeded.
An error occurred from socket communication with the node Logger.
Unknown termination error.
Usage Notes
Consider the following when defining the Terminate Log Stream function.
Topic
Status
Usage Notes
If the function status if PXSTC_Success, the message catalog for the
operator was successfully terminated by this function. See also Initiate
Example
#include <pxoper.h>
PX_ErrorProc myerror;
PX_LogHandle loghandle;
PX_LogInit(oprhandle, "mycomponent", 75, NULL, myerror, &loghandle);
PX_LogTerminate(loghandle);
Teradata Parallel Transporter Operator Programmer Guide
Chapter 3: Operator Interface Functions
Update Global Variable
Update Global Variable
Purpose
Update Global Variable is the service function that assigns a value to a global variable.
Structure
#include <pxoper.h>
PXSTC_Code PX_UpdateGlobalVar(PX_OperatorHandle operator,
PX_Name varName,
PX_Addr itemBufferAddr,
PX_Length itemBufferSize);
PX_Count itemIndex, where
Parameter
itemBufferAddr itemBufferSize itemIndex operator varName
Function
input input input input input
Specification
Address of the buffer where the value to be assigned to the global variable is stored.
Size of the value in the item buffer.
Item of the global variable to be updated.
The itemIndex parameter can range from 1 to the maximum limit specified when the global variable was created.
Operator handle by which the global variable is to be updated.
Name of the global variable.
Return Codes
The following Update Global Variable function status codes are defined by the Teradata PT operator interface:
Status Code
PXSTC_InvalidArgument
PXSTC_BadHandle
PXSTC_LengthError
PXSTC_NotEnough
PXSTC_Success
Signifies
One or more bad input arguments.
An undefined operator handle.
The length of the update value does not match the length of the global variable buffer.
The global variable is too large.
A successful update access of the global variable.
Usage Notes
Consider the following when defining the Update Global Variable function.
Teradata Parallel Transporter Operator Programmer Guide 83
Chapter 3: Operator Interface Functions
Update Global Variable
Topic
Status
See Also
Usage Notes
If the function status is PXSTC_Success, the value stored at the
itemBufferAddr location is assigned to the specified itemIndex of the
varName global variable.
•
•
Create Global Variable function
84 Teradata Parallel Transporter Operator Programmer Guide
Chapter 3: Operator Interface Functions
Write Checkpoint Record
Write Checkpoint Record
Purpose
Write Checkpoint Record is the service function that writes a checkpoint record to the restart log file.
Structure
#include <pxoper.h>
PXSTC_Code PX_WriteCheckpoint(PX_OperatorHandle operator,
PX_Addr dataAddr,
PX_Length dataLength); where
Parameter
dataAddr dataLength operator
Function
input input input
Specification
Address of the checkpoint record to be written.
Length of the checkpoint record.
Operator handle from which the checkpoint record is to be read.
Return Codes
The following Write Checkpoint Record function status codes are defined by the Teradata PT operator interface:
Status Code
PXSTC_InvalidArgument
PXSTC_BadHandle
PXSTC_Success
Signifies
One or more bad input arguments.
An undefined operator handle.
Successful write of the checkpoint record.
Usage Notes
Consider the following when defining the Write Checkpoint Record function.
Topic
Status
Usage Notes
If the function status is PXSTC_Success, then the checkpoint record is written to the restart log table. See also the
function.
Teradata Parallel Transporter Operator Programmer Guide 85
Chapter 3: Operator Interface Functions
Write to Log Stream
Write to Log Stream
Purpose
Write to Log Stream is the service function that is used for submitting log messages.
Structure
#include <pxoper.h>
PXSTC_Code PX_LogWrite(PX_LogHandle loghandle,
PXInt32 messagenumber,
PXInt32 destination,
PXInt32 messagecategory,
...); where
Parameter
destination loghandle messagecategory messagenumber
Function
input input input input
Specification
Destination bit mask describing which destinations the message should go to. Any combination of LOG_DEST_CONS and
LOG_DEST_LOG is valid. Multiple destinations are entered by or’ing the values (LOG_DEST_CONS | LOG_DEST_LOG)
Handle to the log stream (returned from PX_LogInit())
Category of the message. The valid message categories are:
•
LOG_DEBUG
•
LOG_TRACE
•
LOG_INFO
•
LOG_WARNING
•
LOG_FATALERROR
•
LOG_USERERROR
Number of the message in the message catalog.
The message catalog is identified in the DEFINE OPERATOR statement in the Teradata PT script.
The message described by the message number, is used as a format string when accessed from the Log View Client.
86 Teradata Parallel Transporter Operator Programmer Guide
Chapter 3: Operator Interface Functions
Write to Log Stream
Parameter
...
Function
input
Specification
Arguments to the message (1..*).
This variable list of parameters is the arguments that will go into the format string from the message catalog. Each argument is supplied with type and value. This is handled by a set of macros in the following way:
•
LOG_INT16(val) - Short integer values. For example,
LOG_INT16(5) corresponds to supplying the short value 5.
•
LOG_INT32(val) - Long integer values. E.g. LOG_INT32(56) corresponds to supplying the long value 56.
•
LOG_INT64(val) - Long long values. E.g. LOG_INT64(578) corresponds to supplying the long value 578.
•
LOG_CHAR(val) - Character values. E.g. LOG_CHAR('g') corresponds to supplying the character 'g'.
•
LOG_STRING(val) - String values. E.g.
LOG_STRING("mystring") corresponds to supplying the string
"mystring".
•
LOG_FLOAT(val) - 32 bit floating point values. E.g.
LOG_FLOAT(5.4) corresponds to supplying the floating point value 5.4.
•
LOG_DOUBLE(val) - 64 bit floating point values. E.g.
LOG_DOUBLE(5.7) corresponds to supplying the double precision floating point value 5.7.
This list must always end with PXEOP (EndOfParameterList) as the last parameter. Failure to do so will make the program loop and eventually incur a memory fault.
Return Codes
The following Write to Log Stream function status codes are defined by the Teradata PT operator interface:
Status Code
PXSTC_Success
PXSTC_Log
CommunicationError
PXSTC_LogInsuffMem
Error
PXSTC_InvalidDataType
PXSTC_NoMessage
Catalog
PXSTC_UnknownError
Signifies
The call succeeded.
An error occurred from socket communication with the Node
Logger.
A memory allocation failure.
The type of some of the parameters is unknown to the Logger API.
The requested message catalog is not present.
Unknown error encountered when writing a log record.
Teradata Parallel Transporter Operator Programmer Guide 87
Chapter 3: Operator Interface Functions
Write to Log Stream
Usage Notes
Consider the following when defining the Write to Log Stream function.
Topic
Status
Usage Notes
If the function status if PXSTC_Success, the message was successfully written to the message catalog by this function. See also
Example
#include <pxoper.h>
PX_ErrorProc myerror;
PX_LogHandle loghandle;
PX_LogInit(oprhandle, "mycomponent", 75, NULL, myerror, &loghandle);
.
PX_LogWrite(loghandle, mymessagenumber,
LOG_DEST_CONS | LOG_DEST_LOG,
LOG_FATALERROR, ...);
.
PX_LogTerminate(loghandle);
88 Teradata Parallel Transporter Operator Programmer Guide
Downloaden
Openbare link bijgewerkt
De openbare link naar uw chat is bijgewerkt. You may view and manage your chat links after registration here.
Openbare link document
Advertentie