Data Buffer Length

The application passes the byte length of the data buffer to the driver in an argument, named BufferLength or a similar name. For example, in the following call to SQLBindCol, the application specifies the length of the ValuePtr buffer (sizeof(ValuePtr)).

SQLCHAR ValuePtr[50];

SQLINTEGER ValueLenOrInd;

SQLBindCol(hstmt, 1, SQL_C_CHAR, ValuePtr, sizeof(ValuePtr), &ValueLenOrInd);

A driver will always return the number of bytes, not the number of characters, in the buffer length argument of any function that has an output string argument.

Data buffer lengths are required only for output buffers; the driver uses them to avoid writing past the end of the buffer. However, the driver checks the data buffer length only when the buffer contains variable-length data, such as character or binary data. If the buffer contains fixed-length data, such as an integer or date structure, the driver ignores the data buffer length and assumes the buffer is large enough to hold the data; that is, it never truncates fixed-length data. It is therefore important for the application to allocate a large enough buffer for fixed-length data.

When a truncation of non-data output strings occurs (such as the cursor name returned for SQLGetCursorName), the returned length in the buffer length argument is the maximum byte length possible. That means that it is twice the number of characters, because the string could contain DBCS characters. For example, if the cursor name is ten ANSI characters long (10 bytes), and an application calls SQLGetCursorName to try to retrieve the cursor name into a buffer that is 6 bytes long, the value returned in *NameLengthPtr will be 20.

Data buffer lengths are not required for input buffers because the driver does not write to these buffers.