SQLSetCursorName - Set cursor name

 

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

 

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 UDB CLI always generates and uses an internally generated cursor name when a SELECT statement is prepared or processed directly. SQLSetCursorName() allows an application-defined cursor name to be used in an SQL statement (a Positioned UPDATE or DELETE). DB2 UDB 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 18 bytes in length. Any attempt to set a cursor name longer than 18 bytes 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 is 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

 

Parent topic:

DB2 UDB CLI functions