CLI の手引きおよび解説書

SQLPrepare - ステートメントを準備する

目的


仕様: DB2 CLI 1.1 ODBC 1.0 ISO CLI

SQLPrepare() は、入力ステートメント・ハンドルに SQL ステートメントを関連付け、そのステートメントを DBMS に送って準備します。アプリケーションは、ステートメント・ハンドルを他の関数に渡して、この準備済みステートメントを参照することができます。

すでに照会ステートメント (または結果セットを戻す関数) でステートメント・ハンドルを使用している場合、 SQLPrepare() を呼び出す前に SQLFreeStmt() を呼び出してカーソルをクローズする必要があります。

構文

SQLRETURN   SQLPrepare       (SQLHSTMT          StatementHandle,
                              SQLCHAR      FAR  *StatementText,
                              SQLINTEGER        TextLength);

関数引き数

表 136. SQLPrepare 引き数
データ・タイプ 引き数 使用法 説明
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 の場合は、そのステートメントで参照されるカーソルを、同じ接続ハンドルおよび同じ分離レベルの個別のステートメント・ハンドルで定義する必要があります。

戻りコード

診断

表 137. SQLPrepare SQLSTATE
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 つ以上が含まれていました。
  • 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 ステートメントがあります。
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 属性を使用して設定することができます。
注:

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

許可

なし。

CLI サンプル tbread.c

(ここで完全サンプル 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);
 
 

参照


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