CLI の手引きおよび解説書

SQLExtendedPrepare - ステートメントの準備とステートメント属性の設定

目的


仕様: 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 つです。

  1. SQL ステートメントを走査して、ODBC/ベンダーのエスケープ文節を探さない。これは、 SQL_ATTR_NOSCAN ステートメント属性が SQL_NOSCAN に設定されているかのような動作になります。 SQL ステートメントに ODBC/ベンダーのエスケープ文節が含まれている場合、 SQLExtendedBind() は使用できません。
  2. SQL ステートメントに含めるパラメーター・マーカーの数を事前に (cRecords で) 指示しておく。

StatementHandleStatementText、および TextLength については、 SQLPrepare - ステートメントを準備するを参照してください。

cPars 引き数は、StatementText 内のパラメーター・マーカーの数を指示します。

引き数 cStmtType は、準備中のステートメントのタイプを指示する場合に使用します。有効な値のリストについては、『cStmtType 値のリスト』を参照してください。

最後の 3 つの引き数は、使用するステートメント属性のセットを指示する場合に使用します。この呼び出しで指定するステートメント属性には、cStmtAttrs を設定します。配列は、ステートメント属性リストの保持用とそれぞれの値の保持用に 2 つ作成してください。作成した配列を piStmtAttrpvParams に使用します。有効なステートメント属性については、SQLSetStmtAttr - ステートメントに関連したオプションの設定を参照してください。

cStmtType 値のリスト

引き数 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 つ以上が含まれていました。
  • COMMIT
  • ROLLBACK
  • 接続されたデータベース・サーバーが準備できない SQL ステートメント
  • 構文エラーを含むステートメント
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 属性を使用して設定することができます。
注:

a
xxx は、そのクラス・コードの任意の SQLSTATE を表します。たとえば、 37xxx は 37 クラスの任意の SQLSTATE を表します。
注:すべての DBMS が準備時に上記の診断メッセージをすべて報告するわけではありません。したがって、 SQLExecute() を呼び出すときにもアプリケーションがこれらの条件を処理できなければなりません。

制約

なし。

該当するサンプルの一覧については、 sqllib\samples\cli (または sqllib/samples/cli) サブディレクトリー内の README ファイルを参照してください。

参照


[ ページのトップ | 前ページ | 次ページ | 目次 | 索引 ]