SQLGetCursorName() - カーソル名を取得する

SQLGetCursorName() は、ステートメント・ハンドルに関連したカーソル名を戻します。SQLSetCursorName() を用いて明示的にカーソル名を設定すると、SQLSetCursorName() への呼び出し で指定した名前が戻されます。 明示的に名前を設定しない場合は、SQLGetCursorName() は、そのカーソルに対して暗黙的に生成した名前を戻します。

SQLGetCursorName() の ODBC 仕様

表 1. SQLGetCursorName() の仕様
ODBC 仕様レベル X/Open CLI CAE 仕様 ISO CLI 仕様
1.0 あり あり

構文

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

関数の引数

次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。

表 2. SQLGetCursorName() の引数
データ・タイプ 引数 使用法 説明
SQLHSTMT hstmt 入力 識別対象のカーソルがオープン状態のステートメント・ハンドルを指定します。
SQLCHAR * szCursor 出力 カーソル名が戻されるバッファーを指定します。
SQLSMALLINT cbCursorMax 入力 引数 szCursor が指しているバッファーのサイズを指定します。
SQLSMALLINT * pcbCursor 出力 カーソルが必要とするバイト数を受け取るバッファーを指します。

使用法

SQLGetCursorName() は、SQLSetCursorName() を用いてカーソルに明示的に設定した名前を戻します。 カーソルに名前を設定しなかった場合は、この関数を使用して、Db2® ODBC が内部的に生成した 名前を取り出すことができます。

SQLGetCursorName() は、あるステートメント上の同一カーソル名 (その名前は明示的または暗黙的の いずれでも可能) を戻します。この SQLGetCursorName() がこのカーソル名を戻すのは、そのステートメントを ドロップするか、別の明示的な名前を設定するまで継続します。 カーソル名は、常に 18 文字以下であり、接続内では常に固有の名前です。

Db2 ODBC が内部的に生成したカーソル名は、常に SQLCUR または SQL_CUR で始まります。また、照会の結果セットの場合、Db2 ODBC はカーソル名の接頭部として、SQLCURQRS も 予約済みです。(この命名規則の詳細については 制約事項を参照してください。)

戻りコード

SQLGetCursorName() は、呼び出された後、次のいずれかの値を戻します。
  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_ERROR
  • SQL_INVALID_HANDLE

診断

次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。

表 3. SQLGetCursorName() の 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 規格と整合性があります。

例

以下の例 は、SQLGetCursorName() を使用して、 先行する更新ステートメントで必要なカーソル名を抜き出すアプリケーションを示しています。
図 1. カーソル名を抜き出すアプリケーション
 /******************************************************************/
 /*  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;
}