Buffers

An application passes data to the driver in an input buffer. The driver returns data to the application in an output buffer. The application must allocate memory for both input and output buffers. If the application uses the buffer to retrieve string data, the buffer must contain space for the null termination byte.

Some functions accept pointers to buffers that are used later by other functions. The application must ensure that these pointers remain valid until all applicable functions have used them. For example, the argument rgbValue in SQLBindCol points to an output buffer where SQLFetch returns the data for a column.

Input Buffers

An application passes the address and length of an input buffer to the driver. The length of the buffer must be one of the following values:

• A length greater than or equal to zero

  This value is the actual length of the data in the input buffer. For character data, a length of zero indicates that the data is an empty (zero length) string. A length of zero is different from a null pointer. If the application specifies the length of character data, the character data does not need to be null-terminated.

• SQL_NTS

  This value specifies that a character data value is null-terminated.

• SQL_NULL_DATA

  This value tells the driver to ignore the value in the input buffer and use a NULL data value instead. It is valid only when the input buffer provides the value of a parameter in an SQL statement.

For character data that contains embedded null characters, the operation of IBM Informix ODBC Driver functions is undefined; for maximum interoperability, it is better not to use them. Informix database servers treat null characters as end-of-string markers or as indicators that no more data exists.

Unless it is specifically prohibited in a function description, the address of an input buffer can be a null pointer. In such cases, the value of the corresponding buffer-length argument is ignored. For more information about input buffers, see Converting Data from SQL to C.

Output Buffers

An application passes the following 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 specifically 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.

For more information about output buffers, see Converting Data from SQL to C.