DB2 Version 9.7 for Linux, UNIX, and Windows

SQLGetCursorName function (CLI) - Get cursor name

Purpose

Specification:

CLI 1.1

ODBC 1.0

ISO CLI

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

Unicode Equivalent: This function can also be used with the Unicode character set. The corresponding Unicode function is SQLGetCursorNameW(). Refer to Unicode functions (CLI) for information on 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 on 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);