16.7.4 SQLSetCursorName, SQLSetCursorNameW
- Organization of this subsection
(1) Function
This ODBC function assigns a cursor name to an active statement handle. If an application does not call this function, the HADB ODBC driver generates cursor names.
(2) Format
-
For SQLSetCursorName
SQLRETURN SQLSetCursorName ( SQLHSTMT StatementHandle, /* In */ SQLCHAR * CursorName, /* In */ SQLSMALLINT NameLength /* In */ )
-
For SQLSetCursorNameW
SQLRETURN SQLSetCursorName ( SQLHSTMT StatementHandle, /* In */ SQLWCHAR * CursorName, /* In */ SQLSMALLINT NameLength /* In */ )
(3) Arguments
- StatementHandle
-
Specifies a statement handle.
- CursorName
-
Specifies a cursor name to be associated.
- NameLength
-
Specifies the length of *CursorName (in bytes for SQLSetCursorName and in characters for SQLSetCursorNameW).
If the character string specified in CursorName guarantees a null terminating character, SQL_NTS can be specified in this argument.
(4) Return value
This ODBC function returns SQL_SUCCESS, SQL_ERROR, or SQL_INVALID_HANDLE.
(5) SQLSTATE
This ODBC function returns one of the following SQLSTATE values:
SQLSTATE |
Description |
Remarks |
Returned |
---|---|---|---|
01000 |
General warning |
-- |
N |
01004 |
Character string data was right-truncated |
N |
|
24000 |
Invalid cursor status |
The statement associated with StatementHandle has already executed or is engaged in cursor positioning. |
Y |
34000 |
Invalid cursor name |
|
Y |
3C000 |
Duplicate cursor name |
The cursor name specified in *CursorName already exists. |
Y |
5C002 |
Character encoding conversion error |
A character code that cannot be converted was detected. |
Y |
HY000 |
General error |
-- |
N |
HY001 |
Memory allocation error |
N |
|
HY009 |
Invalid use of null pointer |
CursorName is a null pointer. |
Y |
HY010 |
Function sequence error |
-- |
Y |
HY013 |
Memory management error |
The function call could not be processed because the memory object could not be accessed. |
N |
HY090 |
Invalid string or buffer length |
The value specified in NameLength is less than or equal to 0, or not SQL_NTS. |
Y |
HYT01 |
Connection timeout expired |
A connection timeout occurred before the data source responded to the request. The connection timeout value can be specified by using SQL_ATTR_CONNECTION_TIMEOUT in SQLSetConnectAttr or SQLSetConnectAttrW. |
N |
IM001 |
Driver does not support this function |
-- |
N |
- Legend:
-
Y: This SQLSTATE might be returned by the HADB ODBC driver.
N: This SQLSTATE is not returned by the HADB ODBC driver.
--: None
(6) Notes
Use the cursor library provided by Microsoft if you intend to use the cursor name set by this function. If the cursor library provided by Microsoft is not used, the HADB ODBC driver ignores the set cursor name.