SQLSetPos - 行セットにカーソル位置を設定する

SQLSetPos() 行セットにカーソル位置を設定する。カーソルを一度設定すると、 それらの行のデータのリフレッシュ、更新、および削除をアプリケーションで実行できます。

SQLSetPos() の ODBC 仕様

表 1. SQLSetPos() の仕様
ODBC 仕様レベル X/Open CLI CAE 仕様 ISO CLI 仕様
1.0 あり あり

構文

SQLRETURN   SQLSetPos (
               SQLHSTMT          StatementHandle,
               SQLSETPOSIROW     RowNumber,
               SQLUSMALLINT      Operation,
               SQLUSMALLINT      LockType);

関数の引数

表 2. SQLSetPos の引数
データ・タイプ 引数 使用法 説明
SQLHSTMT StatementHandle 入力 ステートメント・ハンドル。
SQLUSMALLINT RowNumber 入力

Operation で指定される操作が実行される行の行セット内の位置。RowNumber が 0 の場合、行セットの各行に操作が適用されます。

SQLUSMALLINT Operation 入力 実行する操作:
  • SQL_POSITION
  • SQL_REFRESH
  • SQL_UPDATE
  • SQL_DELETE
  • SQL_ADD
ODBC はまた、後方互換性のためにのみ以下の操作を指定します。これも Db2® ODBC がサポートします。
  • SQL_ADD

Db2 ODBC が SQL_ADD を SQLSetPos() 呼び出しでサポートします。この関数は推奨できません。 代わりに SQLBulkOperations() の Operation 値を SQL_ADD に指定して使用します。

SQLUSMALLINT LockType 入力 Operation 引数で指定される操作の実行後の、行のロック方法を指定します。Db2 ODBC は SQL_LOCK_NO_CHANGE をサポートします。
ODBC はまた、以下の操作を指定します。これは、Db2 ODBC はサポートしません。
  • SQL_LOCK_EXCLUSIVE
  • SQL_LOCK_UNLOCK

使用法

RowNumber 引数: RowNumber 引数は、Operation 引数で指定される操作が実行される行セット内の行数を指定します。RowNumber が 0 の場合、行セットの各行に操作が適用されます。RowNumber は、0 から行セット内の行数をすべて含んだものの中の値にする必要があります。

C 言語では、配列は、0 をベースにしていますが、RowNumber 引数は、1 をベースにしています。例えば、行セットの 5 番目の行を更新するには、アプリケーションは、行セットバッファーを配列指標 4 で変更しますが、RowNumber を 5 に指定します。

アプリケーションは、SQLSetPos() を呼び出す時に、カーソル位置を指定できます。 一般的に、アプリケーションは、SQL_POSITION 操作または SQL_REFRESH 操作を指定した SQLSetPos() を呼び出し、位置決めされた更新または削除ステートメントの実行または SQLGetData() の呼び出しの前にカーソルの位置を決めます。

Operation 引数: データ・ソースでサポートされるオプションを決定するために、アプリケーションは、カーソルのタイプによりますが、以下の情報タイプの内の 1 つを指定して SQLGetInfo() を呼び出します。
  • SQL_FORWARD_ONLY_CURSOR_ATTRIBUTES1
  • SQL_DYNAMIC_CURSOR_ATTRIBUTES1
  • SQL_STATIC_CURSOR_ATTRIBUTES1
Operation には、以下の値のいずれかが含まれます。
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 つのステートメントによって獲得されるロックは、同じ接続上の別のステートメントでアンロックできます。

ODBC は、以下の LockType 引数を定義します。Db2 ODBC は SQL_LOCK_NO_CHANGE のみをサポートします。データ・ソースでサポートされるロックを決定するには、アプリケーションは、SQL_LOCK_TYPES 情報タイプを指定して SQLGetInfo() を呼び出します。
表 3. Operation 値
LockType 引数 ロック・タイプ
SQL_LOCK_NO_CHANGE 行が SQLSetPos() が呼び出された前と同じ状態 (ロックされているかアンロックされている) になっていることを確認します。LockType のこの値は、明示的行レベル・ロッキングをサポートしないデータ・ソースで、現行の並行性とトランザクションの分離レベルに必要とされるロッキングを使用できるようにします。
SQL_LOCK_EXCLUSIVE Db2 ODBC ではサポートされません。 行を排他的にロックします。
SQL_LOCK_UNLOCK Db2 ODBC ではサポートされません。 行をアンロックします。

状況配列と操作配列

以下の状況配列と操作配列は SQLSetPos() と共に使用されます。
  • 行状況配列には、行セット内の各行のデータの状況値が含まれています。SQLFetch()、SQLFetchScroll()、または SQLSetPos() の呼び出し後、状況値はこの配列で設定されます。
  • 行操作配列には、行セット内の各行の値が含まれます。これには、一括操作の場合 SQLSetPos() 呼び出しを無視するか実行するかが示されます。配列内の各エレメントは SQL_ROW_PROCEED (デフォルト) または SQL_ROW_IGNORE です。SQL_ATTR_ROW_OPERATION_PTR ステートメント属性は行操作配列を指します。
