Btrieve API オペレーション
 
このページをシェアする                  
Btrieve API オペレーション
ここでは、アプリケーションが Btrieve API を使って実行できるオペレーションについて説明します。各オペレーションに、次の情報があります。
オペレーションの名前、コードおよび説明。
パラメーター - オペレーションを実行する際に、6 個のパラメーターのうちのどの値がアプケーションから送られ、アプリケーションに返されるのかを表に示しています。「送り値」パラメーターは、アプリケーションからオペレーションに送られます。「戻り値」パラメーターは、オペレーション完了後にオペレーションからアプリケーションに返されます。
前提条件 - オペレーションを正常に実行させるためにアプリケーションが満たすべき条件を示します。
手順 - オペレーションが要求するパラメーターを初期化する手順を示します。
詳細 - オペレーションについての追加情報を示します。
結果 - オペレーションが正常に終了した場合と、何らかのエラーが発生した場合の結果を示します。それぞれのオペレーションは、オペレーションの結果をアプリケーションに通知するステータス コードを返します。ステータス コード 0 は、オペレーションが正常に終了したことを示します。0 以外のステータス コードは、通常は何らかのエラーが発生したことを示します。ただし、0 以外のステータス コードの中には、単に情報を提供するだけで、関連するオペレーションが正常に終了したときにも示されるものがあります。たとえば、ステータス コード 60 は指定したリジェクト カウントに到達したことを意味します。
ポジショニング - オペレーションがファイル内のレコードの論理カレンシーまたは物理カレンシーに与える影響を示します。
Btrieve API オペレーションの一覧をアルファベット順に示します。
Abort Transaction(21)
Begin Transaction(19 または 1019)
Clear Owner(30)
Close(1)
Continuous Operation(42)
Create(14)
Create Index(31)
Delete(4)
Drop Index(32)
End Transaction(20)
Find Percentage(45)
Get By Percentage(44)
Get Direct/Chunk(23)
Get Direct/Record(23)
Get Directory(18)
Get Equal(5)
Get First(12)
Get Greater Than(8)
Get Greater Than or Equal(9)
Get Key(+50)
Get Last(13)
Get Less Than(10)
Get Less Than or Equal(11)
Get Next(6)
Get Next Extended(36)
Get Position(22)
Get Previous(7)
Get Previous Extended(37)
Insert(2)
Insert Extended(40)
Login/Logout(78)
Open(0)
Reset(28)
Set Directory(17)
Set Owner(29)
Stat(15)
Stat Extended(65)
Step First(33)
Step Last(34)
Step Next(24)
Step Next Extended(38)
Step Previous(35)
Step Previous Extended(39)
Stop(25)
Unlock(27)
Update(3)
Update Chunk(53)
Version(26)
Abort Transaction(21)
Abort Transaction オペレーション(B_ABORT_TRAN)では、現在のトランザクションを終了し、このトランザクションの開始以降に実行されたすべてのオペレーションの結果を削除します。また、トランザクションによって設定されたすべてのファイルとレコードのロックを解除します。
パラメーター
 
 
オペレーション コード
ポジション ブロック
データ バッファー
データ バッファー長
キー バッファー
キー番号
送り値
* 
 
 
 
 
 
戻り値
 
 
 
 
 
 
前提条件
Abort Transaction オペレーションを発行する前に、Begin Transaction(19 または 1019)オペレーションが正常に実行されている必要があります。
手順
オペレーション コードを 21 に設定します。MicroKernel エンジンでは、オペレーション コード以外の Abort Transaction 呼び出しパラメーターはすべて無視されます。
結果
Abort Transaction オペレーションが正常に終了した場合は、MicroKernel エンジンからステータス コード 0 が返されます。トランザクションの開始以降に発行されたすべての Insert、Update、および Delete オペレーションの結果がファイルから削除されます。
Abort Transaction オペレーションが正常に実行されなかった場合は、MicroKernel エンジンから次のステータス コードのいずれかが返されます。
36
アプリケーションでトランザクション エラーが発生しました。
39
End Transaction オペレーションまたは Abort Transaction オペレーションを実行する前に、Begin Transaction オペレーションを実行する必要があります。
ポジショニング
Abort Transaction オペレーションは、ファイルのカレンシー情報にまったく影響しません。
Begin Transaction(19 または 1019)
Begin Transaction オペレーション(B_BEGIN_TRAN)では、トランザクションの開始を定義します。トランザクションは、複数の Btrieve API オペレーションを単一イベントとして実行する必要がある場合に有用です。たとえば、いくつかのオペレーションのうち少なくとも 1 つでもオペレーションが正常に終了しないと、データベースの論理的整合性が保てなくなる場合には、トランザクションを使用してください。
一連のオペレーションを Begin Transaction と End Transaction オペレーションで囲んでおくと、明示的な End Transaction(20)でトランザクションの完了を要求しない限り、MicroKernel エンジンはその間に実行された複数のオペレーションをすべて取り消すことができます。トランザクション内で加えられた変更は、End Transaction オペレーションの実行が正常に終了するまで、ほかのユーザーからは見ることができません。
MicroKernel エンジンは、ファイルやパフォーマンスに多大な影響を与えるという理由で、いくつかのオペレーションについてトランザクション中の実行を禁止しています。この特定のオペレーションとは、Set Owner(29)Clear Owner(30)Create Index(31)、および Drop Index(32)です。
パラメーター
 
 
オペレーション コード
ポジション ブロック
データ バッファー
データ バッファー長
キー バッファー
キー番号
送り値
* 
 
 
 
 
 
戻り値
 
 
 
 
 
 
前提条件
Begin Transaction オペレーションを発行する前に、先行するトランザクションを終了または中止しておく必要があります。
手順
オペレーション コードを 19 に設定して排他トランザクションを開始するか、1019 に設定して並行トランザクションを開始します。MicroKernel エンジンでは、オペレーション コード以外の Begin Transaction 呼び出しパラメーターはすべて無視されます。
Begin Transaction オペレーションでは、デフォルトのロック バイアスを指定できます。
+100 - 単一レコード ウェイト ロック
+200 - 単一レコード ノーウェイト ロック
+300 - 複数レコード ウェイト ロック
+400 - 複数レコード ノーウェイト ロック
並行トランザクションの Begin Transaction オペレーションでは、+500 をオペレーション コードに追加できます(1519)。追加すると、トランザクション内の Insert、Update、Delete の各オペレーションが、MicroKernel エンジンによって再試行されなくなります。
さらに、+500 バイアスをデフォルトのロック バイアスと組み合わせることもできます。たとえば、1019 + 500 + 200(1719)を使用すると、Insert、Update および Delete オペレーションの再試行を抑え、並行トランザクションが実行されます。また同時に、単一レコードの読み取りノーウェイト ロックが指定されます。
トランザクションおよびロックの詳細については、『PSQL Programmer's Guide』を参照してください。
結果
Begin Transaction オペレーションが正常に終了した場合は、MicroKernel エンジンからステータス コード 0 が返されます。
Begin Transaction オペレーションが正常に実行されなかった場合は、MicroKernel エンジンから次のステータス コードのいずれかが返されます。
36
アプリケーションでトランザクション エラーが発生しました。
37
別のトランザクションが実行中です。
ポジショニング
Begin Transaction オペレーションは、ファイルのカレンシー情報にまったく影響しません。
Clear Owner(30)
Clear Owner オペレーション(B_CLEAR_OWNER)では、あらかじめ Set Owner オペレーションを使ってファイルに割り当ててあるオーナー ネームを削除します。ファイルがあらかじめ暗号化されている場合は、Clear Owner オペレーションの実行中に MicroKernel エンジンによってファイルの解読も行われます。詳細については、『Advanced Operations Guide』のオーナー ネームを参照してください。
パラメーター
 
 
オペレーション コード
ポジション ブロック
データ バッファー
データ バッファー長
キー バッファー
キー番号
送り値
* 
* 
 
 
 
 
戻り値
 
* 
 
 
 
 
前提条件
対象となるファイルが開いており、オーナー ネームが指定されていることが必要です。
トランザクションが実行中でないことが必要です。
手順
1 オペレーション コードを 30 に設定します。
2 対象となるファイルを識別するポジション ブロックを渡します。
結果
Clear Owner オペレーションが正常に実行されると、それ以降、MicroKernel エンジンはファイルを開いたり変更したりするときにオーナー ネームを要求しなくなります。オーナーを割り当てるときにファイルのデータを暗号化した場合には、MicroKernel エンジンは Clear Owner オペレーションの実行中にデータの解読も行います。暗号化されているデータが多いほど、Clear Owner オペレーションの実行にかかる時間は長くなります。
Clear Owner オペレーションが正常に実行されなかった場合は、MicroKernel エンジンから次のステータス コードのいずれかが返されます。
3
ファイルが開いていません。
41
実行しようとした操作は MicroKernel エンジンでは許可されていません。
ポジショニング
Clear Owner オペレーションは、ファイルのカレンシー情報にまったく影響しません。
Close(1)
Close オペレーション(B_CLOSE)では、指定されたポジション ブロックに関連付けられているファイルを閉じ、そのファイルに対して実行されたロックをすべて解除します。ファイルへのアクセスを終了するとき、アプリケーションでは必ず Close オペレーションを実行する必要があります。Close オペレーションの実行後は、もう一度 Open(0)を発行しない限り、そのファイルにはアクセスできなくなります。
トランザクション中でも、ファイルを閉じることができます。ただし、Close オペレーションを実行しても、トランザクションは終了しません。トランザクションは明示的に終了または中止する必要があります。トランザクションを中止すると、トランザクション中に行われた変更は打ち切られます。トランザクションを終了すると、変更が反映されます。
メモ:トランザクション中にファイルを閉じた場合、MicroKernel エンジンではそのファイルへの更新を正しく処理できるように、トランザクションが中止または終了されるまでファイルのオープン ハンドルを保持します。ただし、そのファイルのポジション ブロックをアプリケーションで使用することはできなくなります。
パラメーター
 
 
オペレーション コード
ポジション ブロック
データ バッファー
データ バッファー長
キー バッファー
キー番号
送り値
* 
* 
 
 
 
 
戻り値
 
 
 
 
 
 
前提条件
対象となるファイルが開いていることが必要です。
手順
1 オペレーション コードを 1 に設定します。
2 閉じるファイルに対応する有効なポジション ブロックを渡します。
結果
Close オペレーションが正常に終了した場合は、閉じたファイルに対応するポジション ブロックは有効でなくなります。
Close オペレーションが正常に実行されなかった場合は、ファイルが開いたままになり、MicroKernel エンジンから次のステータス コードが返されます。
3
ファイルが開いていません。
ポジショニング
Close オペレーションを実行すると、ファイルの物理カレンシー情報および論理カレンシー情報は消去されます。
Continuous Operation(42)
Continuous オペレーション(B_CONTINOUS)では、アクティブな MicroKernel エンジン ファイルを閉じることなく、システム バックアップを実行できます。ファイルのバックアップ中に行った変更は、デルタ ファイルと呼ばれる一時ファイルに記憶されます。デルタ ファイルに書き込まれた変更を除き、Continuous オペレーション モードに置かれたすべてのファイルの内容がシステム バックアップの対象になります。バックアップされたファイルが Continuous オペレーション モードから抜けると、MicroKernel エンジンにより、デルタ ファイルの変更がこれらのファイルに自動的にロール インされます。
メモ:このオペレーションは、ローカル エンジンで動作しているアプリケーションにのみ使用できます。クライアント アプリケーションはリモート マシンにあるファイルに対してこのオペレーションを使用することはできません。
このオペレーションを使うと、ファイルがアクティブな状態のまま、それを安全にコピーできます。クライアント/サーバー セットアップでは、あるファイルで Continuous オペレーションを開始するクライアントは、そのファイルで Continuous オペレーションを終了するクライアントでもなければなりません。
パラメーター
 
 
オペレーション コード
ポジション ブロック
データ バッファー
データ バッファー長
キー バッファー
キー番号
送り値
* 
 
* 
* 
 
* 
戻り値
 
 
* 
* 
 
 
メモ:キー番号パラメーターの値が 0(Continuous オペレーション モードを開始)または 2(Continuous オペレーション モードを終了)の場合にのみ、データ バッファー パラメーターおよびデータ バッファー長パラメーターの値が必要です。以下に、これらのキー番号の値について説明します。キー番号パラメーターが 1 の場合、データ バッファー長は 0 である必要があります。
手順
Continuous オペレーション モードを開始するには、以下の手順を実行してください。
1 バックアップの対象となるファイルまたはファイルのセットを定義するか、目的のファイルを現在バックアップの対象として定義されているファイルのセットに追加します。
a. オペレーション コードを 42 に設定します。
b. Continuous オペレーション モードに置くファイルの名前をデータ バッファー パラメーターに入れます。サーバー名のみを除いた絶対パス名を入れます。名前をカンマで区切り、リストの最後にバイナリ 0 を付けます。
次の例は、Windows サーバーの場合の例です。
f:\acct\march.mkd,f:\acct\april.mkd
c. 名前の長さをデータ バッファー長パラメーターに入れます。この値は、データ バッファー自体に入っている、バイナリ 0 を含めた実際の名前の長さ以上の値にする必要があります。たとえば、例に挙げた名前の場合、データ バッファー長には 40 以上の値を入れることが必要です。
d. キー番号パラメーターを 0 に設定します。
2 バックアップを実行します。
3 Continuous オペレーション モードを終了します。
a. オペレーション コードを 42 に設定します。
b. キー番号パラメーターを 1 に設定します。
1 つまたは複数の特定のファイルで Continuous オペレーションを終了するには、キー番号パラメーターを 2 に設定し、手順 1b で説明したようにファイル名をデータ バッファー パラメーターに入れます。さらに、手順 1c で説明したように、名前の長さをデータ バッファー長パラメーターに入れます。
詳細
一連のファイルをバックアップするように定義する場合は、以下の点に留意してください。
MicroKernel エンジンは、データ バッファーにファイル名が入っていなくてもエラーと見なしません。ファイル名が見つからない場合、MicroKernel エンジンは Continuous オペレーションで何の動作も行いません。
データ バッファーに重複するファイル名が存在しても、Continuous オペレーションの動作状況には影響しません。MicroKernel エンジンでは、指定したファイルを 1 度だけ Continuous オペレーション モードに置きます。
同じディレクトリに、ファイル名が同一で拡張子のみが異なるようなファイルを置かないでください。たとえば、Invoice.btr という名前のデータ ファイルと Invoice.mkd という名前のファイルが同じディレクトリ内にあってはなりません。このような制限が設けられているのは、データベース エンジンがさまざまな機能でファイル名のみを使用し、ファイルの拡張子を無視するためです。Continuous オペレーションでは、デルタ ファイル名として、対応するファイルの名前に拡張子「.^^^」を付けた名前を使用します。MicroKernel エンジンは両方のファイルについて同一のデルタ ファイルに書き込もうとするため、データの破損につながるか、またはステータス 85 が返される可能性があります。また、これらのファイルが Continuous オペレーション モードに置くファイルの大きなリストの一部であったとしても、この状況が発生する場合には、ファイルは一切 Continuous オペレーション モードに置かれません。
アプリケーションでは、Continuous オペレーションを反復的に呼び出して、Continuous オペレーション モードに置くファイルのリストにファイル名を追加できます。ただし、リレーショナル エンジンによってファイルの一部に参照整合性(RI)制約が設定されている場合は、この操作により、バックアップが壊れる可能性があります。参照整合性制約と関連付けられているファイルは、単独の Continuous オペレーション呼び出しで渡す必要があります。
既に Continuous オペレーション モードに入っているファイルを指定すると、MicroKernel エンジンからステータス コード 88 が返されます。
Continuous オペレーションを呼び出すサーバー ベースのアプリケーションを作成する場合は、必ず BTRVID を呼び出し、有効なクライアント ID を使用することで、同一クライアントのもとで Continuous オペレーションの開始と終了を行えるようにします。
Btrieve API では、BTRVID 関数を使ってバックアップ セットごとに異なるクライアント ID を指定し、複数のバックアップ セットを定義できます。ただし、同じファイルを 2 つのセットに入れることはできません。
MicroKernel エンジンによってデルタ ファイルからデータ ファイルに変更内容がロール インされているときでも、ユーザーは通常の場合と同じように、MicroKernel エンジン ファイルの更新、挿入および読み取りを引き続き実行できます。MicroKernel エンジンは挿入作業で必要となれば、変更内容のロール イン中でもデルタ ファイルに新しいページを追加します。このため、変更内容が失われることはありません。
メモ:デルタ ファイルは決して手動で削除しないでください。
アプリケーションで BTRV 関数を使用する場合は、ファイルが Continuous オペレーション モードに入っているときにそのアプリケーションをアンロードしないでください。アンロードすると、対象となるファイルを Continuous オペレーション モードから削除できなくなることがあります。これは、対象となるファイルのオーナーとして MicroKernel エンジンが当初割り当てたデフォルトのクライアント ID が、別のアプリケーションに再割り当てされてしまう可能性があるからです。MicroKernel エンジンでは対象となるファイルの正しいオーナーがわからなくなるため、それらのファイルを Continuous オペレーション モードから削除できなくなってしまいます。
Continuous オペレーション モードに入るとき、または MicroKernel エンジンによってデルタ ファイルからデータ ファイルに変更内容がロール インされている最中にシステムがクラッシュした場合は、システムの再起動後初めてそのファイルを開くときに、MicroKernel エンジンによってすべての変更内容がファイルにロール インされます。
結果
Continuous オペレーションが正常に終了した場合、MicroKernel エンジンからステータス コード 0 が返されますが、データ バッファーおよびデータ バッファー長パラメーターには何の値も返されません。
このオペレーションが正常に実行されなかった場合、MicroKernel エンジンから次のステータス コードのいずれかが返されます。
11
指定されたファイル名は不正です。
12
MicroKernel エンジンは指定されたファイルを見つけられません。
41
実行しようとした操作は MicroKernel エンジンでは許可されていません。
51
オーナー ネームが不正です。
88
アプリケーションでモードの不一致エラーが発生しました。
91
アプリケーションでサーバー エラーが発生しました。
上記のコードに加え、アプリケーションには、 ステータス コード 18 のような標準の I/O エラーが返されることがあります。
MicroKernel エンジンから 0 以外のステータス コードが返される場合、Continuous オペレーションは、エラーを発生させた入力文字列の一部をデータ バッファーに返します。入力文字列が使用されていない場合、データ バッファーにはエラーの原因となったファイル名が返されます。データ バッファー長には、データ バッファー内の出力文字列の長さが反映されます。この場合は、エラーの原因となったファイル名の長さが入ります。
ポジショニング
Continuous オペレーションを実行しても、ファイルにカレンシーは確立しません。
Create(14)
Create オペレーション(B_CREATE)では、アプリケーション内部から新しいデータ ファイルを生成できます。Create オペレーションにはファイルの削除または名前変更ができるサブファンクションもあります(Create オペレーションによる削除および名前変更サブファンクションを参照)。
メモ:同じディレクトリに、ファイル名が同一で拡張子のみが異なるようなファイルを置かないでください。たとえば、同じディレクトリ内のデータ ファイルの 1 つに Invoice.btr、もう 1 つに Invoice.mkd という名前を付けてはいけません。このような制限が設けられているのは、データベース エンジンがファイル名のみを使用し、ファイルの拡張子を無視する場合もあるからです。この場合、ファイルの拡張子だけが異なるファイルは、データベース エンジンでは同一のものであると認識されます。
パラメーター
 
 
オペレーション コード
ポジション ブロック
データ バッファー
データ バッファー長
キー バッファー
キー番号
送り値
* 
 
