Output buffers
An application passes arguments to the driver so that the driver can return data in an output buffer.
- The address of the output buffer, to which the driver returns
the data
Unless it is prohibited in a function description, the address of an output buffer can be a null pointer. In such cases, the driver does not return anything in the buffer and, in the absence of other errors, returns SQL_SUCCESS.
If necessary, the driver converts data before returning it. The driver always null-terminates character data before returning it.
- The length of the buffer
The driver ignores this value if the returned data has a fixed length in C, as with an integer, real number, or date structure.
- The address of a variable in which the driver returns the length
of the data (the length buffer)
The returned length of the data is SQL_NULL_DATA if the data is a null value in a result set. Otherwise, the returned length of the data is the number of bytes of data that are available to return. If the driver converts the data, the returned length of the data is the number of bytes that remain after the conversion; for character data, it does not include the null-termination byte that the driver adds.
If the output buffer is too small, the driver attempts to truncate the data. If the truncation does not cause a loss of significant data, the driver returns the truncated data in the output buffer, returns the length of the available data (as opposed to the length of the truncated data) in the length buffer, and returns SQL_SUCCESS_WITH_INFO. If the truncation causes a loss of significant data, the driver leaves the output and length buffers untouched and returns SQL_ERROR. The application calls SQLGetDiagRec to retrieve information about the truncation or the error.