15.10 - Response Buffer - Call-Level Interface Version 2

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

Call-Level Interface Version 2
Programming Reference

Information received from the 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...


    deallocates the buffers when DBCHCL is called for the End Request function.


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

    (Locate Mode)

    to the application in the response buffers

    (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 the 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 the server 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, the 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 the Teradata Database.

    Active Buffers Per Request

    There are times when CLIv2‘s sending in to the Teradata Database for the next buffer full of a response conflicts with CLIv2‘s sending in a new request to the Teradata Database. The rule in effect is that a session may have the 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.