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 为 SQL_HANDLE_STMT 和 Handle of 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。 SQLGetDiagRec 在 *MessageText 缓冲区中返回的错误消息描述了错误及其原因。 |
| HY001 | 内存分配错误 | 驱动程序无法分配支持执行或完成函数所需的内存。 |
| HY009 | null 指针的使用无效 | (DM) 参数 CursorName 为 null 指针。 |
| HY010 | 函数序列错误 | (DM) 为与 StatementHandle 关联的连接句柄调用了异步执行的函数。 调用 SQLSetCursorName 函数时，此异步函数仍在执行。 (DM) 为 StatementHandle 调用了异步执行的函数，并在调用此函数时仍在执行。 (DM) SQLExecute、 SQLExecDirect、 SQLBulkOperations 或 SQLSetPos 已为 StatementHandle 调用，并返回SQL_NEED_DATA。 在针对所有数据执行参数或列发送数据之前调用了此函数。 |
| HY013 | 内存管理错误 | 无法处理函数调用，因为无法访问基础内存对象，可能是由于内存不足。 |
| HY090 | 无效的字符串或缓冲区长度 | (DM) 参数 NameLength 小于 0 但不等于 SQL_NTS。 |
| HY117 | 由于事务状态未知，连接已暂停。 仅允许断开连接和只读函数。 | (DM) 有关挂起状态的详细信息，请参阅 SQLEndTran 函数。 |
| HYT01 | 超过连接超时时间 | 在数据源响应请求之前，连接超时期限已过期。 连接超时期限通过 SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT设置。 |
| IM001 | 驱动程序不支持此函数 | (DM) 与 StatementHandle 关联的驱动程序不支持 函数。 |
注释
游标名称仅用于定位更新和删除语句 (例如 UPDATE表名称 ...WHERE 当前游标名称) 。 有关详细信息，请参阅 定位更新和删除语句。 如果应用程序不调用 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 函数 |