SQLBindCol() - Bind a column to an application variable

ODBC specifications for SQLBindCol()

Function arguments

The following table lists the data type, use, and description for each argument in this function.

Important: You must ensure the locations that the pointers rgbValue and pcbValue reference are valid until you call SQLFetch() or SQLExtendedFetch(). For SQLBindCol(), the pointers rgbValue and pcbValue are deferred outputs, which means that the storage locations to which they point are not updated until you fetch a row from the result set. For example, if you call SQLBindCol() within a local function, you must call SQLFetch() from within the same scope of the function, or you must allocate the rgbValue buffer as static or global.

Tip: Place the buffer that the rgbValue argument specifies consecutively in memory after the buffer that the pcbValue argument specifies for better Db2 ODBC performance for all varying-length data types. See Usage for more details.

Usage

Call SQLBindCol() once for each column in a result set from which you want to retrieve data or LOB locators. You generate result sets when you call SQLPrepare(), SQLExecDirect(), SQLGetTypeInfo(), or one of the catalog functions. After you bind columns to a result set, call SQLFetch() to place data from these columns into application storage locations (the locations to which the rgbValue and cbValue arguments point). If the fCType argument specifies a LOB locator, a locator value (not the LOB data itself) is placed in these locations. This locator value references the entire data value in the LOB column at the server. You might need to obtain column attributes before you call SQLBindCol(). To obtain these attributes, call SQLDescribeCol() or SQLColAttribute().

You can use SQLExtendedFetch() in place of SQLFetch() to retrieve multiple rows from the result set into an array. In this case, the rgbValue argument references an array. You cannot mix calls to SQLExtendedFetch() with calls to SQLFetch() on the same result set.

Obtaining information about the result set: Columns are identified by a number, assigned sequentially from left to right, starting at 1. To determine the number of columns in a result set, call SQLNumResultCols(), or call SQLColAttribute() with the FieldIdentifier argument set to SQL_DESC_COUNT.

Call SQLDescribeCol() or SQLColAttribute() to query the attributes (such as data type and length) of a column. You can then use this information to allocate a storage location with a C data type and length that match the SQL data type an length of the result set column. In the case of LOB data types, you can retrieve a locator instead of the entire LOB value.

You can choose which, if any, columns that you want to bind from a result set. For unbound columns, use SQLGetData() instead of, or in conjunction with, SQLBindCol() to retrieve data. Generally, SQLBindCol() is more efficient than SQLGetData().

During subsequent fetches, you can use SQLBindCol() to change which columns are bound to application variables or to bind previously unbound columns. New binds do not apply to data that you have fetched; these binds are used for the next fetch. To unbind a single column, call SQLBindCol() with the rgbValue pointer set to NULL. To unbind all the columns, call SQLFreeStmt() with the fOption input set to SQL_UNBIND.

Allocating buffers: Ensure that you allocate enough storage to hold the data that you retrieve. When you allocate a buffer to hold varying-length data, allocate an amount of storage that is equal to the maximum length of data that the column that is bound to this buffer can produce. If you allocate less storage than this maximum, SQLFetch() or SQLExtendedFetch() truncates any data that is larger than the space that you allocated. When you allocate a buffer that holds fixed-length data, Db2 ODBC assumes that the size of the buffer is the length of the C data type. If you specify data conversion, the amount of space that the data requires might change.

When you bind a column that is defined as SQL_GRAPHIC, SQL_VARGRAPHIC, or SQL_LONGVARGRAPHIC, you can set the fCType argument to SQL_C_DBCHAR, SQL_C_WCHAR, or SQL_C_CHAR. If you set the fCType argument to SQL_C_DBCHAR or SQL_C_WCHAR, the data that you fetch into the rgbValue buffer is nul-terminated by a double-byte nul-terminator. If you set the fCType argument to SQL_C_CHAR, the data that you fetch is not always nul-terminated. In both cases, the length of the rgbValue buffer (cbValueMax) is in units of bytes, and the value is always a multiple of 2.

When you bind a varying-length column, Db2 ODBC can write to both of the buffers that specified by the pcbValue and rgbValue arguments in one operation if you allocate these buffers contiguously. The following example illustrates how to allocate these buffers contiguously:

struct {  SQLINTEGER  pcbValue;
          SQLCHAR     rgbValue[MAX_BUFFER];
       } column;

Handling data truncation: If SQLFetch() or SQLExtendedFetch() truncates data, it returns SQL_SUCCESS_WITH_INFO and set the pcbValue argument to a value that represents the amount of space (in bytes) that the full data requires.

When you bind a column that holds SQL_ROWID data, you can set the fCType argument to SQL_C_CHAR or SQL_C_DEFAULT. The data that you fetch into the buffer that the rgbValue argument specifies is nul-terminated. The maximum length of a ROWID column in the database management system is 40 bytes. Therefore, to retrieve this type of data without truncation, you must allocate an rgbValue buffer of at least 40 bytes in your application.

Retrieved UTF-8 data is terminated by a single-byte nul-terminator, where as retrieved UCS-2 data is terminated by a double-byte nul-terminator.

The most recent bind column function call determines the type of binding that is in effect.

Return codes

Diagnostics

The following table lists each SQLSTATE that this function generates, with a description and explanation for each value.