Multiple rows can be exported together in a buffer using the Connection object’s GetBuffer function. Exporting an entire buffer full of rows using the GetBuffer function rather than one row at a time using the GetRow function improves performance by reducing the amount of data movement required. The GetBuffer function accepts as its arguments a pointer to an unallocated character buffer and a pointer to a TD_Length variable. The GetBuffer function uses these two arguments to return a pointer to a data buffer and to return the total length of that data buffer.
conn->GetBuffer(&buffer,&length);
The GetBuffer function returns the TD_Success value when a buffer of data is successfully retrieved. The buffer of data returned by the GetBuffer function must be immediately either copied or processed. The buffer used to return the data is overwritten on the next GetBuffer function call, and the buffer is destroyed when the Connection object is deleted. The GetBuffer function returns the TD_END_Method value (defined in Teradata PT Status Messages when all rows have been retrieved and the data acquisition process is complete.
In order to use the GetBuffer feature, set the TD_BUFFER_MODE attribute to Yes (or Y) before initiating the Connection object. The GetRow function cannot be called if the GetBuffer feature is enabled.
Specify the size and format of the data buffer returned by the GetBuffer function by setting one or more of the following buffer layout attributes:
- TD_BUFFER_MAX_SIZE
- TD_BUFFER_HEADER_SIZE
- TD_BUFFER_LENGTH_SIZE
- TD_BUFFER_TRAILER_SIZE
These attributes correspond to the total maximum size of the data buffer, the row header size allocated for each row in the data buffer, the row length size used for each row in the data buffer, and the trailer size allocated for the data buffer. See Load Rows into a Teradata Database using PutBuffer for a description of the format of the data buffer, and Required Attributes for a detailed description of each of the four buffer layout attributes and their default values.
The layout of the data buffer returned by GetBuffer can alternatively be set by using the Export driver’s TD_Evt_BufferLayout modifier along with the PutEvent function. The Export driver’s TD_Evt_BufferLayout modifier can be used to set the data buffer layout any time after the Export driver has been initialized up until the first call to the Export driver’s GetBuffer function. The modifier returns TD_Unavailable if called after the first call to the GetBuffer function. For more information on how to use the Export driver’s TD_Evt_BufferLayout modifier, see PutEvent Modifiers.