15.00 - Service Functions - Parallel Transporter

Teradata Parallel Transporter Operator Programmer Guide

prodname
Parallel Transporter
vrm_release
15.00
category
Programming Reference
featnum
B035-2435-034K

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 11: Service Functions 

Function

Use

Allocate Storage
Free Storage

Allocating and freeing Teradata PT storage for your operator.

Create Global Variable
Read Global Variable
Update Global Variable
Delete Global Variable

Creating, accessing, and deleting global variables.

Put Attribute
Get Attribute

Storing and retrieving attribute values.

Put Row
Get Row

Storing and retrieving data rows.

Put Column Value
Get Column Value

Storing and retrieving column values.

Write Checkpoint Record
Read Checkpoint Record

Storing and retrieving checkpoint records.

Create Column Schema
Get Column Schema

Creating and accessing column schemas.

Begin Table Schema Definition
Finalize Table Schema Definition

Creating table schemas.

Get Table Schema List
Get Column Schema List

Retrieving lists of table and column schemas.

Set Error Message

Creating error messages.

Initiate Log Stream
Write to Log Stream
Terminate Log Stream

Initiating, writing, and terminating a log stream function.

Define Error Handler

Redirecting a call after an error occurs in the Logger API.

Complete descriptions for each of the above functions follow in the next section.

Allocate Storage

Purpose  

Allocate Storage is the service function that allocates Teradata PT storage for the operator.

Structure

#include <pxoper.h>
PXSTC_Code PX_AllocateStorage(PX_OperatorHandle operator, 
   PX_Length storageSize, 
   PX_Addr * storageAddr);

where:

 

Parameter

Function

Specification

operator

input

Instance of the operator for which the storage is to be allocated.

storageSize

input

Amount of storage you want to allocate to the named operator.

storageAddr

output

Pointer to the address of the allocated storage.

Return Codes

The following Allocate Storage function status codes are defined by the Teradata PT operator interface.

 

Status Code

Signifies

PXSTC_InvalidArgument

One or more bad input arguments.

PXSTC_BadHandle

An undefined object handle.

PXSTC_NotEnough

