SQLGetCursorName 函数SQLGetCursorName Function

Conformance
引入的版本: ODBC 1.0 标准符合性: ISO 92Version Introduced: ODBC 1.0 Standards Compliance: ISO 92

总结Summary
SQLGetCursorName返回与指定语句相关联的游标名称。SQLGetCursorName returns the cursor name associated with a specified statement.

语法Syntax

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

参数Arguments

StatementHandleStatementHandle
送语句句柄。[Input] Statement handle.

CursorNameCursorName
输出指向缓冲区的指针,将在此缓冲区中返回游标名称。[Output] Pointer to a buffer in which to return the cursor name.

如果CursorName为 NULL,则NameLengthPtr仍将返回可用于在CursorName所指向的缓冲区中返回的字符总数(字符数据的 NULL 终止字符除外)。If CursorName is NULL, NameLengthPtr will still return the total number of characters (excluding the null-termination character for character data) available to return in the buffer pointed to by CursorName.

BufferLengthBufferLength
送* CursorName的长度,以字符为长度。[Input] Length of *CursorName, in characters. 如果* *CursorName中的值是 Unicode 字符串(在调用SQLGetCursorNameW时),则BufferLength*参数必须是偶数。If the value in *CursorName is a Unicode string (when calling SQLGetCursorNameW), the BufferLength argument must be an even number.

NameLengthPtrNameLengthPtr
输出一个指向内存的指针,将在此内存中返回可在* CursorName中返回的字符总数(不包括 null 终止字符)。[Output] Pointer to memory in which to return the total number of characters (excluding the null-termination character) available to return in *CursorName. 如果可返回的字符数大于或等于BufferLength,则* CursorName中的游标名称将被截断为BufferLength减去 null 终止字符的长度。If the number of characters available to return is greater than or equal to BufferLength, the cursor name in *CursorName is truncated to BufferLength minus the length of a null-termination character.

返回Returns

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR 或 SQL_INVALID_HANDLE。SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.

诊断Diagnostics

SQLGetCursorName返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时,可以通过使用HandleType的 SQL_HANDLE_STMT 和StatementHandle句柄调用SQLGetDiagRec来获取关联的 SQLSTATE 值。When SQLGetCursorName returns either SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value can be obtained by calling SQLGetDiagRec with a HandleType of SQL_HANDLE_STMT and a Handle of StatementHandle. 下表列出了通常由SQLGetCursorName返回的 SQLSTATE 值,并对该函数的上下文中的每个值进行了说明:"(DM)" 表示法位于驱动程序管理器返回的 SQLSTATEs 的说明之前。The following table lists the SQLSTATE values commonly returned by SQLGetCursorName and explains each one in the context of this function; the notation "(DM)" precedes the descriptions of SQLSTATEs returned by the Driver Manager. 除非另有说明,否则与每个 SQLSTATE 值相关联的返回代码将 SQL_ERROR。The return code associated with each SQLSTATE value is SQL_ERROR, unless noted otherwise.

SQLSTATESQLSTATE 错误Error 说明Description
0100001000 一般警告General warning 驱动程序特定的信息性消息。Driver-specific informational message. (函数返回 SQL_SUCCESS_WITH_INFO。)(Function returns SQL_SUCCESS_WITH_INFO.)
0100401004 字符串数据,右截断String data, right truncated 缓冲区* CursorName不够大,无法返回整个游标名称,因此游标名称已被截断。The buffer *CursorName was not large enough to return the entire cursor name, so the cursor name was truncated. 在 *NameLengthPtr中返回未截断游标名称的长度。The length of the untruncated cursor name is returned in *NameLengthPtr. (函数返回 SQL_SUCCESS_WITH_INFO。)(Function returns SQL_SUCCESS_WITH_INFO.)
HY000HY000 常规错误General error 发生了一个错误,该错误没有特定的 SQLSTATE,没有为其定义实现特定的 SQLSTATE。An error occurred for which there was no specific SQLSTATE and for which no implementation-specific SQLSTATE was defined. MessageText 缓冲区中的SQLGetDiagRec返回的错误消息描述了错误及其原因。 * **The error message returned by SQLGetDiagRec in the *MessageText buffer describes the error and its cause.
HY001HY001 内存分配错误Memory allocation error 驱动程序无法分配支持执行或完成此函数所需的内存。The driver was unable to allocate memory required to support execution or completion of the function.
HY010HY010 函数序列错误Function sequence error (DM)为与StatementHandle关联的连接句柄调用了异步执行的函数。(DM) An asynchronously executing function was called for the connection handle that is associated with the StatementHandle. 调用SQLGetCursorName函数时,此异步函数仍在执行。This asynchronous function was still executing when the SQLGetCursorName function was called.

StatementHandle调用了SQLExecuteSQLExecDirectSQLMoreResults ,并返回 SQL_PARAM_DATA_AVAILABLE。(DM) SQLExecute, SQLExecDirect, or SQLMoreResults was called for the StatementHandle and returned SQL_PARAM_DATA_AVAILABLE. 在检索所有流式处理参数的数据之前调用此函数。This function was called before data was retrieved for all streamed parameters.

