SQLBindCol

SQLBindCol

函数状态: 正式函数 ,建设者:快乐浪子 ,最新更新时间: 2003-1-24 17:24:41 修改该函数

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

说明：
   版本引入：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;
      }
   }
}