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 函数 |