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 implicitly generated name is returned.

 

Syntax

SQLRETURN SQLGetCursorName (SQLHSTMT       hstmt,
                            SQLCHAR        *szCursor,
                            SQLSMALLINT    cbCursorMax,
                            SQLSMALLINT    *pcbCursor);

 

Function arguments

Table 1. SQLGetCursorName 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.

 

Return codes

 

Diagnostics

Table 2. SQLGetCursorName SQLSTATEs
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.

 

Restrictions

ODBC's generated cursor names start with SQL_CUR and X/Open CLI generated cursor names begin with SQLCUR. DB2® UDB CLI uses SQLCUR.

 

Example

Refer to Example: Interactive SQL and the equivalent DB2 UDB CLI function calls for a listing of the check_error, initialize, and terminate functions used in the following example.

By using the code examples, you agree to the terms of the Code license and disclaimer information. 

/*************************************************************************
** 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 */

 

References

 

Parent topic:

DB2 UDB CLI functions