SQLSetCursorName 函数
一致性
引入的版本:ODBC 1.0 标准符合性:ISO 92
总结
SQLSetCursorName 将游标名称与活动语句相关联。 如果应用程序不调用 SQLSetCursorName,驱动程序会根据需要为 SQL 语句处理生成游标名称。
语法
SQLRETURN SQLSetCursorName(
SQLHSTMT StatementHandle,
SQLCHAR * CursorName,
SQLSMALLINT NameLength);
参数
StatementHandle
[输入]语句句柄。
CursorName
[输入]游标名称。 为了有效处理,游标名称不应在游标名称中包含任何前导空格或尾随空格,如果游标名称包含带分隔符的标识符,则分隔符应定位为游标名称中的第一个字符。
NameLength
[输入]*CursorName 的长度(以字符为单位)。
返回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR 或SQL_INVALID_HANDLE。
诊断
当 SQLSetCursorName 返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时,可以通过使用 handleType of SQL_HANDLE_STMT 和 StatementHandle 句柄调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值。 下表列出了 SQLSetCursorName 通常返回的 SQLSTATE 值,并解释此函数上下文中的每个值;表示法“(DM)”位于驱动程序管理器返回的 SQLSTATE 的说明之前。 除非另有说明,否则与每个 SQLSTATE 值关联的返回代码SQL_ERROR。
SQLSTATE | 错误 | 说明 |
---|---|---|
01000 | 常规警告 | 特定于驱动程序的信息性消息。 (函数返回SQL_SUCCESS_WITH_INFO。) |
01004 | 字符串数据,右截断 | 游标名称超出了最大限制,因此只使用了允许的最大字符数。 |
24000 | 游标状态无效 | 对应于 StatementHandle 的语句已处于已执行状态或游标定位状态。 |
34000 | 无效的游标名称 | *CursorName 中指定的游标名称无效,因为它超出了驱动程序定义的最大长度,或者以“SQLCUR”或“SQL_CUR”开头。 |
3C000 | 重复的游标名称 | *CursorName 中指定的游标名称已存在。 |
HY000 | 常规错误 | 发生错误:没有特定的 SQLSTATE,也没有定义特定于实现的 SQLSTATE。 *MessageText 缓冲区中 SQLGetDiagRec 返回的错误消息描述错误及其原因。 |
HY001 | 内存分配错误 | 驱动程序无法分配支持执行或完成函数所需的内存。 |
HY009 | 无效使用 null 指针 | (DM) Argument CursorName 为 null 指针。 |
HY010 | 函数序列错误 | (DM) 为与 StatementHandle 关联的连接句柄调用异步执行函数。 调用 SQLSetCursorName 函数时,此异步函数仍在执行。 (DM) 为 StatementHandle 调用异步执行函数,并在调用此函数时仍在执行。 (DM) 为 StatementHandle 调用了 SQLExecute、SQLExecDirect、SQLBulkOperations 或 SQLSetPos,并返回了SQL_NEED_DATA。 在为所有数据执行参数或列发送数据之前调用此函数。 |
HY013 | 内存管理错误 | 无法处理函数调用,因为基础内存对象无法访问,可能是因为内存条件低。 |
HY090 | 字符串或缓冲区长度无效 | (DM) 参数 NameLength 小于 0,但不等于SQL_NTS。 |
HY117 | 连接因未知事务状态而挂起。 仅允许断开连接和只读函数。 | (DM) 有关挂起状态的详细信息,请参阅 SQLEndTran 函数。 |
HYT01 | 超过连接超时时间 | 在数据源响应请求之前,连接超时期限已过期。 连接超时期限通过 SQLSetConnectAttr 设置,SQL_ATTR_CONNECTION_TIMEOUT。 |
IM001 | 驱动程序不支持此函数 | (DM) 与 StatementHandle 关联的驱动程序不支持该函数。 |
评论
游标名称仅用于定位更新和删除语句(例如,UPDATE 表名 ...WHERE CURRENT OF cursor-name)。 有关详细信息,请参阅 定位更新和删除语句。 如果应用程序不调用 SQLSetCursorName 来定义游标名称,则在执行查询语句时,驱动程序将生成以字母开头的名称SQL_CUR且长度不超过 18 个字符。
连接中的所有游标名称必须是唯一的。 驱动程序定义游标名称的最大长度。 为了获得最大的互操作性,建议应用程序将游标名称限制为不超过 18 个字符。 在 ODBC 3*.x* 中,如果游标名称是带引号的标识符,则它以区分大小写的方式进行处理,并且可以包含 SQL 语法不允许或特殊对待的字符,例如空白或保留关键字。 如果游标名称必须以区分大小写的方式进行处理,则必须将其作为带引号的标识符传递。
显式或隐式设置的游标名称将保留设置,直到删除与其关联的语句(使用 SQLFreeHandle)。 只要游标处于已分配或准备状态,就可以调用 SQLSetCursorName 来重命名语句上的游标。
代码示例
在以下示例中,应用程序使用 SQLSetCursorName 为语句设置游标名称。 然后,它使用该语句从 CUSTOMERS 表中检索结果。 最后,它执行定位更新以更改 John Smith 的电话号码。 请注意,应用程序对 SELECT 和 UPDATE 语句使用不同的语句句柄。
有关另一个代码示例,请参阅 SQLSetPos。
#define NAME_LEN 50
#define PHONE_LEN 10
SQLHSTMT hstmtSelect,
SQLHSTMT hstmtUpdate;
SQLRETURN retcode;
SQLHDBC hdbc;
SQLCHAR szName[NAME_LEN], szPhone[PHONE_LEN];
SQLINTEGER cbName, cbPhone;
/* Allocate the statements and set the cursor name. */
SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmtSelect);
SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmtUpdate);
SQLSetCursorName(hstmtSelect, "C1", SQL_NTS);
/* SELECT the result set and bind its columns to local buffers. */
SQLExecDirect(hstmtSelect,
"SELECT NAME, PHONE FROM CUSTOMERS",
SQL_NTS);
SQLBindCol(hstmtSelect, 1, SQL_C_CHAR, szName, NAME_LEN, &cbName);
SQLBindCol(hstmtSelect, 2, SQL_C_CHAR, szPhone, PHONE_LEN, &cbPhone);
/* Read through the result set until the cursor is */
/* positioned on the row for John Smith. */
do
retcode = SQLFetch(hstmtSelect);
while ((retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) &&
(strcmp(szName, "Smith, John") != 0));
/* Perform a positioned update of John Smith's name. */
if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {
SQLExecDirect(hstmtUpdate,
"UPDATE EMPLOYEE SET PHONE=\"2064890154\" WHERE CURRENT OF C1",
SQL_NTS);
}
相关函数
有关以下内容的信息 | 请参阅 |
---|---|
执行 SQL 语句 | SQLExecDirect 函数 |
执行准备的 SQL 语句 | SQLExecute 函数 |
返回游标名称 | SQLGetCursorName 函数 |
设置光标滚动选项 | SQLSetScrollOptions 函数 |