CLI の手引きおよび解説書

SQLSetCursorName - カーソル名を設定する

目的


仕様: DB2 CLI 1.1 ODBC 1.0 ISO CLI

SQLSetCursorName() は、ステートメント・ハンドルにカーソル名を関連付けます。 DB2 CLI は、ステートメント・ハンドルが割り振られるときに、カーソル名を暗黙に生成するので、この関数は任意選択です。

構文

SQLRETURN   SQLSetCursorName (SQLHSTMT          StatementHandle,
                              SQLCHAR      FAR  *CursorName,
                              SQLSMALLINT       NameLength);

関数引き数

表 154. SQLSetCursorName 引き数
データ・タイプ 引き数 使用法 説明
SQLHSTMT StatementHandle 入力 ステートメント・ハンドル
SQLCHAR * CursorName 入力 カーソル名。
SQLSMALLINT NameLength 入力 CursorName 引き数の内容の長さ。

使用法

DB2 CLI は常に、照会を直接準備または実行するときに、内部生成のカーソル名を生成し、使用します。 SQLSetCursorName() では、アプリケーションで定義されるカーソル名を SQL ステートメント (定位置 UPDATE または DELETE) で使用できます。 DB2 CLI は、内部名にこの名前をマップします。ハンドルが除去されるまで、名前はステートメント・ハンドルと関連付けられたままであるか、このステートメント・ハンドルに他の SQLSetCursorName() が呼び出されます。

SQLGetCursorName() はアプリケーションが設定した名前を戻しますが (名前が設定されている場合)、位置指定された UPDATE および DELETE ステートメントと関連したエラー・メッセージは、内部名を参照します。このため、SQLSetCursorName() を使用せず、代わりに SQLGetCursorName() を呼び出して取得できる内部名を使用することをお勧めします。

カーソル名は、次の規則に従う必要があります。

処理の効率を上げるには、 CursorName バッファーに先行スペースや後書きスペースを入れないようにしてください。 CursorName バッファーに区切り ID が入っている場合、アプリケーションは先頭の二重引用符を CursorName バッファーの先頭文字として配置します。

戻りコード

診断

表 155. SQLSetCursorName SQLSTATE
SQLSTATE 説明 解説
34000 カーソル名が無効です。 引き数 CursorName で指定されたカーソル名は無効です。カーソル名は「SQLCUR」または「SQL_CUR」から始まっているか、または、カーソル命名規則 (先頭が a〜z または A〜Z で、その後に英字、数字、下線文字の任意の組み合わせが続く) に違反しています。

引き数 CursorName で指定されたカーソル名はすでに存在しています。

カーソル名の長さが、 SQL_MAX_CURSOR_NAME_LEN 引き数のある SQLGetInfo() が戻した値よりも大きいです。

40003 08S01 通信リンクに障害が起きました。 アプリケーションとデータ・ソースとの間の通信リンクが、関数の完了する前に失敗しました。
58004 予期しないシステム障害です。 回復不能システム・エラー。
HY001 メモリーの割り振り失敗です。 DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。
HY009 引き数値が無効です。 CursorName は、ヌル・ポインターでした。
HY010 関数の順序エラーです。 ステートメント・ハンドル上にオープン・カーソルまたは位置指定されたカーソルがあります。

実行時データ (SQLParamData()SQLPutData()) 操作中に、関数が呼び出されました。

BEGIN COMPOUND と END COMPOUND SQL の操作中に、関数が呼び出されました。

非同期実行関数 (この関数ではない) が StatementHandle で呼び出され、この関数は、呼び出し時に依然実行中でした。

HY013 予期しないメモリーのハンドル・エラーが起きました。 DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを使用することができませんでした。
HY090 ストリングまたはバッファー長が無効です。 引き数 NameLength0 より小さい値でしたが、 SQL_NTS と等しくありませんでした。

許可

なし。

CLI サンプル tbmod.c

(ここで完全サンプル tbmod.c を使用することもできます 。)

/* From the CLI sample TBMOD.C */
/* ... */
    /* set the name of the cursor */    
    rc = SQLSetCursorName(hstmtSelect, (SQLCHAR *)"CURSNAME", SQL_NTS);
    STMT_HANDLE_CHECK( hstmtSelect, sqlrc);
    
 

参照


[ ページのトップ | 前ページ | 次ページ | 目次 | 索引 ]