SQLSetPos - 行セットにカーソル位置を設定する
SQLSetPos() 行セットにカーソル位置を設定する。カーソルを一度設定すると、 それらの行のデータのリフレッシュ、更新、および削除をアプリケーションで実行できます。
SQLSetPos() の ODBC 仕様
| ODBC 仕様レベル | X/Open CLI CAE 仕様 | ISO CLI 仕様 |
|---|---|---|
| 1.0 | あり | あり |
構文
SQLRETURN SQLSetPos (
SQLHSTMT StatementHandle,
SQLSETPOSIROW RowNumber,
SQLUSMALLINT Operation,
SQLUSMALLINT LockType);
関数の引数
| データ・タイプ | 引数 | 使用法 | 説明 |
|---|---|---|---|
| SQLHSTMT | StatementHandle | 入力 | ステートメント・ハンドル。 |
| SQLUSMALLINT | RowNumber | 入力 | Operation で指定される操作が実行される行の行セット内の位置。RowNumber が 0 の場合、行セットの各行に操作が適用されます。 |
| SQLUSMALLINT | Operation | 入力 | 実行する操作:
ODBC はまた、後方互換性のためにのみ以下の操作を指定します。これも Db2® ODBC がサポートします。
Db2 ODBC が SQL_ADD を SQLSetPos() 呼び出しでサポートします。この関数は推奨できません。 代わりに SQLBulkOperations() の Operation 値を SQL_ADD に指定して使用します。 |
| SQLUSMALLINT | LockType | 入力 | Operation 引数で指定される操作の実行後の、行のロック方法を指定します。Db2 ODBC は SQL_LOCK_NO_CHANGE をサポートします。 ODBC はまた、以下の操作を指定します。これは、Db2 ODBC はサポートしません。
|
使用法
RowNumber 引数: RowNumber 引数は、Operation 引数で指定される操作が実行される行セット内の行数を指定します。RowNumber が 0 の場合、行セットの各行に操作が適用されます。RowNumber は、0 から行セット内の行数をすべて含んだものの中の値にする必要があります。
C 言語では、配列は、0 をベースにしていますが、RowNumber 引数は、1 をベースにしています。例えば、行セットの 5 番目の行を更新するには、アプリケーションは、行セットバッファーを配列指標 4 で変更しますが、RowNumber を 5 に指定します。
アプリケーションは、SQLSetPos() を呼び出す時に、カーソル位置を指定できます。 一般的に、アプリケーションは、SQL_POSITION 操作または SQL_REFRESH 操作を指定した SQLSetPos() を呼び出し、位置決めされた更新または削除ステートメントの実行または SQLGetData() の呼び出しの前にカーソルの位置を決めます。
- SQL_FORWARD_ONLY_CURSOR_ATTRIBUTES1
- SQL_DYNAMIC_CURSOR_ATTRIBUTES1
- SQL_STATIC_CURSOR_ATTRIBUTES1
- SQL_POSITION
-
Db2 ODBC は、RowNumber で指定された行にカーソルを置きます。
SQL_ATTR_ROW_STATUS_PTR ステートメント属性で示される行状況配列の内容は変更されません。SQL_ATTR_ROW_OPERATION_PTR ステートメント属性で示される行操作配列の内容は無視されます。
- SQL_REFRESH
-
Db2 ODBC は、RowNumber で指定された行にカーソルを置き、その行に対して行セット・バッファーにあるデータをリフレッシュします。行セット・バッファーに Db2 ODBC がデータを戻す方法について詳しくは、行方向および列方向バインディングの説明を参照してください。Db2 ODBC は、SQL_REFRESH での静的カーソルのみをサポートします。
Operation 値を SQL_REFRESH に設定した SQLSetPos() は、現在フェッチされている行セット内の行の状況と内容を更新します。バッファーにあるデータはリフレッシュされますが、再フェッチはされないので、 行セットにあるメンバーシップが修正されます。
SQL_ATTR_ROW_STATUS_PTR ステートメント属性で示される行状況配列の内容もリフレッシュされます。
- SQL_UPDATE
-
Db2 ODBC は、RowNumber で指定された行にカーソルを置き、下にある行のデータを行セット・バッファー内の値で更新します (SQLBindCol() の rgbValue 引数)。SQLSetPos() は、長さまたはインディケーター・バッファーからデータの長さを取り出します (SQLBindCol() の pcbValue 引数)。いずれかの列の長さが SQL_COLUMN_IGNORE の場合、列は更新されません。
行の更新後、行状況配列が既にある場合は、行状況配列に対応するエレメントが SQL_ROW_UPDATED または SQL_ROW_SUCCESS_WITH_INFO に更新されます。
SQL_ATTR_ROW_OPERATION_PTR ステートメント属性で示される行操作配列を使用して、一括更新中に現在行セットにある行が無視されるように指示することができます。
- SQL_DELETE
-
Db2 ODBC は、RowNumber で示された行にカーソルを置き、下にある行のデータを削除します。
SQL_ATTR_ROW_STATUS_PTR ステートメント属性で示される行状況配列に対応するエレメントは、SQL_ROW_DELETED に変更されます。
SQL_ATTR_ROW_OPERATION_PTR ステートメント属性で示される行操作配列を使用して、一括削除中に現在行セットにある行が無視されるように指示することができます。
- SQL_ADD
-
Db2 ODBC は、SQL_ADD 値を後方互換性のみに指定します。
推奨: SQL_ADD 値を指定した SQLPos() を呼び出す代わりに、ODBC 関数 SQLBulkOperations() の Operation 引数を SQL_ADD に指定して使用してください。
LockType 引数
LockType 引数は並行性を制御するアプリケーションのために 1 つの方法を提供します。一般的に、並行性レベルおよびトランザクションをサポートするデータ・ソースは LockType 引数の SQL_LOCK_NO_CHANGE 値のみをサポートします。
LockType 引数は、単一ステートメントのために指定されますが、ロックは同じ権限を接続上のすべてのステートメントに授けます。具体的には、接続上の 1 つのステートメントによって獲得されるロックは、同じ接続上の別のステートメントでアンロックできます。
| LockType 引数 | ロック・タイプ |
|---|---|
| SQL_LOCK_NO_CHANGE | 行が SQLSetPos() が呼び出された前と同じ状態 (ロックされているかアンロックされている) になっていることを確認します。LockType のこの値は、明示的行レベル・ロッキングをサポートしないデータ・ソースで、現行の並行性とトランザクションの分離レベルに必要とされるロッキングを使用できるようにします。 |
| SQL_LOCK_EXCLUSIVE | Db2 ODBC ではサポートされません。 行を排他的にロックします。 |
| SQL_LOCK_UNLOCK | Db2 ODBC ではサポートされません。 行をアンロックします。 |
状況配列と操作配列
- 行状況配列には、行セット内の各行のデータの状況値が含まれています。SQLFetch()、SQLFetchScroll()、または SQLSetPos() の呼び出し後、状況値はこの配列で設定されます。
- 行操作配列には、行セット内の各行の値が含まれます。これには、一括操作の場合 SQLSetPos() 呼び出しを無視するか実行するかが示されます。配列内の各エレメントは SQL_ROW_PROCEED (デフォルト) または SQL_ROW_IGNORE です。SQL_ATTR_ROW_OPERATION_PTR ステートメント属性は行操作配列を指します。
戻りコード
- SQL_SUCCESS
- SQL_SUCCESS_WITH_INFO
- SQL_NEED_DATA
- SQL_STILL_EXECUTING
- SQL_ERROR
- SQL_INVALID_HANDLE
診断
次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。
| SQLSTATE | 説明 | 説明 |
|---|---|---|
| 01000 | 警告。 | 通知メッセージ。(関数は SQL_SUCCESS_WITH_INFO を戻します。) |
| 01004 | データが切り捨てられました。 | Operation 引数は SQL_REFRESH でした。データ・タイプ SQL_C_CHAR または SQL_C_BINARY の列に対して戻されたストリングまたはバイナリー・データは、非ブランク文字または非ヌル・バイナリー・データを切り捨てました。 |
| 01S01 | 行にエラーがあります。 | RowNumber 引数は 0 でした。Operation 引数で指定された操作が実行された時に 1 つ以上の行でエラーが発生しました。 複数行操作の行で全部ではないが少なくとも一回エラーが発生した場合、SQL_SUCCESS_WITH_INFO が戻されます。単一行操作でエラーが発生した場合は、SQL_ERROR が戻されます。 |
| 01S07 | 小数部分が切り捨てられました。 | Operation 引数は SQL_REFRESH でした。アプリケーション・バッファーのデータ・タイプは SQL_C_CHAR または SQL_C_BINARY ではありませんでした。1 つ以上の列に対するアプリケーション・バッファーに戻されたデータが切り捨てられました。数値データ・タイプの場合は、数値の小数部分が切り捨てられました。時刻データ・タイプとタイム・スタンプ・データ・タイプの場合は、時刻の一部分が切り捨てられました。 |
| 07006 | 変換が無効です。 | 結果セット内の列のデータ値を SQLBindCol() 呼び出しの fCType で指定されたデータ・タイプに変換できませんでした。 |
| 21S02 | 派生した表の程度が列リストと一致しません。 | 引数 Operation は SQL_UPDATE でした。すべての列が、アンバインドされた状態であるか、読み取り専用であるためか、バウンドの長さまたはインディケーター・バッファー内の値が SQL_COLUMN_IGNORE のため、列を更新できませんでした。 |
| 22001 | ストリング・データの右側が切り捨てられました。 | 列へ文字値またはバイナリー値を割り当てることによって、非ブランク (文字の場合) または非ヌル (バイナリーの場合) の文字かバイトの切り捨てが起こりました。 |
| 22003 | 数値が範囲外です。 | 以下の状態のいずれかが発生しました。
|
| 22008 | 日時形式が無効または日時フィールドがオーバーフローしました。 | 以下の状態のいずれかが発生しました。
|
| HY000 | 一般エラー。 | 特定の SQLSTATE が存在しないエラーが起こりました。SQLGetDiagRec() が *MessageText バッファー に戻したエラー・メッセージに、エラーとその原因が記述されています。 |
| HY001 | メモリーの割り振りに失敗しました。 | Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振れませんでした。アプリケーション・プロセスのためにプロセス・レベルのメモリーを使い尽くした可能性があります。 オペレーティング・システムの構成を調べて、プロセス・レベルのメモリー制限に関する情報を確認してください。 |
| HY010 | 関数シーケンス・エラーが発生しました。 | 以下の状態のいずれかが発生しました。
|
| HY011 | この時点では操作は無効です。 | アプリケーションが SQL_ATTR_ROW_STATUS_PTR ステートメント属性を設定しました。 それから、SQLFetch()、SQLFetchScroll()、または SQLExtendedFetch() が呼び出される前に SQLSetPos() が呼び出されました。 |
| HY090 | ストリングまたはバッファーの長さが無効です。 | 以下の状態のいずれかが発生しました。
|
| HY107 | 行の値が範囲外です。 | 以下の状態のいずれかが発生しました。
|
| HYC00 | ドライバーは使用できません。 | Db2 ODBC またはデータ・ソースは、Operation 引数または LockType 引数で要求された操作をサポートしません。 |
制約事項
動的両方向スクロール・カーソルに対して SQL_REFRESH は Db2 ODBC でサポートされていません。
例
rc = SQLSetPos(
hstmt,
1, /* Position at the first row of the rowset. */
SQL_POSITION,
SQL_LOCK_NO_CHANGE); /* Do not change the lock state. */