15.10 - Connection Class - Parallel Transporter

Teradata Parallel Transporter Application Programming Interface

prodname
Parallel Transporter
vrm_release
15.10
category
Programming Reference
featnum
B035-2516-035K

Connection Class

The Connection class manages all of the attributes required to connect to the Teradata Database. These attributes store attribute, schema and DML Group objects.

Note: On mainframe‑attached z/OS platforms, connection.h is located in TWB.H(CONNECTI). Notes have been made for the following syntax examples to use #include “connecti.h” instead of “connection.h.”

 

Table 2: Connection Class Objects 

Object Name and Function

Syntax and Notes

Return Codes

AddArrayAttribute

Adds a connection attribute with more than one value.

#include “connection.h”
Void
AddArrayAttribute(
TD_Attribute
attribute,
	TD_Count count, 
   	Char* value, ...,
NULL);
Void
AddArrayAttribute(
TD_Attribute
attribute,
	TD_Count count, 
   	TD_IntValue value, ...,
NULL );

where these parameters specify:

  • attribute Input for the type of attribute being added.
  • count Input for the number of values.
  • value Input for the values of attributes terminated by NULL.
  • On mainframe‑attached z/OS platforms, connection.h is located in TWB.H(CONNECTI). Use #include “connecti.h” instead of “connection.h.”

    None

    AddAttribute

    Adds a connection attribute.

    #include “connection.h”
    Void
    AddAttribute(
    TD_Attribute
    attribute,
    Char* value);
    Void
    AddAttribute(
    TD_Attribute
    attribute,
     	TD_IntValue value);

    where these parameters specify:

  • attribute Input for the type of attribute being added.
  • value Input for the value of the attribute.
  • On mainframe‑attached z/OS platforms, connection.h is located in TWB.H(CONNECTI). Use #include “connecti.h” instead of “connection.h.”

    None

    AddDMLGroup

    Adds a DMLGroup object to the connection.

    #include “connection.h”
    TD_StatusCode
    AddDMLGroup(
    DMLgroup* dmlgroup,
    	TD_Index* index);

    where these parameters specify:

  • dmlgroup Input pointer to the DmlGroup object.
  • index Output for the index number of the DMLGroup.
  • On mainframe‑attached z/OS platforms, connection.h is located in TWB.H(CONNECTI). Use #include “connecti.h” instead of “connection.h.”

    TD_Error, TD_Success

    For more information, see “Teradata PT Status Messages” on page 71.

    AddSchema

    Adds a schema object to the connection.

    A schema is the definition of the columns in a table or data source. An input schema defines the fields in a record of input data.

    #include “connection.h”
    void
    AddSchema(
    Schema* schema);

    where the schema parameter is input for the pointer to the schema object.

    On mainframe‑attached z/OS platforms, connection.h is located in TWB.H(CONNECTI). Use #include “connecti.h” instead of “connection.h.”

    None

    AddSchema

    Adds schema to the connection object retrieved via GetSchema (char **schema_buff, TD_Count *numCols, TD_Length *length)

    Returns a schema object in a schema pointer.

    #include “connection.h”
    AddSchema(Schema **schema, char *colInfo, TD_Length numCols);

    where:

  • colInfo contains the schema buffer.
  • schema contains the new schema.
  • numCols contains the number of columns.
  •  

    This method is capable of adding the schema to the connection object before the initiate phase is complete.

    The method is only used for the dynamic schema feature with multiple instances.

    None

    AddValue (char*)

    Adds character value to the attribute.

    #include "connection.h"
    void AddValue(char* value);

    * On mainframe-attached z/OS platforms, connection.h is located in TWB.H(CONNECT). Use #include "connecti.h" instead of "connection.h"

    None

    AddValue (int)

    Adds integer value to the attribute.

    #include "connection.h"
    void AddValue(int value);

    * On mainframe-attached z/OS platforms connection.h is located in TWB.H(CONNECT). Use #include "connecti.h" instead of "connection.h"

    None

    ApplyRows

    Applies the data loaded in the acquisition phase. (Load and Update only).

    #include “connection.h”
    TD_StatusCode
    ApplyRows( );

    On mainframe‑attached z/OS platforms, connection.h is located in TWB.H(CONNECTI). Use #include “connecti.h” instead of “connection.h.”

    TD_Error,
    TD_END_Method
    TD_SYNC_Barrier,
    TD_SYNC_TELINFO

    For more information, see “Teradata PT Status Messages” on page 71.

    Checkpoint

    Tells the driver to perform a checkpoint.

    #include “connection.h”
    TD_StatusCode		 
    Checkpoint(
    char **data,
    TD_Length* length );

    where these parameters specify:

  • Data Output buffer for the checkpoint data.
  • Length Output for the length of the checkpoint buffer.
  • The checkpoint method currently returns NULL with a data length of zero. These Checkpoint parameters are reserved for future expansion.

    For more information, see “Add Checkpoint and Restart” on page 33.

    On mainframe‑attached z/OS platforms, connection.h is located in TWB.H(CONNECTI). Use #include “connecti.h” instead of “connection.h.”

    TD_Call_EndAcq,
    TD_END_Method, TD_Error,
    TD_SYNC_Barrier, TD_SYNC_TELINFO

    For more information, see “Teradata PT Status Messages” on page 71.

    Class Constructor

    Returns the Connection class instance.

    #include “connection.h”
    using namespace teradata::client::API;
    Connection* Connection( );

    On mainframe‑attached z/OS platforms, connection.h is located in TWB.H(CONNECTI). Use #include “connecti.h” instead of “connection.h.”

    None

    Class Constructor

    Specifies encoding for the Connection class and returns the Connection class instance.

    #include “connection.h”
    using namespace teradata::client::API;
    Connection* Connection(TD_Encoding);

    Valid values are TD_UTF8_ENCODING (the default) and TD_UTF16_ENCODING.

    This Class Constructor is not supported on mainframe‑attached z/OS platforms.

    None

    EndAcquisition

    Informs the driver that the data acquisition phase is completed.

    This function must be called before the data can be applied.

    #include “connection.h”
    TD_StatusCode
    EndAcquisition( );

    On mainframe‑attached z/OS platforms, connection.h is located in TWB.H(CONNECTI). Use #include “connecti.h” instead of “connection.h.”

    TD_END_Method, TD_Error, TD_SYNC_Barrier, TD_SYNC_TELINFO

    For more information, see “Teradata PT Status Messages” on page 71.

    GetBuffer

    Retrieves a buffer full of rows from the Teradata Database.

    Exporting by the buffer provides a performance improvement over exporting one row at a time.

    Data is in null indicator mode. For more information, see “Load Data into or Export Data from the Teradata Database” on page 27.

    #include “connection.h”
    TD_StatusCode
    GetBuffer(
    char** data,TD_Length* length);

    where these parameters specify:

  • Data Output for the buffer of data.
  • Length Output parameter that contains the length (in bytes) of the data buffer.
  • On mainframe‑attached z/OS platforms, connection.h is located in TWB.H(CONNECTI). Use #include “connecti.h” instead of “connection.h.”

    TD_END_Method, TD_Error, TD_SYNC_Barrier, TD_SYNC_TELINFO, TD_Success

    For more information, see “Teradata PT Status Messages” on page 71.

    GetCheckPointInterval

    Returns the checkpoint interval.

    #include "connection.h"
    int Connection::GetCheckPointInterval()

    * On mainframe-attached z/OS platforms, connection.h is located in TWB.H(CONNECT). Use #include "connecti.h" instead of "connection.h"

    Returns the integer holding the check point interval.

    GetCount

    Gets the count of the attributes.

    #include "connection.h"
    int GetCount();

    * On mainframe-attached z/OS platforms, connection.h is located in TWB.H(CONNECT). Use #include "connecti.h" instead of "connection.h"

    Returns an integer holding the count of attributes.

    GetEncoding

    Returns the character set encoding type

    #include "connection.h"
    TD_Encoding Connection::GetEncoding ()

    * On mainframe-attached z/OS platforms, connection.h is located in TWB.H(CONNECT). Use #include "connecti.h" instead of "connection.h"

    TD_UTF8_ENCODING

    TD_UTF16_
    ENCODING

    TD_EBCDIC_
    ENCODING

    GetErrorInfo

    Retrieves detailed information about the last error received.

    #include “connection.h”
    Void
    GetErrorInfo(
    Char* errorMsg,
    	TD_ErrorType* errorType);

    where these parameters specify:

  • errorMsg Output error string message associated with the last received error. Set to NULL if no error has occurred.
  • errorType Output error type associated with the last received error (A value of zero for Teradata PT errors, a value of one for DBS errors, a value of two for CLIv2 errors and a value of minus one when no errors have occurred.)
  • On mainframe‑attached z/OS platforms, connection.h is located in TWB.H(CONNECTI). Use #include “connecti.h” instead of “connection.h.”

    None

    GetEvent

    Retrieves runtime statistics from the driver.

    #include “connection.h”
    TD_StatusCode
    GetEvent(
    TD_EventType eventType,
    	char** eventData,
    	TD_Length* eventDataLen,
    	TD_Index eventIndex = 0);

    where these parameters specify:

  • eventType Input for the name of the event to retrieve statistics for.
  • eventData Output pointer to the appropriate expected return data for the event.
  • eventDataLen Output parameter that contains the length (in bytes) of the data for the event.
  • eventIndex Input Target table index for the desired event data. This optional parameter only applies to a few events with the default value being 0.
  • On mainframe‑attached z/OS platforms, connection.h is located in TWB.H(CONNECTI). Use #include “connecti.h” instead of “connection.h.”

    TD_END_Method, TD_Error, TD_SYNC_Barrier, TD_SYNC_TELINFO, TD_Unavailable

    For more information, see “Teradata PT Status Messages” on page 71.

    GetName

    Gets the name of the attribute.

    #include ""connection.h"
    char* GetName();

    * On mainframe-attached z/OS platforms, connection.h is located in TWB.H(CONNECT). Use #include "connecti.h" instead of "connection.h"

    Returns the character pointer holding the attribute name.

    GetRow

    Retrieves a row of data from the Teradata Database.

    Data is in null indicator mode.

    #include “connection.h”
    TD_StatusCode		
    GetRow(
    Byte** data,
    TD_Length* length);

    where these parameters specify:

  • Data Output for the buffer of data.
  • Length Output for the length of the data buffer.
  • On mainframe‑attached z/OS platforms, connection.h is located in TWB.H(CONNECTI). Use #include “connecti.h” instead of “connection.h.”

    TD_END_Method, TD_Error, TD_Success, TD_SYNC_Barrier, TD_SYNC_TELINFO

    For more information, see “Teradata PT Status Messages” on page 71.

    GetSchema

    Retrieves the schema.

    #include “connection.h”
    TD_StatusCode
    GetSchema(Schema** schema);

    where schema is the output schema pointer.

    On mainframe‑attached z/OS platforms, connection.h is located in TWB.H(CONNECTI). Use #include “connecti.h” instead of “connection.h.”

    TD_Error, TD_Success

    TD_Unavailable

    For more information, see “Teradata PT Status Messages” on page 71.

    GetSchema

    Retrieves schema in a buffer in encrypted form

    #include “connection.h”
    TD_StatusCode
        GetSchema (char **schema_buff, TD_Count *numCols, TD_Length *length)’

    where:

  • Schema is put in schema_buff.
  • numCols getd the number of columns.
  • length has the length of the schema buffer.
  • These values are only meaningful to AddSchema (Schema **schema, char *colInfo, TD_Length numCols); method.

    This method is only used for the dynamic schema feature with multiple instances.

    TD_Success

    TD_Unavailable

    TD_Error

    GetTELINFO

    Retrieves the TELINFO area from the master instance in a multi‑instance environment.

    #include “connection.h”
    TD_StatusCode
    GetTELINFO(
    Char** TELINFO,
    TD_Length* length);

    where these parameters specify:

  • TELINFO Output pointer to the buffer containing the TELINFO area.
  • Length Output for the length of the TELINFO area.
  • On mainframe‑attached z/OS platforms, connection.h is located in TWB.H(CONNECTI). Use #include “connecti.h” instead of “connection.h.”

    TD_Error, TD_Success

    For more information, see “Teradata PT Status Messages” on page 71.

    GetTPTAPIVersion

    Copies the TPTAPI version to the user-provided version variable.

    #include "connection.h"
       void GetTPTAPIVersion (char *version);

    where this parameter specifies:

  • version Character pointer with pre-allocated memory.
  • You must allocate sufficient memory for version. A minimum of 50 bytes is ideal.

    A null-terminated TPTAPI version string is copied to version.

    None

    GetType

    Gets the attribute type.

    #include "connection.h"
    int GetType();

    * On mainframe-attached z/OS platforms, connection.h is located in TWB.H(CONNECT).Use #include "connecti.h" instead of "connection.h"

    Returns the integer holding the attribute type:

    1 mType = 0 (if non-array or non-multivalue)

    2 mType = 1 (if array or multivalue)

    3 mType = 2 (if integer)

    GetUpperValue

    Change the attribute from lower case to upper case.

    #include "connection.h"
    char* GetUpperValue(int index = 0);

    * On mainframe-attached z/OS platforms, connection.h is located in TWB.H(CONNECT). Use #include "connecti.h" instead of "connection.h"

    Returns the character pointer holding the attribute in upper case.

    GetValue

    Gets the specific attribute.

    #include "connection.h"
    char* GetValue(int index = 0);

    * On mainframe-attached z/OS platforms,
    connection.h is located in TWB.H(CONNECT). Use #include "connecti.h" instead of "connection.h"

    Returns the character pointer holding the specific attribute.

    Initiate

    Processes the Connection class attributes, schemas, and DML groups; initializes the driver and SQL.

    Teradata FastLoad, Teradata FastExport, and Teradata MultiLoad sessions are connected by the driver.

    #include “connection.h”
    TD_StatusCode
    Initiate( );

    On mainframe‑attached z/OS platforms, connection.h is located in TWB.H(CONNECTI). Use #include “connecti.h” instead of “connection.h.”

    TD_END_Method, TD_Error, TD_SYNC_Barrier, TD_SYNC_TELINFO

    For more information, see “Teradata PT Status Messages” on page 71.

    MakeArray

    Consolidates attribute values into array values and sets the array attribute properties.

    #include "connection.h"
    void MakeArray(char spaceValues);

    * On mainframe-attached z/OS platforms, connection.h is located in TWB.H(CONNECT). Use #include "connecti.h" instead of "connection.h"

    None

    PutBuffer

    Sends a buffer of data to the Teradata Database.

    Eliminates the extra data movement to the CLIv2 Data or IndicData.

    For more information, see “Load Data into or Export Data from the Teradata Database” on page 27.

    #include “connection.h”
    TD_StatusCode
    PutBuffer(
    Char* data,
    TD_Length length,
    	TD_Boolean indicator);

    where these parameters specify:

  • Data Input for the buffer of data.
  • Length Input for the length of the data buffer.
  • Indicator Input parameter that equals one if the data is in indicator mode or equals zero if in non-indicator mode. Must be set to one when used with the Update and Stream drivers.
  • On mainframe‑attached z/OS platforms, connection.h is located in TWB.H(CONNECTI). Use #include “connecti.h” instead of “connection.h.”

    TD_Call_EndAcq,
    TD_Error, TD_Success

    For more information, see “Teradata PT Status Messages” on page 71.

    PutEvent

    Modifies the driver at runtime.

    #include “connection.h”
    TD_StatusCode
    PutEvent(
    TD_EventType modifierType,
    char * modifierData,
    TD_Length modifierDataLen,
    TD_Index modifierIndex = 0);

    where these parameters specify:

  • modifierType Input used for the modifier name. Specifies which modifier receives information.
  • modifierData Input pointer for the appropriate expected modifier data
  • modifierDataLen Input parameter specifying the length (in bytes) for the modifier data.
  • modifierIndex Input Target table index for the desired event. This optional parameter is not currently used by any modifier.
  • On mainframe‑attached z/OS platforms, connection.h is located in TWB.H(CONNECTI). Use #include “connecti.h” instead of “connection.h.”

    TD_EndMethod,
    TD_Error, TD_SYNC_Barrier,
    TD_SYNC_TELINFO, TD_Unavailable

    For more information, see “Teradata PT Status Messages” on page 71.

    PutRow

    Sends a row of data to the Teradata Database.

    Data must be in null indicator mode format.

    #include “connection.h”
    TD_StatusCode
    PutRow(
    Char* data,
    TD_Length length );

    where these parameters specify:

  • Data Input for the buffer containing a row of data.
  • Length Input for the length of the data buffer. The length is the total length of all the column values (including the length bytes for variable-length values) plus the number of indicator bytes. For more information on how to determine the number of indicator bytes, see “Data Format” on page 32.
  • On mainframe‑attached z/OS platforms, connection.h is located in TWB.H(CONNECTI). Use #include “connecti.h” instead of “connection.h.”

    TD_Call_EndAcq,
    TD_Error, TD_Success

    For more information, see “Teradata PT Status Messages” on page 71.

    PutTELINFO

    Used by the slave to store the TELINFO area passed from the master in a multi-instance environment.

    #include “connection.h”
    TD_StatusCode
    PutTELINFO(
    Char* TELINFO,
    TD_Length length);

    where these parameters specify:

  • TELINFO Input to the buffer containing the TELINFO area.
  • Length Input for the length of the TELINFO buffer.
  • On mainframe‑attached z/OS platforms, connection.h is located in TWB.H(CONNECTI). Use #include “connecti.h” instead of “connection.h.”

    TD_Error, TD_Success

    For more information, see “Teradata PT Status Messages” on page 71.

    Restart

    Causes the driver to restart at the point of the last checkpoint.

    #include “connection.h”
    TD_StatusCode		
    Restart(
    char *data,
    TD_Length length );

    where these parameters specify:

  • Data Input buffer for the checkpoint data.
  • Length Input for the length of the checkpoint buffer.
  • On mainframe‑attached z/OS platforms, connection.h is located in TWB.H(CONNECTI). Use #include “connecti.h” instead of “connection.h.”

    TD_END_Method, TD_Error,
    TD_SYNC_Barrier, TD_SYNC_TELINFO

    For more information, see “Teradata PT Status Messages” on page 71.

    SetCount

    Sets the count of the attributes.

    #include "connection.h"
    void SetCount(int c);

    * On mainframe-attached z/OS platforms, connection.h is located in TWB.H(CONNECT). Use #include "connecti.h" instead of "connection.h"

    None

    SetValue

    Sets the character value to a specific attribute.

    #include "connection.h"
    void SetValue(char* value, int index = 0);

    * On mainframe-attached z/OS platforms, connection.h is located in TWB.H(CONNECT). Use #include ""connecti.h"" instead of ""connection.h

    None

    SetValue

    Sets the integer value to a specific attribute.

    #include "connection.h"
    void SetValue(int value, int index = 0);

    * On mainframe-attached z/OS platforms, connection.h is located in TWB.H(CONNECT). Use #include" connecti.h" instead of "connection.h"

    None

    SetType

    Sets the attribute type.

    #include "connection.h"
    void SetType(int t);

    * On mainframe-attached z/OS platforms, connection.h is located in TWB.H(CONNECT). Use #include "connecti.h" instead of "connection.h"

    None

    Terminate

    Closes the driver and disconnects all sessions.

    #include “connection.h”
    TD_StatusCode
    Terminate( );

    On mainframe‑attached z/OS platforms, connection.h is located in TWB.H(CONNECTI). Use #include “connecti.h” instead of “connection.h.”

    TD_END_Method, TD_Error, TD_SYNC_Barrier, TD_SYNC_TELINFO

    For more information, see “Teradata PT Status Messages” on page 71.

    UseDMLGroups

    Designates which DML group to use.

    #include “connection.h”
    TD_StatusCode		
    UseDMLGroups(
    TD_Index* index,
    	TD_Count count);

    where these parameters specify:

  • Index Input pointer to an array of indexes. Each index refers to a DML group added using the AddDMLGroup function.
  • Count Input for the number of indexes in the index array.
  • On mainframe‑attached z/OS platforms, connection.h is located in TWB.H(CONNECTI). Use #include “connecti.h” instead of “connection.h.”

    TD_Error, TD_Success

    For more information, see “Teradata PT Status Messages” on page 71.