通过

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

另请参阅

ODBC API 参考
ODBC 头文件