16.7.3 SQLGetCursorName, SQLGetCursorNameW : Hitachi Advanced Database Application Development Guide

(1) Function

This ODBC function returns the cursor name associated with a specified statement handle.

(2) Format

For SQLGetCursorName

SQLRETURN SQLGetCursorName
(
  SQLHSTMT         StatementHandle,        /* In */
  SQLCHAR        * CursorName,             /* Out */
  SQLSMALLINT      BufferLength,           /* In */
  SQLSMALLINT    * NameLengthPtr           /* Out */
)

For SQLGetCursorNameW

SQLRETURN SQLGetCursorNameW
(
  SQLHSTMT         StatementHandle,        /* In */
  SQLWCHAR       * CursorName,             /* Out */
  SQLSMALLINT      BufferLength,           /* In */
  SQLSMALLINT    * NameLengthPtr           /* Out */
)

To Page Top

(3) Arguments

StatementHandle: Specifies a statement handle.
CursorName: Specifies a pointer to the buffer in which the cursor name is to be returned.
BufferLength: Specifies the length^# of *CursorName. SQL_NTS cannot be specified.
NameLengthPtr: Specifies a pointer to the buffer that stores the total valid length^# that is returned to *CursorName. This length does not include the null terminating character.
#: The length must be in bytes for SQLGetCursorName and in characters for SQLGetCursorNameW.

To Page Top

(4) Return value

This ODBC function returns SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, 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	The cursor name could not be stored because the `*CursorName` buffer was too small (the cursor name was truncated). The function returns `SQL_SUCCESS_WITH_INFO`.	Y
`01S51`	Code replacement occurred during conversion of character encoding	A character code that cannot be converted was detected and then replaced with the specified character. The function returns `SQL_SUCCESS_WITH_INFO`.	Y
`HY000`	General error	--	N
`HY001`	Memory allocation error		N
`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
`HY015`	No cursor name available	--	N
`HY090`	Invalid string or buffer length	The value specified in `BufferLength` is less than `0`. An invalid value (`SQL_NTS`) was specified in `BufferLength`.	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

If the SQLSetCursorName function or SQLSetCursorNameW function has not been used and no explicit cursor name has been set, this function returns the cursor name that is generated automatically by the HADB ODBC driver, which is SQL_CURXXXXX (where XXXXX is a sequential number beginning with 00001).
Use the cursor library provided by Microsoft if you intend to use the cursor name obtained by this function. If the cursor library provided by Microsoft is not used, the HADB ODBC driver ignores the cursor name associated with a statement handle.

To Page Top