仕様: | DB2 CLI 6.0 |
SQLExtendedPrepare() は、ステートメントの準備とステートメント属性グループの設定を 1 回の呼び出しで実行する場合に使用します。
SQLPrepare() を 1 回呼び出してから SQLSetStmtAttr() を繰り返し呼び出す代わりに、この関数を使用できます。
構文
SQLRETURN SQLExtendedPrepare( SQLHSTMT StatementHandle, SQLCHAR * StatementText, SQLINTEGER TextLength, SQLINTEGER cPars, SQLSMALLINT sStmtType, SQLINTEGER cStmtAttrs, SQLINTEGER * piStmtAttr, SQLINTEGER * pvParams );
関数引き数
表 65. SQLExtendedPrepare() 引き数
データ・タイプ | 引き数 | 使用法 | 説明 |
---|---|---|---|
SQLHSTMT | StatementHandle | 入力 | ステートメント・ハンドル。 |
SQLCHAR | StatementText | 入力 | SQL ステートメント・ストリング。 |
SQLINTEGER | TextLength | 入力 | StatementText 引き数の内容の長さ。
これは、StatementText 内の SQL ステートメントの正確な長さに設定するか、ステートメント・テキストがヌル終了の場合は SQL_NTS に設定する必要があります。 |
SQLINTEGER | cPars | 入力 | ステートメントのパラメーター・マーカーの数。 |
SQLSMALLINT | sStmtType | 入力 | ステートメント・タイプ。有効な値については、『cStmtType 値のリスト』を参照してください。 |
SQLINTEGER | cStmtAttrs | 入力 | この呼び出しで指定するステートメント属性の数。 |
SQLINTEGER | piStmtAttr | 入力 | 設定するステートメント属性の配列。 |
SQLINTEGER | pvParams | 入力 | 設定する、対応するステートメント属性値の配列。 |
使用法
この関数の最初の 3 つの引き数は、SQLPrepare() の引き数とまったく同じです。
SQLExtendedBind() 使用時の要件は、以下の 2 つです。
StatementHandle、StatementText、および TextLength については、 SQLPrepare - ステートメントを準備するを参照してください。
cPars 引き数は、StatementText 内のパラメーター・マーカーの数を指示します。
引き数 cStmtType は、準備中のステートメントのタイプを指示する場合に使用します。有効な値のリストについては、『cStmtType 値のリスト』を参照してください。
最後の 3 つの引き数は、使用するステートメント属性のセットを指示する場合に使用します。この呼び出しで指定するステートメント属性には、cStmtAttrs を設定します。配列は、ステートメント属性リストの保持用とそれぞれの値の保持用に 2 つ作成してください。作成した配列を piStmtAttr と pvParams に使用します。有効なステートメント属性については、SQLSetStmtAttr - ステートメントに関連したオプションの設定を参照してください。
引き数 cStmtType は、以下のどれかの値に設定できます。
戻りコード
診断
表 66. SQLExtendedPrepare SQLSTATE
SQLSTATE | 説明 | 解説 | ||
---|---|---|---|---|
01000 | 警告。 | 通知メッセージ。 (関数は、SQL_SUCCESS_WITH_INFO を戻します。) | ||
01504 | UPDATE または DELETE ステートメントに WHERE 文節がありません。 | StatementText の UPDATE ステートメントまたは DELETE ステートメントに、 WHERE 文節が入っていませんでした。 | ||
01508 | ステートメントはブロック化できませんでした。 | このステートメントは、記憶域以外の理由でブロック化できませんでした。 | ||
01S02 | オプション値が変更されました。 | DB2 CLI は *pvParams の指定値をサポートしていないか、または *pvParams の指定値が SQL の制約および要件にかなっていないため、 DB2 CLI が同等の値を代用しました。 (関数は、SQL_SUCCESS_WITH_INFO を戻します。) | ||
08S01 | 通信リンクに障害が起きました。 | 関数が処理を完了する前に、DB2 CLI とその接続先データ・ソースとの間の通信リンクが失敗しました。 | ||
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 ステートメントがあります。 | ||
HY000 | 一般的なエラーです。 | 特定の SQLSTATE がなかった場合のエラーが発生しました。 SQLGetDiagRec() により *MessageText バッファーに返されたエラー・メッセージに、そのエラーと原因が記述されています。 | ||
HY001 | メモリーの割り振り失敗です。 | DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。 | ||
HY008 | 操作が取り消しになりました。 |
非同期処理が StatementHandle に対して使用可能になりました。関数が呼び出され、その実行が完了する前に、 SQLCancel() が StatementHandle で呼び出されました。そして、関数が再び StatementHandle で呼び出されました。 関数が呼び出され、その実行が完了する前に、
SQLCancel() が複数スレッドのアプリケーション内の別のスレッドから、
StatementHandle で呼び出されました。
| ||
HY009 | 引き数値が無効です。 | StatementText は、ヌル・ポインターでした。 | ||
HY010 | 関数の順序エラーです。 | 実行時データ (SQLParamData()、SQLPutData()) 操作中に、関数が呼び出されました。
BEGIN COMPOUND と END COMPOUND SQL の操作中に、関数が呼び出されました。 | ||
HY011 | この段階で操作は無効です。 | Attribute が、SQL_ATTR_CONCURRENCY、 SQL_ATTR_CURSOR_TYPE、 SQL_ATTR_SIMULATE_CURSOR、または SQL_ATTR_USE_BOOKMARKS であり、ステートメントが準備済みでした。 | ||
HY013 | 予期しないメモリーのハンドル・エラーが起きました。 | DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを使用することができませんでした。 | ||
HY014 | もはやハンドルはありません。 | DB2 CLI は、内部資源が原因でハンドルを割り当てることができませんでした。 | ||
HY017 | 自動割り振りの記述子ハンドルについて無効な使用です。 | Attribute 引き数が SQL_ATTR_IMP_ROW_DESC または SQL_ATTR_IMP_PARAM_DESC でした。 Attribute 引き数が SQL_ATTR_APP_ROW_DESC または SQL_ATTR_APP_PARAM_DESC であり、*ValuePtr の値が、暗黙的に割り当てられた記述子ハンドルでした。 | ||
HY024 | 属性値が無効です。 | 指定済みの Attribute 値が与えられているので、 *ValuePtr に指定されたのは無効な値でした。 (DB2 CLI がこの SQLSTATE を戻すのは、 SQL_ATTR_ACCESS_MODE や SQL_ATTR_ASYNC_ENABLE などの離散的な値セットを受け入れる接続およびステートメント属性に対してのみです。その他すべての接続およびステートメント属性に対しては、ドライバーで *ValuePtr の指定値を検査する必要があります。) | ||
HY090 | ストリングまたはバッファー長が無効です。 | 引き数 TextLength は 1 より小さい値でしたが、SQL_NTS と等しくありませんでした。 | ||
HY092 | オプション・タイプが範囲外です。 | DB2 CLI のこのバージョンでは、引き数 Attribute の指定値が無効です。 | ||
HYC00 | ドライバーが機能していません。 | 引き数 Attribute に指定された値は、このバージョンの DB2 CLI ドライバーには有効な接続またはステートメント属性でしたが、データ・ソースによりサポートされていませんでした。 | ||
HYT00 | タイムアウトになりました。 | データ・ソースが結果セットを返す前に、タイムアウト期間が満了しました。タイムアウトは、 Windows 3.1 や Macintosh System 7 のようなマルチタスクではないシステム上でのみサポートされています。タイムアウト期間は、 SQLSetConnectAttr() の SQL_ATTR_QUERY_TIMEOUT 属性を使用して設定することができます。 | ||
|
注: | すべての DBMS が準備時に上記の診断メッセージをすべて報告するわけではありません。したがって、 SQLExecute() を呼び出すときにもアプリケーションがこれらの条件を処理できなければなりません。 |
制約
なし。
該当するサンプルの一覧については、 sqllib\samples\cli (または sqllib/samples/cli) サブディレクトリー内の README ファイルを参照してください。
参照