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.
SQLSetCursorNameW()
. Refer to Unicode in Db2 for i CLI for more information about Unicode
support for Db2 for
i CLI.Syntax
SQLRETURN SQLSetCursorName (SQLHSTMT hstmt,
SQLCHAR *szCursor,
SQLSMALLINT cbCursor);
Function 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
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.
|
HY013 * | Memory management problem | The driver is unable to access memory required to support the processing or completion of the function. |