SQLSetCursorName - Set cursor name

SQLSetCursorName() associates a cursor name with the statement handle. This function is optional because DB2® for i CLI implicitly generates a cursor name when needed.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. The corresponding Unicode function is SQLSetCursorNameW(). Refer to Unicode in DB2 for iCLI for more information about Unicode support for DB2 for i CLI.

Syntax

SQLRETURN SQLSetCursorName (SQLHSTMT       hstmt,
                            SQLCHAR        *szCursor,
                            SQLSMALLINT    cbCursor);

Function arguments

Table 1. SQLSetCursorName arguments
Data type	Argument	Use	Description
SQLHSTMT	hstmt	Input	Statement handle.
SQLCHAR *	szCursor	Input	Cursor name.
SQLSMALLINT	cbCursor	Input	Length of contents of szCursor argument.

Usage

DB2 for i CLI always generates and uses an internally generated cursor name when a SELECT statement is prepared or executed directly. SQLSetCursorName() allows an application-defined cursor name to be used in an SQL statement (a Positioned UPDATE or DELETE). DB2 for i CLI maps this name to an internal name. SQLSetCursorName() must be called before an internal name is generated. The name remains associated with the statement handle, until the handle is dropped. The name also remains after the transaction has ended, but at this point SQLSetCursorName() can be called to set a different name for this statement handle.

Cursor names must follow the following rules:

All cursor names within the connection must be unique.
Each cursor name must be less than or equal to 128 characters in length. Any attempt to set a cursor name longer than 128 characters results in an SQL0504 error.
Because a cursor name is considered an identifier in SQL, it must begin with an English letter (a-z, A-Z) followed by any combination of digits (0-9), English letters or the underscore character (_).
Unless the input cursor name is enclosed in double quotation marks, all leading and trailing blanks from the input cursor name string are removed.

Return codes

SQL_SUCCESS
SQL_ERROR
SQL_INVALID_HANDLE

Diagnostics

Table 2. SQLSetCursorName SQLSTATEs
SQLSTATE	Description	Explanation
34000	Cursor name that is not valid	The cursor name specified by the argument szCursor is not valid. The cursor name either begins with "SQLCUR" or "SQL_CUR" or violates either the driver or the data source cursor naming rules (Must begin with a-z or A-Z followed by any combination of English letters, digits, or the '_' character. The cursor name specified by the argument szCursor exists.
58004	System error	Unrecoverable system error.
HY001	Memory allocation failure	The driver is unable to allocate memory required to support the processing or completion of the function.
HY009	Argument value that is not valid	szCursor is a null pointer. The argument cbCursor is less than 1, but not equal to SQL_NTS.
HY010	Function sequence error	The statement handle is not in allocated state. `SQLPrepare()` or `SQLExecDirect()` is called before `SQLSetCursorName()`.
HY013 *	Memory management problem	The driver is unable to access memory required to support the processing or completion of the function.

References

SQLGetCursorName - Get cursor name