SQL Server 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;

}

}

}