CLI の手引きおよび解説書

SQLExecDirect - ステートメントの直接実行

目的


仕様: DB2 CLI 1.1 ODBC 1.0 ISO CLI

SQLExecDirect() は、指定された SQL ステートメントを直接実行します。ステートメントは、1 回だけ実行されます。また、接続しているデータベース・サーバーが、ステートメントを動的に作成できなければなりません。 (サポートされる SQL ステートメントの詳細については、 表 215 を参照してください。)

構文

SQLRETURN   SQLExecDirect    (SQLHSTMT          StatementHandle,
                              SQLCHAR      *FAR StatementText,
                              SQLINTEGER        TextLength);

関数引き数

表 57. SQLExecDirect 引き数
データ・タイプ 引き数 使用法 説明
SQLHSTMT StatementHandle 入力 ステートメント・ハンドル。 StatementHandle に関連したオープン・カーソルがあってはなりません。詳細については、SQLFreeStmt - ステートメント・ハンドルの解放 (またはリセット)を参照してください。
SQLCHAR * StatementText 入力 SQL ステートメント・ストリング。接続しているデータベース・サーバーが、ステートメントを作成できなければなりません。詳細については、表 215 を参照してください。
SQLINTEGER TextLength 入力 StatementText 引き数の内容の長さ。この長さは、ステートメントの正確な長さに設定するか、ステートメントがヌル終了である場合は SQL_NTS に設定する必要があります。

使用法

SQL ステートメント・テキストにベンダー・エスケープ文節順序列が含まれている場合、 DB2 CLI はまず SQL ステートメント・テキストを適切な DB2 固有の形式に修正してから、それを用いて作成および実行を依頼します。アプリケーションがベンダー・エスケープ文節順序列 (ベンダー・エスケープ文節の使用) を含む SQL ステートメントを生成しない場合は、接続レベルで SQL_NOSCAN_ON に SQL_ATTR_NOSCAN を設定することによって、 DB2 CLI がベンダー・エスケープ文節を探索して走査することがないようにすることができます。

SQL ステートメントを COMMIT または ROLLBACK とすることはできません。その代わり、 SQLTransact() を呼び出して COMMIT または ROLLBACK を出してください。サポートされる SQL ステートメントの詳細については、表 215を参照してください。

SQL ステートメント・ストリングの中に、パラメーター・マーカーが含まれている場合があります。パラメーター・マーカーは "?" 文字で表され、また、SQLExecDirect() を呼び出すときにアプリケーションに提供された値が置き換えられる、ステートメント内の位置を指示するのに使用されます。この値は、以下のものから得られます。

SQLExecDirect() を呼び出す前に、すべてのパラメーターをバインドしておく必要があります。

パラメーター・マーカーに関する規則については、 SQL 解説書 の PREPARE のセクションを参照してください。

SQL ステートメントが照会の場合、SQLExecDirect() はカーソル名を生成し、そのカーソルをオープンします。アプリケーションが SQLSetCursorName() を使用してカーソル名をステートメント・ハンドルに関連付けた場合、 DB2 CLI はアプリケーションで生成されたカーソル名を内部作成されたカーソル名に関連付けます。

結果セットを生成すると、SQLFetch() または SQLFetchScroll() は、バインドされた変数、LOB ロケーター、または LOB ファイル参照のいずれかに、その次のデータ行 (複数行の場合もある) を取り出します (SQLBindCol() または SQLBindFileToCol() を使用します)。また、バインドされなかった列についても、 SQLGetData() を呼び出すとデータを取り出すことができます。

SQL ステートメントが定位置 DELETE または定位置 UPDATE の場合、そのステートメントで参照されたカーソルを行に入れ、同じ接続ハンドルの別個のステートメント・ハンドルで定義する必要があります。

ステートメント・ハンドル上にオープン・カーソルがあってはなりません。

SQLParamOptions() を呼び出して、入力パラメーター値の配列が各パラメーター・マーカーにバインドされるように指定した場合、アプリケーションは SQLExecDirect() を一度だけ呼び出して、入力パラメーター値の配列全体を処理します。

戻りコード

アプリケーションが SQLParamData()SQLPutData() を呼び出して、実行時データ・パラメーター値を入力するよう要求すると、SQL_NEED_DATA が返されます。

SQL ステートメントが検索 UPDATE または検索 DELETE であり、検索条件を満たしている行がない場合、SQL_NO_DATA_FOUND が返されます。

診断

