Btrieve API Guide (v11)

Create Index(31)

Create Index オペレーション(B_BUILD_INDEX)では、既存のファイルにキーを追加します。

パラメーター

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

 

戻り値
 
 
 
 
 
 

前提条件

手順

  1. オペレーション コードに 31 を設定します。
  2. キーを追加するファイルのポジション ブロックを渡します。
  3. キーの各セグメントについて、16 バイトのキー仕様ブロックをデータ バッファーに格納します。表 8 で定義されているものと同じ構造体を使用します。キー ポジションおよびキー長の情報は整数で格納します。システム定義のログ キー(システム データとも言います)を再構築している場合、データ バッファーは少なくとも 16 バイトの長さで、ゼロに初期化されている必要があります。
  4. 新しいキーに ACS を定義するには、次のいずれかの手順を実行します。
  5. データ バッファー長パラメーターにデータ バッファー内のバイト数を設定します。新しいキーが ACS を持たない、もしくはデフォルトの ACS を使用する場合は、次の式を使って正しいデータ バッファー長を決定します。
    16 * (セグメント数)
    新しいキーでデフォルト以外の ACS を指定する場合は、次の式を使って正しいデータ バッファー長を決定します。
    16 * (セグメント数) + 265
  6. 作成されるキーに特定のキー番号を割り当てるには、目的のキー番号に 0x80 を加算し、その合計値をキー番号パラメーターに入れます。システム定義のログ キー(システム データ)を再構築している場合は、0xFD(つまり、キー番号 125 + 128)を指定します。

    メモ

    キー番号はファイルで一意であることが必要です。また、有効な値でなければなりません(つまり、各キー番号の値は、ファイルのページ サイズに対して許容されるキーの最大数よりも小さい値でなければなりません)。


詳細

トランザクショナル インターフェイスでは、キーを作成するときに特定のキー番号を割り当てることができます。この機能は、キーを削除して、その削除したキーよりも大きなキー番号を持つすべてのキーの番号をトランザクショナル インターフェイスに付け替えさせないようにする機能と相補関係にあります。アプリケーションがインデックスを削除し、トランザクショナル インターフェイスにそれよりも大きな番号を持つキーの番号を付け替えないように指示を出した場合、その後でユーザーが具体的なキー番号を割り当てずに影響を受けたファイルを複製すると、複製したファイルには元のファイルとは別のキー番号が割り当てられます。

データ バッファーで ACS を定義すると、トランザクショナル インターフェイスは ACS 定義をファイルに追加する前に、まず指定された名前を使って既存の ACS をチェックします。トランザクショナル インターフェイスが指定された名前を持つ既存の ACS を検出した場合、トランザクショナル インターフェイスはファイル内で ACS 定義の複製は行わず、既存の ACS と新しいキーとの関連付けを行います。

キー フラグ ワードに「名前付きの ACS を使用」属性を指定した場合、トランザクショナル インターフェイスはデータ バッファーに指定された ACS 名を使ってファイル内で同名の ACS を検索してから、その ACS を新しいキーに割り当てます。

ファイルが複数のトランザクショナル インターフェイスによって開かれており、あるクライアントが Create Index プロセスを開始した場合、リモート クライアントは、トランザクショナル インターフェイスによってキーが作成されている間も、同じファイルに対して Get および Step オペレーションを実行できます。

作成されるキーが AUTOINCREMENT キーでない場合は、リモート クライアントの Get および Step オペレーションにロック バイアスを使用でき、Create Index プロセスが完了したときに、読み取りオペレーションをさらに発行しなくても、ロックされていたレコードを更新したり削除したりできます。トランザクショナル インターフェイスではキーを作成するためにレコードのイメージを変更する必要がないため、このような処理が可能になります。

ただし、作成されるキーが AUTOINCREMENT キーである場合は、トランザクショナル インターフェイスではインデックスを構築し、かつ適切なフィールドでゼロ値を使ってすべてのレコードを変更する必要があります。キーの作成前または最中にロック バイアスを使わずに Get または Step オペレーションを実行したリモート クライアントは、キーの作成が正常に終了した後で Update または Delete オペレーションを実行するとき、ステータス コード 80 を受け取ります。

また、あるクライアントがレコードをロックしている最中に、別のクライアントが AUTOINCREMENT キーを作成しようとすると、トランザクショナル インターフェイスからステータス コード 84 が返されます。同様に、あるクライアントが AUTOINCREMENT キーのインデックスを作成している最中に、別のクライアントがロック バイアスを使って Get または Step オペレーションを実行しようとすると、トランザクショナル インターフェイスからステータス コード 85 が返されます。

結果

トランザクショナル インターフェイスはファイルに新しいキーを直ちに追加します。このオペレーションの所要時間は、インデックスが作成される総レコード数、ファイルのサイズおよび新しいインデックスの長さによって変わります。

Create Index オペレーションが正常に終了した場合、新しいキーの番号は指定した番号になるか、または次のいずれかになります。

オペレーションの終了しだい、新しいキーを使ってデータにアクセスすることができるようになります。

Create Index オペレーションが正常に実行されなかった場合、新しいインデックスの一部が既に構築されていたとしても、トランザクショナル インターフェイスはそれをすべて削除します。エラーが発生する前に新しいインデックスに割り当てられたファイル ページは、ファイルの空き領域リストに置かれ、レコードを挿入したり別のキーを作成したりするときに再利用されます。

AUTOINCREMENT キーの作成中にエラーが発生すると、それまでに変更されている値はそのまま残ります。トランザクショナル インターフェイスから返される可能性のあるステータス コードは次のとおりです。

22
データ バッファー パラメーターが短すぎます。
27
キー ポジションが不正です。
41
実行しようとした操作はトランザクショナル インターフェイスでは許可されていません。
45
指定したキー フラグが不正です。
49
拡張キー タイプが不正です。
56
インデックスが不完全です。
84
レコードまたはページがロックされています。
85
ファイルはロックされています。
104
トランザクショナル インターフェイスがロケールを認識しません。
134
トランザクショナル インターフェイスがインターナショナル ソート規則(ISR)を読み取れません。
135
指定されたインターナショナル ソート規則(ISR)テーブルは破損しているか、または不正です。
136
トランザクショナル インターフェイスは、指定されたオルタネート コレーティング シーケンスをファイル内に見つけられません。

キーの作成中に処理が中断されても、ファイルのほかのキーを使ってファイルのデータにアクセスすることはできます。しかし、不完全なインデックスを使ってデータにアクセスしようとすると、トランザクショナル インターフェイスから 0 以外のステータス コードが返されます。この問題を解決するには、Drop Index オペレーション(32)を使って不完全なインデックスを削除し、Create Index オペレーションを再発行してください。

ポジショニング

Create Index オペレーションは、ファイルのカレンシー情報にまったく影響しません。


Create(14)

Delete(4)