Either:

  • Not enough storage can be allocated
  • The requested storage size is too large
  • PXSTC_Success

    Successful access to the object attribute.

    Usage Notes  

    Consider the following when using the Allocate Storage function.

     

    Topic

    Usage Note

    Status

    If the function status is PXSTC_Success, the storage address will be stored in the location indicated by the storageAddr pointer. See also the Free Storage function.

    Begin Table Schema Definition

    Purpose  

    Begin Table Schema Definition is the service function that starts the definition of a table schema for the operator.

    Structure

    #include <pxoper.h>
    PXSTC_Code PX_BeginTableSchemaDefinition(
       PX_OperatorHandle operator, 
       PX_SchemaType schemaType, 
       PX_TableSchemaHandle * tableSchemaHandle);

    where:

     

    Parameter

    Function

    Specification

    operator

    input

    Instance of the operator for which the table schema is being defined.

    schemaType

    input

    Schema type, which can be either:

  • PX_InputSchema
  • PX_OutputSchema
  • PX_InputOutputSchema
  • tableSchemaHandle

    output

    Pointer to the defined table schema.

    Return Codes

    The following Begin Table Schema Definition function status codes are defined by the Teradata PT operator interface:

     

    Status Code

    Signifies

    PXSTC_InvalidArgument

    One or more bad input arguments.

    PXSTC_BadHandle

    An undefined object handle.

    PXSTC_Success

    Successful initiation of the table schema definition.

    Usage Notes  

    Consider the following when using the Begin Table Schema Definition function.

     

    Topic

    Usage Note

    Status

    If the function status is PXSTC_Success, the table schema handle will be stored in the location indicated by the tableSchemaHandle pointer. See also the Finalize Table Schema Definition function.

    Checkpoint

    Purpose  

    Checkpoint is a user-provided function that creates a checkpoint record for operators.

    Structure

    #include <pxoper.h>
    PXSTC_Code PX_Checkpoint(PX_OperatorHandle operator, PX_LongInt phase);

    where:

     

    Parameter

    Function

    Specification

    operator

    input

    Operator handles associated with the Checkpoint function.

    phase

    input

    Current processing phase number

    Return Codes

    The following Checkpoint function status codes are defined by the Teradata PT operator interface:

     

    Status Code

    Signifies

    PXSTC_EndMethod

    Successful checkpoint processing.

    This status condition indicates that the checkpoint record was successfully written to the restart log by this function.

    PXSTC_NextPhase

    Proceed with the next processing phase.

    PXSTC_SamePhase

    Continue with the current processing phase.

    Define additional Checkpoint function status codes as required to support your operator.

    Usage Notes  

    Consider the following when using the Checkpoint function.

     

    Topic

    Usage Note

    Description

    Use the Checkpoint function to record the checkpoint information identified by the operator parameter. See also the Restart function.

    Create Column Schema

    Purpose  

    Create Column Schema is the service function that creates the schema for a column.

    Structure

    #include <pxoper.h>
    PXSTC_Code PX_CreateColumnSchema(
       PX_TableSchemaHandle tableSchemaHandle,
       PX_ColumnName columnName,
       PX_DataType dataType,
       PX_Length dataLength,
       PX_ByteOffset offset,
       PX_Precision precision,
       PX_Scale scale,
       PX_TruthValue nullIndicator,
       PX_ColumnSchemaHandle * columnHandle);

    where:

     

    Parameter

    Function

    Specification

    columnHandle

    output

    Column handle for which the schema is being created.

    columnName

    input

    Column-name attribute of the column schema.

    dataLength

    input

    Column length for both numeric and nonnumeric data types.

    dataType

    input

    Data type attribute of the column schema.

    nullIndicator

    input

    Truth value indicating whether or not the column value can be NULL.

    offset

    input

    Column position in terms of the number of bytes into the data row. An offset specification of -1 signifies that no column position is defined.

    precision

    input

    Precision value (number of digits) for a numeric data type.

    The precision specification can range from 1 to 38.

    scale

    input

    Scale value (number of digits to the right of the decimal point) for a numeric data type.

    tableSchemaHandle

    input

    Data schema handle by which the column schema will be created.

    Return Codes

    The following Create Column Schema function status codes are defined by the Teradata PT operator interface:

     

    Status Code

    Signifies

    PXSTC_InvalidArgument

    One or more bad input arguments.

    PXSTC_BadHandle

    An undefined data schema handle.

    PXSTC_Success

    Successful creation of the column schema definition.

    Usage Notes  

    Consider the following when using the Create Column Schema function.

     

    Topic

    Usage Notes

    Data Type Specifications

    Teradata PT supports the following data type specifications:

  • PX_DataType_Integer
  • PX_DataType_SmallInt
  • PX-DataType_LongInt
  • PX_DataType_Float
  • PX_DataType_Decimal
  • PX_DataType_Char
  • PX_DataType_ByteInt
  • PX_DataType_VarChar
  • PX_DataType_Byte
  • PX_DataType_VarByte
  • PX_DataType_Graphic
  • PX_DataType_VarGraphic
  • PX_DataType_Date
  • PX_DataType_Date_ANSI
  • PX_DataType_Boolean
  • Valid abbreviations in data type specifications:

  • CHARACTERS as:
  • CHARACTER
  • CHARS
  • CHAR
  • DECIMAL as DEC
  • INTEGER as INT
  • Status

    If the function status is PXSTC_Success, the column schema will be stored in the location indicated by the columnHandle pointer. See also the Get Column Schema function.

    Create Global Variable

    Purpose  

    Create Global Variable is the service function that creates a global variable for the operator.

    Structure

    #include <pxoper.h>
    PXSTC_Code PX_CreateGlobalVar(PX_OperatorHandle operator,
       PX_Name varName,
       PX_Length varSize,
       PX_Count varCount);

    where:

     

    Parameter

    Function

    Specification

    operator

    input

    Instance of the operator handle for which the global variable is being created.

    varCount

    input

    Maximum number items to be created for the global variable.

    varName

    input

    Name of the global variable.

    varSize

    input

    Item size of the global variable, in bytes.

    Return Codes

    The following Create Global Variable function status codes are defined by the Teradata PT operator interface:

     

    Status Code

    Signifies

    PXSTC_InvalidArgument

    One or more bad input arguments.

    PXSTC_BadHandle

    An undefined object handle.

    PXSTC_NotEnough

    The global variable size is too large

    PXSTC_Success

    Successful creation of the global variable.

    Usage Notes  

    Consider the following when using the Create Global Variable function.

     

    Topic

    Usage Notes

    Status

    If the function status is PXSTC_Success, all items of the global variable were created successfully.

    Delete Global Variable

    Purpose  

    Delete Global Variable is the service function that deletes a global variable that had been created for the operator.

    Structure

    #include <pxoper.h>
    PXSTC_Code PX_DeleteGlobalVar(PX_OperatorHandle operator, PX_Name varName);

    where:

     

    Parameter

    Function

    Specification

    operator

    input

    Instance of the operator handle for which the global variable is being deleted.

    varName

    input

    Name of the global variable.

    Return Codes

    The following Delete Global Variable function status codes are defined by the Teradata PT operator interface:

     

    Status Code

    Signifies

    PXSTC_InvalidArgument

    One or more bad input arguments.

    PXSTC_BadHandle

    An undefined object handle.

    PXSTC_Success

    Successful deletion of the global variable.

    Usage Notes  

    Consider the following when using the Delete Global Variable function.

     

    Topic

    Usage Notes

    Status

    If the function status is PXSTC_Success, all items of the global variable were deleted successfully. See also the Create Global Variable function.

    Define Error Handler

    Purpose  

    Define Error Handler is the service function that identifies the function to be called if an error occurs in the Logger API. The return value is a pointer to the function previously called when an error occurred.

    Structure

    #include <pxoper.h>
    PXSTC_Code PX_SetLogError(PX_LogHandle loghandle, PX_ErrorProc errorproc);

    where:

     

    Parameter

    Function

    Specification

    loghandle

    input

    The handle to the log stream. The structure is allocated by the Logger API.

    errorproc

    input

    The function to be called when an error occurs.

    Return Codes

    The Define Error Handler function returns the address of the function previously defined.

     

    Status Code

    Signifies

    void*

    The address of the error procedure previously used.

    Usage Notes  

    Consider the following when using the Define Error Handler function.

     

    Topic

    Usage Notes

    See Also

    Initiate Log Stream

    Example  

    #include <pxoper.h>
    PX_ErrorProc  myerror1, myerror2;
    PX_LogHandle loghandle;
    PX_LogInit(oprhandle, "mycomponent", 75, NULL, myerror1, &loghandle);
    .
    PX_SetLogError(loghandle, myerror2);
    .
    PX_Terminate(loghandle);

    Event

    Purpose  

    Event is a user-provided function that allows operators to perform event processing or notification.

    Structure

    #include <pxoper.h>
    PXSTC_Code PX_Event(PX_OperatorHandle operator, PX_LongInt phase);

    where:

     

    Parameter

    Function

    Specification

    operator

    input

    Operator handle that is associated with the Event function.

    phase

    input

    Current processing phase number.

    Return Codes

    The following Event function status codes are defined by the Teradata PToperator interface:

     

    Status Code

    Signifies

    PXSTC_EndMethod

    Successful execution of the operator.

    This status condition indicates that the event was successfully processed by this function.

    PXSTC_NextPhase

    Proceed with the next processing phase.

    PXSTC_SamePhase

    Continue with the current processing phase.

    Define additional Event function status codes as required to support your operator.

    Usage Notes  

    Consider the following when using the Event function.

     

    Topic

    Usage Notes

    Description

    This function requires the caller to user the PutAttribute function to specify the event to be processed by the operator.

    Also see “Put Attribute” on page 74.

    Execute

    Purpose  

    Execute is a user-provided function that executes a data processing function for the operator.

    Structure

    #include <pxoper.h>
    PXSTC_Code PX_Execute(PX_OperatorHandle operator, PX_LongInt phase);

    where:

     

    Parameter

    Function

    Specification

    operator

    input

    Operator handle associated with the Execute function.

    The operator parameter is a handle that identifies the operator that the Execute function is bound to. You can use this handle to invoke any of the Teradata PT service functions described in this chapter.

    phase

    input

    Current processing phase number

    Return Codes

    The following Execute function status codes are defined by the Teradata PT operator interface. Define additional Execute function status codes required to support your operator.

     

    Status Code

    Signifies

    PXSTC_EndMethod

    Successful execution of the operator.

    PXSTC_EndOfData

    End of data

    PXSTC_NextPhase

    Proceed with the next processing phase.

    PXSTC_SamePhase

    Continue with the current processing phase.

    Usage Notes  

    Define additional Execute function status codes as required to support your operator.

     

    Topic

    Usage Notes

    Description

    Use the Execute function to process data row-by-row, as specified by the operator parameter. The following results occur:

  • PXSTC_EndMethod - all rows were successfully processed.
  • PXSTC_NextPhase - advance to the next phase in the same method
  • PXSTC_SamePhase - a row was successfully processed.
  • See also the Initiate function and the Terminate function

    Finalize Table Schema Definition

    Purpose  

    Finalize Table Schema Definition is the service function that finalizes the process of creating the table schema.

    Structure

    #include <pxoper.h>
    PXSTC_Code PX_FinalizeTableSchemaDefinition(PX_TableSchemaHandle tableSchemaHandle);

    where:

     

    Parameter

    Function

    Specification

    tableSchemaHandle

    input

    Table schema handle function to be finalized.

    Return Codes

    The following Finalize Table Schema Definition function status codes are defined by the Teradata PT operator interface:

     

    Status Code

    Signifies

    PXSTC_Conflict

    Mismatching type of operations, data, or protocols.

    PXSTC_CountError

    The specified number of objects does not match some predefined value.

    PXSTC_LengthError

    The length of the data to be stored does not match the length of the internal buffer.

    PXSTC_BadHandle

    An undefined table schema handle.

    PXSTC_SchemaError

    An error was detected in the data schema.

    PXSTC_Success

    Successful creation of the table schema.

    Usage Notes  

    Consider the following when using the Finalize Table Schema Definition function.

     

    Topic

    Usage Notes

    Description

    You must use the Finalize Data Schema Definition function to finalize a data schema before it can be used by Teradata PT operators for subsequent data manipulation functions.

    Status

    If the function status is PXSTC_Success, the defined table schema can be used by Teradata PT operators. See also Begin Table Schema Definition.

    Free Storage

    Purpose  

    Free Storage is the service function that frees the operator storage that was previously allocated.

    Structure

    #include <pxoper.h>
    PXSTC_Code PX_FreeStorage(PX_OperatorHandle operator, PX_Addr storageAddr);

    where:

     

    Parameter

    Function

    Specification

    operator

    input

    Operator handle for which the storage is to be freed.

    storageAddr

    input

    Address of the storage to be freed.

    Return Codes

    The following Free Storage function status codes are defined by the Teradata PT operator interface:

     

    Status Code

    Signifies

    PXSTC_InvalidArgument

    One or more bad input arguments.

    PXSTC_BadHandle

    An undefined object handle.

    PXSTC_Success

    Successful access to the object attribute.

    Usage Notes  

    Consider the following when defining the Free Storage function.

     

    Topic

    Usage Notes

    Status

    If the function status is PXSTC_Success, the storage at the location indicated by the storageAddr pointer was successfully freed. See also Allocate Storage.

    Get Attribute

    Purpose  

    Get Attribute is the service function that retrieves the value of a specific attribute associated with the operator.

    Structure

    #include <pxoper.h>
    PXSTC_Code PX_GetAttribute(PX_OperatorHandle operator,
       PX_AttributeName attributeName,
       PX_AttributeValue * attributeValue,
       PX_Length * valueLength);

    where:

     

    Parameter

    Function

    Specification

    attributeName

    input

    Name of the object attribute.

    attributeValue

    output

    Retrieved value of the specified attribute.

    operator

    input

    Operator handle from which the attribute is to be retrieved.

    valueLength

    output

    Length of the retrieved attribute value.

    Return Codes

    The following Get Attribute function status codes are defined by the Teradata PT operator interface:

     

    Status Code

    Signifies

    PXSTC_InvalidArgument

    One or more bad input arguments.

    PXSTC_BadHandle

    An undefined object handle.

    PXSTC_NotFound

    The specified attribute was not found in the specified object.

    PXSTC_Success

    Successful access to the specified attribute.

    Usage Notes  

    Consider the following when defining the Get Attribute function.

     

    Topic

    Usage Notes

    System Attributes

    Table 12 on page 60 lists the Teradata PT system attributes that you can retrieve with the Get Attributes function. See also Put Attribute.

    Status

    If the function status is PXSTC_Success:

  • The address of the attribute value is stored as the attributeValue parameter.
  • The valueLength parameter indicates the length of the attribute value.
  •  

    Table 12: Get-Accessible System Attributes 


    Attribute Name


    Data Type

    Data Length
    (in bytes)


    Description

    SYSTEM_Code

    PX_Code

    4

    System ABEND code

    SYSTEM_FilterHandle

    PX_FilterHandle

    4

    Handle of the filter object

    SYSTEM_GlobalHandle

    PX_GlobalHandle

    4

    Handle of the global anchor

    SYSTEM_InstanceNumber

    PX_Number

    4

    Instance number of the operator, starting from 1

    SYSTEM_MaxInstances

    PX_Count

    4

    Maximum number of instances that can be created for the operator

    SYSTEM_OperatorName

    PX_Addr

    4

    Address of string containing the operator name

    SYSTEM_OperatorType

    PX_Number

    4

    Code indicating type of operator: producer=1, consumer=2, filter=3

    SYSTEM_PhaseNumber

    PX_Count

    4

    Current processing phase number

    SYSTEM_UserAreaAddr

    PX_Addr

    4

    Address of the user area

    Get Column Schema

    Purpose  

    Get Column Schema is the service function that retrieves the column schema associated with a column.

    Structure

    #include <pxoper.h>
    PXSTC_Code PX_GetColumnSchema(
       PX_ColumnSchemaHandle columnHandle,
       PX_ColumnName *columnName,
       PX_DataType * dataType,
       PX_Length * dataLength,
       PX_ByteOffset * offset,
       PX_Precision * precision,
       PX_Scale * scale,
       PX_TruthValue * nullIndicator);

    where:

     

    Parameter

    Function

    Specification

    columnHandle

    output

    Column handle from which the column schema is to be obtained.

    columnName

    output

    Column-name attribute of the column schema.

    dataLength

    output

    Column length for both numeric and nonnumeric data types.

    dataType

    output

    Data type attribute of the column schema.

    nullIndicator

    output

    Truth value indicating whether or not the column value can be NULL.

    offset

    output

    Column position in terms of the number of bytes into the data row.

    An offset specification of -1 signifies that no column position is defined.

    precision

    output

    Precision value (number of digits) for a numeric data type.

    The precision specification can range from 1 to 38.

    scale

    output

    Scale value (number of digits to the right of the decimal point) for a numeric data type.

    Return Codes

    The following Get Column Schema function status codes are defined by the Teradata PT operator interface:

     

    Status Code

    Signifies

    PXSTC_InvalidArgument

    One or more bad input arguments.

    PXSTC_BadHandle

    An undefined column schema handle.

    PXSTC_Success

    Successful retrieval of the column schema.

    Usage Notes  

    Consider the following when defining thee Get Column Schema function.

     

    Topic

    Usage Notes

    Status

    If the function status is PXSTC_Success the values of the output parameters are returned. See also Create Column Schema.

    Get Column Schema List

    Purpose  

    Get Column Schema List is the service function that retrieves the list of column handles associated with a table schema.

    Structure

    #include <pxoper.h>
    PXSTC_Code PX_GetColumnSchemaList(
       PX_TableSchemaHandle tableSchemaHandle,
       PX_ColumnSchemaList * columnSchemaList,
       PX_Count * columnSchemaCount);

    where:

     

    Parameter

    Function

    Specification

    columnSchemaCount

    output

    Number of column schemas in the list.

    columnSchemaList

    output

    Pointer to the location of the retrieved column schema list.

    tableSchemaHandle

    input

    Table schema handle from which the column schema list is to be retrieved.

    Return Codes

    The following Get Column Schema List function status codes are defined by the Teradata PT operator interface:

     

    Status Code

    Signifies

    PXSTC_InvalidArgument

    One or more bad input arguments.

    PXSTC_BadHandle

    An undefined data schema handle.

    PXSTC_NotFound

    The specified column schema list was not found in the specified object.

    PXSTC_Success

    Successful retrieval of the list of column handles.

    Usage Notes  

    Consider the following when defining the Get Column Schema List function.

     

    Topic

    Usage Notes

    Status

    If the function status is PXSTC_Success, the address of the column schema list is stored in the location pointed to by the columnSchemaList parameter. See also Get Table Schema List.

    Get Column Value

    Purpose  

    Get Column Value is the service function that retrieves the data value associated with a column.

    Structure

    #include <pxoper.h>
    PXSTC_Code PX_GetColumnValue(PX_ColumnHandle columnHandle,
       PX_Indicator * nullIndicator,
       PX_DataAddr * dataAddr,
       PX_Length * dataLength);

    where:

     

    Parameter

    Function

    Specification

    columnHandle

    input

    Column handle from which the column value is to be retrieved.

    dataAddr

    output

    Pointer to the address of the column value.

    dataLength

    output

    Pointer to the length of the column value.

    nullIndicator

    output

    Pointer to the indication of whether or not the column value is NULL.

    Return Codes

    The following Get Column Value function status codes are defined by the Teradata PT operator interface:

     

    Status Code

    Signifies

    PXSTC_InvalidArgument

    One or more bad input arguments.

    PXSTC_BadHandle

    An undefined column handle.

    PXSTC_Success

    Successful projection of data value to the column.

    Usage Notes  

    Consider the following when defining the Get Column Value function.

     

    Topic

    Usage Notes

    Status

    If the function status is PXSTC_Success:

  • The nullIndicator parameter indicates whether or not the column value is NULL.
  • The dataAddr parameter stores the address of the column value.
  • The dataLength parameter stores the length of the returned column value.
  • See also the Put Column Value function.

    Get Row

    Purpose  

    Get Row is the service function that retrieves a data row.

    Structure

    #include <pxoper.h>
    PXSTC_Code PX_GetRow(PX_TableSchemaHandle tableSchemaHandle,
       PX_Count * columnCount,
       PX_Indicator ** nullIndicator,
       PX_ByteOffset ** offsets,
       PX_Length ** lengths,
       PX_Addr * rowAddr,
       PX_Length * rowLength);

    where:

     

    Parameter

    Function

    Specification

    columnCount

    output

    Pointer to the number of columns associated with the data row.

    lengths

    output

    Pointer to the array of integers representing the length of the corresponding column value.

    nullIndicator

    output

    Pointer to the array of indicator bytes specifying whether or not the corresponding column value is NULL.

    offsets

    output

    Pointer to the array of integers representing the corresponding column positions in terms of the number of bytes into the data row.

    rowAddr

    output

    Pointer to the address of the data row.

    rowLength

    output

    Pointer to the length of the data row.

    tableSchemaHandle

    input

    Table schema handle by which the data row is to be obtained.

    Return Codes

    The following Get Row function status codes are defined by the Teradata PT operator interface:

     

    Status Code

    Signifies

    PXSTC_BadHandle

    An undefined data schema handle.

    PXSTC_Success

    Successful retrieval of the data row.

    PXSTC_EndOfData

    End of data.

    Usage Notes  

    Consider the following when defining the Get Row function.

     

    Topic

    Usage Notes

    Return Data Format

    Data rows returned by the Get Row function are always prefixed with NULL indicator bytes.

    Status

    If the function status is PXSTC_Success:

  • The rowAddr parameter stores the address of the data row.
  • The rowLength parameter stores the length of the data row.
  • The columnCount parameter stores the number of columns associated with the data row.
  • The nullIndicators parameter is the address of the array indicating whether or not the column values are NULL.
  • The offsets parameter is the address of the array that indicates the byte offsets into the data row.
  • The lengths parameter is the address of the array that indicates the lengths of the column values.
  • See Also

  • Begin Table Schema Definition function
  • Finalize Table Schema Definition function
  • Put Row function
  • Get Table Schema List

    Purpose  

    Get Table Schema List is the service function that retrieves the table schemas associated with an operator.

    Structure

    #include <pxoper.h>
    PXSTC_Code PX_GetTableSchemaList(
       PX_OperatorHandle operator,
       PX_SchemaType schemaType,
       PX_TableSchemaList * tableSchemaList,
       PX_Count * tableSchemaCount);

    where:

     

    Parameter

    Function

    Specification

    operator

    input

    Operator handle from which the list of table schemas is to be retrieved.

    schemaType

    input

    Schema type, which can be either:

  • PX_InputSchema
  • PX_OutputSchema
  • PX_InputOutputSchema
  • tableSchemaList

    output

    Pointer to the address of the list of table schemas.

    tableSchemaCount

    output

    Pointer to the number of schemas in the table schema list.

    Return Codes

    The following Get Table Schema List function status codes are defined by the Teradata PT operator interface:

     

    Status Code

    Signifies

    PXSTC_InvalidArgument

    One or more bad input arguments.

    PXSTC_BadHandle

    An undefined operator handle.

    PXSTC_NotFound

    The specified table list was not found in the specified object.

    PXSTC_Success

    Successful fetching of the table schema list.

    Usage Notes  

    Consider the following when defining the Get Table Schema List function.

     

    Topic

    Usage Notes

    Status

    If the function status is PXSTC_Success:

  • The address of the table schema list is stored at the location indicated by the tableSchemaList parameter.
  • The tableSchemaCount parameter points to the number of table schemas in the list.
  • See Also

  • Begin Table Schema Definition function
  • Finalize Table Schema Definition function
  • Initiate

    Purpose  

    Initiate is the user-provided function that establishes the processing environment for an operator.

    Structure

    #include <pxoper.h>
    PXSTC_Code PX_Initiate(PX_OperatorHandle operator, PX_LogInt phase);

    where:

     

    Parameter

    Function

    Specification

    operator

    input

    Operator handle associated with the Initiate function.

    The operator parameter is a handle that identifies the operator that the Initiate function is bound to. You can use this handle to invoke any of the Teradata PT service functions described in this chapter.

    phase

    input

    Current processing phase number

    Return Codes

    The following Initiate function status codes are defined by the Teradata PT operator interface:

     

    Status Code

    Signifies

    PXSTC_EndMethod

    Successful initialization of the operator.

    PXSTC_NextPhase

    Proceed with the next processing phase.

    PXSTC_SamePhase

    Continue with the current processing phase.

    Define additional Initiate function status codes as required to support your operator.

    Usage Notes  

    Consider the following when defining the Initiate function.

     

    Topic

    Usage Notes

    Status

    If the function status is PXSTC_EndMethod, the processing environment was successfully established by this function. See also the Terminate function.

    Initiate Log Stream

    Purpose  

    Initiate Log Stream is used for initiating a log stream. The message catalog name is supplied in the Teradata PT script to make the Log View Server or Log View Client generate the messages. The logging facility itself does not use the message catalog.

    Structure

    #include <pxoper.h>
    PXSTC_Code PX_LogInit(PX_OperatorHandle oprhandle,
       char  *componentname,
       PX_Number instancenumber
       char  *outputlogreport,
       PX_ErrorProc  errorproc,
       PX_LogHandle *loghandle);

    where:

     

    Parameter

    Function

    Specification

    componentname

    input

    Name of the component.

    instancenumber

    input

    Number of the operator instance.

    loghandle

    output

    Handle to the log stream, allocated by the Logger API.

    The caller is responsible for passing the address of a PX_LogHandle pointer to PX_LogInit, but the Logger API is responsible for allocating the structure.

    errorproc

    input

    Pointer to the function to be called if an error occurs in the Logger API, or NULL if no specific error handling is wanted.

    oprhandle

    input

    Handle to the operator.

    outputlogreport

    input

    Name of the private log report, or NULL, if the log report is public.

    The outputlogreport parameter may contain an explicit character value, for example, PrivateFileName, or it may be NULL. If NULL is specified, the log becomes PUBLIC.

    Return Codes

    The following Initiate Log Stream function status codes are defined by the Teradata PT operator interface:

     

    Status Code

    Signifies

    PXSTC_Success

    The call succeeded.

    PXSTC_LogInsuff
    MemError

    Memory allocation failure.

    PXSTC_CatalogError

    No message catalog specified.

    PXSTC_Log
    CommunicationError

    Error from socket communication with the Node Logger.

    PXSTC_LogPassword

    The Logger API has supplied a wrong password for the logger (indicates an attempt to access the logger without using the supplied API).

    PXSTC_InvalidData
    Type

    The type of some of the parameters is unknown to the Logger API.

    PXSTC_NoMessage
    Catalog

    The requested message catalog is not present.

    PXSTC_Unknown
    Error

    Unknown initialization error.

    Define additional Initiate Log Stream function status codes as required to support your operator.

    Usage Notes  

    Consider the following when defining the Initiate Log Stream function.

     

    Topic

    Usage Note

    Status

    If the function status is PXSTC_Success, the message catalog for the operator was successfully initialized by this function

    See Also

  • Terminate Log Stream function
  • Write to Log Stream function
  • Example  

    #include <pxoper.h>
    PX_ErrorProc  myerror;
    PX_Operator oprhandle;
    PX_LogHandle *loghandle;
    .
    .
    .
    PX_Initiate(PX_Operator oprhandle) 
    {
    .
    .
    .
    .
    /* Initiate a public log stream for instance 75 
    of "mycomponent". */
    PX_LogInit(oprhandle,"mycomponent", 75, NULL, myerror, &loghandle);
    .
    /* 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);
    .
    .
    }

    Put Attribute

    Purpose  

    Put Attribute is the service function that assigns a value to a specific operator attribute or to an accessible Teradata PT system attribute.

    Structure

    #include <pxoper.h>
    PXSTC_Code PX_PutAttribute(PX_OperatorHandle operator,
       PX_AttributeName attributeName,
       PX_AttributeValue attributeValue,
       PX_Length valueLength);

    where:

     

    Parameter

    Function

    Specification

    attributeName

    input

    Name of the operator attribute to be assigned the value.

    attributeValue

    input

    Address of the location containing the value to be assigned to the operator attribute.

    operator

    input

    Operator handle to which the attribute value is to be assigned.

    valueLength

    input

    Length of the value to be assigned to the operator attribute.

    Return Codes

    The following Put Attribute function status codes are defined by the Teradata PT operator interface:

     

    Status Code

    Signifies

    PXSTC_InvalidArgument

    One or more bad input arguments.

    PXSTC_BadHandle

    An undefined object handle.

    PXSTC_NotFound

    The specified attribute was not found in the specified object.

    PXSTC_Success

    Successful access to the specified attribute.

    Usage Notes  

    Consider the following when defining the Put Attribute function.

     

    Topic

    Usage Notes

    System Attributes

    Table 13 on page 75 lists the Teradata PT system attributes that you can set with the Put Attributes function. See also the Get Attribute function.

    Status

    If the function status is PXSTC_Success the value was successfully assigned to the operator attribute.

     

    Table 13: Put-Accessible System Attributes


    Attribute Name


    Data Type

    Data Length
    (in bytes)


    Description

    SYSTEM_Code

    PX_Code

    4

    System ABEND code

    SYSTEM_UserAreaAddr

    PX_Addr

    4

    Address of the user area

    Put Column Value

    Purpose  

    Put Column Value is the service function that stores a value in the specified column.

    Structure

    #include <pxoper.h>
    PXSTC_Code PX_PutColumnValue(PX_ColumnHandle columnHandle,
       PX_Indicator nullIndicator,
       PX_Addr dataAddr,
       PX_Length dataLength);

    where:

     

    Parameter

    Function

    Specification

    columnHandle

    input

    Column handle where the value is to be stored.

    dataAddr

    input

    The address of the value.

    dataLength

    input

    Length of the value.

    nullIndicator

    input

    Truth value indicating whether or not the column value can be NULL.

    Return Codes

    The following Put Column Value function status codes are defined by the Teradata PT operator interface:

     

    Status Code

    Signifies

    PXSTC_InvalidArgument

    One or more bad input arguments.

    PXSTC_BadHandle

    An undefined column handle.

    PXSTC_Success

    Successful storage of the specified column value.

    Usage Notes  

    Consider the following when defining the Put Column Value function.

     

    Topic

    Usage Notes

    Status

    If the function status is PXSTC_Success, the value is stored in the internal buffer associated with the specified column. See also the Get Column Value function.

    Put Row

    Purpose  

    Put Row is the service function that stores a data row.

    Structure

    #include <pxoper.h>
    PXSTC_Code PX_PutRow(PX_TableSchemaHandle tableSchemaHandle,
       PX_Count columnCount,
       PX_Indicator * nullIndicator,
       PX_ByteOffset * offsets,
       PX_Length * lengths,
       PX_Addr rowAddr,
       PX_Length rowLength);

    where:

     

    Parameter

    Function

    Specification

    columnCount

    input

    Number of columns associated with the data row.

    lengths

    output

    Pointer to the array of integers representing the length of the corresponding column value.

    nullIndicator

    output

    Pointer to the array of indicator bytes specifying whether or not the corresponding column value is NULL.

    offsets

    output

    Pointer to the array of integers representing the corresponding column positions in terms of the number of bytes into the data row.

    rowAddr

    input

    Pointer to the address of the data row to be stored.

    rowLength

    input

    Pointer to the length of the data row.

    tableSchemaHandle

    input

    Table schema handle by which the data row is to be stored.

    Return Codes

    The following Put Row function status codes are defined by the Teradata PT operator interface:

     

    Status Code

    Signifies

    PXSTC_InvalidArgument

    One or more bad input arguments.

    PXSTC_BadHandle

    An undefined table schema handle.

    PXSTC_LengthError

    Length of data to be stored does not match length of internal buffer.

    PXSTC_Success

    Successful storage of the data row.

    Usage Notes  

    Consider the following when defining the Put Row function.

     

    Topic

    Usage Notes

    Indicator Mode Data

    If the data row is in indicator mode, then the columnCount parameter must be zero and the following parameters must all be NULL:

  • nullIndicators
  • offsets
  • lengths
  • Teradata Call-Level Interface Version2 for Mainframe-Attached Systems
  • Teradata Call-Level Interface Version2 for Network-Attached Systems
  • Status

    If the function status is PXSTC_Success, then the data row is stored in the internal buffer described by the table schema associated with the dataSchemaHandle parameter.

    See Also

  • Begin Table Schema Definition function
  • Finalize Table Schema Definition function
  • Get Row function
  • Read Checkpoint Record

    Purpose  

    Read Checkpoint Record is the service function that reads a checkpoint record.

    Structure

    #include <pxoper.h>
    PXSTC_Code PX_ReadCheckpoint(PX_OperatorHandle operator,
       PX_Addr * dataAddr,
       PX_Length * dataLength);

    where:

     

    Parameter

    Function

    Specification

    dataAddr

    output

    Pointer to the address of the checkpoint record.

    dataLength

    output

    Pointer to the length of the checkpoint record.

    operator

    input

    Operator handle from which the checkpoint record is to be read.

    Return Codes

    The following Read Checkpoint Record function status codes are defined by the Teradata PT operator interface:

     

    Status Code

    Signifies

    PXSTC_InvalidArgument

    One or more bad input arguments.

    PXSTC_BadHandle

    An undefined operator handle.

    PXSTC_Success

    Successful read of the checkpoint record.

    Usage Notes  

    Consider the following when defining the Read Checkpoint Record function.

     

    Topic

    Usage Notes

    Status

    If the function status is PXSTC_Success, then the checkpoint record is stored in the location pointed to by the dataAddr parameter. See also the Write Checkpoint Record function.

    Read Global Variable

    Purpose  

    Read Global Variable is the service function that retrieves the value of a global variable.

    Structure

    #include <pxoper.h>
    PXSTC_Code PX_ReadGlobalVar(PX_OperatorHandle operator,
       PX_Name varName,
       PX_Count itemIndex,
       PX_Addr * itemBufferAddr,
       PC_Length * itemBufferSize);

    where:

     

    Parameter

    Function

    Specification

    itemBufferAddr

    output

    Pointer to the address of the buffer where the value of the global variable is stored.

    itemBufferSize

    output

    Pointer to the size of the item buffer.

    itemIndex

    input

    Item of the global variable to be retrieved.

    The itemIndex parameter can range from 1 to the maximum limit specified when the global variable was created.

    operator

    input

    Operator handle by which the global variable is to be read.

    varName

    input

    Name of the global variable.

    Return Codes

    The following Read Global Variable function status codes are defined by the Teradata PT operator interface:

     

    Status Code

    Signifies

    PXSTC_InvalidArgument

    One or more bad input arguments.

    PXSTC_BadHandle

    An undefined object handle.

    PXSTC_Success

    A successful read access of the global variable.

    Usage Notes  

    Consider the following when defining the Read Global Variable function.

     

    Topic

    Usage Notes

    Status

    If the function status is PXSTC_Success, then:

  • The value of the global variable is stored in the location pointed to by the itemBufferAddr parameter
  • The length of the global variable value is indicated by the itemBufferSize pointer
  • See Also

  • Update Global Variable function
  • Create Global Variable function
  • Restart

    Purpose  

    Restart is a user-provided function that performs any functionality when an operator is restarted by the infrastructure.

    Structure

    #include <pxoper.h>
    PXSTC_Code PX_Restart(PX_OperatorHandle operator, PX_LongInt phase);

    where:

     

    Parameter

    Function

    Specification

    operator

    input

    Name of the operator handle to be restarted.

    phase

    input

    Current processing phase number

    Return Codes

    The following Restart function status codes are defined by the Teradata PT operator interface:

     

    Status Code

    Signifies

    PXSTC_EndMethod

    Successful restart of the operator.

    PXSTC_NextPhase

    Proceed with the next processing phase.

    PXSTC_SamePhase

    Continue with the current processing phase.

    Define additional Restart function status codes as required to support your operator.

    Usage Notes  

    Consider the following when defining the Restart function.

     

    Topic

    Usage Notes

    Status

    If the function status is PXSTC_EndMethod, the restart operation was successfully established by this function. See also the Checkpoint function.

    Set Error Message

    Purpose  

    Set Error Message is the service function that assigns an error message to the operator.

    Structure

    #include <pxoper.h>
    PXSTC_Code PX_SetErrorMessage(PX_OperatorHandle operator,
       PX_ErrorText message,
       PX_Length messageLength);

    where:

     

    Parameter

    Function

    Specification

    message

    input

    Location of the error message text.

    messageLength

    input

    Length of the error message text.

    operator

    input

    Operator handle to which the error message is assigned.

    Return Codes

    The following Set Error Message function status codes are defined by the Teradata PT operator interface:

     

    Status Code

    Signifies

    PXSTC_InvalidArgument

    One or more bad input arguments.

    PXSTC_BadHandle

    An undefined object handle.

    PXSTC_Success

    Successful setting of the error message.

    Usage Notes  

    Consider the following when defining the Set Error Message function.

     

    Topic

    Usage Notes

    Status

    If the function status is PXSTC_Success, then:

  • The error message stored at the location specified by the message parameter will be saved by the operator
  • The length of the message is indicated by the messageLength parameter
  • Terminate

    Purpose  

    Terminate is the user-provided function that ends the operating environment of the operator.

    Structure

    #include <pxoper.h>
    PXSTC_Code PX_Terminate(PX_OperatorHandle operator, PX_LongInt phase);

    where:

     

    Parameter

    Function

    Specification

    operator

    input

    Operator handle associated with the Terminate function.

    The operator parameter is a handle that identifies the operator that the Terminate function is bound to. You can use this handle to terminate any of the Teradata PT service functions described in this chapter.

    phase

    input

    Current processing phase number

    Return Codes

    The following Terminate function status codes are defined by the Teradata PT operator interface:

     

    Status Code

    Signifies

    PXSTC_EndMethod

    Successful termination of the operator.

    PXSTC_NextPhase

    Proceed with the next processing phase.

    PXSTC_SamePhase

    Continue with the current processing phase.

    Define additional Terminate function status codes as required to support your operator.

    Usage Notes  

    Consider the following when defining the Terminate function.

     

    Topic

    Usage Notes

    Status

    If the function status is PXSTC_EndMethod, the processing environment was successfully terminated by this function. See also Initiate function.

    Terminate Log Stream

    Purpose  

    Terminate Log Stream is the service function that ends the log stream. Each initiated log stream (PX_LogInit) must be terminated with a call of PX_LogTerminate with its own specific log handle.

    Structure

    #include <pxoper.h>
    PXSTC_Code PX_LogTerminate(PX_LogHandle loghandle);

    where:

     

    Parameter

    Function

    Specification

    loghandle

    input

    Handle to the log stream, freed by the Logger API.

    Return Codes

    The following Terminate Log Stream function status codes are defined by the Teradata PT operator interface:

     

    Status Code

    Signifies

    PXSTC_Success

    The call succeeded.

    PXSTC_LogCommunicationError

    An error occurred from socket communication with the node Logger.

    PXSTC_UnknownError

    Unknown termination error.

    Usage Notes  

    Consider the following when defining the Terminate Log Stream function.

     

    Topic

    Usage Notes

    Status

    If the function status if PXSTC_Success, the message catalog for the operator was successfully terminated by this function. See also Initiate Log Stream.

    Example  

    #include <pxoper.h>
    PX_ErrorProc myerror;
    PX_LogHandle loghandle;
    PX_LogInit(oprhandle, "mycomponent", 75, NULL, myerror, &loghandle); 
    PX_LogTerminate(loghandle);

    Update Global Variable

    Purpose  

    Update Global Variable is the service function that assigns a value to a global variable.

    Structure

    #include <pxoper.h>
    PXSTC_Code PX_UpdateGlobalVar(PX_OperatorHandle operator,
       PX_Name varName,
       PX_Addr itemBufferAddr,
       PX_Length itemBufferSize);
       PX_Count itemIndex,

    where:

     

    Parameter

    Function

    Specification

    itemBufferAddr

    input

    Address of the buffer where the value to be assigned to the global variable is stored.

    itemBufferSize

    input

    Size of the value in the item buffer.

    itemIndex

    input

    Item of the global variable to be updated.

    The itemIndex parameter can range from 1 to the maximum limit specified when the global variable was created.

    operator

    input

    Operator handle by which the global variable is to be updated.

    varName

    input

    Name of the global variable.

    Return Codes

    The following Update Global Variable function status codes are defined by the Teradata PT operator interface:

     

    Status Code

    Signifies

    PXSTC_InvalidArgument

    One or more bad input arguments.

    PXSTC_BadHandle

    An undefined operator handle.

    PXSTC_LengthError

    The length of the update value does not match the length of the global variable buffer.

    PXSTC_NotEnough

    The global variable is too large.

    PXSTC_Success

    A successful update access of the global variable.

    Usage Notes  

    Consider the following when defining the Update Global Variable function.

     

    Topic

    Usage Notes

    Status

    If the function status is PXSTC_Success, the value stored at the itemBufferAddr location is assigned to the specified itemIndex of the varName global variable.

    See Also

  • Read Global Variable function
  • Create Global Variable function
  • Write Checkpoint Record

    Purpose  

    Write Checkpoint Record is the service function that writes a checkpoint record to the restart log file.

    Structure

    #include <pxoper.h>
    PXSTC_Code PX_WriteCheckpoint(PX_OperatorHandle operator,
       PX_Addr dataAddr,
       PX_Length dataLength);

    where:

     

    Parameter

    Function

    Specification

    dataAddr

    input

    Address of the checkpoint record to be written.

    dataLength

    input

    Length of the checkpoint record.

    operator

    input

    Operator handle from which the checkpoint record is to be read.

    Return Codes

    The following Write Checkpoint Record function status codes are defined by the Teradata PT operator interface:

     

    Status Code

    Signifies

    PXSTC_InvalidArgument

    One or more bad input arguments.

    PXSTC_BadHandle

    An undefined operator handle.

    PXSTC_Success

    Successful write of the checkpoint record.

    Usage Notes  

    Consider the following when defining the Write Checkpoint Record function.

     

    Topic

    Usage Notes

    Status

    If the function status is PXSTC_Success, then the checkpoint record is written to the restart log table. See also the Read Checkpoint Record function.

    Write to Log Stream

    Purpose  

    Write to Log Stream is the service function that is used for submitting log messages.

    Structure

    #include <pxoper.h>
    PXSTC_Code PX_LogWrite(PX_LogHandle loghandle,
    PXInt32 messagenumber,
    PXInt32 destination,
    PXInt32 messagecategory,
    ...);

    where:

     

    Parameter

    Function

    Specification

    destination

    input

    Destination bit mask describing which destinations the message should go to. Any combination of LOG_DEST_CONS and LOG_DEST_LOG is valid. Multiple destinations are entered by or’ing the values (LOG_DEST_CONS | LOG_DEST_LOG)

    loghandle

    input

    Handle to the log stream (returned from PX_LogInit())

    messagecategory

    input

    Category of the message. The valid message categories are:

  • LOG_DEBUG
  • LOG_TRACE
  • LOG_INFO
  • LOG_WARNING
  • LOG_FATALERROR
  • LOG_USERERROR
  • messagenumber

    input

    Number of the message in the message catalog.

    The message catalog is identified in the DEFINE OPERATOR statement in the Teradata PT script.

    The message described by the message number, is used as a format string when accessed from the Log View Client.

    ...

    input

    Arguments to the message (1..*).

    This variable list of parameters is the arguments that will go into the format string from the message catalog. Each argument is supplied with type and value. This is handled by a set of macros in the following way:

  • LOG_INT16(val) - Short integer values. For example, LOG_INT16(5) corresponds to supplying the short value 5.
  • LOG_INT32(val) - Long integer values. E.g. LOG_INT32(56) corresponds to supplying the long value 56.
  • LOG_INT64(val) - Long long values. E.g. LOG_INT64(578) corresponds to supplying the long value 578.
  • LOG_CHAR(val) - Character values. E.g. LOG_CHAR('g') corresponds to supplying the character 'g'.
  • LOG_STRING(val) - String values. E.g. LOG_STRING("mystring") corresponds to supplying the string "mystring".
  • LOG_FLOAT(val) - 32 bit floating point values. E.g. LOG_FLOAT(5.4) corresponds to supplying the floating point value 5.4.
  • LOG_DOUBLE(val) - 64 bit floating point values. E.g. LOG_DOUBLE(5.7) corresponds to supplying the double precision floating point value 5.7.
  • This list must always end with PXEOP (EndOfParameterList) as the last parameter. Failure to do so will make the program loop and eventually incur a memory fault.

    Return Codes

    The following Write to Log Stream function status codes are defined by the Teradata PT operator interface:

     

    Status Code

    Signifies

    PXSTC_Success

    The call succeeded.

    PXSTC_Log
    CommunicationError

    An error occurred from socket communication with the Node Logger.

    PXSTC_LogInsuffMem
    Error

    A memory allocation failure.

    PXSTC_InvalidDataType

    The type of some of the parameters is unknown to the Logger API.

    PXSTC_NoMessage
    Catalog

    The requested message catalog is not present.

    PXSTC_UnknownError

    Unknown error encountered when writing a log record.

    Usage Notes  

    Consider the following when defining the Write to Log Stream function.

     

    Topic

    Usage Notes

    Status

    If the function status if PXSTC_Success, the message was successfully written to the message catalog by this function. See also Initiate Log Stream.

    Example  

    #include <pxoper.h>
    PX_ErrorProc myerror;
    PX_LogHandle loghandle;
    PX_LogInit(oprhandle, "mycomponent", 75, NULL, myerror, &loghandle); 
    .
    PX_LogWrite(loghandle, mymessagenumber, 
      LOG_DEST_CONS | LOG_DEST_LOG,
      LOG_FATALERROR, ...);
    .
    PX_LogTerminate(loghandle);