仕様: | DB2 CLI 1.1 | ODBC 1.0 | ISO CLI |
SQLPrepare() は、入力ステートメント・ハンドルに SQL ステートメントを関連付け、そのステートメントを DBMS に送って準備します。アプリケーションは、ステートメント・ハンドルを他の関数に渡して、この準備済みステートメントを参照することができます。
すでに照会ステートメント (または結果セットを戻す関数) でステートメント・ハンドルを使用している場合、 SQLPrepare() を呼び出す前に SQLFreeStmt() を呼び出してカーソルをクローズする必要があります。
構文
SQLRETURN SQLPrepare (SQLHSTMT StatementHandle, SQLCHAR FAR *StatementText, SQLINTEGER TextLength);
関数引き数
データ・タイプ | 引き数 | 使用法 | 説明 |
---|---|---|---|
SQLHSTMT | StatementHandle | 入力 | ステートメント・ハンドル。 StatementHandle に関連したオープン・カーソルがあってはなりません。 |
SQLCHAR * | StatementText | 入力 | SQL ステートメント・ストリング。 |
SQLINTEGER | TextLength | 入力 | StatementText 引き数の内容の長さ。
これは、szSqlstr 内の SQL ステートメントの正確な長さに設定するか、ステートメント・テキストがヌル文字で終了している場合は SQL_NTS に設定する必要があります。 |
使用法
DB2 CLI バージョン 5 では、デフォルトで据え置き準備がオンになります。対応する実行要求が発行されるまで、PREPARE 要求はサーバーに送られません。これによってネットワーク・フローが最小限になり、パフォーマンスが向上します。詳細はデフォルトでの据え置き準備を参照してください。
SQL ステートメント・テキストにベンダー・エスケープ文節順序列を含む場合、 DB2 CLI は、準備のために SQL ステートメント・テキストをデータベースにサブミットする前に、まず SQL ステートメント・テキストを適切な DB2 特定形式に修正します。アプリケーションがベンダー・エスケープ文節順序列 (ベンダー・エスケープ文節の使用を参照) を含む SQL を生成しない場合は、 SQL_ATTR_NOSCAN ステートメント属性を接続レベルで SQL_NOSCAN に設定することによって、 DB2 CLI がベンダー・エスケープ文節に走査を実行しないようにすることができます。
SQLPrepare() を使用してステートメントをいったん準備したら、アプリケーションは次のものを呼び出して、結果セット (照会ステートメントであった場合) の形式に関する情報を要求することができます。
SQL ステートメント・ストリングには、パラメーター・マーカーが含まれている場合があり、 SQLNumParams() を呼び出して、ステートメント内のパラメーター・マーカーの個数を判別することができます。パラメーター・マーカーは "?" 文字によって表されており、アプリケーションに提供された値が SQLExecute() の呼び出し時に置き換えられる、ステートメント内の位置を指示するのに使用されます。バインド・パラメーター関数である SQLBindParameter()、 SQLSetParam() および SQLBindFileToParam() は、アプリケーションの値を各パラメーター・マーカーにバインドする (関連付ける) ため、またデータの転送時にデータの変換が実行される場合にそのことを示すために使用されます。
SQLExecute() を呼び出す前に、すべてのパラメーターをバインドしておく必要があります。詳細は SQLExecute - ステートメントの実行を参照してください。
パラメーター・マーカーに関する規則については、 SQL 解説書 の PREPARE のセクションを参照してください。
アプリケーションが SQLExecute() 呼び出しからの結果を処理した後で、新しい (または同じ) パラメーター値で再度ステートメントを実行することができます。
SQL ステートメントを COMMIT または ROLLBACK とすることはできません。 SQLTransact() を呼び出して COMMIT または ROLLBACK を出してください。 DB2 ユニバーサル・データベースでサポートされる SQL ステートメントの詳細については、 表 215 を参照してください。
SQL ステートメントが定位置 DELETE または定位置 UPDATE の場合は、そのステートメントで参照されるカーソルを、同じ接続ハンドルおよび同じ分離レベルの個別のステートメント・ハンドルで定義する必要があります。
戻りコード
診断
SQLSTATE | 説明 | 解説 | ||
---|---|---|---|---|
01504 | UPDATE または DELETE ステートメントに WHERE 文節がありません。 | StatementText の UPDATE ステートメントまたは DELETE ステートメントに、 WHERE 文節が入っていませんでした。 | ||
01508 | ステートメントはブロック化できませんでした。 | このステートメントは、記憶域以外の理由でブロック化できませんでした。 | ||
21S01 | 挿入値リストが列リストと一致しません。 | StatementText に INSERT ステートメントがあり、挿入する値の数が派生表の程度と一致していませんでした。 | ||
21S02 | 派生表の程度が列リストと一致しません。 | StatementText に CREATE VIEW ステートメントがあり、指定された名前の数は、照会指定で定義されている派生表と同じ程度になっていません。 | ||
22018 | キャスト仕様の文字値が無効です。 | *StatementText にリテラルまたはパラメーターを含む SQL ステートメントがあり、この値には関連した表の列のデータ・タイプとの互換がありませんでした。 | ||
22019 | 無効なエスケープ文字 | 引き数 StatementText の WHERE 文節に ESCAPE 付きの LIKE 述部があり、 ESCAPE の後に続エスケープ文字の長さが 1 と等しくありませんでした。 | ||
22025 | 無効なエスケープ・シーケンス | 引き数 StatementText の WHERE 文節に「LIKE パターン値 ESCAPE エスケープ文字」があり、パターン値のエスケープ文字の後の文字は "%" でも "_" でもありませんでした。 | ||
24000 | カーソル状態が無効です。 | カーソルはすでに、ステートメント・ハンドル上にオープンされています。 | ||
34000 | カーソル名が無効です。 | StatementText に、位置指定された DELETE または位置指定された UPDATE があり、実行中のステートメントで参照されているカーソルはオープンされていませんでした。 | ||
37xxx a | SQL 構文が無効です。 | StatementText に、次のうちの 1 つ以上が含まれていました。
| ||
40001 | トランザクション・ロールバック。 | この SQL ステートメントが属するトランザクションは、デッドロックまたはタイムアウトが原因でロールバックされました。 | ||
40003 08S01 | 通信リンクに障害が起きました。 | アプリケーションとデータ・ソースとの間の通信リンクが、関数の完了する前に失敗しました。 | ||
42xxx a | 構文エラーまたはアクセス規則違反。 | 425xx は、
StatementText に含まれている SQL ステートメントの実行がこの許可 ID に許可されていないことを示します。
他の 42xxx SQLSTATE は、構文の相違またはステートメントとのアクセス問題があることを示しています。 | ||
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 は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。 | ||
HY008 | 操作が取り消しになりました。 |
非同期処理が StatementHandle に対して使用可能になりました。関数が呼び出され、その実行が完了する前に、 SQLCancel() が StatementHandle で呼び出されました。そして、関数が再び StatementHandle で呼び出されました。 関数が呼び出され、その実行が完了する前に、
SQLCancel() が複数スレッドのアプリケーション内の別のスレッドから、
StatementHandle で呼び出されました。
| ||
HY009 | 引き数値が無効です。 | StatementText は、ヌル・ポインターでした。 | ||
HY010 | 関数の順序エラーです。 | 実行時データ (SQLParamData()、
SQLPutData()) 操作中に、関数が呼び出されました。
BEGIN COMPOUND と END COMPOUND の SQL 操作中に、関数が呼び出されました。 | ||
HY013 | 予期しないメモリーのハンドル・エラーが起きました。 | DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを使用することができませんでした。 | ||
HY014 | もはやハンドルはありません。 | DB2 CLI は、内部資源が原因でハンドルを割り当てることができませんでした。 | ||
HY090 | ストリングまたはバッファー長が無効です。 | 引き数 TextLength は 1 より小さい値でしたが、 SQL_NTS と等しくありませんでした。 | ||
HYT00 | タイムアウトになりました。 | データ・ソースが結果セットを返す前に、タイムアウト期間が満了しました。タイムアウトは、 Windows 3.1 や Macintosh System 7 のようなマルチタスクではないシステム上でのみサポートされています。タイムアウト期間は、 SQLSetConnectAttr() の SQL_ATTR_QUERY_TIMEOUT 属性を使用して設定することができます。 | ||
|
注: | すべての DBMS が準備時に上記の診断メッセージをすべて報告するわけではありません。したがって、 SQLExecute() を呼び出すときにもアプリケーションがこれらの条件を処理できなければなりません。 |
許可
なし。
(ここで完全サンプル tbread.c を使用することもできます 。)
/* From the CLI sample TBREAD.C */ /* ... */ /* prepare the statement */ printf("\n Prepare the statement\n"); printf(" %s\n", stmt); sqlrc = SQLPrepare( hstmt, stmt, SQL_NTS ) ; STMT_HANDLE_CHECK( hstmt, sqlrc);
参照