16.20 - Response Buffer - Teradata Tools and Utilities

Teradata® Call-Level Interface Version 2 Reference for Mainframe-Attached Systems

prodname
Teradata Tools and Utilities
vrm_release
16.20
created_date
September 2019
category
Programming Reference
featnum
B035-2417-108K
Information received from Teradata Database is placed in a buffer called the response buffer. If Two-response-buffers is set to 'Y' in the DBCAREA, CLIv2 uses double buffering, and each buffer is the size specified in the DBCAREA. CLIv2 allocates the buffers when DBCHCL is called for any of the following functions:
  • Connect
  • RunStartUp
  • Initiate with Protocol-function
  • Command
  • Initiate Request function
If Save-response-buffer is set to... Then CLIv2...
N deallocates the buffers when DBCHCL is called for the End Request function.
Y

saves one response buffer when DBCHCL is called for the End Request function.

If the saved buffer is too small for the next request, the saved buffer is deleted and a new buffer of the required size is allocated.

Parcels received from Teradata Database are stored in the response buffers in the following ways.

If the value for Locate-mode is... Then DBCHC makes the response parcels available...
Y (Locate-mode) to the application in the response buffers
N (Mode Mode) and Parcel Mode is Y

in the user-specified move area

CLIv2 automatically replenishes the response buffers. That is, the application may call DBCHCL for the Fetch function repeatedly.

The response buffers may or may not be large enough to hold all the parcels in the response, but the application can draw on them as if they are.

Response Buffers and Rewind

If the application calls DBCHCL for the Rewind function, the pointer that moves back to the first parcel is a pointer in the response stored on a spool file in Teradata Database, not a pointer in the response stored in the response buffers. Therefore, if rewinding may take place, it is important to operate with Keep-response set to 'Y', even if the whole response can fit in the response buffer or buffers.

The response buffer must be at least long enough to hold an Error parcel or Failure parcel, so that the application can detect a problem if it arises. If the response buffer is not long enough for the longest parcel, CLIv2 expands the buffer to the required size (if less than the maximum size) at the time it encounters the longest parcel. If Teradata Database requires a response buffer larger than 32767 bytes but Maximum-parcel is not set to H, then an Error parcel with error code 3177 will be returned.

An Error parcel with error code 3115, 3116, or 3177 may also be returned if that parcel contains an invalid information field (zero, greater than 32767 when Maximum-parcel is set to O, or not greater than the existing buffer size).

Response-buffer-length and Performance

The growth operation costs CPU time. If an application is being optimized for performance and Current-response-buffer-length is higher than Response-buffer-length, consider increasing Response-buffer-length. If all the parcels in the response do not fit in one response buffer, Teradata Database first sends one buffer full of the response and later, as directed by CLIv2, sends the remaining response one buffer full at a time.

A buffer full of parcels refers to the number of whole parcels that can fit in the buffer.

Parcels do not span buffers. As a rule of thumb, the larger the response buffer, the more efficient the transmission of the response from Teradata Database.

Active Buffers Per Request

There are times when CLIv2's sending in to Teradata Database for the next buffer full of a response conflicts with CLIv2's sending in a new request to Teradata Database. The rule in effect is that a session may have Teradata Database active on its behalf for only one request at a time. This applies to the requests the application knows about as well as to the restocking requests done “behind the scenes.” If CLIv2 is restocking response buffers, CLIv2 returns busy from a call to DBCHCL for the Fetch function if Wait-for-response is N. This phenomenon is a possibility when a new request has been refused.