状況配列および操作配列内のエレメント数は、SQL_ATTR_ROW_ARRAY_SIZE ステートメント属性で定義された、行セット内の行数と同じにする必要があります。

戻りコード

SQLPos() は、呼び出された後、次のいずれかの値を戻します。
  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_NEED_DATA
  • SQL_STILL_EXECUTING
  • SQL_ERROR
  • SQL_INVALID_HANDLE

診断

次の表は、この関数が生成する各 SQLSTATE 値ごとに、 その記述と説明を一覧で記載してあります。

表 4. SQLSetPos の 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 数値が範囲外です。 以下の状態のいずれかが発生しました。
  • 引数 Operation は SQL_UPDATE でした。結果セット内の列へ数値を割り当てることによって数値全体 (一部とは対照的に) が切り捨てられました。
  • 引数 Operation は SQL_REFRESH でした。有効数字が失われたために、1 つ以上のバインドされた列に対する数値を戻すことができませんでした。
22008 日時形式が無効または日時フィールドがオーバーフローしました。 以下の状態のいずれかが発生しました。
  • Operation 引数は SQL_UPDATE でした。結果セット内の列に送られたデータの日時算術演算の結果、日時フィールド (年、月、日、時、分、または秒フィールド) がフィールドに許容される値の範囲外になったか、グレゴリオ暦の日時値として自然の規則に基づくと無効になりました。または、結果セット内の列へ数値を割り当てることによって数値全体が切り捨てられました。
  • Operation 引数は SQL_REFRESH でした。結果セットから取り出されたデータの日時算術演算の結果、日時フィールド (年、月、日、時、分、または秒フィールド) がフィールドに許容される値の範囲外になったか、グレゴリオ暦の日時値として自然の規則に基づくと無効になりました。
HY000 一般エラー。 特定の SQLSTATE が存在しないエラーが起こりました。SQLGetDiagRec() が *MessageText バッファー に戻したエラー・メッセージに、エラーとその原因が記述されています。
HY001 メモリーの割り振りに失敗しました。 Db2 ODBC は、関数の実行または完了をサポートするのに必要なメモリーを割り振れませんでした。アプリケーション・プロセスのためにプロセス・レベルのメモリーを使い尽くした可能性があります。 オペレーティング・システムの構成を調べて、プロセス・レベルのメモリー制限に関する情報を確認してください。
HY010 関数シーケンス・エラーが発生しました。 以下の状態のいずれかが発生しました。
  • 指定した StatementHandle が実行状態にありませんでした。SQLExecDirect()、SQLExecute()、またはカタログ関数の、前の呼び出しなしで、関数が呼び出されました。
  • StatementHandle に対し SQLExecute()、SQLExecDirect()、または SQLSetPos() が呼び出しされ、SQL_NEED_DATA を戻しました。 この関数は、すべての実行時データ・パラメーターまたは列にデータが送られる前に呼び出されました。
  • SQLFetchScroll() が呼び出される前か、SQLFetch() が呼び出された後で、SQL_CLOSE オプションを指定した SQLFreeStmt() が呼び出される前に、StatementHandle に対して SQLSetPos() が呼び出されました。
HY011 この時点では操作は無効です。 アプリケーションが SQL_ATTR_ROW_STATUS_PTR ステートメント属性を設定しました。 それから、SQLFetch()、SQLFetchScroll()、または SQLExtendedFetch() が呼び出される前に SQLSetPos() が呼び出されました。
HY090 ストリングまたはバッファーの長さが無効です。 以下の状態のいずれかが発生しました。
  • Operation 引数は SQL_ADD または SQL_UPDATE で、データ値は NULL ポインターでした。 列の長さの値が 0 ではないか、 SQL_DATA_AT_EXEC、 SQL_COLUMN_IGNORE、 SQL_NULL_DATA ではないか、 または SQL_LEN_DATA_AT_EXEC_OFFSET 以下でした。
  • Operation 引数は SQL_ADD または SQL_UPDATE で、 データ値は NULL ポインターではありませんでした。列の長さの値は 0 より小さいが、 SQL_DATA_AT_EXEC、 SQL_COLUMN_IGNORE、 SQL_NTS、または SQL_NULL_DATA に等しくないか、 SQL_LEN_DATA_AT_EXEC_OFFSET 以下でした。
HY107 行の値が範囲外です。 以下の状態のいずれかが発生しました。
  • StatementHandle に関連付けられたカーソルが前方のみとして定義されていたため、カーソルを行セット内に置けませんでした。SQLSetStmtAttr() の SQL_ATTR_CURSOR_TYPE 属性についての説明を参照してください。
  • Operation 引数は SQL_UPDATE、SQL_DELETE、または SQL_REFRESH でした。RowNumber 引数で識別された行が削除されたか、フェッチされていません。
  • Operation 引数は SQL_POSITION で、RowNumber 引数が 0 でした。
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. */