仕様: | DB2 CLI 2.1 | ODBC 2.0 |
SQLBindParameter() は、 SQL ステートメント内のパラメーター・マーカーを以下のいずれかに関連付ける (バインドする) ために使用します。
別の方法として、 SQLBindFileToParam() を使用して LOB パラメーターをファイルに直接バインドすることができます。
この関数は、パラメーターを入力または出力 (あるいはその両方) できるストアード・プロシージャー CALL ステートメントのパラメーターに、アプリケーション記憶域をバインドするときにも使用しなければなりません。この関数は、基本的には SQLSetParam() の拡張です。
構文
SQLRETURN SQL_API SQLBindParameter( SQLHSTMT StatementHandle, /* hstmt */ SQLUSMALLINT ParameterNumber, /* ipar */ SQLSMALLINT InputOutputType, /* fParamType */ SQLSMALLINT ValueType, /* fCType */ SQLSMALLINT ParameterType, /* fSqlType */ SQLUINTEGER ColumnSize, /* cbColDef */ SQLSMALLINT DecimalDigits, /* ibScale */ SQLPOINTER ParameterValuePtr,/* rgbValue */ SQLINTEGER BufferLength, /* cbValueMax */ SQLINTEGER *FAR StrLen_or_IndPtr);/* pcbValue */
関数引き数
データ・タイプ | 引き数 | 使用法 | 説明 | ||
---|---|---|---|---|---|
SQLHSTMT | StatementHandle | 入力 | ステートメント・ハンドル | ||
SQLUSMALLINT | ParameterNumber | 入力 | パラメーター・マーカーは、1 を最初の番号として順次左から右へ番号が付けられます。 | ||
SQLSMALLINT | InputOutputType | 入力 | パラメーターのタイプ。
IPD の SQL_DESC_PARAMETER_TYPE フィールドの値も、この引き数に設定されます。サポートされるタイプは次のとおりです。
| ||
SQLSMALLINT | ValueType | 入力 | パラメーターの C データ・タイプ。以下のタイプがサポートされます。
SQL_C_DEFAULT を指定すると、データが省略時の C データ・タイプから ParameterType で指定するタイプに転送されることになります。
| ||
SQLSMALLINT | ParameterType | 入力 | パラメーターの SQL データ・タイプ。サポートされるタイプは次のとおりです。
| ||
SQLUINTEGER | ColumnSize | 入力 | 対応するパラメーター・マーカーの精度。
ParameterType が以下を表している場合、次のようになります。
| ||
SQLSMALLINT | DecimalDigits | 入力 | ParameterType が SQL_DECIMAL または SQL_NUMERIC である場合、相当するパラメーターの位取り。
ParameterType が SQL_TYPE_TIMESTAMP である場合は、これはタイム・スタンプの文字表示の小数点の右側の桁数です (たとえば、
yyyy-mm-dd hh:mm:ss.fff の位取りは 3 になります)。
上記以外の ParameterType 値の場合は、DecimalDigits は無視されます。 | ||
SQLPOINTER | ParameterValuePtr | 入力 (据え置き) または出力 (据え置き) (あるいはその両方) |
| ||
SQLINTEGER | BufferLength | 入力 | 文字データと 2 進データの場合、
BufferLength は、
ParameterValuePtr バッファーの長さを指定するか (そのバッファーが単一要素として扱われる場合)、または ParameterValuePtr 配列内の個々の要素の長さを指定します (アプリケーションが SQLParamOptions() を呼び出して各パラメーターに複数の値を指定する場合)。文字および 2 進以外のデータの場合、この引き数は無視されます。つまり、ParameterValuePtr のバッファーの長さ (単一要素である場合) または ParameterValuePtr 配列内の各要素の長さ (SQLParamOptions() を使用して各パラメーターに値の配列を指定する場合) は、
C データ・タイプに関連した長さであることが前提とされます。
出力パラメーターの場合、BufferLength を使用して、以下の方法で文字または 2 進出力データを切り捨てるかどうかを判別します。
| ||
SQLINTEGER * | StrLen_or_IndPtr | 入力 (据え置き) または出力 (据え置き) (あるいはその両方) |
これが入力または入出力パラメーターである場合:
これは、 ParameterValuePtr に保管されているパラメーター・マーカー値の長さを (ステートメントの実行時に) 入れる場所を指すポインターです。
パラメーター・マーカーに NULL 値を指定するには、この記憶場所に SQL_NULL_DATA を入れる必要があります。
ValueType が SQL_C_CHAR である場合、この記憶場所には、 ParameterValuePtr に保管されているデータの正確な長さか、または ParameterValuePtr の内容がヌル終了の場合は SQL_NTS が入っていなければなりません。
ValueType が (明示的に、または SQL_C_DEFAULT を使用して暗黙的に) 文字データを示し、かつこのポインターが NULL に設定されている場合、アプリケーションが常に ParameterValuePtr にヌル終了のストリングを提供すると想定されています。また、このことは、このパラメーター・マーカーがヌル値ではありえないことをも暗黙指定しています。
ParameterType が図形データ・タイプを表し、かつ ValueType が SQL_C_CHAR である場合は、 StrLen_or_IndPtr を指すポインターは、NULL ではあり得ず、 StrLen_or_IndPtr の内容が SQL_NTS を保持することもあり得ません。一般に図形データ・タイプの場合、この長さは 2 バイト・データが占有するオクテットの数であり、したがってこの長さは常に 2 の倍数になります。実際に、長さが奇数である場合には、ステートメントを実行しようとするとエラーが発生します。
SQLExecute() または SQLExecDirect() が呼び出され、かつ StrLen_or_IndPtr が SQL_DATA_AT_EXEC の値を指していると、パラメーターの値は SQLPutData() によって送信されます。このパラメーターは、実行時データ・パラメーターと呼ばれます。
| ||
SQLINTEGER * | StrLen_or_IndPtr (cont) | 入力 (据え置き) または出力 (据え置き) (あるいはその両方) |
SQLParamOptions() を使用して各パラメーターに複数の値を指定する場合、 StrLen_or_IndPtr は SQLINTEGER 値の配列 (各要素が対応する ParameterValuePtr 要素 (ヌル終了を除く) 内のバイト数となり得る)、または SQL_NULL_DATA を指します。
- これが出力パラメーターである (InputOutputType が SQL_PARAM_OUTPUT に設定されている) 場合:
これは、出力パラメーターまたはストアード・プロシージャー呼び出し (CALL) でなければならず、ストアード・プロシージャー実行後に以下のいずれかを指します。
|
使用法
パラメーター・マーカーは "?" 文字で表され、アプリケーションに提供された値がステートメントの実行時に置き換えられるステートメント内の位置を指示するのに使用されます。この値は、次のものから得られます。
SQLBindParameter() (または SQLSetParam()) は、アプリケーション記憶域をパラメーター・マーカーにバインドするのに使用されます。
SQLBindParameter() (または SQLSetParam()) は、 LOB ロケーターをパラメーター・マーカーにバインドするのに使用されます。 LOB 値自体はデータベース・サーバーで得られるため、 LOB ロケーターだけがデータベース・サーバーとアプリケーションの間で転送されます。
アプリケーションは、SQLGetSubString()、SQLGetPosition()、または SQLGetLength() のどれかでロケーターを使用することができます。 SQLGetSubString() は、別のロケーターか、またはデータ自体を返すことができます。すべてのロケーターは、そのロケーターを作成したトランザクションの終了まで (カーソルが別の行へ移動した場合も含む)、または FREE LOCATOR ステートメントで解放されるまで有効です。
LOB パラメーター・マーカーにファイルをバインドするには、SQLBindFileToParam() を使用します。 SQLExecDirect() を実行すると、 DB2 CLI はファイルの内容をデータベース・サーバーに直接転送します。
アプリケーションは、SQL ステートメントを実行する前に、その SQL ステートメント内の各パラメーター・マーカーに変数をバインドする必要があります。この関数の場合、 ParameterValuePtr および StrLen_or_IndPtr が据え置き引き数であり、ステートメント実行時には記憶場所が有効であり、かつ入力データ値が入っていなければなりません。このことは、 SQLExecDirect() または SQLExecute() 呼び出しが SQLBindParameter() 呼び出しと同じプロシージャー有効範囲に保持されているか、またはこれらの記憶場所が動的に割り振られているか静的またはグローバルに宣言されているかのいずれかです。
SQLBindParameter() (または SQLSetParam()) は、結果セットの列が知られている場合は、SQLPrepare() の前に呼び出すことができます。それ以外の場合は、ステートメントが作成された後で結果セットの属性を獲得できます。
パラメーター・マーカーは、番号 (ColumnNumber) で参照され、 1 から始まって、左から右へ、連続した番号が付けられます。
この関数によってバインドされるすべてのパラメーターは、以下のいずれかのときまで有効です。
SQL ステートメントを実行し、結果を処理した後、アプリケーションはステートメント・ハンドルを再利用して別の SQL ステートメントを実行したい場合があります。パラメーター・マーカーの仕様 (パラメーターの数、長さ、またはタイプ) が異なる場合、パラメーターのバインドをリセットまたはクリアするには、 SQL_RESET_PARAMS を指定して SQLFreeStmt() を呼び出す必要があります。
ValueType によって指定された C バッファー・データ・タイプは、 ParameterType によって指定される SQL データ・タイプと互換性がなければならず、そうでない場合はエラーが発生します。
アプリケーションは、パラメーターの値を、 ParameterValuePtr バッファーに入れて、または SQLPutData() への 1 つまたは複数の呼び出しによって、渡すことができます。呼び出しを用いた場合、パラメーターは実行時データ・パラメーターになります。アプリケーションは、SQL_DATA_AT_EXEC 値を StrLen_or_IndPtr バッファーに置くことによって、 DB2 CLI に実行時データ・パラメーターについて通知します。また、 ParameterValuePtr 入力引き数を 32 ビット値に設定して、次の SQLParamData() 呼び出しの際に返されるようにし、パラメーター位置を表すのに使用できるようにします。
ParameterValuePtr と StrLen_or_IndPtr で参照される変数内のデータはステートメントを実行するまで検査されないため、データの内容または形式のエラーは SQLExecute() または SQLExecDirect() を呼び出すまで検出も報告もされません。
SQLBindParameter() は、以下のことを行う方法を提供することにより、実質的には SQLSetParam() 関数の機能を拡張したものとなっています。
InputOutputType 引き数は、パラメーターのタイプを指定します。プロシージャーを呼び出さない SQL ステートメント内のパラメーターは、すべて入力パラメーターです。ストアード・プロシージャー呼び出しのパラメーターは、入力、入出力、または出力パラメーターにすることができます。すべてのプロシージャー引き数が入出力であることを DB2 ストアード・プロシージャー引き数規則で一般に暗黙指定している場合でも、アプリケーション・プログラマーはこれまでどおり SQLBindParameter() に関する入力や出力の性質をさらに正確に指定して、さらに厳格なコーディング・スタイルに従うことができます。
同様に、InputOutputType が SQL_PARAM_OUTPUT または SQL_PARAM_INPUT_OUTPUT に設定されている場合、 ParameterValuePtr および StrLen_or_IndPtr バッファー位置は、 CALL ステートメントが実行されるまで有効でなければなりません。
文字データと 2 進 C データの場合、 BufferLength 引き数は ParameterValuePtr バッファーが単一要素である場合にそのバッファーの長さを指定します。一方、アプリケーションが SQLParamOptions() を呼び出して各パラメーターに複数値を指定する場合、 BufferLength は、ヌル終了を含む ParameterValuePtr 配列内の個々の 要素の長さになります。アプリケーションが複数値を指定する場合、 BufferLength を使用して ParameterValuePtr 配列内の値の位置を判別します。その他の C データ・タイプの場合はすべて、BufferLength 引き数は無視されます。
アプリケーションは、パラメーターの値を、 ParameterValuePtr バッファーに入れて、または SQLPutData() への 1 つまたは複数の呼び出しによって、渡すことができます。呼び出しを用いた場合、パラメーターは実行時データ・パラメーターになります。アプリケーションは、SQL_DATA_AT_EXEC 値を StrLen_or_IndPtr バッファーに置くことによって、 DB2 CLI に実行時データ・パラメーターについて通知します。また、ParameterValuePtr 入力引き数を 32 ビット値に設定して、次の SQLParamData() 呼び出しの際に返されるようにし、パラメーター位置を表すのに使用できるようにします。
SQLBindParameter() を使用してアプリケーション変数をストアード・プロシージャーの出力パラメーターにバインドする場合、 ParameterValuePtr バッファーが StrLen_or_IndPtr バッファーの後のメモリーに連続的に置かれると、 DB2 CLI ではある程度パフォーマンスを拡張できます。たとえば、
struct { SQLINTEGER StrLen_or_IndPtr; SQLCHAR ParameterValuePtr[MAX_BUFFER]; } column;
パラメーターは、ファイルまたは記憶場所のいずれか一方にのみバインドすることができ、その両方にバインドすることはできません。最新のバインド・パラメーター関数呼び出しは、有効なバインドを判別します。
ターゲットの列または出力パラメーターの実サイズが分からない場合、アプリケーションは列の長さとして 0 を指定できます。 (ColumnSize を 0 に設定する)。
以前のリリースでは、 ColumnSize が 0 に設定されていると DB2 CLI は列のデータ・タイプに可能な最大サイズを使用しました。場合によっては、これにより不必要に大きなメモリー・ブロックが割り振られる結果となりました。バージョン 6 で、この動作は変更されました。
列のデータ・タイプが固定長の場合、 DB2 CLI ドライバーは長さをデータ・タイプそのものから判別します。しかし、データ・タイプが文字、2 進ストリング、またはラージ・オブジェクトである場合、 ColumnSize を 0 に設定すると別の意味を持ちます。
ColumnSize を 0 に設定する必要がなければ、そうすることは勧められていません。それにより、DB2 CLI は実行時にデータの長さを不必要にチェックすることになるからです。
パラメーター・バインドの変更の必要が生じた場合、アプリケーションはもう一度 SQLBindParameter() を呼び出すことができます。これにより、バインドされているパラメーターのバッファー・アドレスと、それに対応する使用中の長さ / 標識バッファー・アドレスを変更します。
SQLBindParameter() への複数の呼び出しの代わりに、 DB2 CLI はパラメーター・バインドの相対位置もサポートしています。毎回再バインドするよりも、相対位置を使用すると、 SQLExecute() または SQLExecDirect() への次の呼び出しで使用される新しいバッファー・アドレスおよび長さ / 標識アドレスを指定することができます。これは、列方向配列の挿入では使用できませんが、アプリケーションが個々にまたは配列を使用してパラメーターをバインドするかどうかを決めます。
相対位置を使用するのに必要なステップのリストについては、 パラメーター・バインドの相対位置を参照してください。
記述子
パラメーターのバインド方法は、APD および IPD のフィールドによって決定されます。 SQLBindParameter 内の引き数を使用して、その記述子フィールドを設定します。そのフィールドは、また、SQLSetDescField 関数によっても設定できます。 SQLBindParameter は、使用効率が良く、アプリケーションが SQLBindParameter を呼び出すのに記述子ハンドルを獲得する必要はありません。
注: | 1 つのステートメントについての SQLBindParameter() の呼び出しは、他のステートメントに影響することがあり得ます。それが生じるのは、ステートメントに関連した ARD が明示的に割り当てられ、それらが他のステートメントにも関連しているような場合です。 SQLBindParameter() は APD のフィールドを修正するため、この記述子が関連付けられているすべてのステートメントにその修正が適用されます。これが必須の動作でない場合、アプリケーションは、 SQLBindParameter() を呼び出す前に、その他のステートメントとの記述子の関連付けを解除する必要があります。 |
概念的には、SQLBindParameter() は、以下のステップを順次実行します。
StrLen_or_Ind パラメーターは、標識情報およびパラメーター値の長さの両方を指定します。
SQLBindParameter() への呼び出しが失敗したときは、それが APD に設定するはずの記述子の内容フィールドは未定義で、 APD の SQL_DESC_COUNT フィールドは変更されません。さらに、IPD 内の適当なレコードの SQL_DESC_LENGTH、SQL_DESC_PRECISION、SQL_DESC_SCALE、および SQL_DESC_TYPE フィールドは未定義で、 IPD の SQL_DESC_COUNT フィールドは変更されません。
戻りコード
診断
表 22. SQLBindParameter SQLSTATE
SQLSTATE | 説明 | 解説 |
---|---|---|
07006 | 変換が無効です。 | ValueType 引き数によって識別されるデータ値から ParameterType 引き数によって識別されるデータ・タイプへの変換は、意味のある変換ではありません。 (たとえば、SQL_C_DATE から SQL_DOUBLE への変換は無意味です。) |
40003 08S01 | 通信リンクに障害が起きました。 | アプリケーションとデータ・ソースとの間の通信リンクが、関数の完了する前に失敗しました。 |
58004 | 予期しないシステム障害です。 | 回復不能システム・エラー。 |
HY001 | メモリーの割り振り失敗です。 | DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。 |
HY003 | プログラム・タイプが範囲外です。 | 引き数 ParameterNumber で指定された値が、有効なデータ・タイプまたは SQL_C_DEFAULT ではありません。 |
HY004 | SQL のデータ・タイプが範囲外です。 | 引き数 ParameterType に指定された値が、有効な SQL データ・タイプではありません。 |
HY009 | 引き数値が無効です。 | 引き数 ParameterValuePtr は NULL ポインターで、引き数 StrLen_or_IndPtr は NULL ポインターであり、 InputOutputType は SQL_PARAM_OUTPUT ではありません。 |
HY010 | 関数の順序エラーです。 | SQLExecute() または SQLExecDirect() が SQL_NEED_DATA を返した後に関数が呼び出されましたが、すべての実行時データ・パラメーターに関するデータは送られませんでした。 |
HY013 | 予期しないメモリーのハンドル・エラーが起きました。 | DB2 CLI は、関数の実行または完了をサポートするのに必要なメモリーを使用することができませんでした。 |
HY021 | 不整合な記述子情報 | 整合性検査時に検査された記述子情報は、整合性がとれていませんでした。 |
HY090 | ストリングまたはバッファー長が無効です。 | 引き数 BufferLength に指定された値は、0 より小さい値でした。 |
HY093 | パラメーターの数値が無効です。 | 引き数 ValueType に指定された値が、1 より小さいか、サーバーでサポートされる最大数より大きい値でした。 |
HY094 | 位取り値が無効です。 | ParameterType に指定された値が SQL_DECIMAL または SQL_NUMERIC であり、
DecimalDigits に指定された値が 0 より小さいかまたは引き数 ParamDef (精度) の値より大きい値でした。
ParameterType に指定された値が SQL_C_TIMESTAMP で、 ParameterType に指定された値が SQL_CHAR または SQL_VARCHAR のどちらかであり、 DecimalDigits に指定された値が 0 より小さいかまたは 6 より大きい値でした。 |
HY104 | 精度値が無効です。 | ParameterType に指定された値が SQL_DECIMAL または SQL_NUMERIC のどちらかで、 ParamDef に指定された値が 1 より小さい値でした。 |
HY105 | パラメーター・タイプが無効です。 | InputOutputType が SQL_PARAM_INPUT、SQL_PARAM_OUTPUT、または SQL_PARAM_INPUT_OUTPUT のいずれでもありません。 |
HYC00 | ドライバーが機能していません。 | DB2 CLI またはデータ・ソースが、引き数 ValueType に指定された値と引き数 ParameterType に指定された値との組み合わせによって指定された変換をサポートしません。
引き数 ParameterType に指定された値が、 DB2 CLI またはデータ・ソースのどちらかでサポートされていません。 |
制約
DB2 CLI v5 と ODBC 2.0 では、この関数は SQLSetParam() に代わるものとして用いられます。
StrLen_or_IndPtr の新しい値 SQL_DEFAULT_PARAM が ODBC 2.0 に導入され、プロシージャーで使用する値を、アプリケーションから送信された値ではなく、パラメーターの省略時値にするように指定できるようになりました。 DB2 ストアード・プロシージャーの引き数には省略時値の概念がないため、StrLen_or_IndPtr 引き数にこの値を指定すると、 SQL_DEFAULT_PARAM 値は無効な長さとみなされ、 CALL ステートメントを実行したときにエラーになります。
また、ODBC 2.0 には、StrLen_or_IndPtr 引き数を指定して使用する SQL_LEN_DATA_AT_EXEC (length) マクロも導入されました。このマクロは、後続の SQLPutData() 呼び出しを経由して文字または C データ用に送信されるデータ全体の長さの合計を指定するために使用されます。 DB2 ODBC ドライバーではこの情報の必要がないため、このマクロは必要ありません。 ODBC アプリケーションは、 SQLGetInfo() に SQL_NEED_LONG_DATA_LEN オプションを指定して、ドライバーがこの情報を必要とするかどうかを調べます。 DB2 ODBC ドライバーは、この情報が SQLPutData() に必要ないことを示す場合、'N' を戻します。
以下に、さまざまなデータ・タイプをバインドして、一組のパラメーターに結合する例を示します。追加の例については、ストアード・プロシージャーの例を参照してください。
(ここで完全サンプル tbread.c を使用することもできます 。)
/* From the CLI sample TBREAD.C */ /* ... */ /* bind divisionParam to the statement */ printf(" Bind divisionParam to the statement\n"); printf(" %s\n", stmt); sqlrc = SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR, 15, 0, divisionParam, 15, NULL);
参照