SQLExecDirect() - ステートメントを直接実行する
SQLExecDirect() は 、SQL ステートメントを 1 ステップで準備し、実行します。
SQLExecDirect() の ODBC 仕様
| ODBC 仕様レベル | X/Open CLI CAE 仕様 | ISO CLI 仕様 |
|---|---|---|
| 1.0 | あり | あり |
構文
SQLRETURN SQLExecDirect (SQLHSTMT hstmt,
SQLCHAR FAR *szSqlStr,
SQLINTEGER cbSqlStr);
関数の引数
次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。
| データ・タイプ | 引数 | 使用法 | 説明 |
|---|---|---|---|
| SQLHSTMT | hstmt | 入力 | SQL ステートメントを実行するステートメント・ハンドルを指定します。 この引数で使用するステートメント・ハンドルでは、オープン・カーソルを関連付ける ことはできません。ステートメント・ハンドルを解放またはリセットする方法については、SQLFreeStmt() を参照してください。 |
| SQLCHAR * | szSqlStr | 入力 | SQL ステートメントを含むストリングを指定します。接続されたデータベース・サーバーは、ステートメントを準備できる必要があります。 |
| SQLINTEGER | cbSqlStr | 入力 | 引数 szSqlStr の内容の長さ (バイト) を指定します。 この長さは、ステートメントの正確な長さに設定するか、あるい はステートメントが NUL 終了である場合は SQL_NTS に設定する必要があります。 |
使用法
SQL ステートメントを 2 回以上実行する予定の場合、あるいは照会実行前に 結果セットの列に関する情報を取得する必要がある場合は、SQLExecDirect() の代わりに SQLPrepare() および SQLExecute() を使用してください。
SQLExecDirect() を使用するには、接続されたデータベース・サーバーが、 ステートメントを動的に作成できる必要があります。
SQL ステートメント・テキストにベンダー・エスケープ文節シーケンスが含まれる 場合、Db2® ODBC は、まず SQL ステートメント・テキストを、 該当する Db2 固有の形式に変更してから、準備と実行のためにサブミットします。 ベンダー・エスケープ文節シーケンスを含んでいる SQL ステートメントをアプリケーションが 生成しない場合、 接続レベルで SQL_ATTR_NOSCAN ステートメント属性を SQL_NOSCAN_ON に設定します。この属性を SQL_NOSCAN_ON に設定すると、ステートメントのスキャンが原因によるパフォーマンス の影響が回避されます。
この SQL ステートメントを COMMIT または ROLLBACK することはできません。 その代わりに、SQLEndTran() を呼び出して、COMMIT または ROLLBACK ステートメント を出す必要があります。
- アプリケーション変数。
SQLBindParameter() を使用して、アプリケーション・ストレージ域をパラメーター・マーカーにバインドします。
- LOB ロケーターが参照するサーバーにある LOB 値。
SQLBindParameter() を使用して、LOB ロケーターをパラメーター・マーカーにバインド します。LOB の実際の値はサーバーに保持されます。この値は、 別の SQL ステートメントの入力パラメーター値として使用されるまで、 アプリケーションに転送する必要はありません。
SQLExecDirect() を呼び出す前に、すべてのパラメーターをバインドする必要があります。
SQL ステートメントが照会の場合、SQLExecDirect() はカーソル名を生成し、 カーソルをオープンします。 アプリケーションが SQLSetCursorName() を使用してカーソル名を ステートメント・ハンドルに関連付けた場合、Db2 ODBC はアプリケーションで 生成されたカーソル名を内部生成されたカーソル名に関連付けます。
結果セットが生成されると、SQLFetch() または SQLExtendedFetch() は、 データの次の行 (1 行または複数行) を取り出して、バインドされた変数の中に入れます。 また、バインドされなかった列についても、SQLGetData() を呼び出すことにより、 データを取り出すことができます。
SQL ステートメントが位置付け DELETE または位置付け UPDATE の場合、 そのステートメントで参照されたカーソルを行に位置付け、 同じ接続ハンドルの個別のステートメント・ハンドル で定義する必要があります。
SQL ステートメントをステートメント・ハンドルで 実行する前に、オープン・カーソルがそのステートメントにあってはなりません。
SQLSetStmtAttr を呼び出して、入力パラメーター値の配列が それぞれのパラメーター・マーカーにバインドされるように指定した 場合は、SQLExecDirect() を一度だけ呼び出して、入力パラメーター値 の配列全体を処理する必要があります。
FOR n ROWS 文節は、SQLExecDirect() を用いて実行する MERGE ステートメントで指定できません。 マージする行数を指定するには、 SQLSetStmtAttr に SQL_ATTR_PARAMSET_SIZE ステートメント属性を指定して使用します。
戻りコード
- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
- SQL_ERROR
- SQL_INVALID_HANDLE
- SQL_NEED_DATA
- SQL_NO_DATA_FOUND
アプリケーションが実行時データ・パラメーター値を要求すると、SQL_NEED_DATA が戻され ます。SQLParamData() および SQLPutData() を呼び出して、これらのデータ・パラメーター値を SQLExecDirect() に提供します。
SQL ステートメントが検索 UPDATE または検索 DELETE であり、 検索条件を満たしている行がない場合、SQL_SUCCESS が戻されます。SQLRowCount() を使用して、表あるいは表のビューに対して実行された UPDATE、INSERT、 または DELETE ステートメントの影響を受けた表の行数を判別します。
診断
次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。
| SQLSTATE | 説明 | 説明 |
|---|---|---|
| 01504 | UPDATE または DELETE ステートメントに WHERE 節が含まれていません。 | 引数 szSqlStr に UPDATE または DELETE ステートメント が含まれていますが、WHERE 文節がありません。 (表に行がない場合、 関数は SQL_SUCCESS_WITH_INFO または SQL_NO_DATA_FOUND を戻します。) |
| 07001 | パラメーターの数に誤りがあります。 | SQLBindParameter() を用いてアプリケーション変数にバインドされたパラメーターの数が、 引数 szSqlStr に含まれている SQL ステートメントのパラメーター・マーカーの 数より小さくなっています。 |
| 07006 | 変換が無効です。 | Db2 ODBC とアプリケーション変数の間で データを転送すると、非互換のデータ変換が生じます。 |
| 08S01 | 通信リンクに障害が起きました。 | 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。 |
| 21S01 | 挿入値リストが列リストと一致していません。 | 引数 szSqlStr には INSERT ステートメントが含まれており、 挿入される値の数が派生表の程度と一致しませんでした。 |
| 21S02 | 派生した表の程度が列リストと一致しません。 | 引数 szSqlStr には CREATE VIEW ステートメントが含まれており、 指定された名前の数が照会指定で定義された派生表と同じ程度ではありません。 |
| 22001 | ストリング・データの右側が切り捨てられました。 | 文字タイプの列に割り当てられた文字ストリングが、列の最大長を超えました。 |
| 22008 | 日時形式が無効または日時フィールドがオーバーフローしました。 | 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
|
| 22012 | ゼロによる除算は無効です。 | 引数 szSqlStr は算術式を伴う SQL ステートメントを持っていますが、 それが除数ゼロで割り算を行いました。 |
| 22018 | 割り当てにエラーがありました。 | 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
|
| 23000 | 保全性制約違反。 | この SQL ステートメントの実行は許可されていません。その理由は、データベース管理システムにおける整合性を保つための制約に違反する恐れがあるためです。 |
| 24000 | カーソル状態が無効です。 | ステートメント・ハンドルでカーソルがオープン状態です。 |
| 24504 | UPDATE、DELETE、SET、または GET ステートメントで指定されたカーソルが行の上に位置づけられていません。 | 直前の照会からのステートメント・ハンドル上で、結果がペンディングになっているか、 あるいは、ステートメント・ハンドルに関連したカーソルがその時点ではまだクローズされていませんでした。 |
| 34000 | カーソル名が無効です。 | 引数 szSqlStr に位置付け DELETE または位置付け UPDATE が含まれていますが、 ステートメントが参照するカーソルがオープン状態ではありません。 |
| 37xxx1 | SQL 構文が無効です。 | 引数 szSqlStr には、以下の 1 つ以上のステートメント・タイプが含まれています。
|
| 40001 | トランザクション・ロールバック。 | SQL ステートメントが属しているトランザクションが、デッドロックまたはタイムアウト のためにロールバックされました。 |
| 42xxx1 | 構文エラーまたはアクセス規則違反 | これらの SQLSTATE は、以下のエラーのいずれかを示しています。
|
| 42895 | データ・タイプが原因で、EXECUTE または OPEN ステートメントのホスト変数の値を使用できません。 | 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
|
| 42S01 | データベース・オブジェクトは既に存在します。 | 引数 szSqlStr に、CREATE TABLE または CREATE VIEW ステートメントが 含まれていますが、指定された表名またはビュー名は既に存在しています。 |
| 42S02 | データベース・オブジェクトが存在しません。 | 存在しない表名またはビュー名を参照する SQL ステートメントが、 引数 szSqlStr に含まれています。 |
| 42S11 | 索引は既に存在します。 | 引数 szSqlStr に CREATE INDEX ステートメント が含まれていますが、指定された索引名は既に存在しています。 |
| 42S12 | 索引が見つかりません。 | 引数 szSqlStr に DROP INDEX ステートメントが含まれていますが、 指定された索引名が存在しません。 |
| 42S21 | 列は既に存在します。 | 引数 szSqlStr に ALTER TABLE ステートメントが含まれてい ますが、ADD 文節に指定された列は、固有でないか、または基本表の既存の列を示しています。 |
| 42S22 | 列が見つかりません。 | 引数 szSqlStr に、存在しない列名を参照 する SQL ステートメントが含まれています。 |
| 44000 | 保全性制約違反。 | 引数 szSqlStr に、パラメーターまたはリテラルのある SQL ステートメントが
含まれていますが、以下いずれかの違反があります。
|
| 58004 | 予期しないシステム障害です。 | リカバリー不能なシステム・エラーです。 |
| HY001 | メモリーの割り振りに失敗しました。 | Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。 |
| HY009 | NULL ポインターの使用は無効です。 | 引数 szSqlStr が NULL ポインターを指定しています。 |
| HY013 | 予期しないメモリー処理エラーです。 | Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーにアクセスできません。 |
| HY014 | これ以上ハンドルがありません。 | Db2 ODBC は、内部リソースが少ないためにハンドルを割り振ることができません。 |
| HY019 | 数値が範囲外です。 | 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
|
| HY090 | ストリングまたはバッファーの長さが無効です。 | 引数 cbSqlStr は 1 より小さい値です が、SQL_NTS と等しくありません。 |
| 注:
|
||
例
関連例については、SQLFetch() を参照してください。