SQLGetCursorName 函数

  • 项目

一致性
引入的版本：ODBC 1.0 标准符合性：ISO 92

摘要
SQLGetCursorName 返回与指定语句关联的游标名称。

语法

  
SQLRETURN SQLGetCursorName(  
     SQLHSTMT        StatementHandle,  
     SQLCHAR *       CursorName,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   NameLengthPtr);

参数

StatementHandle
[输入]语句句柄。

CursorName
[输出]指向要在其中返回游标名称的缓冲区的指针。

如果 CursorName 为 NULL， NameLengthPtr 仍将返回总字符数， (不包括可在 CursorName 指向的缓冲区中返回的字符数据的 null 终止字符) 。

BufferLength
[输入]*CursorName 的长度（以字符为单位）。

NameLengthPtr
[输出]指向内存的指针，该内存中返回的字符总数 (不包括可在 *CursorName 中返回的 null 终止字符) 。 如果可返回的字符数大于或等于 BufferLength，则*CursorName 中的游标名称将截断为 BufferLength 减去 null 终止字符的长度。

返回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR或SQL_INVALID_HANDLE。

诊断

当 SQLGetCursorName 返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时，可以通过使用 handleType 为 SQL_HANDLE_STMT 和 Handle of StatementHandle 调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值。 下表列出了 SQLGetCursorName 通常返回的 SQLSTATE 值，并说明了此函数上下文中的每个值：表示法“ (DM) ”位于驱动程序管理器返回的 SQLSTATE 说明之前。 与每个 SQLSTATE 值关联的返回代码SQL_ERROR，除非另有说明。

SQLSTATE 错误 说明
01000 常规警告 特定于驱动程序的信息性消息。 (函数返回 SQL_SUCCESS_WITH_INFO.)
01004 字符串数据，右截断 缓冲区 *CursorName 不够大，无法返回整个游标名称，因此游标名称被截断。 未构造游标名称的长度在 *NameLengthPtr 中返回。 (函数返回 SQL_SUCCESS_WITH_INFO.)
HY000 常规错误 发生错误，其中没有特定的 SQLSTATE，也没有定义特定于实现的 SQLSTATE。 SQLGetDiagRec 在 *MessageText 缓冲区中返回的错误消息描述了错误及其原因。
HY001 内存分配错误 驱动程序无法分配支持执行或完成函数所需的内存。
HY010 函数序列错误 (DM) 为与 StatementHandle 关联的连接句柄调用了异步执行的函数。 调用 SQLGetCursorName 函数时，此异步函数仍在执行。

(DM) SQLExecute、 SQLExecDirect 或 SQLMoreResults 已为 StatementHandle 调用并返回SQL_PARAM_DATA_AVAILABLE。 此函数是在检索所有流参数的数据之前调用的。

(DM) 为 StatementHandle 调用了异步执行的函数，并在调用此函数时仍在执行。

(DM) SQLExecute、 SQLExecDirect、 SQLBulkOperations 或 SQLSetPos 已为 StatementHandle 调用，并返回SQL_NEED_DATA。 在针对所有数据执行参数或列发送数据之前调用了此函数。
HY013 内存管理错误 无法处理函数调用，因为无法访问基础内存对象，可能是由于内存不足。
HY015 没有可用的游标名称 (DM) 驱动程序是 ODBC 2*.x* 驱动程序，语句上没有打开的游标，也没有使用 SQLSetCursorName 设置游标名称。
HY090 无效的字符串或缓冲区长度 (DM) 参数 BufferLength 中指定的值小于 0。
HY117 由于事务状态未知，连接已暂停。 仅允许断开连接和只读函数。 (DM) 有关挂起状态的详细信息，请参阅 SQLEndTran 函数。
HYT01 超过连接超时时间 在数据源响应请求之前，连接超时期限已过期。 连接超时期限通过 SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT设置。
IM001 驱动程序不支持此函数 (DM) 与 StatementHandle 关联的驱动程序不支持 函数。

注释

游标名称仅用于定位更新和删除语句 (例如 UPDATE表名称 ...WHERE 当前游标名称) 。 有关详细信息，请参阅 定位更新和删除语句。 如果应用程序不调用 SQLSetCursorName 来定义游标名称，驱动程序将生成一个名称。 此名称以字母SQL_CUR开头。

注意

在 ODBC 2*.x* 中，当没有打开游标且没有通过调用 SQLSetCursorName 设置名称时，对 SQLGetCursorName 的调用将返回 SQLSTATE HY015 () 没有可用的游标名称。 在 ODBC 3*.x* 中，这种情况不再成立;无论何时调用 SQLGetCursorName ，驱动程序都会返回游标名称。

无论名称是显式还是隐式创建，SQLGetCursorName 都返回游标的名称。 如果未调用 SQLSetCursorName ，则会隐式生成游标名称。 只要游标处于已分配或准备状态，就可以调用 SQLSetCursorName 来重命名语句上的游标。

显式或隐式设置的游标名称将保留设置，直到删除与它关联的 StatementHandle ，使用 SQLFreeHandle 和 handleType SQL_HANDLE_STMT。

有关以下方面的信息 请参阅
执行 SQL 语句 SQLExecDirect 函数
执行准备好的 SQL 语句 SQLExecute 函数
准备要执行的语句 SQLPrepare 函数
设置游标名称 SQLSetCursorName 函数

另请参阅

ODBC API 参考
ODBC 头文件