* 
* 
* 
* 
戻り値
 
 
 
 
 
 
前提条件
既存のファイルを基に空のファイルを作成する場合は、Create オペレーションを実行する前に必ずその既存ファイルは閉じているようにします。
手順
1 オペレーション コードを 14 に設定します。
2 詳細の説明に従い、データ バッファーにファイル仕様、キー仕様、およびオルタネート コレーティング シーケンス(ACS)を設定します。データ バッファーに格納するファイル仕様とキー仕様の値はすべて、バイナリ形式でなければなりません。
3 データ バッファー長を設定します。これは、Create の指定を含むバッファーの長さであり、ファイルのレコード長ではありません
4 キー バッファーにファイルのパス名を設定します。パス名の終端は必ず空白かバイナリ ゼロにします。パス名は、ボリューム名および終端文字を含めて、255 文字までの範囲で指定することができます。
PSQL クライアントでサポートするパス名の詳細については、『Getting Started with PSQL』の PSQL リクエスターでサポートするネットワーク パスの形式を参照してください。『PSQL Programmer's Guide』のデータベース URI も参照してください。
5 キー番号パラメーターの値を、表 19 内のいずれかの選択肢を使って設定します。
詳細
データ バッファーには、作成するファイルの仕様とキーの仕様を格納します。Create(14)と Stat(15)は同様のデータ バッファー構造体を使用するため、それらのわずかな違いも含め、ここでまとめて説明されています。以下の表は、BTRV タイプ、さらに BTRVEX タイプのエントリ ポイントに関する情報の構造体を示しています。これら両方の説明は Btrieve API 関数にあります。
2 つのタイプのエントリ ポイント間には、仕様内の要素の順序に違いがあることに留意してください。これらの要素の詳細については、以下のトピックを参照してください。
ファイル仕様ブロック
キー仕様ブロック
データ バッファーには、ファイル仕様と、0 個以上のキー仕様ブロック、0 個以上の ACS ブロックを格納します。
 
表 8 Create および Stat オペレーションで使用される、BTRV タイプのエントリ ポイントのファイル仕様
説明
データ型1
バイト番号
論理固定レコード長。すべてのレコード フィールドの結合サイズです。3
Short Int3
0-1
ページ サイズ。ページ サイズ値を参照してください。
Short Int3
2-3
キー(インデックス)数
Byte
4
ファイル バージョン4ファイル バージョンの値を参照してください。
Byte
5
レコード数。Create(14)オペレーションの場合、下位バージョンとの互換性を保つために 0 に初期化します。
Int3
6-9
ファイル フラグ。ファイル属性を設定します。ファイル フラグの値を参照してください。
Short Int3
10-11
追加ポインター数。Create(14)の場合は、将来のキーの追加のために予約する重複ポインター数です。Stat(15)の場合は、残っているポインター数です。予約重複ポインター フラグと共に使用されます。
Byte
12
物理ページ サイズ。圧縮フラグが設定されている場合に使用されます。値は、512 バイト ブロックの数です。
Byte
13
プリアロケート ページ数。事前に割り当てられるページ数です。ページ プリアロケーションと共に使用されます。Stat(15)の場合は、未使用の空きページ数を返します。
Short Int3
14-15
1 特に指定がない場合、すべてのデータ型は符号なしです。
2 可変長レコードを持つファイルの場合、論理レコード長はレコードの固定長部分のみを指します。
3 Integer は「リトル エンディアン」のバイト順、つまり、Intel 系のコンピューターが採用している下位バイトから上位バイトへ記録する方式で格納する必要があります。
4 Stat(15)のキー番号が 0 の場合は、0 として返されます。
 
 
表 9 Create および Stat オペレーションで使用される、BTRVEX タイプのエントリ ポイントのファイル仕様
説明
データ型1
バイト番号
論理固定レコード長。すべてのレコード フィールドの結合サイズです。
Short Int3
0-1
ページ サイズ。ページ サイズ値を参照してください。
Short Int3
2-3
ファイル フラグ。ファイル属性を設定します。ファイル フラグの値を参照してください。
Short Int3
4-5
予約済み下位バージョンとの互換性を保つために 0 に初期化します。
Short Int3
6-7
レコード数。Create(14)オペレーションの場合、下位バージョンとの互換性を保つために 0 に初期化します。
Long Long Int3
8-15
キー(インデックス)数
Short Int3
16-17
ファイル バージョン4。ファイル バージョンの値を参照してください。
Short Int3
18-19
追加ポインター数。Create(14)の場合は、将来のキーの追加のために予約する重複ポインター数です。Stat(15)の場合は、残っているポインター数です。予約重複ポインター フラグと共に使用されます。
Byte
20
物理ページ サイズ。圧縮フラグが設定されている場合に使用されます。値は、512 バイト ブロックの数です。
Byte
21
プリアロケート ページ数。事前に割り当てられるページ数です。ページ プリアロケーションと共に使用されます。Stat(15)の場合は、未使用の空きページ数を返します。
Short Int3
22-23
予約済み下位バージョンとの互換性を保つために 0 に初期化します。
Long Long Int3
24-31
1 特に指定がない場合、すべてのデータ型は符号なしです。
2 可変長レコードを持つファイルの場合、論理レコード長はレコードの固定長部分のみを指します。
3 Integer は「リトル エンディアン」のバイト順、つまり、Intel 系のコンピューターが採用している下位バイトから上位バイトへ記録する方式で格納する必要があります。
4 Stat(15)のキー番号が 0 の場合は、0 として返されます。
ファイル仕様ブロック
データ バッファーの先頭 16 バイトまたは 32 バイトにはファイル仕様を格納します。バイト位置は 0 から始まります。レコード長、ページ サイズおよびインデックス数の情報を整数で格納します。
論理固定レコード長。論理レコード長は、ファイル内の固定長データのバイト数です。論理レコード長には可変長データを含めないでください。
ページ サイズ。ページ サイズはファイル形式のバージョンによって決まっています。『PSQL Programmer's Guide』のページ サイズの選択を参照してください。次の表は、さまざまなファイル形式バージョンのページ サイズの例を示しています。
表 10 ページ サイズ値
説明
ファイル形式バージョン
データ型1
バイト番号
値の例2
ページ サイズ
6.x から 9.0
Short Int3
2-3
512
6.x から 9.5
1024
6.x から 9.0
1536
6.x から 9.5
2048
6.x から 9.0
3072
3584
6.x 以上
4096
9.0 以上
8192
9.5 以上
16384
ほとんどのファイルでは最小サイズの 4096 バイトが最も効率的です。微調整を行う場合は、『PSQL Programmer's Guide』のページ レベル圧縮を用いたファイルの作成を参照してください。
9.5 以降の形式のファイルを作成する場合、指定された論理ページ サイズがそのファイル形式で有効でなければ、MicroKernel は指定値の次に大きな有効値があるかどうかを調べ、存在する場合はその値に切り上げます。それ以外の値やファイル形式の場合、オペレーションはステータス コード 24 で失敗します。古いバージョンのファイル形式では、切り上げは行われません。
1 特に指定がない場合、すべてのデータ型は符号なしです。
2 簡素化を図るため、数値以外の値の例は C アプリケーションの場合です。
3 Integer は「リトル エンディアン」のバイト順、つまり、Intel 系のコンピューターが採用している下位バイトから上位バイトへ記録する方式で格納する必要があります。
レコード数。ファイル内のレコード数です。この値は Stat(15)によって返されます。Create(14)では、このフィールドを 0 に設定します。
キー数。インデックス数はファイルに対して定義しているキーの数です。キー セグメント数ではありません。データオンリー ファイルを作成するには、インデックス数を 0 に設定します。
ファイル バージョン。作成する MicroKernel エンジンのファイル バージョンです。以前のリリースでは、MicroKernel エンジンは 2 バイト整数を使って Create オペレーションでインデックス数を取得していました。インデックスの最大数は 119 であるため、この整数の上位バイトは常に 0 でした。この上位バイトは、これまで Stat(15)オペレーションでファイル バージョンを返すために使用されてきましたが、Create でファイル バージョンを指定するために使用できるようになりました。これにより、以前のアプリケーションでエラーが発生することはありません。Create でサポートされるファイル バージョンは 6.0、7.0、8.0、9.0、9.5、および 13.0 です。これらは、それぞれ 16 進数の値 0x50、0x60、0x70、0x80、0x90、0x95、0xD0 で特定のバイトに示されます。次の表は、さまざまなファイル形式バージョンのファイル バージョン フラグの値を示しています。
 
