SQLGetCursorName() - カーソル名を取得する
SQLGetCursorName() は、ステートメント・ハンドルに関連したカーソル名を戻します。SQLSetCursorName() を用いて明示的にカーソル名を設定すると、SQLSetCursorName() への呼び出し で指定した名前が戻されます。 明示的に名前を設定しない場合は、SQLGetCursorName() は、そのカーソルに対して暗黙的に生成した名前を戻します。
SQLGetCursorName() の ODBC 仕様
| ODBC 仕様レベル | X/Open CLI CAE 仕様 | ISO CLI 仕様 |
|---|---|---|
| 1.0 | あり | あり |
構文
SQLRETURN SQLGetCursorName (SQLHSTMT hstmt,
SQLCHAR FAR *szCursor,
SQLSMALLINT cbCursorMax,
SQLSMALLINT FAR *pcbCursor);
関数の引数
次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。
| データ・タイプ | 引数 | 使用法 | 説明 |
|---|---|---|---|
| SQLHSTMT | hstmt | 入力 | 識別対象のカーソルがオープン状態のステートメント・ハンドルを指定します。 |
| SQLCHAR * | szCursor | 出力 | カーソル名が戻されるバッファーを指定します。 |
| SQLSMALLINT | cbCursorMax | 入力 | 引数 szCursor が指しているバッファーのサイズを指定します。 |
| SQLSMALLINT * | pcbCursor | 出力 | カーソルが必要とするバイト数を受け取るバッファーを指します。 |
使用法
SQLGetCursorName() は、SQLSetCursorName() を用いてカーソルに明示的に設定した名前を戻します。 カーソルに名前を設定しなかった場合は、この関数を使用して、Db2® ODBC が内部的に生成した 名前を取り出すことができます。
SQLGetCursorName() は、あるステートメント上の同一カーソル名 (その名前は明示的または暗黙的の いずれでも可能) を戻します。この SQLGetCursorName() がこのカーソル名を戻すのは、そのステートメントを ドロップするか、別の明示的な名前を設定するまで継続します。 カーソル名は、常に 18 文字以下であり、接続内では常に固有の名前です。
Db2 ODBC が内部的に生成したカーソル名は、常に SQLCUR または SQL_CUR で始まります。また、照会の結果セットの場合、Db2 ODBC はカーソル名の接頭部として、SQLCURQRS も 予約済みです。(この命名規則の詳細については 制約事項を参照してください。)
戻りコード
- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
- SQL_ERROR
- SQL_INVALID_HANDLE
診断
次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。
| SQLSTATE | 説明 | 説明 |
|---|---|---|
| 01004 | データが切り捨てられました。 | 引数 szCursor が指定するバッファーに戻されたカーソル名は、 引数 cbCursorMax の値より長い値です。 このバッファーのデータは、引数 cbCursorMax が指定する値よりも 1 バイト短く 切り捨てられます。引数 pcbCursor には、完全なカーソル名を収容するのに必要な 長さ (バイト) が含まれています。(SQLGetCursorName() は、この SQLSTATE で SQL_SUCCESS_WITH_INFO を戻します。) |
| 08S01 | 通信リンクに障害が起きました。 | 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。 |
| 58004 | 予期しないシステム障害です。 | リカバリー不能なシステム・エラーです。 |
| HY001 | メモリーの割り振りに失敗しました。 | Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。 |
| HY010 | 関数シーケンス・エラーが発生しました。 | この関数は、実行時データの操作時に呼び出されました。(すなわち、SQLParamData() または SQLPutData() 関数を使用するプロシージャー実行中に関数が呼び出されました。) |
| HY013 | 予期しないメモリー処理エラーです。 | Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーにアクセスできません。 |
| HY015 | 使用可能なカーソル名がありません。 | 引数 hstmt で指定されたステートメント・ハンドルで、 オープン・カーソルがオープンしておらず、SQLSetCursorName() を用いて カーソル名が設定されていません。 |
| HY090 | ストリングまたはバッファーの長さが無効です。 | 引数 cbCursorMax に指定された値は 0 より小さい値です。 |
| HY092 | オプションのタイプが範囲外です。 | 引数 hstmt で指定されたステートメント・ハンドルは無効です。 |
制約事項
ODBC 生成のカーソル名は SQL_CUR で始まります。X/Open CLI 生成のカーソル名 は SQLCUR または SQL_CUR のいずれかで始まります。
Db2 ODBC は、カーソルを命名するための ODBC 仕様とは整合性があり ません。Db2 ODBC は、SQLCUR または SQL_CUR で始まるカーソル名を生成します。 これは、X/Open CLI 規格と整合性があります。
例
/******************************************************************/
/* Perform a positioned update on a column of a cursor. */
/******************************************************************/
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <sqlca.h>
#include "sqlcli1.h"
int main( )
{
SQLHENV hEnv = SQL_NULL_HENV;
SQLHDBC hDbc = SQL_NULL_HDBC;
SQLHSTMT hStmt = SQL_NULL_HSTMT, hStmt2 = SQL_NULL_HSTMT;
SQLRETURN rc = SQL_SUCCESS, rc2 = SQL_SUCCESS;
SQLINTEGER RETCODE = 0;
char *pDSN = "STLEC1";
SWORD cbCursor;
SDWORD cbValue1;
SDWORD cbValue2;
char employee [30];
int salary = 0;
char cursor_name [20];
char update [200];
char *stmt = "SELECT NAME, SALARY FROM EMPLOYEE WHERE
SALARY > 100000 FOR UPDATE OF SALARY";
(void) printf ("**** Entering CLIP04.¥n¥n");
/*****************************************************************/
/* Allocate environment handle */
/*****************************************************************/
RETCODE = SQLAllocHandle( SQL_HANDLE_ENV, SQL_NULL_HANDLE, &hEnv);
if (RETCODE != SQL_SUCCESS)
goto dberror;
/*****************************************************************/
/* Allocate connection handle to DSN */
/*****************************************************************/
RETCODE = SQLAllocHandle( SQL_HANDLE_DBC, hEnv, &hDbc);
if( RETCODE != SQL_SUCCESS ) // Could not get a Connect Handle
goto dberror;
/*****************************************************************/
/* CONNECT TO data source (STLEC1) */
/*****************************************************************/
RETCODE = SQLConnect(hDbc, // Connect handle
(SQLCHAR *) pDSN, // DSN
SQL_NTS, // DSN is nul-terminated
NULL, // Null UID
0 ,
NULL, // Null Auth string
0);
if( RETCODE != SQL_SUCCESS ) // Connect failed
goto dberror;
/*****************************************************************/
/* Allocate statement handles */
/*****************************************************************/
rc = SQLAllocHandle( SQL_HANDLE_STMT, hDbc, &hStmt);
if (rc != SQL_SUCCESS)
goto exit;
rc = SQLAllocHandle( SQL_HANDLE_STMT, hDbc, &hStmt2);
if (rc != SQL_SUCCESS)
goto exit;
/*****************************************************************/
/* Execute query to retrieve employee names */
/*****************************************************************/
rc = SQLExecDirect (hStmt,
(SQLCHAR *) stmt,
strlen(stmt));
if (rc != SQL_SUCCESS)
{
(void) printf ("**** EMPLOYEE QUERY FAILED.¥n");
goto dberror;
}
/*****************************************************************/
/* Extract cursor name -- required to build UPDATE statement. */
/*****************************************************************/
rc = SQLGetCursorName (hStmt,
(SQLCHAR *) cursor_name,
sizeof(cursor_name),
&cbCursor);
if (rc != SQL_SUCCESS)
{
(void) printf ("**** GET CURSOR NAME FAILED.¥n");
goto dberror;
}
(void) printf ("**** Cursor name is
rc = SQLBindCol (hStmt, // bind employee name
1,
SQL_C_CHAR,
employee,
sizeof(employee),
&cbValue1);
if (rc != SQL_SUCCESS)
{
(void) printf ("**** BIND OF NAME FAILED.¥n");
goto dberror;
}
rc = SQLBindCol (hStmt, // bind employee salary
2,
SQL_C_LONG,
&salary,
0,
&cbValue2);
if (rc != SQL_SUCCESS)
{
(void) printf ("**** BIND OF SALARY FAILED.¥n");
goto dberror;
}
/*****************************************************************/
/* Answer set is available -- Fetch rows and update salary */
/*****************************************************************/
while (((rc = SQLFetch (hStmt)) == SQL_SUCCESS) &&;
(rc2 == SQL_SUCCESS))
{
int new_salary = salary*1.1;
(void) printf ("**** Employee Name %s with salary %d. New salary = %d.¥n",
employee,
salary,
new_salary);
sprintf (update,
"UPDATE EMPLOYEE SET SALARY = %d WHERE CURRENT OF %s",
new_salary,
cursor_name);
(void) printf ("***** Update statement is :
rc2 = SQLExecDirect (hStmt2,
(SQLCHAR *) update,
SQL_NTS);
}
if (rc2 != SQL_SUCCESS)
{
(void) printf ("**** EMPLOYEE UPDATE FAILED.¥n");
goto dberror;
}
/*****************************************************************/
/* Reexecute query to validate that salary was updated */
/*****************************************************************/
rc = SQLCloseCursor(hStmt);
rc = SQLExecDirect (hStmt,
(SQLCHAR *) stmt,
strlen(stmt));
if (rc != SQL_SUCCESS)
{
(void) printf ("**** EMPLOYEE QUERY FAILED.¥n");
goto dberror;
}
while ((rc = SQLFetch (hStmt)) == SQL_SUCCESS)
{
(void) printf ("**** Employee Name %s has salary %d.¥n",
employee,
salary);
}
/*****************************************************************/
/* Deallocate statement handles */
/*****************************************************************/
rc = SQLFreeHandle (SQL_HANDLE_STMT, hStmt);
rc = SQLFreeHandle (SQL_HANDLE_STMT, hStmt2);
/*****************************************************************/
/* DISCONNECT from data source */
/*****************************************************************/
RETCODE = SQLDisconnect(hDbc);
if (RETCODE != SQL_SUCCESS)
goto dberror;
/*****************************************************************/
/* Deallocate connection handle */
/*****************************************************************/
RETCODE = SQLFreeHandle (SQL_HANDLE_DBC, hDbc);
if (RETCODE != SQL_SUCCESS)
goto dberror;
/*****************************************************************/
/* Free environment handle */
/*****************************************************************/
RETCODE = SQLFreeHandle (SQL_HANDLE_ENV, hEnv);
if (RETCODE == SQL_SUCCESS)
goto exit;
dberror:
RETCODE=12;
exit:
(void) printf ("**** Exiting CLIP04.¥n¥n");
return RETCODE;
}