SQLSetCursorName - Set cursor name

Purpose

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
SQLCHAR * szCursor Input Cursor name.
SQLHSTMT hstmt Input Statement handle.
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 truncation of that cursor name to 18 bytes. (No warning is generated.)
  • 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

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

Parent topic: DB2 UDB CLI functions