表 11 ファイル バージョンの値
説明
データ型1
バイト番号
値の例2
ファイル バージョン
メモ:13.0 ファイル バージョンではデータ型が異なります。
BTRV タイプ:Byte
BTRVEX タイプ:Short Int
5
18-19
バージョン 6.0
0x60
バージョン 7.0
0x70
バージョン 8.0
0x80
バージョン 9.0
0x90
バージョン 9.5
0x95
バージョン 13
0xD0
データベース エンジンのデフォルトを使用
0x00
1 特に指定がない場合、すべてのデータ型は符号なしです。
2 簡素化を図るため、数値以外の値の例は C アプリケーションの場合です。
追加ポインター数。Create(14)の場合は、将来のキーの追加のために予約する重複ポインター数です。Stat(15)の場合は、残っているポインター数です。予約重複ポインター フラグと共に使用されます。このフラグを使用しないときは、このフィールドを 0 に設定します。
物理ページ サイズ。ページ圧縮ファイル フラグが設定されている場合に使用されます。ページ圧縮フラグが指定されていない場合は、このフィールドを 0 に設定します。このフィールドは、以前は「未使用」とマークされていました。
バージョン 6.x 以降のデータ ファイルでは、論理ページは物理ページに割り当て、ページ アロケーション テーブル(PAT)に格納します。物理ページのサイズは論理ページのサイズと同一です。ページ圧縮は 9.5 以降のファイル形式で使用できます。データベース ページはページ レベルで圧縮されます。各論理ページは、1 つ以上の物理ページ単位に圧縮されます。これら個々の物理ページのサイズは、1 論理ページよりも小さくなります。
物理ページ サイズ フィールドを使用して、ファイルで使用する物理ページ サイズを指定できます。このフィールドで指定する値は、使用される実際の物理ページ サイズを決定するため、512 の倍数にします。0 を指定すると、エンジンは物理ページ サイズのデフォルト値の 512 を使用します。
物理ページ サイズに指定された値は、論理ページ サイズに指定された値よりも大きくすることはできません。物理ページ サイズに指定された値の方が大きい場合、エンジンは論理ページ サイズと同じになるようその値を切り捨てます。論理ページ サイズは物理ページ サイズの倍数になっていなければなりません。倍数でない場合、その論理ページ サイズの値は物理ページ サイズの値のちょうど倍数になるよう切り捨てられます。このような操作の結果として、論理ページ サイズと物理ページ サイズの値が同じになった場合、ページ レベルの圧縮はこのファイルに適用されません。『PSQL Programmer's Guide』のページ レベル圧縮を用いたファイルの作成も参照してください。
ファイル フラグ。ファイル フラグ ワードのビットをセットして、ファイル属性を指定します。次の表に、ファイル フラグの値の 2 進、16 進、および 10 進表記を示します。
表 12 ファイル フラグの値
属性
定数
2 進数
16 進数
10 進数
可変長レコード
VAR_RECS
0000 0000 0000 0001
1
1
ブランク トランケーション
BLANK_TRUNC
0000 0000 0000 0010
2
2
ページ プリアロケーション
PRE_ALLOC
0000 0000 0000 0100
04
4
データ圧縮
DATA_COMP
0000 0000 0000 1000
08
8
キーオンリー ファイル
KEY_ONLY
0000 0000 0001 0000
10
16
インデックス バランス
BALANCED_KEYS
0000 0000 0010 0000
20
32
10% 空きスペース スレッショルド
FREE_10
0000 0000 0100 0000
40
64
20% 空きスペース スレッショルド
FREE_20
0000 0000 1000 0000
80
128
30% 空きスペース スレッショルド
FREE_30
0000 0000 1100 0000
C0
192
予約重複ポインター
DUP_PTRS
0000 0001 0000 0000
100
256
システムデータを含める1
INCLUDE_SYSTEM_DATA
0000 0010 0000 0000
200
512
システム データを含めない
NO_INCLUDE_SYSTEM_DATA
0001 0010 0000 0000
1200
4608
キー番号
SPECIFY_KEY_NUMS
0000 0100 0000 0000
400
1024
VAT の使用
VATS_SUPPORT
0000 1000 0000 0000
800
2048
ページ圧縮の使用2
PAGE_COMPRESSED
0010 0000 0000 0000
2000
8192
1 システム データをファイルに含めるかどうかを明示的に指定していない場合、Btrieve API は、MicroKernel エンジン構成のその時点の「システム データを含める」設定を使用します。
2 ページ レベル圧縮でのみ使用します。「物理ページ サイズ」キー仕様と組み合わせて使用されます。『PSQL Programmer's Guide』のページ レベル圧縮を用いたファイルの作成を参照してください。
互換性のないフラグの使用は避けてください。同一ビット位置を使用するフラグ間には互換性はありません。未使用のビットは将来使用するために予約されています。これらのビットを 0 に設定します。
ファイルの属性を組み合わせるには、対応するファイル フラグの値を加算します。たとえば、可変長レコードを含むことができ、ブランク トランケーションを行うファイルを指定するには、ファイル フラグ ワードを 3(2 + 1)に初期化します。可変長レコードのビットが 0 に設定されている場合、MicroKernel エンジンではブランク トランケーションおよび空きスペース スレッショルドのビットを無視します。
ページ プリアロケーションのビットを設定する場合は、ファイル仕様ブロック(アロケーション)の最後の 2 バイトを使用して、ファイルにプリアロケートするページ数を指定する整数値を格納してください。データ圧縮のビットを設定した場合、MicroKernel エンジンでは可変長レコードのビットが無視されます。キーオンリー ファイルのビットを設定した場合、MicroKernel エンジンではシステム データのビットが無視されます。
データベース エンジンは、システム データを使用しており、レコード長が許容最大サイズを超えるファイルについては自動的にデータ圧縮を使用します。『PSQL Programmer's Guide』の表 8 を参照してください。
ファイルを作成したでインデックスの追加が予想される場合、および、そのインデックスには重複した値が含まれるが、繰り返し重複としてマークされない場合は、重複ポインターのビットを設定します。このビットを設定すると、MicroKernel エンジンでは重複した値をリンクするポインターのためにファイルの各レコードにスペースが確保されるようになります。このようなスペースを確保することにより、特に、キーが長く、多数のレコードが重複するキー値を持つことが予測される場合には、検索時間を短縮し、ディスク領域を節約できる場合があります。
メモ:重複ポインターの領域は、ファイル作成後に追加されるインデックスのみを対象に予約できます。したがって、重複値へのポインターのために領域を確保するときは、この Create オペレーションの実行中に作成されるインデックスの領域は含めないでください。また、繰り返し重複キーとして指定されるキーについて、MicroKernel エンジンは重複ポインターの領域を確保しません。
特定の番号をキーに割り当てることが必要な場合は、キー番号のビットを設定し、希望するキー番号をキー仕様ブロックの手動割り当てキー番号要素(オフセット 0x0E)に入れます。MicroKernel エンジンではキー番号が連続している必要はありません。つまり、ファイルのキー番号は飛んでいてもかまいません。キーが作成されると、MicroKernel エンジンはデフォルトで、0 から始まるキー番号のうち使用可能な最小の番号をそのインデックスに割り当てます。ただし、アプリケーションによっては、デフォルトの割り当てとは異なるキー番号が必要なこともあります。
ファイルで可変長部割り当てテーブルを使用する場合は、VAT の使用のビットを設定します。VAT を使うには、ファイルで可変長レコードを使用していることが必要です。
プリアロケート ページ数。プリアロケートするページ数を指定できます。ページ プリアロケーションのファイル フラグを指定した場合にのみ、この要素を使用してください。ページ プリアロケーションの詳細については、『PSQL Programmer's Guide』のページ プリアロケーションを参照してください。
キー仕様ブロック
ファイル仕様のすぐ後に 0 個以上のキー仕様ブロックを配置します。ファイルのキー セグメントごとに 16 バイトまたは 24 バイトののキー仕様ブロックを割り当てます。キー ポジションおよびキー長の情報は整数で格納します。
次の表で示すように、許容されるキー セグメントの最大数は、ファイルのページ サイズおよびファイル形式によって決まります。
ページ サイズ(バイト数)
キー セグメントの最大数(ファイル バージョン別)
8.x 以前
9.0
9.5
13.0
512
8
8
切り上げ2
切り上げ2
1024
23
23
97
切り上げ2
1536
24
24
切り上げ2
切り上げ2
2048
54
54
97
切り上げ2
2560
54
54
切り上げ2
切り上げ2
3072
54
54
切り上げ2
切り上げ2
3584
54
54
切り上げ2
切り上げ2
4096
119
119
2043
1833
8192
N/A1
119
4203
3783
16384
N/A1
N/A1
4203
3783
1 N/A は「適用外」を意味します。
2 「切り上げ」は、ページ サイズを、ファイル バージョンでサポートされる次のサイズへ切り上げることを意味します。たとえば、512 は 1024 に切り上げられ、2560 は 4096 に切り上げるということです。
3 9.5 以降の形式のファイルでは 119 以上のセグメントを指定できますが、インデックスの数は 119 に制限されます。
Status Codes and Messages』のステータス コード 26:指定されたキーの数が不正です。および 29:キー長が不正です。を参照してください。
次の表は、キー仕様のデータ バッファー構造体を示しています。各キー仕様ブロックは、BTRV タイプのエントリ ポイントの場合は 16 バイト、BTRVEX タイプのエントリ ポイントの場合は 24 バイトです。2 つのデータ型が示されている場合、1 つめは BTRV で使用され、2 つめは BTRVEX で使用されます。オフセットは、各キー ブロックについて繰り返されます。
表 13 Create(14)または Stat(15)のキー セグメントを指定するためのデータ バッファー
説明
データ型1
BTRV のオフセット
BTRVEX のオフセット
キー ポジション。レコード内のキーの最初のバイトの位置。レコード内の最初のバイトは 1 です。
Short Int2
0-1
0-1
キー長。バイト単位のキーの長さ。
Short Int2
2-3
2-3
キー フラグ。キー属性。
Short Int2
4-5
4-5
予約済みCreate(14)では使用されません。下位バージョンとの互換性を保つために 0 に初期化します。
Short Int2
6-7
一意キー。Create(14)では使用されません。下位バージョンとの互換性を保つために 0 に初期化します。
Int または Long Long Int2
6-9
8-15
拡張データ型。キー フラグで「拡張データ型を使用」を指定する場合に使用されます。
Byte または Short Int2
10
16-17
ヌル値(レガシー ヌルのみ)。キー フラグで「ヌルキー(全セグメント)」または「ヌルキー(一部セグメント)」を指定する場合に使用されます。これは、キーの除外値です。レガシー ヌルと真のヌルの概念については、ヌル値を参照してください。
Byte
11
18
予約済みCreate(14)では使用されません。下位バージョンとの互換性を保つために 0 に初期化します。
Short Int2 または Byte
12-13
19
手動割り当てキー番号。ファイル属性で「キー番号」を指定する場合に使用されるキー番号。
Byte または Short Int2
14
20-21
ACS 番号。ACS(オルタネート コレーティング シーケンス)の番号です。キー フラグで「デフォルトの ACS を使用する」、「ファイル内の番号付きの ACS を使用する」または「名前付きの ACS を使用する」を指定する場合に使用されます。
Byte
15
22
予約済みCreate(14)では使用されません。下位バージョンとの互換性を保つために 0 に初期化します。
Byte
23
1 特に指定がない場合、すべてのデータ型は符号なしです。
2 Integer は「リトル エンディアン」のバイト順、つまり、Intel 系のコンピューターが採用している下位バイトから上位バイトへ記録する方式で格納する必要があります。
キー ポジション。キー ポジションは、キーまたはキー セグメントの開始位置のバイト オフセットです。ポジションは 1 からの相対になります。レコードの先頭に位置するキーは、ポジション 1 から始まります。ポジション 0 はありません。
キー長。キーまたはキー セグメントの長さです。キーの最大長は、すべてのキー セグメントを含めて、255 バイトです。
キー フラグ。キー フラグ ワードのビットをセットして、キー属性を指定します。次の表に、キー フラグの値の 2 進、16 進、および 10 進表記を示します。
表 14 キー フラグの値
属性
定数
2 進数
16 進数
10 進数
重複許可(リンクされた重複はデフォルト、あるいは繰り返し重複用に REPEAT_DUPS_KEY と組み合わせる)
DUP
0000 0000 0000 0001
0x1
1
変更可能キー
MOD
0000 0000 0000 0010
0x2
2
旧形式の BINARY データ型を使用
BIN
0000 0000 0000 0100
0x4
4
旧形式の STRING データ型を使用(ビット 2 および 8 は 0 にする必要があります)
 
0000 0000 0000 0000
0x0
0
ヌル キー(全セグメント)
NUL
0000 0000 0000 1000
0x8
8
セグメント キー
SEG
0000 0000 0001 0000
0x10
16
デフォルトの ACS を使用
ALT
0000 0000 0010 0000
0x20
32
ファイル内の番号付きの ACS を使用
NUMBERED_ACS
0000 0100 0010 0000
0x420
1056
名前付きの ACS を使用
NAMED_ACS
0000 1100 0010 0000
0xC20
3104
降順ソート
DESC_KEY
0000 0000 0100 0000
0x40
64
繰り返し重複。DUP 属性と共に使用されます
REPEAT_DUPS_KEY
0000 0000 1000 0000
0x80
128
拡張データ型を使用
EXTTYPE_KEY
0000 0001 0000 0000
0x100
256
ヌル キー(一部セグメント)
MANUAL_KEY
0000 0010 0000 0000
0x200
512
大文字小文字無視キー
NOCASE_KEY
0000 0100 0000 0000
0x400
1024
互換性のないフラグの使用は避けてください。同一ビット位置を使用するフラグ間には互換性はありません。未使用のビットは将来使用するために予約されています。これらのビットを 0 に設定します。
キーの属性を組み合わせるには、それらの値を合計します。たとえば、キーが拡張キー タイプで、セグメント キーの一部であり、さらに降順に照合される場合は、キー フラグ ワードを 336(256 + 16 + 64)に初期化します。
セグメント キー属性は、データ バッファー内の次のキー仕様ブロックが同一キーの次のセグメントを指すことを示します。セグメント キーについては以下の規則に従ってください。
同一キーのすべてのセグメントで、重複可能、繰り返し重複、変更可能、およびヌル キーの値はそれぞれ同じでなければなりません。メモ:レガシー ヌル キー属性を指定する場合は、全セグメントまたは一部セグメントのどちらの場合にも、セグメントごとに異なるヌル値を割り当てることができます。
同一キーのすべてのセグメントで、同一 ACS(オルタネート コレーティング シーケンス)を使用する必要があります。
同一キーのセグメントごとに、異なる降順ソートおよび拡張データ型の値を設定できます。
ACS は、STRING、LSTRING、ZSTRING、WSTRING、および WZSTRING 型のキーにのみ適用されます。大文字小文字の区別を無視し、かつ ACS を使用するキーを定義することはできません。あるキーの一部のセグメントにしか ACS が指定されていないファイルの場合、ACS が指定されているセグメントはその ACS に従ってソートされるのに対し、ACS が指定されていないセグメントはそれぞれの型に従ってソートされます。
拡張データ型。拡張データ型をキー仕様ブロックのバイトにバイナリ値で指定します。表 15 に、拡張データ型に対応するコードを示します。
表 15 拡張データ型
データ型
コード
データ型
コード
STRING
0
ZSTRING
11
INTEGER
1
UNSIGNED BINARY
14
FLOAT
2
AUTOINCREMENT
15
DATE
3
NUMERICSTS
17
TIME
4
NUMERICSA
18
DECIMAL
5
CURRENCY
19
MONEY
6
TIMESTAMP
20
LOGICAL
7
WSTRING
25
NUMERIC
8
WZSTRING
26
BFLOAT
9
GUID
27
LSTRING
10
NULL INDICATOR SEGMENT
255
拡張データ型のコード 12、13、16 および 21 から 24 までは将来使用するために予約されています。
STRING および UNSIGNED BINARY データ型は、標準型と拡張型のどちらとしても定義できます。これにより、以前のバージョンの Btrieve API を使って開発したアプリケーションとの互換性が保てる一方、新しいアプリケーションで拡張データ型を排他的に使用できるようになります。
キーに割り当てるデータ型に関し、入力したレコードがそのキーに定義されているデータ型に合っているかどうかは、MicroKernel エンジンでは確認されません。たとえば、TIMESTAMP キーをファイルに定義することができますが、そこに文字列を格納することもできます。Btrieve API アプリケーションでは問題なく動作していても、ODBC アプリケーションで同じデータに ODBC TIMESTAMP データ型を使ってアクセスしようとすると、正常に動作しないことがあります。これはおそらく、バイトの形式が異なり、タイムスタンプ値を生成するアルゴリズムが異なるからです。データ型の説明については、『SQL Engine Reference』を参照してください。
ヌル値。キーの除外値を表します。あるキーをヌル キーとして定義した場合は、各キー セグメントのヌル値として認識させる値を MicroKernel エンジンに提供する必要があります。これは、レガシー ヌルへの参照内にあり、真のヌルには影響しません。ヌル サポートの説明については、『PSQL Programmer's Guide』のヌル値を参照してください。
手動割り当てキー番号。MicroKernel エンジンでは、インデックス付きのファイルを作成するときに、アプリケーションで特定のキー番号を割り当てることができます。ファイルの各インデックスに手動でキー番号を割り当てるには、各キー番号をキー仕様ブロックにバイナリ値で指定し、ファイル フラグ ワードにキー番号ビット(0x400)を設定します。
キー番号はファイルで一意であり、キー 0 から昇順に指定されていなければなりません。また、有効な値、つまり、ファイルのページサイズに対するキーの最大数よりも小さい値でなければなりません。
手動でキー番号を割り当てるという機能は、キーを削除して、その削除したキーよりも大きなキー番号を持つすべてのキーの番号を MicroKernel エンジンに付け替えさせないようにする機能と相補関係にあります。たとえば、アプリケーションからインデックスを削除し、MicroKernel エンジンにそれよりも大きな番号を持つキーの番号を付け替えないように指示を出した場合、その後でユーザーが具体的なキー番号を割り当てずに影響を受けたファイルを複製すると、複製したファイルには元のファイルとは別のキー番号が割り当てられます。
ACS 番号。特定の ACS を使用するキーの場合、キー仕様ブロックにより、キーの照合に使用する ACS 番号が示されます。ACS 番号はデータ バッファー内の位置に基づいて決まります。最後のキー仕様ブロックに続く最初の ACS は、ACS 番号 0 になります。ACS 0 の次には ACS 1、その次には ACS2、というように続きます。
オルタネート コレーティング シーケンス(ACS)
コレーティング シーケンスは、Create オペレーションのデータ バッファーで、最後のキー仕様ブロックの直後から 1 つずつ順番に現れます。以下の表で、ACS、ISR、または ICU 照合順序を指定するために使用される 265 バイトについて説明します。
ユーザー定義の ACS ファイル文字列値を ASCII 標準とは異なる並び順でソートする ACS を作成するには、アプリケーションからデータ バッファに直接 265 バイトを設定する必要があります。
表 16 ユーザー定義の ACS を作成するためのデータ バッファー
位置(オフセット)
長さ (バイト単位)
説明
0
1
識別バイト。0xAC を指定します。
1
8
MicroKernel エンジンに ACS を識別させる、8 バイトの一意の名前。
9
256
256 バイトのマップ。マップ内の 1 バイトの位置はそれぞれ、マップ内でのその位置のオフセットと同じ値を持つコード ポイントに対応します。その位置にあるバイトの値は、コード ポイントに割り当てられる照合重みです。たとえば、コード ポイント 0x61('a')をコード ポイント 0x41('A')と同じ重みでソートさせるには、オフセット 0x61 および 0x41 に同一の値を設定します。
ユーザー定義の ACS ファイルの例については、『PSQL Programmer's Guide』のオルタネート コレーティング シーケンスを参照してください。
インターナショナル ソート規則(ISR)。ISR テーブル名を指定するには、アプリケーションからデータ バッファーに直接 265 バイトを設定する必要があります。
表 17 ISR 照合順序を指定するためのデータ バッファー
位置(オフセット)
長さ(バイト単位)
説明
0
1
識別バイト。0xAE を指定します。
1
16
MicroKernel エンジンに ISR テーブルを識別させる、16 バイトの一意の名前。ISR テーブル名の一覧については、『PSQL Programmer's Guide』を参照してください。
17
248
Filler
Unicode 照合順序。ICU(International Components for Unicode)標準に従って Unicode 照合順序を指定するには、アプリケーションからデータ バッファーに直接 265 バイトを設定する必要があります。
表 18 Unicode 照合順序を指定するためのデータ バッファー
位置(オフセット)
長さ(バイト単位)
説明
0
1
識別バイト。0xAE を指定します。
1
16
サポートされる ICU 照合順序の名前。u54-msft_enus_0 または root のいずれかになります。16 バイトになるまでスペースを詰める必要があります。
17
248
Filler
データ バッファー長
データ バッファー長は、ファイル仕様、キー仕様、および定義されている ACS ファイルを十分に格納できるだけの長さを持つ必要があります。このパラメーターにファイルのレコード長を指定しないでください。
たとえば、BTRV エントリ ポイントを使用して、1 セグメントのキーを 2 つと ACS を 1 つ持つファイルを作成するには、Create オペレーションのデータ バッファーには、以下のように少なくとも 313 バイトの長さが必要です。
ファイル仕様
+
キー仕様
+
キー2 仕様
+
ACS
 
