Length of string arguments

String arguments for both output and input have associated length arguments. You should always use a valid output length argument.

For input string arguments, the associated length argument passes Db2 ODBC one of the following types of information:
  • The exact length of the string (not including the nul-terminator)
  • The special value SQL_NTS to indicate a nul-terminated string
  • SQL_NULL_DATA to pass a null value
If the length is set to SQL_NTS, Db2 ODBC determines the length of the string by locating the nul-terminator. All length arguments for input/output strings are passed as a count of characters. Length arguments that can refer to both string and non-string data are passed as a count of bytes.

Output string arguments have two associated length arguments, an input length argument to specify the length of the allocated output buffer, and an output length argument to return the actual length of the string returned by Db2 ODBC. The returned length value is the total length of the string available for return, regardless of whether it fits in the buffer or not.

For SQL column data, if the output is a null value, SQL_NULL_DATA is returned in the length argument and the output buffer is untouched.

If a function is called with a null pointer for an output length argument, Db2 ODBC does not return a length, and assumes that the data buffer is large enough to hold the data. When the output data is a null value, Db2 ODBC can not indicate that the value is null. If it is possible that a column in a result set can contain a null value, a valid pointer to the output length argument must always be provided.

Recommendation: Always use a valid output length argument.

If the length argument (pcbValue) and the output buffer (rgbValue) are contiguous in memory, Db2 ODBC can return both values more efficiently, improving application performance. For example, if the following structure is defined and &buffer.pcbValue and buffer.rgbValue are passed to SQLBindCol(), Db2 ODBC updates both values in one operation. 
struct
{   SQLINTEGER pcbValue;
    SQLCHAR    rgbValue [BUFFER_SIZE];
} buffer;