SQLSetCursorName function (CLI) - Set cursor name

Associates a cursor name with the statement handle. This function is optional because CLI implicitly generates a cursor name. The implicit cursor name is available after the dynamic SQL has been prepared on the statement handle.

Specification:

  • CLI 1.1
  • ODBC 1.0
  • ISO CLI
Unicode equivalent: This function can also be used with the Unicode character set. The corresponding Unicode function is SQLSetCursorNameW(). See Unicode functions (CLI) for information about ANSI to Unicode function mappings.

Syntax

SQLRETURN   SQLSetCursorName (
               SQLHSTMT          StatementHandle,  /* hstmt */
               SQLCHAR           *CursorName,      /* szCursor */
               SQLSMALLINT       NameLength);      /* cbCursor */

Function arguments

Table 1. SQLSetCursorName arguments
Data type Argument Use Description
SQLHSTMT StatementHandle input Statement handle
SQLCHAR * CursorName input Cursor name
SQLSMALLINT NameLength input Number of SQLCHAR elements (or SQLWCHAR elements for the Unicode variant of this function) needed to store the CursorName argument.

Usage

CLI always generates and uses an internally generated cursor name when a query is prepared or executed directly. SQLSetCursorName() allows an application-defined cursor name to be used in an SQL statement (a positioned UPDATE or DELETE). CLI maps this name to the internal name. The name will remain associated with the statement handle, until the handle is dropped, or another SQLSetCursorName() is called on this statement handle.

Although SQLGetCursorName() will return the name set by the application (if one was set), error messages associated with positioned UPDATE and DELETE statements will refer to the internal name. For this reason, do not use SQLSetCursorName() for positioned UPDATEs and DELETEs, but instead use the internal name which can be obtained by calling SQLGetCursorName().

Cursor names must follow these rules:
  • All cursor names within the connection must be unique.
  • Each cursor name must be less than or equal to 128 bytes in length. Any attempt to set a cursor name longer than 128 bytes results in truncation of that cursor name to 128 bytes. (No warning is generated.)
  • Since internally generated names begin with SQLCUR or SQL_CUR, the application must not input a cursor name starting with either SQLCUR or SQL_CUR in order to avoid conflicts with internal names.
  • Since 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 (_).
  • To permit cursor names containing characters other than those listed (such as National Language Set or Double Bytes Character Set characters), the application must enclose the cursor name in double quotation marks (").
  • Unless the input cursor name is enclosed in double quotation marks, all leading and trailing blanks from the input cursor name string will be removed.

For efficient processing, applications should not include any leading or trailing spaces in the CursorName buffer. If the CursorName buffer contains a delimited identifier, applications should position the first double quotation marks as the first character in the CursorName buffer.

Return codes

  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_ERROR
  • SQL_INVALID_HANDLE

Diagnostics

Table 2. SQLSetCursorName SQLSTATEs
SQLSTATE Description Explanation
34000 Invalid cursor name. The cursor name specified by the argument CursorName was invalid. The cursor name either begins with "SQLCUR" or "SQL_CUR" or violates the 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 CursorName already exists.

The cursor name length is greater than the value returned by SQLGetInfo() with the SQL_MAX_CURSOR_NAME_LEN argument.
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 about process-level memory limitations.
HY009 Invalid argument value. CursorName was a null pointer.
HY010 Function sequence error. There is an open or positioned cursor on the statement handle.

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 argument NameLength was less than 0, but not equal to SQL_NTS.

Authorization

None.

Example

  /* set the name of the cursor */
  rc = SQLSetCursorName(hstmtSelect, (SQLCHAR *)"CURSNAME", SQL_NTS);