SQLFetch() 使游标前进到结果集的下一行,并检索任何已绑定的列。
SQLFetch() 可用来将数据直接接收到您使用 SQLBindCol() 指定的变量中,也可以在取装之后通过调用 SQLGetData() 来分别接收列。如果在绑定列时指示了转换,则调用 SQLFetch() 时也将执行数据转换。
语法
SQLRETURN SQLFetch (SQLHSTMT hstmt);
函数自变量
数据类型 | 自变量 | 使用 | 描述 |
---|---|---|---|
SQLHSTMT | hstmt | 输入 | 语句句柄 |
用法
仅当最近对 hstmt 执行的语句是 SELECT 时,才可以调用 SQLFetch()。
使用 SQLBindCol() 绑定的应用程序变量的数目一定不能超出结果集中的列数,否则 SQLFetch() 将失败。
如果尚未调用 SQLBindCol() 来绑定任何列,则 SQLFetch() 不返回数据给应用程序,而仅仅使游标前进。在这种情况下,可接着调用 SQLGetData() 来个别地获取所有的列。当 SQLFetch() 使游标前进到下一行时,将废弃未绑定的列中的数据。
如果任何绑定的变量不够大,从而无法存放 SQLFetch() 返回的数据,则将数据截断。如果截断了字符数据,则将返回 SQL_SUCCESS_WITH_INFO,并且生成指示已进行截断的 SQLSTATE。SQLBindCol() 延迟输出自变量 pcbValue 包含从服务器检索的列数据的实际长度。应用程序应该将输出长度与输入长度(来自 SQLBindCol() 的 pcbValue 和 cbValueMax 自变量)作比较以确定已将哪些字符列截断。
如果截断涉及小数点右边的位,则不报告数字数据类型的截断。如果截断发生在小数点的左边,则返回错误(请参考诊断部分)。
将图形数据类型的截断视为与字符数据类型的截断相同。只有一处不同,即填充 rgbValue 缓冲区,使其成为仍小于或等于 SQLBindCol() 中指定的 cbValueMax 的最接近的双字节倍数。在 DB2 UDB CLI 与应用程序之间传送的图形数据永远不会以空终止。
在从结果集检索所有行之后,或者在不需要其余的行时,应调用 SQLFreeStmt() 来关闭游标并废弃其余的数据和相关联的资源。
返回码
如果结果集中没有行,或者先前的 SQLFetch() 调用已从结果集中取装了所有的行,则将返回 SQL_NO_DATA_FOUND。
诊断
SQLSTATE | 描述 | 说明 |
---|---|---|
01004 | 已截断数据 | 为一列或多列返回的数据已被截断。将在右边对字符串值进行截断。(如果没有发生错误,则返回 SQL_SUCCESS_WITH_INFO。) |
HY001 | 内存分配失败 | 驱动程序无法分配支持此函数的执行或完成所必需的内存。 |
HY010 | 函数顺序错误 | 指定的 hstmt 未处于已执行状态。在没有首先调用 SQLExecute 或 SQLExecDirect 的情况下调用了此函数。 |
HY013 * | 内存管理问题 | 驱动程序无法访问支持此函数的执行或完成所必需的内存。 |
有关代码示例的信息,参见代码不保证声明信息。
/************************************************************************* ** file = fetch.c ** ** Example of executing an SQL statement. ** SQLBindCol & SQLFetch is used to retrive data from the result set ** directly into application storage. ** ** Functions used: ** ** SQLAllocConnect SQLFreeConnect ** SQLAllocEnv SQLFreeEnv ** SQLAllocStmt SQLFreeStmt ** SQLConnect SQLDisconnect ** ** SQLBindCol SQLFetch ** SQLTransact SQLExecDirect ** SQLError ** **************************************************************************/ #include <stdio.h> #include <string.h> #include "sqlcli.h" #define MAX_STMT_LEN 255 int initialize(SQLHENV *henv, SQLHDBC *hdbc); int terminate(SQLHENV henv, SQLHDBC hdbc); int print_error (SQLHENV henv, SQLHDBC hdbc, SQLHSTMT hstmt); int check_error (SQLHENV henv, SQLHDBC hdbc, SQLHSTMT hstmt, SQLRETURN frc); /******************************************************************* ** main ** - initialize ** - terminate *******************************************************************/ int main() { SQLHENV henv; SQLHDBC hdbc; SQLCHAR sqlstmt[MAX_STMT_LEN + 1]=""; SQLRETURN rc; rc = initialize(&henv, &hdbc); if (rc == SQL_ERROR) return(terminate(henv, hdbc)); {SQLHSTMT hstmt; SQLCHAR sqlstmt[]="SELECT deptname, location from org where division = 'Eastern'"; SQLCHAR deptname[15], location[14]; SQLINTEGER rlength; rc = SQLAllocStmt(hdbc, &hstmt); if (rc != SQL_SUCCESS ) check_error (henv, hdbc, SQL_NULL_HSTMT, rc); rc = SQLExecDirect(hstmt, sqlstmt, SQL_NTS); if (rc != SQL_SUCCESS ) check_error (henv, hdbc, hstmt, rc); rc = SQLBindCol(hstmt, 1, SQL_CHAR, (SQLPOINTER) deptname, 15, &rlength); if (rc != SQL_SUCCESS ) check_error (henv, hdbc, hstmt, rc); rc = SQLBindCol(hstmt, 2, SQL_CHAR, (SQLPOINTER) location, 14, &rlength); if (rc != SQL_SUCCESS ) check_error (henv, hdbc, hstmt, rc); printf("Departments in Eastern division:/n"); printf("DEPTNAME Location/n"); printf("-------------- -------------/n"); while ((rc = SQLFetch(hstmt)) == SQL_SUCCESS) { printf("%-14.14s %-13.13s /n", deptname, location); } if (rc != SQL_NO_DATA_FOUND ) check_error (henv, hdbc, hstmt, rc); rc = SQLFreeStmt(hstmt, SQL_DROP); if (rc != SQL_SUCCESS ) check_error (henv, hdbc, SQL_NULL_HSTMT, rc); } rc = SQLTransact(henv, hdbc, SQL_COMMIT); if (rc != SQL_SUCCESS ) check_error (henv, hdbc, SQL_NULL_HSTMT, rc); terminate(henv, hdbc); return (0); }/* end main */ /******************************************************************* ** initialize ** - allocate environment handle ** - allocate connection handle ** - prompt for server, user id, & password ** - connect to server *******************************************************************/ int initialize(SQLHENV *henv, SQLHDBC *hdbc) { SQLCHAR server[SQL_MAX_DSN_LENGTH], uid[30], pwd[30]; SQLRETURN rc; rc = SQLAllocEnv (henv); /* allocate an environment handle */ if (rc != SQL_SUCCESS ) check_error (*henv, *hdbc, SQL_NULL_HSTMT, rc); rc = SQLAllocConnect (*henv, hdbc); /* allocate a connection handle */ if (rc != SQL_SUCCESS ) check_error (*henv, *hdbc, SQL_NULL_HSTMT, rc); printf("Enter Server Name:/n"); gets(server); printf("Enter User Name:/n"); gets(uid); printf("Enter Password Name:/n"); gets(pwd); if (uid[0] == '/0') { rc = SQLConnect (*hdbc, server, SQL_NTS, NULL, SQL_NTS, NULL, SQL_NTS); if (rc != SQL_SUCCESS ) check_error (*henv, *hdbc, SQL_NULL_HSTMT, rc); } else { rc = SQLConnect (*hdbc, server, SQL_NTS, uid, SQL_NTS, pwd, SQL_NTS); if (rc != SQL_SUCCESS ) check_error (*henv, *hdbc, SQL_NULL_HSTMT, rc); } return(SQL_SUCCESS); }/* end initialize */ /******************************************************************* ** terminate ** - disconnect ** - free connection handle ** - free environment handle *******************************************************************/ int terminate(SQLHENV henv, SQLHDBC hdbc) { SQLRETURN rc; rc = SQLDisconnect (hdbc); /* disconnect from database */ if (rc != SQL_SUCCESS ) print_error (henv, hdbc, SQL_NULL_HSTMT); rc = SQLFreeConnect (hdbc); /* free connection handle */ if (rc != SQL_SUCCESS ) print_error (henv, hdbc, SQL_NULL_HSTMT); rc = SQLFreeEnv (henv); /* free environment handle */ if (rc != SQL_SUCCESS ) print_error (henv, hdbc, SQL_NULL_HSTMT); return(rc); }/* end terminate */ /******************************************************************* ** - print_error - call SQLError(), display SQLSTATE and message *******************************************************************/ int print_error (SQLHENV henv, SQLHDBC hdbc, SQLHSTMT hstmt) { SQLCHAR buffer[SQL_MAX_MESSAGE_LENGTH + 1]; SQLCHAR sqlstate[SQL_SQLSTATE_SIZE + 1]; SQLINTEGER sqlcode; SQLSMALLINT length; while ( SQLError(henv, hdbc, hstmt, sqlstate, &sqlcode, buffer, SQL_MAX_MESSAGE_LENGTH + 1, &length) == SQL_SUCCESS ) { printf("/n **** ERROR *****/n"); printf(" SQLSTATE: %s/n", sqlstate); printf("Native Error Code: %ld/n", sqlcode); printf("%s /n", buffer); }; return ( SQL_ERROR); } /* end print_error */ /******************************************************************* ** - check_error - call print_error(), checks severity of return code *******************************************************************/ int check_error (SQLHENV henv, SQLHDBC hdbc, SQLHSTMT hstmt, SQLRETURN frc) { SQLRETURN rc; print_error(henv, hdbc, hstmt); switch (frc){ case SQL_SUCCESS : break; case SQL_ERROR : case SQL_INVALID_HANDLE: printf("/n ** FATAL ERROR, Attempting to rollback transaction **/n"); rc = SQLTransact(henv, hdbc, SQL_ROLLBACK); if (rc != SQL_SUCCESS) printf("Rollback Failed, Exiting application/n"); else printf("Rollback Successful, Exiting application/n"); terminate(henv, hdbc); exit(frc); break; case SQL_SUCCESS_WITH_INFO : printf("/n ** Warning Message, application continuing/n"); break; case SQL_NO_DATA_FOUND : printf("/n ** No Data Found ** /n"); break; default : printf("/n ** Invalid Return Code ** /n"); printf(" ** Attempting to rollback transaction **/n"); SQLTransact(henv, hdbc, SQL_ROLLBACK); terminate(henv, hdbc); exit(frc); break; } return(SQL_SUCCESS); } /* end check_error */
参考