SQL ステートメントのパラメーターをバインドするための関数

SQLExecute() が後に続く SQLPrepare() および SQLExecDirect() の両方とも、 これによって、式またはホスト変数 (例えば、組み込み SQL) の代わりにパラメーター・マーカー を使用する SQL ステートメントを実行することができます。

パラメーター・マーカーとは、SQL ステートメントの中に入れておく疑問符 (?) の文字のことです。 このパラメーター・マーカーを含んでいるステートメントを実行すると、これらのマーカーは ホスト変数の内容と置き換えられます。

バインディングすることによって、アプリケーション変数は パラメーター・マーカーに関連付けられます。 アプリケーションは、SQL ステートメントにあるそれぞれの パラメーター・マーカーにアプリケーション変数をバインドしてはじめて、 そのステートメントを実行することができます。 パラメーターをバインドするには、数値で表したパラメーター位置、パラメーターの SQL タイプ、 変数のデータ・タイプ、アプリケーション変数へのポインター、および変数の長さを示す 適切な引数を用いて、SQLBindParameter() を呼び出します。

パラメーター・マーカーは、ODBC 関数呼び出しの際に SQL ステートメント内で、 左から右へ、1 から開始して順次に参照します。SQLNumParams() を呼び出して、ステートメント 内のパラメーターの数を判別することができます。

バインドされたアプリケーション変数とそれに関連する長さ は、据え置き 入力引数と呼ばれます。 これらの引数が据え置きと呼ばれる理由は、パラメーターがバインドされるときにポインター しか渡されないためです。つまり、そのステートメントが実行されるまで、変数からデータが 読み取られることはありません。 据え置き引数によって、バインドされたパラメーター変数の内容を変更することができ、 さらに SQLExecute() への別の呼び出しによる最新の値を使用した SQL ステートメントを実行することができます。

それぞれのパラメーターごとの情報は、アプリケーションがパラメーターを オーバーライドするかアンバインドするまで、あるいはステートメント・ハンドルを ドロップするまで、有効のまま残っています。アプリケーションがパラメーターのバインドを 変更せずに SQL ステートメントを繰り返し実行すると、Db2® ODBC は実行のたびに 同じポインターを使用してデータを見つけます。 また、アプリケーションは、パラメーターのバインドを、別の据え置き変数のセットに 変更することもできます。 アプリケーションでは、フィールドをパラメーター・マーカーにバインドした 時点から、Db2 ODBC が実行時にそれらにアクセスする時点までの間に、 据え置き入力フィールドの割り振り解除または廃棄を行ってはなりません。

SQL ステートメントが必要とする以外のデータ・タイプを用いて、 パラメーターを変数にバインドすることができます。 アプリケーションでは、ソースの C データ・タイプとパラメーター・マーカー の SQL タイプは示す必要があります。Db2 ODBC は、指定された SQL データ・タイプと 一致するように、変数の内容を変換します。例えば、SQL ステートメントには整数値が必要なのに、 アプリケーションでは整数のストリング表記になっているとします。 このような場合、パラメーターにストリングをバインドすることができ、Db2 ODBC は、そのステートメント 実行時に、そのストリングを対応する整数値に変換します。必ずしもすべての C データ・タイプがパラメーター・マーカーにバインドできるとは限りません。

SQLDescribeParam() を使用すると、パラメーター・マーカーのデータ・タイプを判別することができます。 アプリケーションがパラメーター・マーカーに正しくないデータ・タイプを示した場合は、データベース・サーバーによって余分な変換が行われるか、エラーになる可能性があります。

特殊タイプをあるパラメーターに対して比較する SQL 述部を使用する場合、そのパラメーター・マーカー を特殊タイプにキャストするか、特殊タイプをソース・タイプにキャストする必要があります。そのようにしないと、エラーが起こります。