仕様: | DB2 CLI 1.1 | ODBC 1.0 | ISO CLI |
SQLSetCursorName() は、ステートメント・ハンドルにカーソル名を関連付けます。 DB2 CLI は、ステートメント・ハンドルが割り振られるときに、カーソル名を暗黙に生成するので、この関数は任意選択です。
構文
SQLRETURN SQLSetCursorName (SQLHSTMT StatementHandle, SQLCHAR FAR *CursorName, SQLSMALLINT NameLength);
関数引き数
データ・タイプ | 引き数 | 使用法 | 説明 |
---|---|---|---|
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 | ストリングまたはバッファー長が無効です。 | 引き数 NameLength は 0 より小さい値でしたが、 SQL_NTS と等しくありませんでした。 |
許可
なし。
(ここで完全サンプル 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);
参照