仕様: | DB2 CLI 1.1 | ODBC 1.0 | ISO CLI |
SQLExecDirect() は、指定された SQL ステートメントを直接実行します。ステートメントは、1 回だけ実行されます。また、接続しているデータベース・サーバーが、ステートメントを動的に作成できなければなりません。 (サポートされる SQL ステートメントの詳細については、 表 215 を参照してください。)
構文
SQLRETURN SQLExecDirect (SQLHSTMT StatementHandle, SQLCHAR *FAR StatementText, SQLINTEGER TextLength);
関数引き数
データ・タイプ | 引き数 | 使用法 | 説明 |
---|---|---|---|
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() を呼び出すときにアプリケーションに提供された値が置き換えられる、ステートメント内の位置を指示するのに使用されます。この値は、以下のものから得られます。
SQLSetParam() または SQLBindParameter() は、アプリケーション記憶域をパラメーター・マーカーにバインドするのに使用されます。
SQLBindParameter() または SQLSetParam() は、 LOB ロケーターをパラメーター・マーカーにバインドするのに使用されます。 LOB の実際の値はサーバーに保持されるので、別の SQL ステートメントの入力パラメーター値として使用されるまで、アプリケーションに転送する必要はありません。
LOB パラメーター・マーカーにファイルをバインドするには、 SQLBindFileToParam() を使用します。 SQLExecDirect() を実行すると、 DB2 CLI はファイルの内容をデータベース・サーバーに直接転送します。
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 が返されます。
診断
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 ステートメントがありました。
| ||
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 つ以上が含まれていました。
| ||
40001 | トランザクション・ロールバック。 | この SQL ステートメントが属するトランザクションは、デッドロックまたはタイムアウトが原因でロールバックされました。 | ||
40003 08S01 | 通信リンクに障害が起きました。 | アプリケーションとデータ・ソースとの間の通信リンクが、関数の完了する前に失敗しました。 | ||
42xxx | 構文エラーまたはアクセス規則違反。 | 425xx は、
StatementText に含まれている SQL ステートメントの実行がこの許可 ID に許可されていないことを示します。
他の 42xxx SQLSTATE は、構文の相違またはステートメントとのアクセス問題があることを示しています。 | ||
428A1 | ホスト・ファイル変数で参照されるファイルにアクセスできません。 | これは、以下のシナリオで生ずる可能性があります。テキスト内で関連付けられた理由コードは、特定のエラーを表します。
| ||
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 属性を使用して設定することができます。 | ||
|
制約
なし。
(ここで完全サンプル 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);
参照