17.00 - Load Rows into the Database using PutBuffer - 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

The Teradata PT PutBuffer function is available for the Load, Update and Stream drivers. Using PutBuffer for the Update and Stream drivers will only provide performance improvement if the function call overhead to PutRow is costly. If that is not the case, continue to use PutRow for the Update and Stream drivers.

There are five steps to using this method:

  1. Set the buffer mode attribute.
  2. Query the buffer layout.
  3. Load the buffers.
  4. Inform Teradata PT that acquisition is complete.
  5. Apply rows to the database (except when using the Stream driver).

Before Initiate is called, set the buffer mode attribute to Yes in the Connection object as follows:

conn->AddAttribute(TD_BUFFER_MODE,"Yes");

To buffer the data for block loading, query the Connection object using the event method to obtain the layout for the data buffer. The event method should be queried using the TD_Evt_BufferLayout parameter as follows:

returnValue = conn->GetEvent(TD_Evt_BufferLayout, &dataptr, &datalen);

The layout returned by the event method for the buffer event contains four 4-byte unsigned integers corresponding to the maximum buffer size, the row header size, the row length size, and the buffer trailer size.

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.

The following figure is a diagram representing the layout of the Load driver data buffer.

Data Buffer Format

When constructing the data buffer, the user is responsible for filling in the row length for each row and the row data. The row length size can be obtained by the buffer layout event. The beginning of the row header and the buffer trailer should be left blank as they will be filled in by Teradata PT. The total size of the buffer cannot exceed the maximum buffer size returned by the buffer layout event.

Buffers of data are loaded using the Connection object’s PutBuffer method. The PutBuffer method accepts as its arguments a pointer to a buffer of data, the length of the data buffer, and an indicator informing Teradata PT whether the data in the buffer is in indicator mode (a value of one) or in non-indicator mode (a value of zero). Data for the Update and Stream drivers must be in indicator mode (a value of one).

while (!endOfData) {

   /* Assemble a buffer of rows in null-indicator format */
   ...

   /* Pass a buffer to the Teradata Database */
   conn->PutBuffer(buffer, length, 1);
}

Once all data has been loaded, the acquisition method is completed by calling the Connection object’s EndAcquisition method. This must be done before the data can be applied.

conn->EndAcquisition( );

When the acquisition method has been completed, the data is applied in the database by using the Connection object’s ApplyRows method. This is not needed when using the Stream driver.

conn->ApplyRows( );
When using the Load, Stream, or Update drivers, the PutBuffer and PutRow features can not be used in the same job.