Btrieve API Guide (v11)

Insert(2)

Insert オペレーション(B_INSERT)では、ファイルにレコードを挿入します。トランザクショナル インターフェイスでは新しいレコードのキー値を反映して、キーの B-ツリーが調整されます。

パラメーター

 
オペレーション コード
ポジション ブロック
データ バッファー
データ バッファー長
キー バッファー
キー番号
送り値

 

戻り値
 

 
 

 

前提条件

手順

  1. オペレーション コードに 2 を設定します。
  2. ファイルのポジション ブロックを渡します。
  3. データ バッファーに、挿入するレコードを格納します。
  4. データ バッファー長を指定します。この値は、少なくともレコードの固定長部分と同じ長さでなければなりません。
  5. ポジショニング情報(カレンシー)の確立にトランザクショナル インターフェイスが使用するキー番号を指定します。NCC オプションを使用するには、キー番号に -1(0xFF)を指定します。システム定義のログ キー(システム データ)を使用するには、125 を指定します。

    メモ

    NCC(No-currency-change:カレンシー変更なし)オプションを使用すると、Insert オペレーションはキー バッファー パラメーターの値を更新しません。つまり、キー バッファー パラメーターには何の情報も返されません。


結果

Insert オペレーションが正常に終了した場合、トランザクショナル インターフェイスではファイルに新しいレコードが挿入され、新しいレコードを反映してキーの B ツリーが更新されます。また、指定したキーの値がキー バッファーに返されます。トランザクショナル インターフェイスでは、AUTOINCREMENT キーの値がバイナリ 0 に初期化されているレコードを挿入すると、挿入したレコードもデータ バッファーに返され、レコードにはトランザクショナル インターフェイスによって割り当てられた AUTOINCREMENT 値が入っています。NCC Insert オペレーションでは、キー バッファー パラメーターの値は変更されません。

Insert オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。

2
アプリケーションで I/O エラーが発生しました。
3
ファイルが開いていません。
5
レコードのキー フィールドに重複するキー値があります。
18
ディスクがいっぱいです。
21
キー バッファー パラメーターが短すぎます。
22
データ バッファー パラメーターが短すぎます。

ポジショニング

NCC オプションを指定しない Insert オペレーションを実行すると、完全な論理カレンシーおよび物理カレンシーが確立し、挿入したレコードが現在のレコードになります。論理カレンシーは指定したキーに基づきます。

NCC Insert オペレーションを実行すると、論理カレンシーは影響を受けずに、物理カレンシーが確立されます。つまり、NCC Insert オペレーションを実行したアプリケーションでは、ファイル内の論理位置は Insert オペレーションを実行する前と変わらないということです。このような状況で、NCC Insert オペレーションに続けて、Get Next(6)、Get Next Extended(36)、Get Previous(7)、および Get Previous Extended(37)などのオペレーションを実行すると、NCC Insert オペレーション実行以前のアプリケーションの論理カレンシーに基づく値が返されます。


メモ

トランザクショナル インターフェイスでは、NCC Insert オペレーションを実行しても、その結果として何の情報もキー バッファーには返されません。したがって、論理カレンシーの維持が必要なアプリケーションでは、NCC Insert オペレーション後にキー バッファーの値を変更しないでください。変更すると、次の Get オペレーションの結果は予測できないものになります。


トランザクショナル インターフェイスでは標準の Insert オペレーションと NCC Insert オペレーションのどちらを実行しても、新しく挿入されたレコードに対し物理カレンシーが確立されます。NCC Insert オペレーションに続く Step Next(24)、Step Next Extended (38)、Step Previous(35)、Step Previous Extended(39)、Update(3)、Delete(4)、および Get Position(22)などのオペレーションは、新しい物理カレンシーに基づいて機能します。


Get Previous Extended(37)

Insert Extended(40)