SQLGetCursorName function (CLI) - Get cursor name

Returns the cursor name associated with the input statement handle. If a cursor name was explicitly set by calling SQLSetCursorName(), this name will be returned; otherwise, an implicitly generated name will be returned.

Specification:

  • CLI 1.1
  • ODBC 1.0
  • ISO CLI
Unicode Equivalent: This function can also be used with the Unicode character set. The corresponding Unicode function is SQLGetCursorNameW(). See Unicode functions (CLI) for information about ANSI to Unicode function mappings.

Syntax

SQLRETURN   SQLGetCursorName (
               SQLHSTMT          StatementHandle,  /* hstmt */
               SQLCHAR           *CursorName,      /* szCursor */
               SQLSMALLINT       BufferLength,     /* cbCursorMax */
               SQLSMALLINT       *NameLengthPtr);  /* pcbCursor */

Function arguments

Table 1. SQLGetCursorName arguments
Data type Argument Use Description
SQLHSTMT StatementHandle input Statement handle
SQLCHAR * CursorName output Cursor name
SQLSMALLINT BufferLength input Number of SQLCHAR elements (or SQLWCHAR elements for the Unicode variant of this function) needed to store CursorName.
SQLSMALLINT * NameLengthPtr output Number of SQLCHAR elements (or SQLWCHAR elements for the Unicode variant of this function), excluding the null-termination character, available to return for CursorName.

Usage

SQLGetCursorName() will return the cursor name set explicitly with SQLSetCursorName(), or if no name was set, it will return the cursor name internally generated by CLI. If SQLGetCursorName() is called before a statement has been prepared on the input statement handle, an error will result. The internal cursor name is generated on a statement handle the first time dynamic SQL is prepared on the statement handle, not when the handle is allocated.

If a name is set explicitly using SQLSetCursorName(), this name will be returned 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 128 SQLCHAR or SQLWCHAR elements or less, and are always unique within a connection.

Return codes

  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_ERROR
  • SQL_INVALID_HANDLE

Diagnostics

Table 2. SQLGetCursorName SQLSTATEs
SQLSTATE Description Explanation
01004 Data truncated. The cursor name returned in CursorName was 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. It is likely that process-level memory has been exhausted for the application process. Consult the operating system configuration for information about process-level memory limitations.
HY010 Function sequence error.

The function was called while in a data-at-execute (SQLParamData(), SQLPutData()) operation.

The function was called while within a BEGIN COMPOUND and END COMPOUND SQL operation.

An asynchronously executing function (not this one) was called For the StatementHandle and was still executing when this function was called.

The function was called before a statement was prepared on the statement handle.
HY013 Unexpected memory handling error. Db2 CLI was 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

ODBC generated cursor names start with SQL_CUR, CLI generated cursor names start with SQLCUR, and X/Open CLI generated cursor names begin with either SQLCUR or SQL_CUR.

Example

  SQLCHAR cursorName[20];

  /* ... */
  
  /* get the cursor name of the SELECT statement */
  cliRC = SQLGetCursorName(hstmtSelect, cursorName, 20, &cursorLen);