16
+
16
+
16
+
265
= 313
キー番号
Create オペレーションのキー番号は、同名のファイルが既に存在する場合に MicroKernel エンジンが警告を出すかどうか、また、ファイルの作成時に MicroKernel エンジンがローカル エンジンとリモート エンジンのどちらを使用するかを決定します。
次の表を使って、キー番号パラメーターの値を選択します。
表 19 Create オペレーションのキー番号パラメーター
CREATE オペレーション
選択しない
ローカル エンジンにファイルを作成させる
リモート エンジンにファイルを作成させる
標準の作成(ファイルが既存の場合、上書きする)
0
6
99
ファイルが既存の場合、ステータス 59 を返す
-1
7
100
Create オペレーションによる削除および名前変更サブファンクション
Create オペレーションには 2 つのサブファンクションがあり、これを使用してファイルの削除または名前変更ができます。
Pervasive.SQL v8.5 より前は、オペレーティング システムを介して MicroKernel エンジン ファイルを操作することは常に可能でした。これは、オペレーティング システムが PSQL ユーザーに与える権限にエンジンが依存していたためです。
v8.5 で PSQL データベース セキュリティが導入されると、承認されていないアクセスに対しデータベースがセキュリティで保護されている場合には、このようなオペレーティング システムのアクセス権は除去されることがあります。オペレーティング システムの権限が常に利用できるとは限らなくなるため、プログラムによるファイルの削除や移動のためのオプションは変更される可能性があります。
名前変更と削除のサブファンクションは、代替キー番号を持つ Create オペレーションとして実装されています。新規データ ファイルを作成する場合のようにファイル仕様を指定する必要はありません。Create オペレーションで名前変更と削除サブファンクションを使用するための設定方法を、次の表に示します。
表 20 Create オペレーションのサブファンクション
操作
使用するキー番号
説明
データ バッファーに指定するもの
キー バッファーに指定するもの
ファイルの名前変更
-127
データ バッファーの既存のファイルを、キー バッファーの名前に変更します。
既存のファイル名
新しいファイル名
ファイルの削除
-128
ファイルを削除します。
適用外
既存のファイル名
これらのサブファンクションはセキュリティ モデルで動作するように変更されました。その変更点として、サブファンクションは削除または名前変更する MicroKernel エンジン ファイルを示すために、必要に応じて、キー バッファーおよびデータ バッファーでファイル名の代わりに URI を受け入れるようになりました。これにより、セキュリティ情報をオペレーションに指定することができます。URI 接続文字列の詳細については、『PSQL Programmer's Guide』のデータベース URI を参照してください。
セキュリティ情報は、通常の Create または Open オペレーションとまったく同様に処理されます。ユーザーは認証され、かつ、既存のファイルに対して、また新しいファイルの保存場所となるディレクトリに対して DB_RIGHT_CREATE、DB_RIGHT_ALTER、および DB_RIGHT_OPEN 権限を持っている必要があります。
表 21 Create サブファンクション - キー バッファーでの URI パラメーターの使用
操作
URI パラメーター file=
URI パラメーター dbfile=
URI パラメーター table=
名前変更
* 
* 
* 
削除
* 
* 
* 
 
表 22 Create サブファンクション - データ バッファーでの URI パラメーターの使用
操作
file=
dbfile=
table=
名前変更
* 
* 
* 
削除
適用外
適用外
適用外
名前変更および削除サブファンクションでの注意
以前の Create オペレーションの機能は変更されていません。MicroKernel エンジン データ ファイルを新規作成する場合は、既存マニュアルの Create オペレーションの説明に従ってください。
RenameFile および DeleteFile サブファンクションは種々雑多なページの内容には影響しないため、特定のデータベースにバインドされているファイルに使用することはできません。
ファイルにオーナー ネームが含まれている場合、新しいサブファンクションではオーナー ネームのチェックは行われません。オーナー ネームはファイルの内容を表示させるためには、引き続き必要です。
結果
Create オペレーションが正常に終了した場合は、MicroKernel エンジンから同名のファイルが既に存在すると警告されるか、仕様に従って新しいファイルが作成されます。新規ファイルにはレコードは含まれていません。Create オペレーションでは作成したファイルを開きません。したがって、ファイルにアクセスするには、アプリケーションで Open オペレーションを実行する必要があります。
Create オペレーションが失敗した場合は、MicroKernel エンジンから次のステータス コードのいずれかが返されます。
2
アプリケーションで I/O エラーが発生しました。
11
指定されたファイル名は不正です。
18
ディスクがいっぱいです。
22
データ バッファー パラメーターが短すぎます。
24
ページ サイズまたはデータ バッファー サイズが不正です。
25
アプリケーションが指定されたファイルを作成できません。
26
指定されたキーの数が不正です。
27
キー ポジションが不正です。
28
レコード長が不正です。
29
キー長が不正です。
48
オルタネート コレーティング シーケンス定義が不正です。
49
拡張キー タイプが不正です。
59
指定されたファイルは既に存在します。
104
MicroKernel エンジンがロケールを認識しません。
105
このファイルは、可変長部割り当てテーブル(VAT)付きで作成することはできません。
134
MicroKernel エンジンがインターナショナル ソート規則(ISR)を読み取れません。
135
指定されたインターナショナル ソート規則(ISR)テーブルは破損しているか、または不正です。
ポジショニング
Create オペレーションを実行しても、ファイルにカレンシーは確立しません。
Create Index(31)
Create Index オペレーション(B_BUILD_INDEX)では、既存のファイルにキーを追加します。
パラメーター
 
 
オペレーション コード
ポジション ブロック
データ バッファー
データ バッファー長
キー バッファー
キー番号
送り値
* 
* 
* 
* 
 
* 
戻り値
 
 
 
 
 
 
前提条件
対象となるファイルが開いていることが必要です。
ファイル内の既存のキー セグメント数は、許容されるキー セグメントの最大数から追加するキー セグメント数を差し引いた値以下でなければなりません。
許容されるキー セグメントの最大数は、ファイルのページ サイズによって決まります。次の表は、これらの値の一覧を示します。
ページ サイズ(バイト数)
ファイル バージョンによる最大キー セグメント数
8.x 以前
9.0
9.5
13.0
512
8
8
切り上げ2
切り上げ2
1024
23
23
97
切り上げ2
1536
24
24
切り上げ2
切り上げ2
2048
54
54
97
切り上げ2
2560
54
54
切り上げ2
切り上げ2
3072
54
54
切り上げ2
切り上げ2
3584
54
54
切り上げ2
切り上げ2
4096
119
119
2043
1833
8192
N/A1
119
4203
3783
16384
N/A1
N/A1
4203
3783
1 N/A は「適用外」を意味します。
2 「切り上げ」は、ページ サイズを、ファイル バージョンでサポートされる次のサイズへ切り上げることを意味します。たとえば、512 は 1024 に切り上げられ、2560 は 4096 に切り上げるということです。
3 9.5 以降の形式のファイルでは 119 以上のセグメントを指定できますが、インデックスの数は 119 に制限されます。
Status Codes and Messages』のステータス コード 26:指定されたキーの数が不正です。および 29:キー長が不正です。を参照してください。
新しいキーのキー フラグ、位置および長さが、キーを追加しようとしているファイルに対して適切であることを確認します。
トランザクションが実行中でないことが必要です。
手順
1 オペレーション コードを 31 に設定します。
2 キーを追加するファイルのポジション ブロックを渡します。
3 キーの各セグメントについて、キー仕様ブロックをデータ バッファーに格納します。Create(14)で説明されているものと同じ構造体を使用します。キー ポジションおよびキー長の情報は整数で格納します。システム定義のログ キー(システム データとも言います)を再構築している場合、データ バッファーは少なくとも 1 つのキー仕様ブロックのサイズがあり、ゼロに初期化されている必要があります。
4 新しいキーに ACS を定義するには、次のいずれかの手順を実行します。
デフォルトの ACS、つまり、ファイルに既に定義されている先頭の ACS を使用するには、キー フラグ ワードに「デフォルトの ACS を使用」属性を指定します。
新しい ACS を定義するには、キー フラグ ワードに「番号付きの ACS を使用」属性を指定し、ACS 番号フィールドをゼロに設定します。さらに、データ バッファーの最後のキー仕様ブロックの後に 265 バイトの ACS を格納します。
名前によって既存の ACS を指定するには、キー フラグ ワードに「名前付きの ACS を使用」属性を指定し、ACS 番号フィールドをゼロに設定します。さらに、ACS 名を、データ バッファーの最後のキー仕様ブロックの後にある 265 バイトのブロックの先頭から格納します(名前より後の ACS ブロックの残り部分は無視されます)。名前の形式は次のいずれかに従っている必要があります。
 
ACS の種類
長さ(バイト単位)
説明
ユーザー定義の ACS
1
識別バイト 0xAC
"
8
ACS テーブル名
ISR
1
識別バイト 0xAE
"
16
ISR テーブル名
 
5 データ バッファー長パラメーターをデータ バッファー内のバイト数に設定します。新しいキーが ACS を持たない、もしくはデフォルトの ACS を使用する場合は、次の式を使って正しいデータ バッファー長を決定します。
(16 または 24) * (セグメント数)
新しいキーでデフォルト以外の ACS を指定する場合は、次の式を使って正しいデータ バッファー長を決定します。
(16 または 24) * (セグメント数) + 265
6 作成されるキーに特定のキー番号を割り当てるには、目的のキー番号に 0x80 を加算し、その合計値をキー番号パラメーターに入れます。システム定義のログ キー(システム データ)を再構築している場合は、0xFD(つまり、キー番号 125 + 128)を指定します。BTRVEX では、このバイアスにより小さな正の値が生成されるため、符号拡張してはいけないということに留意してください。
メモ:キー番号はファイルで一意であることが必要です。また、有効な値でなければなりません。つまり、各キー番号の値は、指定したページ サイズに対して許容されるキー セグメントの最大数よりも小さい値でなければなりません。
詳細
MicroKernel エンジンでは、キーを作成するときに特定のキー番号を割り当てることができます。この機能は、キーを削除して、その削除したキーよりも大きなキー番号を持つすべてのキーの番号を MicroKernel エンジンに付け替えさせないようにする機能と相補関係にあります。アプリケーションがインデックスを削除し、MicroKernel エンジンにそれよりも大きな番号を持つキーの番号を付け替えないように指示を出した場合、その後でユーザーが具体的なキー番号を割り当てずに影響を受けたファイルを複製すると、複製したファイルには元のファイルとは別のキー番号が割り当てられます。
データ バッファーで ACS を定義すると、MicroKernel エンジンは ACS 定義をファイルに追加する前に、まず指定された名前を使って既存の ACS をチェックします。MicroKernel エンジンが指定された名前を持つ既存の ACS を検出した場合、MicroKernel エンジンはファイル内で ACS 定義の複製は行わず、既存の ACS と新しいキーとの関連付けを行います。
キー フラグ ワードに「名前付きの ACS を使用」属性を指定した場合、MicroKernel エンジンはデータ バッファーに指定された ACS 名を使ってファイル内で同名の ACS を検索してから、その ACS を新しいキーに割り当てます。
ファイルが複数の MicroKernel エンジン クライアントによって開かれており、そのクライアントのうちの 1 人が Create Index プロセスを開始した場合、リモート クライアントは、MicroKernel エンジン クライアントによってキーが作成されている間も、開いているファイルに対して Get および Step オペレーションを実行できます。
作成されるキーが autoincrement キーでない場合は、リモート クライアントの Get および Step オペレーションにロック バイアスを使用でき、Create Index プロセスが完了したときに、読み取りオペレーションをさらに発行しなくても、ロックされていたレコードを更新したり削除したりできます。MicroKernel エンジンではキーを作成するためにレコードのイメージを変更する必要がないため、このような処理が可能になります。
ただし、作成されるキーが autoincrement キーである場合は、MicroKernel エンジンではインデックスを構築し、かつ適切なフィールドでゼロ値を使ってすべてのレコードを変更する必要があります。キーの作成前または最中にロック バイアスを使わずに Get または Step オペレーションを実行したリモート クライアントは、キーの作成が正常に終了した後で Update または Delete オペレーションを実行するとき、ステータス コード 80 を受け取ります。
また、あるクライアントがレコードをロックしている最中に、別のクライアントが autoincrement キーを作成しようとすると、MicroKernel エンジンからステータス コード 84 が返されます。同様に、あるクライアントが autoincrement キーのインデックスを作成している最中に、別のクライアントがロック バイアスを使って Get または Step オペレーションを実行しようとすると、MicroKernel エンジンからステータス コード 85 が返されます。
結果
MicroKernel エンジンはファイルに新しいキーを直ちに追加します。このオペレーションの所要時間は、インデックスが作成される総レコード数、ファイルのサイズおよび新しいインデックスの長さによって変わります。
Create Index オペレーションが正常に終了した場合、新しいキーの番号は指定した番号になるか、または次のいずれかになります。
キー番号が飛んでいないファイルの場合は、新しいキー番号は以前の最大のキー番号より 1 つ大きくなります。
キー番号が飛んでいるファイルの場合は、新しいキー番号は欠けているキー番号のうちの最小の番号になります。
オペレーションの終了次第、新しいキーを使ってデータにアクセスすることができるようになります。
Create Index オペレーションが正常に実行されなかった場合、新しいインデックスの一部が既に構築されていたとしても、MicroKernel エンジンはそれをすべて削除します。エラーが発生する前に新しいインデックスに割り当てられたファイル ページは、ファイルの空き領域リストに置かれ、レコードを挿入したり別のキーを作成したりするときに再利用されます。
autoincrement キーの作成中にオペレーションが失敗した場合、それまでに変更されている値はそのまま残ります。MicroKernel エンジンから返される可能性のあるステータス コードは次のとおりです。
22
データ バッファー パラメーターが短すぎます。
27
キー ポジションが不正です。
41
実行しようとした操作は MicroKernel エンジンでは許可されていません。
45
指定したキー フラグが不正です。
49
拡張キー タイプが不正です。
56
インデックスが不完全です。
84
レコードまたはページがロックされています。
85
ファイルはロックされています。
104
MicroKernel エンジンがロケールを認識しません。
134
MicroKernel エンジンがインターナショナル ソート規則(ISR)を読み取れません。
135
指定されたインターナショナル ソート規則(ISR)テーブルは破損しているか、または不正です。
136
MicroKernel エンジンは、指定されたオルタネート コレーティング シーケンスをファイル内に見つけられません。
キーの作成中に処理が中断されても、ファイルのほかのキーを使ってファイルのデータにアクセスすることはできます。しかし、不完全なインデックスを使ってデータにアクセスしようとすると、MicroKernel エンジンから 0 以外のステータス コードが返されます。この問題を解決するには、Drop Index(32)オペレーションを使って不完全なインデックスを削除し、Create Index を再発行してください。
ポジショニング
Create Index オペレーションは、ファイルのカレンシー情報にまったく影響しません。
Delete(4)
Delete オペレーション(B_DELETE)では、ファイルから既存のレコードを削除します。削除したレコードが占有していたスペースは、新しいレコードを挿入するために再利用されます。
パラメーター
 
 
オペレーション コード
ポジション ブロック
データ バッファー
データ バッファー長
キー バッファー
キー番号
送り値
* 
* 
 
 
 
 
戻り値
 
