SQLGetCursorName - Get cursor name
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 internally generated name is
returned.
Internally generated cursor names are always 18 bytes in length.
Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. The corresponding Unicode function is SQLGetCursorNameW(). Refer to Unicode in Db2 for i CLI for more information about Unicode support for DB2® CLI.
Syntax
SQLRETURN SQLGetCursorName (SQLHSTMT hstmt,
SQLCHAR *szCursor,
SQLSMALLINT cbCursorMax,
SQLSMALLINT *pcbCursor);
Function arguments
Data type | Argument | Use | Description |
---|---|---|---|
SQLHSTMT | hstmt | Input | Statement handle |
SQLCHAR * | szCursor | Output | Cursor name |
SQLSMALLINT | cbCursorMax | Input | Length of buffer szCursor |
SQLSMALLINT * | pcbCursor | Output | Amount of bytes available to return for szCursor |
Usage
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.
The generated cursor names of ODBC start with SQL_CUR and X/Open CLI generated cursor names begin with SQLCUR. Db2 for i CLI uses SQLCUR.
Return codes
- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
- SQL_ERROR
- SQL_INVALID_HANDLE
Diagnostics
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. |
Example
check_error,
initialize, and terminate
functions used in the following
example. /*************************************************************************
** 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 */