 |
Btrieve API Guide (v11) |
 |
|
Create Index(31)
Create Index オペレーション(B_BUILD_INDEX)では、既存のファイルにキーを追加します。
パラメーター
|
オペレーション コード
|
ポジション ブロック
|
データ バッファー
|
データ バッファー長
|
キー バッファー
|
キー番号
|
送り値
|
|
|
|
|
|
|
戻り値
|
|
|
|
|
|
|
前提条件
- 対象となるファイルが開いていることが必要です。
- ファイル内の既存のキー セグメント数は、許容されるキー セグメントの最大数から追加するキー セグメント数を差し引いた値以下でなければなりません。
- 許容されるキー セグメントの最大数は、ファイルのページ サイズによって決まります。次の表に、ページ サイズとキー セグメントの最大数を示します。
ページ サイズ(バイト数)
|
キー セグメントの最大数(ファイル バージョン別)
|
8.x 以前
|
9.0
|
9.5
|
512
|
8
|
8
|
切り上げ2
|
1,024
|
23
|
23
|
97
|
1,536
|
24
|
24
|
切り上げ2
|
2,048
|
54
|
54
|
97
|
2,560
|
54
|
54
|
切り上げ2
|
3,072
|
54
|
54
|
切り上げ2
|
3,584
|
54
|
54
|
切り上げ2
|
4,096
|
119
|
119
|
204(または 119)3
|
8,192
|
N/A1
|
119
|
420(または 119)3
|
16,384
|
N/A1
|
N/A1
|
420(または 119)3
|
1 N/A は「適用外」を意味します。
2 「切り上げ」は、ページ サイズを、ファイル バージョンでサポートされる次のサイズへ切り上げることを意味します。たとえば、512 は 1,024 に切り上げられ、2,560 は 4,096 に切り上げるということです。
3 リレーショナル インターフェイスで使用できるインデックス セグメントの最大数は 119 です。トランザクショナル インターフェイスの場合、最大数は、ページ サイズ 4,096 では 204、ページ サイズ 8,192 および 16,384 では 420 です。
|
- 『Status Codes and Messages』のステータス コード 26:指定されたキーの数が不正です。および 29:キー長が不正です。を参照してください。
- 新しいキーのキー フラグ、位置および長さが、キーを追加しようとしているファイルに対して適切であることを確認します。
- トランザクションが実行中でないことが必要です。
手順
- オペレーション コードに 31 を設定します。
- キーを追加するファイルのポジション ブロックを渡します。
- キーの各セグメントについて、16 バイトのキー仕様ブロックをデータ バッファーに格納します。表 8 で定義されているものと同じ構造体を使用します。キー ポジションおよびキー長の情報は整数で格納します。システム定義のログ キー(システム データとも言います)を再構築している場合、データ バッファーは少なくとも 16 バイトの長さで、ゼロに初期化されている必要があります。
- 新しいキーに ACS を定義するには、次のいずれかの手順を実行します。
- デフォルトの ACS、つまり、ファイルに既に定義されている先頭の ACS を使用するには、キー フラグ ワードに「デフォルトの ACS を使用」属性を指定します。
- 新しい ACS を定義するには、キー フラグ ワードに「番号付きの ACS を使用」属性を指定し、ACS 番号フィールドにゼロ(0)を設定します。さらに、データ バッファーの最後のキー仕様ブロックの後に 265 バイトの ACS を格納します。
- 名前によって既存の ACS を指定するには、キー フラグ ワードに「名前付きの ACS を使用」属性を指定し、ACS 番号フィールドにゼロ(0)を設定します。さらに、ACS 名を、データ バッファーの最後のキー仕様ブロックの後にある 265 バイトのブロックの先頭から格納します(名前より後の ACS ブロックの残り部分は無視されます)。名前の形式は次のいずれかに従っている必要があります。
ACS の種類
|
長さ(バイト単位)
|
説明
|
ユーザー定義の ACS
|
1
|
識別バイト 0xAC
|
〃
|
8
|
ACS テーブル名
|
ISR
|
1
|
識別バイト 0xAE
|
〃
|
16
|
ISR テーブル名
|
- データ バッファー長パラメーターにデータ バッファー内のバイト数を設定します。新しいキーが ACS を持たない、もしくはデフォルトの ACS を使用する場合は、次の式を使って正しいデータ バッファー長を決定します。
- 16 * (セグメント数)
- 新しいキーでデフォルト以外の ACS を指定する場合は、次の式を使って正しいデータ バッファー長を決定します。
- 16 * (セグメント数) + 265
- 作成されるキーに特定のキー番号を割り当てるには、目的のキー番号に 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 オペレーションが正常に終了した場合、新しいキーの番号は指定した番号になるか、または次のいずれかになります。
- キー番号が飛んでいないファイルの場合は、新しいキー番号は以前の最大のキー番号より 1 つ大きくなります。
- キー番号が飛んでいるファイルの場合は、新しいキー番号は欠けているキー番号のうちの最小の番号になります。
オペレーションの終了しだい、新しいキーを使ってデータにアクセスすることができるようになります。
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) |
|