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 of SQL_HANDLE_STMT 和 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。 *MessageText 缓冲区中 SQLGetDiagRec 返回的错误消息描述错误及其原因。 |
| HY001 | 内存分配错误 | 驱动程序无法分配支持执行或完成函数所需的内存。 |
| HY010 | 函数序列错误 | （DM） 为与 StatementHandle 关联的连接句柄调用异步执行函数。 调用 SQLGetCursorName 函数时，此异步函数仍在执行。 （DM） 为 StatementHandle 调用了 SQLExecute、SQLExecDirect 或 SQLMoreResults，并返回了SQL_PARAM_DATA_AVAILABLE。 在检索所有流式处理参数的数据之前调用此函数。 （DM） 为 StatementHandle 调用异步执行函数，并在调用此函数时仍在执行。 （DM） 为 StatementHandle 调用了 SQLExecute、SQLExecDirect、SQLBulkOperations 或 SQLSetPos，并返回了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 CURRENT OF cursor-name）。 有关详细信息，请参阅 定位更新和删除语句。 如果应用程序不调用 SQLSetCursorName 来定义游标名称，驱动程序将生成一个名称。 此名称以字母SQL_CUR开头。
注意
在 ODBC 2*.x* 中，当没有打开的游标，并且 SQLSetCursorName 调用未设置名称时，对 SQLGetCursorName 的调用返回了 SQLSTATE HY015（没有可用的游标名称）。 在 ODBC 3*.x* 中，这不再为 true;无论何时 调用 SQLGetCursorName ，驱动程序都会返回游标名称。
SQLGetCursorName 返回游标的名称，无论名称是显式还是隐式创建。 如果未 调用 SQLSetCursorName ，则隐式生成游标名称。 只要游标处于已分配或准备状态，就可以调用 SQLSetCursorName 来重命名语句上的游标。
显式或隐式设置的游标名称将保留设置，直到删除与其关联的 StatementHandle，并将 SQLFreeHandle 与 handleType 结合使用SQL_HANDLE_STMT。
相关函数
| 有关以下内容的信息 | 请参阅 |
|---|---|
| 执行 SQL 语句 | SQLExecDirect 函数 |
| 执行准备的 SQL 语句 | SQLExecute 函数 |
| 准备语句以供执行 | SQLPrepare 函数 |
| 设置游标名称 | SQLSetCursorName 函数 |