SQLGetCursorName() returns the cursor name associated with the input statement handle. If a cursor name is explicitly set by calling SQLSetCursorName(), this name is returned; otherwise, an implicitly generated name is returned.
SQLRETURN SQLGetCursorName (SQLHSTMT hstmt,
SQLCHAR *szCursor,
SQLSMALLINT cbCursorMax,
SQLSMALLINT *pcbCursor);
| Data type | Argument | Use | Description |
|---|---|---|---|
| SQLCHAR * | szCursor | Output | Cursor name |
| SQLHSTMT | hstmt | Input | Statement handle |
| SQLSMALLINT * | pcbCursor | Output | Amount of bytes available to return for szCursor |
| SQLSMALLINT | cbCursorMax | Input | Length of buffer szCursor |
SQLGetCursorName() returns a cursor name if a name is set using SQLSetCursorName() or if a SELECT statement is processed on the statement handle. If neither of these is true, then calling SQLGetCusorName() results in an error.
If a name is set explicitly using SQLSetCursorName(), this name is returned until the statement is dropped, or until another explicit name is set.
If an explicit name is not set, an implicit name is generated when a SELECT statement is processed, and this name is returned. Implicit cursor names always begin with SQLCUR.
| SQLSTATE | Description | Explanation |
|---|---|---|
| 01004 | Data truncated | The cursor name returned in szCursor is longer than the value in cbCursorMax, and is truncated to cbCursorMax - 1 bytes. The argument pcbCursor contains the length of the full cursor name available for return. The function returns SQL_SUCCESS_WITH_INFO. |
| 40003 * | Statement completion unknown | The communication link between the CLI and the data source fails before the function completes processing. |
| 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 | The argument szCursor or pcbCursor is
a null pointer. The value specified for the argument cbCursorMax is less than 1. |
| HY010 | Function sequence error | The statement hstmt is not in execute state. Call SQLExecute(), SQLExecDirect() or SQLSetCursorName() before calling SQLGetCursorName(). |
| HY013 * | Memory management problem | The driver is unable to access memory required to support the processing or completion of the function. |
| HY015 | No cursor name available. | There is no open cursor on the hstmt and no cursor name has been set with SQLSetCursorName(). The statement associated with hstmt does not support the use of a cursor. |
ODBC's generated cursor names start with SQL_CUR and X/Open CLI generated cursor names begin with SQLCUR. DB2® UDB CLI uses SQLCUR.
/*************************************************************************
** file = getcurs.c
**
** Example of directly executing a SELECT and positioned UPDATE SQL statement.
** Two statement handles are used, and SQLGetCursor is used to retrieve the
** generated cursor name.
**
** Functions used:
**
** SQLAllocConnect SQLFreeConnect
** SQLAllocEnv SQLFreeEnv
** SQLAllocStmt SQLFreeStmt
** SQLConnect SQLDisconnect
**
** SQLBindCol SQLFetch
** SQLTransact SQLError
** SQLExecDirect SQLGetCursorName
**************************************************************************/
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include "sqlcli.h"
#define MAX_STMT_LEN 255
int initialize(SQLHENV *henv,
SQLHDBC *hdbc);
int terminate(SQLHENV henv,
SQLHDBC hdbc);
int print_error (SQLHENV henv,
SQLHDBC hdbc,
SQLHSTMT hstmt);
int check_error (SQLHENV henv,
SQLHDBC hdbc,
SQLHSTMT hstmt,
SQLRETURN frc);
/*******************************************************************
** main
** - initialize
** - terminate
*******************************************************************/
int main()
{
SQLHENV henv;
SQLHDBC hdbc;
SQLRETURN rc,
rc2;
rc = initialize(&henv, &hdbc);
if (rc != SQL_SUCCESS) return(terminate(henv, hdbc));
{SQLHSTMT hstmt1,
hstmt2;
SQLCHAR sqlstmt[]="SELECT name, job from staff for update of job";
SQLCHAR updstmt[MAX_STMT_LEN + 1];
SQLCHAR name[10],
job[6],
newjob[6],
cursor[19];
SQLINTEGER rlength, attr;
SQLSMALLINT clength;
rc = SQLAllocStmt(hdbc, &hstmt1);
if (rc != SQL_SUCCESS )
check_error (henv, hdbc, SQL_NULL_HSTMT, rc);
/* make sure the statement is update-capable */
attr = SQL_FALSE;
rc = SQLSetStmtAttr(hstmt1,SQL_ATTR_FOR_FETCH_ONLY, &attr, 0);
/* allocate second statement handle for update statement */
rc2 = SQLAllocStmt(hdbc, &hstmt2);
if (rc2 != SQL_SUCCESS )
check_error (henv, hdbc, SQL_NULL_HSTMT, rc);
rc = SQLExecDirect(hstmt1, sqlstmt, SQL_NTS);
if (rc != SQL_SUCCESS )
check_error (henv, hdbc, hstmt1, rc);
/* Get Cursor of the SELECT statement's handle */
rc = SQLGetCursorName(hstmt1, cursor, 19, &clength);
if (rc != SQL_SUCCESS )
check_error (henv, hdbc, hstmt1, rc);
/* bind name to first column in the result set */
rc = SQLBindCol(hstmt1, 1, SQL_CHAR, (SQLPOINTER) name, 10,
&rlength);
if (rc != SQL_SUCCESS )
check_error (henv, hdbc, hstmt1, rc);
/* bind job to second column in the result set */
rc = SQLBindCol(hstmt1, 2, SQL_CHAR, (SQLPOINTER) job, 6,
&rlength);
if (rc != SQL_SUCCESS )
check_error (henv, hdbc, hstmt1, rc);
printf("Job Change for all clerks\n");
while ((rc = SQLFetch(hstmt1)) == SQL_SUCCESS)
{
printf("Name: %-9.9s Job: %-5.5s \n", name, job);
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 %s",
newjob, cursor);
rc2 = SQLExecDirect(hstmt2, updstmt, SQL_NTS);
if (rc2 != SQL_SUCCESS )
check_error (henv, hdbc, hstmt2, rc);
}
}
if (rc != SQL_NO_DATA_FOUND )
check_error (henv, hdbc, hstmt1, rc);
SQLFreeStmt(hstmt1, SQL_CLOSE);
}
printf("Commiting Transaction\n");
rc = SQLTransact(henv, hdbc, SQL_COMMIT);
if (rc != SQL_NO_DATA_FOUND )
check_error (henv, hdbc, SQL_NULL_HSTMT, rc);
terminate(henv, hdbc);
return (0);
}/* end main */