`SQLSetCursorName()` - Set cursor name

SQLSetCursorName() associates a cursor name with the statement handle. This function is optional because Db2 ODBC implicitly generates a cursor name when each statement handle is allocated.

ODBC specifications for `SQLSetCursorName()`

Table 1. `SQLSetCursorName()` specifications
ODBC specification level	In X/Open CLI CAE specification?	In ISO CLI specification?
1.0	Yes	Yes

Syntax

SQLRETURN   SQLSetCursorName (SQLHSTMT          hstmt,
                              SQLCHAR     FAR   *szCursor,
                              SQLSMALLINT       cbCursor);

Function arguments

The following table lists the data type, use, and description for each argument in this function.

Table 2. `SQLSetCursorName()` arguments
Data type	Argument	Use	Description
SQLHSTMT	hstmt	input	Statement handle
SQLCHAR *	szCursor	input	Cursor name
SQLSMALLINT	cbCursor	input	The length, in bytes, of contents of szCursor argument

Usage

Db2 ODBC 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 ODBC maps this name to the internal name. The name remains associated with the statement handle, until the handle is dropped, or another SQLSetCursorName() is called on this statement handle.

Although SQLGetCursorName() returns the name set by the application (if one is set), error messages that are associated with positioned UPDATE and DELETE statements refer to the internal name.

Recommendation: Do not use SQLSetCursorName(). Instead, use the internal name, which you can obtain 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.)
Because internally generated names begin with SQLCUR, SQL_CUR, or SQLCURQRS, the application must not input a cursor name starting with either SQLCUR or SQL_CUR in order to avoid conflicts with internal names.
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 (_).
To permit cursor names containing characters other than those listed above (such as National Language Set or Double-Byte 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 are removed.

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

Return codes

After you call SQLSetCursorName(), it returns one of the following values:

SQL_SUCCESS
SQL_ERROR
SQL_INVALID_HANDLE

Diagnostics

The following table lists each SQLSTATE that this function generates, with a description and explanation for each value.

Table 3. `SQLSetCursorName()` SQLSTATEs
SQLSTATE	Description	Explanation
08S01	Communication link failure.	The communication link between the application and data source fails before the function completes.
34000	Invalid cursor name.	This SQLSTATE is returned for one or more of the following reasons: The cursor name specified by the argument szCursor is invalid. The cursor name either begins with SQLCUR, SQL_CUR, or SQLCURQRS 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 szCursor already exists. The cursor name length is greater than the value returned by `SQLGetInfo()` with the SQL_MAX_CURSOR_NAME_LEN argument.
58004	Unexpected system failure.	Unrecoverable system error.
HY001	Memory allocation failure.	Db2 ODBC is not able to allocate the required memory to support the execution or the completion of the function.
HY009	Invalid use of a null pointer.	szCursor is a null pointer.
HY010	Function sequence error.	This SQLSTATE is returned for one or more of the following reasons: There is an open or positioned cursor on the statement handle. The function is called during a data-at-execute operation. (That is, the function is called during a procedure that uses the `SQLParamData()` or `SQLPutData()` functions.)
HY013	Unexpected memory handling error.	Db2 ODBC is not able to access the memory that is required to support execution or completion of the function.
HY090	Invalid string or buffer length.	The argument cbCursor is less than 0, but not equal to SQL_NTS.

Example

The following example shows an application that uses SQLSetCursorName() to set a cursor name.

Figure 1. An application that sets a cursor name

/* ... */
    SQLCHAR         sqlstmt[] =
                    "SELECT name, job FROM staff "
                    "WHERE job='Clerk'  FOR UPDATE OF job";
/* ... */
    /* Allocate second statement handle for update statement */
    rc2 = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt2);
    /* Set Cursor for the SELECT statement handle */
    rc = SQLSetCursorName(hstmt1, "JOBCURS", SQL_NTS);
    rc = SQLExecDirect(hstmt1, sqlstmt, SQL_NTS);
    /* bind name to first column in the result set */
    rc = SQLBindCol(hstmt1, 1, SQL_C_CHAR, (SQLPOINTER) name.s, 10,
                    &name.ind);
    /* bind job to second column in the result set */
    rc = SQLBindCol(hstmt1, 2, SQL_C_CHAR, (SQLPOINTER) job.s, 6,
                    &job.ind);
    printf("Job change for all clerks\n");
    while ((rc = SQLFetch(hstmt1)) == SQL_SUCCESS) {
        printf("Name: %-9.9s Job: %-5.5s \n", name.s, job.s);
        printf("Enter new job or return to continue\n");
        gets(newjob);
        if (newjob[0] != '\0') {
            sprintf(updstmt,
                    "UPDATE staff set job = '%s' where current of JOBCURS",
                    newjob);
            rc2 = SQLExecDirect(hstmt2, updstmt, SQL_NTS);
        }
    }
    if (rc != SQL_NO_DATA_FOUND)
        check_error(henv, hdbc, hstmt1, rc, __LINE__, __FILE__);
/* ... */

SQLSetCursorName() - Set cursor name

ODBC specifications for SQLSetCursorName()