* 
 
 
 
 
前提条件
対象となるファイルが開いていることが必要です。
対象となるファイルの物理カレンシーまたは論理カレンシーを確立しておくことが必要です。この要件を満たすオペレーションには、Get(Get ... Extended、Get Key を除く)、Step(Step ... Extended を除く)、Insert、および Update オペレーションがあります。
手順
1 オペレーション コードを 4 に設定します。
2 削除するレコードを含むファイルのポジション ブロックを渡します。
詳細
Delete オペレーションを Extended Get または Extended Step オペレーションの直後に実行した場合、これは有効なオペレーションになりません。
Delete オペレーションを実行した後、それ以降の Get Next または Get Previous オペレーションでは、論理位置を確立した直前のオペレーションと同じキー番号を使用する必要があります。別の値を使用すると、MicroKernel エンジンからステータス コード 7 が返されます。
MicroKernel エンジンでは、Get Key(+50)の後に Delete オペレーションを実行することはできません。MicroKernel エンジンで Delete オペレーションを実行する前に、変更しようとしているデータ ページの現在の使用回数と、レコードを読み取った時点のデータ ページの使用回数が比較されます。使用回数を取得するには、MicroKernel エンジンがデータ ページを読み取る必要があります。
Get Key オペレーションではデータ ページを読み取らないので、Delete オペレーションで比較するための使用回数が利用可能になりません。MicroKernel エンジンでは、比較なしにパッシブ並行制御の矛盾チェックを実行できないため、Delete オペレーションは正常に実行されません。Delete オペレーションが正常に実行されないと、MicroKernel エンジンからステータス コード 8 が返されます。
結果
Delete オペレーションが正常に終了した場合は、MicroKernel エンジンによってファイルからレコードが削除され、削除したレコードにロックが設定されていた場合はそのロックが解除され、さらに削除の結果を反映して、すべてのキー インデックスを調整されます。
Delete オペレーションが正常に実行されなかった場合は、MicroKernel エンジンから次のステータス コードのいずれかが返されます。
8
現在のポジションが不正です。
80
MicroKernel エンジンでレコード レベルの矛盾が発生しました。
84
レコードまたはページがロックされています。
85
ファイルはロックされています。
Delete オペレーションを実行してもファイル サイズは小さくなりません。レコードの削除によって生じる空き領域は、今後レコードを追加するときに再利用されます。ディスク容量を回復するには、ファイルを再作成して、そのファイルにすべてのレコードを挿入するしかありません。
ポジショニング
Delete オペレーションを実行すると、すべての物理位置情報と現在のレコードの論理位置は消去されますが、次のレコードまたは前のレコードの論理位置は変わりません。
Drop Index(32)
Drop Index オペレーション(B_DROP_INDEX)では、既存のファイルからキーを削除します。
パラメーター
 
 
オペレーション コード
ポジション ブロック
データ バッファー
データ バッファー長
キー バッファー
キー番号
送り値
* 
* 
 
 
 
* 
戻り値
 
 
 
 
 
 
前提条件
対象となるファイルが開いていることが必要です。
ファイル内にキーが存在していることが必要です。
トランザクションが実行中でないことが必要です。
手順
1 オペレーション コードを 32 に設定します。
2 削除するキーを含むファイルのポジション ブロックを渡します。
3 キー番号パラメーターに削除するキーの番号を格納します。システム定義のログ キー(システム データとも言います)を削除するには、125 を指定します。
詳細
システム定義のログ キーを削除した場合、Create Index(31)オペレーションを使ってそれを再構築することができます。
キーを削除する場合、特に指定しなければ、削除したキーよりもキー番号の大きなキーはすべて、MicroKernel エンジンによって自動的に番号が付け替えられます。MicroKernel エンジンは、削除したキーよりも番号の大きなキーの番号を 1 ずつ減らします。たとえば、キー番号 1、4、および 7 を含むファイルがあるとします。キー 4 を削除すると、MicroKernel エンジンは残ったキーの番号を 1 と 6 に付け替えます。
MicroKernel エンジンによってキー番号を自動的に付け替えられたくない場合は、128 というバイアスをキー番号パラメーターに入れる値に加算します。このバイアスにより、キー番号は飛んだままにしておくことができ、その結果、ファイル内のほかのキー番号に影響を及ぼすことなく、壊れたインデックスを削除し、そのインデックスを作成し直すことができます。インデックスを再構築するには、Create Index(31)を使います。このオペレーションではキー番号を指定できます。
ただし、キーを削除し、それよりキー番号の大きなキーの番号を付け替えなかった場合、その後でユーザーが具体的なキー番号を割り当てずに影響を受けたファイルを複製すると、複製したファイルには元のファイルとは別のキー番号が割り当てられます。
メモ:ユーザーは Btrieve Maintenance ツール、またはそのコマンド ライン バージョンの butil を使ってファイルを複製できます。複製により、既存のファイルと同じ統計情報を持つ新しい空のファイルが作成されます。
結果
Drop Index オペレーションが正常に終了した場合、指定したインデックスは MicroKernel エンジンによって削除され、そのインデックスに割り当てられていたページは、今後の使用のために空き領域のリストに配置されます。また、特に指定しなければ、MicroKernel エンジンでは削除したキーよりもキー番号の大きなキーの番号が付け替えられます。
Drop Index オペレーションが正常に実行されなかった場合は、MicroKernel エンジンから次のステータス コードのいずれかが返されます。
6
キー番号パラメーターが不正です。
41
実行しようとした操作は MicroKernel エンジンでは許可されていません。
MicroKernel エンジンがインデックスを削除中に処理が中断されても、ファイルのほかのキーを使ってファイルのデータにアクセスすることはできます。しかし、不完全なインデックスを使ってファイルにアクセスしようとすると、MicroKernel エンジンからステータス コード 56 が返されます。処理が中断された場合は、Drop Index オペレーションを再発行してください。
ポジショニング
Drop Index オペレーションは、ファイルの物理カレンシー情報にはまったく影響しません。ただし、直前に論理カレンシーを確立するために使用したキーを削除すると、論理カレンシーは消去されます。
End Transaction(20)
End Transaction オペレーション(B_END_TRAN)では、トランザクションを終了し、データ ファイルに適切な変更を加えます。また、トランザクションによって設定されたすべてのファイルとレコードのロックを解除します。
パラメーター
 
 
オペレーション コード
ポジション ブロック
データ バッファー
データ バッファー長
キー バッファー
キー番号
送り値
* 
 
 
 
 
 
戻り値
 
 
 
 
 
 
前提条件
End Transaction オペレーションを発行する前に、Begin Transaction(19 または 1019)が正常に終了している必要があります。
手順
オペレーション コードを 20 に設定します。MicroKernel エンジンでは、オペレーション コード以外の End Transaction 呼び出しパラメーターはすべて無視されますが、将来のリリースとの互換性を確保するために 0 に初期化してください。
結果
End Transaction オペレーションが正常に終了した場合は、トランザクション内で実行されたすべてのオペレーションの結果がファイルに保存されます。End Transaction オペレーションを実行した後でトランザクションを中止することはできません。
End Transaction オペレーションが正常に実行されなかった場合は、MicroKernel エンジンから次のステータス コードが返されます。
38
MicroKernel エンジンで、トランザクション制御ファイル I/O エラーが発生しました。
ポジショニング
End Transaction オペレーションは、ファイルのカレンシー情報にまったく影響しません。
Find Percentage(45)
Find Percentage オペレーション(B_GET_PERCENT)は、スクロール バーを実装するウィンドウ指向のアプリケーションで使用することのできる 2 つの Btrieve API オペレーションのうちの 1 つです。もう 1 つのオペレーションは Get By Percentage(44)です。Find Percentage では、キー パスまたはファイル内でのレコードの物理位置を基準として、それに対応するレコードのおおよその位置を返します。位置はパーセンテージ値で表されます。パーセンテージ値の範囲の定義については、結果を参照してください。
パラメーター
 
 
オペレーション コード
ポジション ブロック
データ バッファー
データ バッファー長
キー バッファー
キー番号
送り値
* 
* 
* 
* 
* 
* 
戻り値
 
* 
* 
* 
 
 
メモ:Find Percentage を使って、キー パスを基準に対応するパーセンテージをシークする場合は、データ バッファー パラメーターに値を入力する必要はありません。ファイル内でのレコードの物理位置を基準に対応するパーセンテージをシークする場合は、キー バッファー パラメーターに値を入力する必要はありません。
前提条件
対象となるファイルが開いていることが必要です。
キー パスに基づいてパーセンテージをシークする場合は、対象となるファイルがデータオンリー ファイルであってはいけません。
ファイル内のレコードの物理位置に基づいてパーセンテージをシークする場合は、そのレコードの物理位置をデータ バッファー パラメーターに指定する必要があります。この位置は、Get Position(22)を使って取得できます。BTRV または BTRVEX タイプのエントリ ポイントの使用と一貫性を持たせてください。
手順
1 オペレーション コードを 45 に設定します。
2 ファイルのポジション ブロックを渡します。
3 ファイル内のレコードの物理位置を基準にパーセンテージをシークする場合は、レコードの 4 バイトまたは 8 バイトの物理アドレスをデータ バッファーに格納します。レコードのキー パスを基準にパーセンテージをシークし、その検索の精度を指定する場合は、精度で指定されているようにデータ バッファー パラメーターを設定します。それ以外の場合は、データ バッファー パラメーターに値を入れる必要はありません。
4 データ バッファー長を最小値である 4 バイトまたは 8 バイトに設定します。この 4 バイトという最小長は、MicroKernel エンジンの内部的な実装に必要とされます。検索の精度を指定する場合は、データ バッファー長を最小値の 12 バイトまたは 16 バイトに設定します。
5 キー パスを基準にパーセンテージをシークする場合は、キー値をキー バッファー パラメーターに設定します。それ以外の場合は、キー バッファー パラメーターに値を入れる必要はありません。
6 キー番号パラメーターを以下のとおりに設定します。
キー パスによってパーセンテージをシークする場合は、キー番号パラメーターを実際のキー番号に設定します。
レコードの物理位置によってパーセンテージをシークする場合は、キー番号パラメーターを -1 に設定します。
詳細
Find Percentage オペレーションは、特にスクロール バーの実装をサポートする目的で用意されています。このオペレーションの精度、つまり、返されたパーセンテージ値がレコードまたはキー値の位置をどれだけ精確に反映しているかどうかは、さまざまな要因によって影響を受けます。このため、スクロール バーの実装以外の目的で使用する場合は、このオペレーションの精度を信頼しないでください。
Find Percentage オペレーションを最適化するため、MicroKernel エンジンでは、ファイルのレコードはデータ ページ間に、キーはインデックス ページ間に均等に分布していることを前提としています。ただし、分布状態は次のような状況によって影響を受けます。
ファイルがインデックス バランスを使用しておらず、同一範囲内のキーで多数のレコードが削除されている。
同一範囲内の物理アドレスで多数のレコードが削除されている。
ファイルに多数の重複するキー値が含まれており、そのキーがリンク重複キーになっている。
精度
精度の設定は任意であり、パーセンテージを測定する要素を選択することができます。PSQL 9 より前のリリースでは、この値は常に 10000 でした。
精度を指定する場合は、以下の手順に従ってください。
Find Percentage オペレーションの精度を指定するには
1 データ バッファーのレコード アドレス領域の後の 4 バイトに識別バイト ExPc(0x45、0x78、0x50、0x63)を設定します。
2 この識別バイトの後の 4 バイトに希望する精度を LoHi Intel 整数で指定します。選択できる精度は、1 から 0xFFFFFFFF までの数値です。
3 使用されるエントリ ポイントに応じて、データ バッファー長が少なくとも 12 バイトまたは 16 バイトであることを確認してください。
次の表は、これらの手順における位置とレイアウトをまとめています。
 
BTRV、BTRVID、BTRCALL、BTRCALLID
BTRVEX、BTRVEXID
レコード アドレス
4 バイト、オフセット 0
8 バイト、オフセット 0
識別の精度
4 バイト、オフセット 4
4 バイト、オフセット 8
一般の精度
4 バイト、オフセット 8
4 バイト、オフセット 12
合計サイズ
4 または 12 バイト
8 または 16 バイト
たとえば、365 件のレコードが入っているファイルから 100 番目のレコードを取得したい場合、パーセンテージに 100、精度に 365 を使用して Find Percentage(45)を実行することができます。
結果
Find Percentage オペレーションが正常に終了した場合は、MicroKernel エンジンによって、指定したキー値またはレコードの相対位置がデータ バッファーに返されます。この位置は、キー パスまたはファイルにおけるオフセットのパーセンテージとして表され、0(0%)から 10000(100.00%)までの範囲の値になります。これは、物理位置でも論理位置でもないので注意してください。
パーセンテージ値は、下位バイト、上位バイトの順の 4 バイト整数として返されます。たとえば、デフォルトの精度を使用する場合は次のようになります。
16 進数の戻り値
10 進数の戻り値
キー パスまたはファイル内でのパーセンテージ
88h 13h
5000
50%
また、オペレーションが正常に終了した場合には、MicroKernel エンジンからデータ バッファー長に少なくとも 4 が返されます。
Find Percentage オペレーションが正常に実行されなかった場合は、MicroKernel エンジンから次のステータス コードのいずれかが返されます。 
3
ファイルが開いていません。
6
キー番号パラメーターが不正です。
7
キー番号が変更されました。
8
現在のポジションが不正です。
9
オペレーションが EOF(end-of-file)を検出しました。
22
データ バッファー パラメーターが短すぎます。
41
実行しようとした操作は MicroKernel エンジンでは許可されていません。
43
指定されたレコード アドレスが不正です。
82
MicroKernel エンジンがポジショニングを失いました。
ポジショニング
Find Percentage オペレーションを実行しても、カレンシー情報は変更されません。
Get By Percentage(44)
Get By Percentage オペレーション(B_SEEK_PERCENT)は、スクロール バーを実装するウィンドウ指向のアプリケーションで使用することのできる 2 つの Btrieve API オペレーションのうちの 1 つです。もう 1 つは Find Percentage(45)です。Get By Percentage オペレーションは、ファイル内のレコードの相対位置によってレコードを取得します。この位置は、オペレーションを呼び出すときに指定したパーセンテージ値に基づきます。また、この位置は特定のキー パスを基準とするのか、ファイル内のレコードの実際の物理位置を表すのかを指定する必要があります。
パラメーター
 
 
オペレーション コード
ポジション ブロック
データ バッファー
データ バッファー長
キー バッファー
キー番号
送り値
* 
* 
* 
* 
 
* 
戻り値
 
* 
* 
* 
* 
 
