SQLBindCol

SQLBindCol

SQLBindCol 　　函数功能描述:将数据缓冲绑定到结果集的列

 说明：

 　　版本引入：ODBC 1.0

 　　遵从标准：ISO 92

 　　功能说明： SQLBindCol将应用程序的数据缓冲绑定到结果集的各列

 　　函数原型： SQLRETURN SQLBindCol( 　　SQLHSTMT StatementHandle, 　　SQLUSMALLINT ColumnNumber, 　　SQLSMALLINT TargetType, 　　SQLPOINTER TargetValuePtr, 　　SQLINTEGER BufferLength, 　　SQLLEN * StrLen_or_Ind);

参数：

 　　StatementHandle 　　[输入] 声明的句柄

 　　ColumnNumber 　　[输入] 结果集里要绑定的列号。列号为从0开始递增的数字编号，第0列为书签列。如果没有使用书签――就是说，SQL_ATTR_USE_BOOKMARKS这个声明属性被置为SQL_UB_OFF――那么列号从1开始计数；

 　　TargetType 　　[输入] *TargetValuePtr所指缓冲的C数据类型的标识符，当通过SQLFetch, SQLFetchScroll, SQLBulkOperations或 SQLSetPos从数据源取得数据的时候，驱动程序将数据转换成这个类型；当通过SQLBulkOperations或SQLSetPos发送数据到数据源时，驱动程序从这个类型来转换数据。

 　　TargetValuePtr 　　[输入/输出] 用来绑定列的数据缓冲的指针。SQLFetch 和SQLFetchScroll返回数据到这个缓冲。当操作为SQL_FETCH_BY_BOOKMARK标识的时候SQLBulkOperations返回数据到这个缓冲。当操作为SQL_ADD 或 SQL_UPDATE_BY_BOOKMARK时，从这个缓冲取得数据。当操作为SQL_REFRESH时，SQLSetPos返回数据到这个缓冲中；当操作为SQL_UPDATE时，从这个缓冲取得数据。如果TargetValuePtr为一空指针，驱动程序取消列到数据缓冲的绑定。应用程序可通过SQL_UNBIND选项通过调用SQLFreeStmt来取消所有列的绑定。如果SQLBindCol调用的TargetValuePtr参数为空指针而StrLen_or_IndPtr是有效的值的话，应用程序可取消列的绑定但仍然存在一个该列的长度/指示缓冲绑定。

 　　BufferLength 　　[输入] *TargetValuePtr指向的缓冲的字节数长度。驱动程序使用BufferLength来避免返回可变长数据如字符或二进制数时写过*TargetValuePtr的边界。注意驱动程序会在返回字符数据到*TargetValuePtr时计算空终止符。因此*TargetValuePtr缓冲就要包括空终止符的空间，否则驱动程序会截短数据。当驱动程序返回定长数据如整形数或一个数据结构时，驱动程序会忽略BufferLength参数并判断缓冲是否足够大来接收数据。因此很重要的是应用程序要分配一个足够大的缓冲给定长数据，否则驱动程序会写过缓冲的界。当BufferLength 小于0时SQLBindCol返回SQLSTATE HY090（无效的字符串或缓冲长度），等于0时不返回这个结果，可是，如果TargetType指定为一个字符类型，应用程序就不要将BufferLength设为0，因为ISO的CLI-适应的 驱动程序在这种情况下返回SQLSTATE HY090。

 　　StrLen_or_IndPtr 　　[输入/输出] 指向绑定列的长度/指示缓冲。SQLFetch 和 SQLFetchScroll返回一个数值到这个缓冲。当操作为SQL_ADD，SQL_UPDATE_BY_BOOKMARK, 或 SQL_DELETE_BY_BOOKMARK时SQLBulkOperations从这个缓冲取得一个数值。当操作为SQL_FETCH_BY_BOOKMARK时SQLBulkOperations返回一个数值到这个缓冲，当操作为SQL_REFRESH时SQLSetPos返回一个数值到此缓冲；但操作为SQL_UPDATE时，它从这个缓冲取回一个数值。SQLFetch, SQLFetchScroll, SQLBulkOperations, 和 SQLSetPos可返回以下数值到长度/指示缓冲：

 　　  l 返回数据的有效长度 　　l SQL_NO_TOTAL 　　l SQL_NULL_DATA

 　　应用程序可下列值放入长度/指示缓冲给供SQLBulkOperations 或SQLSetPos使用：

 　　  l 待发送数据的长度 　　l SQL_NTS 　　l SQL_NULL_DATA 　　l SQL_DATA_AT_EXEC 　　l SQL_LEN_DATA_AT_EXEC宏的结果 　　l SQL_COLUMN_IGNORE

 　　如果指示缓冲和长度缓冲是分开的缓冲区的话，指示缓冲只能返回SQL_NULL_DATA，而长度缓冲可返回所有其他的值。如果StrLen_or_IndPtr为一个空指针，那么没有可用的长度或指示值。这是当取数据且数据为NULL时的一个错误。

 　　返回值： 　　SQL_SUCCESS,SQL_SUCCESS_WITH_INFO,SQL_ERROR,或SQL_INVALID_HANDLE.

 　　 备注：此SDK函数的使用涉及到很多相关的部分，请使用者一定要认真仔细。

示例代码： 　　

   #define NAME_LEN 50 　　

   #define PHONE_LEN 10 　　

   SQLCHAR szName[NAME_LEN], szPhone[PHONE_LEN]; 　　

   SQLINTEGER sCustID, cbName, cbCustID, cbPhone; 　　

   SQLHSTMT hstmt; 　　

   SQLRETURN retcode; 　　

   retcode = SQLExecDirect(hstmt, 　　"SELECT CUSTID, NAME, PHONE FROM CUSTOMERS ORDER BY 2, 1, 3", 　　SQL_NTS); 　　

   if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO)

　　{ 　　/* Bind columns 1, 2, and 3 */

　　        SQLBindCol(hstmt, 1, SQL_C_ULONG, &sCustID, 0, &cbCustID);

　　        SQLBindCol(hstmt, 2, SQL_C_CHAR, szName, NAME_LEN, &cbName);

 　　       SQLBindCol(hstmt, 3, SQL_C_CHAR, szPhone, PHONE_LEN, &cbPhone);

　　        /* Fetch and print each row of data. On */

 　　       /* an error, display a message and exit. */

　　       while (TRUE) 　　

              {

 　　              retcode = SQLFetch(hstmt);

 　　              if (retcode == SQL_ERROR || retcode == SQL_SUCCESS_WITH_INFO)

　　              {

 　　                     show_error();

　　              }

 　　              if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO)

　　               {

 　　                     fprintf(out, "%-*s %-5d %*s", NAME_LEN-1, szName, 　　sCustID, PHONE_LEN-1, szPhone);

 　　              }

　　              else

 　　              {

 　　                     break;

　　              }

　　       }

　　}