SQLBindCol--Bind a column to an application variable

Purpose

SQLBindCol() is used to associate (bind) columns in a result set to application variables, for all C data types. Data is transferred from the DBMS to the application when SQLFetch() is called. Data conversion might occur when the data is transferred.

SQLBindCol() is called once for each column in the result set that the application needs to retrieve.

In general, SQLPrepare() or SQLExecDirect() is called before this function, and SQLFetch() is called after. Column attributes might also be needed before calling SQLBindCol(), and can be obtained using SQLDescribeCol().

Syntax

SQLRETURN   SQLBindCol       (SQLHSTMT          StatementHandle,   /* hstmt */
                              SQLUSMALLINT      ColumnNumber,      /* icol */
                              SQLSMALLINT       TargetType,        /* fCType */
                              SQLPOINTER        TargetValuePtr,    /* rgbValue */
                              SQLINTEGER        BufferLength,      /* cbValueMax */
                              SQLINTEGER   *FAR StrLen_or_IndPtr); /* pcbValue */

Function arguments

Table 32. SQLBindCol arguments

For this function, both TargetValuePtr and StrLen_or_Ind are deferred outputs, meaning that the storage locations these pointers point to do not get updated until a result set row is fetched. As a result, the locations referenced by these pointers must remain valid until SQLFetch() is called. For example, if SQLBindCol() is called within a local function, SQLFetch() must be called from within the same scope of the function or the TargetValuePtr buffer must be allocated or declared as static or global.

Usage

The application calls SQLBindCol() one time for each column in the result set for which it wants to retrieve the data. Result sets are generated either by calling SQLExecute() or SQLExecDirect(). When SQLFetch() is called, the data in each of these bound columns is placed into the assigned location (given by the pointers TargetValuePtr and StrLen_or_Ind).

Columns are identified by a number, assigned sequentially from left to right. Column numbers start at one.

The number of columns in the result set can be determined by calling SQLNumResultCols().

The application can query the attributes (such as data type and length) of the column by first calling SQLDescribeCol(). This information can then be used to allocate a storage location of the correct data type and length to indicate data conversion to another data type.

An application can choose not to bind every column, or even not to bind any columns. Data in any of the columns can also be retrieved using SQLGetData() after the bound columns are fetched for the current row.

In subsequent fetches, the application can change the binding of these columns or bind previously unbound columns by calling SQLBindCol(). The new binding does not apply to data already fetched, it is used on the next fetch. To unbind a single column, call SQLBindCol() with the TargetValuePtr pointer set to NULL. To unbind all the columns, the application should call SQLFreeStmt().

The application must ensure that enough storage is allocated for the data to be retrieved. If the buffer is to contain variable length data, the application must allocate as much storage as the maximum length of the bound column requires; otherwise, the data might be truncated. If the buffer is to contain fixed length data, DB2 CLI assumes that the size of the buffer is the length of the C data type. If data conversion is specified, the required size might be affected.

If string truncation occurs, SQL_SUCCESS_WITH_INFO is returned and StrLen_or_IndPtr is set to the actual size of TargetValuePtr available for return to the application.

Return codes

• SQL_SUCCESS
• SQL_SUCCESS_WITH_INFO
• SQL_ERROR
• SQL_INVALID_HANDLE

Diagnostics

Table 33. SQLBindCol SQLSTATEs

Additional diagnostic messages relating to the bound columns might be reported at fetch time.

Restrictions

Output buffers need to be word-aligned (even). Many processors such as the Motorola 68000 have word-alignment rules, and for non-character data types, the application should align the buffer properly.

Related reference

• Key to DB2 CLI function descriptions
• DB2 CLI function summary