The data length is the byte length of the data as it would be stored in the application’s data buffer, not as it is stored in the data source. This distinction is important because the data is often stored in different forms in the buffer and in the source. Thus, for data sent to the data source, this is the byte length of the data before conversion to the data source’s type. For data retrieved from the data source, this is the byte length of the data after conversion to the data buffer’s type and before any truncation is done.
For fixed-length data, such as an integer or a date structure, the byte length of the data is always the size of the data type. In general, applications allocate a data buffer the size of the data type. If the application allocates a smaller buffer, the consequences are undefined because the driver assumes the data buffer is the size of the data type. It does not truncate the data to fit into a smaller buffer. If the application allocates a larger buffer, the extra space is never used.
For variable-length data, such as character or binary data, it is important to recognize that the byte length of the data is separate from and often different than the byte length of the buffer. The relation of these two lengths was shown earlier in this chapter. If the byte length of the data is greater than the byte length of the buffer, the driver truncates the data to the length of the buffer and returns SQL_SUCCESS_WITH_INFO in argument iRet. However, the returned byte length is the length of the untruncated data.
For example, suppose an application allocates 50 bytes for a character data buffer. If the driver has 10 bytes of data to return, it returns those 10 bytes in the buffer. The byte length of the data is 10, and the byte length of the buffer is 50. If the driver has 60 bytes of character data to return, it truncates the data to 50 bytes, returns those bytes in the buffer, and returns SQL_SUCCESS_WITH_INFO in the iRet argument to the function. The byte length of the data is 60 (the length before truncation), and the byte length of the buffer is still 50.
A diagnostic record is created for each column that is truncated. Because it takes time for the driver to create these records and for the application to process them, truncation can degrade performance. Usually, an application can avoid this problem by allocating large enough buffers. However, this might not be possible when working with long data. When data truncation occurs, the application can sometimes allocate a larger buffer and re-fetch the data.