Btrieve API オペレーション
この章では、アプリケーションが Btrieve API を使って実行できるオペレーションについて説明します。各オペレーションについて、この章では以下の情報を示します。
•オペレーションの名前、コードおよび説明。
•パラメーター - オペレーションを実行する際に、6 個のパラメーターのうちのどの値がアプケーションから送られ、アプリケーションに返されるのかを表に示しています。「送り値」の行のパラメーターはアプリケーションからオペレーションに送られます。「戻り値」の行のパラメーターは、オペレーション完了後にオペレーションからアプリケーションに返されます。
•前提条件 - オペレーションを正常に実行させるためにアプリケーションが満たすべき条件を示します。
•手順 - オペレーションが要求するパラメーターを初期化する手順を示します。
•詳細 - オペレーションについての追加情報を示します。
•結果 - オペレーションが正常に終了した場合と、何らかのエラーが発生した場合の結果を示します。それぞれのオペレーションは、オペレーションの結果をアプリケーションに通知するステータス コードを返します。ステータス コード 0 は、オペレーションが正常に終了したことを示します。0 以外のステータス コードは、通常は何らかのエラーが発生したことを示します。ただし、0 以外のステータス コードの中には、単に情報を提供するだけで、関連するオペレーションが正常に終了したときにも示されるものがあります。たとえば、ステータス コード 60 は指定したリジェクト カウントに到達したことを意味します。
•ポジショニング - オペレーションがファイル内のレコードの論理カレンシーあるいは物理カレンシーに与える影響を示します。
この章では、以下の Btrieve API オペレーションをアルファベット順に説明します。
Abort Transaction（21）
Abort Transaction オペレーション（B_ABORT_TRAN）では、現在のトランザクションを終了し、このトランザクションの開始以降に実行されたすべてのオペレーションの結果を削除します。また、トランザクションによって設定されたすべてのファイルとレコードのロックを解除します。
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
前提条件
Abort Transaction オペレーションを発行する前に、Begin Transaction オペレーション（19 または 1019）が正常に実行されている必要があります。
手順
オペレーション コードに 21 を設定します。トランザクショナル インターフェイスでは、オペレーション コード以外の Abort Transaction 呼び出しパラメーターはすべて無視されます。
結果
Abort Transaction オペレーションが正常に終了した場合は、トランザクショナル インターフェイスからステータス コード 0 が返されます。トランザクションの開始以降に発行されたすべての Insert、Update および Delete オペレーションの結果がファイルから削除されます。
Abort Transaction オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。
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）でトランザクションの完了を要求しない限り、トランザクショナル インターフェイスはその間に実行された複数のオペレーションをすべて取り消すことができます。トランザクション内で加えられた変更は、End Transaction オペレーションの実行が正常に終了するまで、ほかのユーザーからは見ることができません。
トランザクショナル インターフェイスは、ファイルやパフォーマンスに多大な影響を与えるという理由で、いくつかのオペレーションについてトランザクション中の実行を禁止しています。この特定のオペレーションとは、Set Owner、Clear Owner、Create Index、Drop Index です。
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
前提条件
Begin Transaction オペレーションを発行する前に、先行するトランザクションを終了または中止しておく必要があります。
手順
オペレーション コードに 19 を設定して排他トランザクションを開始するか、1019 を設定して並行トランザクションを開始します。トランザクショナル インターフェイスでは、オペレーション コード以外の Begin Transaction 呼び出しパラメーターはすべて無視されます。
Begin Transaction オペレーションでは、デフォルトのロック バイアスを指定できます。
•+100 - 単一レコード ウェイト ロック
•+200 - 単一レコード ノーウェイト ロック
•+300 - 複数レコード ウェイト ロック
•+400 - 複数レコード ノーウェイト ロック
並行トランザクションの Begin Transaction オペレーションでは、+500 をオペレーション コードに追加できます（1519）。追加すると、トランザクション内の Insert、Update、Delete の各オペレーションが、トランザクショナル インターフェイスによって再試行されなくなります。
さらに、+500 バイアスをデフォルトのロック バイアスと組み合わせることもできます。たとえば、1019 + 500 + 200（1719）を使用すると、Insert、Update および Delete オペレーションの再試行を抑え、並行トランザクションが実行されます。また同時に、単一レコードの読み取りノーウェイト ロックが指定されます。
トランザクションおよびロックの詳細については、『Pervasive PSQL Programmer's Guide』を参照してください。
結果
Begin Transaction オペレーションが正常に終了した場合は、トランザクショナル インターフェイスからステータス コード 0 が返されます。
Begin Transaction オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。
36 | アプリケーションでトランザクション エラーが発生しました。 |
37 | 別のトランザクションが実行中です。 |
ポジショニング
Begin Transaction オペレーションは、ファイルのカレンシー情報にまったく影響しません。
Clear Owner（30）
Clear Owner オペレーション（B_CLEAR_OWNER）では、あらかじめ Set Owner オペレーションを使ってファイルに割り当ててあるオーナー ネームを削除します。ファイルがあらかじめ暗号化されている場合は、Clear Owner オペレーションの実行中にトランザクショナル インターフェイスによってファイルの解読も行われます。
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
前提条件
•対象となるファイルが開いており、オーナー ネームが指定されていることが必要です。
•トランザクションが実行中でないことが必要です。
手順
1 オペレーション コードに 30 を設定します。
2 対象となるファイルを識別するポジション ブロックを渡します。
結果
Clear Owner オペレーションが正常に実行されると、それ以降、トランザクショナル インターフェイスはファイルを開いたり変更したりするときにオーナー ネームを要求しなくなります。オーナーを割り当てるときにファイルのデータを暗号化した場合には、トランザクショナル インターフェイスは Clear Owner オペレーションの実行中にデータの解読も行います。暗号化されているデータが多いほど、Clear Owner オペレーションの実行にかかる時間は長くなります。
Clear Owner オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。
3 | ファイルが開いていません。 |
41 | 実行しようとした操作はトランザクショナル インターフェイスでは許可されていません。 |
ポジショニング
Clear Owner オペレーションは、ファイルのカレンシー情報にまったく影響しません。
Close（1）
Close オペレーション（B_CLOSE）では、指定されたポジション ブロックに関連付けられているファイルを閉じ、そのファイルに対して実行されたロックをすべて解除します。ファイルへのアクセスを終了するとき、アプリケーションでは必ず Close オペレーションを実行する必要があります。Close オペレーションの実行後は、もう一度 Open オペレーション（0）を発行しない限り、そのファイルにはアクセスできなくなります。
トランザクション中でも、ファイルを閉じることができます。ただし、Close オペレーションを実行しても、トランザクションは終了しません。トランザクションは明示的に終了または中止する必要があります。トランザクションを中止すると、トランザクション中に行われた変更は削除されます。トランザクションを終了すると、変更が反映されます。
メモ： トランザクション中にファイルを閉じた場合、トランザクショナル インターフェイスではそのファイルへの更新を正しく処理できるように、トランザクションが中止または終了されるまでファイルのオープン ハンドルを保持します。ただし、そのファイルのポジション ブロックをアプリケーションで使用することはできなくなります。
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
前提条件
•対象となるファイルが開いていることが必要です。
手順
1 オペレーション コードに 1 を設定します。
2 閉じるファイルに対応する有効なポジション ブロックを渡します。
結果
Close オペレーションが正常に終了した場合は、閉じたファイルに対応するポジション ブロックは有効でなくなります。
Close オペレーションが正常に実行されなかった場合は、ファイルが開いたままになり、トランザクショナル インターフェイスから次のステータス コードが返されます。
ポジショニング
Close オペレーションを実行すると、ファイルの物理カレンシー情報および論理カレンシー情報は消去されます。
Continuous Operation（42）
Continuous オペレーション（B_CONTINOUS）では、アクティブなトランザクショナル インターフェイス ファイルを閉じることなく、システム バックアップを実行できます。ファイルのバックアップ中に行った変更は、デルタ ファイルと呼ばれる一時ファイルに記憶されます。デルタ ファイルに書き込まれた変更を除き、Continuous オペレーション モードに置かれたすべてのファイルの内容がシステム バックアップの対象になります。バックアップされたファイルが Continuous オペレーション モードから抜けると、トランザクショナル インターフェイスにより、デルタ ファイルの変更がこれらのファイルに自動的にロール インされます。
メモ： このオペレーションは、ローカル エンジンで動作しているアプリケーションにのみ使用できます。クライアント アプリケーションはリモート マシンにあるファイルに対してこのオペレーションを使用することはできません。
このオペレーションを使うと、ファイルがアクティブな状態のまま、それを安全にコピーできます。クライアント/サーバー セットアップでは、あるファイルで 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 で説明したように、名前の長さをデータ バッファー長パラメーターに入れます。
詳細
一連のファイルをバックアップするように定義する場合は、以下の点に留意してください。
•トランザクショナル インターフェイスは、データ バッファーにファイル名が入っていなくてもエラーと見なしません。ファイル名が見つからない場合、トランザクショナル インターフェイスは Continuous オペレーションで何の動作も行いません。
•データ バッファーに重複するファイル名が存在しても、Continuous オペレーションの動作状況には影響しません。MKDE では、指定したファイルを 1 度だけ Continuous オペレーション モードに置きます。
•同じディレクトリに、ファイル名が同一で拡張子のみが異なるようなファイルを置かないでください。たとえば、Invoice.btr という名前のデータ ファイルと Invoice.mkd という名前のファイルが同じディレクトリ内にあってはなりません。このような制限が設けられているのは、データベース エンジンがさまざまな機能でファイル名のみを使用し、ファイルの拡張子を無視するためです。Continuous オペレーションでは、デルタ ファイル名として、対応するファイルの名前に拡張子「.^^^」を付けた名前を使用します。トランザクショナル インターフェイスは両方のファイルについて同一のデルタ ファイルに書き込もうとするため、データの破損につながるか、もしくはステータス 85 が返される可能性があります。また、これらのファイルが Continuous オペレーション モードに置くファイルの大きなリストの一部であったとしても、この状況が発生する場合には、ファイルは一切 Continuous オペレーション モードに置かれません。
•アプリケーションでは、Continuous オペレーションを反復的に呼び出して、Continuous オペレーション モードに置くファイルのリストにファイル名を追加できます。ただし、SRDE によってファイルの一部に参照整合性（RI）制約が設定されている場合は、この操作により、バックアップが壊れる可能性があります。参照整合性制約と関連付けられているファイルは、単独の Continuous オペレーション呼び出しで渡す必要があります。
既に Continuous オペレーション モードに入っているファイルを指定すると、トランザクショナル インターフェイスからステータス コード 88 が返されます。
Continuous オペレーションを呼び出すサーバー ベースのアプリケーションを作成する場合は、必ず BTRVID を呼び出し、有効なクライアント ID を使用することで、同一クライアントのもとで Continuous オペレーションの開始と終了を行えるようにします。
Btrieve API では、BTRVID 関数を使ってバックアップ セットごとに異なるクライアント ID を指定し、複数のバックアップ セットを定義できます。ただし、同じファイルを 2 つのセットに入れることはできません。
トランザクショナル インターフェイスによってデルタ ファイルからデータ ファイルに変更内容がロール インされているときでも、ユーザーは通常の場合と同じように、トランザクショナル インターフェイス ファイルの更新、挿入および読み取りを引き続き実行できます。トランザクショナル インターフェイスは挿入作業で必要となれば、変更内容のロール イン中でもデルタ ファイルに新しいページを追加します。このため、変更内容が失われることはありません。
メモ： デルタ ファイルは決して手動で削除しないでください。
アプリケーションで BTRV 関数を使用する場合は、ファイルが Continuous オペレーション モードに入っているときにそのアプリケーションをアンロードしないでください。アンロードすると、対象となるファイルを Continuous オペレーション モードから削除できなくなることがあります。これは、対象となるファイルのオーナーとしてトランザクショナル インターフェイスが当初割り当てたデフォルトのクライアント ID が、別のアプリケーションに再割り当てされてしまう可能性があるからです。トランザクショナル インターフェイスでは対象となるファイルの正しいオーナーがわからなくなるため、それらのファイルを Continuous オペレーション モードから削除できなくなってしまいます。
Continuous オペレーション モードに入るとき、またはトランザクショナル インターフェイスによってデルタ ファイルからデータ ファイルに変更内容がロール インされている最中にシステムがクラッシュした場合は、システムの再起動後初めてそのファイルを開くときに、トランザクショナル インターフェイスによってすべての変更内容がファイルにロール インされます。
結果
Continuous オペレーションが正常に終了した場合、トランザクショナル インターフェイスからステータス コード 0 が返されますが、データ バッファーおよびデータ バッファー長パラメーターには何の値も返されません。
このオペレーションが正常に実行されなかった場合、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。
11 | 指定されたファイル名は不正です。 |
12 | トランザクショナル インターフェイスは指定されたファイルを見つけられません。 |
41 | 実行しようとした操作はトランザクショナル インターフェイスでは許可されていません。 |
51 | オーナー ネームが不正です。 |
88 | アプリケーションでモードの不一致エラーが発生しました。 |
91 | アプリケーションでサーバー エラーが発生しました。 |
上記のコードに加え、アプリケーションには、ステータス コード 18 のような標準の I/O エラーが返されることがあります。
トランザクショナル インターフェイスから 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 文字までの範囲で指定することができます。
Pervasive PSQL クライアントでサポートするパス名の詳細については、『
Getting Started with Pervasive PSQL』の
Pervasive リクエスターでサポートするネットワーク パスの形式を参照してください。『
Pervasive PSQL Programmer's Guide』の
データベース URI も参照してください。
5 キー番号パラメーターの値を、表
14 の値のいずれかを使って指定します。
詳細
表
8 は、ファイル仕様およびキー仕様を格納する順序を示しています。
表 8 Create オペレーションのデータ バッファー構造体
説明 | データ型1 | バイト番号 | 値の例2 |
ファイル仕様 |
論理固定レコード長3 | Short Int4 | 0, 1 | すべてのフィールドを結合したサイズです。 |
ページ サイズ | Pervasive PSQL 6.x から 9.4 | Short Int | 2, 3 | 512 |
Pervasive PSQL 6.x 以上 | 1,024 |
Pervasive PSQL 6.x から 9.4 | 1,536 |
Pervasive PSQL 6.x 以上 | 2,048 |
Pervasive PSQL 6.x から 9.4 | 3,072 |
3,584 |
Pervasive PSQL 6.x 以上 | 4,096 |
Pervasive PSQL 9.0 から 9.4x | 8,192 |
Pervasive PSQL 9.5 以上 | 16,384 |
ほとんどのファイルでは最小サイズの 4096 バイトが最も効率的です。微調整を行う場合の詳細については、 ページ レベル圧縮を用いたファイルの作成を参照してください。 9.5 ファイル形式のファイルを作成する場合、指定された論理ページ サイズがそのファイル形式で有効ならば、MicroKernel は指定値の次に大きな有効値があるかどうかを調べ、存在する場合はその値に切り上げます。それ以外の値やファイル形式の場合、オペレーションはステータス コード 24 で失敗します。古いバージョンのファイル形式では切り上げは行われません。 |
キー（インデックス）数 | Byte | 4 | |
ファイル バージョン | Byte | 5 | 0x60 | バージョン 6.0 |
0x70 | バージョン 7.0 |
0x80 | バージョン 8.0 |
0x90 | バージョン 9.0 |
0x95 | バージョン 9.5 |
0x00 | データベース エンジンのデフォルトを使用 |
予約済み（Create オペレーションでは使用しません） | 予約済み | 6- 9 | 0 |
ファイル フラグ。ファイル属性を指定します。ファイルの例では、ファイル フラグを使用していません。 | Short Int | 10, 11 | 0 |
追加ポインター数。将来のキーの追加のために予約する重複ポインター数を設定します。ファイル属性で予約重複ポインターを指定する場合に使用します。 | Byte | 12 | 0 |
予約済み（Create オペレーションでは使用しません） | 予約済み | 13 | 0 |
プリアロケート ページ数。事前に割り当てられるページ数を設定します。ファイル属性でページ プリアロケーションを指定する場合に使用します。 | Short Int | 14, 15 | 0 |
キー 0（ラスト ネーム）のキー仕様 |
キー ポジション。レコード内のキーの最初のバイトの位置を指定します。レコード内の最初のバイトは 1 です。 | Short Int | 16, 17 | 1 |
キー長。バイト単位でキーの長さを指定します。 | Short Int | 18, 19 | 25 |
キー フラグ。キー属性を指定します。 | Short Int | 20, 21 | EXTTYPE_KEY + NOCASE_KEY + DUP + MOD |
Create には使用しません。 | Byte | 22-25 | 0 |
拡張キー タイプ。キー フラグで「拡張キー タイプを使用する」を指定する場合に使用します。拡張データ型のうちの 1 つを指定します。 | Byte | 26 | ZSTRING |
ヌル値（レガシー ヌルのみ）。キー フラグで「ヌルキー（すべてのセグメント）」または「ヌルキー（任意のセグメント）」を指定する場合に使用します。キーの除外値を指定します。レガシー ヌルと真のヌルの概念については、 ヌル値を参照してください。 | Byte | 27 | 0 |
Create には使用しません。 | Byte | 28, 29 | 0 |
手動割り当てキー番号。ファイル属性で「キー番号」を指定する場合に使用します。キー番号を割り当てます。 | Byte | 30 | 0 |
ACS 番号。キー フラグで「デフォルトの ACS を使用する」、「ファイル内の番号付きの ACS を使用する」または「名前付きの ACS を使用する」を指定する場合に使用します。使用する ACS 番号を指定します。 | Byte | 31 | 0 |
キー 1（社員 ID）のキー仕様 |
キー ポジション。（社員 ID は、ミドル イニシャルの後の最初のバイトから始まります。） | Short Int | 32, 33 | 52 |
キー長。 | Short Int | 34, 35 | 4 |
キー フラグ。 | Short Int | 36, 37 | EXTTYPE_KEY + MOD |
Create には使用しません。 | Byte | 38-41 | 0 |
拡張キー タイプ。 | Byte | 42 | INTEGER |
ヌル値。 | Byte | 43 | 0 |
Create には使用しません。 | Byte | 44, 45 | 0 |
手動割り当てキー番号。 | Byte | 46 | 0 |
ACS 番号。 | Byte | 47 | 0 |
ページ圧縮のキー仕様 |
物理ページ サイズ5 | Char | A | 512
（デフォルト値） |
1 特に指定がない場合、すべてのデータ型は符号なしです。 2 簡素化を図るため、数値以外の値の例は C アプリケーションの場合です。 3 可変長レコードを持つファイルの場合、論理レコード長はレコードの固定長部分のみを指します。 4 Short Integer（Short Int）は「リトル エンディアン」のバイト順、つまり、Intel 系のコンピューターが採用している下位バイトから上位バイトへ記録する方式で格納する必要があります。 5 ページ レベル圧縮でのみ使用します。ページ圧縮ファイル フラグ（表 6 を参照）と組み合わせて使用する必要があります。詳細については、『 Pervasive PSQL Programmer's Guide』の ページ レベル圧縮を用いたファイルの作成を参照してください。 |
メモ： トランザクショナル インターフェイスは Create オペレーションではデータ バッファーの「未使用」および「予約済み」領域を使用しませんが、それらを割り当てておく必要があります。将来のリリースとの互換性を維持するため、予約済み領域はゼロに初期化してください。
ファイル仕様
データ バッファーの先頭 16 バイトにはファイル仕様を格納します。バイトは 0 から数え始めます。レコード長、ページ サイズおよびインデックス数の情報を整数で格納します。
論理レコード長。（オフセット 0x00）論理レコード長はファイルの固定長データのバイト数です（論理レコード長には可変長データを含めないでください）。
ページ サイズ。（オフセット 0x02）ページ サイズはファイル形式のバージョンによって決まっています。『
Pervasive PSQL Programmer's Guide』の
ページ サイズの選択を参照してください。
インデックス数。（オフセット 0x04）インデックス数はファイルに対して定義しているキーの数です。キー セグメント数ではありません。データオンリー ファイルを作成するには、インデックス数に 0 を設定します。
ファイル バージョン。（オフセット 0x05）作成するトランザクショナル インターフェイスのファイル バージョンです。前のリリースでは、トランザクショナル インターフェイスは 2 バイト整数を使って Create オペレーションでインデックス数を取得していました。インデックスの最大数は 119 であるため、この整数の上位バイトは常にゼロでした。この上位バイトは、Stat オペレーションではファイル バージョンを返すために常に使用されていますが、以前のアプリケーションを破棄しなくとも、Create オペレーションでファイル バージョンの指定に使用できるようになりました。Create でサポートされるファイル バージョンは 6.x、7.x、8.x、9.x、9.5 です。これらは、それぞれ 16 進数の値 0x50、0x60、0x70、0x80、0x90、0x95 で特定のバイトに示されます。
物理ページ サイズ。（オフセット 0xA）このフィールドは、以前は「未使用」とマークされていました。このフィールドはページ圧縮ファイル フラグと組み合わせて使用されます。ページ圧縮フラグが指定されていなければ、このフィールドは無視されます。
バージョン 6.x 以降のデータ ファイルでは、論理ページは物理ページに割り当て、ページ アロケーション テーブル（PAT）に格納します。物理ページのサイズは論理ページのサイズと同一です。ページ圧縮は 9.5 以降のファイル形式で使用できます。データベース ページはページ レベルで圧縮されます。各論理ページは、1 つ以上の物理ページ単位に圧縮されます。これら個々の物理ページのサイズは、1 論理ページよりも小さくなります。
物理ページ サイズ フィールドを使用して、ファイルで使用する物理ページ サイズを指定できます。このフィールドで指定する値は、使用される実際の物理ページ サイズを決定するため、512 の倍数にします。ゼロを指定すると、エンジンは物理ページ サイズのデフォルト値を使用します。デフォルト値は 512 バイトです。
物理ページ サイズに指定された値は、論理ページ サイズに指定された値よりも大きくすることはできません。物理ページ サイズに指定された値の方が大きい場合、エンジンは論理ページ サイズと同じになるようその値を切り捨てます。論理ページ サイズは物理ページ サイズの倍数になっていなければなりません。倍数でない場合、その論理ページ サイズの値は物理ページ サイズの値のちょうど倍数になるよう切り捨てられます。このような操作の結果として、論理ページ サイズと物理ページ サイズの値が同じになった場合、ページ レベルの圧縮はこのファイルに適用されません。『
Pervasive PSQL Programmer's Guide』の
ページ レベル圧縮を用いたファイルの作成も参照してください。
ファイル フラグ。（オフセット 0x0A）ファイル フラグ ワードのビットをセットして、ファイルの属性を指定します。表
9 に、ファイル フラグの値の 2 進、16 進、および 10 進表記を示します。
表 9 ファイル フラグの値
属性 | 定数 | 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 10 00 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 | 4,608 |
キー番号 | SPECIFY_KEY_NUMS | 0000 0100 0000 0000 | 400 | 1,024 |
VAT の使用 | VATS_SUPPORT | 0000 1000 0000 0000 | 800 | 2,048 |
ページ圧縮の使用2 | PAGE_COMPRESSED | 0010 0000 0000 0000 | 2000 | 8,192 |
1 システム データをファイルに含めるかどうかを明示的に指定していない場合、Btrieve API は、トランザクショナル インターフェイス設定オプションの「システム データ」のその時点の設定を使用します。 2 ページ レベル圧縮でのみ使用します。「物理ページ サイズ」キー仕様と組み合わせて使用されます。詳細については、『 Pervasive PSQL Programmer's Guide』の ページ レベル圧縮を用いたファイルの作成を参照してください。 |
互換性のないフラグの使用は避けてください。同一ビット位置を使用するフラグ間には互換性はありません。未使用のビットは将来使用するために予約されています。これらのビットには 0 を設定します。
ファイルの属性を組み合わせるには、対応するファイル フラグの値を加算します。たとえば、可変長レコードを含むことができ、ブランク トランケーションを行うファイルを指定するには、ファイル フラグ ワードを 3（2 + 1）に初期化してください。可変長レコードのビットが 0 に設定されている場合、トランザクショナル インターフェイスではブランク トランケーションおよび空きスペース スレッショルドのビットを無視します。
ページ プリアロケーションのビットを設定する場合は、ファイル仕様ブロック（アロケーション）の最後の 2 バイトを使用して、ファイルにプリアロケートするページ数を指定する整数値を格納してください。データ圧縮のビットを設定した場合、トランザクショナル インターフェイスでは可変長レコードのビットが無視されます。キーオンリー ファイルのビットを設定した場合、トランザクショナル インターフェイスではシステム データのビットが無視されます。
データベース エンジンは、システム データを使用しており、レコード長が許容最大サイズを超えるファイルについては自動的にデータ圧縮を使用します。『
Pervasive PSQL Programmer's Guide』の表
12 を参照してください。
ファイルを作成した後でインデックスの追加が予想され、そのインデックスに多数の重複した値が含まれる場合は、重複ポインターのビットを設定します。このビットを設定すると、トランザクショナル インターフェイスでは重複した値をリンクするポインターのためにファイルの各レコードにスペースが確保されるようになります。このようなスペースを確保することにより、特に、キーが長く、多数のレコードが重複するキー値を持つことが予測される場合には、検索時間を短縮し、ディスク領域を節約できる場合があります。
メモ： 重複ポインターの領域は、ファイル作成後に追加されるインデックスのみを対象に予約できます。したがって、重複値へのポインターのために領域を確保するときは、この Create オペレーションの実行中に作成されるインデックスの領域は含めないでください。また、繰り返し重複キーとして指定されるキーについて、トランザクショナル インターフェイスは重複ポインターの領域を確保しません。
特定の番号をキーに割り当てることが必要な場合は、キー番号のビットを設定し、希望するキー番号をキー仕様ブロックの手動割り当てキー番号要素（オフセット 0x0E）に入れます。トランザクショナル インターフェイスではキー番号が連続している必要はありません。つまり、ファイルのキー番号は飛んでいてもかまいません。キーが作成されると、トランザクショナル インターフェイスはデフォルトで、0 から始まるキー番号のうち使用可能な最小の番号をそのインデックスに割り当てます。ただし、アプリケーションによっては、デフォルトの割り当てとは異なるキー番号が必要なこともあります。
ファイルで可変長部割り当てテーブルを使用する場合は、VAT の使用のビットを設定します。VAT を使うには、ファイルで可変長レコードを使用していることが必要です。
予約する重複ポインター数。（オフセット 0x0C）予約する重複ポインター数をファイルごとに指定できます。予約重複ポインターのファイル フラグを指定した場合にのみ、この要素を使用してください。重複キーの詳細については、『
Pervasive PSQL Programmer's Guide』の
重複キーを参照してください。
アロケーション。（オフセット 0x0E）プリアロケートするページ数を指定できます。ページ プリアロケーションのファイル フラグを指定した場合にのみ、この要素を使用してください。ページのプリアロケーションの詳細については、『
Pervasive PSQL Programmer's Guide』の
ページ プリアロケーションを参照してください。
キー仕様ブロック
ファイル仕様のすぐ後にキー仕様ブロックを配置します。ファイルのキー セグメントごとに 16 バイトのキー仕様ブロックを割り当てます。キー ポジションおよびキー長の情報は整数で格納します。
キー セグメントの最大許容数は、ファイルのページ サイズによって異なります。
ページ サイズ（バイト数） | キー セグメントの最大数（ファイル バージョン別） |
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：キー長が不正です。を参照してください。
キー ポジション。（オフセット 0x00）キー ポジションは、キーまたはキー セグメントの開始位置のバイト オフセットです。ポジションは 1 からの相対になります。レコードの先頭に位置するキーは、ポジション 1 から始まります。ポジション 0 はありません。
キー長。（オフセット 0x02）キーまたはキー セグメントの長さです。キーの最大長は、すべてのキー セグメントを含めて、255 バイトです。
キー フラグ。（オフセット 0x04）キー フラグ ワードのビットをセットして、キーの属性を指定します。表
10 に、キー フラグの値の 2 進、16 進、および 10 進表記を示します。
表 10 キー フラグの値
属性 | 定数 | 2 進数 | 16 進数 | 10 進数 |
重複許可（リンクされた重複はデフォルト、あるいは繰り返し重複用に REPEAT_DUPS_KEY と組み合わせる） | DUP | 0000 0000 0000 0001 | 1 | 1 |
変更可能キー値 | MOD | 0000 0000 0000 0010 | 2 | 2 |
旧形式の BINARY データ型を使用 | BIN | 0000 0000 0000 0100 | 4 | 4 |
旧形式の STRING データ型を使用（ビット 2 および 8 は 0 にする必要があります） | | 0000 0000 0000 0000 | 0 | 0 |
ヌル キー（全セグメント） | NUL | 0000 0000 0000 1000 | 8 | 8 |
セグメント キー | SEG | 0000 0000 0001 0000 | 10 | 16 |
デフォルトの ACS を使用 | ALT | 0000 0000 0010 0000 | 20 | 32 |
ファイル内の番号付きの ACS を使用 | NUMBERED_ACS | 0000 0100 0010 0000 | 420 | 1,056 |
名前付きの ACS を使用 | NAMED_ACS | 0000 1100 0010 0000 | C20 | 3,104 |
降順ソート | DESC_KEY | 0000 0000 0100 0000 | 40 | 64 |
繰り返し重複（DUP 属性と組み合わせる） | REPEAT_DUPS_KEY | 0000 0000 1000 0000 | 80 | 128 |
拡張データ型を使用 | EXTTYPE_KEY | 0000 0001 0000 0000 | 100 | 256 |
ヌル キー（一部セグメント） | MANUAL_KEY | 0000 0010 0000 0000 | 200 | 512 |
大文字小文字無視キー | NOCASE_KEY | 0000 0100 0000 0000 | 400 | 1,024 |
互換性のないフラグの使用は避けてください。同一ビット位置を使用するフラグ間には互換性はありません。未使用のビットは将来使用するために予約されています。これらのビットには 0 を設定します。
キーの属性を組み合わせるには、対応するキー フラグの値を加算します。たとえば、キーが拡張キー タイプで、セグメント キーの一部であり、さらに降順に照合される場合は、キー フラグ ワードを 336（256 + 16 + 64）に初期化します。
セグメント キー属性は、データ バッファー内の次のキー仕様ブロックが同一キーの次のセグメントを指すことを示します。セグメント キーについては以下の規則に従ってください。
•同一キーのすべてのセグメントで、重複可能、繰り返し重複、変更可能およびヌル キーの値はそれぞれ同じでなければなりません（レガシー ヌル キー属性を指定する場合は、全セグメントまたは一部セグメントのどちらの場合にも、セグメントごとに異なるヌル値を割り当てることができます）。
•同一キーのすべてのセグメントで、同一 ACS を使用する必要があります。
•同一キーのセグメントごとに、異なる降順ソートおよび拡張データ型の値を設定できます。
ACS は、STRING、LSTRING および ZSTRING キーにのみ適用できます。大文字小文字の区別を無視し、かつ ACS を使用するキーを定義することはできません。あるキーの一部のセグメントにしか ACS が指定されていないファイルの場合、ACS が指定されているセグメントはその ACS に従ってソートされ、ACS が指定されていないセグメントはそれぞれの型に従ってソートされます。
拡張データ型。（オフセット 0x0A）拡張データ型をキー仕様ブロックのバイト 10 にバイナリ値で指定します。表
11 に、拡張データ型に対応するコードを示します。
表 11 拡張データ型
データ型 | コード | データ型 | コード |
CHAR | 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 を使って開発したアプリケーションとの互換性が保てる一方、新しいアプリケーションで拡張データ型を排他的に使用できるようになります。
キーに割り当てるデータ型に関し、入力したレコードがそのキーに定義されているデータ型に合っているかどうかは、トランザクショナル インターフェイスでは確認されません。たとえば、TIMESTAMP キーをファイルに定義することができますが、そこに文字列を格納することもできます。Btrieve API アプリケーションでは問題なく動作していても、ODBC アプリケーションで同じデータに ODBC TIMESTAMP データ型を使ってアクセスしようとすると、正常に動作しないことがあります。これはおそらく、バイトの形式が異なり、タイムスタンプ値を生成するアルゴリズムが異なるからです。データ型の説明については、『SQL Engine Reference』を参照してください。
ヌル値。（オフセット 0x0B）キー仕様ブロックのこのオフセットは、キーの除外値を表します。あるキーをヌル キーとして定義した場合は、各キー セグメントのヌル値として認識させる値をトランザクショナル インターフェイスに提供する必要があります。これは、レガシー ヌルへの参照内にあり、真のヌルには影響しません。ヌルのサポートの説明については、『
Pervasive PSQL Programmer's Guide』の
ヌル値を参照してください。
手動割り当てキー番号。（オフセット 0x0E）トランザクショナル インターフェイスでは、インデックス付きのファイルを作成するときに、アプリケーションで特定のキー番号を割り当てることができます。ファイルの各インデックスに手動でキー番号を割り当てるには、各キー番号をキー仕様ブロックのバイト 14 にバイナリ値で指定し、ファイル フラグ ワードにキー番号ビット（0x400）を設定します。
キー番号はファイルで一意であり、キー 0 から昇順に指定されていなければなりません。また、有効な値、つまり、ファイルのページ サイズに対するキーの最大数よりも小さい値でなければなりません。
手動でキー番号を割り当てるという機能は、キーを削除して、その削除したキーよりも大きなキー番号を持つすべてのキーの番号をトランザクショナル インターフェイスに付け替えさせないようにする機能と相補関係にあります。たとえば、アプリケーションからインデックスを削除し、トランザクショナル インターフェイスにそれよりも大きな番号を持つキーの番号を付け替えないように指示を出した場合、その後でユーザーが具体的なキー番号を割り当てずに影響を受けたファイルを複製すると、複製したファイルには元のファイルとは別のキー番号が割り当てられます。
ACS 番号。（オフセット 0x0F）特定の ACS を使用するキーの場合、キー仕様ブロックのオフセット 0x0F により、キーの照合に使用する ACS 番号が示されます。ACS 番号はデータ バッファー内の位置に基づいて決まります。最後のキー仕様ブロックに続く最初の ACS は、ACS 番号 0 になります。ACS 0 の次には ACS 1、その次には ACS 2、というように続きます。
オルタネート コレーティング シーケンス（ACS）
アプリケーションでは、データ バッファー内の最後のキー仕様ブロックの直後から ACS を 1 つずつ順に指定します。
ユーザー定義の ACS。文字列値を ASCII 標準とは異なる並び順でソートする ACS を作成するには、表
12 に示す形式を使って、アプリケーションからデータ バッファーに直接 265 バイトを設定する必要があります。
表 12 ユーザー定義の ACS を作成するためのデータ バッファー
位置
（オフセット） | 長さ
（バイト単位） | 説明 |
0 | 1 | 識別バイト。0xAC を指定します。 |
1 | 8 | トランザクショナル インターフェイスに ACS を識別させる、8 バイトの一意の名前。 |
9 | 256 | 256 バイトのマップ。マップ内の 1 バイトの位置はそれぞれ、マップ内でのその位置のオフセットと同じ値を持つコード ポイントに対応します。その位置にあるバイトの値は、コード ポイントに割り当てられるコレーティング ウェイトです。たとえば、コード ポイント 0x61（'a'）をコード ポイント 0x41（'A'）と同じウェイトでソートさせるには、オフセット 0x61 および 0x41 に同一の値を設定します。 |
ユーザー定義の ACS の例については、『
Pervasive PSQL Programmer's Guide』の
オルタネート コレーティング シーケンスを参照してください。
インターナショナル ソート規則（ISR）。ISR を指定するには、以下の形式でアプリケーションからデータ バッファーに直接 265 バイトを設定することが必要です。
表 13 ISR ACS を指定するためのデータ バッファー
位置
（オフセット） | 長さ
（バイト単位） | 説明 |
0 | 1 | 識別バイト。0xAE を指定します。 |
1 | 16 | トランザクショナル インターフェイスに ISR テーブルを識別させる、16 バイトの一意の名前。ISR テーブル名のリストについては、『Pervasive PSQL Programmer's Guide』を参照してください。 |
17 | 248 | Filler |
データ バッファー長
データ バッファー長は、ファイル仕様、キー仕様、および定義されている ACS を十分に格納できるだけの長さを持つ必要があります。このパラメーターにファイルのレコード長を指定しないでください。
たとえば、1 セグメントのキーを 2 つと ACS を 1 つ持つファイルを作成するには、Create オペレーションのデータ バッファーには、以下のように、少なくとも 313 バイトの長さが必要です。
ファイル仕様 | + | キー仕様 | + | キー2 仕様 | + | ACS | |
16 | + | 16 | + | 16 | + | 265 | = 313 |
キー番号
Create オペレーションのキー番号パラメーターは、同名のファイルが既に存在する場合にトランザクショナル インターフェイスが警告を出すかどうかを決定するために、また、ファイルの作成時にトランザクショナル インターフェイスがローカル エンジンとリモート エンジンのどちらを使用するかを決定するために使用されます。
表
14 を使って、キー番号パラメーターで使用する値を決定します。
メモ： ローカル エンジンでファイルを作成するよう指定する場合は、ワークグループ エンジンでもサーバー エンジンでも、Create オペレーションに何ら違いはありません。
表 14 Create オペレーションのキー番号パラメーター
CREATE オペレーション | 選択しない | ローカル エンジンにファイルを作成させる | リモート エンジンにファイルを作成させる |
標準の作成（ファイルが既存の場合、上書きする） | 0 | 6 | 99 |
ファイルが既存の場合、ステータス 59 を返す | -1 | 7 | 100 |
Create オペレーションによる削除および名前変更サブファンクション
Create オペレーションには 2 つのサブファンクションがあり、これを使用してファイルの削除または名前変更ができます。
Pervasive.SQL v8.5 より前のリリースでは、オペレーティング システムを介してトランザクショナル インターフェイス ファイルを操作することは常に可能でした。これは、オペレーティング システムが Pervasive PSQL ユーザーに与える権限にトランザクショナル インターフェイスが依存していたためです。
しかし現在は、セキュリティが設定された Pervasive PSQL データベースがある場合、承認されていないアクセスからデータベースを保護する過程において、このようなオペレーティング システムのアクセス権は除去されることがあります。これにより、必ずしも必要な権限を利用できるとは限らなくなるため、プログラムによるファイルの削除や移動が困難になりました。
名前変更と削除のサブファンクションは、代替キー番号を持つ Create オペレーションとして実装されています。新規データ ファイルを作成する場合のようにファイル仕様を指定する必要はありません。Create オペレーションで名前変更と削除サブファンクションを使用するための設定方法を、次の表に示します。
表 15 Create オペレーションのサブファンクション
機能 | 使用するキー番号 | 説明 | データ バッファーに指定するもの | キー バッファーに指定するもの |
ファイルの名前変更 | -127 | データ バッファーの既存のファイルを、キー バッファーの名前に変更します。 | 既存のファイル名 | 新しいファイル名 |
ファイルの削除 | -128 | ファイルを削除します。 | 適用外 | 既存のファイル名 |
これらのサブファンクションはセキュリティ モデルで動作するように変更されました。その変更点として、サブファンクションは削除または名前変更するトランザクショナル インターフェイス ファイルを示すために、必要に応じて、キー バッファーおよびデータ バッファーでファイル名の代わりに URI を受け入れるようになりました。これにより、セキュリティ情報をオペレーションに指定することができます。URI 接続文字列の詳細については、『
Pervasive PSQL Programmer's Guide』の
データベース URI を参照してください。
セキュリティ情報は、通常の Create または Open オペレーションとまったく同様に処理されます。ユーザーは認証され、かつ、既存のファイルに対して、また新しいファイルの保存場所となるディレクトリに対して DB_RIGHT_CREATE、DB_RIGHT_ALTER、および DB_RIGHT_OPEN 権限を持っている必要があります。
表 16 Create サブファンクション －キー バッファーでの URI パラメーターの使用
機能 | URI パラメーター file= | URI パラメーター dbfile= | URI パラメーター table= |
名前変更 | | | |
削除 | | | |
表 17 Create サブファンクション －データ バッファーでの URI パラメーターの使用
機能 | file= | dbfile= | table= |
名前変更 | | | |
削除 | 適用外 | 適用外 | 適用外 |
名前変更および削除サブファンクションでの注意
•以前の Create オペレーションの機能は変更されていません。トランザクショナル インターフェイス データ ファイルを新規作成する場合は、既存マニュアルの Create オペレーションの説明に従ってください。
•RenameFile および DeleteFile サブファンクションは種々雑多なページの内容には影響しないため、特定のデータベースにバインドされているファイルに使用することはできません。
•ファイルにオーナー ネームが含まれている場合、新しいサブファンクションではオーナー ネームのチェックは行われません。オーナー ネームはファイルの内容を表示させるためには、引き続き必要です。
結果
Create オペレーションが正常に終了した場合は、トランザクショナル インターフェイスから同名のファイルが既に存在すると警告されるか、仕様に従って新しいファイルが作成されます。新規ファイルにはレコードは含まれていません。Create オペレーションでは作成したファイルを開きません。したがって、ファイルにアクセスするには、アプリケーションで Open オペレーションを実行する必要があります。
Create オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。
2 | アプリケーションで I/O エラーが発生しました。 |
11 | 指定されたファイル名は不正です。 |
18 | ディスクがいっぱいです。 |
22 | データ バッファー パラメーターが短すぎます。 |
24 | ページ サイズまたはデータ バッファー サイズが不正です。 |
25 | アプリケーションが指定されたファイルを作成できません。 |
26 | 指定されたキーの数が不正です。 |
27 | キー ポジションが不正です。 |
28 | レコード長が不正です。 |
29 | キー長が不正です。 |
48 | オルタネート コレーティング シーケンス定義が不正です。 |
49 | 拡張キー タイプが不正です。 |
59 | 指定されたファイルは既に存在します。 |
104 | トランザクショナル インターフェイスがロケールを認識しません。 |
105 | このファイルは、可変長部割り当てテーブル（VAT）付きで作成することはできません。 |
134 | トランザクショナル インターフェイスがインターナショナル ソート規則（ISR）を読み取れません。 |
135 | 指定されたインターナショナル ソート規則（ISR）テーブルは破損しているか、または不正です。 |
ポジショニング
Create オペレーションを実行しても、ファイルにカレンシーは確立しません。
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：キー長が不正です。を参照してください。
•新しいキーのキー フラグ、位置および長さが、キーを追加しようとしているファイルに対して適切であることを確認します。
•トランザクションが実行中でないことが必要です。
手順
1 オペレーション コードに 31 を設定します。
2 キーを追加するファイルのポジション ブロックを渡します。
3 キーの各セグメントについて、16 バイトのキー仕様ブロックをデータ バッファーに格納します。表
8 で定義されているものと同じ構造体を使用します。キー ポジションおよびキー長の情報は整数で格納します。システム定義のログ キー（システム データとも言います）を再構築している場合、データ バッファーは少なくとも 16 バイトの長さで、ゼロに初期化されている必要があります。
4 新しいキーに 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 テーブル名 |
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 オペレーションが正常に終了した場合、新しいキーの番号は指定した番号になるか、または次のいずれかになります。
•キー番号が飛んでいないファイルの場合は、新しいキー番号は以前の最大のキー番号より 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 オペレーションは、ファイルのカレンシー情報にまったく影響しません。
Delete（4）
Delete オペレーション（B_DELETE）では、ファイルから既存のレコードを削除します。削除したレコードが占有していたスペースは、新しいレコードを挿入するために再利用されます。
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
前提条件
•対象となるファイルが開いていることが必要です。
•対象となるファイルの物理カレンシーまたは論理カレンシーを確立しておくことが必要です。この要件を満たすオペレーションには次のものがあります。Get、Step、Insert および Update オペレーションです。ただし、Get ... Extended、Get Key、Step ... Extended は除きます。
手順
1 オペレーション コードに 4 を設定します。
2 削除するレコードを含むファイルのポジション ブロックを渡します。
詳細
Delete オペレーションを Extended Get または Extended Step オペレーションの直後に実行した場合、これは有効なオペレーションになりません。
Get オペレーションの直後に Delete オペレーションを実行する場合は、Get オペレーションから返されるキー番号を変更しないでください。変更してしまうと、レコードはトランザクショナル インターフェイスで正常に削除されますが、レコード削除後に実行する最初の Get オペレーションでステータス コード 7 が返されます。
トランザクショナル インターフェイスでは、Get Key オペレーション（+50）の後に Delete オペレーションを実行することはできません。トランザクショナル インターフェイスで Delete オペレーションを実行する前に、変更しようとしているデータ ページの現在の使用回数と、レコードを読み取った時点のデータ ページの使用回数が比較されます。使用回数を取得するには、トランザクショナル インターフェイスがデータ ページを読み取る必要があります。
Get Key オペレーションではデータ ページを読み取らないので、Delete オペレーションで比較するための使用回数が利用可能になりません。トランザクショナル インターフェイスでは、比較なしにパッシブ並行制御の矛盾チェックを実行できないため、Delete オペレーションは正常に実行されません。Delete オペレーションが正常に実行されないと、トランザクショナル インターフェイスからステータス コード 8 が返されます。
結果
Delete オペレーションが正常に終了した場合は、トランザクショナル インターフェイスによってファイルからレコードが削除され、削除したレコードにロックが設定されていた場合はそのロックが解除され、さらに削除の結果を反映して、すべてのキー インデックスを調整されます。
Delete オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。
8 | 現在のポジションが不正です。 |
80 | トランザクショナル インターフェイスでレコード レベルの矛盾が発生しました。 |
84 | レコードまたはページがロックされています。 |
85 | ファイルはロックされています。 |
Delete オペレーションを実行してもファイル サイズは小さくなりません。レコードの削除によって生じる空き領域は、今後レコードを追加するときに再利用されます。ディスク容量を回復するには、ファイルを再作成して、そのファイルにすべてのレコードを挿入するしかありません。
ポジショニング
Delete オペレーションを実行すると、すべての物理位置情報と現在のレコードの論理位置は消去されますが、次のレコードまたは前のレコードの論理位置は変わりません。
Drop Index（32）
Drop Index オペレーション（B_DROP_INDEX）では、既存のファイルからキーを削除します。
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
前提条件
•対象となるファイルが開いていることが必要です。
•ファイル内にキーが存在していることが必要です。
•トランザクションが実行中でないことが必要です。
手順
1 オペレーション コードに 32 を設定します。
2 削除するキーを含むファイルのポジション ブロックを渡します。
3 キー番号パラメーターに削除するキーの番号を格納します。システム定義のログ キー（システム データとも言います）を削除するには、125 を指定します。
詳細
システム定義のログ キーを削除した場合、Create Index（31）オペレーションを使ってそれを再構築することができます。
キーを削除すると、トランザクショナル インターフェイスでは特に指定がなければ、削除したキーよりもキー番号の大きなキーはすべて自動的に番号が付け替えられます。トランザクショナル インターフェイスでは、削除したキーよりもキー番号の大きなキーは、番号が 1 ずつ小さくなります。たとえば、キー番号 1、4、および 7 を含むファイルがあるとします。キー 4 を削除すると、トランザクショナル インターフェイスでは残ったキーの番号が 1 と 6 に付け替えられます。
トランザクショナル インターフェイスによってキー番号を自動的に付け替えられたくない場合は、128 というバイアスをキー番号パラメーターに入れる値に加算します。これにより、キー番号は飛んだままにしておくことができ、その結果、ファイル内のほかのキー番号に影響を及ぼすことなく、壊れたインデックスを削除し、そのインデックスを作成し直すことができます。インデックスを再構築するには、Create Index オペレーション（31）を使います。このオペレーションではキー番号を指定できます。
ただし、キーを削除し、それよりキー番号の大きなキーの番号を付け替えなかった場合、その後でユーザーが具体的なキー番号を割り当てずに影響を受けたファイルを複製すると、複製したファイルには元のファイルとは別のキー番号が割り当てられます。（ユーザーは Btrieve Maintenance ユーティリティを使ってファイルを複製できます。複製とは、ある既存のファイルと同じ統計情報を使って新しい空のファイルを作成する処理です。）
結果
Drop Index オペレーションが正常に終了した場合、指定したインデックスはトランザクショナル インターフェイスによって削除され、そのインデックスに割り当てられていたページは、今後の使用のために空き領域のリストに配置されます。また、特に指定しなければ、トランザクショナル インターフェイスでは削除したキーよりもキー番号の大きなキーの番号が付け替えられます。
Drop Index オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。
6 | キー番号パラメーターが不正です。 |
41 | 実行しようとした操作はトランザクショナル インターフェイスでは許可されていません。 |
トランザクショナル インターフェイスがインデックスを削除中に処理が中断されても、ファイルのほかのキーを使ってファイルのデータにアクセスすることはできます。しかし、不完全なインデックスを使ってファイルにアクセスしようとすると、トランザクショナル インターフェイスからステータス コード 56 が返されます。処理が中断された場合は、Drop Index オペレーションを再発行してください。
ポジショニング
Drop Index オペレーションは、ファイルの物理カレンシー情報にはまったく影響しません。ただし、直前に論理カレンシーを確立するために使用したキーを削除すると、論理カレンシーは消去されます。
End Transaction（20）
End Transaction オペレーション（B_END_TRAN）では、トランザクションを終了し、データ ファイルに適切な変更を加えます。また、トランザクションによって設定されたすべてのファイルとレコードのロックを解除します。
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
前提条件
End Transaction オペレーションを発行する前に、Begin Transaction オペレーション（19 または 1019）が正常に終了している必要があります。
手順
オペレーション コードに 20 を設定します。トランザクショナル インターフェイスでは、オペレーション コード以外の End Transaction 呼び出しパラメーターはすべて無視されますが、将来のリリースとの互換性を確保するために 0 に初期化してください。
結果
End Transaction オペレーションが正常に終了した場合は、トランザクション内で実行されたすべてのオペレーションの結果がファイルに保存されます。End Transaction オペレーションを実行した後でトランザクションを中止することはできません。
End Transaction オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから次のステータス コードが返されます。
38 | トランザクショナル インターフェイスで、トランザクション制御ファイル 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 を使って、キー パスを基準に対応するパーセンテージをシークする場合は、データ バッファー パラメーターに値を入力する必要はありません。ファイル内でのレコードの物理位置を基準に対応するパーセンテージをシークする場合は、キー バッファー パラメーターに値を入力する必要はありません。
前提条件
•対象となるファイルが開いていることが必要です。
•キー パスに基づいてパーセンテージをシークする場合は、対象となるファイルがデータオンリー ファイルであってはいけません。
•ファイル内のレコードの物理位置に基づいてパーセンテージをシークする場合は、そのレコードの 4 バイト物理位置をデータ バッファー パラメーターに指定する必要があります。この値は、Get Position オペレーション（22）を使って取得できます。
手順
1 オペレーション コードに 45 を設定します。
2 ファイルのポジション ブロックを渡します。
3 ファイル内のレコードの物理位置を基準にパーセンテージをシークする場合は、レコードの物理アドレスをデータ バッファー パラメーターに格納します。レコードのキー パスを基準にパーセンテージをシークし、その検索に精度を指定する場合は、
精度で指定されているようにデータ バッファー パラメーターを設定します。それ以外の場合は、データ バッファー パラメーターに値を入れる必要はありません。
4 データ バッファー長に最小値である 4 バイトを設定します（この 4 バイトという最小長は、トランザクショナル インターフェイスの内部的な実装に必要とされます）。検索に精度を設定する場合は、データ バッファー長を最小値の 12 バイトに設定します。
5 キー パスを基準にパーセンテージをシークする場合は、キー値をキー バッファー パラメーターに設定します。それ以外の場合は、キー バッファー パラメーターに値を入れる必要はありません。
6 キー番号パラメーターを以下のとおりに設定します。
a. キー パスによってパーセンテージをシークする場合は、キー番号パラメーターに実際のキー番号を設定します。
b. レコードの物理位置によってパーセンテージをシークする場合は、キー番号パラメーターに -1（0xFF）を設定します。
詳細
Find Percentage オペレーションは、特にスクロール バーの実装をサポートする目的で用意されています。このオペレーションの精度、つまり、返されたパーセンテージ値がレコードまたはキー値の位置をどれだけ精確に反映しているかどうかは、さまざまな要因によって影響を受けます。このため、スクロール バーの実装以外の目的で使用する場合は、このオペレーションの精度を信頼しないでください。
Find Percentage オペレーションを最適化するため、トランザクショナル インターフェイスでは、ファイルのレコードはデータ ページ間に、キーはインデックス ページ間に均等に分布していることを前提としています。ただし、分布状態は次のような状況によって影響を受けます。
•ファイルがインデックス バランスを使用しておらず、同一範囲内のキーで多数のレコードが削除されている。
•同一範囲内の物理アドレスで多数のレコードが削除されている。
•ファイルに多数の重複するキー値が含まれており、そのキーがリンク重複キーになっている。
精度
精度の設定はオプションで、パーセンテージを測定する要素を選択することができます。Pervasive PSQL 9 より前のリリースでは、この値は常に 10,000 でした。
精度を指定する場合は、以下の手順に従ってください。
►Find Percentage オペレーションの精度を指定するには
1 データ バッファーの 2 番目の 4 バイトに ExPc を設定します。
2 3 番目の 4 バイトに希望する精度を LoHi Intel 整数で指定します。選択できる精度は、1 から 0xFFFFFFFF までの数値です。
3 データ バッファー長が少なくとも 12 バイトあることを確認してください。
たとえば、365 件のレコードが入っているファイルから 100 番目のレコードを取得したい場合、パーセンテージに 100、精度に 365 を使用して FindPercentage を実行することができます。
結果
Find Percentage オペレーションが正常に終了した場合は、トランザクショナル インターフェイスによって、指定したキー値またはレコードの相対位置がデータ バッファーに返されます。この位置は、キー パスまたはファイルにおけるオフセットのパーセンテージとして表され、0（0 %）から 10,000（100.00%）までの範囲の値になります。これは、物理位置でも論理位置でもないので注意してください。
パーセンテージ値は、下位バイト、上位バイトの順の 2 バイト整数として返されます。たとえば、次のようになります。
16 進数の戻り値 | 10 進数の戻り値 | キー パスまたはファイル内でのパーセンテージ |
88h 13h | 00 50 | 50% |
また、オペレーションが正常に終了した場合には、トランザクショナル インターフェイスからデータ バッファー長に 4 が返されます。
Find Percentage オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。
3 | ファイルが開いていません。 |
6 | キー番号パラメーターが不正です。 |
7 | キー番号が変更されました。 |
8 | 現在のポジションが不正です。 |
9 | オペレーションが EOF（end-of-file）を検出しました。 |
22 | データ バッファー パラメーターが短すぎます。 |
41 | 実行しようとした操作はトランザクショナル インターフェイスでは許可されていません。 |
43 | 指定されたレコード アドレスが不正です。 |
82 | トランザクショナル インターフェイスがポジショニングを失いました。 |
ポジショニング
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 - 複数レコード ノーウェイト ロック
ロックの詳細については、『Pervasive PSQL Programmer's Guide』を参照してください。
2 ファイルのポジション ブロックを渡します。
3 パーセンテージの値を 2 バイト整数でデータ バッファーに格納します。パーセンテージ値の許容範囲および関連情報については、「詳細」を参照してください。
4 データ バッファー長に、返される可能性のある最大レコード長以上の値を設定します（トランザクショナル インターフェイスの内部的な実装は、データ バッファー長に最小値の 4 バイトが設定されていることを必要とします）。検索に精度を設定する場合は、データ バッファー長を最小値の 12 バイトに設定します。
5 キー番号パラメーターを設定します。
a. キー パスによってレコードをシークする場合は、キー番号パラメーターに実際のキー番号を設定します。システム定義のログ キー（システム データ）を使用するには、125 を指定します。
b. ファイル内のレコードの物理位置によってレコードをシークする場合は、キー番号パラメーターに -1（0xFF）を設定します。
詳細
精度を指定しない場合（
精度 を参照）、データ バッファー パラメーターの最初の 2 バイトに対するパーセンテージ値の許容範囲は、0（キー パスまたはファイルの先頭を表します）から 10,000（キー パスまたはファイルの末尾を表します）までです。この値は、小数点以下 2 桁を含むものとして、0% から 100.00% の範囲に対応しています。ファイル中の 33.33% あたりにあるレコードを検索する場合は、データ バッファーに値 3333 を渡します。値は、下位バイト、上位バイトの順の整数として格納してください。たとえば、ファイル内の 50% の地点をシークするには、5,000（0x1388）という値を使います。0x1388 の下位バイトと上位バイトを入れ替え、0x88 と 0x13 をデータ バッファー パラメーターの先頭の 2 バイトに格納します。
レコードのキー パスを基準にパーセンテージをシークし、その検索に精度を指定する場合は、
精度で指定されているようにデータ バッファー パラメーターを設定します。
Get By Percentage オペレーションは、特にスクロール バーの実装をサポートする目的で用意されています。このオペレーションの精度、つまり、返されたレコードがファイル内の指定したパーセンテージ地点に実際に位置しているかどうかは、さまざまな要因によって影響を受けます。このため、スクロール バーの実装以外の目的で使用する場合は、このオペレーションの精度を信頼しないでください。
Get By Percentage オペレーションを最適化するため、トランザクショナル インターフェイスでは、ファイルのレコードはデータ ページ間に、キーはインデックス ページ間に均等に分布していることを前提としています。ただし、分布状態は次のような状況によって影響を受けます。
•ファイルがインデックス バランスを使用しておらず、同一範囲内のキーで多数のレコードが削除されている。
•同一範囲内の物理アドレスで多数のレコードが削除されている。
•ファイルに多数の重複するキー値が含まれており、そのキーがリンク重複キーになっている。
精度
精度の設定はオプションで、パーセンテージを測定する要素を選択することができます。Pervasive PSQL 9 より前のリリースでは、この値は常に 10,000 でした。
精度を指定する場合は、以下の手順に従ってください。
►Get By Percentage オペレーションの精度を指定するには
1 データ バッファーの 2 番目の 4 バイトに ExPc を設定します。
2 3 番目の 4 バイトに希望する精度を LoHi Intel 整数で指定します。選択できる精度は、1 から 0xFFFFFFFF までの数値です。
3 データ バッファー長が少なくとも 12 バイトあることを確認してください。
たとえば、365 件のレコードが入っているファイルから 100 番目のレコードを取得したい場合、パーセンテージに 100、精度に 365 を使用して GetByPercentage を実行することができます。
結果
Get By Percentage オペレーションが正常に終了した場合は、トランザクショナル インターフェイスによって、指定したキー パスを基準とする位置またはファイル内の物理位置にあるレコードがデータ バッファーに返されます。さらにトランザクショナル インターフェイスからは、データ バッファー長パラメーターにレコード長がバイト単位で返されます。キー パスによってレコードをシークした場合は、トランザクショナル インターフェイスからキー バッファー パラメーターに指定したキー パスのキー値が返されます。物理レコード順によってレコードをシークした場合は、トランザクショナル インターフェイスからキー バッファー パラメーターには何の情報も返されません。
メモ： Get By Percentage オペレーションでキー パスを基準としてレコードをシークした場合、そのキーに重複値が含まれているときは、トランザクショナル インターフェイスでは常に重複値を含む先頭のレコードが返されます。このような実装の細部によって、オペレーションの精度が影響を受ける場合があります。
Get By Percentage オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。
3 | ファイルが開いていません。 |
6 | キー番号パラメーターが不正です。 |
7 | キー番号が変更されました。 |
8 | 現在のポジションが不正です。 |
9 | オペレーションが EOF（end-of-file）を検出しました。 |
22 | データ バッファー パラメーターが短すぎます。 |
41 | 実行しようとした操作はトランザクショナル インターフェイスでは許可されていません。 |
43 | 指定されたレコード アドレスが不正です。 |
82 | トランザクショナル インターフェイスがポジショニングを失いました。 |
ポジショニング
指定したキー パスを基準としてレコードをシークするとき、Get By Percentage オペレーションが正常に終了した場合は、指定したキー番号と取得したレコードのそれぞれに基づいて新しい論理カレンシーおよび物理カレンシーが確立されます。
ファイル内のレコードの物理位置を基準としてレコードをシークするとき、Get By Percentage オペレーションが正常に終了した場合は、取得したレコードに基づいて新しい物理カレンシーが確立されます。
Get By Percentage オペレーションが正常に実行されなかった場合、トランザクショナル インターフェイスではカレンシーは変更されません。
Get Direct/Chunk（23）
Get Direct/Chunk オペレーション（B_GET_DIRECT）では、チャンクと呼ばれるレコードの部分を 1 つまたは複数取得できます。このオペレーションは、65,535 バイトより長いレコードを含むファイルで特に役に立ちます。データ バッファー パラメーターの長さには制限があるため、このようなレコードは長すぎて、ほかの Get および Step オペレーションでは取得できません。アプリケーションでは、物理アドレスを指定することで、チャンクが取得されるレコードを指定します。通常、レコード内でのチャンクの位置は、そのオフセットと長さで指定されます。
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
前提条件
•対象となるファイルが開いていることが必要です。
•4 バイトから成るレコードの物理位置を用意する必要があります。この値は、Get Position オペレーション（22）を使って取得できます。
•Get Direct/Chunk オペレーションから返されるすべての値を格納するのに十分な大きさのデータ バッファーを用意する必要があります。また、Get Direct/Chunk オペレーションが間接チャンク オペレーションを実行するとき、データ バッファーにはチャンク ディスクリプター全体（すべてのチャンク定義）を格納できなければなりません。データ バッファーの最大サイズは、表
18 に示すように制限されています。
表 18 環境によるデータ バッファー サイズの制限
環境 | 最大データ バッファー サイズ |
サーバーまたはワークステーション エンジンへのローカル呼び出し | 64,512 バイト |
DOS リクエスター（BREQNT）を経由したリモート呼び出し | 55,512 バイト |
Windows または Linux リクエスターを経由したリモート呼び出し | 65,153 バイト |
手順
1 オペレーション コードに 23 を設定します。オプションで、ロック バイアスも指定できます。
•+100 - 単一レコード ウェイト ロック
•+200 - 単一レコード ノーウェイト ロック
•+300 - 複数レコード ウェイト ロック
•+400 - 複数レコード ノーウェイト ロック
ロックの詳細については、『Pervasive PSQL Programmer's Guide』を参照してください。
2 ファイルのポジション ブロックを渡します。
3 詳細の説明に従って、データ バッファーを指定します。
4 データ バッファー長に、入力構造体の長さ（表
19 または表
20）とトランザクショナル インターフェイスに取得するように要求したバイト数の、どちらか大きい方を指定します。
Get Direct/Chunk オペレーションの一部のオプションでは、データ バッファー以外の場所にチャンクを取得します。データ バッファー長を計算する方法については、
詳細を参照してください。
5 キー番号パラメーターに -2（0xFE）を設定します。
詳細
データ バッファーでは、次のチャンク ディスクリプターのいずれかを使用します。
•ランダム チャンク ディスクリプター - オペレーションに付き 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 |
ランダム チャンクを取り出すには、次の表に基づいてデータ バッファー内に構造体を作成する必要があります。
表 19 ランダム チャンク オペレーションのデータ バッファー
要素 | 長さ（バイト単位） | 説明 |
レコード アドレス | 4 | レコードの 4 バイト物理アドレス。この値は、Get Position オペレーション（22）を使って取得できます。 |
ランダム チャンク ディスクリプター |
サブファンクション | 4 | チャンク ディスクリプターの種類。次のいずれかを指定します。 •0x80000000（直接ランダム チャンク ディスクリプター） - チャンクを直接データ バッファーに取得します。1 つ目のチャンクが取得されるとデータ バッファーのオフセット 0 に格納され、2 つ目のチャンクが 1 つ目のチャンクの直後に続き、と以下同様に続きます。 •0x80000001（間接ランダム チャンク ディスクリプター） - チャンクをチャンク定義によって指定されるアドレス内に取得します。 |
チャンク数 | 4 | 取得するチャンク数。この値は少なくとも 1 以上であることが必要です。明確な最大値はありませんが、チャンク ディスクリプターはデータ バッファーに収まらなければなりません。データ バッファーのサイズは、表 18 の説明のとおり制限されています。 |
チャンク定義
（各チャンクについて繰り返す） | 12（32 ビット アプリケーション用） 16（64 ビット アプリケーション用） | 各チャンク定義は、以下に示すように、4 バイトのチャンク オフセット、それに続く 4 バイトのチャンク長、さらに 32 ビット アプリケーションの場合は 4 バイトのユーザー データ、または 64 ビット アプリケーションの場合は 8 バイトのユーザー データから構成されます。 •チャンク オフセット - チャンクの開始地点を、レコードの先頭からのオフセット（バイト単位）で示します。最小値は 0、最大値はレコードの末尾のバイトのオフセットです。 •チャンク長 - チャンク内のバイト数を示します。最小値は 0、最大値は 65,535 です。ただし、チャンク ディスクリプターはデータ バッファーに収まらなければなりません。データ バッファーのサイズは、表 18 の説明のとおり制限されています。 •ユーザー データ - （間接ディスクリプターでのみ使用します。）32 ビット アプリケーションの場合、実際のチャンク データへの 32 ビット ポインターです。64 ビット アプリケーションの場合、実際のチャンク データへの 64 ビット ポインターです。使用すべき形式は、オペレーティング システムによって異なります。1 直接チャンク ディスクリプターのサブファンクションの場合、トランザクショナル インターフェイスではこの要素は無視されます。 |
1 DOS アプリケーションの場合、ユーザー データは 16 ビット オフセットおよび 16 ビット セグメントとして初期化してください。ユーザー データでは、そのセグメントの最後を越えてメモリをアドレス指定することはできません。チャンク長をユーザー データのオフセット部分に加算したとき、その結果は、ユーザー データによって定義されるセグメントの範囲内でなければなりません。デフォルトで、トランザクショナル インターフェイスではこの規則に対する違反はチェックされず、このような違反は適切に処理されません。 |
次の表は、直接ランダム チャンクを取り出す場合の 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 つのチャンクをすべて取得できます。矩形チャンクを取り出すには、次の表に基づいてデータ バッファー内に構造体を作成する必要があります。
表 20 矩形チャンクのデータ バッファー
要素 | 長さ（バイト単位） | 説明 |
レコード アドレス | 4 | レコードの 4 バイト物理アドレス。この値は、Get Position オペレーション（22）を使って取得できます。 |
矩形チャンク ディスクリプター |
サブファンクション | 4 | チャンク ディスクリプターの種類。次のいずれかを指定します。 •0x80000002（直接矩形チャンク ディスクリプター） - チャンクを直接データ バッファーに取得します。1 つ目のチャンクが取得されるとデータ バッファーのオフセット 0 に格納され、2 つ目のチャンクが 1 つ目のチャンクの直後に続き、と以下同様に続きます。 •0x80000003（間接矩形チャンク ディスクリプター） - チャンクをユーザー データ要素およびアプリケーションの行間隔要素によって指定されるアドレス内に取得します。 |
行数 | 4 | 矩形チャンク ディスクリプターの操作対象とするチャンク数。最小値は 1 です。明確な最大値はありません。 |
位置（オフセット） | 4 | 取得する最初のバイトの、レコードの先頭からのオフセット。最小値は 0、最大値はレコードの末尾のバイトのオフセットです。レコードが 1 つの矩形として表される場合、この要素は、取得される先頭行にある先頭バイトのオフセットを指します。 |
行のバイト数 | 4 | 各チャンクで取得するバイト数。最小値は 0、最大値は 65,535 です。ただし、チャンク ディスクリプターはデータ バッファーに収まらなければなりません。データ バッファーのサイズは、表 18 の説明のとおり制限されています。 |
行間隔 | 4 | チャンクの先頭から次のチャンクの先頭までのバイト数。 |
ユーザー データ | 4（32 ビット アプリケーション用） 8（64 ビット アプリケーション用） | （間接ディスクリプターでのみ使用します。）32 ビット アプリケーションの場合、トランザクショナル インターフェイスが各行からバイトを取得した後でそれらを格納する場所への 32 ビット ポインター。64 ビット アプリケーションの場合、トランザクショナル インターフェイスが各行からバイトを取得した後でそれらを格納する場所への 64 ビット ポインター。 使用すべき形式は、オペレーティング システムによって異なります。1 直接矩形ディスクリプターの場合、トランザクショナル インターフェイスではこの要素は無視されます。ただしそれでも、この要素を割り当て、0 に初期化しておく必要があります。 |
アプリケーションの行間隔 | 4 | （間接矩形ディスクリプターでのみ使用します。）矩形がアプリケーションのメモリ（つまり、ユーザー データで指定したアドレス）に格納されるときの、矩形内のチャンクの先頭から次のチャンクの先頭までのバイト数。直接矩形ディスクリプターの場合、トランザクショナル インターフェイスではこの要素は無視されます。ただしそれでも、この要素を割り当て、0 に初期化しておく必要があります。 |
1 DOS アプリケーションの場合、ユーザー データは 16 ビット オフセットとそれに続く 16 ビット セグメントで表してください。 |
間接矩形ディスクリプターを使用するときは、取得されたチャンクがチャンク ディスクリプターを上書きしないように、ユーザー データ ポインターが初期化されていることを確認してください。トランザクショナル インターフェイスは、返されたチャンクをユーザー データ要素が示す場所にコピーするとき、ディスクリプターを使用します。チャンク ディスクリプターを上書きしてしまった場合は、トランザクショナル インターフェイスからステータス コード 62 が返されます。
矩形がメモリ内にあるとき、各行の間隔がレコードとして格納されているときと同じバイト数になる場合は、アプリケーションの行間隔に行間隔と同じ値を設定します。しかし、矩形がアプリケーションのメモリ内で再配置され、行の間隔が何バイトか増減する場合は、アプリケーションの行間隔により、その情報をトランザクショナル インターフェイスに渡すことができます。
間接矩形ディスクリプターを使用するときは、トランザクショナル インターフェイスはユーザー データ要素およびアプリケーションの行間隔要素を使って、取得後のデータの格納場所を決定します。トランザクショナル インターフェイスでは 1 行目のデータはユーザー データのオフセット 0 に格納されます。トランザクショナル インターフェイスでは 2 行目のデータは、ユーザー データ + アプリケーションの行間隔で指定されるアドレスに格納されます。トランザクショナル インターフェイスでは 3 行目のデータは、ユーザー データ + (アプリケーションの行間隔 * 2) で指定されるアドレスに格納され、以下同様です。
次の表は、直接矩形チャンクを取り出す場合の 32 ビット アプリケーション用データ バッファーの例を示しています。
要素名 | サンプル値 | 長さ（バイト単位） |
レコード アドレス | 0x00000628 | 4 |
サブファンクション | 0x80000002 | 4 |
行数 | 3 | 4 |
位置（オフセット） | 25 | 4 |
行のバイト数 | 4 | 4 |
行間隔 | 16 | 4 |
ユーザー データ | 0 | 4 |
アプリケーションの行間隔 | 0 | 4 |
ネクストインレコード サブファンクション バイアス
これまでに述べたサブファンクションの値にバイアス 0x40000000 を加算すると、トランザクショナル インターフェイスではレコード内の物理カレンシー（つまり、レコード内の現在の物理位置）に基づいてサブファンクションのオフセット要素の値が算出されます。ネクストインレコード サブファンクションを使用する場合、トランザクショナル インターフェイスではチャンク ディスクリプターのオフセット要素は無視されます。
結果
Get Direct/Chunk オペレーションが正常に終了した場合、トランザクショナル インターフェイスでは直接チャンク ディスクリプターを使用しているときは、データ バッファーにチャンクが順に返されます。間接ランダム チャンク ディスクリプターを使用しているとき、トランザクショナル インターフェイスでは各チャンクのユーザー データ要素で指定した場所にデータが返されます。また、間接矩形ディスクリプターを使用しているとき、トランザクショナル インターフェイスではユーザー データ要素およびアプリケーションの行間隔要素から計算される場所にデータが返されます。
さらにトランザクショナル インターフェイスから、データ バッファー長パラメーターには、取得されたチャンクの長さの総計が格納されます（この戻り値は、チャンクが取得されて直接データ バッファーに格納されたか、間接ディスクリプターによってチャンクが取得され別の場所に格納されたかどうかに関係なく、取得された全バイト数を反映しています）。オペレーションが部分的にしか正常に実行されなかった場合、アプリケーションではデータ バッファー長パラメーターに返された値を使って、どのチャンクが取得されなかったか、また最後のチャンクの何バイトまでが取得されたかを調べることができます。
いずれかのチャンクで、開始位置がレコードの末尾を超えてしまう場合（結果として、トランザクショナル インターフェイスからステータス コード 103 が返されます）、またはチャンクのオフセットと長さの合計がレコード長を超えてしまう場合には、Get Direct/Chunk オペレーションの一部だけが正常に実行されます。後者の場合はトランザクショナル インターフェイスからステータス コード 0 が返されますが、このオペレーションに後続のチャンクがある場合、その処理は中止されます。
メモ： すべてのチャンクが適切に取得されたかどうかを知らせるものは、データ バッファー長パラメーターだけです。このため、Get Direct/Chunk オペレーションの実行後は、必ずデータ バッファー長パラメーターに返された値をチェックしてください。
次のステータス コードは、Get Direct/Chunk オペレーションの一部だけが実行されたことを示します。トランザクショナル インターフェイスからこれらのステータス コードのいずれかが返された場合は、アプリケーションでデータ バッファー長パラメーターの戻り値を調べて、トランザクショナル インターフェイスから実際に返されたデータ量を確認する必要があります。
22 | データ バッファー パラメーターが短すぎます。 |
54 | レコードの可変長部分が破損しています。 |
103 | チャンク オフセットが大きすぎます。 |
トランザクショナル インターフェイスから次のステータス コードが返される場合、データはまったく取得されません。
43 | 指定されたレコード アドレスが不正です。 |
58 | 圧縮バッファー長が短すぎます。 |
62 | ディスクリプターが不正です。 |
97 | データ バッファーが小さすぎます。 |
106 | トランザクショナル インターフェイスは、Get Next Chunk オペレーションを実行できません。 |
ポジショニング
Get Direct/Chunk オペレーションは、論理カレンシーにまったく影響しません。物理カレンシーについては、チャンクが取り出されたレコードが現在の物理レコードになります。
Get Direct/Record（23）
Get Direct/Record オペレーション（B_GET_DIRECT）では、定義されているキー パスではなく、ファイル内の物理位置を使ってレコードを取得します。
以下のような操作を実行する場合は、Get Direct/Record オペレーションを使用してください。
•キー値の代わりに物理位置を使って、より高速にレコードを取得する。
•Get Position オペレーション（22）を使ってレコードの 4 バイト物理位置を取得し、その位置を保存する。それから、カレンシーに影響を与えるほかのオペレーションを実行した後で Get Direct/Record オペレーションを使って、その位置に直接戻る。
•一連の重複レコードの中から 1 つのレコードを取得するとき、その一連のレコードを先頭からすべて読み取りし直すことなく、4 バイトの物理位置を使って取得する。
•現在のキー パスを変更する。Get Position オペレーションに続けて、別のキー番号を使った Get Direct/Record オペレーションを実行すると、別のインデックス パスに現在のレコードのポジショニングが確立します。この後で Get Next オペレーションを実行すると、新しいキー パスに基づいてファイル内の次のレコードが返されます。
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
メモ： データオンリー ファイルで Get Direct/Record オペレーションを実行する場合は、キー番号パラメーターは必要ありません。
前提条件
•対象となるファイルが開いていることが必要です。
•4 バイトから成るレコードの物理位置を用意する必要があります。この値は、Get Position オペレーション（22）を使って取得できます。このオペレーションを実行すると、現在のレコードの物理アドレスが返されます。
手順
1 オペレーション コードに 23 を設定します。オプションで、ロック バイアスも指定できます。
•+100 - 単一レコード ウェイト ロック
•+200 - 単一レコード ノーウェイト ロック
•+300 - 複数レコード ウェイト ロック
•+400 - 複数レコード ノーウェイト ロック
ロックの詳細については、『Pervasive PSQL Programmer's Guide』を参照してください。
2 ファイルのポジション ブロックを渡します。
3 データ バッファーの先頭の 4 バイトに、目的のレコードの位置を表す 4 バイト値を格納します。
4 データ バッファー長に取得するレコードの長さ以上の値を設定します。
5 キー番号には、トランザクショナル インターフェイスで論理カレンシーを確立するパスのキー番号を設定します。トランザクショナル インターフェイスで論理カレンシーの確立を必要としない場合は、-1 を指定します。システム定義のログ キー（システム データ）を使用するには、125 を指定します。
結果
Get Direct/Record オペレーションが正常に終了した場合、トランザクショナル インターフェイスでは要求したレコードがデータ バッファーに、レコード長がデータ バッファー長に、指定したキー パスのキー値がキー バッファーにそれぞれ返されます。
Get Direct/Record オペレーションが正常に実行されず、要求したレコードをトランザクショナル インターフェイスが取得できなかった場合は、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。
22 | データ バッファー パラメーターが短すぎます。（論理カレンシーはまだ確立されています） |
43 | 指定されたレコード アドレスが不正です。（論理カレンシーは確立されていません） |
44 | 指定されたキー パスが不正です。（論理カレンシーは確立されていません） |
82 | トランザクショナル インターフェイスがポジショニングを失いました。（論理カレンシーは確立されていません） |
ポジショニング
Get Direct/Record オペレーションを実行すると、既存の論理カレンシー情報が消去され、指定したキー番号に従って新しい論理カレンシーが確立されます。物理カレンシー情報にはまったく影響しません。
Get Directory（18）
Get Directory オペレーション（B_GET_DIR）では、指定された論理ディスク ドライブの現在のディレクトリを返します。
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
前提条件
Get Directory オペレーションはいつでも発行することができます。キー バッファーには少なくとも 65 文字の長さが必要です。
手順
1 オペレーション コードに 18 を設定します。
2 キー番号パラメーターに論理ディスク ドライブ番号を格納します。ドライブは、A の場合は 1、B の場合は 2、というように指定します。デフォルトのドライブを使用するには 0 を指定します。
結果
トランザクショナル インターフェイスでは、オペレーションが正常に終了した場合、バイナリ 0 で終端する現在のディレクトリがキー バッファーに返されます。
ポジショニング
Get Directory オペレーションは、ファイルのカレンシー情報にはまったく影響しません。
Get Equal（5）
Get Equal オペレーション（B_GET_EQUAL）では、キー バッファーに指定されたキー値と等しいキー値を持つレコードを取得します。キーの重複が可能な場合は、同じキー値を持つグループの中で先頭のレコード（作成順）が取得されます。
Get Key（+50）バイアスを使うと、ファイル内に値が存在するかどうかを検出することもできます。一般に、Get Key オペレーションの方が高速に処理されます。
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
前提条件
•対象となるファイルが開いていることが必要です。
•ファイルがデータオンリー ファイルであってはいけません。
手順
1 オペレーション コードに 5 を設定します。オプションで、ロック バイアスも指定できます。
•+100 - 単一レコード ウェイト ロック
•+200 - 単一レコード ノーウェイト ロック
•+300 - 複数レコード ウェイト ロック
•+400 - 複数レコード ノーウェイト ロック
ロックの詳細については、『Pervasive PSQL Programmer's Guide』を参照してください。
2 ファイルのポジション ブロックを渡します。
3 データ バッファー長に取得するレコードの長さ以上の値を設定します。
4 キー バッファーに目的のキー値を指定します。キーが複数のセグメントから成る場合は、必ずすべてのセグメントを記述し、それらすべてに値を設定するようキー バッファーを定義してください。すべてのセグメントについて検索条件を設定しない場合は、代わりに Get Greater Than Or Equal オペレーションを使用してください。
5 キー番号に正しいキー パスを設定します。システム定義のログ キー（システム データ）を使用するには、125 を指定します。
結果
Get Equal オペレーションが正常に終了した場合は、トランザクショナル インターフェイスでは要求したレコードがデータ バッファーに、そのレコードの長さがデータ バッファー長に返されます。
Get Equal オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。
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 - 複数レコード ノーウェイト ロック
ロックの詳細については、『Pervasive PSQL Programmer's Guide』を参照してください。
2 ファイルのポジション ブロックを渡します。
3 データ バッファー長に取得するレコードの長さ以上の値を設定します。
4 キー番号にキー パスを設定します。システム定義のログ キー（システム データ）を使用するには、125 を指定します。
結果
Get First オペレーションが正常に終了した場合は、トランザクショナル インターフェイスでは要求したレコードがデータ バッファーに返され、対応するキー値がキー バッファーに格納され、さらにそのレコードの長さがデータ バッファー長に返されます。
Get First オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。
3 | ファイルが開いていません。 |
6 | キー番号パラメーターが不正です。 |
9 | オペレーションが EOF（end-of-file）を検出しました。 |
22 | データ バッファー パラメーターが短すぎます。 |
ポジショニング
Get First オペレーションを実行すると、完全な論理カレンシーおよび物理カレンシーが確立し、取得したレコードが現在のレコードになります。論理位置の直前は、ファイルの先頭よりも前を指すことになります。
Get Greater（8）
Get Greater オペレーション（B_GET_GT）では、キー番号で指定されたフィールドが、キー バッファーの値よりも次に大きな値を含むレコードを取得します。キーの重複が可能な場合は、同じキー値を持つグループの中で先頭のレコード（作成順）が取得されます。
Get Key（+50）バイアスを使うと、ファイル内に値が存在するかどうかを検出することもできます。一般に、Get Key オペレーションの方が高速に処理されます。
メモ： 降順キーで Get Greater オペレーションを実行する場合、「次に大きな値」というのは、実際にはキー バッファーで指定された値よりも小さな値を指すことになります。
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
前提条件
•対象となるファイルが開いていることが必要です。
•ファイルがデータオンリー ファイルであってはいけません。
手順
1 オペレーション コードに 8 を設定します。オプションで、ロック バイアスも指定できます。
•+100 - 単一レコード ウェイト ロック
•+200 - 単一レコード ノーウェイト ロック
•+300 - 複数レコード ウェイト ロック
•+400 - 複数レコード ノーウェイト ロック
ロックの詳細については、『Pervasive PSQL Programmer's Guide』を参照してください。
2 ファイルのポジション ブロックを渡します。
3 データ バッファー長に取得するレコードの長さ以上の値を設定します。
4 キー バッファー パラメーターに目的のキー値を指定します。
5 キー番号パラメーターに正しいキー パスを設定します。システム定義のログ キー（システム データ）を使用するには、125 を指定します。
結果
Get Greater オペレーションが正常に終了した場合、トランザクショナル インターフェイスでは要求したレコードがデータ バッファーに、キー値がキー バッファーに、さらにそのレコードの長さがデータ バッファー長に格納されます。
Get Greater オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。
3 | ファイルが開いていません。 |
6 | キー番号パラメーターが不正です。 |
22 | データ バッファー パラメーターが短すぎます。 |
ポジショニング
Get Greater オペレーションを実行すると、完全な論理カレンシーおよび物理カレンシーが確立し、取得したレコードが現在のレコードになります。
Get Greater Than or Equal（9）
Get Greater Than or Equal オペレーション（B_GET_GE）では、キー番号で指定されたキーが、キー バッファーに指定された値と等しいかそれよりも大きな値を持つレコードを取得します。トランザクショナル インターフェイスではまず、等しいという条件を満たすレコードが検索されます。キーの重複が可能な場合は、同じキー値を持つグループの中で先頭のレコード（作成順）が取得されます。
Get Key（+50）バイアスを使うと、ファイル内に値が存在するかどうかを検出することもできます。一般に、Get Key オペレーションの方が高速に処理されます。
メモ： 降順キーで Get Greater Than or Equal オペレーションを実行する場合、「次に大きな値」というのは、実際にはキー バッファーで指定された値よりも小さな値を指すことになります。
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
前提条件
•対象となるファイルが開いていることが必要です。
•ファイルがデータオンリー ファイルであってはいけません。
手順
1 オペレーション コードに 9 を設定します。オプションで、ロック バイアスも指定できます。
•+100 - 単一レコード ウェイト ロック
•+200 - 単一レコード ノーウェイト ロック
•+300 - 複数レコード ウェイト ロック
•+400 - 複数レコード ノーウェイト ロック
ロックの詳細については、『Pervasive PSQL Programmer's Guide』を参照してください。
2 ファイルのポジション ブロックを渡します。
3 データ バッファー長に取得するレコードの長さ以上の値を設定します。
4 キー バッファー パラメーターにキー値を指定します。
5 キー番号パラメーターに正しいキー パスを設定します。システム定義のログ キー（システム データ）を使用するには、125 を指定します。
結果
Get Greater Than or Equal オペレーションが正常に終了した場合、トランザクショナル インターフェイスでは要求したレコードがデータ バッファーに、キー値がキー バッファーに、さらにそのレコードの長さがデータ バッファー長に格納されます。
Get Greater Than or Equal オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。
3 | ファイルが開いていません。 |
6 | キー番号パラメーターが不正です。 |
22 | データ バッファー パラメーターが短すぎます。 |
ポジショニング
Get Greater Than or Equal オペレーションを実行すると、完全な論理カレンシーおよび物理カレンシーが確立し、取得したレコードが現在のレコードになります。
Get Key（+50）
Get Key バイアスを使用すると、実際にデータ レコードを取得することなく Get オペレーションを実行できます。Get Key を使って、ファイル内にある値が存在するかどうかを検出できます。一般に、Get Key オペレーションは対応する Get オペレーションよりも高速に実行できます。Get Key オペレーションは、以下のいずれかの Get オペレーションと共に使用します。
パラメーター
パラメーターは対応する Get オペレーションと同様です。ただし、トランザクショナル インターフェイスではデータ バッファー長の設定は無視され、データ バッファーにはレコードが返されません。
前提条件
Get Key オペレーションの前提条件は、対応する Get オペレーションの前提条件と同じです。
手順
1 対応する Get オペレーションの場合と同じようにパラメーターを設定します。データ バッファー長を初期化する必要はありません。
2 オペレーション コードには、実行する Get オペレーションのオペレーション コードに 50 を加算した値を設定します。たとえば、Get Equal オペレーション（5）と共に Get Key（+50）を実行するには、オペレーション コードに 55 を設定します。
トランザクショナル インターフェイスでは、Get Key オペレーション（+50）の後に Delete または Update オペレーションを実行することはできません。トランザクショナル インターフェイスで、Delete または Update オペレーションを実行する前に、変更しようとしているデータ ページの現在の使用回数と、レコードを読み取った時点のデータ ページの使用回数が比較されます。使用回数を取得するには、トランザクショナル インターフェイスがデータ ページを読み取る必要があります。
Get Key オペレーションではデータ ページを読み取らないので、Delete または Update オペレーションで比較するための使用回数が利用可能になりません。トランザクショナル インターフェイスでは、比較なしにパッシブ並行制御の矛盾チェックを実行できないため、Update または Delete オペレーションは正常に実行されません。Update または Delete オペレーションが正常に実行されないと、トランザクショナル インターフェイスからステータス コード 8 が返されます。
結果
トランザクショナル インターフェイスで要求したキーが検出されると、そのキー値がキー バッファーに格納され、ステータス コード 0 が返されます。そうでない場合は、トランザクショナル インターフェイスからキー値を検出できなかった理由を示すステータス コードが返されます。
ポジショニング
Get Key オペレーションを実行すると、対応する Get オペレーションと同様の方法で現在のポジショニングが確立されます。ただし、Get Key オペレーションの対象となるキーが重複を許可している場合、トランザクショナル インターフェイスでは取得された現在のキー値の重複インスタンスは無視されます。Get Key オペレーションの実行後、論理位置の直前は次に小さなキー値を含むレコードを指します。また、論理位置の直後は次に大きなキー値を含むレコードを指します。
たとえば、Smith が 8 回と Smythe が 1 回出現する姓のキーを対象に、Get Key を Get Equal オペレーション（55）と共に実行したとします。論理位置の直後は次の Smith ではなく、Smythe を指すことになります。
Get Key オペレーションではどれか 1 つのレコードが識別されるわけではないため、トランザクショナル インターフェイスでは Get Key オペレーションに続けて Update または Delete オペレーションを実行することはできません。
Get Last（13）
Get Last オペレーション（B_GET_LAST）では、指定されたキーに基づいて末尾の論理レコードを取得します。末尾のキー値が重複している場合は、同じキー値を持つグループの中で末尾のレコードが返されます。
Get Key（+50）バイアスを使うと、ファイル内に値が存在するかどうかを検出することもできます。一般に、Get Key オペレーションの方が高速に処理されます。
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
前提条件
•対象となるファイルが開いていることが必要です。
•ファイルがデータオンリー ファイルであってはいけません。
手順
1 オペレーション コードに 13 を設定します。オプションで、ロック バイアスも指定できます。
•+100 - 単一レコード ウェイト ロック
•+200 - 単一レコード ノーウェイト ロック
•+300 - 複数レコード ウェイト ロック
•+400 - 複数レコード ノーウェイト ロック
ロックの詳細については、『Pervasive PSQL Programmer's Guide』を参照してください。
2 ファイルのポジション ブロックを渡します。
3 データ バッファー長に取得するレコードの長さ以上の値を設定します。
4 キー番号にキー パスを設定します。システム定義のログ キー（システム データ）を使用するには、125 を指定します。
結果
Get Last オペレーションが正常に終了した場合、トランザクショナル インターフェイスでは要求したレコードがデータ バッファーに返され、対応するキー値がキー バッファーに格納され、さらにそのレコードの長さがデータ バッファー長に返されます。
Get Last オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。
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 - 複数レコード ノーウェイト ロック
ロックの詳細については、『Pervasive PSQL Programmer's Guide』を参照してください。
2 ファイルのポジション ブロックを渡します。
3 データ バッファー長に取得するレコードの長さ以上の値を設定します。
4 キー バッファー パラメーターに目的のキー値を指定します。
5 キー番号パラメーターにキー パスを設定します。システム定義のログ キー（システム データ）を使用するには、125 を指定します。
結果
Get Less Than オペレーションが正常に終了した場合、トランザクショナル インターフェイスではレコードがデータ バッファーに、そのレコードのキー値がキー バッファーに、さらにそのレコードの長さがデータ バッファー長に返されます。
Get Less Than オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。
3 | ファイルが開いていません。 |
6 | キー番号パラメーターが不正です。 |
22 | データ バッファー パラメーターが短すぎます。 |
ポジショニング
Get Less Than オペレーションを実行すると、完全な論理カレンシーおよび物理カレンシーが確立し、取得したレコードが現在のレコードになります。
Get Less Than or Equal（11）
Get Less Than or Equal オペレーション（B_GET_LE）では、キー番号で指定されたキーが、キー バッファーに指定された値と等しいかそれよりも小さな値を持つレコードを取得します。トランザクショナル インターフェイスではまず、等しいという条件を満たすレコードが検索されます。キーの重複が可能な場合は、同じキー値を持つグループの中で末尾のレコード（作成順）が取得されます。
Get Key（+50）バイアスを使うと、ファイル内に値が存在するかどうかを検出することもできます。一般に、Get Key オペレーションの方が高速に処理されます。
メモ： 降順キーで Get Less Than or Equal オペレーションを実行する場合、「次に小さな値」というのは、実際にはキー バッファーで指定された値よりも大きな値を指すことになります。
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
前提条件
•対象となるファイルが開いていることが必要です。
•ファイルがデータオンリー ファイルであってはいけません。
手順
1 オペレーション コードに 11 を設定します。オプションで、ロック バイアスも指定できます。
•+100 - 単一レコード ウェイト ロック
•+200 - 単一レコード ノーウェイト ロック
•+300 - 複数レコード ウェイト ロック
•+400 - 複数レコード ノーウェイト ロック
ロックの詳細については、『Pervasive PSQL Programmer's Guide』を参照してください。
2 ファイルのポジション ブロックを渡します。
3 データ バッファー長に取得するレコードの長さ以上の値を設定します。
4 キー バッファー パラメーターにキー値を指定します。
5 キー番号パラメーターにキー パスを設定します。システム定義のログ キー（システム データ）を使用するには、125 を指定します。
結果
Get Less Than or Equal オペレーションが正常に終了した場合、トランザクショナル インターフェイスではレコードがデータ バッファーに、そのレコードのキー値がキー バッファーに、さらにそのレコードの長さがデータ バッファー長に返されます。
Get Less Than or Equal オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。
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 - 複数レコード ノーウェイト ロック
ロックの詳細については、『Pervasive PSQL Programmer's Guide』を参照してください。
2 ファイルのポジション ブロックを渡します。
3 データ バッファー長に取得するレコードの長さ以上の値を設定します。
4 キー バッファーに前のオペレーションで取得したキー値を指定します。キー バッファーには、前の呼び出しでトランザクショナル インターフェイスから返されたキー値とまったく同じものを渡します。トランザクショナル インターフェイスでは、ファイル内の現在の位置を決定するために、直前にキー バッファーに格納された情報が必要となるからです。
5 キー番号パラメーターに、前の呼び出しで使用したキー パスを設定します。Get Next オペレーションを使ってキー パスを変更することはできません。
結果
Get Next オペレーションが正常に終了した場合、トランザクショナル インターフェイスではレコードがデータ バッファーに、そのレコードのキー値がキー バッファーに、さらにそのレコードの長さがデータ バッファー長に返されます。
Get Next オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。
3 | ファイルが開いていません。 |
6 | キー番号パラメーターが不正です。 |
7 | キー番号が変更されました。 |
8 | 現在のポジションが不正です。 |
9 | オペレーションが EOF（end-of-file）を検出しました。 |
22 | データ バッファー パラメーターが短すぎます。 |
82 | トランザクショナル インターフェイスがポジショニングを失いました。 |
このオペレーションの実行により、論理位置の直後がファイルの末尾よりも後を指す場合は、ステータス コード 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 - 複数レコード ノーウェイト ロック
ロックの詳細については、『Pervasive PSQL Programmer's Guide』を参照してください。
2 ファイルのポジション ブロックを渡します。
3 入力データ バッファーと戻りデータ バッファーのどちらか大きい方を格納できるように、十分な長さのデータ バッファーを指定します。表
21 に示す構造体に従って、データ バッファーを初期化します。
4 データ バッファー長に、入力構造体（表
21）と戻り構造体（表
22）のどちらか大きい方の長さを指定します。
5 キー バッファーに前のオペレーションで取得したキー値を指定します。キー バッファーには、前の呼び出しでトランザクショナル インターフェイスから返されたキー値とまったく同じものを渡します。トランザクショナル インターフェイスでは、ファイル内の現在の位置を決定するために、直前にキー バッファーに格納された情報が必要となるからです。
6 キー番号パラメーターに、前の呼び出しで使用したキー パスを設定します。Get Next Extended オペレーションを使ってキー パスを変更することはできません。
詳細
次の表は、入力データ バッファーの構造体を示しています。
表 21 Extended Get / Step オペレーションの入力データ バッファー構造体
要素 | 長さ（バイト単位） | 説明 |
ヘッダー | 2 | データ バッファー全体の長さ。 |
2 | 2 つの文字列定数値のいずれかを指定します（固定長で、ヌル終端にしてはいけません）。
"EG" - ポジショニングされているレコードの次のレコードから検索を開始します。
"UC" - ポジショニングされているレコードから検索を開始します。 Step Next Extended オペレーションの場合は、この値には常に "EG" を設定してください。 |
フィルター（固定部分） | 2 | リジェクト カウントの最大数。これは、トランザクショナル インターフェイスでレコードの検索中に、フィルター条件を満たさないものとしてスキップできるレコードの件数です。0 から 65,535 までの範囲の値を指定できます（0 を指定すると、トランザクショナル インターフェイスではシステム定義の最大リジェクト カウント、4,095 が使用されます）。 |
2 | フィルター条件として使用する論理式の項の数。（0 を指定すると、トランザクショナル インターフェイスではフィルター処理が実行されません）。項の数はデータ バッファーのサイズによってのみ制限されます。Pervasive.SQL 2000i SP3 でのみ、項の数が 119 に制限されています。 |
フィルター（論理式の各項について、このセグメントを 1 回繰り返す） | 1 | フィールドのデータ型。表 11 に記載されているコードのいずれかを使用します。 |
2 | フィールド長。 |
2 | フィールドのオフセット（ゼロを基準にした相対的なオフセット）。 |
1 | 比較演算子のコードを指定します。
1 等しい
2 より大きい
3 より小さい
4 等しくない
5 以上
6 以下 ファイルの既存の ACS のいずれかを使って文字列を比較するには、+8 バイアスを加算します。 ファイルのデフォルトの ACS を使って文字列を比較するには、+32 バイアスを加算します。デフォルトの ACS とは、ファイルで定義されている先頭の ACS のことです。+8 バイアスと +32 バイアスの両方を使用すると、+32 バイアスは無視されます。 |
| 2 番目のオペランドが定数ではなく、レコード内の別のフィールドの場合は、+64 バイアスを加算します。 大文字と小文字を区別しないで文字列を比較するには、+128 バイアスを加算します。 |
1 | AND/OR 論理演算子を指定します。
0 - 最後の項を示します。
1 - 次の項を AND で結合します。
2 - 次の項を OR で結合します。 |
2 または n | 2 つのフィールドを比較する場合は、2 バイトの、2 番目のフィールドに対するゼロ基準の相対的なオフセットを指定します（2 番目のフィールドは、同じデータ型かつ同じ長さでなければなりません）。
または
フィールドを定数と比較する場合は、定数の実際の値を指定します。定数の長さ（n）は、フィールドの長さと等しくなければなりません。 |
0、5、9、17 | 名前によって ACS を指定（バイアス +8）するときは、表 12 に示されている名前の形式のいずれかを使って、ACS 識別子を指定します。 |
ディスクリプター（固定部分） | 2 | 取得するレコード数。レコードのセットではなく 1 つのレコードだけを取得するには、1 を指定します。 |
2 | 各レコードから抽出するフィールド数。 |
ディスクリプター（抽出される各フィールドについて、このセグメントを繰り返す） | 2 | 抽出するフィールド長。 |
2 | フィールドのオフセット（ゼロを基準にした相対的なオフセット）。 |
トランザクショナル インターフェイスでは Extended Get および Step オペレーションのフィルターで使用されている AND および OR 演算子は、厳密に左から右へ向かって解釈されます。トランザクショナル インターフェイスは、次の規則に従ってフィルター内の式の評価を続けていきます。
•現在のレコードに適用された式が真で、次の演算子が OR の場合、トランザクショナル インターフェイスではそのレコードはフィルター条件を満たすものと見なされます。
•式が真で、次の演算子が AND の場合、トランザクショナル インターフェイスでは次のいずれかの状況になるまで各式の評価が継続されます。
•トランザクショナル インターフェイスが次の OR 式に達する。
•式の 1 つが偽と評価される。
•トランザクショナル インターフェイスがフィルターの末尾に達する。
•式が偽で、次の演算子が OR の場合、トランザクショナル インターフェイスではフィルター内の次の式が引き続き評価されます。
•式が偽で、次の演算子が AND の場合、トランザクショナル インターフェイスではそのレコードは拒否されます。
次のいずれかの条件が成立すると、レコードの検索は中止されます。
•トランザクショナル インターフェイスで、フィルター条件を満たす、指定した数のレコードが検出される。
•トランザクショナル インターフェイスがフィルター条件を満たすレコードを検索している間に、検索したレコード数が指定したリジェクト カウントの最大数を超える。
•現在のキー パスがフィルター条件のフィールドとして使用されており、それ以降ファイルの残り部分にフィルター条件を満たすレコードはないとする、拒否レコードにトランザクショナル インターフェイスが達する。
•トランザクショナル インターフェイスがファイルの末尾に達する。
例
フィルター条件を満たす次のレコード全体を取得するには、フィルター部分を希望どおりに設定し、次のようにディスクリプター フィールドを設定します。
1 レコード数に 1 を設定します。
2 フィールド数に 1 を設定します。
3 フィールド長に取得するレコード全体の長さを設定します。
4 フィールドのオフセットに 0 を設定します。
フィルター条件を使わずに次の 12 件のレコードを取得し、各レコードから 4 つのフィールドを抽出するには、論理式の項の数に 0 を設定し、次のようにディスクリプター フィールドを設定します。
1 レコード数に 12 を設定します。
2 フィールド数に 4 を設定します。
3 抽出する 4 つのフィールドごとにフィールド長およびフィールドのオフセット パラメーターを設定します。
レコードからのフィールドの取得
Extended オペレーションを使ってレコードのフィールド（レコードの一部）を取得するときは、データ バッファーがオペレーションから返される情報を十分に格納できることを確認しておく必要があります。
表
22 は、トランザクショナル インターフェイスから返されるデータ バッファーの構造体を示しています。
表 22 Extended Get / Step オペレーションの戻りデータ バッファー構造体
要素 | 長さ（バイト単位） | 説明 |
レコード数 | 2 | 返されたレコード数。 |
繰り返し部分（取得されたレコードごとに 1 つあります） |
長さ 0 | 2 | 先頭レコードのイメージ（すべてのフィールドを結合したもの）の長さ。 |
位置 0 | 4 | 先頭レコードの物理カレンシー（アドレス）。 |
レコード 0 | n | 先頭レコードのイメージ（すべてのフィールドを結合したもの）。 |
.
.
. | | |
長さ x | 2 | 末尾レコードのイメージ（すべてのフィールドを結合したもの）の長さ（バイト単位）。 |
位置 x | 4 | 末尾レコードの物理カレンシー（アドレス）。 |
レコード x | n | 末尾レコードのイメージ（すべてのフィールドを結合したもの）。 |
返されたすべてのレコード（またはレコードのフィールド）が固定長である場合、戻りデータ バッファー内のデータの位置は簡単に計算できます。しかし、Extended オペレーションから返されたデータ バッファーからレコードの可変長部分を抽出するには、さらに特別な手順を踏む必要があります。
レコードの可変長部分が返されるとき、トランザクショナル インターフェイスは戻りデータ バッファー内に余分なレコード イメージを詰め込みません。したがって、レコードの可変長部分が占有する最大のバイト数を想定して戻りデータ バッファー内の領域を確保しても、実際に返されたデータがその最大値を下回る場合、トランザクショナル インターフェイスでは次に返されたフィールドのフィールド記述は現在のフィールドのデータの直後から始まることになります。
たとえば、固定レコード長が 100 バイトで、可変長部分は最大 300 バイトになると推定されるときに、5 件のレコードの可変長部分だけを取得したいとします。入力バッファーのディスクリプター要素を使って、フィールド長に 300 を設定し、フィールドのオフセットに 100 を設定します。戻りバッファーについては、次の計算式で示すように、レコード数を示す 2 バイトと、レコード当たり 306 バイト（つまり、長さの 2 バイト、アドレスの 4 バイト、およびデータの 300 バイト）を加算する必要があります。
2 + ((2 バイト + 4 バイト + 300 バイト) * 5) = 1532 バイト
しかし、返された先頭レコードの可変長部分には 50 バイトのデータしかなかったとします。その結果、2 バイトから成る 2 番目に返されるレコードの長さは、データ バッファーのオフセット 58、つまり先頭レコードのフィールド イメージの直後に格納されることになります。こうした状況でもアプリケーションでは、トランザクショナル インターフェイスからデータ バッファーに返された長さ、位置、およびデータを正確に解析する必要があります。
結果
Get Next Extended オペレーションが正常に終了した場合は、トランザクショナル インターフェイスから次の情報が返されます。
•データ バッファーには、取得された 1 つまたは複数のレコードに含まれる 1 つまたは複数のフィールドが格納されます（表
22 を参照してください）。
•データ バッファー長には、受け取った総バイト数が格納されます。
•キー バッファーには、受け取った最後のデータ レコードのキー値が格納されます。
Get Next Extended オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。
3 | ファイルが開いていません。 |
6 | キー番号パラメーターが不正です。 |
7 | キー番号が変更されました。 |
8 | 現在のポジションが不正です。 |
9 | オペレーションが EOF（end-of-file）を検出しました。 |
22 | データ バッファー パラメーターが短すぎます。 |
60 | 指定されたリジェクト カウントに達しました。 |
61 | 作業領域が小さすぎます。 |
62 | ディスクリプターが不正です。 |
64 | フィルター制限に達しました。 |
65 | フィールド オフセットが不正です。 |
82 | トランザクショナル インターフェイスがポジショニングを失いました。 |
134 | トランザクショナル インターフェイスがインターナショナル ソート規則（ISR）を読み取れません。 |
135 | 指定されたインターナショナル ソート規則（ISR）テーブルは破損しているか、または不正です。 |
136 | トランザクショナル インターフェイスは、指定されたオルタネート コレーティング シーケンスをファイル内に見つけられません。 |
トランザクショナル インターフェイスでは、0 以外のステータス コードが返されても、有効なデータがデータ バッファーに返されることがあります。ただしこの場合、返された最後のレコードは不完全なものである可能性があります。データ バッファー長パラメーターに 0 を超える値が返されている場合は、データ バッファーに抽出されたデータを確認してください。
データ バッファーが短すぎるためにフィールドを部分的にしか格納できない場合は、トランザクショナル インターフェイスではその一部だけのフィールドも含め、格納できるだけのレコード部分が返されます。部分フィールドが抽出される最後のフィールドである場合、トランザクショナル インターフェイスではオペレーションが続行されます。そうでない場合、トランザクショナル インターフェイスではオペレーションは中止され、ステータス コード 22 が返されます。
たとえば、2 件の可変長レコードから 3 つのフィールドを取得する Get Next Extended オペレーションを考えてみましょう。最初のレコードは 55 バイトで、2 番目のレコードは 50 バイトの長さだとします。データ バッファーには 50 バイトのデータを返すことができます。取得する 3 つのフィールドは次のように定義されています。
•フィールド 1 はオフセット 2 から始まり、2 バイト長です。
•フィールド 2 はオフセット 45 から始まり、10 バイト長です。
•フィールド 3 はオフセット 6 から始まり、2 バイト長です。
トランザクショナル インターフェイスで Get Next Extended オペレーションが実行されるとき、最初のレコードは問題なく返されます。しかし、2 番目のレコードからフィールド 2 の 10 バイトを抽出しようとすると、オフセット 45 とレコードの末尾のオフセット 49 の間では 5 バイトしか取得できないことがトランザクショナル インターフェイスによって検出されます。この時点で、トランザクショナル インターフェイスはフィールド 2 の不足している 5 バイト分を詰め込まないため、フィールド 3 は抽出できなくなります。その代わりに、トランザクショナル インターフェイスからステータス コード 22 が返され、フィールド 1 全体とフィールド 2 の先頭 5 バイトが戻りデータ バッファーに格納されます。
トランザクショナル インターフェイスではフィルター条件で使用するフィールドと演算子によって、要求を最適化できる場合があります。拒否レコードに達すると、ステータス コード 64 が返され、ファイルの未検索の部分にはフィルター条件を満たすレコードがそれ以上ないことが示されます。
ポジショニング
Get Next Extended オペレーションを実行すると、完全な論理カレンシーおよび物理カレンシーが確立されます。検索された最後のレコードが現在のレコードになります。このレコードは、フィルター条件を満たして取得されたレコードか、またはフィルター条件を満たさないために拒否されたが、まだ最適化の範囲を超えていないレコードのいずれかです。たとえば、Extended オペレーションがステータス 9 を返した場合は、ファイルの末尾のレコードが現在のレコードになります。ステータス 60（リジェクト カウントに達しました）が返された場合は、拒否された最後のレコードが現在のレコードです。ステータス 64（フィルター制限に達しました）が返された場合には、最適化条件を満たす最後のレコードが現在のレコードになります。これ以降のレコードは最適化の範囲を超えていることを確認するために、トランザクショナル インターフェイスが次のレコードを検索する必要があったとしても、現在のレコードの設定は条件を満たす前のレコードに戻されます。
メモ： トランザクショナル インターフェイスでは、Get Next Extended オペレーションの後に Delete または Update オペレーションを実行することはできません。現在のレコードは検索された最後のレコードであるため、アプリケーションには、意図したレコードを適切に削除または更新しているかどうかを確認する方法がありません。
Get Position（22）
Get Position オペレーション（B_GET_POSITION）では、4 バイトで表した現在のレコードの物理位置を返します。Get Position オペレーションを発行するときに物理カレンシーが確立されていないと、オペレーションは正常に実行されません。レコードの位置（アドレス）を決定できれば、Get Direct/Record オペレーション（23）を使って、ファイル内の物理位置を基にそのレコードを直接取得できるようになります。トランザクショナル インターフェイスでは、Get Position 要求を処理するためにディスク I/O は行われません。
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
前提条件
•対象となるファイルが開いていることが必要です。
•アプリケーションでは、物理カレンシーを確立しておくことが必要です。
手順
1 オペレーション コードに 22 を設定します。
2 ファイルのポジション ブロックを渡します。
3 データ バッファー長に少なくとも 4 バイトを設定します。
4 キー番号に 0 を設定します。
結果
Get Position オペレーションが正常に終了した場合は、トランザクショナル インターフェイスからレコードの位置がデータ バッファーに返されます。位置は、High-Low で記録される 4 バイトのバイナリ値で、ファイル内でのレコードのオフセット（バイト単位）を示します。また、トランザクショナル インターフェイスではデータ バッファー長にも 4 バイトが設定されます。
Get Position オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。
3 | ファイルが開いていません。 |
8 | 現在のポジションが不正です。 |
ポジショニング
Get Position オペレーションは、ポジショニングにまったく影響しません。
Get Previous（7）
Get Previous オペレーション（B_GET_PREVIOUS）では、指定されたキーに基づいて、論理位置で前にあるレコードを取得します。Get Previous オペレーションを使うと、重複するキー値を持つレコードのグループの中でレコードを検索できます。
Get Key（+50）バイアスを使うと、ファイル内に値が存在するかどうかを検出することもできます。一般に、Get Key オペレーションの方が高速に処理されます。
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
前提条件
•対象となるファイルが開いていることが必要です。
•ファイルがデータオンリー ファイルであってはいけません。
•アプリケーションでは、指定したキーに基づく前の論理位置を確立しておくことが必要です。
手順
1 オペレーション コードに 7 を設定します。オプションで、ロック バイアスも指定できます。
•+100 - 単一レコード ウェイト ロック
•+200 - 単一レコード ノーウェイト ロック
•+300 - 複数レコード ウェイト ロック
•+400 - 複数レコード ノーウェイト ロック
ロックの詳細については、『Pervasive PSQL Programmer's Guide』を参照してください。
2 ファイルのポジション ブロックを渡します。
3 データ バッファー長に取得するレコードの長さ以上の値を設定します。
4 キー バッファーに前のオペレーションで取得したキー値を指定します。キー バッファーには、前の呼び出しでトランザクショナル インターフェイスが返したキー値とまったく同じものを渡します。トランザクショナル インターフェイスでは、ファイル内の現在の位置を決定するために、直前にキー バッファーに格納された情報が必要となるからです。
5 キー番号パラメーターに、前の呼び出しで使用したキー パスを設定します。Get Previous オペレーションを使ってキー パスを変更することはできません。
結果
Get Previous オペレーションが正常に終了した場合、トランザクショナル インターフェイスではキー バッファーが新しいレコードのキー値を使って更新され、データ バッファーに前のレコードが返され、データ バッファー長にそのレコードの長さが返されます。
Get Previous オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。
3 | ファイルが開いていません。 |
6 | キー番号パラメーターが不正です。 |
7 | キー番号が変更されました。 |
8 | 現在のポジションが不正です。 |
9 | オペレーションが EOF（end-of-file）を検出しました。 |
22 | データ バッファー パラメーターが短すぎます。 |
82 | トランザクショナル インターフェイスがポジショニングを失いました。 |
このオペレーションの実行により、論理位置の直前がファイルの先頭よりも前を指す場合は、ステータス コード 9 が返されます。
ポジショニング
Get Previous オペレーションを実行すると、完全な論理カレンシーおよび物理カレンシーが確立し、取得したレコードが現在のレコードになります。
Get Previous Extended（37）
Get Previous Extended オペレーション（B_GET_PREV_EXTENDED）では、指定されたキーに基づき、論理位置の直前からファイルの先頭へ向かって 1 つまたは複数のレコードを検索します。検索したレコードがフィルター条件を満たしているかどうかをチェックした上で、条件を満たすレコードだけを取得します。フィルター条件は論理式の形を取り、キー フィールドのみに制限されません。
Get Previous Extended オペレーションでは、レコードから指定した部分だけを抽出し、その部分だけをアプリケーションに返すこともできます。
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
前提条件
•対象となるファイルが開いていることが必要です。
•ファイルがデータオンリー ファイルであってはいけません。
•指定したキーに基づく前の論理位置を確立しておくことが必要です。
手順
1 オペレーション コードに 37 を設定します。オプションで、ロック バイアスも指定できます。
•+100 - 単一レコード ウェイト ロック
•+200 - 単一レコード ノーウェイト ロック
•+300 - 複数レコード ウェイト ロック
•+400 - 複数レコード ノーウェイト ロック
ロックの詳細については、『Pervasive PSQL Programmer's Guide』を参照してください。
2 ファイルのポジション ブロックを渡します。
3 入力データ バッファーと戻りデータ バッファーのどちらか大きい方を格納できるように、十分な長さのデータ バッファーを指定します。表
21 に示す構造体に従って、データ バッファーを初期化します。
4 データ バッファー長に、入力構造体（表
21）と戻り構造体（表
22）のどちらか大きい方の長さを指定します。
トランザクショナル インターフェイスではバッファーを用意して、Extended オペレーションのワークスペースとして使用できるようにします。このバッファーのサイズは、［拡張オペレーション バッファー サイズ］オプションを使って構成します。データ バッファー構造体、取得される最長のレコード、およびリクエスターのオーバーヘッドの 355 バイト、これらの合計が設定したバッファー サイズを超えることはできません。（リクエスターのオーバーヘッドは、DOS ワークステーションのエンジンには適用できません。）
5 キー バッファーに前のオペレーションで取得したキー値を指定します。キー バッファーには、前の呼び出しでトランザクショナル インターフェイスから返されたキー値とまったく同じものを渡します。トランザクショナル インターフェイスでは、ファイル内の現在の位置を決定するために、直前にキー バッファーに格納された情報が必要となるからです。
6 キー番号パラメーターに、前の呼び出しで使用したキー パスを設定します。Get Previous Extended オペレーションを使ってキー パスを変更することはできません。
詳細
このオペレーションでは、Get Next Extended オペレーションの場合と同じ入力データ バッファーおよび戻りデータ バッファーを使用します。詳しくは
詳細をご覧ください。
結果
このオペレーションでは、Get Next Extended オペレーションと同様の結果が返されます。詳しくは
結果をご覧ください。
ポジショニング
Get Previous Extended オペレーションを実行すると、完全な論理カレンシーおよび物理カレンシーが確立されます。検索された最後のレコードが現在のレコードになります。このレコードは、フィルター条件を満たして取得されたレコードか、またはフィルター条件を満たさないために拒否されたレコードのいずれかです。
メモ： トランザクショナル インターフェイスでは、Get Previous Extended オペレーションの後に Delete または Update オペレーションを実行することはできません。現在のレコードは検索された最後のレコードであるため、アプリケーションには、意図したレコードを適切に削除または更新しているかどうかを確認する方法がありません。
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）などのオペレーションは、新しい物理カレンシーに基づいて機能します。
Insert Extended（40）
Insert Extended オペレーション（B_EXT_INSERT）では、ファイルに 1 つまたは複数のレコードを挿入します。トランザクショナル インターフェイスでは、新しいレコードのキー値を反映して、キーの B ツリーが調整されます。
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
メモ： NCC（No-currency-change：カレンシー変更なし）オプションを使用すると、Insert Extended オペレーションはキー バッファー パラメーターの値を更新しません。つまり、キー バッファー パラメーターには何の情報も返されません。
前提条件
•対象となるファイルが開いていることが必要です。
•挿入するレコードは適切なレコード長を持つ必要があります。また、キー値は対象となるファイルで定義されているキーと一致していなければなりません。
手順
1 オペレーション コードに 40 を設定します。
2 ファイルのポジション ブロックを渡します。
3 表
23 に示す構造体に従って、データ バッファーを指定します。
4 データ バッファー長を指定します。この値は、データ バッファー構造体のサイズと一致していることが必要です。
5 カレンシーの確立にトランザクショナル インターフェイスが使用するキー番号を指定します。NCC オプションを使用するには、キー番号に -1（0xFF）を指定します。システム定義のログ キー（システム データ）を使用するには、125 を指定します。
詳細
次の表は、データ バッファーの構造体を示しています。
表 23 Insert Extended オペレーションのデータ バッファー構造体
要素 | 長さ（バイト単位） | 説明 |
固定部分 | 2 | 挿入するレコード数。 |
繰り返し部分（レコードごとに 1 つあります） |
| 2 | レコード イメージの長さ。 |
| n | レコード イメージ。 |
結果
Insert Extended オペレーションが正常に終了した場合、トランザクショナル インターフェイスではファイルに新しいレコードが挿入され、新しいレコードを反映してすべての B ツリーが更新されます。さらに、NCC Insert Extended オペレーションの場合を除き、最後に挿入したレコードから、指定したキーの値がキー バッファーに返されます。また、戻りデータ バッファーの先頭ワードには、ファイルに正常に挿入されたレコードの数がトランザクショナル インターフェイスによって格納されます。データ バッファーの先頭ワードの後には、挿入されたレコードのアドレスがトランザクショナル インターフェイスによって格納されます。
オペレーションの一部しか正常に実行されず、トランザクショナル インターフェイスから 0 以外のステータス コードが返された場合、データ バッファーの先頭ワードの値は正常に挿入されたレコードの数と等しくなります。エラーの原因となったレコードは、正常に挿入されたレコード数 + 1 番目のレコードです。
Insert Extended オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。
2 | アプリケーションで I/O エラーが発生しました。 |
3 | ファイルが開いていません。 |
5 | レコードのキー フィールドに重複するキー値があります。 |
18 | ディスクがいっぱいです。 |
21 | キー バッファー パラメーターが短すぎます。 |
22 | データ バッファー パラメーターが短すぎます。 |
ポジショニング
NCC オプションを指定しない Insert Extended オペレーションを実行すると、完全な論理カレンシーおよび物理カレンシーが確立し、挿入されたレコードのキー値がヌルでなければ、最後に挿入されたレコードが現在のレコードになります。論理カレンシーは指定したキーに基づきます。
NCC Insert Extended オペレーションを実行すると、論理カレンシーは影響を受けずに、物理カレンシーが確立されます。つまり、NCC Insert Extended オペレーションを実行したアプリケーションでは、ファイル内の論理位置はオペレーションを実行する前と変わらないということです。このような状況で、NCC Insert Extended オペレーションに続けて、Get Next（6）、Get Next Extended（36）、Get Previous（7）、および Get Previous Extended（37）などのオペレーションを実行すると、NCC Insert Extended オペレーション実行以前のアプリケーションの論理カレンシーに基づく値が返されます。
メモ： トランザクショナル インターフェイスでは、NCC Insert Extended オペレーションを実行しても、その結果として何の情報もキー バッファーには返されません。したがって、論理カレンシーの維持が必要なアプリケーションでは、NCC Insert Extended オペレーション後にキー バッファーの値を変更しないでください。変更すると、次の Get オペレーションの結果は予測できないものになります。
トランザクショナル インターフェイスでは標準の Insert Extended オペレーションと NCC Insert Extended オペレーションのどちらを実行しても、新しく挿入されたレコードに対し物理カレンシーが確立されます。したがって、NCC Insert Extended オペレーションに続く Step Next（24）、Step Next Extended（38）、Step Previous（35）、Step Previous Extended（39）、Update（3）、Delete（4）、および Get Position（22）などのオペレーションは、新しい物理カレンシーに基づいて機能します。
Get Next オペレーション（6）のような、元の論理カレンシーに基づくオペレーションを実行するために、アプリケーションで Insert Extended オペレーション実行前のファイルの論理位置を保存しておく必要がある場合に、NCC Insert Extended オペレーションが役立ちます。
NCC Insert Extended オペレーションを実行しないで同様の結果を得るには、アプリケーションで以下の手順を実行する必要があります。
1 Get Position（22） - 現在の論理レコードの、4 バイト長の物理アドレスを取得します。アプリケーションでこの値を保存し、手順 3 でこれを渡して元に戻します。
2 Insert Extended（40） - 新しいレコードを挿入します。このオペレーションにより、新しい論理カレンシーおよび物理カレンシーが確立されます。
3 Get Direct/Record（23） - 手順 1 での状態に論理カレンシーと物理カレンシーを戻します。
NCC Insert Extended オペレーションは、論理カレンシーについてはこの手順と同様の結果を得られますが、物理カレンシーについては異なります。たとえば、これら 2 つの手順のいずれかに続けて Get Next（6）オペレーションを実行した場合は、どちらの手順でも結果は変わりませんが、Step Next（24）を実行した場合は、異なるレコードが返される可能性があります。
Login/Logout（78）
Login/Logout オペレーション（B_LOGIN/B_LOGOUT）を使用すると、ユーザーは自身のユーザー資格情報を指定したり、データベース エンジンから認証トークンおよび許可トークンを取得したりすることができます。このオペレーションでは、ユーザーが自身のログイン資格情報をリセットすることも可能であるため、データベースヘのアクセスを取得するためにログイン資格情報を再入力する必要があります。
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
前提条件
•データベース名およびユーザー ID はあらかじめ定義されている必要があります。
ログイン手順
1 オペレーション コードに 78 を設定します。
2 キー番号に 0 を設定します。
3 データベース URI の形式を用いて、キー バッファーにサーバー名、データベース名、ユーザー ID、およびパスワードを設定しますURI 接続文字列の詳細については、『
Pervasive PSQL Programmer's Guide』の
データベース URI を参照してください。
ログアウト手順
1 オペレーション コードに 78 を設定します。
2 キー番号に 1 を設定します。
3 データベース URI の形式を用いて、キー バッファーにサーバー名、データベース名、ユーザー ID、およびパスワードを設定します（『
Pervasive PSQL Programmer's Guide』の
データベース URI を参照してください）。
結果
Login または Logout オペレーションが正常に終了した場合は、ステータス 0 が返されます。正常に実行されなかった場合は、次のステータス コードのいずれかが返されます。
1 | 不正な操作です。 |
172 | データベース名が見つかりません。 |
3103 | 不明なサーバーです。 |
注記
データベース URI を結合した長さは 255 バイト未満でなければなりません。これがキー バッファーの最大サイズだからです。
Login オペレーションではパフォーマンスに負荷がかかります。アプリケーション、ファイルごとにログインおよびログアウトするようなコーディングをしないでください。代わりに、セッションの始めに一度データベースにログインし、データベース作業が完了したらログアウトするようにしてください。
ポジショニング
Login/Logout オペレーションは、ファイルのカレンシー情報にはまったく影響しません。
Open（0）
Open オペレーション（B_OPEN）は、ファイルへのアクセスを可能にします。アプリケーションでファイルにアクセスするには、まず Open オペレーションを実行する必要があります。フル パス名または相対パス名を指定する限り、対象となるファイルが現在のディレクトリに保存されている必要はありません。
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
前提条件
•開くファイルは、アクセス可能な論理ディスク ドライブ上にあることが必要です。
•そのファイルで使用可能なファイル ハンドルが存在することが必要です。
手順
1 オペレーション コードに 0 を設定します。
2 ファイルにオーナーが設定されている場合は、データ バッファー パラメーターにオーナー ネームを指定し、末尾にバイナリ 0 を付けます。
3 データ バッファー長パラメーターに、バイナリ 0 を含めたオーナー ネームの長さを指定します。
キー バッファー パラメーターに、開くファイルのパス名を入れます。埋め込みスペースの設定に応じて、パス名の終端はヌル（バイナリ ゼロ）にします。パス名は半角 255 文字までの範囲で指定できます。ヌル終端文字を含む完全修飾 UNC（Unified Naming Convention）パス名は、半角 255 文字までの範囲で指定できます。
トランザクショナル インターフェイスは通常、ファイル名を完全修飾 UNC ファイル名に拡張します。たとえば、J:
\Data
\File.dat は
\\サーバー名
\共有名
\Data
\File.dat に変換されます。この拡張されたファイル名が、ヌル終端文字を含めて半角 255 文字までにならなければなりません。『
Pervasive PSQL Programmer's Guide』の
データベース URI も参照してください。
ただし、Btrieve の Open 要求がローカル エンジンに送られる場合は、MIF はローカルのドライブ文字をコンピューター名および共有名に置き換えません。ローカルで開く場合にもっと長い名前でも受け入れられたとしても、リモート クライアントではそのファイルを開けないことがあります。
クライアントの設定オプション［スペースを含むファイル/ディレクトリ名］によって、埋め込みスペースを含むファイル名がサポートされます。デフォルトでは、この設定パラメーターは
オンになっています。つまり、スペースはパスの一部と見なされます。この設定がオンの場合、ファイル名はヌル バイトで区切る必要があります。この設定がオフの場合、埋め込みスペースを含むファイル（"
C:\My Folder\my file.mkd" など）を使用することはできません。『
Advanced Operations Guide』の
長いファイル名と埋め込みスペースのサポートを参照してください。
Pervasive PSQL クライアントでサポートするパス名の詳細については、『
Getting Started with Pervasive PSQL』の
Pervasive リクエスターでサポートするネットワーク パスの形式を参照してください。
4 キー番号パラメーターに、表
24 に記載されているモード値のいずれかを指定します。
詳細
ここでは、サポートされているオープン モードについて説明します。
注意： データベース エンジンは、クライアントがアクセラレイティド モードを使用している間は、クライアントのトランザクション アトミシティ、トランザクション一貫性保守、およびアーカイブ ログの安全性を保証できません。この制約があるのは、ログからの復元が必要な場合に、完全な復元を行うために十分な情報がログに含まれていない可能性があるからです。なぜなら、ログは、1 つのデータ ファイル上で行った操作の部分的な記録でしかないからです。
たとえば、アクセラレイティド モードを使用して追加を実行中のクライアントと、ノーマル モードを使用して更新を実行中のクライアントが同じファイルへアクセス中にシステム障害が発生した場合、メモリ上のアクセラレイティドの追加操作はディスクに書き出されませんが、トランザクショナルな更新操作はトランザクション ログに書き込まれるため、データ ファイルにまだ存在していないレコードに対する更新がトランザクション ログに含まれる可能性があります。
この操作の組み合わせを含むアーカイブ ログをロール フォワードしようとすると、失敗します。
ファイルを開く際に、オープン モードによって、ローカル エンジンとリモート エンジンのどちらを使用するかをトランザクショナル インターフェイスに指示できます。キー番号パラメーターにオープン モードの値を指定します。
メモ： ローカル エンジンでファイルを開くように指定する場合は、ワークグループ エンジンでもサーバー エンジンでも、Open オペレーションに何ら違いはありません。
表 24 オープン モード
説明 | 選択しない | ローカル エンジンで実行 | リモート エンジンで実行 |
ノーマル | 0 | 6 | 99 |
アクセラレイティド
特定のファイルでのパフォーマンスを向上するために、ファイルをアクセラレイティド モードで開くことができます（6.x トランザクショナル インターフェイスでもアクセラレイティド モードで開くことはできましたが、ノーマル モードで開いたものと解釈されました）。アクセラレイティド モードでファイルを開くと、トランザクショナル インターフェイスは、そのファイルに対するトランザクション ログを実行しません。上記の「注意」を参照してください。 | -1 | 7 | 100 |
リードオンリー
リードオンリー モードでファイルを開くと、ファイルは読み取ることしかできず、更新できなくなります。このモードを使うと、トランザクショナル インターフェイスでは自動的に回復できない破損データを含むファイルを開くことができます。ファイルのインデックスのデータが壊れている場合は、リードオンリー モードでファイルを開き、Step Next（24）オペレーションを使用することによって、レコードを取得できます。 | -2 | 8 | 101 |
ベリファイ
このモードは無視されます。トランザクショナル インターフェイスではこのモードを指定しても、ファイルはノーマル モードで開かれます。以前のバージョンのトランザクショナル インターフェイスでは、ベリファイ モードを指定すると、ディスクに書き込まれたデータが正しいかどうかが検証されました。 | -3 | 適用外 | 適用外 |
エクスクルーシブ
エクスクルーシブ モードはファイルに対する排他的なアクセスを可能にします。あるアプリケーションが排他的にアクセスしているファイルは、閉じるまで、ほかのアプリケーションから開くことができなくなります。 | -4 | 10 | 103 |
開いているファイルの最大数について定められた制限はありません。同時に開くことができるファイルの数は、使用可能なメモリに応じて変わります。
ファイルは、トランザクショナル インターフェイスによって 1 回だけ開かれます。（トランザクショナル インターフェイスは、複数のクライアントが同時に 1 つのファイルを開いている状況や、単独のクライアントがファイルのポジション ブロックを複数持っている状況を認識し、処理します。）拡張ファイルを開くとき、トランザクショナル インターフェイスでは 1 つのハンドルが使用され、ベース ファイルとすべてのエクステンション ファイルが開かれます。
結果
Open オペレーションが正常に終了した場合、トランザクショナル インターフェイスでは目的のファイルにファイル ハンドルが割り当てられ、新しく開いたファイルの Open 呼び出しで渡したポジション ブロックが予約されて、そのファイルがアクセス可能な状態になります。
Open オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。
2 | アプリケーションで I/O エラーが発生しました。 |
11 | 指定されたファイル名は不正です。 |
12 | トランザクショナル インターフェイスは指定されたファイルを見つけられません。 |
20 | トランザクショナル インターフェイスまたは Btrieve リクエスターが非アクティブです。 |
46 | 要求したファイルへのアクセスは拒否されました。 |
84 | レコードまたはページがロックされています。 |
85 | ファイルはロックされています。 |
86 | ファイル テーブルがいっぱいです。 |
87 | ハンドル テーブルがいっぱいです。 |
88 | アプリケーションでモードの不一致エラーが発生しました。 |
次の表には、ローカル クライアントで使用可能なオープン モードの組み合わせを示します。
表 25 ローカル クライアントのオープン モードの組み合わせ
ローカル クライアント 1 のオープン モード | ローカル クライアント 2 のオープン モード | 結果 |
ノーマル | ノーマル | 正常終了 |
| リードオンリー | 正常終了 |
| エクスクルーシブ | ステータス コード 88 |
| アクセラレイティド | 正常終了 |
リードオンリー | ノーマル | 正常終了 |
| リードオンリー | 正常終了 |
| エクスクルーシブ | ステータス コード 88 |
| アクセラレイティド | 正常終了 |
エクスクルーシブ | ノーマル | ステータス コード 88 |
| リードオンリー | ステータス コード 88 |
| エクスクルーシブ | ステータス コード 88 |
| アクセラレイティド | ステータス コード 88 |
アクセラレイティド | ノーマル | 正常終了 |
| リードオンリー | 正常終了 |
| エクスクルーシブ | ステータス コード 88 |
| アクセラレイティド | 正常終了 |
ポジショニング
Open オペレーションを実行しても、ポジショニングは確立しません。ただし、次の物理レコードがファイルの先頭の物理レコードになります。
Reset（28）
Reset オペレーション（B_RESET）では、クライアントが保持しているすべてのリソースを解放します。このオペレーションは、クライアントが実行中のトランザクションを中止し、すべてのロックを解除し、さらに、クライアントが開いているファイルをすべて閉じます。
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
前提条件
トランザクショナル インターフェイスまたはリクエスターがロードされていて、Reset 呼び出しを発行するクライアントがトランザクショナル インターフェイスとの接続を確立していれば、アプリケーションではいつでも Reset オペレーションを発行できます。トランザクショナル インターフェイスとの接続は、たとえば、ファイルを開いたり、Pervasive PSQL ユーティリティを使ってファイルのステータスを要求したりすることにより確立します。
手順
1 オペレーション コードに 28 を設定します。
2 キー番号およびキー バッファー パラメーターに 0 を設定します。
結果
Reset オペレーションが正常に終了した場合、トランザクショナル インターフェイスでは指定したクライアント、ウィンドウ、またはセッションに対して次の動作が実行されます。
1 実行中のトランザクションがすべて中止される。
2 保持されているすべてのロックが解除される。
3 開いているファイルがすべて閉じられる。
Reset オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから 0 以外のステータス コードが返されます。
ポジショニング
Reset オペレーションを実行すると、開いているファイルがすべて閉じられるため、すべてのカレンシーが消去されます。
Set Directory（17）
Set Directory オペレーション（B_SET_DIR）では、指定したパス名を現在のディレクトリとして設定します。
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
前提条件
対象となる論理ディスク ドライブおよびディレクトリがアクセス可能であることが必要です。
手順
1 オペレーション コードに 17 を設定します。
2 キー バッファーに、論理ディスク ドライブおよびディレクトリ パスを、最後にバイナリ 0 を付けて格納します。ドライブ名を省略した場合、トランザクショナル インターフェイスではデフォルトのドライブが使用されます。ディレクトリの絶対パスを指定しなかった場合、トランザクショナル インターフェイスではキー バッファーに指定したディレクトリ パスが現在のディレクトリに追加されます。
Pervasive PSQL クライアントでサポートするパス名の詳細については、『
Getting Started with Pervasive PSQL』の
Pervasive リクエスターでサポートするネットワーク パスの形式を参照してください。
結果
Set Directory オペレーションが正常に終了した場合、トランザクショナル インターフェイスではキー バッファーに指定したディレクトリが現在のディレクトリになります。
Set Directory オペレーションが正常に実行されなかった場合、トランザクショナル インターフェイスでは現在のディレクトリは変更されないままで、0 以外のステータス コードが返されます。
ポジショニング
Set Directory オペレーションは、ポジショニングにまったく影響しません。
Set Owner（29）
Set Owner オペレーション（B_SET_OWNER）ではファイルにオーナー ネーム（パスワード）を割り当てます。ファイルにオーナー ネームが設定されている場合は、ユーザーやアプリケーションはそのファイルにアクセスするたびにオーナー ネームを指定する必要があります。オーナー ネームがすべてのアクセス権に対し、あるいは更新権限だけに対し要求されるように指定することができます。
オーナー ネームを割り当てるときに、ディスク上のファイルのデータを暗号化するようトランザクショナル インターフェイスに指示することもできます。データの暗号化を指定すると、トランザクショナル インターフェイスでは Set Owner オペレーションの実行中にすべてのデータが暗号化されます。このため、ファイル サイズが大きいほど、Set Owner オペレーションの完了に要する時間は長くなります。
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
前提条件
•対象となるファイルが開いていることが必要です。
•トランザクションが実行中でないことが必要です。
•ファイルに既にオーナ ネームが設定されていてはいけません。
手順
1 オペレーション コードに 29 を設定します。
オプションで、+17000 のバイアスを含めると最長 24 バイト（半角 24 文字）のオーナーネーム（「長い」オーナーネーム）を作成することができます。このバイアスは btrconst.h に B_LONG_OWNER_NAME_BIAS としても定義されています。Btrconst.h は、Btriev ソフトウェア開発キット（SDK）で提供されます。
•長いオーナー ネームを指定した場合、そのデータ ファイルは Pervasive PSQL v10 SP1 より前のデータベース エンジンで読み取ることはできません。
•長いオーナー ネームを使用したデータ ファイルは、v9.5 より前のファイル形式にリビルドしようとする場合、そのオーナー ネームを最初に削除しておかないとリビルドすることができません。
2 保護するファイルを識別するポジション ブロックを渡します。
3 データ バッファーとキー バッファーの両方にオーナー ネームを格納します。トランザクショナル インターフェイスは、誤って不正な値を指定するのを防ぐために、オーナー ネームを両方のバッファーに格納することを要求します。
+17000 のバイアスが指定されない場合、オーナー ネームは 8 バイト（半角 8 文字）までの範囲で指定可能で、末尾はバイナリ 0 になっている必要があります。これは「短い」オーナー ネームと呼びます。+17000 のバイアスが指定された場合、オーナー ネームは 24 バイト（半角 24 文字）までの範囲で指定可能で、末尾はバイナリ 0 になっている必要があります。これは「長い」オーナー ネームと呼びます。どちらの場合も、オーナー ネームをすべてスペース（0x20）で構成することはできません。
4 データ バッファー長パラメーターに、バイナリ 0 を含めたオーナー ネームの長さを指定します。オーナー ネームが、指定可能な最大長（8 文字または 24 文字）よりも短い場合、その最大長に満たない部分には空白が埋め込まれます。
5 キー番号に、ファイルに対するアクセス制限と暗号化のタイプを指定する整数を設定します（表
26 を参照してください）。
詳細
一度オーナー ネームを指定すると、
Clear Owner（30）オペレーションを発行するまでそのオーナー ネームは有効です。次の表に、キー番号に指定できるアクセス制限コードの一覧を示します。
表 26 アクセスおよび暗号化のコード
コード | 説明 |
0 | すべてのアクセス モードでオーナー ネームが必要になります（データは暗号化されません）。 |
1 | 読み取り専用アクセスはオーナ ネームがなくても許可されます（データは暗号化されません）。 |
2 | すべてのアクセス モードでオーナー ネームが必要になります（データが暗号化されます）。 |
3 | 読み取り専用アクセスはオーナー ネームがなくても許可されます（データが暗号化されます）。 |
結果
Set Owner オペレーションが正常に終了した場合、それ以降のオペレーションでは正しいオーナー ネームが指定されない限り、トランザクショナル インターフェイスでファイルへのアクセスやファイルの変更を行えなくなります。唯一の例外は、オーナー ネームの指定なしで読み取り専用アクセスが許可されている場合です。さらに、Set Owner オペレーションが正常に終了すると、暗号化が指定されている場合には、トランザクショナル インターフェイスでファイル内のデータが暗号化されます。
暗号化は直ちに行われ、ファイル全体が暗号化されるまではトランザクショナル インターフェイスの制御下にあります。ファイル サイズが大きいほど、暗号化処理にかかる時間は長くなります。暗号化されたファイルからのデータの読み取りは、暗号化されていないファイルからデータを読み取る場合よりも遅くなります。トランザクショナル インターフェイスはディスクからページを読み込む際にそのページを解読し、ディスクに書き込む際に再度ページを暗号化します。キャッシュが小さい場合、あるいは比較的大量の変更操作を行う場合には、トランザクショナル インターフェイスは暗号化ルーチンをさらに頻繁に実行しなければなりません。
Set Owner オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。
41 | 実行しようとした操作はトランザクショナル インターフェイスでは許可されていません。 |
50 | ファイルのオーナーは既に設定されています。 |
51 | オーナー ネームが不正です。 |
ポジショニング
Set Owner オペレーションは、ポジショニングにまったく影響しません。
Stat（15）
Stat オペレーション（B_STAT）では、ファイルに定義されている特性を取得します。また、ファイル内のレコード数、ファイルの各インデックスに格納されている重複のないキー値の数、ファイル内の未使用ページ数など、ファイルの内容についての情報も返します。
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
前提条件
対象となるファイルが開いていることが必要です。
手順
1 オペレーション コードに 15 を設定します。
2 ファイルのポジション ブロックを渡します。
3 ファイルに定義されている統計情報を格納するのに十分なデータ バッファーを確保します。
4 データ バッファー長を指定します。ファイルの統計情報を十分に格納できる長さが必要です（詳細については、表
27 および表
28 を参照してください）。
5 少なくとも 255 バイトのキー バッファーを指定します。
6 次のようにキー番号を設定します。
•ファイルのバージョンおよび未使用の重複ポインターについての情報を除外する場合は、0 を指定します。表
27 を参考にして、戻りデータ バッファーを解析します。
•ファイルのバージョンおよび未使用の重複ポインターについての情報を含める場合は、-1（0xFF）を指定します。表
28 を参考にして、戻りデータ バッファーを解析します。
詳細
トランザクショナル インターフェイスでは、ファイルの作成以降に追加されたキーも含めて、ファイル内のすべてのキーについての情報が返されます。このキー情報には、適用可能な ACS 定義も含まれます。データ バッファー領域を確保する際、このような追加情報について考慮する必要があります。特に、ここでは、Create（0）オペレーションで使用したものと同じデータ バッファーは使用しないでください。
トランザクショナル インターフェイスでは、ファイルに最大 119 までのキーと複数の ACS を定義できるため、可能な最長データ バッファーは 33,455 バイトになります（つまり、16 + (119 * 16) + (119 * 265) です）。しかし、これほど大きなデータ バッファーが必要になることはおそらくありません。実際、ある特定の情報しか必要ない場合は、データ バッファーを小さくした方が良い場合があります。たとえば、データ バッファー長を 1,920 バイト（つまり、16 + (16 * 119)）に設定したとします。実際、このような設定にした場合、キー情報はすべて返されますが、ACS は必ずしもすべては返されません。アプリケーションで ACS についての情報が必要ない場合は、この方法を使うことができます。
キー番号パラメーターに値 0 を指定した場合、トランザクショナル インターフェイスでは次の表に示すような Stat 情報が返されます。
表 27 ファイルのバージョン情報を除外したデータ バッファー
要素 | 説明 | 長さ
（バイト単位） |
ファイル仕様 | レコード長 | 2 |
| ページ サイズ | 2 |
| インデックス数 | 2 |
| レコード数 | 4 |
| ファイル フラグ | 2 |
| 予約ワード | 2 |
| 未使用ページ | 2 |
キー仕様（各セグメントについて繰り返される） | キー ポジション | 2 |
| キー長 | 2 |
| キー フラグ | 2 |
| 重複のないキー値の数 | 4 |
| 拡張データ型 | 1 |
キー仕様（各セグメントについて繰り返される） | ヌル値 | 1 |
| 予約済み | 2 |
| キー番号 | 1 |
| ACS（オルタネート コレーティング シーケンス）番号 | 1 |
ACS 番号 0 | ACS | 265 |
. . . | . . . | . . . |
ACS 番号 x | ACS | 265 |
キー番号パラメーターに値 -1 を指定した場合、トランザクショナル インターフェイスでは次の表に示すような Stat 情報が返されます。
表 28 ファイルのバージョン情報を含むデータ バッファー
要素 | 説明 | 長さ
（バイト単位） |
ファイル仕様 | レコード長 | 2 |
| ページ サイズ | 2 |
| インデックス数 | 1 |
| ファイルのバージョン番号 | 1 |
| レコード数 | 4 |
| ファイル フラグ | 2 |
| 未使用の重複ポインター数 | 1 |
| 予約バイト | 1 |
| 未使用ページ | 2 |
キー仕様（各キー セグメントについて繰り返される） | キー ポジション | 2 |
| キー長 | 2 |
| キー フラグ | 2 |
| 重複のないキー値の数 | 4 |
| 拡張データ型 | 1 |
| ヌル値 | 1 |
| 予約済み | 2 |
| キー番号 | 1 |
（キー仕様の最後のメンバー。ここまでが繰り返される要素） | ACS（オルタネート コレーティング シーケンス）番号 | 1 |
ACS 番号 0 | ACS | 265 |
. . . | . . . | . . . |
ACS 番号 x | ACS | 265 |
ファイル仕様
戻りデータ バッファーのファイル仕様フィールドは、次の点を除いて、
Create（14）で説明したものとまったく同じです。
•ファイル仕様領域
•データ バッファーにファイルのバージョン情報が含まれている場合は、インデックス数が 1 バイト長になり、その後に 1 バイトのファイルのバージョン情報が続きます。ファイルのバージョン番号の値を 10 進数に変換しないでください。0x70 という値はそのファイルが v7.0 ファイルであることを示し、0x60 という値はそのファイルが v6.x ファイルであることを示します（以下同様）。トランザクショナル インターフェイスではファイルを作成するとき、ファイルに定義されている属性に従ってバージョン番号が割り当てられます。
•レコード数は、ファイル内のレコードの数を表す 4 バイト長の値です。
•ファイル フラグ ワードで、ビット 9 と 12 は次のような意味を持ちます。
ビット 9 = 1 かつ
ビット 12 = 0 | ファイルはシステム データを使って作成されました。（これは、必ずしもシステム定義のログ キーが現在使用されていることを意味しません。削除された可能性もあります。） |
ビット 9 = 1 かつ
ビット 12 = 1 | ファイルはシステム データを使わずに作成されました。 |
Stat オペレーションでは、システム データがデフォルトで組み込まれたのか、明示的に組み込まれたのかは示されません。
•データ バッファーにファイルのバージョン情報が含まれている場合、1 バイトの未使用重複ポインターの数がファイル フラグ フィールドに続き、ファイル内に残っている未使用の重複ポインターの数が示されます。
•予約領域が割り当てられますが、トランザクショナル インターフェイスは Stat オペレーションではこの領域を無視します。
キー仕様
戻りデータ バッファーのキー仕様フィールドは、で説明したものと基本的には同じです。ただし、キー フラグ フィールドの後に 4 バイトの重複のないキー値の数が続き、指定されたキーに対して一意で重複のない値を持つレコードの数が示される点が異なります。
ACS
戻りデータ バッファーの ACS 定義は、
Create（14）で説明したものとまったく同じです。
結果
Stat オペレーションが正常に終了した場合、トランザクショナル インターフェイスではファイルおよびキーの特性がデータ バッファーに返され、データ バッファーの長さがデータ バッファー長に返されます。対象となるファイルが拡張ファイルである場合、トランザクショナル インターフェイスでは先頭のエクステンション ファイルのファイル名がキー バッファーに返されます。先頭のエクステンション ファイルのファイル名が 63 バイトを超える場合、トランザクショナル インターフェイスではファイル名が切り詰められます。ファイルが拡張ファイルでない場合は、トランザクショナル インターフェイスではキー バッファーの先頭バイトが 0 に初期化されます（Stat Extended オペレーションを使うと、拡張ファイルに関する統計情報を取得できます）。
Stat オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。
3 | ファイルが開いていません。 |
22 | データ バッファー パラメーターが短すぎます。 |
ポジショニング
Stat オペレーションは、ポジショニングにまったく影響しません。
Stat Extended（65）
Stat Extended オペレーション（B_EXTENDED_STAT）にはいくつかのサブファンクションがあります。これを使って、アプリケーションは開いているファイルについての情報を収集することができます。
表 29 Stat Extended（65）のサブファンクション
サブファンクション ID | 説明 |
1 | エクステンション ファイル名の一覧表示 |
2 | ファイルのシステム データ情報 |
3 | 重複による競合レコードおよびキーの識別 |
4 | ファイル情報 |
5 | ゲートウェイの識別 |
6 | ロック オーナーの識別 |
7 | セキュリティ情報 |
8 | ステータス コード 71（参照整合性の定義に違反があります）の発生原因となる、テーブル名またはファイル名の一覧表示 |
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
前提条件
対象となるファイルが開いていることが必要です。
手順
1 オペレーション コードに 65 を設定します。
2 ファイルのポジション ブロックを渡します。
3 データ バッファーに拡張 Stat 構造体を格納します。各サブファンクションで必要な拡張 Stat 構造体の詳細については、以降のセクションを参照してください。
4 データ バッファー長を指定します。
5 キー番号に 0 を設定します。
サブファンクション 1：拡張ファイル情報
入力ポジション ブロックで指定されたファイルの場合、このサブファンクションは、指定データ ファイルと関連付けられたエクステンション ファイルについての情報を返します。返される情報には、存在するエクステンション ファイルの数、関数によって返された番号、および返されたファイルの名前が含まれます。
入力データ バッファー構造体
エクステンション ファイルに関する情報を取得するには、データ バッファーに拡張ファイル ディスクリプターを次のとおりに作成する必要があります。
表 30 拡張ファイル ディスクリプター
要素 | 長さ（バイト単位） | 説明 |
識別バイト | 4 | Stat Extended 呼び出しのタイプ。Extended Stat 呼び出しを示す 0x45、0x78、0x53、0x74 の 4 バイトを指定します。これらは ASCII の ExSt、または Intel 型、LoHi およびリトル エンディアン方式のハードウェアの値 0x74537845 に相当します。 |
サブファンクション | 4 | Stat Extended 呼び出しのタイプ。0x00000001 を指定します。 |
名前空間 | 4 | ファイルの命名規則。0x00000000 を指定します。 |
ファイルの最大数 | 4 | 返されるファイル名の最大数。この値には、拡張ファイルを構成するエクステンション ファイルの数を超える値を設定できます（拡張ファイルには最大 32 個のエクステンション ファイルが含まれます）。 |
先頭ファイルのシーケンス | 4 | 返される先頭のファイル名のシーケンス番号。ベース ファイルから始めるには 0 を指定し、先頭のエクステンション ファイルから始めるには 1 を指定します（以下同様）。エクステンション ファイルの数を超える値を指定すると、トランザクショナル インターフェイスからステータス コード 0 が返されますが、ファイル名は何も返されません。 |
バッファー スペース | n | 戻りデータ用に余分な空き領域を確保することができます。ステータス コード 22 が返された場合は、もっと大きなデータ バッファー サイズを指定してオペレーションを再試行してください。 |
出力データ バッファー構造体
拡張ファイル サブファンクションの場合、トランザクショナル インターフェイスではデータ バッファー長パラメーターの値が更新され、表
31 で説明されているような拡張ファイル構造体がデータ バッファーに返されます。
表 31 拡張ファイルの戻りバッファー
要素 | 長さ（バイト単位） | 説明 |
ファイル数 | 4 | 拡張ファイルを構成するオペレーティング システム ファイルの数。 |
エクステンション ファイル数 | 4 | 返されたエクステンション ファイルの数。 |
ファイル名部分（返された各ファイル名について繰り返される） |
ファイル名の長さ | 4 | エクステンション ファイル名の長さ。 |
ファイル名 | n | エクステンション ファイル名。 |
サブファンクション 2：システム データ情報
入力ポジション ブロックで指定されたファイルの場合、このサブファンクションは、ファイルに定義されたシステム キーがあるかどうか、また、そのファイルはログ可能（トランザクション一貫性保守が可能）であるかどうかに関する情報を返します。
入力データ バッファー構造体
ファイルでのシステム データの使用に関する情報を取得するには、データ バッファーにシステム データ ディスクリプターを次のとおりに作成する必要があります。
表 32 システム データ ディスクリプター
要素 | 長さ（バイト単位） | 説明 |
識別バイト | 4 | Extended Stat 呼び出しのための一意な識別子。 ExSt を指定します。表 30 を参照してください。 |
サブファンクション | 4 | Stat Extended 呼び出しのタイプ。0x00000002 を指定します。 |
出力データ バッファー構造体
システム データ サブファンクションの場合、トランザクショナル インターフェイスでは次のようなシステム データ構造体がデータ バッファーに返されます。
表 33 システム データの戻りバッファー
要素 | 長さ（バイト単位） | 説明 |
システム データを持つ | 1 | ファイルのレコードにシステム定義のログ キー（システム データとも言います）が含まれているかどうかを示します。1 = Yes、0 = No。 |
ログ キーを持つ | 1 | システム定義のログ キーが現在使用されているか、それとも削除されているかどうかを示します。1 = Yes、0 = No（削除された）。 |
ログ可能 | 1 | トランザクション一貫性保守を実現するために使用できる重複のないキーがファイルにあるかどうかを示します。このキーは、ユーザー定義の重複のないキーか、システム定義のログ キーのいずれかになります。1 = Yes、0 = No。 |
ログ キー番号 | 1 | トランザクショナル インターフェイスでトランザクション ログ キーとして現在使用されているキー番号。システム定義のログ キーがトランザクション ログ キーとして使用されている場合、この値は 125 になります。 |
システム データのサイズ | 2 | システム定義のログ キーのサイズで、8 になります。 |
システム データのバージョン | 2 | データベース エンジンのメジャー バージョンを含んでいる 2 バイト フィールド。たとえば、バージョン 9.x ならば 0x0009、バージョン 10.x ならば 0x000a となります。 |
サブファンクション 3：重複レコードによる競合情報
入力ポジション ブロックで指定されたファイルの場合、このサブファンクションは、指定データ ファイルと関連付けられたエクステンション ファイルについての情報を返します。返される情報には、直前の失敗した挿入または更新操作でステータス コード 5（重複キー）の発生原因となった、レコード アドレスおよびキー番号が含まれます。
入力データ バッファー構造体
一番最近ステータス コード 5（重複キー）を発生させたレコード アドレスおよびキー番号に関する情報を取得するには、データ バッファーに重複レコード情報ディスクリプターを次のとおりに作成する必要があります。
表 34 重複レコードによる競合ディスクリプター
要素 | 長さ（バイト単位） | 説明 |
識別バイト | 4 | Extended Stat 呼び出しのための一意な識別子。 ExSt を指定します。表 30 を参照してください。 |
サブファンクション | 4 | Stat Extended 呼び出しのタイプ。0x00000003 を指定します。 |
出力データ バッファー構造体
システム データ サブファンクションの場合、トランザクショナル インターフェイスでは次のようなシステム データ構造体がデータ バッファーに返されます。
表 35 重複レコードによる競合の戻りバッファー
要素 | 長さ（バイト単位） | 説明 |
重複レコード アドレス | 4 | 重複するキー値を含んでいるレコードの物理アドレス。 |
キー番号 | 4 | 重複する値を含んでいるキーのキー番号。 |
サブファンクション 4：ファイル情報
入力ポジション ブロックで指定されたファイルの場合、このサブファンクションは、指定データ ファイルと関連付けられたエクステンション ファイルについての情報を返します。返される情報には次のものが含まれます。トランザクショナル インターフェイスがファイルの識別に使用する内部ファイル ID、現在開いているファイル ハンドル数、ファイルが前回開かれたときのタイムスタンプ、およびファイル プロパティを示すさまざまなフラグがあります。
入力データ バッファー構造体
開いているファイルに関する情報を取得するには、データ バッファーにファイル情報ディスクリプターを次のとおりに作成する必要があります。
表 36 ファイル情報ディスクリプター - 開いているファイル
要素 | 長さ（バイト単位） | 説明 |
識別バイト | 4 | Extended Stat 呼び出しのための一意な識別子。 ExSt を指定します。表 30 を参照してください。 |
サブファンクション | 4 | Stat Extended 呼び出しのタイプ。0x00000004 を指定します。 |
バッファー スペース | 12 | 戻り情報に必要な追加バイト。 出力データ バッファー構造体を参照してください。ファイル情報サブファンクションの場合、トランザクショナル インターフェイスではデータ バッファーにファイル情報構造体が返されます。 |
出力データ バッファー構造体
ファイル情報サブファンクションの場合、トランザクショナル インターフェイスでは次のようなファイル情報構造体がデータ バッファーに返されます。
表 37 ファイル情報構造体 - 開いているファイル
要素 | 長さ（バイト単位） | 説明 |
ファイル ID | 4 | トランザクショナル インターフェイスがファイルを識別するために使用する重複のない番号。 |
ハンドル数 | 4 | トランザクショナル インターフェイスがこのファイルで開いている現在のハンドル数。 |
開かれたときのタイムスタンプ | 4 | トランザクショナル インターフェイスが物理ファイルを前回開いたときのシステム時間。システム時間は、世界協定時刻（UTC）を基に 1970 年 1 月 1 日の午前零時からの秒数で表されます。 |
ファイルの使用回数 | 4 | 各チェックポイントまたはシステム トランザクションごとにこの数が増加します。また使用回数は FCR にも置かれます。ここで返される数は、トランザクショナル インターフェイスのキャッシュ内で表されるファイルの使用回数です。チェックポイントを開始すると、この数が増加します。 |
フラグ | 4 | さまざまな値を設定できる 4 バイトのビットマップ。設定可能な値の説明については、次の表を参照してください。将来的にはさらに多くのフラグが追加されます。 |
フラグ フィールドに使用できる値については、次の表で説明します。
表 38 ファイル情報フラグ
値 | 名前 | 説明 |
0x00000001 | 明示的ロック | 現在ファイル上で明示的ロックがあります。 |
0x00000002 | クライアント トランザクション | 現在ファイル上で、クライアント トランザクションが少なくとも 1 つ開いています。 |
0x00000004 | 読み取り専用 | ファイルはトランザクショナル インターフェイスによって読み取り専用で開かれています。これは CD-ROM ドライブまたは読み取り専用ディレクトリです。 |
0x00000008 | Continuous オペレーション | ファイルは現在 Continuous オペレーション モードです。 |
0x00000010 | 参照整合性 | ファイルには参照整合性制約が設定されています。 |
0x00000020 | オーナー読み取り/書き込み | ファイルには読み取り/書き込みのオーナー ネームが割り当てられています。ファイルの読み取り/書き込みにはオーナー ネームが要求されます。 |
0x00000040 | オーナー読み取り OK | 書き込みを行う場合にのみ要求されるオーナー ネームを持ちます。読み取りは、オーナー ネームなしで行うことができます。 |
0x00000080 | 不正なオーナーでのオープン | このファイルには読み取り OK のオーナー ネームが割り当てられています。ハンドルが不正なオーナー ネームで開かれました。 |
0x00000100 | オーナー暗号化 | ファイルにはオーナー ネームの暗号化フラグが設定されています。このフラグは、ファイル内のすべてのページは暗号化されており、テキスト エディターでは読み取れないことを意味します。 |
サブファンクション 5：ゲートウェイ情報
入力ポジション ブロックで指定されたファイルの場合、このサブファンクションは、ファイルの制御を行うゲートウェイ エンジンについての情報を返します。
入力データ バッファー構造体
指定されたファイルの処理を行うゲートウェイ エンジンに関する情報を取得するには、データ バッファーにゲートウェイ情報ディスクリプターを次のとおりに作成する必要があります。
表 39 ゲートウェイ情報ディスクリプター
要素 | 長さ（バイト単位） | 説明 |
識別バイト | 4 | Extended Stat 呼び出しのための一意な識別子。 ExSt を指定します。表 30 を参照してください。 |
サブファンクション | 4 | Stat Extended 呼び出しのタイプ。0x00000005 を指定します。 |
バッファー スペース | 最低でも 80 | 戻り情報に必要な追加バイト。詳細については、 出力データ バッファー構造体を参照してください。 |
出力データ バッファー構造体
ゲートウェイ情報サブファンクションの場合、トランザクショナル インターフェイスではデータ バッファー長パラメーターが更新され、次のようなゲートウェイ情報構造体がデータ バッファーに返されます。
表 40 ファイル情報構造体 - ゲートウェイ情報
要素 | 長さ（バイト単位） | 説明 |
メジャー バージョン | 4 | エンジンのメジャー バージョン。たとえば、バージョン 7 または 8 などです。 |
マイナー バージョン | 4 | エンジンのマイナー バージョン。たとえば、05 または 82 などです。 |
パッチ レベル | 4 | エンジンのパッチ レベル。たとえば、1、2、または 3 になります。 |
プラットフォーム | 4 | エンジンが動作しているオペレーティング システム プラットフォーム。 |
サーバー名 | 64 | データベース エンジンが動作しているマシンの名前を示すヌル終端文字列。Btrieve API 呼び出しによって返されるデータ バッファー長には、サーバー名とヌル終端文字を含めた戻りデータの実際の長さが格納されます。 |
サブファンクション 6：ロック オーナーの識別
入力ポジション ブロックで指定されたファイルの場合、このサブファンクションは、一番最近ファイルのアクセス時にステータス コード 84 または 85 を発生させた原因に関する情報を返します。
入力データ バッファー構造体
ステータス 84 または 85 の原因に関する情報を取得するには、データ バッファーにロック オーナー情報ディスクリプターを次のとおりに作成する必要があります。
表 41 ロック オーナー情報ディスクリプター
要素 | 長さ（バイト単位） | 説明 |
識別バイト | 4 | Extended Stat 呼び出しのための一意な識別子。 ExSt を指定します。表 30 を参照してください。 |
サブファンクション | 4 | Stat Extended 呼び出しのタイプ。0x00000006 を指定します。 |
バッファー スペース | 最低でも 96 | 戻り情報に必要な追加バイト。詳細については、 サブファンクション 7：セキュリティ情報を参照してください。 |
出力データ バッファー構造体
ロック オーナー情報サブファンクションの場合、トランザクショナル インターフェイスではデータ バッファー長パラメーターが更新され、次のようなロック オーナー情報構造体がデータ バッファーに返されます。
表 42 ロック オーナー情報の戻りバッファー
要素 | 長さ（バイト単位） | 説明 |
クライアント ID | 16 | ブロックしているクライアントの 16 バイトのクライアント ID。 |
フラグ | 4 | 発生した競合のタイプを示すフラグを含む 4 バイトのビットマップ。各フラグの値の説明については、次の表を参照してください。 |
トランザクション内での時間 | 4 | ブロックしたクライアントがトランザクション中にロックするミリ秒数。これは、オペレーションを再試行するかどうかを決定するのに役立ちます。 |
キー番号 | 4 | 競合がキー ページ上で発生した場合、この要素はその競合に関与しているキーを示します。この情報を確認すれば、データベースの設計で予測される競合を減らすのに役立ちます。 |
トランザクション レベル | 4 | この数がゼロ以外の場合、ブロックしているクライアントは現在トランザクション中です。いくつかのページやレコードはトランザクションが完了するまでロックされるので、この情報はオペレーションを再試行するかどうかを決定するのに役立ちます。 |
予約済み | 8 | 今後の使用に備えて予約されています。ブロックしているクライアントに関して有用だと思われる情報がある場合は、Pervasive Software までご連絡ください。 |
表示名 | 64 | これはヌルで終了する文字列です。これは Monitor 内で各クライアントごとに表示される識別名と同じです。最低でも現在の表示名の長さの最大値である 64 バイトを使用してください。Btrieve API 呼び出しによって返されるデータ バッファー長には、表示名とヌル終端文字を含めた戻りデータの実際の長さが格納されます。 |
以前にブロックしていたクライアントの記録がトランザクショナル インターフェイスにない場合、出力データ バッファー長はゼロに設定されます。
フラグ フィールドに使用できる値については、次の表で説明します。
表 43 ロック オーナーのフラグ
値 | 名前 | 説明 |
0x00000001 | 暗黙ロック | ブロックしたクライアントは暗黙ロックを使用しています。 |
0x00000002 | 明示的ロック | ブロックしたクライアントは明示的ロックを使用しています。 |
0x00000010 | ファイル ロック | ブロックしたクライアントはファイル ロックを使用しています。 |
0x00000020 | ページ ロック | ブロックしたクライアントはページ ロックを使用しています。 |
0x00000040 | レコード ロック | ブロックしたクライアントはレコード ロックを使用しています。 |
0x00000100 | データ ページ | 競合がページ ロックの場合、このフラグは競合がデータ ページで発生したことを示します。 |
0x00000200 | キー ページ | 競合がページ ロックの場合、このフラグは競合がキー ページで発生したことを示します。 |
0x00000400 | 可変ページ | 競合がページ ロックの場合、このフラグは競合が可変ページで発生したことを示します。 |
0x00000800 | 同じプロセス | このフラグが設定された場合、ブロックしているクライアント ID の最初の 12 バイトと、ブロックされたクライアント（Stat Extended 呼び出しを発行したクライアント）の最初の 12 バイトが同じです。この場合、同じコンピューター上の同じプロセスからブロックした 2 つのクライアントがあることを意味します。Btrieve API 呼び出しを行うシングル スレッドのアプリケーションの場合は、このオペレーションを再試行しても役立ちません。ブロックしている動作を終了または中止する必要があります。 |
0x00001000 | 書き込みノー ウェイト | ブロックしたクライアントがバイアス 500 を使用していることを示します。 |
0x00002000 | 書き込み保持 | ブロックしたクライアントが、ページへの変更を行って、そのトランザクションが終了するまでページ全体をロックしたことを示します。この状況は、変更によってキー エントリが別のページへ移動した場合に、キー ページの暗黙ロックで発生します。 |
0x00004000 | 読み取りノー ウェイト | 明示的レコード ロックの場合、このフラグは、ブロックしたクライアントがロック バイアス 200 または 400 のいずれかを使用していることを示します。 |
0x00008000 | 複数読み取り | 明示的レコード ロックの場合、このフラグは、ブロックしたクライアントがロック バイアス 300 または 400 のいずれかを使用していることを示します。 |
サブファンクション 7：セキュリティ情報
このサブファンクションは、クライアントが現在のファイルにアクセスするために、どのように認証および許可されたかについての情報を返します。セキュリティに使用されている現在のデータベースに関する情報も示します。
入力データ バッファー構造体
このハンドルが持っているどのアクセス権がどのように認証されたかについてセキュリティ情報を取得するには、データ バッファーにセキュリティ情報ディスクリプターを次のとおりに作成する必要があります。
表 44 セキュリティ情報ディスクリプター
要素 | 長さ（バイト単位） | 説明 |
識別バイト | 4 | Stat Extended 呼び出しのタイプ。0x45785374 を指定します。（これは、ASCII の ExSt に相当します。） |
識別バイト | 4 | Stat Extended 呼び出しのタイプ。0x00000007 を指定します。 |
バッファー スペース | 最低でも 142 | 戻り情報に必要な追加バイト。詳細については「結果」を参照してください。 |
出力データ バッファー構造体
セキュリティ情報サブファンクションの場合、MicroKernel ではデータ バッファー長パラメーターが更新され、次のようなセキュリティ情報構造体がデータ バッファーに返されます。
表 45 セキュリティ情報の戻りバッファー
要素 | 長さ（バイト単位） | 説明 |
ハンドルのフラグ | 4 | このハンドルのセキュリティに使用されているメソッドを示すフラグを含む 4 バイトのビットマップ。各フラグの値の説明については、次の表を参照してください。 |
ハンドルのフラグ | 4 | このクライアントの、現在のデフォルト データベースのセキュリティに使用されているメソッドを示すフラグを含む 4 バイトのビットマップ。各フラグの値の説明については、次の表を参照してください。 |
アクセス権 | 4 | これらは、このハンドルを使用するクライアントに与えられているアクセス権です。各フラグの値の説明については、アクセス権の表を参照してください。 |
ハンドル データベース名のバッファー サイズ | 2 | ヌルで終わるハンドル データベース名文字列の格納に使用されるバッファーの長さ。 |
ハンドル テーブル名のバッファー サイズ | 2 | ヌルで終わるハンドル テーブル名文字列の格納に使用されるバッファーの長さ。 メモ：テーブル名は、ファイルがデータベースにバインドされない限りわかりません（たとえば参照制約）。つまり、ファイルは、ファイルのテーブル名で参照される URI 接続文字列を使用して開かれています。URI 接続文字列の詳細については、『 Pervasive PSQL Programmer's Guide』の データベース URI を参照してください。 |
ハンドル ユーザー名のバッファー サイズ | 2 | ヌルで終わるハンドル ユーザー名文字列の格納に使用されるバッファーの長さ。 |
現在のデータベース名のバッファー サイズ | 2 | ヌルで終わる現在のデータベース名文字列の格納に使用されるバッファーの長さ。 |
現在のユーザー名のバッファー サイズ | 2 | ヌルで終わる現在のユーザー名文字列の格納に使用されるバッファーの長さ。 |
ハンドル データベース名 | 可変 | このハンドルのセキュリティを確立するために使用されるデータベース名。 |
ハンドル テーブル名 | 可変 | このハンドルと関連付けられているテーブル名。 |
ハンドル ユーザー名 | 可変 | このハンドルのセキュリティを確立するために使用されるユーザー名。 |
現在のデータベース名 | 可変 | このクライアントの、現在のデフォルトのデータベース名。 |
現在のユーザー名 | 可変 | このクライアントの、現在のデフォルト データベースに関連付けられているユーザー名。 |
2 つの Flags フィールドで使用できる値については、以下の表で説明します。
表 46 セキュリティ フラグ
値 | 名前 | 説明 |
0x00000001 | 信頼される | このハンドルは信頼されています。割り当てられたデータベースはありません。 |
0x00000002 | 暗黙 | データベース ログインは暗黙です - 開いている間。 |
0x00000004 | 明示的 | データベース ログインは明示的です - Btrieve Login が実行されました。 |
0x00000008 | データベースによる認証 | 認証はデータベース セキュリティによって行われました。このフラグが設定されていなければ、認証はオペレーティング システムのセキュリティによって行われました。 |
0x00000010 | データベースによる許可 | 許可はデータベース セキュリティによって行われました。このフラグが設定されていなければ、許可はオペレーティング システムのセキュリティによって行われました。 |
0x00000020 | Windows 名前付きパイプ | 認証がオペレーティング システムによるものである場合、これはセキュリティに NT 名前付きパイプが使用されたことを示します。 |
0x00000040 | ワークグループ | 認証がオペレーティング システムによるものである場合、これはワークグループ エンジン式のセキュリティが行われたことを示します。つまり、認証も許可も行われていないということです。 |
0x00000080 | Btpasswd | 認証が Linux オペレーティング システムによるものである場合、これは etc/btpasswd ファイルが使用されたことを示します。 |
0x00000100 | PAM | 認証が Linux オペレーティング システムによるものである場合、これは PAM 認証が使用されたことを示します。 |
0x00000200 | RTSS Complete | 認証がオペレーティング システムによるものである場合、これは、"Complete" に設定された RTSS を使用して認証が行われたことを示します。 |
0x00000400 | RTSS Preauthorized | 認証がオペレーティング システムによるものである場合、これは、"Preauthorized" に設定された RTSS を使用して認証が行われたことを示します。 |
0x00000800 | RTSS Disabled | 認証がオペレーティング システムによるものである場合、これは、"Disabled" に設定された RTSS を使用して認証が行われたことを示します。 |
表 47 アクセス権フラグ
値 | 名前 | 説明 |
0x00000000 | No Rights | データベース オブジェクトに対する権限がありません。アクセス権は与えられていません。 |
0x00000001 | Open | ファイルを開くために与えられるアクセス権。これは、レコードの読み取りが可能であることも意味します。 |
0x00000002 | Insert | レコードを挿入するために与えられるアクセス権。 |
0x00000004 | Update | レコードを更新するために与えられるアクセス権。 |
0x00000008 | Create | このファイルを作成するために与えられるアクセス権。 |
0x00000010 | Delete | レコードを削除するために与えられるアクセス権。 |
0x00000020 | Execute | SQL でストアド プロシージャを実行するために与えられるアクセス権。 |
0x00000040 | Alter | SQL でこのファイルを変更するために与えられるアクセス権。 |
0x00000080 | Refer | SQL でこのファイルを参照するために与えられるアクセス権。 |
0x00000100 | Create View | SQL でこのファイルのビューを作成するために与えられるアクセス権。 |
0x00000200 | Create Stored Procedure | SQL でこのファイルのストアド プロシージャを作成するために与えられるアクセス権。 |
結果
Stat Extended オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。
3 | ファイルが開いていません。 |
06 | キー番号パラメーターが不正です。 |
22 | データ バッファー パラメーターが短すぎます。 |
62 | ディスクリプターが不正です。 |
Step First（33）
Step First オペレーション（B_STEP_FIRST）では、ファイル内の先頭の物理レコードを取得します。トランザクショナル インターフェイスではこのレコードを取得するためにキー パスは使用されません。
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
前提条件
対象となるファイルが開いていることが必要です。
手順
1 オペレーション コードに 33 を設定します。オプションで、ロック バイアスも指定できます。
•+100 - 単一レコード ウェイト ロック
•+200 - 単一レコード ノーウェイト ロック
•+300 - 複数レコード ウェイト ロック
•+400 - 複数レコード ノーウェイト ロック
ロックの詳細については、『Pervasive PSQL Programmer's Guide』を参照してください。
2 ファイルのポジション ブロックを渡します。
3 データ バッファー長に取得するレコードの長さ以上の値を設定します。
結果
Step First オペレーションが正常に終了した場合、トランザクショナル インターフェイスではファイル内の先頭の物理レコードがデータ バッファーに返され、返されたバイト数がデータ バッファー長に設定されます。
Step First オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。
3 | ファイルが開いていません。 |
9 | オペレーションが EOF（end-of-file）を検出しました。 |
22 | データ バッファー パラメーターが短すぎます。 |
ポジショニング
Step First オペレーションを実行すると、論理カレンシーが消去されます。取得したレコードを現在の物理レコードとして使用し、物理カレンシーが設定されます。物理位置の直前は、ファイルの先頭よりも前を指すことになります。
Step Last（34）
Step Last オペレーション（B_STEP_LAST）では、ファイル内の末尾の物理レコードを取得します。トランザクショナル インターフェイスではこのレコードを取得するためにキー パスは使用されません。
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
前提条件
対象となるファイルが開いていることが必要です。
手順
1 オペレーション コードに 34 を設定します。オプションで、ロック バイアスも指定できます。
•+100 - 単一レコード ウェイト ロック
•+200 - 単一レコード ノーウェイト ロック
•+300 - 複数レコード ウェイト ロック
•+400 - 複数レコード ノーウェイト ロック
ロックの詳細については、『Pervasive PSQL Programmer's Guide』を参照してください。
2 ファイルのポジション ブロックを渡します。
3 データ バッファー長に取得するレコードの長さ以上の値を設定します。
結果
Step Last オペレーションが正常に終了した場合、トランザクショナル インターフェイスではファイル内の末尾の物理レコードがデータ バッファーに返され、返されたバイト数がデータ バッファー長に設定されます。
Step Last オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。
3 | ファイルが開いていません。 |
9 | オペレーションが EOF（end-of-file）を検出しました。（ファイルが空の場合） |
22 | データ バッファー パラメーターが短すぎます。 |
ポジショニング
Step Last オペレーションを実行すると、論理カレンシーが消去されます。取得したレコードを現在の物理レコードとして使用し、物理カレンシーが設定されます。物理位置の直後は、ファイルの末尾よりも後を指すことになります。
Step Next（24）
Step Next オペレーション（B_STEP_NEXT）では、次の物理位置として示されるレコードを取得します。トランザクショナル インターフェイスではこのレコードを取得するためにキー パスは使用されません。
Step Next オペレーションを任意の Get または Step オペレーションの直後に実行すると、前のオペレーションで取得されたレコードの物理的に次にあるレコードが返されます。
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
前提条件
対象となるファイルが開いていることが必要です。
手順
1 オペレーション コードに 24 を設定します。オプションで、ロック バイアスも指定できます。
•+100 - 単一レコード ウェイト ロック
•+200 - 単一レコード ノーウェイト ロック
•+300 - 複数レコード ウェイト ロック
•+400 - 複数レコード ノーウェイト ロック
ロックの詳細については、『Pervasive PSQL Programmer's Guide』を参照してください。
2 ファイルのポジション ブロックを渡します。
3 データ バッファー長に取得するレコードの長さ以上の値を設定します。
結果
Step Next オペレーションが正常に終了した場合、トランザクショナル インターフェイスではファイル内の次の物理レコードがデータ バッファーに返され、返されたバイト数がデータ バッファー長に設定されます。
Step Next オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。
3 | ファイルが開いていません。 |
9 | オペレーションが EOF（end-of-file）を検出しました。 |
22 | データ バッファー パラメーターが短すぎます。 |
ポジショニング
Step Next オペレーションを実行しても、論理カレンシーは確立しません。取得したレコードを現在の物理レコードとして使用し、物理カレンシーが設定されます。
Delete オペレーション（4）の直後に Step Next オペレーションを発行すると、Delete の前のオペレーションで次の物理レコードとして確立されたレコードが返されます。
Open オペレーション（0）の直後に Step Next オペレーションを発行すると、ファイル内の先頭レコードが返されます。
Step Next Extended（38）
Step Next Extended オペレーション（B_STEP_NEXT_EXT）では、物理位置の直後からファイルの末尾へ向かって 1 つまたは複数のレコードを検索します。検索したレコードがフィルター条件を満たしているかどうかをチェックした上で、条件を満たすレコードだけを取得します。フィルター条件は論理式の形を取り、キー フィールドのみに制限されません。
Step Next Extended オペレーションでは、既存のレコードの中から指定したフィールドを抽出し、抽出したフィールドだけを含む新しいレコードのセットを返すこともできます。
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
前提条件
•対象となるファイルが開いていることが必要です。
•次の物理位置を確立しておくことが必要です。（たとえば、Delete オペレーションの次に Step Next Extended オペレーションを実行することはできません。）
手順
1 オペレーション コードに 38 を設定します。オプションで、ロック バイアスも指定できます。
•+100 - 単一レコード ウェイト ロック
•+200 - 単一レコード ノーウェイト ロック
•+300 - 複数レコード ウェイト ロック
•+400 - 複数レコード ノーウェイト ロック
ロックの詳細については、『Pervasive PSQL Programmer's Guide』を参照してください。
2 ファイルのポジション ブロックを渡します。
3 入力データ バッファーと戻りデータ バッファーのどちらか大きい方を格納できるように、十分な長さのデータ バッファーを指定します。表
21 に示す構造体に従って、データ バッファーを初期化します。
4 上記の手順に従って、データ バッファー長に適切な値を指定します。
トランザクショナル インターフェイスではバッファーを用意して、Extended オペレーションのワークスペースとして使用できるようにします。このバッファーのサイズは、［拡張オペレーション バッファー サイズ］オプションを使って構成します。データ バッファー構造体、取得される最長のレコード、およびリクエスターのオーバーヘッドの 355 バイト、これらの合計が設定したバッファー サイズを超えることはできません。（リクエスターのオーバーヘッドは、DOS ワークステーションのエンジンには適用できません。）
詳細
Step Next Extended オペレーションの「詳細」の内容は、Get Next Extended オペレーションと同じです。詳しくは
詳細をご覧ください。
結果
Step Next Extended オペレーションが正常に終了した場合、トランザクショナル インターフェイスでは表
22 に示すとおり、取得された 1 つまたは複数のレコードに含まれる 1 つまたは複数のフィールドがデータ バッファーに返されます。さらにトランザクショナル インターフェイスから、データ バッファー長パラメーターには、データ バッファーに返されたバイト数が設定されます。
Step Next Extended オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。
3 | ファイルが開いていません。 |
9 | オペレーションが EOF（end-of-file）を検出しました。 |
22 | データ バッファー パラメーターが短すぎます。 |
60 | 指定されたリジェクト カウントに達しました。 |
61 | 作業領域が小さすぎます。 |
62 | ディスクリプターが不正です。 |
64 | フィルター制限に達しました。 |
65 | フィールド オフセットが不正です。 |
82 | トランザクショナル インターフェイスがポジショニングを失いました。 |
134 | トランザクショナル インターフェイスがインターナショナル ソート規則（ISR）を読み取れません。 |
135 | 指定されたインターナショナル ソート規則（ISR）テーブルは破損しているか、または不正です。 |
136 | トランザクショナル インターフェイスは、指定されたオルタネート コレーティング シーケンスをファイル内に見つけられません。 |
トランザクショナル インターフェイスでは、0 以外のステータス コードが返されても、有効なデータがデータ バッファーに返されることがあります。ただしこの場合、返された最後のレコードは不完全なものである可能性があります。データ バッファー長パラメーターに 0 を超える値が返されている場合は、データ バッファーに抽出されたデータを確認してください。
レコードが短すぎてフィールドの一部しか使用されない場合は、トランザクショナル インターフェイスからは、一部のみ使用されたフィールドも含めて、レコードから抽出できたもののみを返します。部分フィールドが抽出される最後のフィールドである場合、トランザクショナル インターフェイスではオペレーションが続行されます。そうでない場合、トランザクショナル インターフェイスではオペレーションは中止され、ステータス コード 22 が返されます。
たとえば、2 件の可変長レコードから 3 つのフィールドを取得する Step Next Extended オペレーションを考えてみましょう。最初のレコードは 55 バイトで、2 番目のレコードは 50 バイトだとします。取得するフィールドは次のように定義されています。
•フィールド 1 はオフセット 2 から始まり、2 バイト長です。
•フィールド 2 はオフセット 45 から始まり、10 バイト長です。
•フィールド 3 はオフセット 6 から始まり、2 バイト長です。
トランザクショナル インターフェイスで Step Next Extended オペレーションが実行されるとき、最初のレコードは問題なく返されます。しかし、2 番目のレコードのフィールド 2 から 10 バイトを抽出しようとすると、トランザクショナル インターフェイスではオフセット 45 とレコードの末尾のオフセット 49 の間では 5 バイトしか取得できないことが検出されます。この時点で、トランザクショナル インターフェイスではフィールド 2 の不足している 5 バイト分は詰め込まれないため、フィールド 3 は抽出できなくなります。その代わりに、トランザクショナル インターフェイスからステータス コード 22 が返され、フィールド 1 全体とフィールド 2 の先頭 5 バイトが戻りデータ バッファーに格納されます。
ポジショニング
Step Next Extended オペレーションを実行しても、論理カレンシーは確立しませんが、検索された最後のレコードが現在の物理レコードになります。なお、このレコードは取得されているとは限りません。このレコードは、フィルター条件を満たして取得されたレコードか、またはフィルター条件を満たさないために拒否されたレコードのいずれかです。
メモ： トランザクショナル インターフェイスでは、Step Next Extended オペレーションの後に Delete または Update オペレーションを実行することはできません。現在のレコードは検索された最後のレコードであるため、アプリケーションには、意図したレコードを適切に削除または更新しているかどうかを確認する方法がありません。
Step Previous（35）
Step Previous オペレーション（B_STEP_PREVIOUS）では、前の物理位置として示されるレコードを取得します。トランザクショナル インターフェイスでは Step Previous オペレーションでレコードを取得するためにインデックス パスは使用されません。
Step Previous オペレーションを任意の Get または Step オペレーションの直後に実行すると、前のオペレーションで取得されたレコードの物理的に前にあるレコードが返されます。
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
前提条件
•対象となるファイルが開いていることが必要です。
•前の物理位置を確立しておくことが必要です（たとえば、Delete オペレーションの次に Step Previous オペレーションを実行することはできません）。
手順
1 オペレーション コードに 35 を設定します。オプションで、ロック バイアスも指定できます。
•+100 - 単一レコード ウェイト ロック
•+200 - 単一レコード ノーウェイト ロック
•+300 - 複数レコード ウェイト ロック
•+400 - 複数レコード ノーウェイト ロック
ロックの詳細については、『Pervasive PSQL Programmer's Guide』を参照してください。
2 ファイルのポジション ブロックを渡します。
3 データ バッファー長に取得するレコードの長さ以上の値を設定します。
結果
Step Previous オペレーションが正常に終了した場合、トランザクショナル インターフェイスではファイル内の前の物理レコードがデータ バッファーに返され、返されたバイト数がデータ バッファー長に設定されます。
このオペレーションが正常に実行されなかった場合、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。
3 | ファイルが開いていません。 |
9 | オペレーションが EOF（end-of-file）を検出しました。（ファイルの先頭で実行した場合） |
22 | データ バッファー パラメーターが短すぎます。 |
ポジショニング
Step Previous オペレーションを実行しても、論理カレンシーは確立しません。取得したレコードを現在の物理レコードとして使用し、物理カレンシーが設定されます。
Step Previous Extended（39）
Step Previous Extended オペレーション（B_STEP_PREVIOUS_EXT）では、物理位置の直前からファイルの先頭へ向かって 1 つまたは複数のレコードを検索します。検索したレコードがフィルター条件を満たしているかどうかをチェックした上で、条件を満たすレコードだけを取得します。フィルター条件は論理式の形を取り、キー フィールドのみに制限されません。
Step Previous Extended オペレーションでは、既存のレコードの中から指定したフィールドを抽出し、抽出したフィールドだけを含む新しいレコードのセットを返すこともできます。
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
前提条件
•対象となるファイルが開いていることが必要です。
•前の物理位置を確立しておくことが必要です（たとえば、Delete オペレーションの次に Step Previous Extended オペレーションを実行することはできません）。
手順
1 オペレーション コードに 39 を設定します。オプションで、ロック バイアスも指定できます。
•+100 - 単一レコード ウェイト ロック
•+200 - 単一レコード ノーウェイト ロック
•+300 - 複数レコード ウェイト ロック
•+400 - 複数レコード ノーウェイト ロック
ロックの詳細については、『Pervasive PSQL Programmer's Guide』を参照してください。
2 ファイルのポジション ブロックを渡します。
3 入力データ バッファーと戻りデータ バッファーのどちらか大きい方を格納できるように、十分な長さのデータ バッファーを指定します。表
21 に示す構造体に従って、データ バッファーを初期化します。
4 上記の手順に従って、データ バッファー長に適切な値を指定します。
トランザクショナル インターフェイスではバッファーを用意して、Extended オペレーションのワークスペースとして使用できるようにします。このバッファーのサイズは、［拡張オペレーション バッファー サイズ］オプションを使って構成します。データ バッファー構造体、取得される最長のレコード、およびリクエスターのオーバーヘッドの 355 バイト、これらの合計が設定したバッファー サイズを超えることはできません。（リクエスターのオーバーヘッドは、DOS ワークステーションのエンジンには適用できません。）
詳細
このオペレーションでは、Get Next Extended オペレーションの場合と同じ入力データ バッファーおよび戻りデータ バッファーを使用します。詳しくは
詳細をご覧ください。
結果
このオペレーションでは、Step Next Extended オペレーションと同様の結果が返されます。詳しくは
結果をご覧ください。
ポジショニング
Step Previous Extended オペレーションを実行しても、論理カレンシーは確立しませんが、検索された最後のレコードが現在の物理レコードになります。なお、このレコードは取得されているとは限りません。このレコードは、フィルター条件を満たして取得されたレコードか、またはフィルター条件を満たさないために拒否されたレコードのいずれかです。
メモ： トランザクショナル インターフェイスでは、Step Previous Extended オペレーションの後に Delete または Update オペレーションを実行することはできません。現在のレコードは検索された最後のレコードであるため、アプリケーションには、意図したレコードを適切に削除または更新しているかどうかを確認する方法がありません。
Stop（25）
Stop オペレーション（B_STOP）では、クライアントに対していくつかの終了ルーチンを実行します。終了ルーチンには、すべてのロックを解除する、開いているファイルでそのクライアントに関連付けられているファイルをすべて閉じるなどのルーチンがあります。
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
手順
オペレーション コードに 25 を設定します。
結果
Stop オペレーションが正常に終了した場合、トランザクショナル インターフェイスでは次のような動作が実行されます。
1 実行中のトランザクションがすべて中止される。
2 クライアントによって保持されているすべてのロックが解除されます。
3 クライアントが開いているファイルがすべて閉じられます。
4 ほかのクライアント（トランザクショナル インターフェイスに登録されているほかのアプリケーション）が存在しない場合、トランザクショナル インターフェイスの設定にもよりますが、トランザクショナル インターフェイスの実行が終了し、いくつかのリソースが解放されます。
Stop オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから 0 以外のステータス コードが返されます。最もよくあるのはステータス コード 20（MicroKernel または Btrieve リクエスターが非アクティブ）です。このステータスは、トランザクショナル インターフェイスまたはリクエスターがロードされていないために発生します。
ポジショニング
Stop オペレーションを実行すると、開いているファイルがすべて閉じられるため、すべてのカレンシーが消去されます。
Unlock（27）
Unlock オペレーション（B_UNLOCK）では、明示的にロックされている 1 つまたは複数のレコード（つまり、ロック バイアス +100、+200、+300 または +400 を使ってロックされたレコード）のロックを解除します。Unlock オペレーションは指定したポジション ブロックで保持されているロックを解除するので、同一ファイルを複数回開いた場合は、ポジション ブロックごとに Unlock オペレーションを発行しなければ、レコードのロックは完全に解除されません。同様に、ファイル内のレコードに対しロックを保持している各クライアントが Unlock オペレーションを発行しなければ、レコードのロックは完全に解除されません。
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
前提条件
少なくとも 1 つのレコードがロックされていることが必要です。
手順
►単一レコード ロックを解除するには、次の手順に従います。
1 オペレーション コードに 27 を設定します。
2 ロックされたレコードを含むファイルのポジション ブロックを渡します。
3 キー番号に正の値またはゼロを設定します。
►複数レコード ロックが設定されている 1 つのレコードのロックを解除するには、まずそのレコードを対象に Get Position オペレーション（22）を発行し、ロックを解除するレコードの 4 バイト物理位置を取得します。その後、次の手順に従って Unlock オペレーションを発行します。
1 オペレーション コードに 27 を設定します。
2 ロックされたレコードを含むファイルのポジション ブロックを渡します。
3 トランザクショナル インターフェイスから返される 4 バイトの物理位置をデータ バッファーに格納します。
4 データ バッファー長に 4 を設定します。
5 キー番号パラメーターに -1 を設定します。
►ファイル上の複数レコード ロックをすべて解除するには、次の手順に従います。
1 オペレーション コードに 27 を設定します。
2 複数のロックを含むファイルのポジション ブロックを渡します。
3 キー番号パラメーターに -2 を設定します。
結果
Unlock オペレーションが正常に終了した場合、トランザクショナル インターフェイスではオペレーションで指定したロックがすべて解除されます。
Unlock オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから 0 以外のステータス コード、たいていはステータス コード 81 が返されます。
ポジショニング
Unlock オペレーションは、ポジショニングにまったく影響しません。
Update（3）
Update オペレーション（B_UPDATE）では、既存のレコードの情報を変更します。
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
メモ： NCC（No-currency-change：カレンシー変更なし）オプションを使用すると、Update オペレーションはキー バッファー パラメーターの値を更新しません。つまり、キー バッファー パラメーターには情報は返されません。
前提条件
•対象となるファイルが開いていることが必要です。
•ファイルの物理カレンシーを確立しておくことが必要です。（Extended Get、Extended Step、または Get Key オペレーションでも物理カレンシーは確立しますが、これらのオペレーションの後に Update オペレーションを実行することはできません。）
手順
1 オペレーション コードに 3 を設定します。
2 レコードを含むファイルのポジション ブロックを渡します。
3 データ バッファーに更新後のデータ レコードを格納します。
4 データ バッファー長に更新後のレコードの長さを設定します。
5 キー番号に、レコードの取得に使用したキー番号を設定します。NCC オプションを使用するには、キー番号に -1（0xFF）を指定します。システム定義のログ キー（システム データ）を使用するには、125 を指定します。
Get オペレーションの直後に NCC オプションを使用しない Update オペレーションを実行するとき、トランザクショナル インターフェイスでは Get オペレーションで取得したものとまったく同じキー番号を渡します。そうしないと、トランザクショナル インターフェイスでレコードは正常に更新されますが、更新後に実行する最初の Get オペレーションでステータス コード 7 が返されます。
結果
Update オペレーションが正常に終了した場合、トランザクショナル インターフェイスではファイル内に格納されているレコードがデータ バッファー内の新しい値を使って更新され、キー値の変更を反映してインデックスが調整されます。また、指定したキーの値がキー バッファーに返されます。NCC Update オペレーションでは、キー バッファー パラメーターの値は更新されません。
トランザクショナル インターフェイスでは、アプリケーションが更新するレコードに単一レコード ロックを設定している場合は、ロックが解除されます。しかし、複数レコード ロックは Update オペレーションを実行しても解除されません。
Update オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。
5 | レコードのキー フィールドに重複するキー値があります。 |
8 | 現在のポジションが不正です。 |
10 | キー フィールドは変更できません。 |
22 | データ バッファー パラメーターが短すぎます。 |
80 | トランザクショナル インターフェイスでレコード レベルの矛盾が発生しました。 |
ポジショニング
Update オペレーションも NCC Update オペレーションも、物理カレンシーには影響しません。
更新されたキーの値によってインデックス内のレコードが再配置される場合は、NCC オプションを使用しない Update オペレーションが論理カレンシーに影響を与えることがあります。たとえば、INTEGER キーの現在の論理レコードがそのキーに対して 1 という値を持つ場合を考えてみましょう。これと同じキーについて、次の論理レコードは 2 という値を持ちます。このとき 1 を 4 に更新すると、次の論理レコードが変わります。この例では、Update オペレーションの実行後、次の論理レコードは 4 よりも大きい値を持つことになります。
NCC Update オペレーションは論理カレンシーに影響しません。つまり、NCC Update オペレーションを実行したアプリケーションでは、ファイル内の論理位置は Update オペレーションを実行する前と変わらないということです。このような状況で、NCC Update オペレーションに続けて、Get Next（6）、Get Next Extended（36）、Get Previous（7）、および Get Previous Extended（37）などのオペレーションを実行すると、NCC Update オペレーション実行以前のアプリケーションの論理カレンシーに基づく値が返されます。
メモ： トランザクショナル インターフェイスでは、NCC Update オペレーションを実行しても、その結果として何の情報もキー バッファーには返されません。したがって、論理カレンシーの維持が必要なアプリケーションでは、NCC Update オペレーション後にキー バッファーの値を変更しないでください。変更すると、次の Get オペレーションの結果は予測できないものになります。
Update Chunk（53）
Update Chunk オペレーション（B_CHUNK_UPDATE）では、レコードの 1 つまたは複数の部分（チャンク）の情報を変更できます。また、既存のレコードに情報を追加してレコードを長くしたり、既存のレコードを指定したオフセットで切り詰めることもできます。
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
前提条件
•対象となるファイルが開いていることが必要です。
•ファイルの現在の物理レコードまたは論理レコードを確立しておくことが必要です。
メモ： Extended オペレーションまたは Get Key オペレーション（+50）でも必要な位置は確立しますが、これらのオペレーションの直後に Update Chunk オペレーションを発行することはできません。それは、これらのオペレーションでは単独のレコードが返されないからです。
手順
1 オペレーション コードに 53 を設定します。
2 レコードを含むファイルのポジション ブロックを渡します。
3 詳細の説明に従って、データ バッファーを指定します。
4 データ バッファー長に、データ バッファーに格納するバイト数以上の値を設定します。データ バッファー長の計算の詳細については、「詳細」を参照してください。
5 レコードの取得に使用したキー番号をキー番号パラメーターに設定します。システム定義のログ キー（システム データ）を使用するには、125 を指定します。
詳細
データ バッファーでは、次のチャンク ディスクリプターのいずれかを使用します。
•ランダム チャンク ディスクリプター - オペレーションに付き 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 |
ランダム チャンク ディスクリプターを定義するには、次の表に基づいてデータ バッファーに構造体を作成する必要があります。
表 48 ランダム チャンク ディスクリプター構造体
要素 | 長さ（バイト単位） | 説明 |
サブファンクション | 4 | チャンク ディスクリプターの種類。次のいずれかを指定します。 •0x80000000（直接ランダム チャンク ディスクリプター） - データ バッファーに直接格納されているチャンクを更新します。先頭のチャンクを更新するためのデータは、データ バッファー内の最後のチャンク定義（チャンク n）の直後に格納します。また、2 番目のチャンク データは先頭のチャンク データの直後に、と順次格納します。 •0x80000001（間接ランダム チャンク ディスクリプター） - チャンク定義で指定されたアドレスにあるデータを基にチャンクを更新します。 |
チャンク数 | 4 | 更新するチャンク数。この値は少なくとも 1 であることが必要です。明確な最大値はありませんが、チャンク ディスクリプターはデータ バッファーに収まらなければなりません。データ バッファーのサイズは、表 18 の説明のとおり制限されています。 |
チャンク定義
（各チャンクについて繰り返す） | 12（32 ビット アプリケーション用） 16（64 ビット アプリケーション用） | 各チャンク定義は、以下に示すように、4 バイトのチャンク オフセット、それに続く 4 バイトのチャンク長、さらに 32 ビット アプリケーションの場合は 4 バイトのユーザー データ、または 64 ビット アプリケーションの場合は 8 バイトのユーザー データから構成されます。 •チャンク オフセット - チャンクの開始地点を、レコードの先頭からのオフセット（バイト単位）で示します。最小値は 0、最大値はレコードの末尾のバイトのオフセット + 1 です。 •チャンク長 - チャンク内のバイト数を示します。最小値は 0、最大値は 65,535 です。ただし、チャンク定義はデータ バッファーに収まらなければなりません。データ バッファーのサイズは、表 18 の説明のとおり制限されています。 •ユーザー データ - （間接ディスクリプターでのみ使用します。）32 ビット アプリケーションの場合、実際のチャンク データへの 32 ビット ポインターです。64 ビット アプリケーションの場合、実際のチャンク データへの 64 ビット ポインターです。使用すべき形式は、オペレーティング システムによって異なります。1 直接チャンク ディスクリプターのサブファンクションの場合、トランザクショナル インターフェイスではこの要素は無視されます。 |
1 DOS アプリケーションの場合、ユーザー データは 16 ビット オフセットおよび 16 ビット セグメントとして初期化してください。ユーザー データでは、そのセグメントの最後を越えてメモリをアドレス指定することはできません。チャンク長をユーザー データのオフセット部分に加算したとき、その結果は、ユーザー データによって定義されるセグメントの範囲内でなければなりません。デフォルトで、トランザクショナル インターフェイスではこの規則に対する違反はチェックされず、このような違反は適切に処理されません。 |
次の表は、32 ビット アプリケーション用の直接ランダム チャンク ディスクリプター構造体の例を示しています。
要素 | サンプル値 | 長さ（バイト単位） |
サブファンクション | 0x8000000 | 4 |
チャンク数 | 3 | 4 |
チャンク 0 | | |
チャンク オフセット | 0x12 | 4 |
チャンク長 | 0x05 | 4 |
ユーザー データ | 適用外 | 4 |
チャンク 1 | | |
チャンク オフセット | 0x2A | 4 |
チャンク長 | 0x08 | 4 |
ユーザー データ | 適用外 | 4 |
チャンク 2 | | |
チャンク オフセット | 0x41 | 4 |
チャンク長 | 0x0E | 4 |
ユーザー データ | 適用外 | 4 |
チャンク 0 用データ | 適用外 | 5 |
チャンク 1 用データ | 適用外 | 8 |
チャンク 2 用データ | 適用外 | 14 |
矩形チャンク ディスクリプター構造体
同じ長さのチャンクがレコード全体にわたって等間隔に配置されている場合は、矩形チャンク ディスクリプターを使って、更新するすべてのチャンクを記述することができます。たとえば、次のような図を考えてみましょう。この図は、レコード内のオフセット 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 つのチャンクをすべて更新できます。矩形チャンクを更新するには、表
49 に基づいてデータ バッファーに構造体を作成する必要があります。
表 49 矩形チャンク ディスクリプター構造体
要素 | 長さ（バイト単位） | 説明 |
サブファンクション | 4 | チャンク ディスクリプターの種類。次のいずれかを指定します。 •0x80000002（直接矩形チャンク ディスクリプター） - データ バッファーに直接格納されているチャンクを更新します。先頭のチャンクを更新するためのデータは、データ バッファー内の最後のチャンク定義（チャンク n）の直後に格納します。また、2 番目のチャンク データは先頭のチャンク データの直後に、と順次格納します。 •0x80000003（間接矩形チャンク ディスクリプター） - チャンク定義で指定されたアドレスにあるデータを基にチャンクを更新します。 |
行数 | 4 | 矩形チャンク ディスクリプターの操作対象とするチャンク数。最小値は 1 です。明確な最大値はありません。 |
位置（オフセット） | 4 | 更新する最初のバイトの、レコードの先頭からのオフセット。最小値は 0、最大値はレコードの末尾のバイトのオフセット + 1 です。レコードが 1 つの矩形として表される場合、この要素は、更新される先頭行にある先頭バイトのオフセットを指します。 |
行のバイト数 | 4 | 各チャンクで更新するバイト数。最小値は 0、最大値は 65,535 です。ただし、チャンク定義はデータ バッファーに収まらなければなりません。データ バッファーのサイズは、表 18 の説明のとおり制限されています。 |
行間隔 | 4 | チャンクの先頭から次のチャンクの先頭までのバイト数。 |
ユーザー データ | 4（32 ビット アプリケーション用） 8（64 ビット アプリケーション用） | （間接ディスクリプターでのみ使用します。）32 ビット アプリケーションの場合、実際のチャンク データへの 32 ビット ポインターです。64 ビット アプリケーションの場合、実際のチャンク データへの 64 ビット ポインターです。使用すべき形式は、オペレーティング システムによって異なります。1 直接矩形ディスクリプターの場合、トランザクショナル インターフェイスではこの要素は無視されます。ただしそれでも、この要素を割り当て、0 に初期化しておく必要があります。 |
アプリケーションの行間隔 | 4 | （間接矩形ディスクリプターでのみ使用します。）矩形がアプリケーションのメモリ（つまり、ユーザー データで指定したアドレス）に格納されるときの、矩形内のチャンクの先頭から次のチャンクの先頭までのバイト数。直接矩形ディスクリプターの場合、トランザクショナル インターフェイスではこの要素は無視されます。ただしそれでも、この要素を割り当て、0 に初期化しておく必要があります。 |
1 DOS アプリケーションの場合、ユーザー データは 16 ビット オフセットとそれに続く 16 ビット セグメントで表してください。 |
矩形がメモリ内にあるとき、各行の間隔がレコードとして格納されているときと同じバイト数になる場合は、アプリケーションの行間隔に行間隔と同じ値を設定します。しかし、矩形がアプリケーションのメモリ内で再配置され、行の間隔が何バイトか増減する場合は、アプリケーションの行間隔により、その情報をトランザクショナル インターフェイスに渡すことができます。
間接矩形ディスクリプターを使用するときは、トランザクショナル インターフェイスはユーザー データ要素およびアプリケーションの行間隔要素を使って、更新のためにデータを読み取る場所を決定します。トランザクショナル インターフェイスでは先頭行のデータはユーザー データのオフセット 0 から読み取られます。トランザクショナル インターフェイスでは 2 行目のデータは、ユーザー データ + アプリケーションの行間隔で指定されるアドレスから読み取られます。トランザクショナル インターフェイスでは 3 行目のデータは、ユーザー データ + (アプリケーションの行間隔 * 2) で指定されるアドレスから読み取られ、以下同様です。
次の表は、32 ビット アプリケーション用の直接矩形チャンク ディスクリプター構造体の例を示しています。
要素名 | サンプル値 | 長さ（バイト単位） |
サブファンクション | 0x80000002 | 4 |
行数 | 3 | 4 |
位置（オフセット） | 0x19 | 4 |
行のバイト数 | 0x04 | 4 |
行間隔 | 0x10 | 4 |
ユーザー データ | 0 | 4 |
アプリケーションの行間隔 | 0 | 4 |
データ（行 0） | 適用外 | 4 |
データ（行 1） | 適用外 | 4 |
データ（行 2） | 適用外 | 4 |
切り捨てディスクリプター構造体
切り捨てディスクリプターを使うと、指定したオフセットでレコードを切り捨てることができます。この種類のチャンク ディスクリプターを使用するには、次の表に基づいてデータ バッファーに構造体を作成する必要があります。
表 50 切り捨てディスクリプター構造体
要素 | 長さ（バイト単位） | 説明 |
サブファンクション | 4 | チャンク ディスクリプターの種類。0x80000004 を指定します。 |
チャンク オフセット | 4 | 切り捨てを開始する位置の、レコード内でのバイト オフセット。指定したバイトと、それ以降のバイトがすべて削除されます。最小値は 4、最大値はレコードの末尾のバイトのオフセットです。 |
ネクストインレコード サブファンクション バイアス
これまでに述べたサブファンクションの値にバイアス 0x40000000 を加算すると、トランザクショナル インターフェイスではレコード内の物理カレンシー（つまり、レコード内の現在の物理位置）に基づいてサブファンクションのオフセット要素の値が算出されます。ネクストインレコード サブファンクションを使用する場合、トランザクショナル インターフェイスではチャンク ディスクリプターのオフセット要素は無視されます。
このバイアスをランダム チャンク ディスクリプターと組み合わせて使用し、1 回のオペレーションで複数のチャンクを更新する場合、トランザクショナル インターフェイスでは前のチャンクの長さに前のチャンクのオフセットが加算され、先頭のチャンクを除くすべてのチャンクに対するオフセットが自動的に計算されます。つまり、ネクストインレコード バイアスは、オペレーションの対象となるすべてのチャンクに適用されるということです。
追加サブファンクション バイアス
バイアス 0x20000000 をランダム チャンク ディスクリプターのサブファンクションまたは矩形チャンク ディスクリプターのサブファンクションの値に加算すると、トランザクショナル インターフェイスではそのサブファンクションのオフセット要素の値がレコードの末尾の次のバイトとなるように計算されます。
メモ： このバイアスは、ネクストインレコード バイアスまたは切り捨てサブファンクションと共に使用しないでください。
トランザクショナル インターフェイスで、このバイアスをランダム チャンク ディスクリプターと組み合わせて使用し、1 回のオペレーションで複数のチャンクを更新する場合、トランザクショナル インターフェイスでは前のチャンクの追加後のレコードの長さに基づいて、先頭のチャンクを除くすべてのチャンクに対するオフセットが自動的に計算されます。
結果
Update Chunk オペレーションが正常に終了した場合、トランザクショナル インターフェイスではデータ バッファーのチャンク ディスクリプター部分でチャンクとして識別されたレコードの部分が更新されます。チャンクを更新するための新しいデータは、直接チャンク ディスクリプターのサブファンクションを使用した場合はチャンク ディスクリプター自体に、間接チャンク ディスクリプターのサブファンクションを使用した場合は、各チャンクのユーザー データ要素の 32 ビット ポインターで指定されたメモリ アドレスに格納されています。Update Chunk オペレーションが完了すると、トランザクショナル インターフェイスではキー値の変更を反映してキー インデックスが調整され、必要に応じてキー バッファー パラメーターが更新されます。
さらに、アプリケーションが更新するレコードに単一レコード ロックを設定している場合は、トランザクショナル インターフェイスではロックが解除されます。しかし、複数レコード ロックは Update Chunk オペレーションを実行しても解除されません。
Update Chunk オペレーションが正常に実行されなかった場合は、トランザクショナル インターフェイスから次のステータス コードのいずれかが返されます。
5 | レコードのキー フィールドに重複するキー値があります。 |
8 | 現在のポジションが不正です。 |
10 | キー フィールドは変更できません。 |
22 | データ バッファー パラメーターが短すぎます。 |
58 | 圧縮バッファー長が短すぎます。 |
62 | ディスクリプターが不正です。 |
80 | トランザクショナル インターフェイスでレコード レベルの矛盾が発生しました。 |
97 | データ バッファーが小さすぎます。 |
103 | チャンク オフセットが大きすぎます。 |
106 | トランザクショナル インターフェイスは、Get Next Chunk オペレーションを実行できません。 |
ポジショニング
Update Chunk オペレーションを実行しても、物理カレンシーおよび現在の論理レコードは変わりません。
メモ： Get オペレーションに続けて Update Chunk オペレーションを実行する場合は、直前の Get オペレーションで指定したキー番号と異なる値を Update Chunk オペレーションに渡さないでください。異なるキー番号を渡すと、トランザクショナル インターフェイスによって確立されるポジショニングが予測できないものになります。
Version（26）
クライアント アプリケーションの場合、Version オペレーション（B_VERSION）では、ローカルのトランザクショナル インターフェイスのバージョンおよび、適用可能であれば、リクエスターのバージョンが返されます。また、クライアント アプリケーションがサーバー上のファイルを開いていたり、キー バッファーにサーバー ファイル パス名を指定していると、そのサーバー上で実行されているトランザクショナル インターフェイスのバージョンも返されます。サーバーベース アプリケーションの場合は、サーバーベース トランザクショナル インターフェイスのバージョンおよびリビジョン番号が返されます。
パラメーター
| オペレーション コード | ポジション ブロック | データ バッファー | データ バッファー長 | キー バッファー | キー番号 |
送り値 | | | | | | |
戻り値 | | | | | | |
前提条件
Version オペレーションを発行するには、トランザクショナル インターフェイスまたはリクエスターのどちらかがロードされていることが必要です。
手順
1 オペレーション コードに 26 を設定します。
2 データ バッファー長に少なくとも 15 を設定します（詳細については、表
51 を参照してください）。
3 サーバーベース トランザクショナル インターフェイスのバージョン番号を取得するには、そのサーバー上で開いているファイルの有効なポジション ブロックを指定するか、キー バッファーに有効なパス名を指定する必要があります。
結果
ワークステーション トランザクショナル インターフェイスとクライアント リクエスターの両方にアクセスできるように環境設定されており、Version オペレーションが正常に終了した場合は、ワークステーション トランザクショナル インターフェイス、クライアント リクエスター、およびサーバーベース トランザクショナル インターフェイスのバージョン情報が返されます。
この場合、15 バイトのデータ バッファーとデータ バッファー長を指定してください。
クライアント リクエスターとワークステーション トランザクショナル インターフェイスの両方がロードされており、データ バッファーとデータ バッファー長に 5 バイトしか指定していないと、クライアント リクエスターのバージョン情報だけが返されます。
10 バイトしか指定してしない場合は、クライアント リクエスターとローカル ワークステーション エンジンが返されます。
データ バッファーとデータ バッファー長に 15 バイトを指定した場合は、クライアント リクエスター、ローカル ワークステーション エンジン、およびサーバー エンジン（適用可能な場合）が返されます。
データ バッファーには、表
51 の形式に従って、Version オペレーションからトランザクショナル インターフェイスまたはリクエスターごとに 5 バイトのバージョン ブロックが返されます。各ブロックの 5 バイト目により、それぞれのトランザクショナル インターフェイスまたはリクエスターを識別できます。
表 51 バージョン ブロック
要素 | 長さ（バイト単位） | 説明 |
バージョン番号 | 2 | Pervasive PSQL のバージョン番号。 |
リビジョン番号 | 2 | Pervasive PSQL のリビジョン番号。 |
リクエスターまたはエンジンの種類 | 1 | エンジンまたはリクエスターの種類は、次のいずれかになります。 •9（0x39）はワークグループ データベース エンジン、またはワークグループの認証モードを使用している Linux データベース サーバー •D（0x44）は DOS ワークステーション •N（0x4E）はクライアント リクエスター •T（0x54）は Windows サーバー エンジン •U（0x55）は PAM または BTPASSWD 認証を使用している Linux サーバー |
たとえば、Pervasive.SQL v8.10 for Windows を実行している場合は、データ バッファーに次のような 16 進の値が返されます。
08 00 0A 00 54
これらの値を 10 進に変換すると、バージョン番号は 8 で、リビジョン番号は 10 になります。Version オペレーションが正常に実行されなかった場合、トランザクショナル インターフェイスからは 0 以外のステータス コードが返されます。
ポジショニング
Version オペレーションは、ポジショニングにまったく影響しません。
