17.00 - GetEvent Queries - Parallel Transporter

Teradata® Parallel Transporter Application Programming Interface Programmer Guide

prodname
Parallel Transporter
vrm_release
17.00
created_date
June 2020
category
Programming Reference
featnum
B035-2516-220K

All events must be queried after the driver is initiated and before it is terminated. Events queried before their data is available return TD_Unavailable. The following table lists events used with the Connection object’s GetEvent function to retrieve run time statistics from the Update driver.

Event Returned Value
TD_Evt_AcquisitionPhaseStats One 4-byte unsigned integer for the acquisition phase elapsed time and three 8-byte double for the acquisition phase CPU time, for megabytes per second, and for megabytes per CPU second.

Query this event after the start of data loading.

The elapsed time is at the job level. The elapsed time may be slightly different between the instances. The main instance will have the most accurate elapsed time.

The CPU time, megabytes per second, and megabytes per CPU second are at the instance level.

TD_Evt_ApplicationPhaseStat One 4-byte unsigned integer for the application phase elapsed time.

Query this event after ApplyRows.

The elapsed time is at the job level. The elapsed time may be slightly different between the instances. The main instance will have the most accurate elapsed time.

TD_Evt_ApplyCount64 Three 8-byte unsigned integers: one 8-byte unsigned integer for the number of rows inserted into the database, followed by one 8-byte unsigned integer for the number of rows updated, followed by one 8-byte unsigned integer for the number of rows deleted.

Query this event after ApplyRows. For a multi-instance job, only query these numbers in the master instance. The master instance returns the total number of rows inserted, updated, and deleted to the target table from all instances.

TD_Evt_CLIError One 4-byte integer for the CLIv2 error number and a 255-byte character buffer for the CLIv2 error text. Query this event at any time.
TD_Evt_BufferLayout Four 4-byte unsigned integers corresponding to the maximum buffer size, the row header size, the row length size, and the buffer trailer size. Use this information to format the buffer required for block updating.
These layout values will change depending on the user environment and may be defined differently in future releases. Always obtain these values from the event method before buffering data.

Query this event at any time.

TD_Evt_DBSError One 4-byte integer for the database error number and a 255 byte character buffer containing the error text. This event can be queried at any time.
TD_Evt_ConnectStatus Three 4-byte integers corresponding to the number of sessions requested, the number of sessions connected, and any CLIv2 error number that occurred during the connect process. Query this event at any time.
TD_Evt_CPUTime One 8-byte double for the CPU time of the instance in seconds. Query this event at any time.
TD_Evt_RowCounts Three 4-byte unsigned integers corresponding to the number of rows received, sent, and applied. Query this event before EndAcquisition to get the current number of rows received. However, the rest of the data for this event is available only after ApplyRows.

The rows-applied count returned by this event does not take into consideration rows that are rejected by the database during the application phase. Query the TD_Evt_ApplyCount event to get the final count of rows that have been applied to the target tables.

TD_Evt_RowCounts64 Three 8-byte unsigned integers corresponding to the number of rows received, sent, and applied. Query this event anytime before EndAcquisition to get the current number of rows received. The rest of the data for this event is available after ApplyRows.

If rows are being loaded using PutRow, the data for this event will not be available until enough rows have been loaded to fill one internal buffer or until the Checkpoint function has been called.

The rows-applied count returned by this event does not take into consideration rows that are rejected by the database during the application phase. Query the TD_Evt_ApplyCount event to get the final count of rows that have been applied to the target table.

TD_Evt_ApplyCount Three 4-byte unsigned integers corresponding to the number of rows inserted, updated, and deleted. This event must be called with a table index greater than or equal to one to signify which target table the desired data is for. Query this event after ApplyRows.

For a multi-instance job, only query this number in the master instance.

The master instance returns the total number of rows applied to the target table from all instances.

TD_Evt_ErrorTable1 One 4-byte unsigned integer for the number of rows in error table 1. This event must be called with a table index greater than or equal to one to signify the desired data’s target table. Query this event after ApplyRows.
TD_Evt_ErrorTable2 One 4-byte unsigned integer for the number of rows in error table 2. This event must be called with a table index greater than or equal to one to signify the desired data’s target table. Query this event after ApplyRows.
TD_Evt_ExitCode One 2-byte integer for the exit code of the driver. Query this event right before the driver terminates.
TD_Evt_OperVersion A pointer to a character string containing the driver version. Query this event only after the driver has been initiated.
TD_Evt_QueryBandByteCount The main instance returns a 4-byte unsigned value for the number of internal Query Band data bytes sent to the database. The slave instances return "event not available", because the slave instances do not log on a control SQL session. Only the main instance log on a control SQL session.
TD_Evt_RowsCheckpointed One 4-byte unsigned integer corresponding to the total number of rows that have been received and checkpointed for the entire job. Query this event any time after initiating a Teradata PT database connection in a single-instance job. This event will return TD_Unavailable when queried in a job containing multiple instances; this event is invalid if multiple instances are used.

Note that the event data returned by this event can be used as a replacement for the checkpoint data that must be passed into the Restart method during a restart job. It is recommended to always save the checkpoint data from the last successful call to the CheckPoint method in a potential restart job. However, if the checkpoint data is not saved then the event data returned by this event can be passed into the Restart method instead. This alternate method of performing checkpoint/restarts will only work with single-instance jobs.

TD_Evt_RowsCheckpointed64 One 8-byte unsigned integer corresponding to the total number of rows that have been received and checkpointed for the entire job. Query this event anytime after initiating a Teradata PT API database connection in a single-instance job. This event will return TD_Unavailable when queried in a job containing multiple instances; this event is invalid if multiple instances are used.

Note that the event data returned by this event can be used as a replacement for the checkpoint data that must be passed into the Restart method during a restart job. Teradata recommends to always save the checkpoint data from the last successful call to the CheckPoint method in a potential restart job. However, if the checkpoint data is not saved, then the event data returned by this event can be passed into the Restart method instead. This alternate method of performing checkpoint/restarts will only work with single-instance jobs.

TD_Evt_RowsDiscarded One 8-byte unsigned integer for the number of rows discarded by the operator. Query this event after Acquisition phase.
TD_Evt_SessionNodeID A pointer to a character string containing the information about the SessionNodeID for all the job sessions.
Data in the SessionNodeID for every session contains the following information:
  • First 4 bytes will contain the database session number.
  • Next 2 bytes will contain Session type.
  • Next 2 bytes will contain the unformatted node ID.
  • Next 4 bytes will contain length(n) of the formatted node-ID.
  • Next 'n' bytes will contain formatted node ID.

This event can be queried only after the operator has been initiated and before the operator has been terminated.

TD_Evt_SessionThrougput A pointer to a character string containing the information about the SessionThroughput for all the job sessions.
Data in the SessionThroughput for every Session contains the following information:
  • First 4 bytes will contain the database session number,.
  • Next 2 bytes will contain Session type.
  • Next 8 bytes will contain CLI average actual send throughput.
  • Next 8 bytes will contain CLI average actual receive throughput.
  • Next 8 bytes will contain CLI average overall send throughput.
  • Next 8 bytes will contain CLI average overall receive throughput.

This event can be queried only after the operator has been initiated and before the operator has been terminated.

TD_Evt_Version A pointer to a character string containing the Teradata PT version followed by a pointer to a character string containing the operator version. Query this event at any time. The operator version is available only after the driver has been initiated.