Length of string arguments in DB2 UDB CLI functions

 

Input string arguments have an associated length argument.

The length argument indicates to DB2^® UDB call level interface (CLI) either the length of the allocated buffer (not including the null byte terminator) or the special value SQL_NTS. If SQL_NTS is passed, DB2 UDB CLI determines the length of the string by locating the null terminating character.

Output string arguments have two associated length arguments, one to specify the length of the allocated buffer and one to return the length of the string returned by DB2 UDB CLI. The returned length value is the total length of the string available for return, whether it fits in the buffer or not.

For SQL column data, if the output is an empty string, SQL_NULL_DATA is returned in the length argument.

If a function is called with a null pointer for an output length argument, DB2 UDB CLI does not return a length. This might be useful when it is known that the buffers are large enough for all possible results. If DB2 UDB CLI attempts to return the SQL_NULL_DATA value to indicate a column contains null data and the output length argument is a null pointer, the function call fails.

Every character string that DB2 UDB CLI returns is terminated with a null terminating character (hexadecimal 00), except for strings that are returned from graphic data types. This requires that all buffers allocate enough space for the maximum number that is expected, plus one for the null-terminating character.

 

Parent topic:

Working with string arguments in DB2 UDB CLI functions