表 58. SQLExecDirect SQLSTATE
SQLSTATE 説明 解説
01504 UPDATE または DELETE ステートメントに WHERE 文節がありません。 StatementText の UPDATE ステートメントまたは DELETE ステートメントに、 WHERE 文節が入っていませんでした。 (表に行がなかった場合、関数は SQL_SUCCESS_WITH_INFO または SQL_NO_DATA_FOUND を返します。)
01508 ステートメントはブロック化できませんでした。 このステートメントは、記憶域以外の理由でブロック化できませんでした。
07001 パラメーターの数が正しくありません。 SQLBindParameter() を使用してアプリケーション変数にバインドされたパラメーターの数が、引き数 StatementText に含まれている SQL ステートメント内のパラメーター・マーカーの数より小さい値でした。
07006 変換が無効です。 DB2 CLI とアプリケーション変数の間でデータを転送すると、非互換のデータ変換が行われます。
21S01 挿入値リストが列リストと一致しません。 StatementText に INSERT ステートメントがあり、挿入する値の数が派生表の程度と一致していませんでした。
21S02 派生表の程度が列リストと一致しません。 StatementText に CREATE VIEW ステートメントがあり、指定された名前の数は、照会指定で定義されている派生表と同じ程度になっていません。
22001 ストリング・データの右側が切り捨てられました。 文字タイプ列に割り当てられた文字ストリングが、列の最大長を超えました。
22003 数値が範囲外です。 数値タイプ列に割り当てられた数値のために、割り当て時または中間結果の計算時に、数値の整数部分が切り捨てられました。

StatementText に、ゼロでの除算を行わせた算術式を含む SQL ステートメントがありました。

注:その結果、DB2 ユニバーサル・データベースに対してカーソル状態は定義されません (他の RDBMS のカーソルはオープンしたままになります)。

22005 割り当てにエラーがありました。 StatementText にはパラメーターまたはリテラルのある SQL ステートメントが含まれており、値または SQL ロケーターは関連した表列のデータ・タイプとの互換性がありませんでした。

パラメーター値に関連付けられている長さ (SQLBindParameter() に指定されている pcbValue バッファーの内容) は有効ではありません。

SQLBindParameter() または SQLSetParam() に使用されている引き数 fSQLType は SQL 図形データ・タイプを指示しましたが、据え置き長さ引き数 (pcbValue) には奇数の長さの値が含まれています。図形データ・タイプの場合、長さの値は偶数でなければなりません。

22007 日時形式が無効です。 StatementText には日時形式が無効な SQL ステートメントが含まれていました。つまり、無効なストリング表示または値が指定されたか、あるいは値が無効な日付になっています。
22008 日時フィールドがオーバーフローしました。 日時フィールドがオーバーフローしました。たとえば、日付またはタイム・スタンプの算術計算の結果が有効な日付範囲内にないか、または日時の値が小さ過ぎて、結合変数に割り当てることができません。
22012 ゼロによる割算は無効です。 StatementText に、ゼロでの除算を行わせた算術式を含む SQL ステートメントがありました。
23000 保全性制約違反です。 SQL ステートメントの実行ができないのは、それを実行すると DBMS 内に保全性制約違反が発生するからです。
24000 カーソル状態が無効です。 カーソルはすでに、ステートメント・ハンドル上にオープンされています。
24504 UPDATE、DELETE、SET、または GET ステートメントで識別されたカーソルが、行に位置付けられていません。 結果は直前の照会から StatementHandle で保留状態になったか、 hsmt に関連したカーソルがまだクローズされていませんでした。
34000 カーソル名が無効です。 StatementText に、位置指定された DELETE または位置指定された UPDATE があり、実行中のステートメントで参照されているカーソルはオープンされていませんでした。
37xxx a SQL 構文が無効です。 StatementText に、以下のうちの 1 つ以上が含まれていました。
  • COMMIT
  • ROLLBACK
  • 接続されたデータベース・サーバーが準備できない SQL ステートメント
  • 構文エラーを含むステートメント
40001 トランザクション・ロールバック。 この SQL ステートメントが属するトランザクションは、デッドロックまたはタイムアウトが原因でロールバックされました。
40003 08S01 通信リンクに障害が起きました。 アプリケーションとデータ・ソースとの間の通信リンクが、関数の完了する前に失敗しました。
42xxx 構文エラーまたはアクセス規則違反。 425xx は、 StatementText に含まれている SQL ステートメントの実行がこの許可 ID に許可されていないことを示します。

他の 42xxx SQLSTATE は、構文の相違またはステートメントとのアクセス問題があることを示しています。

428A1 ホスト・ファイル変数で参照されるファイルにアクセスできません。 これは、以下のシナリオで生ずる可能性があります。テキスト内で関連付けられた理由コードは、特定のエラーを表します。
  • 01 - ファイル名の長さが無効か、またはファイル名とパスのいずれか、または両方の形式が無効です。
  • 02 - ファイル・オプションが無効です。ファイル・オプションには、以下のいずれかの値が指定されなければなりません。

     
    SQL_FILE_READ      -既存ファイルからの読み取り
    SQL_FILE_CREATE    -書き込みのための新規ファイルの
                        作成
    SQL_FILE_OVERWRITE -既存ファイルの上書き
                        ファイルが存在しない場合は
                        ファイルを作成
    SQL_FILE_APPEND    -既存ファイルへの付加
                        ファイルが存在しない場合は
                        ファイルを作成
    
  • 03 - ファイルが見つかりませんでした。
  • 04 - SQL_FILE_CREATE オプションが、既存のファイルと同じ名前を持つファイルに指定されました。
  • 05 - ファイルへのアクセスが拒否されました。ユーザーが、ファイルをオープンするための許可を持っていません。
  • 06 - ファイルへのアクセスが拒否されました。ファイルが非互換モードで使用中です。書き込まれるファイルが、排他モードでオープンされています。
  • 07 - ファイルへの書き込み中に、ディスクがいっぱいになりました。
  • 08 - ファイルの読み取り中に、予期しないファイル終わりが見つかりました。
  • 09 - ファイルのアクセス中に、媒体エラーが起きました。
