| Specification: | DB2 CLI 1.1 | ODBC 1.0 | ISO CLI |
SQLGetCursorName() returns the cursor name associated with the input statement handle. If a cursor name is explicitly set by calling SQLSetCursorName(), this name returns; otherwise, an implicitly generated name returns.
Syntax
SQLRETURN SQLGetCursorName (
SQLHSTMT StatementHandle, /* hstmt */
SQLCHAR *FAR CursorName, /* szCursor */
SQLSMALLINT BufferLength, /* cbCursorMax */
SQLSMALLINT *FAR NameLengthPtr); /* pcbCursor */
Function arguments
Table 64. SQLGetCursorName Arguments
| Data type | Argument | Use | Description |
|---|---|---|---|
| SQLHSTMT | StatementHandle | input | Statement handle |
| SQLCHAR * | CursorName | output | Cursor name |
| SQLSMALLINT | BufferLength | input | Length of buffer CursorName |
| SQLSMALLINT * | NameLengthPtr | output | Number of bytes available to return for CursorName |
Usage
SQLGetCursorName() returns the cursor name set explicitly with SQLSetCursorName(), or if no name is set, it returns the cursor name internally generated by DB2 CLI.
If a name is set explicitly using SQLSetCursorName(), this name returns until the statement is dropped, or until another explicit name is set.
Internally generated cursor names always begin with SQLCUR or SQL_CUR. Cursor names are always 18 characters or less and are always unique within a connection.
Return codes
Diagnostics
Table 65. SQLGetCursorName SQLSTATEs
| SQLSTATE | Description | Explanation |
|---|---|---|
| 01004 | Data truncated. | The cursor name returned in CursorName is longer than the value in BufferLength, and is truncated to BufferLength - 1 bytes. The argument NameLengthPtr contains the length of the full cursor name available for return. The function returns SQL_SUCCESS_WITH_INFO. |
| 40003 08S01 | Communication link failure. | The communication link between the application and data source failed before the function completed. |
| 58004 | Unexpected system failure. | Unrecoverable system error. |
| HY001 | Memory allocation failure. | DB2 CLI is unable to allocate memory required to support execution or completion of the function. |
| HY010 | Function sequence error. |
The function is called while in a data-at-execute
(SQLParamData(), SQLPutData()) operation.
|
| HY013 | Unexpected memory handling error. | DB2 CLI is unable to access memory required to support execution or completion of the function. |
| HY090 | Invalid string or buffer length. | The value specified for the argument BufferLength is less than 0. |
Restrictions
None.
Related reference