Call Level Interface Guide and Reference

SQLGetCursorName - Get Cursor Name

Purpose

Specification: DB2 CLI 1.1 ODBC 1.0 ISO CLI

SQLGetCursorName() returns the cursor name associated with the input statement handle. If a cursor name was explicitly set by calling SQLSetCursorName(), this name will be returned; otherwise, an implicitly generated name will be returned.

Syntax

SQLRETURN   SQLGetCursorName (
                SQLHSTMT          StatementHandle,   /* hstmt */
                SQLCHAR      *FAR CursorName,        /* szCursor */
                SQLSMALLINT       BufferLength,      /* cbCursorMax */
                SQLSMALLINT  *FAR NameLengthPtr);    /* pcbCursor */

Function Arguments

Table 92. SQLGetCursorName Arguments

Data Type Argument Use Description
SQLHSTMT StatementHandle input Statement handle
SQLCHAR * CursorName output Cursor name
SQLSMALLINT BufferLength input Length of buffer CursorName
SQLSMALLINT * NameLengthPtr output Number of bytes available to return for CursorName

Data Type	Argument	Use	Description
SQLHSTMT	`StatementHandle`	input	Statement handle
SQLCHAR *	`CursorName`	output	Cursor name
SQLSMALLINT	`BufferLength`	input	Length of buffer `CursorName`
SQLSMALLINT *	`NameLengthPtr`	output	Number of bytes available to return for `CursorName`

Usage

SQLGetCursorName() will return the cursor name set explicitly with SQLSetCursorName(), or if no name was set, it will return the cursor name internally generated by DB2 CLI.

If a name is set explicitly using SQLSetCursorName(), this name will be returned until the statement is dropped, or until another explicit name is set.

Internally generated cursor names always begin with SQLCUR or SQL_CUR. Cursor names are always 18 characters or less, and are always unique within a connection.

Return Codes

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

Diagnostics

Table 93. SQLGetCursorName SQLSTATEs

SQLSTATE Description Explanation
01004 Data truncated. The cursor name returned in CursorName was longer than the value in BufferLength, and is truncated to BufferLength - 1 bytes. The argument NameLengthPtr contains the length of the full cursor name available for return. The function returns SQL_SUCCESS_WITH_INFO.
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.
HY010 Function sequence error.
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 value specified for the argument BufferLength is less than 0.

SQLSTATE	Description	Explanation
01004	Data truncated.	The cursor name returned in `CursorName` was longer than the value in `BufferLength`, and is truncated to `BufferLength` - 1 bytes. The argument `NameLengthPtr` contains the length of the full cursor name available for return. The function returns SQL_SUCCESS_WITH_INFO.
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.
HY010	Function sequence error.	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 value specified for the argument `BufferLength` is less than 0.

Restrictions

ODBC generated cursor names start with SQL_CUR, DB2 CLI generated cursor names start with SQLCUR, and X/Open CLI generated cursor names begin with either SQLCUR or SQL_CUR.

CLI Sample tbmod.c

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

 
/* From the CLI sample TBMOD.C */
/* ... */
 
    /* get the cursor name of the SELECT statement */
    sqlrc = SQLGetCursorName( hstmtSelect, 
                              cursorName, 20, &cursorLen ) ;

References

[ Top of Page | Previous Page | Next Page ]