16.7.4 SQLSetCursorName, SQLSetCursorNameW : Hitachi Advanced Database Application Development Guide

(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.

To Page Top

(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 */
)

To Page Top

(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.

To Page Top

(4) Return value

This ODBC function returns SQL_SUCCESS, SQL_ERROR, or SQL_INVALID_HANDLE.

To Page Top

(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	The size of the cursor name is greater than the maximum size (30 bytes) supported by the HADB ODBC driver. The cursor name specified in `CursorName` begins with `SQL_CUR`.	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

To Page Top

(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.

To Page Top