(DM)为StatementHandle调用了异步执行的函数,并且在调用此函数时仍在执行该函数。(DM) An asynchronously executing function was called for the StatementHandle and was still executing when this function was called.

(DM) SQLExecuteSQLExecDirectSQLBulkOperationsSQLSetPos调用了StatementHandle并返回 SQL_NEED_DATA。(DM) SQLExecute, SQLExecDirect, SQLBulkOperations, or SQLSetPos was called for the StatementHandle and returned SQL_NEED_DATA. 在为所有执行时数据参数或列发送数据之前,将调用此函数。This function was called before data was sent for all data-at-execution parameters or columns.
HY013HY013 内存管理错误Memory management error 未能处理函数调用,原因可能是由于内存不足而无法访问基础内存对象。The function call could not be processed because the underlying memory objects could not be accessed, possibly because of low memory conditions.
HY015HY015 没有可用的游标名称No cursor name available (DM)驱动程序是一个 ODBC 2.x驱动程序,语句中没有打开的游标,并且没有使用SQLSetCursorName设置游标名称。(DM) The driver was an ODBC 2 .x driver, there was no open cursor on the statement, and no cursor name had been set with SQLSetCursorName.
HY090HY090 字符串或缓冲区长度无效Invalid string or buffer length (DM)在参数BufferLength中指定的值小于0。(DM) The value specified in the argument BufferLength was less than 0.
HY117HY117 由于未知的事务状态,连接被挂起。Connection is suspended due to unknown transaction state. 仅允许断开连接和只读函数。Only disconnect and read-only functions are allowed. (DM)有关挂起状态的详细信息,请参阅SQLEndTran 函数(DM) For more information about suspended state, see SQLEndTran Function.
HYT01HYT01 连接超时已过期Connection timeout expired 连接超时期限在数据源响应请求之前过期。The connection timeout period expired before the data source responded to the request. 连接超时期限通过SQLSetConnectAttr设置,SQL_ATTR_CONNECTION_TIMEOUT。The connection timeout period is set through SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001IM001 驱动程序不支持此功能Driver does not support this function (DM)与StatementHandle关联的驱动程序不支持该函数。(DM) The driver associated with the StatementHandle does not support the function.

注释Comments

游标名称仅用于定位的 update 和 delete 语句(例如,更新表名称.。。光标的当前名称)。Cursor names are used only in positioned update and delete statements (for example, UPDATE table-name ...WHERE CURRENT OF cursor-name). 有关详细信息,请参阅定位更新和删除语句For more information, see Positioned Update and Delete Statements. 如果应用程序不调用SQLSetCursorName来定义游标名称,则驱动程序将生成一个名称。If the application does not call SQLSetCursorName to define a cursor name, the driver generates a name. 此名称以字母开头 SQL_CUR。This name begins with the letters SQL_CUR.

备注

在 ODBC 2.x中,当没有打开的游标,并且调用SQLSetCursorName未设置任何名称时,对SQLGETCURSORNAME的调用将返回 SQLSTATE HY015 (无可用的游标名称)。In ODBC 2 .x, when there was no open cursor and no name had been set by a call to SQLSetCursorName, a call to SQLGetCursorName returned SQLSTATE HY015 (No cursor name available). 在 ODBC 3.x中,这种情况不再成立;无论何时调用SQLGetCursorName ,驱动程序都将返回游标名称。In ODBC 3 .x, this is no longer true; regardless of when SQLGetCursorName is called, the driver returns the cursor name.

无论名称是显式创建还是隐式创建, SQLGetCursorName都将返回游标的名称。SQLGetCursorName returns the name of a cursor whether or not the name was created explicitly or implicitly. 如果未调用SQLSetCursorName ,则会隐式生成游标名称。A cursor name is implicitly generated if SQLSetCursorName is not called. 可以调用SQLSetCursorName来重命名语句上的游标,只要游标处于已分配或准备好的状态。SQLSetCursorName can be called to rename a cursor on a statement as long as the cursor is in an allocated or prepared state.

显式或隐式设置的游标名称将在删除与之关联的StatementHandle后保持不变,并使用SQLFreeHandleHandleType的 SQL_HANDLE_STMT。A cursor name that is set either explicitly or implicitly remains set until the StatementHandle with which it is associated is dropped, using SQLFreeHandle with a HandleType of SQL_HANDLE_STMT.

有关以下方面的信息For information about 请参阅See
执行 SQL 语句Executing an SQL statement SQLExecDirect 函数SQLExecDirect Function
执行已准备的 SQL 语句Executing a prepared SQL statement SQLExecute 函数SQLExecute Function
准备要执行的语句Preparing a statement for execution SQLPrepare 函数SQLPrepare Function
设置游标名称Setting a cursor name SQLSetCursorName 函数SQLSetCursorName Function

另请参阅See Also

ODBC API 参考 ODBC API Reference
ODBC 头文件ODBC Header Files