メモ:ファイル内のレコードの物理位置を基準としてレコードをシークする場合、Get By Percentage オペレーションからキー バッファー パラメーターには何の情報も返されません。
前提条件
対象となるファイルが開いていることが必要です。
キー パスに基づいてレコードをシークする場合は、対象となるファイルがデータオンリー ファイルであってはいけません。
手順
1 オペレーション コードを 44 に設定します。任意でロック バイアスも指定できます。
+100 - 単一レコード ウェイト ロック
+200 - 単一レコード ノーウェイト ロック
+300 - 複数レコード ウェイト ロック
+400 - 複数レコード ノーウェイト ロック
ロックの詳細については、『PSQL Programmer's Guide』を参照してください。
2 ファイルのポジション ブロックを渡します。
3 パーセンテージの値を 4 バイト整数でデータ バッファーに格納します。パーセンテージ値の許容範囲および関連情報については、詳細を参照してください。
4 データ バッファー長を、返される可能性のある最大レコード長以上の値に設定します(MicroKernel エンジンの内部的な実装は、データ バッファー長が最小値の 4 バイトに設定されていることを必要とします)。検索に精度を設定する場合は、データ バッファー長を最小値の 12 バイトに設定します。
5 キー番号パラメーターを設定します。
キー パスによってパーセンテージをシークする場合は、キー番号パラメーターを実際のキー番号に設定します。システム定義のログ キー(システム データ)を使用するには、125 を指定します。
ファイル内のレコードの物理位置によってレコードをシークする場合は、キー番号パラメーターを -1 に設定します。
詳細
精度を指定しない場合(精度を参照)、データ バッファー パラメーターの最初の 2 バイトに対するパーセンテージ値の許容範囲は、0(キー パスまたはファイルの先頭を表します)から 10000(キー パスまたはファイルの末尾を表します)までです。この値は、小数点以下 2 桁を含むものとして、0% から 100.00% の範囲に対応しています。ファイル中の 33.33% あたりにあるレコードを検索する場合は、データ バッファーに値 3333 を渡します。値は、下位バイト、上位バイトの順の整数として格納してください。たとえば、ファイル内の 50% の地点をシークするには、5000(0x1388)という値を使います。0x1388 の下位バイトと上位バイトを入れ替え、0x88 と 0x13 をデータ バッファー パラメーターの先頭の 2 バイトに格納します。
検索の精度を指定する場合は、精度で指定されているようにデータ バッファー パラメーターを設定します。
Get By Percentage オペレーションは、特にスクロール バーの実装をサポートする目的で用意されています。このオペレーションの精度、つまり、返されたレコードがファイル内の指定したパーセンテージ地点に実際に位置しているかどうかは、さまざまな要因によって影響を受けます。このため、スクロール バーの実装以外の目的で使用する場合は、このオペレーションの精度を信頼しないでください。
Get By Percentage オペレーションを最適化するため、MicroKernel エンジンでは、ファイルのレコードはデータ ページ間に、キーはインデックス ページ間に均等に分布していることを前提としています。ただし、分布状態は次のような状況によって影響を受けます。
ファイルがインデックス バランスを使用しておらず、同一範囲内のキーで多数のレコードが削除されている。
同一範囲内の物理アドレスで多数のレコードが削除されている。
ファイルに多数の重複するキー値が含まれており、そのキーがリンク重複キーになっている。
精度
精度の設定は任意であり、パーセンテージを測定する要素を選択することができます。PSQL 9 より前のリリースでは、この値は常に 10000 でした。
精度を指定する場合は、以下の手順に従ってください。
Get By Percentage オペレーションの精度を指定するには
1 データ バッファーのパーセンテージの後の 2 番目の 4 バイトに識別バイト ExPc(0x45、0x78、0x50、0x63)を設定します。
2 この識別バイトの後の 4 バイトに希望する精度を LoHi Intel 整数で指定します。選択できる精度は、1 から 0xFFFFFFFF までの数値です。
3 データ バッファー長が少なくとも 12 バイトあることを確認してください。
たとえば、365 件のレコードが入っているファイルから 100 番目のレコードを取得したい場合、パーセンテージに 100、精度に 365 を使用して Get By Percentage(44)を実行することができます。
結果
Get By Percentage オペレーションが正常に終了した場合は、MicroKernel エンジンによって、指定したキー パスを基準とする位置またはファイル内の物理位置にあるレコードがデータ バッファーに返されます。さらに MicroKernel エンジンからは、データ バッファー長パラメーターにレコード長がバイト単位で返されます。キー パスによってレコードをシークした場合は、MicroKernel エンジンからキー バッファー パラメーターに指定したキー パスのキー値が返されます。物理レコード順によってレコードをシークした場合は、MicroKernel エンジンからキー バッファー パラメーターには何の情報も返されません。
メモ:Get By Percentage オペレーションでキー パスを基準としてレコードをシークした場合、そのキーに重複値が含まれているときは、MicroKernel エンジンでは常に重複値を含む先頭のレコードが返されます。このような実装の細部によって、オペレーションの精度が影響を受ける場合があります。
Get By Percentage オペレーションが正常に実行されなかった場合は、MicroKernel エンジンから次のステータス コードのいずれかが返されます。
3
ファイルが開いていません。
6
キー番号パラメーターが不正です。
7
キー番号が変更されました。
8
現在のポジションが不正です。
9
オペレーションが EOF(end-of-file)を検出しました。
22
データ バッファー パラメーターが短すぎます。
41
実行しようとした操作は MicroKernel エンジンでは許可されていません。
43
指定されたレコード アドレスが不正です。
82
MicroKernel エンジンがポジショニングを失いました。
ポジショニング
指定したキー パスを基準としてレコードをシークするとき、Get By Percentage オペレーションが正常に終了した場合は、指定したキー番号と取得したレコードのそれぞれに基づいて新しい論理カレンシーおよび物理カレンシーが確立されます。
ファイル内のレコードの物理位置を基準としてレコードをシークするとき、Get By Percentage オペレーションが正常に終了した場合は、取得したレコードに基づいて新しい物理カレンシーが確立されます。
Get By Percentage オペレーションが正常に実行されなかった場合、MicroKernel エンジンではカレンシーは変更されません。
Get Direct/Chunk(23)
Get Direct/Chunk オペレーション(B_GET_DIRECT)では、チャンクと呼ばれるレコードの部分を 1 つまたは複数取得できます。このオペレーションは、最大データ バッファー サイズより長いレコードを含むファイルで特に役に立ちます。データ バッファー パラメーターの長さには制限があるため、このようなレコードは長すぎて、ほかの Get および Step オペレーションでは取得できません。アプリケーションでは、物理アドレスを指定することで、チャンクが取得されるレコードを指定します。通常、レコード内でのチャンクの位置は、そのオフセットと長さで指定されます。
パラメーター
 
 
オペレーション コード
ポジション ブロック
データ バッファー
データ バッファー長
キー バッファー
キー番号
送り値
* 
* 
* 
* 
 
* 
戻り値
 
* 
* 
* 
 
 
前提条件
対象となるファイルが開いていることが必要です。
レコードの物理位置を用意する必要があります。この位置は、Get Position(22)を使って取得できます。BTRV または BTRVEX タイプのエントリ ポイントの使用と一貫性を持たせてください。
Get Direct/Chunk オペレーションから返されるすべての値を格納するのに十分な大きさのデータ バッファーを用意する必要があります。また、Get Direct/Chunk オペレーションが間接チャンク オペレーションを実行するとき、データ バッファーにはチャンク ディスクリプター全体(すべてのチャンク定義)を格納できなければなりません。
手順
1 オペレーション コードを 23 に設定します。任意でロック バイアスも指定できます。
+100 - 単一レコード ウェイト ロック
+200 - 単一レコード ノーウェイト ロック
+300 - 複数レコード ウェイト ロック
+400 - 複数レコード ノーウェイト ロック
ロックの詳細については、『PSQL Programmer's Guide』を参照してください。
2 ファイルのポジション ブロックを渡します。
3 詳細の説明に従って、データ バッファーを指定します。
4 データ バッファー長に、入力構造体の長さ(表 23 または表 24)と MicroKernel エンジンに取得するように要求したバイト数の、どちらか大きい方を指定します。
Get Direct/Chunk オペレーションの一部のオプションでは、データ バッファー以外の場所にチャンクを取得します。データ バッファー長を計算する方法については、詳細を参照してください。
5 キー番号パラメーターを -2 に設定します。
詳細
データ バッファーでは、次のチャンク ディスクリプターのいずれかを使用します。
ランダム チャンク ディスクリプター - オペレーションに付き 1 つのチャンクを取得するため、またはチャンクがレコード全体にわたってランダムに配置されているときに、1 回のオペレーションで複数のチャンクを取得するために使用します。
矩形チャンク ディスクリプター - 各チャンクの長さが同じで、チャンクがレコード内に等間隔に配置されているときに、1 回のオペレーションで複数のチャンクを取得するために使用します。
ランダム チャンク
次の例は、ランダムに配置されている 3 つのチャンク([*] がある部分)を含むレコードを示しています。チャンク 0(バイト 0x12 から 0x16)、チャンク 1(バイト 0x2A から 0x31)、およびチャンク 2(バイト 0x41 から 0x4E)です。
00
01
02
03
04
05
06
07
08
09
0A
0B
0C
0D
0E
0F
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
10
11
[*]
[*]
[*]
[*]
[*]
17
18
19
1A
1B
1C
1D
1E
1F
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
20
21
22
23
24
25
26
27
28
29
[*]
[*]
[*]
[*]
[*]
[*]
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
[*]
[*]
32
33
34
35
36
37
38
39
3A
3B
3C
3D
3E
3F
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
40
[*]
[*]
[*]
[*]
[*]
[*]
[*]
[*]
[*]
[*]
[*]
[*]
[*]
[*]
4F
ランダム チャンクを取り出すには、次の表に基づいてデータ バッファー内に構造体を作成する必要があります。
表 23 ランダム チャンク オペレーションのデータ バッファー
要素
長さ(バイト単位)
説明
レコード アドレス
4 または 81
レコードの物理位置。この位置は、Get Position(22)を使って取得できます。
ランダム チャンク ディスクリプター
サブファンクション
4
チャンク ディスクリプターの種類。次のいずれかです。
0x80000000(直接ランダム チャンク ディスクリプター) - チャンクを直接データ バッファーに取得します。1 つ目のチャンクが取得されるとデータ バッファーのオフセット 0 に格納され、2 つ目のチャンクが 1 つ目のチャンクの直後に続き、と以下同様に続きます。
0x80000001(間接ランダム チャンク ディスクリプター) - チャンクをチャンク定義によって指定されるアドレス内に取得します。
チャンク数
4
取得するチャンク数。この値は少なくとも 1 以上であることが必要です。明確な最大値はありませんが、チャンク ディスクリプターはデータ バッファーに収まらなければなりません。
チャンク定義
(各チャンクについて繰り返す)
12(32 ビット アプリケーション用)
16(64 ビット アプリケーション用)
各チャンク定義は、以下に示すように、4 バイトのチャンク オフセット、それに続く 4 バイトのチャンク長、さらに 32 ビット アプリケーションの場合は 4 バイトのユーザー データ、または 64 ビット アプリケーションの場合は 8 バイトのユーザー データから構成されます。
チャンク オフセット - チャンクの開始地点を、レコードの先頭からのオフセット(バイト単位)で示します。最小値は 0、最大値はレコードの末尾のバイトのオフセットです。
チャンク長 - チャンク内のバイト数を示します。最小値は 0、最大値は 655352 です。
ユーザー データ - (間接ディスクリプターでのみ使用します。)32 ビット アプリケーションの場合、実際のチャンク データへの 32 ビット ポインターです。64 ビット アプリケーションの場合、実際のチャンク データへの 64 ビット ポインターです。直接チャンク ディスクリプターのサブファンクションの場合、MicroKernel エンジンではこの要素は無視されます。
1 サイズは、使用するエントリ ポイントが BTRV タイプか BTRVEX タイプかによって決まります。
2 BTRVEX の場合、チャンク サイズは 65535 に制限されていますが、1 個の大きなデータ バッファーに複数のチャンクを返すことができます。
次の表は、BTRV エントリ ポイントを使って直接ランダム チャンクを取り出す場合の、32 ビット アプリケーション用データ バッファーの例を示しています。
要素
サンプル値
長さ(バイト単位)
レコード アドレス
0x00000628
4
サブファンクション
0x80000000
4
チャンク数
3
4
チャンク 0
チャンク オフセット
18
4
チャンク長
5
4
ユーザー データ
適用外
4
チャンク 1
チャンク オフセット
42
4
チャンク長
8
4
ユーザー データ
適用外
4
チャンク 2
チャンク オフセット
65
4
チャンク長
14
4
ユーザー データ
適用外
4
矩形チャンク ディスクリプター構造体
同じ長さのチャンクがレコード全体にわたって等間隔に配置されている場合は、矩形チャンク ディスクリプターを使って、取得するすべてのチャンクを記述することができます。たとえば、次のような図を考えてみましょう。この図は、レコード内のオフセット 0x00 から 0x4F までを表しています。
00
01
02
03
04
05
06
07
08
09
0A
0B
0C
0D
0E
0F
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
10
11
12
13
14
15
16
17
18
[*]
[*]
[*]
[*]
1D
1E
1F
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
20
21
22
23
24
25
26
27
28
[*]
[*]
[*]
[*]
2D
2E
2F
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
30
31
32
33
34
35
36
37
38
[*]
[*]
[*]
[*]
3D
3E
3F
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
40
41
42
43
44
45
46
47
48
49
4A
4B
4C
4D
4E
4F
このレコードには 3 つのチャンク([*] がある部分)が含まれています。チャンク 0(バイト 0x19 から 0x1C)、チャンク 1(バイト 0x29 から 0x2C)、およびチャンク 2(バイト 0x39 から 0x3C)です。各チャンクはどれも 4 バイトの長さで、チャンク同士は、各チャンクの先頭から計算すると、いずれも合計 16(0x10)バイトずつ離れています。
1 つの矩形ディスクリプターを使って、3 つのチャンクをすべて取得できます。矩形チャンクを取り出すには、次の表に基づいてデータ バッファー内に構造体を作成する必要があります。
表 24 矩形チャンクのデータ バッファー
要素
長さ(バイト単位)
説明
レコード アドレス
4 または 81
レコードの 4 バイト物理アドレス。この位置は、Get Position(22)を使って取得できます。
矩形チャンク ディスクリプター
サブファンクション
4
チャンク ディスクリプターの種類。次のいずれかです。
0x80000002(直接矩形チャンク ディスクリプター) - チャンクを直接データ バッファーに取得します。1 つ目のチャンクが取得されるとデータ バッファーのオフセット 0 に格納され、2 つ目のチャンクが 1 つ目のチャンクの直後に続き、と以下同様に続きます。
0x80000003(間接矩形チャンク ディスクリプター) - チャンクをユーザー データ要素およびアプリケーションの行間隔要素によって指定されるアドレス内に取得します。
行数
4
矩形チャンク ディスクリプターの操作対象とするチャンク数。この値の最小値は 1 です。明確な最大値はありません。
位置(オフセット)
4
取得する最初のバイトの、レコードの先頭からのオフセット。最小値は 0、最大値はレコードの末尾のバイトのオフセットです。レコードが 1 つの矩形として表される場合、この要素は、取得される先頭行にある先頭バイトのオフセットを指します。
行のバイト数
4
各チャンクで取得するバイト数。最小値は 0、最大値は 655352 です。
行間隔
4
チャンクの先頭から次のチャンクの先頭までのバイト数。
ユーザー データ
4(32 ビット アプリケーション用)
8(64 ビット アプリケーション用)
(間接ディスクリプターでのみ使用します。)32 ビット アプリケーションの場合、MicroKernel エンジンが各行からバイトを取得した後でそれらを格納する場所への 32 ビット ポインター。64 ビット アプリケーションの場合、MicroKernel エンジンが各行からバイトを取得した後でそれらを格納する場所への 64 ビット ポインター。
直接矩形ディスクリプターの場合、MicroKernel エンジンではこの要素は無視されます。ただしそれでも、この要素を割り当て、0 に初期化しておく必要があります。
アプリケーションの行間隔
4
(間接矩形ディスクリプターでのみ使用します。)矩形がアプリケーションのメモリ(つまり、ユーザー データで指定したアドレス)に格納されるときの、矩形内のチャンクの先頭から次のチャンクの先頭までのバイト数。直接矩形ディスクリプターの場合、MicroKernel エンジンではこの要素は無視されます。ただしそれでも、この要素を割り当て、0 に初期化しておく必要があります。
1 サイズは、使用するエントリ ポイントが BTRV タイプか BTRVEX タイプかによって決まります。
2 BTRVEX の場合、チャンク サイズは 65535 に制限されていますが、1 個の大きなデータ バッファーに複数のチャンクを返すことができます。
間接矩形ディスクリプターを使用するときは、取得されたチャンクがチャンク ディスクリプターを上書きしないように、ユーザー データ ポインターが初期化されていることを確認してください。MicroKernel エンジンは、返されたチャンクをユーザー データ要素が示す場所にコピーするとき、ディスクリプターを使用します。チャンク ディスクリプターを上書きしてしまった場合は、MicroKernel エンジンからステータス コード 62 が返されます。
矩形がメモリ内にあるとき、各行の間隔がレコードとして格納されているときと同じバイト数になる場合は、アプリケーションの行間隔を行間隔と同じ値に設定します。しかし、矩形がアプリケーションのメモリ内で再配置され、行の間隔が何バイトか増減する場合は、アプリケーションの行間隔により、その情報を MicroKernel エンジンに渡すことができます。
間接矩形ディスクリプターを使用するときは、MicroKernel エンジンはユーザー データ要素およびアプリケーションの行間隔要素を使って、取得後のデータの格納場所を決定します。MicroKernel エンジンは 1 行目のデータを、ユーザー データのオフセット 0 に格納します。MicroKernel エンジンは 2 行目のデータを、ユーザー データ + アプリケーションの行間隔で指定されるアドレスに格納します。MicroKernel エンジンは 3 行目のデータを、ユーザー データ + (アプリケーションの行間隔 * 2) で指定されるアドレスに格納します。以下同様です。
次の表は、BTRV エントリ ポイントを使って直接矩形チャンクを取り出す場合の、32 ビット アプリケーション用データ バッファーの例を示しています。
要素名
サンプル値
長さ(バイト単位)
レコード アドレス
0x00000628
4
サブファンクション
0x80000002
4
行数
3
4
位置(オフセット)
25
4
行のバイト数
4
4
行間隔
16
4
ユーザー データ
0
4
アプリケーションの行間隔
0
4
ネクストインレコード サブファンクション バイアス
これまでに述べたサブファンクションの値にバイアス 0x40000000 を加算すると、MicroKernel エンジンではレコード内の物理カレンシー(つまり、レコード内の現在の物理位置)に基づいてサブファンクションのオフセット要素の値が算出されます。ネクストインレコード サブファンクションを使用する場合、MicroKernel エンジンではチャンク ディスクリプターのオフセット要素は無視されます。
結果
Get Direct/Chunk オペレーションが正常に終了した場合、直接チャンク ディスクリプターを使用しているときは、MicroKernel エンジンではデータ バッファーにチャンクが順に返されます。間接ランダム チャンク ディスクリプターを使用しているとき、MicroKernel エンジンでは各チャンクのユーザー データ要素で指定した場所にデータが返されます。また、間接矩形ディスクリプターを使用しているとき、MicroKernel エンジンではユーザー データ要素およびアプリケーションの行間隔要素から計算される場所にデータが返されます。
さらに MicroKernel エンジンから、データ バッファー長パラメーターには、取得されたチャンクの長さの総計が格納されます(この戻り値は、チャンクが取得されて直接データ バッファーに格納されたか、間接ディスクリプターによってチャンクが取得され別の場所に格納されたかどうかに関係なく、取得された全バイト数を反映しています)。オペレーションが部分的にしか正常に実行されなかった場合、アプリケーションではデータ バッファー長パラメーターに返された値を使って、どのチャンクが取得されなかったか、また最後のチャンクの何バイトまでが取得されたかを調べることができます。
いずれかのチャンクで、開始位置がレコードの末尾を超えてしまう場合(結果として、MicroKernel エンジンからステータス コード 103 が返されます)、またはチャンクのオフセットと長さの合計がレコード長を超えてしまう場合には、Get Direct/Chunk オペレーションの一部だけが正常に実行されます。後者の場合は MicroKernel エンジンからステータス コード 0 が返されますが、このオペレーションに後続のチャンクがある場合、その処理は中止されます。
メモ:すべてのチャンクが適切に取得されたかどうかを知らせるものは、データ バッファー長パラメーターだけです。このため、Get Direct/Chunk オペレーションの実行後は、必ずデータ バッファー長パラメーターに返された値をチェックしてください。
次のステータス コードは、Get Direct/Chunk オペレーションの一部だけが実行されたことを示します。MicroKernel エンジンからこれらのステータス コードのいずれかが返された場合は、アプリケーションでデータ バッファー長パラメーターの戻り値を調べて、MicroKernel エンジンから実際に返されたデータ量を確認する必要があります。
22
データ バッファー パラメーターが短すぎます。
54
レコードの可変長部分が破損しています。
103
チャンク オフセットが大きすぎます。
MicroKernel エンジンから次のステータス コードが返される場合、データはまったく取得されません。
43
指定されたレコード アドレスが不正です。
58
圧縮バッファー長が短すぎます。
62
ディスクリプターが不正です。
97
データ バッファーが小さすぎます。
106
MicroKernel エンジンは、Get Next Chunk オペレーションを実行できません。
ポジショニング
Get Direct/Chunk オペレーションは、論理カレンシーにまったく影響しません。物理カレンシーについては、チャンクが取り出されたレコードが現在の物理レコードになります。
Get Direct/Record(23)
Get Direct/Record オペレーション(B_GET_DIRECT)では、定義されているキー パスではなく、ファイル内の物理位置を使ってレコードを取得します。
以下のような操作を実行する場合は、Get Direct/Record オペレーションを使用してください。
キー値の代わりに物理位置を使って、より高速にレコードを取得する。
Get Position(22)を使ってレコードの物理位置を取得し、その位置を保存する。それから、カレンシーに影響を与えるほかのオペレーションを実行した後で Get Direct/Record を使って、その位置に直接戻る。
一連の重複レコードの中から 1 つのレコードを取得するとき、その一連のレコードを先頭からすべて読み取りし直すことなく、物理位置を使って取得する。
現在のキー パスを変更する。Get Position オペレーションに続けて、別のキー番号を使った Get Direct/Record オペレーションを実行すると、別のインデックス パスに現在のレコードのポジショニングが確立します。この後で Get Next オペレーションを実行すると、新しいキー パスに基づいてファイル内の次のレコードが返されます。
パラメーター
 
 
オペレーション コード
ポジション ブロック
データ バッファー
データ バッファー長
キー バッファー
キー番号
送り値
* 
* 
* 
* 
 
