Connection Class - Parallel Transporter

Teradata® Parallel Transporter Application Programming Interface Programmer Guide - 20.00
Deployment
VantageCloud
VantageCore
Edition
Enterprise
IntelliFlex
Lake
VMware
Product
Parallel Transporter
Release Number
20.00
Published
October 2023
Language
English (United States)
Last Update
2023-11-20
dita:mapPath
haz1691132518981.ditamap
dita:ditavalPath
obe1474387269547.ditaval
dita:id
ana1478611373864
Product Category
Teradata Tools and Utilities

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

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.”
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.
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.
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 Teradata PT Status Messages.

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.
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.
GetBuffer

Retrieves a buffer full of rows from the 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 Teradata PT Status Messages.

 
#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.
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 database 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.
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 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.
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.
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 gets 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 main 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.
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:

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

mType = 1 (if array or multivalue)

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.
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 database.

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

For more information, see Teradata PT Status Messages.

 
#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.
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.
PutRow

Sends a row of data to the 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 Teradata PT Status Messages.

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.
PutTELINFO

Used by the worker to store the TELINFO area passed from the main 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.
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.
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.
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.