SQLExecute() - ステートメントを実行する

SQLExecute() は、SQLPrepare() を用いて正常に準備されたステートメントを 1 回以上実行します。SQLExecute() を用いてステートメントを実行する場合は、 そのステートメントのパラメーター・マーカーにバインドされた任意のアプリケーション変数の現行値が使用されます。

SQLExecute() の ODBC 仕様

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

構文

SQLRETURN   SQLExecute       (SQLHSTMT          hstmt);

関数の引数

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

表 2. SQLExecute() の引数
データ・タイプ 引数 使用法 説明
SQLHSTMT hstmt 入力 ステートメント・ハンドルを指定します。 オープン・カーソルはステートメント・ハンドルに関連付ける ことはできません。詳しくは、SQLFreeStmt() を参照してください。

使用法

SQLExecute() を使用して、SQLPrepare() を用いて準備した SQL ステートメント を実行します。この SQL ステートメントには、パラメーター・マーカーを含めることができます。 パラメーター・マーカーとは、SQL ステートメント・ストリングに置く疑問符 (?) の文字のこと です。SQLExecute() を呼び出してパラメーター・マーカーを含んでいるステートメントを実行すると、このマーカーはそれぞれがホスト変数の内容と置き換わります。

SQLBindParameter() を使用して、ステートメント・ストリングのすべてのパラメーター・マーカーを、アプリケーションが提供する 値に関連付けてから、SQLExecute() を呼び出す必要があります。この値は、以下のいずれかのソースから取得することができます。
  • アプリケーション変数。

    SQLBindParameter() を使用して、アプリケーション・ストレージ域をパラメーター・マーカーにバインドします。

  • LOB ロケーターが参照するサーバーにある LOB 値。

    SQLBindParameter() を使用して、LOB ロケーターをパラメーター・マーカーにバインド します。LOB の実際の値はサーバーに保持されます。この値は、 別の SQL ステートメントの入力パラメーター値として使用されるまで、 アプリケーションに転送する必要はありません。

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

アプリケーションは、SQLExecute() 呼び出しからの結果を処理した後、新しい (または同じ) パラメーター値を使用して再度ステートメントを実行することができます。

SQLExecDirect() によって実行されたステートメントを、SQLExecute() を呼び出して 再実行することはできません。SQLExecute() を用いてステートメントを実行する前に、SQLPrepare() を 呼び出す必要があります。

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

照会を複数回実行するには、引数 fOption を SQL_CLOSE に設定し、SQLFreeStmt() を 呼び出すことによって、カーソルをクローズする必要があります。SQLExecute() を呼び出す場合は 、オープン・カーソルがステートメント・ハンドルにあってはなりません。

結果セットが生成されると、SQLFetch() または SQLExtendedFetch() は、 データの次の行 (1 行または複数行) を取り出して、バインドされた変数 または LOB ロケーターに入れます。 また、バインドされなかった列についても、SQLGetData() を呼び出すことにより、 データを取り出すことができます。

SQL ステートメントが位置付け DELETE または位置付け UPDATE の 場合、SQLExecute() 呼び出し時に、そのステートメントが参照する カーソルを行に位置付け、同じ接続ハンドルのもとで個別の ステートメント・ハンドル上に定義する必要があります。

SQLSetStmtAttr を呼び出して、入力パラメーター値の配列が それぞれのパラメーター・マーカーにバインドされるように指定した 場合は、SQLExecDirect() を一度だけ呼び出して、入力パラメーター値 の配列全体を処理する必要があります。 実行されたステートメントが複数の結果セットを戻す (入力パラメーターのそれぞれの セットごとに 1 つ) 場合は、SQLMoreResults() を呼び出して、 現在の結果セットの処理が完了したならば次の結果セットに進んでください。

戻りコード

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

アプリケーションが実行時データ・パラメーター値を要求すると、SQL_NEED_DATA が戻され ます。SQLParamData() および SQLPutData() を呼び出して、これらの値を SQLExecute() に与えます。

SQL ステートメントが検索 UPDATE または検索 DELETE であり、 検索条件を満たしている行がない場合、SQL_SUCCESS が戻されます。SQLRowCount() を使用して 、表あるいは表のビューに対して実行された UPDATE、INSERT、 DELETE、または MERGE ステートメントの影響を受けた表の行数を判別してください。

診断

SQLExecute() が戻す SQLSTATE には、SQLExecDirect() が生成できるすべて の SQLSTATE (例外は、HY009、HY014、およ び HY090 はなく、HY010 が追加されている) が 含まれています。

次の表は、SQLExecute() が戻すことができる 追加の SQLSTATE を示し、説明したものです。

表 3. SQLExecute() の SQLSTATE
SQLSTATE 説明 説明
HY010 関数シーケンス・エラーが発生しました。 SQLExecute() が、SQLPrepare() よりも前のステートメントで呼び出されました。

例

関連例については、SQLPrepare() を参照してください。