* 
戻り値
 
* 
* 
* 
* 
 
メモ:データオンリー ファイルで Get Direct/Record オペレーションを実行する場合は、キー番号パラメーターは必要ありません。
前提条件
対象となるファイルが開いていることが必要です。
4 バイトまたは 8 バイトから成るレコードの物理位置を用意する必要があります。この値は、Get Position(22)を使って取得できます。このオペレーションを実行すると、現在のレコードの物理アドレスが返されます。BTRV または BTRVEX タイプのエントリ ポイントの使用と一貫性を持たせてください。
手順
1 オペレーション コードを 23 に設定します。任意でロック バイアスも指定できます。
+100 - 単一レコード ウェイト ロック
+200 - 単一レコード ノーウェイト ロック
+300 - 複数レコード ウェイト ロック
+400 - 複数レコード ノーウェイト ロック
ロックの詳細については、『PSQL Programmer's Guide』を参照してください。
2 ファイルのポジション ブロックを渡します。
3 データ バッファーの先頭に、目的のレコードの位置を表す 4 バイト値または 8 バイト値を格納します。サイズは、使用しているエントリ ポイントが BTRV タイプか BTRVEX タイプかによって決まります。
4 データ バッファー長を、取得するレコードの長さ以上の値に設定します。
5 キー番号を、MicroKernel エンジンで論理カレンシーを確立するパスのキー番号に設定します。MicroKernel エンジンで論理カレンシーの確立を必要としない場合は、-1 を指定します。システム定義のログ キー(システム データ)を使用するには、125 を指定します。
結果
Get Direct/Record オペレーションが正常に終了した場合、MicroKernel エンジンでは要求したレコードがデータ バッファーに、レコード長がデータ バッファー長に、指定したキー パスのキー値がキー バッファーにそれぞれ返されます。
Get Direct/Record オペレーションが正常に実行されず、要求したレコードを MicroKernel エンジンが取得できなかった場合は、MicroKernel エンジンから次のステータス コードのいずれかが返されます。
22
データ バッファー パラメーターが短すぎます。(論理カレンシーはまだ確立されています)
43
指定されたレコード アドレスが不正です。(論理カレンシーは確立されていません)
44
指定されたキー パスが不正です。(論理カレンシーは確立されていません)
82
MicroKernel エンジンがポジショニングを失いました。(論理カレンシーは確立されていません)
ポジショニング
Get Direct/Record オペレーションを実行すると、既存の論理カレンシー情報が消去され、指定したキー番号に従って新しい論理カレンシーが確立されます。物理カレンシー情報にはまったく影響しません。
Get Directory(18)
Get Directory オペレーション(B_GET_DIR)では、指定された論理ディスク ドライブの現在のディレクトリを返します。
パラメーター
 
 
オペレーション コード
ポジション ブロック
データ バッファー
データ バッファー長
キー バッファー
キー番号
送り値
* 
 
 
 
 
* 
戻り値
 
 
 
 
* 
 
前提条件
Get Directory オペレーションはいつでも発行することができます。キー バッファーには少なくとも 65 文字の長さが必要です。
手順
1 オペレーション コードを 18 に設定します。
2 キー番号パラメーターに論理ディスク ドライブ番号を格納します。ドライブは、A の場合は 1、B の場合は 2、というように指定します。デフォルトのドライブを使用するには 0 を指定します。
結果
MicroKernel エンジンでは、オペレーションが正常に終了した場合、バイナリ 0 で終端する現在のディレクトリがキー バッファーに返されます。
ポジショニング
Get Directory オペレーションは、ファイルのカレンシー情報にはまったく影響しません。
Get Equal(5)
Get Equal オペレーション(B_GET_EQUAL)では、キー バッファーに指定されたキー値と等しいキー値を持つレコードを取得します。キーの重複が可能な場合は、同じキー値を持つグループの中で先頭のレコード(作成順)が取得されます。Get Key(+50)バイアスを使うと、ファイル内に値が存在するかどうかを検出することもできます。一般に、Get Key オペレーションの方が高速に処理されます。
パラメーター
 
 
オペレーション コード
ポジション ブロック
データ バッファー
データ バッファー長
キー バッファー
キー番号
送り値
* 
* 
 
* 
* 
* 
戻り値
 
* 
* 
* 
 
 
前提条件
対象となるファイルが開いていることが必要です。
ファイルがデータオンリー ファイルであってはいけません。
手順
1 オペレーション コードを 5 に設定します。任意でロック バイアスも指定できます。
+100 - 単一レコード ウェイト ロック
+200 - 単一レコード ノーウェイト ロック
+300 - 複数レコード ウェイト ロック
+400 - 複数レコード ノーウェイト ロック
ロックの詳細については、『PSQL Programmer's Guide』を参照してください。
2 ファイルのポジション ブロックを渡します。
3 データ バッファー長を、取得するレコードの長さ以上の値に設定します。
4 キー バッファーに目的のキー値を指定します。キーが複数のセグメントから成る場合は、必ずすべてのセグメントを記述し、それらすべてに値を設定するようキー バッファーを定義してください。すべてのセグメントについて検索条件を設定しない場合は、代わりに Get Greater Than Or Equal オペレーションを使用してください。
5 キー番号を正しいキー パスに設定します。システム定義のログ キー(システム データ)を使用するには、125 を指定します。
結果
Get Equal オペレーションが正常に終了した場合は、MicroKernel エンジンでは要求したレコードがデータ バッファーに、そのレコードの長さがデータ バッファー長に返されます。
Get Equal オペレーションが正常に実行されなかった場合は、MicroKernel エンジンから次のステータス コードのいずれかが返されます。
3
ファイルが開いていません。
4
アプリケーションがキー値を見つけられません。
6
キー番号パラメーターが不正です。
22
データ バッファー パラメーターが短すぎます。
このオペレーションは、キーのヌル インジケーター セグメントにゼロ以外の値が含まれている場合にはステータス コード 4 を返します。Get Equal を使ってヌルのレコードは検索できません。これは、ヌルの定義はあいまいなものであり、どの値とも等しくならないからです。ヌル値の検索が必要な場合は、Get First オペレーションに続けて Get Next オペレーションを使用します。
ポジショニング
Get Equal オペレーションを実行すると、完全な論理カレンシーおよび物理カレンシーが確立し、取得したレコードが現在のレコードになります。
Get First(12)
Get First オペレーション(B_GET_FIRST)では、指定されたキーに基づいて先頭の論理レコードを取得します。Get Key(+50)バイアスを使うと、ファイル内に値が存在するかどうかを検出することもできます。一般に、Get Key オペレーションの方が高速に処理されます。
パラメーター
 
 
オペレーション コード
ポジション ブロック
データ バッファー
データ バッファー長
キー バッファー
キー番号
送り値
* 
* 
 
* 
 
* 
戻り値
 
* 
* 
* 
* 
 
前提条件
対象となるファイルが開いていることが必要です。
ファイルがデータオンリー ファイルであってはいけません。
手順
1 オペレーション コードを 12 に設定します。任意でロック バイアスも指定できます。
+100 - 単一レコード ウェイト ロック
+200 - 単一レコード ノーウェイト ロック
+300 - 複数レコード ウェイト ロック
+400 - 複数レコード ノーウェイト ロック
ロックの詳細については、『PSQL Programmer's Guide』を参照してください。
2 ファイルのポジション ブロックを渡します。
3 データ バッファー長を、取得するレコードの長さ以上の値に設定します。
4 キー番号をキー パスに設定します。システム定義のログ キー(システム データ)を使用するには、125 を指定します。
結果
Get First オペレーションが正常に終了した場合は、MicroKernel エンジンでは要求したレコードがデータ バッファーに返され、対応するキー値がキー バッファーに格納され、さらにそのレコードの長さがデータ バッファー長に返されます。
Get First オペレーションが正常に実行されなかった場合は、MicroKernel エンジンから次のステータス コードのいずれかが返されます。
3
ファイルが開いていません。
6
キー番号パラメーターが不正です。
9
オペレーションが EOF(end-of-file)を検出しました。
22
データ バッファー パラメーターが短すぎます。
ポジショニング
Get First オペレーションを実行すると、完全な論理カレンシーおよび物理カレンシーが確立し、取得したレコードが現在のレコードになります。論理位置の直前は、ファイルの先頭よりも前を指すことになります。
Get Greater Than(8)
Get Greater Than オペレーション(B_GET_GT)では、キー番号で指定されたフィールドが、キー バッファーの値よりも次に大きな値を含むレコードを取得します。キーの重複が可能な場合は、同じキー値を持つグループの中で先頭のレコード(作成順)が取得されます。Get Key(+50)バイアスを使うと、ファイル内に値が存在するかどうかを検出することもできます。一般に、Get Key オペレーションの方が高速に処理されます。
メモ:降順キーで Get Greater Than オペレーションを実行する場合、「次に大きな値」というのは、実際にはキー バッファーで指定された値よりも小さな値を指すことになります。
パラメーター
 
 
オペレーション コード
ポジション ブロック
データ バッファー
データ バッファー長
キー バッファー
キー番号
送り値
* 
* 
 
* 
* 
* 
戻り値
 
* 
* 
* 
* 
 
前提条件
対象となるファイルが開いていることが必要です。
ファイルがデータオンリー ファイルであってはいけません。
手順
1 オペレーション コードを 8 に設定します。任意でロック バイアスも指定できます。
+100 - 単一レコード ウェイト ロック
+200 - 単一レコード ノーウェイト ロック
+300 - 複数レコード ウェイト ロック
+400 - 複数レコード ノーウェイト ロック
ロックの詳細については、『PSQL Programmer's Guide』を参照してください。
2 ファイルのポジション ブロックを渡します。
3 データ バッファー長を、取得するレコードの長さ以上の値に設定します。
4 キー バッファー パラメーターに目的のキー値を指定します。
5 キー番号パラメーターを正しいキー パスに設定します。システム定義のログ キー(システム データ)を使用するには、125 を指定します。
結果
Get Greater Than オペレーションが正常に終了した場合、MicroKernel エンジンでは要求したレコードがデータ バッファーに、キー値がキー バッファーに、さらにそのレコードの長さがデータ バッファー長に格納されます。
Get Greater Than オペレーションが正常に実行されなかった場合は、MicroKernel エンジンから次のステータス コードのいずれかが返されます。
3
ファイルが開いていません。
6
キー番号パラメーターが不正です。
22
データ バッファー パラメーターが短すぎます。
ポジショニング
Get Greater Than オペレーションを実行すると、完全な論理カレンシーおよび物理カレンシーが確立し、取得したレコードが現在のレコードになります。
Get Greater Than or Equal(9)
Get Greater Than or Equal オペレーション(B_GET_GE)では、キー番号で指定されたキーが、キー バッファーに指定された値と等しいかそれよりも大きな値を持つレコードを取得します。MicroKernel エンジンではまず、等しいという条件を満たすレコードが検索されます。キーの重複が可能な場合は、同じキー値を持つグループの中で先頭のレコード(作成順)が取得されます。Get Key(+50)バイアスを使うと、ファイル内に値が存在するかどうかを検出することもできます。一般に、Get Key オペレーションの方が高速に処理されます。
メモ:降順キーで Get Greater Than or Equal オペレーションを実行する場合、「次に大きな値」というのは、実際にはキー バッファーで指定された値よりも小さな値を指すことになります。
パラメーター
 
 
オペレーション コード
ポジション ブロック
データ バッファー
データ バッファー長
キー バッファー
キー番号
送り値
* 
* 
 
* 
* 
* 
戻り値
 
* 
* 
* 
* 
 
