SQLSetCursorName 函数SQLSetCursorName Function

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

总结Summary
SQLSetCursorName将游标名称与活动语句相关联。SQLSetCursorName associates a cursor name with an active statement. 如果应用程序不调用SQLSetCursorName,则驱动程序将根据需要为 SQL 语句处理生成游标名称。If an application does not call SQLSetCursorName, the driver generates cursor names as needed for SQL statement processing.

语法Syntax

  
SQLRETURN SQLSetCursorName(  
     SQLHSTMT      StatementHandle,  
     SQLCHAR *     CursorName,  
     SQLSMALLINT   NameLength);  

参数Arguments

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

CursorNameCursorName
送游标名称。[Input] Cursor name. 为实现有效处理,游标名称不应在游标名称中包括任何前导空格或尾随空格,并且如果游标名称包含分隔的标识符,则分隔符应作为游标名称中的第一个字符定位。For efficient processing, the cursor name should not include any leading or trailing spaces in the cursor name, and if the cursor name includes a delimited identifier, the delimiter should be positioned as the first character in the cursor name.

NameLengthNameLength
送*CursorName中的字符的长度。[Input] Length in characters of *CursorName.

返回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

SQLSetCursorName返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时,可以通过使用HandleType的 SQL_HANDLE_STMT 和StatementHandle句柄调用SQLGetDiagRec来获取关联的 SQLSTATE 值。When SQLSetCursorName returns 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. 下表列出了通常由SQLSetCursorName返回的 SQLSTATE 值,并对该函数的上下文中的每个值进行了说明:"(DM)" 表示法位于驱动程序管理器返回的 SQLSTATEs 的说明之前。The following table lists the SQLSTATE values commonly returned by SQLSetCursorName 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 游标名称超出了最大限制,因此只使用了允许的最大字符数。The cursor name exceeded the maximum limit, so only the maximum allowable number of characters was used.
2400024000 无效的游标状态Invalid cursor state 对应于StatementHandle的语句已经处于执行或游标定位状态。The statement corresponding to StatementHandle was already in an executed or cursor-positioned state.
3400034000 无效的游标名称Invalid cursor name *CursorName中指定的游标名称无效,因为它超出了驱动程序定义的最大长度,或者它以 "SQLCUR" 或 "SQL_CUR" 开头。The cursor name specified in *CursorName was invalid because it exceeded the maximum length as defined by the driver, or it started with "SQLCUR" or "SQL_CUR."
3C0003C000 重复的游标名称Duplicate cursor name *CursorName中指定的游标名已经存在。The cursor name specified in *CursorName already exists.
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.
HY009HY009 空值指针的使用无效Invalid use of null pointer (DM)参数CursorName为 null 指针。(DM) The argument CursorName was a null pointer.
HY010HY010 函数序列错误Function sequence error (DM)为与StatementHandle关联的连接句柄调用了异步执行的函数。(DM) An asynchronously executing function was called for the connection handle that is associated with the StatementHandle. 调用SQLSetCursorName函数时,此 aynchronous 函数仍在执行。This aynchronous function was still executing when the SQLSetCursorName function was called.

(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.
HY090HY090 字符串或缓冲区长度无效Invalid string or buffer length (DM)参数NameLength小于0但不等于 SQL_NTS。(DM) The argument NameLength was less than 0 but not equal to SQL_NTS.
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来定义游标名称,则在执行查询语句时,驱动程序会生成一个名称,该名称以 SQL_CUR 字母开头,并且长度不超过18个字符。If the application does not call SQLSetCursorName to define a cursor name, on execution of a query statement the driver generates a name that begins with the letters SQL_CUR and does not exceed 18 characters in length.

连接中的所有游标名称必须是唯一的。All cursor names within the connection must be unique. 游标名称的最大长度由驱动程序定义。The maximum length of a cursor name is defined by the driver. 为实现最大互操作性,建议应用程序将游标名称限制为不超过18个字符。For maximum interoperability, it is recommended that applications limit cursor names to no more than 18 characters. 在 ODBC 1.x中,如果游标名称是带引号的标识符,则会以区分大小写的方式对其进行处理,并且它可以包含 SQL 语法不允许或将要处理的字符,例如空格或保留关键字。In ODBC 3 .x, if a cursor name is a quoted identifier, it is treated in a case-sensitive manner and it can contain characters that the syntax of SQL would not permit or would treat specially, such as blanks or reserved keywords. 如果游标名称必须以区分大小写的方式进行处理,则必须将其作为带引号的标识符传递。If a cursor name must be treated in a case-sensitive manner, it must be passed as a quoted identifier.

显式或隐式设置的游标名称会在删除与之关联的语句后,使用SQLFreeHandleA cursor name that is set either explicitly or implicitly remains set until the statement with which it is associated is dropped, using SQLFreeHandle. 可以调用SQLSetCursorName来重命名语句上的游标,只要游标处于已分配或准备好的状态。SQLSetCursorName can be called to rename a cursor on a statement as long as the cursor is in an allocated or prepared state.

代码示例Code Example

在下面的示例中,应用程序使用SQLSetCursorName设置语句的游标名称。In the following example, an application uses SQLSetCursorName to set a cursor name for a statement. 然后,它使用该语句来检索 CUSTOMERS 表中的结果。It then uses that statement to retrieve results from the CUSTOMERS table. 最后,它将执行定位更新以更改 John Smith 的电话号码。Finally, it performs a positioned update to change the phone number of John Smith. 请注意,应用程序对SELECTUPDATE语句使用不同的语句句柄。Note that the application uses different statement handles for the SELECT and UPDATE statements.

有关其他代码示例,请参阅SQLSetPosFor another code example, see 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);  
}  
有关以下方面的信息For information about 请参阅See
执行 SQL 语句Executing an SQL statement SQLExecDirect 函数SQLExecDirect Function
执行已准备的 SQL 语句Executing a prepared SQL statement SQLExecute 函数SQLExecute Function
返回游标名称Returning a cursor name SQLGetCursorName 函数SQLGetCursorName Function
设置游标滚动选项Setting cursor scrolling options SQLSetScrollOptions 函数SQLSetScrollOptions Function

另请参阅See Also

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