通过

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

另请参阅

ODBC API 参考
ODBC 头文件