42895 EXECUTE または OPEN ステートメント内のホスト変数値は、そのデータ・タイプのゆえに使用できません。 バインド・パラメーター関数呼び出しに指定された LOB ロケーター・タイプが、パラメーター・マーカーの LOB データ・タイプと一致していません。

バインド・パラメーター関数に使用される引き数 fSQLType は、 LOB ロケーター・タイプを指定しましたが、対応するパラメーター・マーカーは LOB ではありません。

44000 保全性制約違反。 StatementText に、パラメーターまたはリテラルのある SQL ステートメントが含まれていました。このパラメーター値が、関連した表列で NOT NULL として定義されている列について NULL だったか、固有値だけが入るように制約された列について重複値が指定されていたか、または、他の保全性制約に違反しました。
56084 DRDA では、LOB データはサポートされていません。 DRDA サーバーに接続 (DB2 コネクトを使用して行う) しているときには、 LOB 列の選択や更新を行うことができません。
58004 予期しないシステム障害です。 回復不能システム・エラー。
S0001 データベース・オブジェクトはすでに存在しています。 StatementText に、 CREATE TABLE ステートメントまたは CREATE VIEW ステートメントがあり、指定されている表名または視点名はすでに存在しています。
S0002 データベース・オブジェクトは存在していません。 StatementText に、存在しない表名または視点名を参照する SQL ステートメントが含まれていました。
S0011 索引はすでに存在しています。 StatementText に CREATE INDEX ステートメントがあり、指定された索引名はすでに存在していました。
S0012 索引がありません。 StatementText に DROP INDEX ステートメントがあり、指定された索引名は存在していませんでした。
S0021 列はすでに存在しています。 StatementText に ALTER TABLE ステートメントがあり、 ADD 文節に指定されている列は固有になっていなかったか、基本表の既存の列を識別できませんでした。
S0022 列がありません。 StatementText に、存在しない列名を参照する SQL ステートメントが含まれていました。
HY001 メモリーの割り振り失敗です。 DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。
HY009 引き数値が無効です。 StatementText は、ヌル・ポインターでした。
HY013 予期しないメモリーのハンドル・エラーが起きました。 DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを使用することができませんでした。
HY014 もはやハンドルはありません。 DB2 CLI は、内部資源が原因でハンドルを割り当てることができませんでした。
HY090 ストリングまたはバッファー長が無効です。 引き数 TextLength は 1 より小さい値でしたが、SQL_NTS と等しくありませんでした。
HY092 オプション・タイプが範囲外です。 直前の SQLBindFileToParam() 操作の FileOptions 引き数が無効でした。
HY503 ファイル名の長さが無効です。 SQLBindFileToParam() からの fileNameLength 引き数値は 0 より小さい値でしたが、 SQL_NTS と等しい値ではありませんでした。
HYT00 タイムアウトになりました。 データ・ソースが結果セットを返す前に、タイムアウト期間が満了しました。タイムアウトは、 Windows 3.1 や Macintosh System 7 のようなマルチタスクではないシステム上でのみサポートされています。タイムアウト期間は、 SQLSetConnectAttr() の SQL_ATTR_QUERY_TIMEOUT 属性を使用して設定することができます。
注:

a
xxx は、そのクラス・コードの任意の SQLSTATE を表します。たとえば、 37xxx は 37 クラスの任意の SQLSTATE を表します。

制約

なし。

CLI サンプル tbread.c

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

/* From the CLI sample TBREAD.C */
/* ... */
    /* execute directly the statement */
    printf("\n    Execute directly the statement.\n");
    printf("        %s\n", stmt);
    sqlrc = SQLExecDirect( hstmt, stmt, SQL_NTS ) ;
    STMT_HANDLE_CHECK( hstmt, sqlrc);
 
/* ... */
    /* execute directly the statement */
    printf("\n    Execute directly the statement.\n");
    printf("        %s\n", stmt);
    sqlrc = SQLExecDirect( hstmt, stmt, SQL_NTS ) ;
    STMT_HANDLE_CHECK( hstmt, sqlrc);
 
/* ... */
    /* execute directly the statement */
    printf("\n    Execute directly the statement\n");
    printf("        %s.\n", stmt);
    sqlrc = SQLExecDirect( hstmt, stmt, SQL_NTS ) ;
    STMT_HANDLE_CHECK( hstmt, sqlrc);
 
 

参照


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