Call Level Interface Guide and Reference

SQLSetCursorName - Set Cursor Name

Purpose

Specification:

DB2 CLI 1.1

ODBC 1.0

ISO CLI

SQLSetCursorName() associates a cursor name with the statement handle. This function is optional since DB2 CLI implicitly generates a cursor name when each statement handle is allocated.

Syntax

SQLRETURN   SQLSetCursorName (SQLHSTMT          StatementHandle,
                              SQLCHAR      FAR  *CursorName,
                              SQLSMALLINT       NameLength);

Function Arguments

Table 154. SQLSetCursorName Arguments

Data Type	Argument	Use	Description
SQLHSTMT	StatementHandle	input	Statement handle
SQLCHAR *	CursorName	input	Cursor name
SQLSMALLINT	NameLength	input	Length of contents of CursorName argument

Usage

DB2 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). DB2 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, we recommend that you do not use SQLSetCursorName(), 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 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.)
• 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 above (such as National Language Set or Double Bytes Character Set characters), the application must enclose the cursor name in double quotes (").
• Unless the input cursor name is enclosed in double quotes, 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 quote as the first character in the CursorName buffer.

Return Codes

• SQL_SUCCESS
• SQL_SUCCESS_WITH_INFO
• SQL_ERROR
• SQL_INVALID_HANDLE

Diagnostics

Table 155. 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.
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.
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.

CLI Sample tbmod.c

(The complete sample tbmod.c is also available here .)

 
/* From the CLI sample TBMOD.C */
/* ... */
 
    /* set the name of the cursor */    
    rc = SQLSetCursorName(hstmtSelect, (SQLCHAR *)"CURSNAME", SQL_NTS);
    STMT_HANDLE_CHECK( hstmtSelect, sqlrc);
    
 

References

• SQLGetCursorName - Get Cursor Name