SQLBindParameter() - パラメーター・マーカーをバッファーまたは LOB ロケーターにバインドする
SQLBindParameter() は、パラメーター・マーカーをアプリケーション変数にバインドして、SQLSetParam() 関数の機能を拡張します。
SQLBindParameter() の ODBC 仕様
| ODBC 仕様レベル | X/Open CLI CAE 仕様 | ISO CLI 仕様 |
|---|---|---|
| 2.0 | なし | なし |
構文
31 ビット・アプリケーションの場合、次の構文を使用します。
SQLRETURN SQL_API SQLBindParameter(
SQLHSTMT hstmt,
SQLUSMALLINT ipar,
SQLSMALLINT fParamType,
SQLSMALLINT fCType,
SQLSMALLINT fSqlType,
SQLUINTEGER cbColDef,
SQLSMALLINT ibScale,
SQLPOINTER rgbValue,
SQLINTEGER cbValueMax,
SQLINTEGER FAR *pcbValue);
64 ビット・アプリケーションの場合、次の構文を使用します。
SQLRETURN SQL_API SQLBindParameter(
SQLHSTMT hstmt,
SQLUSMALLINT ipar,
SQLSMALLINT fParamType,
SQLSMALLINT fCType,
SQLSMALLINT fSqlType,
SQLULEN cbColDef,
SQLSMALLINT ibScale,
SQLPOINTER rgbValue,
SQLLEN cbValueMax,
SQLLEN FAR *pcbValue);
関数の引数
次の表は、この関数のそれぞれの引数ごとに、 データ・タイプ、用途、および説明を示しています。
| データ・タイプ | 引数 | 使用法 | 説明 |
|---|---|---|---|
| SQLHSTMT | hstmt | 入力 | バインドするステートメントのステートメント・ハンドルを指定します。 |
| SQLUSMALLINT | ipar | 入力 | パラメーター・マーカー番号を指定します。 これは、左から右へ、1 から順番に番号が付けられます。 |
| SQLSMALLINT | fParamType | 入力 | パラメーターのタイプを指定します。以下のタイプのパラメーターを指定できます。
|
| SQLSMALLINT | fCType | 入力 | パラメーターの C データ・タイプを指定します。 以下のタイプがサポートされています。
|
| SQLSMALLINT | fSqlType | 入力 | パラメーターの SQL データ・タイプを指定します。 サポートされるタイプは次のとおりです。
制約事項: SQL_BLOB_LOCATOR、SQL_CLOB_LOCATOR、および SQL_DBCLOB_LOCATOR は、アプリケーションに 関連した概念であり、CREATE TABLE での列定義ではデータ・タイプにはマップされません。 |
| SQLUINTEGER (31 ビット) または SQLULEN (64 ビット) 1 | cbColDef | 入力 | 対応するパラメーター・マーカーの精度を指定します。
この精度の意味は、以下のように、引数 fSqlType が示すデータ・タイプによって異なります。
|
| SQLSMALLINT | ibScale | 入力 | 引数 fSqlType が SQL_DECIMAL または SQL_NUMERIC の場合、対応するパラメーター
の位取りを指定します。
引数 fSqlType が SQL_TYPE_TIMESTAMP の場合、これはタイム・スタンプの文字表示における
小数点の右側の桁数です (例えば、yyyy-mm-dd hh:mm:ss.fff の位取りは 3)。
ここで述べた引数 fSqlType の値以外は、引数 ibScale は 無視されます。 |
| SQLPOINTER | rgbValue | 入力 (据え置き)、出力 (据え置き)、または入力 (据え置き) および出力 (据え置き) | 引数 rgbValue が入力引数、出力引数、またはその両方なのかによって、
以下の特性がこの引数に適用されます。
|
| SQLINTEGER (31 ビット) または SQLLEN (64 ビット) 2 | cbValueMax | 入力 | 文字およびバイナリー・データの場合、引数 cbValueMax は、 引数 rgbValue が示すバッファーのサイズ (バイト) を指定します。 このバッファーが単一エレメントの場合は、この値はそのエレメントのサイズを 指定します。 このバッファーが配列の場合は、この値はその配列の各エレメントのサイズを 指定します。SQLSetStmtAttr を呼び出して、それぞれのパラメーターごとに複数の値を指定します。文字以外およびバイナリー・データ以外の場合は、 この引数は無視されます。 この長さは、これらのケースの C データ・タイプに関連した長さである と想定されます。 出力パラメーターの場合、引数 cbValueMax を使用して、
文字またはバイナリー出力データを切り捨てるかどうかを判別します。
データは、以下の方法で切り捨てられます。
|
| SQLINTEGER * (31 ビット) SQLLEN * (64 ビット)2 | pcbValue | 入力 (据え置き)、出力 (据え置き)、または入力 (据え置き) および出力 (据え置き) | 引数 pcbValue が入力引数、出力引数、またはその両方なのかによって、 以下の特性がこの引数に適用されます。
|
| 連続する SQLINTEGER * (31-bit) SQLLEN * (64-bit)2 | pcbValue | 入力 (据え置き)、出力 (据え置き)、または入力 (据え置き) および出力 (据え置き) |
|
注:
|
|||
使用法
- すべての C タイプのアプリケーション変数または C タイプのアプリケーション変数の配列 (ストレージ・バッファー)。 アプリケーション変数の場合、SQLExecute() または SQLExecDirect() が呼び出されると、 データはアプリケーションからデータベース管理システムへ転送されます。 この転送により、データは C タイプのアプリケーション変数から、SQLBindParameter() 呼び出しで 指定した SQL タイプに変換されます。
- SQL LOB タイプ LOB ロケーター。LOB データ・タイプの場合、SQL ステートメントの実行時 に、LOB ロケーター値 (LOB データそのものではない) はサーバーに転送されます。
また、SQLBindParameter() は、アプリケーション・ストレージを ストアード・プロシージャー CALL ステートメントのパラメーターにバインドします。 このバインドのタイプでは、パラメーターは、入力、出力、または入出力両方のパラメーター が可能です。
SQLBindParameter() を呼び出して、パラメーター・マーカーをアプリケーション変数にバインドします。パラメーター・マーカーとは、SQL ステートメントに置く疑問符 (?) の文字のことです。 パラメーター・マーカーを含んでいるステートメントを実行すると、これらのマーカーは ホスト変数の内容と置き換えられます。
- ストアード・プロシージャーのパラメーターを適切に処理するために 必要なパラメーターが、入力、出力、または入出力のいずれであるかを指定できます。
- SQLSetStmtAttr を SQLBindParameter() と組み合わせて使用するときに、入力パラメーター値の配列を指定できます。 単一エレメント・アプリケーション変数を、ストアード・プロシージャー 呼び出し (CALL) ステートメントの一部ではないパラメーター・マーカーに バインドする際には、SQLSetParam() が依然として使用できます。
- アプリケーション変数。
- データベース・サーバーからの LOB 値 (LOB ロケーターを指定することにより)。
- SQLExecDirect() または SQLExecute() への呼び出しを、SQLBindParameter() への呼び出し と同じプロシージャー有効範囲に保持する。
- 入力または出力パラメーター用に使用する保管場所を動的に割り振る。
- 入力または出力パラメーター用に使用する保管場所を静的に宣言する。
- 入力または出力パラメーター用に使用する保管場所をグローバルに宣言する。
パラメーター・マーカーを LOB ロケーターにバインドする: LOB ロケーターをパラメーター・マーカーにバインドすると、データベース・サーバーは LOB 値を 提供します。 アプリケーションは、ネットワーク全体にわたって、LOB ロケーター値のみを転送します。
LOB ロケーターを用いて、SQLGetSubString()、SQLGetPosition()、または SQLGetLength() を 使用することができます。SQLGetSubString() は、別のロケーターかまたはデータ自体を 戻すことができます。 ロケーターを作成したときのトランザクションの終了まで (たとえカーソルが別の行に移った場合でも)、 あるいは FREE LOCATOR ステートメントを出すまで、ロケーターはすべて有効のまま残っています。
結果セットに関する情報を取得する: 結果セットに現れる列が分かっている場合は、SQLPrepare() の前に SQLBindParameter() を 呼び出すことができます。結果セットに現れる列が分からない場合は、照会ステートメントを準備して列属性を 取得する必要があります。
パラメーター・マーカーは、SQLBindParameter() の引数 ipar が示している番号 によって参照します。 パラメーター・マーカーは、左から右へ、1 から順番に番号が付けられています。
パラメーター・タイプを指定する: 引数 fParamType は、パラメーターのタイプを指定します。 プロシージャーを呼び出さない SQL ステートメントのパラメーターは、 すべて入力パラメーターです。 ストアード・プロシージャー呼び出しのパラメーターは、入力、 入出力、または出力のいずれかのパラメーターが可能です。 すべてのプロシージャー引数は入出力であることを Db2 ストアード・プロシージャー引数規則で 一般には暗黙指定している場合であっても、アプリケーション・プログラマーは、 入力または出力の性質をより正確に SQLBindParameter() で指定して、 さらに厳密なコーディング・スタイルに従うように選択することができます。引数 fParamType を設定する場合は、以下のような Db2 ODBC の性質を考慮してください。
- アプリケーションがプロシージャー呼び出しのパラメーターのタイプを 決定できない場合は、引数 fParamType を SQL_PARAM_INPUT に設定します。 この場合、データ・ソースがパラメーターに値を戻すと、Db2 ODBC はそれを破棄します。
- アプリケーションが、パラメーターに SQL_PARAM_INPUT_OUTPUT また は SQL_PARAM_OUTPUT としてのマークを付けており、かつ、データ・ソースが値を戻さない 場合、Db2 ODBC は引数 pcbValue が指定するバッファーを SQL_NULL_DATA に設定します。
- アプリケーションがパラメーターに SQL_PARAM_OUTPUT としてマークを付けた場合は、 そのパラメーターのデータは、CALL ステートメントが処理された後に、アプリケーションに戻されます。 引数 rgbValue および pcbValue がいずれも NULL ポインターである 場合、Db2 ODBC は出力値を破棄します。データ・ソースが出力パラメーターの値を 戻さない場合、Db2 ODBC は pcbValue バッファーを SQL_NULL_DATA に設定します。
- 引数 fParamType が SQL_PARAM_INPUT または SQL_PARAM_INPUT_OUTPUT に
設定されている場合、保管場所は有効、かつステートメント実行時には入力データ値が
入っている必要があります。
引数 rgbValue および pcbValue は据え置き引数である
ため、SQLExecDirect() または SQLExecute() のいずれかの呼び出しを SQLBindParameter() 呼び出しと
同じプロシージャー有効範囲内で保持するか、あるいは rgbValue および pcbValue の引数の値は、動的に割り振るか、それとも静的ないしはグローバルに宣言する必要があります。
同様に、引数 fParamType が SQL_PARAM_OUTPUT また は SQL_PARAM_INPUT_OUTPUT に設定されている場合、引数 rgbValue およ び pcbValue が指定するバッファーは、CALL ステートメントが実行されるまで、 有効のままになっている必要があります。
- 引数 HandleType を SQL_HANDLE_STMT に設定して、SQLFreeHandle() を呼び出します。
- 引数 fOption を SQL_RESET_PARAMS に設定して、SQLFreeStmt() を呼び出します。
- 同じパラメーター ipar 番号に対して、再度、SQLBindParameter() を呼び出します。
SQL ステートメントを実行し、結果を処理した後、 ステートメント・ハンドルを再利用して別の SQL ステートメントを 実行したい場合があります。 パラメーター・マーカーの仕様 (パラメーター数、長さ、またはタイプ) が異なる場合、 パラメーターのバインドをリセットまたはクリアするためには、SQL_RESET_PARAMS を 用いて SQLFreeStmt() を呼び出す必要があります。
fCType で与えられた C バッファー・データ・タイプは、fSqlType で 示された SQL データ・タイプと互換性がある必要があります。 互換性がない場合には、エラーが発生します。
実行時データ・パラメーターを指定する: アプリケーションは、パラメーターの値を rgbValue バッファー で渡すか、もしくは SQLPutData() に対する 1 つ以上の呼び出しによって 渡すことができます。SQLPutData() への呼び出しでは、これらのパラメーターは実行時データ・パラメーターになります。アプリケーションは、pcbValue バッファーに SQL_DATA_AT_EXEC 値を 入れることによって、Db2 ODBC に実行時データ・パラメーターを通知します。rgbValue 入力引数が 32 ビット値に設定されます。 この値は後続の SQLParamData() 呼び出しで戻され、パラメーター位置を 示すために使用することができます。
rgbValue および pcbValue によって参照される変数のデータは、 ステートメントが実行されるまで検査されないため、 データ内容のエラーまたは形式のエラーは、SQLExecute() または SQLExecDirect() が 呼び出されるまで検出されず、報告もされません。
バッファーを割り振る: 文字データおよびバイナリー C データの場合、rgbValue バッファーが単一エレメントであれば、引数 cbValueMax はそのバッファーの長さ (バイト) を指定します。 一方、アプリケーションが SQLSetStmtAttr() を呼び出し、それぞれのパラメーターごとに複数の値を指定する場合は、引数 cbValueMax は rgbValue 配列の それぞれの エレメントの長さ (バイト) を指定します。 これには、NUL 終止符も含まれます。 アプリケーションが複数の値を指定する場合、cbValueMax を使用 して rgbValue 配列の値のロケーションを決めます。他の C データ・タイプの場合は すべて、引数 cbValueMax は無視されます。
パラメーターの値は、引数 rgbValue が指定するバッファー で渡すか、もしくは SQLPutData() に対する 1 つ以上の呼び出しによって 渡すことができます。SQLPutData() への呼び出しでは、これらのパラメーターは実行時データ・パラメーターになります。アプリケーションは、pcbValue バッファーに SQL_DATA_AT_EXEC 値を 入れることによって、Db2 ODBC に実行時データ・パラメーターを通知します。rgbValue 入力引数が 32 ビット値に設定されます。 この値は後続の SQLParamData() 呼び出しで戻され、パラメーター位置を 示すために使用することができます。
- SQLSTATE 22001 -- 引数 cbColDef が 40 より小さい場合
- SQLSTATE HY104 -- 引数 cbColDef が 40 より大きい場合
struct { SQLINTEGER pcbValue;
SQLCHAR rgbValue[MAX_BUFFER];
} column;
- ODBC ドライバーは、以下の条件が両方とも満たされる場合は、EBCDIC データを
アプリケーション変数に入れます。
- CURRENTAPPENSCH = EBCDIC が初期設定ファイルで指定されているか、CURRENTAPPENSCH キーワードに指定された CCSID が EBCDIC CCSID であるか、あるいは、CURRENTAPPENSCH キーワードが初期設定ファイルで指定されていない。
- 引数 fCType が、SQLBindParameter() 呼び出しで SQL_C_CHAR または SQL_C_DBCHAR を指定している。
- ODBC ドライバーは、引数 fCType が、SQLBindParameter() 呼び出しで SQL_C_WCHAR を指定している場合は、ユニコード UCS-2 データをアプリケーション変数に入れます。
- ODBC ドライバーは、以下の条件が両方とも満たされる場合は、ユニコード UTF-8 データを
アプリケーション変数に入れます。
- CURRENTAPPENSCH = UNICODE が初期設定ファイルで指定されているか、あるいは CURRENTAPPENSCH に指定された CCSID がユニコード CCSID (1200、1208、13488 または 17584) である。
- 引数 fCType が、SQLBindParameter() 呼び出しで SQL_C_CHAR を指定している。
- ODBC ドライバーは、以下の条件が両方とも満たされる場合は、ASCII データを
アプリケーション変数に入れます。
- CURRENTAPPENSCH = ASCII が初期設定ファイルで指定されているか、あるいは CURRENTAPPENSCH に指定された CCSID が ASCII CCSID である。
- 引数 fCType が、SQLBindParameter() 呼び出しで SQL_C_CHAR または SQL_C_DBCHAR を指定している。
戻りコード
- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
- SQL_ERROR
- SQL_INVALID_HANDLE
診断
次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。
| SQLSTATE | 説明 | 説明 |
|---|---|---|
| 07006 | 変換が無効です。 | 引数 fCType によって示されるデータ値から、引数 fSqlType によって 示されるデータ・タイプへの変換は、無意味な変換です。 (例えば、SQL_C_TYPE_DATE から SQL_DOUBLE へ の変換は無意味です) |
| 08S01 | 通信リンクに障害が起きました。 | 関数が完了する前に、アプリケーションとデータ・ソース間の 通信リンクで障害が発生しました。 |
| 58004 | 予期しないシステム障害です。 | リカバリー不能なシステム・エラーが起こりました。 |
| HY001 | メモリーの割り振りに失敗しました。 | Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振ることができません。 |
| HY003 | プログラム・タイプが範囲外です。 | 引数 fCType が、有効なデータ・タイプでも SQL_C_DEFAULT でもありません。 |
| HY004 | SQL データ・タイプが無効です。 | 引数 fSqlType に指定された値が有効な SQL データ・タイプ ではありません。 |
| HY009 | NULL ポインターの使用は無効です。 | 引数 OutputHandlePtr は NULL ポインターです。 |
| HY010 | 関数シーケンス・エラーが発生しました。 | この関数は、SQLExecute() または SQLExecDirect() が SQL_NEED_DATA を戻した後に呼び出されましたが、 実行時データ・パラメーターに対してデータがすべて送信されたとは限りません。 |
| HY013 | 予期しないメモリー処理エラーです。 | Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーにアクセスできません。 |
| HY090 | ストリングまたはバッファーの長さが無効です。 | 引数 cbValueMax に指定された値が 0 より小さい値です。 |
| HY093 | パラメーター番号が無効です。 | 引数 ipar に指定された値が 1 より小さい値です。 |
| HY094 | 位取りの値が無効です。 | fSqlType に指定された値が SQL_TYPE_TIMESTAMP であり、ibScale 引数の値が 0 未満か 12 より大きい場合、HY094 が戻されます。![]() |
| HY104 | 精度値が無効です。 | 引数 fSqlType に指定された値は、SQL_DECIMAL または SQL_NUMERIC のいずれかであり、引数 cbColDef に指定された値が 1 未満であるため、この SQLSTATE が戻されます。 次の理由に該当した場合に、この SQLSTATE が戻されます。
|
| HY105 | パラメーター・タイプが無効です。 | 引数 fParamType は、以下のいずれの値も指定していません。
|
| HYC00 | ドライバーは使用できません。 | 次の 1 つ以上の理由に該当した場合に、この SQLSTATE が戻されます。
|
制約事項
引数 pcbValue の新しい値である SQL_DEFAULT_PARAM が ODBC 2.0 で導入されました。 これは、プロシージャーが、アプリケーションから送られた値ではなく、パラメーターのデフォルト値を 使用する必要がある旨を指示しています。Db2 ストアード・プロシージャーの引数はデフォルト値 を使用しないため、 引数 pcbValue に SQL_DEFAULT_PARAM を指定すると、CALL ステートメントの 実行時にエラーが生じます。 このエラーは、SQL_DEFAULT_PARAM 値の長さが無効と見なされるために起こります。
ODBC 2.0 には、引数 pcbValue と一緒に 使用する SQL_LEN_DATA_AT_EXEC(length) マクロも提供されています。 このマクロは、後続の SQLPutData() 呼び出しを用いて送信される すべての文字 C データまたはすべてのバイナリー C データの長さの合計を指定 します。Db2 ODBC ドライバーではこの情報は不要なため、このマクロは不要です。ドライバーがこの情報を必要としているかどうかをチェックするには、 引数 InfoType を SQL_NEED_LONG_DATA_LEN に設定して、SQLGetInfo() を呼び出します。 Db2 ODBC ドライバーは、SQLPutData() ではこの情報が必要ないことを示す 'N' を戻します。
例
/* ... */
SQLCHAR stmt[] =
"INSERT INTO PRODUCT VALUES (?, ?, ?, ?, ?)";
SQLINTEGER Prod_Num[NUM_PRODS] = {
100110, 100120, 100210, 100220, 100510, 100520, 200110,
200120, 200210, 200220, 200510, 200610, 990110, 990120,
500110, 500210, 300100
};
SQLCHAR Description[NUM_PRODS][257] = {
"Aquarium-Glass-25 litres", "Aquarium-Glass-50 litres",
"Aquarium-Acrylic-25 litres", "Aquarium-Acrylic-50 litres",
"Aquarium-Stand-Small", "Aquarium-Stand-Large",
"Pump-Basic-25 litre", "Pump-Basic-50 litre",
"Pump-Deluxe-25 litre", "Pump-Deluxe-50 litre",
"Pump-Filter-(for Basic Pump)",
"Pump-Filter-(for Deluxe Pump)",
"Aquarium-Kit-Small", "Aquarium-Kit-Large",
"Gravel-Colored", "Fish-Food-Deluxe-Bulk",
"Plastic-Tubing"
};
SQLDOUBLE UPrice[NUM_PRODS] = {
110.00, 190.00, 100.00, 150.00, 60.00, 90.00, 30.00,
45.00, 55.00, 75.00, 4.75, 5.25, 160.00, 240.00,
2.50, 35.00, 5.50
};
SQLCHAR Units[NUM_PRODS][3] = {
" ", " ", " ", " ", " ", " ", " ", " ", " ",
" ", " ", " ", " ", " ", "kg", "kg", "m"
};
SQLCHAR Combo[NUM_PRODS][2] = {
"N", "N", "N", "N", "N", "N", "N", "N", "N",
"N", "N", "N", "Y", "Y", "N", "N", "N"
};
SQLUINTEGER pirow = 0;
/* ... */
/* Prepare the statement */
rc = SQLPrepare(hstmt, stmt, SQL_NTS);
rc = SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_SLONG, SQL_INTEGER,
0, 0, Prod_Num, 0, NULL);
rc = SQLBindParameter(hstmt, 2, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_VARCHAR,
257, 0, Description, 257, NULL);
rc = SQLBindParameter(hstmt, 3, SQL_PARAM_INPUT, SQL_C_DOUBLE, SQL_DECIMAL,
10, 2, UPrice, 0, NULL);
rc = SQLBindParameter(hstmt, 4, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR,
3, 0, Units, 3, NULL);
rc = SQLBindParameter(hstmt, 5, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR,
2, 0, Combo, 2, NULL);
rc = SQLParamOptions(hstmt, NUM_PRODS, &pirow);
rc = SQLExecute(hstmt);
printf("Inserted
/* ... */
SQL_C_TYPE_TIMESTAMP_EXT