SQLGetCursorName - 获取游标名称

SQLGetCursorName() 返回与输入语句句柄关联的游标名称。如果通过调用 SQLSetCursorName()来显式设置游标名，那么将返回此名称; 否则，将返回内部生成的名称。

内部生成的游标名称的长度始终为 18 个字节。

Unicode (UTF-16) 等效: 此函数还可以与 Unicode (UTF-16) 字符集配合使用。相应的 Unicode 函数是 SQLGetCursorNameW() 。有关 DB2® CLI 的 Unicode 支持的更多信息，请参阅 Db2 for i CLI 中的 Unicode 。

语法

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

函数自变量

表 1. SQLGetCursorName参数
数据类型	自变量	使用	描述
SQLHSTMT	hstmt	输入	语句句柄
SQLCHAR *	szCursor	输出	游标名称
SQLSMALLINT	cbCursorMax	输入	缓冲区的长度 szCursor
SQLSMALLINT *	pcbCursor	输出	可供 szCursor 返回的字节数

用法

如果使用 SQLSetCursorName() 设置了名称，或者在语句句柄上处理了 SELECT 语句，那么 SQLGetCursorName() 将返回游标名称。如果这两种情况都不成立，那么调用 SQLGetCusorName() 将导致错误。

如果使用 SQLSetCursorName()显式设置名称，那么将返回此名称，直到删除语句或设置另一个显式名称为止。

如果存储过程调用导致打开游标，那么 SQLSetCursorName() 不会返回存储过程所设置的名称。

如果未设置显式名称，那么在处理 SELECT 语句时将生成隐式名称，并返回此名称。隐式游标名称始终以 SQLCUR 开头。

生成的 ODBC 游标名称以 SQL_CUR 开头，而 X/Open CLI 生成的游标名称以 SQLCUR 开头。 Db2 for i CLI 使用 SQLCUR。

返回码

SQL_SUCCESS
sql_success_with_info
SQL_ERROR
sql_invalid_handle

诊断

表 2。 SQLGetCursorName SQLSTATEs
SQLSTATE	描述	说明
01004	数据已截断	szCursor中返回的游标名称长于 cbCursorMax 中的值，因此被截断为 cbCursorMax-1字节。参数 pcbCursor 包含可供返回的游标全名的长度。此函数返回 SQL_SUCCESS_WITH_INFO。
40003 *	语句完成未知	在该功能完成处理之前， CLI 与数据源之间的通信链路发生故障。
58004	系统错误	不可恢复的系统错误。
HY001	内存分配失败	驱动程序无法分配支持功能处理或完成所需的内存。
HY009	参数值无效	自变量 szCursor 或 pcbCursor 是空指针。为参数 cbCursorMax 指定的值小于 1。
HY010	函数顺序错误	语句 hstmt 未处于执行状态。在调用 `SQLGetCursorName()`之前调用 `SQLExecute()`， `SQLExecDirect()` 或 `SQLSetCursorName()` 。
HY013 *	内存管理问题	驱动程序无法访问支持处理或完成功能所需的内存。
HY015	没有可用的游标名称。	hstmt 上没有打开的游标，并且没有使用 `SQLSetCursorName()`设置游标名称。与 hstmt 关联的语句不支持使用游标。

限制

当使用存储过程调用打开游标时， SQLGetCursorName() 不会返回正确的名称。

示例

请参阅示例: 交互式 SQL 和等效的 Db2 for i CLI 函数调用，以获取以下示例中使用的

check_error,
initialize, and terminate

函数的列表。

注: 通过使用代码示例，您同意代码许可证和免责声明信息的条款。

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

SQLGetCursorName - 获取游标名称

语法

函数自变量

用法

返回码

诊断

限制

示例

引用