SQLPrepare - ステートメントの準備

目的

仕様:

DB2 CLI 1.1

ODBC 1.0

ISO CLI

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

ステートメント・ハンドルが照会ステートメント (または結果セットを戻すいずれかの関数) と一緒に以前使用されていた場合は、SQLPrepare() を呼び出す前に、SQLFreeStmt() を呼び出す必要があります。

構文

SQLRETURN   SQLPrepare       (SQLHSTMT          StatementHandle,   /* hstmt */
                              SQLCHAR      FAR  *StatementText,    /* szSqlStr */
                              SQLINTEGER        TextLength);       /* cbSqlStr */

関数の引き数

表 74. SQLPrepare の引き数

データ・タイプ	引き数	用途	説明
SQLHSTMT	`StatementHandle`	入力	ステートメント・ハンドル。
SQLCHAR	`StatementText`	入力	SQL ステートメント・ストリング。
SQLINTEGER	`TextLength`	入力	`StatementText` 引き数の内容の長さ。これは、`szSqlstr` 内の SQL ステートメントの正確な長さに設定するか、ステートメント・テキストがヌルで終了する場合には、SQL_NTS に設定する必要がある。

データ・タイプ

引き数

用途

説明

SQLHSTMT

StatementHandle

入力

ステートメント・ハンドル。

SQLCHAR

StatementText

入力

SQL ステートメント・ストリング。

SQLINTEGER

TextLength

入力

StatementText 引き数の内容の長さ。

これは、szSqlstr 内の SQL ステートメントの正確な長さに設定するか、ステートメント・テキストがヌルで終了する場合には、SQL_NTS に設定する必要がある。

使用法

SQLPrepare() を使用してステートメントを準備した後、アプリケーションでは (ステートメントが照会であった場合)、以下のいずれかの関数を呼び出して、結果セットの形式に関する情報を要求することができます。

SQLNumResultCols()
SQLDescribeCol()

SQL ステートメント・ストリングにはパラメーター・マーカーが含まれている場合があります。パラメーター・マーカーは、? 文字によって表され、SQLExecute() の呼び出し時に、アプリケーション提供の値が置き換えられる、ステートメント内の位置を示すために使用されます。バインド・パラメーター関数 SQLBindParameter() は、アプリケーション値を各パラメーター・マーカーにバインドし (関連付け)、データの転送時にいずれかのデータ変換を実行すべきかどうかを示すために使用します。

SQLExecute() を呼び出す前に、すべてのパラメーターをバインドする必要があります。詳細については、SQLExecute - ステートメントの実行を参照してください。

パラメーター・マーカーに関する規則については、「DB2 Universal Database SQL リファレンス」の PREPARE ステートメントのセクションを参照してください。

SQLExecute() 呼び出しの結果を処理した後、アプリケーションは新規 (または同じ) パラメーター値を使って、そのステートメントを再度実行することができます。

戻りコード

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

診断

表 75. SQLPrepare の SQLSTATE

SQLSTATE	説明	解説
42nnn	構文エラー。	42nnn SQLSTATE は、ステートメント関連のさまざまな構文またはアクセスに関する問題を示す。文字 nnn は、そのクラス・コードを持ついずれかの SQLSTATE を示す。例えば、42nnn は、42 クラスのいずれかの SQLSTATE を示す。
58004	予期しないシステム障害。	回復不能なシステム・エラー。
HY001	メモリーの割り振りの失敗。	DB2 CLI が、関数を実行または完了させるのに必要なメモリーを割り当てることができない。
HY009	無効な引き数値。	`StatementText` がヌル・ポインターである。
HY013	予期しないメモリー処理エラー。	DB2 CLI が、関数を実行または完了させるのに必要なメモリーにアクセスできない。
HY014	ハンドル数の限界に到達済み。	DB2 CLI が、内部リソースが原因でハンドルを割り振ることができない。
HY090	無効なストリング長またはバッファー長。	引き数 `TextLength` が 1 より小さいが、SQL_NTS と等しくない。

制約事項

なし。

関連した解説