前提条件
対象となるファイルが開いていることが必要です。
ファイルがデータオンリー ファイルであってはいけません。
手順
1 オペレーション コードを 9 に設定します。任意でロック バイアスも指定できます。
+100 - 単一レコード ウェイト ロック
+200 - 単一レコード ノーウェイト ロック
+300 - 複数レコード ウェイト ロック
+400 - 複数レコード ノーウェイト ロック
ロックの詳細については、『PSQL Programmer's Guide』を参照してください。
2 ファイルのポジション ブロックを渡します。
3 データ バッファー長を、取得するレコードの長さ以上の値に設定します。
4 キー バッファー パラメーターにキー値を指定します。
5 キー番号パラメーターを正しいキー パスに設定します。システム定義のログ キー(システム データ)を使用するには、125 を指定します。
結果
Get Greater Than or Equal オペレーションが正常に終了した場合、MicroKernel エンジンでは要求したレコードがデータ バッファーに、キー値がキー バッファーに、さらにそのレコードの長さがデータ バッファー長に格納されます。
Get Greater Than or Equal オペレーションが正常に実行されなかった場合は、MicroKernel エンジンから次のステータス コードのいずれかが返されます。
3
ファイルが開いていません。
6
キー番号パラメーターが不正です。
22
データ バッファー パラメーターが短すぎます。
ポジショニング
Get Greater Than or Equal オペレーションを実行すると、完全な論理カレンシーおよび物理カレンシーが確立し、取得したレコードが現在のレコードになります。
Get Key(+50)
Get Key バイアスを使用すると、実際にデータ レコードを取得することなく Get オペレーションを実行できます。Get Key を使って、ファイル内にある値が存在するかどうかを検出できます。一般に、Get Key オペレーションは対応する Get オペレーションよりも高速に実行できます。Get Key オペレーションは、以下のいずれかの Get オペレーションと共に使用します。
Get Equal(5)
Get Next(6)
Get Previous(7)
Get Greater Than(8)
Get Greater Than or Equal(9)
Get Less Than(10)
Get Less Than or Equal(11)
Get First(12)
Get Last(13)
Get By Percentage(44)
パラメーター
パラメーターは対応する Get オペレーションと同様です。ただし、MicroKernel エンジンではデータ バッファー長の設定は無視され、データ バッファーにはレコードが返されません。
前提条件
Get Key オペレーションの前提条件は、対応する Get オペレーションの前提条件と同じです。
手順
1 対応する Get オペレーションの場合と同じようにパラメーターを設定します。データ バッファー長を初期化する必要はありません。
2 オペレーション コードを、実行する Get オペレーションのオペレーション コードに 50 を加算した値に設定します。たとえば、Get Equal(5)と共に Get Key(+50)を実行するには、オペレーション コードを 55 に設定します。
MicroKernel エンジンでは、Get Key(+50)の後に Delete または Update オペレーションを実行することはできません。MicroKernel エンジンで、Delete または Update オペレーションを実行する前に、変更しようとしているデータ ページの現在の使用回数と、レコードを読み取った時点のデータ ページの使用回数が比較されます。使用回数を取得するには、MicroKernel エンジンがデータ ページを読み取る必要があります。
Get Key オペレーションではデータ ページを読み取らないので、Delete または Update オペレーションで比較するための使用回数が利用可能になりません。MicroKernel エンジンでは、比較なしにパッシブ並行制御の矛盾チェックを実行できないため、Update または Delete オペレーションは正常に実行されません。Update または Delete オペレーションが正常に実行されないと、MicroKernel エンジンからステータス コード 8 が返されます。
結果
MicroKernel エンジンで要求したキーが検出されると、そのキー値がキー バッファーに格納され、ステータス コード 0 が返されます。そうでない場合は、MicroKernel エンジンからキー値を検出できなかった理由を示すステータス コードが返されます。
ポジショニング
Get Key オペレーションを実行すると、対応する Get オペレーションと同様の方法で現在のポジショニングが確立されます。ただし、Get Key オペレーションの対象となるキーが重複を許可している場合、MicroKernel エンジンでは取得された現在のキー値の重複インスタンスは無視されます。Get Key オペレーションの実行後、論理位置の直前は次に小さなキー値を含むレコードを指します。また、論理位置の直後は次に大きなキー値を含むレコードを指します。
たとえば、Smith が 8 回と Smythe が 1 回出現する姓のキーを対象に、Get Key を Get Equalオペレーション(55)と共に実行したとします。論理位置の直後は次の Smith ではなく、Smythe を指すことになります。
Get Key オペレーションではどれか 1 つのレコードが識別されるわけではないため、MicroKernel エンジンでは Get Key オペレーションに続けて Update または Delete オペレーションを実行することはできません。
Get Last(13)
Get Last オペレーション(B_GET_LAST)では、指定されたキーに基づいて末尾の論理レコードを取得します。末尾のキー値が重複している場合は、同じキー値を持つグループの中で末尾のレコードが返されます。Get Key(+50)バイアスを使うと、ファイル内に値が存在するかどうかを検出することもできます。一般に、Get Key オペレーションの方が高速に処理されます。
パラメーター
 
 
オペレーション コード
ポジション ブロック
データ バッファー
データ バッファー長
キー バッファー
キー番号
送り値
* 
* 
 
* 
 
* 
戻り値
 
* 
* 
* 
* 
 
前提条件
対象となるファイルが開いていることが必要です。
ファイルがデータオンリー ファイルであってはいけません。
手順
1 オペレーション コードを 13 に設定します。任意でロック バイアスも指定できます。
+100 - 単一レコード ウェイト ロック
+200 - 単一レコード ノーウェイト ロック
+300 - 複数レコード ウェイト ロック
+400 - 複数レコード ノーウェイト ロック
ロックの詳細については、『PSQL Programmer's Guide』を参照してください。
2 ファイルのポジション ブロックを渡します。
3 データ バッファー長を、取得するレコードの長さ以上の値に設定します。
4 キー番号をキー パスを設定します。システム定義のログ キー(システム データ)を使用するには、125 を指定します。
結果
Get Last オペレーションが正常に終了した場合は、MicroKernel エンジンでは要求したレコードがデータ バッファーに返され、対応するキー値がキー バッファーに格納され、さらにそのレコードの長さがデータ バッファー長に返されます。
Get Last オペレーションが正常に実行されなかった場合は、MicroKernel エンジンから次のステータス コードのいずれかが返されます。
3
ファイルが開いていません。
6
キー番号パラメーターが不正です。
9
オペレーションが EOF(end-of-file)を検出しました。
22
データ バッファー パラメーターが短すぎます。
ポジショニング
Get Last オペレーションを実行すると、完全な論理カレンシーおよび物理カレンシーが確立し、取得したレコードが現在のレコードになります。論理位置の直後は、ファイルの末尾よりも後を指すことになります。
Get Less Than(10)
Get Less Than オペレーション(B_GET_LT)では、キー番号で指定されたキーが、キー バッファーに指定された値よりも次に小さな値を持つレコードを取得します。キーの重複が可能な場合は、同じキー値を持つグループの中で末尾のレコード(作成順)が取得されます。Get Key(+50)バイアスを使うと、ファイル内に値が存在するかどうかを検出することもできます。一般に、Get Key オペレーションの方が高速に処理されます。
メモ:降順キーで Get Less Than オペレーションを実行する場合、「次に小さな値」というのは、実際にはキー バッファーで指定された値よりも大きな値を指すことになります。
パラメーター
 
 
オペレーション コード
ポジション ブロック
データ バッファー
データ バッファー長
キー バッファー
キー番号
送り値
* 
* 
 
* 
* 
* 
戻り値
 
* 
* 
* 
* 
 
前提条件
対象となるファイルが開いていることが必要です。
ファイルがデータオンリー ファイルであってはいけません。
手順
1 オペレーション コードを 10 に設定します。任意でロック バイアスも指定できます。
+100 - 単一レコード ウェイト ロック
+200 - 単一レコード ノーウェイト ロック
+300 - 複数レコード ウェイト ロック
+400 - 複数レコード ノーウェイト ロック
ロックの詳細については、『PSQL Programmer's Guide』を参照してください。
2 ファイルのポジション ブロックを渡します。
3 データ バッファー長を、取得するレコードの長さ以上の値に設定します。
4 キー バッファー パラメーターに目的のキー値を指定します。
5 キー番号パラメーターをキー パスに設定します。システム定義のログ キー(システム データ)を使用するには、125 を指定します。
結果
Get Less Than オペレーションが正常に終了した場合、MicroKernel エンジンではレコードがデータ バッファーに、そのレコードのキー値がキー バッファーに、さらにそのレコードの長さがデータ バッファー長に返されます。
Get Less Than オペレーションが正常に実行されなかった場合は、MicroKernel エンジンから次のステータス コードのいずれかが返されます。
3
ファイルが開いていません。
6
キー番号パラメーターが不正です。
22
データ バッファー パラメーターが短すぎます。
ポジショニング
Get Less Than オペレーションを実行すると、完全な論理カレンシーおよび物理カレンシーが確立し、取得したレコードが現在のレコードになります。
Get Less Than or Equal(11)
Get Less Than or Equal オペレーション(B_GET_LE)では、キー番号で指定されたキーが、キー バッファーに指定された値と等しいかそれよりも小さな値を持つレコードを取得します。MicroKernel エンジンではまず、等しいという条件を満たすレコードが検索されます。キーの重複が可能な場合は、同じキー値を持つグループの中で末尾のレコード(作成順)が取得されます。Get Key(+50)バイアスを使うと、ファイル内に値が存在するかどうかを検出することもできます。一般に、Get Key オペレーションの方が高速に処理されます。
メモ:降順キーで Get Less Than or Equal オペレーションを実行する場合、「次に小さな値」というのは、実際にはキー バッファーで指定された値よりも大きな値を指すことになります。
パラメーター
 
 
オペレーション コード
ポジション ブロック
データ バッファー
データ バッファー長
キー バッファー
キー番号
送り値
* 
* 
 
* 
* 
* 
戻り値
 
* 
* 
* 
* 
 
前提条件
対象となるファイルが開いていることが必要です。
ファイルがデータオンリー ファイルであってはいけません。
手順
1 オペレーション コードを 11 に設定します。任意でロック バイアスも指定できます。
+100 - 単一レコード ウェイト ロック
+200 - 単一レコード ノーウェイト ロック
+300 - 複数レコード ウェイト ロック
+400 - 複数レコード ノーウェイト ロック
ロックの詳細については、『PSQL Programmer's Guide』を参照してください。
2 ファイルのポジション ブロックを渡します。
3 データ バッファー長を、取得するレコードの長さ以上の値に設定します。
4 キー バッファー パラメーターにキー値を指定します。
5 キー番号パラメーターをキー パスに設定します。システム定義のログ キー(システム データ)を使用するには、125 を指定します。
結果
Get Less Than or Equal オペレーションが正常に終了した場合、MicroKernel エンジンではレコードがデータ バッファーに、そのレコードのキー値がキー バッファーに、さらにそのレコードの長さがデータ バッファー長に返されます。
Get Less Than or Equal オペレーションが正常に実行されなかった場合は、MicroKernel エンジンから次のステータス コードのいずれかが返されます。
3
ファイルが開いていません。
6
キー番号パラメーターが不正です。
22
データ バッファー パラメーターが短すぎます。
ポジショニング
Get Less Than or Equal オペレーションを実行すると、完全な論理カレンシーおよび物理カレンシーが確立し、取得したレコードが現在のレコードになります。
Get Next(6)
Get Next オペレーション(B_GET_NEXT)では、指定されたキーに基づいて、論理位置で次にあるレコードを取得します。Get Next オペレーションを使うと、重複するキー値を持つレコードのグループの中でレコードを検索できます。Get Key(+50)バイアスを使うと、ファイル内に値が存在するかどうかを検出することもできます。一般に、Get Key オペレーションの方が高速に処理されます。
パラメーター
 
 
オペレーション コード
ポジション ブロック
データ バッファー
データ バッファー長
キー バッファー
キー番号
送り値
* 
* 
 
* 
* 
* 
戻り値
 
* 
* 
* 
* 
 
前提条件
対象となるファイルが開いていることが必要です。
ファイルがデータオンリー ファイルであってはいけません。
アプリケーションでは、指定したキーに基づく次の論理位置を確立しておくことが必要です。
手順
1 オペレーション コードを 6 に設定します。任意でロック バイアスも指定できます。
+100 - 単一レコード ウェイト ロック
+200 - 単一レコード ノーウェイト ロック
+300 - 複数レコード ウェイト ロック
+400 - 複数レコード ノーウェイト ロック
ロックの詳細については、『PSQL Programmer's Guide』を参照してください。
2 ファイルのポジション ブロックを渡します。
3 データ バッファー長を、取得するレコードの長さ以上の値に設定します。
4 キー バッファーに前のオペレーションで取得したキー値を指定します。
キー バッファーには、前の呼び出しで MicroKernel エンジンから返されたキー値とまったく同じものを渡します。MicroKernel エンジンでは、ファイル内の現在の位置を決定するために、直前にキー バッファーに格納された情報が必要となるからです。
5 キー番号パラメーターを、論理位置を確立した前の呼び出しで使用したキー パスに設定します。Get Next オペレーションを使ってキー パスを変更することはできません。
結果
Get Next オペレーションが正常に終了した場合、MicroKernel エンジンではレコードがデータ バッファーに、そのレコードのキー値がキー バッファーに、さらにそのレコードの長さがデータ バッファー長に返されます。
Get Next オペレーションが正常に実行されなかった場合は、MicroKernel エンジンから次のステータス コードのいずれかが返されます。
3
ファイルが開いていません。
6
キー番号パラメーターが不正です。
7
キー番号が変更されました。
8
現在のポジションが不正です。
9
オペレーションが EOF(end-of-file)を検出しました。
22
データ バッファー パラメーターが短すぎます。
82
MicroKernel エンジンがポジショニングを失いました。
このオペレーションの実行により、論理位置の直後がファイルの末尾よりも後を指す場合は、ステータス コード 9 が返されます。
ポジショニング
Get Next オペレーションを実行すると、完全な論理カレンシーおよび物理カレンシーが確立し、取得したレコードが現在のレコードになります。
Get Next Extended(36)
Get Next Extended オペレーション(B_GET_NEXT_EXTENDED)では、指定されたキーに基づき、論理位置の直後からファイルの末尾へ向かって 1 つまたは複数のレコードを検索します。検索したレコードがフィルター条件を満たしているかどうかをチェックした上で、条件を満たすレコードだけを取得します。フィルター条件は論理式の形を取り、キー フィールドのみに制限されません。
Get Next Extended オペレーションでは、レコードから指定した部分だけを抽出し、その部分だけをアプリケーションに返すこともできます。
パラメーター
 
 
オペレーション コード
ポジション ブロック
データ バッファー
データ バッファー長
キー バッファー
キー番号
送り値
* 
* 
* 
* 
* 
* 
戻り値
 
* 
* 
* 
* 
 
前提条件
対象となるファイルが開いていることが必要です。
ファイルがデータオンリー ファイルであってはいけません。
指定したキーに基づく次の論理位置を確立しておくことが必要です。論理位置は、Get Equal など非拡張の(Extended でない)Get オペレーションをどれか発行することによって確立できます。
手順
1 オペレーション コードを 36 に設定します。任意でロック バイアスも指定できます。
+100 - 単一レコード ウェイト ロック
+200 - 単一レコード ノーウェイト ロック
+300 - 複数レコード ウェイト ロック
+400 - 複数レコード ノーウェイト ロック
ロックの詳細については、『PSQL Programmer's Guide』を参照してください。
2 ファイルのポジション ブロックを渡します。
3 入力データ バッファーと戻りデータ バッファーのどちらか大きい方を格納できるように、十分な長さのデータ バッファーを指定します。表 25 に示す構造体に従って、データ バッファーを初期化します。
4 データ バッファー長に、入力構造体(表 25)と戻り構造体(表 26)のどちらか大きい方の長さを指定します。
5 キー バッファーに前のオペレーションで取得したキー値を指定します。キー バッファーには、前の呼び出しで MicroKernel エンジンから返されたキー値とまったく同じものを渡します。MicroKernel エンジンでは、ファイル内の現在の位置を決定するために、直前にキー バッファーに格納された情報が必要となるからです。
6 キー番号パラメーターを、論理位置を確立した前の呼び出しで使用したキー パスに設定します。Get Next Extended オペレーションを使ってキー パスを変更することはできません。
詳細
次の表は、入力データ バッファーの構造体を示しています。
表 25 Extended Get / Step オペレーションの入力データ バッファー構造体
要素
長さ(バイト単位)
説明
ヘッダー
2
入力データ バッファーの正確な長さ。
2
2 つの文字列定数値のいずれかを指定します(固定長で、ヌル終端にしてはいけません)。
"EG" - ポジショニングされているレコードの次のレコードから検索を開始します。
"UC" - ポジショニングされているレコードから検索を開始します。
Step Next Extended オペレーションの場合は、この値を常に "EG" に設定してください。
フィルター(固定部分)
2
リジェクト カウントの最大数。これは、MicroKernel エンジンでレコードの検索中に、フィルター条件を満たさないものとしてスキップできるレコードの件数です。0 から 65535 までの範囲の値を指定できます。0 を指定すると、MicroKernel エンジンではシステム定義の最大リジェクト カウント、4095 が使用されます。
2
フィルター条件として使用する論理式の項の数。0 を指定すると、MicroKernel エンジンではフィルター処理が実行されません。項の数はデータ バッファーのサイズによってのみ制限されます。Pervasive.SQL 2000i SP3 でのみ、項の数が 119 に制限されています。
フィルター(論理式の各項について、このセグメントを 1 回繰り返す)
1