仕様: | DB2 CLI 6.0 | ODBC 3.0 |
キーセット主導カーソル上で以下の操作を実行するには、 SQLBulkOperations() を使用します。
構文
SQLRETURN SQLBulkOperations ( SQLHSTMT StatementHandle, SQLSMALLINT Operation);
関数引き数
データ・タイプ | 引き数 | 使用法 | 説明 |
---|---|---|---|
SQLHSTMT | StatementHandle | 入力 | ステートメント・ハンドル。 |
SQLSMALLINT | 操作 | 入力 | 以下を実行する操作です。
|
使用法
アプリケーションは SQLBulkOperations() を使用して、キーセット主導カーソル内の現行の照会に対応する基本表または視点に対して以下の操作を実行します。
汎用アプリケーションは、必要なバルク操作がサポートされているかどうかを最初に確認する必要があります。それを行うために、SQLGetInfo() に SQL_DYNAMIC_CURSOR_ATTRIBUTES1 および SQL_DYNAMIC_CURSOR_ATTRIBUTES2 の InfoType を指定して呼び出すことができます (たとえば、 SQL_CA1_BULK_UPDATE_BY_BOOKMARK が戻されるかどうかを確認するため)。
SQLBulkOperations() を呼び出した後は、ブロック・カーソルの位置が定義されていません。アプリケーションは SQLFetchScroll() を呼び出してカーソル位置を設定しなければなりません。アプリケーションは、 FetchOrientation 引き数として SQL_FETCH_FIRST、SQL_FETCH_LAST、 SQL_FETCH_ABSOLUTE、または SQL_FETCH_BOOKMARK を指定した SQLFetchScroll() だけを呼び出すようにしてください。アプリケーションが SQLFetch()、または FetchOrientation 引き数として SQL_FETCH_PRIOR、SQL_FETCH_NEXT、または SQL_FETCH_RELATIVE を指定した SQLFetchScroll() を呼び出した場合、カーソル位置は定義されません。
バルク操作 (SQLBulkOperations() への呼び出し) では、列を無視できます。これを行うには、SQLBindCol() を呼び出して列長 / 標識バッファー (StrLen_or_IndPtr) を SQL_COLUMN_IGNORE に設定します。これは SQL_DELETE_BY_BOOKMARK バルク操作には適用されません。詳細については、SQLBindCol - アプリケーション変数または LOB ロケーターに列をバインドするを参照してください。
この関数を使用してバルク操作を行うときに行を無視できないので、アプリケーションが SQL_ATTR_ROW_OPERATION_PTR ステートメント属性を SQLBulkOperations() の呼び出し時に設定する必要はありません。
SQL_ATTR_ROWS_FETCHED_PTR ステートメント属性が示すバッファーには、 SQLBulkOperations() への呼び出しによって影響される行数が含まれています。
Operation 引き数が SQL_ADD または SQL_UPDATE_BY_BOOKMARK であって、カーソルに関連した照会指定の選択リストに同じ列に対する複数の参照が含まれるとき、エラーが生成されます。
SQLBulkOperations() を使用してデータを挿入するため、アプリケーションは以下の一連の手順を実行します。
注: | SQL_ATTR_ROW_STATUS_PTR ステートメント属性が示す配列のサイズは SQL_ATTR_ROW_ARRAY_SIZE と等しいか、または SQL_ATTR_ROW_STATUS_PTR がヌル・ポインターでなければなりません。 |
アプリケーションが Operation 引き数に SQL_ADD を指定して SQLBulkOperations() を呼び出す前に列 0 をバインドした場合、 CLI はブックマークのあるバインドされた列 0 バッファーを新しく挿入された行によって更新します。そのために、アプリケーションはステートメントの実行前に SQL_ATTR_USE_BOOKMARKS ステートメント属性を SQL_UB_VARIABLE に設定していなければなりません。
長いデータは SQLParamData() および SQLPutData() への呼び出しを行う SQLBulkOperations() によって、複数の部分として追加できます。詳細については、このセクションの『長いデータを使用してバルク挿入およびバルク更新を行う』を参照してください。
アプリケーションは SQLBulkOperations() を呼び出す前に、 SQLFetch() または SQLFetchScroll() を呼び出す必要があります。
重複した列を含むカーソル上で Operation 引き数に SQL_ADD を指定して SQLBulkOperations() を呼び出した場合、エラーが戻されます。
SQLBulkOperations() と共にブックマークを使用してバルク更新を実行するため、アプリケーションは以下の一連の手順を実行します。
SQLBindCol() を呼び出して、更新したいデータをバインドする。データは SQL_ATTR_ROW_ARRAY_SIZE 値に等しいサイズの配列にバインドされます。さらに、SQLBindCol() を呼び出して列 0 (ブックマークの列) をバインドします。
注: | SQL_ATTR_ROW_STATUS_PTR ステートメント属性が示す配列のサイズは SQL_ATTR_ROW_ARRAY_SIZE と等しいか、または SQL_ATTR_ROW_STATUS_PTR がヌル・ポインターでなければなりません。 |
注: | アプリケーションが SQL_ATTR_ROW_STATUS_PTR ステートメント属性を設定した場合、そのアプリケーションはこの配列を検査して操作の結果を知ることができます。 |
オプションとして、SQLBulkOperations(StatementHandle, SQL_FETCH_BY_BOOKMARK) を呼び出してデータをバインドされたアプリケーション・バッファーに取り出し、更新が行われたことを確認します。
データが更新されている場合、CLI は適切な行の行状況配列の値を SQL_ROW_UPDATED に変更します。
SQLParamData() および SQLPutData() への呼び出しを行うことによって、 SQLBulkOperations() で実行されるバルク更新には長いデータを含めることができます。詳細については、このセクションの『長いデータを使用してバルク挿入およびバルク更新を行う』を参照してください。
DB2 CLI 内のブックマークは複数のカーソルにまたがることができません。つまり、アプリケーションは直前のカーソルから保存したブックマークを使用することができません。ブックマークによる更新を行う前に SQLFetch() または SQLFetchScroll() を使用して、ブックマークを取得する必要があります。
重複した列を含むカーソル上で Operation 引き数に SQL_UPDATE_BY_BOOKMARK を指定して SQLBulkOperations() を呼び出した場合、エラーが戻されます。
SQLBulkOperations() と共にブックマークを使用してバルク取り出しを実行するため、アプリケーションは以下の一連の手順を実行します。
注: | SQL_ATTR_ROW_STATUS_PTR ステートメント属性が示す配列のサイズは SQL_ATTR_ROW_ARRAY_SIZE と等しいか、または SQL_ATTR_ROW_STATUS_PTR ステートメント属性がヌル・ポインターでなければなりません。 |
DB2 CLI 内のブックマークは複数のカーソルにまたがることができません。つまり、アプリケーションは直前のカーソルから保存したブックマークを使用することができません。ブックマークによる更新を行う前に SQLFetch() または SQLFetchScroll() を使用して、ブックマークを取得する必要があります。
SQLBulkOperations() と共にブックマークを使用してバルク削除を実行するため、アプリケーションは以下の一連の手順を実行します。
注: | SQL_ATTR_ROW_STATUS_PTR ステートメント属性が示す配列のサイズは SQL_ATTR_ROW_ARRAY_SIZE と等しいか、または SQL_ATTR_ROW_STATUS_PTR ステートメント属性がヌル・ポインターでなければなりません。 |
DB2 CLI 内のブックマークは複数のカーソルにまたがることができません。つまり、アプリケーションは直前のカーソルから保存したブックマークを使用することができません。ブックマークによる更新を行う前に SQLFetch() または SQLFetchScroll() を使用して、ブックマークを取得する必要があります。
長いデータを使用してバルク挿入およびバルク更新を行う
SQLBulkOperations() を呼び出して実行するバルク挿入およびバルク更新では、長いデータを使用できます。アプリケーションが長いデータを挿入または更新するためには、前述の『バルク挿入を実行する』および『ブックマークを使用してバルク更新を実行する』の項で説明した手順に加えて、以下の手順を実行します。
アプリケーションは、 SQL_LEN_DATA_AT_EXEC(length) マクロの結果を *StrLen_or_IndPtr バッファーに入れます。列の SQL データ・タイプが SQL_LONGVARBINARY、SQL_LONGVARCHAR、または長い、データ・ソースに特定のデータ・タイプであり、 CLI が SQL_NEED_LONG_DATA_LEN 情報タイプとして「Y」を SQLGetInfo() に戻す場合、 length はパラメーターに送るデータのバイト数です。その他の場合、負でない値を指定して、その値は無視されます。
注: | data-at-execution パラメーターは data-at-execution 列と類似していますが、
SQLParamData() によって戻される値はそれぞれ異なります。
Data-at-execution 列は、 SQLBulkOperations() によって行が更新または挿入されたときにデータが SQLPutData() と共に送られる行セット内の列です。それらは SQLBindCol() にバインドされます。 SQLParamData() によって戻される値は、処理中の *TargetValuePtr バッファー内の行のアドレスです。 |
SQLBulkOperations() が SQL_NEED_DATA を戻した後でデータがすべての data-at-execution 列に送られる前に、操作が取り消されるか SQLParamData() または SQLPutData() でエラーが生じた場合、アプリケーションがステートメントまたはステートメントに関連した接続で呼び出せるのは SQLCancel()、 SQLGetDiagField()、SQLGetDiagRec()、SQLGetFunctions()、 SQLParamData()、または SQLPutData() だけです。そのステートメントで、またはそのステートメントに関連した接続で他の関数を呼び出すと、その関数は SQL_ERROR および SQLSTATE HY010 (関数順序エラー) を戻します。
CLI が data-at-execution 列のためにデータをまだ必要としているときにアプリケーションが SQLCancel() を呼び出すと、 CLI は操作を取り消します。その後、アプリケーションは SQLBulkOperations() を再び呼び出せます。取り消しによってカーソル状態または現行カーソル位置が影響を受けることはありません。
行状況の配列
SQLBulkOperations() を呼び出した後、行状況配列には行セットのデータの行ごとの状況値が含まれています。この配列内の状況値は以下の関数を呼び出した後に設定されます。
SQLFetch() または SQLFetchScroll() が SQLBulkOperations() よりも前に呼び出されていない場合、この配列は最初 SQLBulkOperations() への呼び出しによって移植されます。この配列は、SQL_ATTR_ROW_STATUS_PTR ステートメント属性によって示されます。行状況配列の要素数は、行セットの行数に等しくなければなりません。 (SQL_ATTR_ROW_ARRAY_SIZE ステートメント属性で定義されます。) 行状況配列については、SQLFetch - 次の行の取り出しを参照してください。
戻りコード
診断
表 28. SQLBulkOperations SQLSTATE
SQLSTATE | 説明 | 解説 |
---|---|---|
01000 | 警告。 | 通知メッセージ。 (関数は、SQL_SUCCESS_WITH_INFO を戻します。) |
01004 | 切り捨てられたデータ。 | Operation 引き数は SQL_FETCH_BY_BOOKMARK で、データ・タイプ SQL_C_CHAR または SQL_C_BINARY の 1 つまたは複数の列用に戻されるストリングや 2 進データは、非ブランク文字または非ヌルの 2 進データの短縮形となります。 |
01S07 | 無効な変換。 | Operation 引き数は SQL_FETCH_BY_BOOKMARK で、アプリケーション・バッファーのデータ・タイプは SQL_C_CHAR や SQL_C_BINARY ではなく、
1 つまたは複数の列用にアプリケーション・バッファーに戻されるデータは切り捨てられました。
(数値 C データ・タイプの場合、数の小数部分は切り捨てられます。時刻、タイム・スタンプ、およびインターバル C データ・タイプの場合、時刻の小数部分は切り捨てられます。)
(関数は、SQL_SUCCESS_WITH_INFO を戻します。) |
07006 | 制限付きデータ・タイプ属性違反。 | Operation 引き数は SQL_FETCH_BY_BOOKMARK であり、結果セットにある列のデータ値を、
SQLBindCol() への呼び出しで TargetType 引き数に指定されたデータ・タイプに変換できませんでした。
Operation 引き数は SQL_UPDATE_BY_BOOKMARK または SQL_ADD であり、アプリケーション・バッファー内のデータ値を結果セットにある列のデータ・タイプに変換できませんでした。 |
07009 | 記述子索引が無効です。 | 引き数 Operation は SQL_ADD であり、列は結果セット内の列数よりも大きい列番号にバインドされました。 |
21S02 | 派生した表の程度が列リストと一致しません。 | 引き数 Operation は SQL_UPDATE_BY_BOOKMARK で、どの列も更新不能でした。理由は、どの列もバインドされていないか、読取専用であるか、バインド済みの長さ / 標識バッファーが SQL_COLUMN_IGNORE であったためです。 |
22001 | 文字列データの右を切り捨てました。 | 結果セット内の列への文字または 2 進値の割り当てが、非ブランク文字 (文字の場合) または非ヌル文字 (2 進数の場合) またはバイトに切り捨てられました。 |
22003 | 範囲外の数値。 | Operation 引き数は SQL_ADD または
SQL_UPDATE_BY_BOOKMARK で、結果セットの列への数値割り当てが、数の整数部分 (小数部分ではなく) を切り捨てました。
引き数 Operation は SQL_FETCH_BY_BOOKMARK で、 1 つまたは複数のバインド済み列に数値を戻したことで、有効数字を失った可能性があります。 |
22007 | 無効な日時形式。 | Operation 引き数は SQL_ADD または
SQL_UPDATE_BY_BOOKMARK で、結果セットの列への日付またはタイム・スタンプ値の割り当てで、年、月、または日フィールドの範囲が超過しました。
引き数 Operation は SQL_FETCH_BY_BOOKMARK で、 1 つまたは複数のバインド済み列用の日付またはタイム・スタンプ値の戻りで、年、月、または日フィールドの範囲が超過した可能性があります。 |
22008 | 日 / 時フィールドの桁あふれ。 | Operation 引き数は SQL_ADD または
SQL_UPDATE_BY_BOOKMARK で、結果セットの列に送られるデータの日時計算で、結果の日時フィールド (年、月、日、時、分、または秒フィールド) が許容範囲を超えたか、または、グレゴリオ歴に基づく日時の法則に対して無効な値になりました。
Operation 引き数は SQL_FETCH_BY_BOOKMARK で、結果セットから検索されるデータの日時計算で、結果の日時フィールド (年、月、日、時、分、または秒フィールド) が許容範囲を超えたか、または、グレゴリオ歴に基づく日時の法則に対して無効な値になりました。 |
22015 | インターバル・フィールドの桁あふれ。 | Operation 引き数は SQL_ADD または SQL_UPDATE_BY_BOOKMARK で、厳密な数値またはインターバル C タイプをインターバル SQL データ・タイプに割り当てた結果、有効数字が失われました。
Operation 引き数は SQL_ADD または SQL_UPDATE_BY_BOOKMARK で、インターバル SQL タイプに割り当てるとき、インターバル SQL タイプ内に C タイプの値を表すものがありませんでした。
Operation 引き数は SQL_FETCH_BY_BOOKMARK で、厳密な数値またはインターバル SQL タイプからインターバル C タイプに割り当てた結果、先頭フィールドの有効数字が失われました。
Operation 引き数は SQL_FETCH_BY_BOOKMARK で、インターバル C タイプに割り当てるとき、インターバル C タイプ内に SQL タイプの値を表すものがありませんでした。 |
22018 | キャスト指定の文字値が無効。 | Operation 引き数は SQL_FETCH_BY_BOOKMARK で、
C タイプは厳密またはおおよその数値、日時、またはインターバル・データ・タイプです。列にある値はバインドされた C タイプの有効なリテラルではありません。
引き数 Operation は SQL_ADD または SQL_UPDATE_BY_BOOKMARK です。 SQL タイプは厳密またはおおよその数値、日時、またはインターバル・データ・タイプです。 C タイプは SQL_C_CHAR です。列にある値はバインドされた C タイプの有効なリテラルではありません。 |
23000 | 整合性制約違反。 | Operation 引き数は SQL_ADD、
SQL_DELETE_BY_BOOKMARK、または SQL_UPDATE_BY_BOOKMARK で、整合性制約の違反が生じました。
Operation 引き数は SQL_ADD で、バインドされていない列は NOT NULL と定義されていて、省略時値がありません。
Operation は SQL_ADD で、バインドされた StrLen_or_IndPtr バッファーで指定された長さは SQL_COLUMN_IGNORE で、列には省略時値がありませんでした。 |
24000 | 無効なカーソル状態。 | StatementHandle は実行状態にありましたが、 StatementHandle に関連する結果セットがありませんでした。 |
40001 | 逐次化障害。 | トランザクションは、別のトランザクションとの資源デッドロックのためにロールバックされました。 |
40003 | ステートメントの完了は不明。 | 関連した接続がこの関数の実行中に失敗して、トランザクションの状態を判別できません。 |
42000 | 構文エラーまたはアクセス違反。 | DB2 CLI は Operation 引き数で要求された操作の実行に必要な行をロックできませんでした。 |
44000 | WITH CHECK OPTION 違反。 | Operation 引き数は SQL_ADD または SQL_UPDATE_BY_BOOKMARK で、挿入または更新が視点付き表または WITH CHECK OPTION を指定して作成した視点付き表から派生した表で実行され、挿入または更新の影響を受ける 1 つ以上の行が視点付き表に含まれなくなります。 |
HY000 | 汎用エラー | 処理系固有の SQLSTATE が存在しなかったり、定義されなかった場合のエラーが発生しました。 SQLGetDiagRec() により *MessageText バッファーに返されたエラー・メッセージに、そのエラーと原因が記述されています。 |
HY001 | メモリー割り振りエラー。 | DB2 CLI は、この関数の実行または完了をサポートするために必要なメモリーを割り当てられませんでした。 |
HY008 | 操作が取り消しになりました。 | 非同期処理が StatementHandle に対して使用可能になりました。関数が呼び出され、その実行が完了する前に、
SQLCancel() が StatementHandle で呼び出されました。そして、関数が再び StatementHandle で呼び出されました。
関数が呼び出され、その実行が完了する前に、 SQLCancel() が複数スレッドのアプリケーション内の別のスレッドから、 StatementHandle で呼び出されました。 |
HY010 | 関数の順序エラーです。 |
実行時データ (SQLParamData()、SQLPutData()) 操作中に、関数が呼び出されました。 BEGIN COMPOUND と END COMPOUND SQL の操作中に、関数が呼び出されました。 非同期実行関数 (この関数ではない) が StatementHandle で呼び出され、この関数は、呼び出し時に依然実行中でした。
|
HY011 | 操作はこの時点では無効です。 | SQL_ATTR_ROW_STATUS_PTR ステートメント属性は、 SQLFetch() または SQLFetchScroll()、および SQLBulkOperations に対する呼び出しの間に設定されました。 |
HY013 | 予期しないメモリー処理エラー。 | DB2 CLI は、この関数の実行または完了をサポートするために必要なメモリーにアクセスできませんでした。 |
HY090 | ストリングまたはバッファー長が無効。 | Operation 引き数は SQL_ADD または
SQL_UPDATE_BY_BOOKMARK であり、データ値はヌル・ポインターであり、列長値は 0、SQL_DATA_AT_EXEC、SQL_COLUMN_IGNORE、
SQL_NULL_DATA のいずれでもでないか、または SQL_LEN_DATA_AT_EXEC_OFFSET 以下でした。
Operation 引き数は SQL_ADD または SQL_UPDATE_BY_BOOKMARK であり、データ値はヌル・ポインターでなく、列長値は 0 よりも小さいが、 SQL_DATA_AT_EXEC、SQL_COLUMN_IGNORE、 SQL_NTS、または SQL_NULL_DATA ではないか、または SQL_LEN_DATA_AT_EXEC_OFFSET 以下でした。
長さ / 標識バッファーの値は SQL_DATA_AT_EXEC でした。 SQL タイプは、SQL_LONGVARCHAR、 SQL_LONGVARBINARY、または長いデータ・タイプでした。また、SQLGetInfo() の情報タイプ SQL_NEED_LONG_DATA_LEN は "Y" でした。
Operation 引き数は SQL_ADD で、 SQL_ATTR_USE_BOOKMARK ステートメント属性は SQL_UB_VARIABLE に設定され、列 0 は長さがこの結果セットのブックマークの最大長に等しくないバッファーにバインドされました。 (この長さは IRD の SQL_DESC_OCTET_LENGTH フィールドに示されていて、 SQLDescribeCol()、 SQLColAttribute()、または SQLGetDescField() を呼び出すことによって取得できます。) |
HY092 | 無効な属性識別子。 | Operation 引き数に指定された値は無効でした。
Operation 引き数は SQL_ADD、 SQL_UPDATE_BY_BOOKMARK、または SQL_DELETE_BY_BOOKMARK で、 SQL_ATTR_CONCURRENCY ステートメント属性は SQL_CONCUR_READ_ONLY に設定されました。
Operation 引き数は SQL_DELETE_BY_BOOKMARK、 SQL_FETCH_BY_BOOKMARK、または SQL_UPDATE_BY_BOOKMARK で、ブックマーク列はバインドされていないか、または SQL_ATTR_USE_BOOKMARKS ステートメント属性が SQL_UB_OFF に設定されました。 |
HYC00 | 任意選択機能は実装されませんでした。 | DB2 CLI またはデータ・ソースは、 Operation 引き数で要求した操作をサポートしていません。 |
HYT00 | タイムアウトになりました。 | データ・ソースが結果セットを戻す前に、照会タイムアウト期間が満了しました。タイムアウト期間は、 Attribute 引き数として SQL_ATTR_QUERY_TIMEOUT を指定した SQLSetStmtAttr() を通じて設定します。 |
HYT01 | 接続タイムアウトになりました。 | データ・ソースが要求に応答する前に、接続タイムアウト期間が満了しました。接続タイムアウト期間は、 SQLSetConnectAttr()、SQL_ATTR_CONNECTION_TIMEOUT を使用して設定します。 |
制約
なし。
該当するサンプルの一覧については、 sqllib\samples\cli (または sqllib/samples/cli) サブディレクトリー内の README ファイルを参照してください。
参照