Btrieve API の紹介
Zen MicroKernel エンジンは、高パフォーマンスなデータ処理とプログラミングの生産性向上を目的として設計されています。MicroKernel エンジン オペレーションを使用すると、開発アプリケーションではキー値、あるいはシーケンシャルまたはランダム アクセス方法に基づいて、レコードの取得、挿入、更新、または削除が行えるようになります。
Btrieve API は、以下のプログラミング言語および開発環境と互換性があります。
•Embarcadero C/C++
•Embarcadero Delphi
•GNU C/C++
•Micro Focus COBOL
•Microsoft Visual Basic
•Microsoft Visual C++
•Watcom C/C++
以下のセクションで API の機能について説明します。
Btrieve API 関数
Btrieve API は単一関数です。この API では、ほとんどのプログラム動作が関数名ではなくオペレーション コード パラメーターによって決定されます。アプリケーションで使用する API は、異なるプラットフォーム間でのコードの移植性を重視するか、特定のプラットフォームで可能な限り最高のパフォーマンスを重視するかを基準として選択してください。
Btrieve アプリケーションでは、データ ファイルに対して絶対に標準の I/O を実行しないでください。開発するアプリケーションでは、Btrieve API 関数を使って、すべてのファイル I/O を実行する必要があります。
次の表は、オペレーション コードで使用するための Btrieve API 関数の一覧です。
表 1 Btrieve API 関数
関数 | オペレーティング システム | 説明 |
|---|
BTRV
BTRVID | すべて | オペレーティング システム間での完全なコード互換性を得るために使用します。大部分の開発者にとって、この利点はパフォーマンスのわずかな低下を十分に埋め合わせるものです。古いデータ バッファー レイアウトを使用します。 |
BTRCALL
BTRCALLID | すべて | キー長の引数を使用する場合に使用します。古いデータ バッファー レイアウトを使用します。 |
BTRVEX
BTRVEXID | すべて | 長いデータ バッファーが必要な場合、または新しいデータ バッファー レイアウトを使用する場合に使用します。データ バッファーを正しく解釈できる限りにおいては、BTRV タイプのエントリ ポイントと混在させることができます。 |
Btrieve API 関数を呼び出すための言語固有の構文を調べるには、『
Zen Programmer's Guide』の
Btrieve API プログラミングを参照してください。
BTRV
BTRV によって、アプリケーションは MicroKernel エンジン呼び出しを実行できるようになります。BTRV 関数は、プログラミング インターフェイスのインストール オプションで提供されるすべての言語インターフェイス モジュールでサポートされています。場合によって、BTRV 関数は実際に BTRCALL 関数を呼び出すことがあります。しかしながら、プラットフォームに依存しないということから、BTRV 関数の方がより好ましいでしょう。
BTRVID
BTRVID によって、アプリケーションはクライアント ID パラメーターを含む単独の MicroKernel エンジン呼び出しを実行できるようになります。このパラメーターはアプリケーションで制御できます。アプリケーションでは BTRVID を使って、自分自身を MicroKernel エンジンに対する複数のクライアント ID として割り当て、ほかのクライアントの状態に影響を与えることなく、各クライアントのオペレーションを実行することができます。詳細については、
クライアント ID を参照してください。
BTRCALL
Windows、Linux、および macOS の場合、BTRCALL は BTRV 関数に相当します。BTRV で発生する若干のパフォーマンス低下が問題にならない限り、BTRCALL ではなく BTRV 関数を使用するようにしてください。
BTRCALLID
クライアント レベルの制御が必要で、アプリケーションが Windows、Linux、macOS、または Raspbian で動作する場合は、BTRCALLID 関数を使用します。
中間関数を呼び出さないこと以外は、この関数は BTRVID 関数に類似しています。
メモ：従来の BTRCALLID32 関数は BTRCALLID 関数にエイリアスされました。
BTRVEX
13.0 形式のファイルのサイズが大きくなる可能性がある場合、およびより大きなデータ バッファーを使用する場合、以前の Btrieve インターフェイスが提供していたものより大きなランタイム値が必要となります。新しいエントリ ポイントである BTRVEX および BTRVEXID は、これらの要件を満たしています。これらは BTRCALL および BTRCALLID と似ていますが、いくつかの関数の引数のデータ型の幅が広くなっている点と、いくつかのデータ バッファーのレイアウトが異なっている点が違います。宣言は btrvexid.h 内にあり、実装は BTRCALL と同じファイル内にあります。
BTRVEX エントリ ポイントを使用する Btrieve オペレーションの場合、データ バッファーで渡される一部の値は、8 バイトのレコード アドレスやレコード カウントのように幅が広くなっています。8 バイト動作は BTRVEX エントリ ポイントに起因するものであり、アクセスするファイルのファイル形式によって決まることでないことに留意してください。BTRVEX を使用する場合、次のオペレーションはデータ バッファーのレイアウトの変更を必要とします。
•Create (14)、Create Index (31)
•Stat (15)
•Get Position (22)
•Get Direct (23)
•Get Next Extended (36)、Get Previous Extended (37)
•Step Next Extended (38)、Step Previous Extended (39)
•Insert Extended (40)
•Find Percentage (45)
•Stat Extended (65) サブファンクション 3 および 8
•Unlock (27)
エントリ ポイントの選択は、レコード データには影響しません。
上述のとおり、データ バッファー サイズの引数は BTRCALL が 16 ビット整数を使用する箇所が BTRVEX では 32 ビット整数へのポインターになっています。このため、データ バッファーを 64 KB より大きくすることができます。
新しいファイル形式へ移行する場合、ポジション ブロックとクライアント ID の値は BTRCALL と BTRVEX の両方で使用できるため、すべてのコードを一度に BTRVEX に変換する必要はないことを覚えておいてください。
BTRVEX のキー番号の引数は 32 ビット整数であるのに対し、BTRCALL は 8 ビットの符号付き整数を使用します。既存のコードを BTRVEX へ簡単に変換するためには、BTRVEX エントリ ポイントはキー値 128 ～ 255 を -128 ～ -1 に再マップします。これは、符号付きバイト（例：-2）としてでなく符号なしバイト（例：0xFE）として指定された定数に対応します。
BTRVEXID
BTRVID および BTRCALLID と同様、BTRVEXID は BTRVEX の利点に加えて、クライアント ID の制御が可能です。
旧バージョンの関数
次の関数は、以前のバージョンの Btrieve API に対応して書かれた古いアプリケーションとの互換性を維持するためだけにサポートされています。
•BTRCALLBACK
•BTRVINIT
•BTRVSTOP
•RQSHELLINIT
•WBRQSHELLINIT
•WBTRVINIT
•WBTRVSTOP
•BRQSHELLINIT
現在のバージョンではこれらの関数を使用しませんが、これらの関数を呼び出す古いアプリケーションは v6.15 以降の MicroKernel バージョンでも正常に実行されます。
Btrieve API 関数のパラメーター
どの関数呼び出しもすべてのパラメーターを提供する必要があります。これは、MicroKernel エンジンがすべてのオペレーションですべてのパラメーターを使用するわけではなく、場合によっては、パラメーター値を無視することがある場合にも、当てはまります。一般に、それぞれのオペレーションでは異なるパラメーターが送られ、返されます。各 Btrieve API オペレーションのパラメーターの詳細については、
Btrieve API オペレーションを参照してください。
メモ：C 開発者：C 言語インターフェイスで使用されるプラットフォームに依存しないデータ型とポインターについては、btitypes.h ファイルを参照してください。
Btrieve API 関数は次のパラメーターを使用します。
•クライアント ID（BTRVID、BTRCALLID、および BTRVEXID 関数のみ）
•キー長（BTRCALL、BTRCALLID、BTRVEX、および BTRVEXID 関数のみ）
オペレーション コード
オペレーション コード パラメーターは、Btrieve API 関数の動作を決定します。たとえば、1 つまたは複数のレコードの読み取り、書き込み、削除、更新などのオペレーションです。アプリケーションでは、すべての Btrieve API 呼び出しに対してオペレーション コードを指定する必要があります。このコードを MicroKernel エンジンが変更することはありません。オペレーション コードについては、
Btrieve API オペレーションで説明しています。
メモ：C 開発者：指定する変数のデータ型は次のいずれかである必要があります。
●BTI_WORD、符号なし short integer
●BTI_INT、符号付き 32 ビット integer。BTRVEX および BTRVEXID でのみ使用されます。
どちらの場合も、変数は値で渡されます。
ステータス コード
BASIC および COBOL アプリケーションでは、MicroKernel エンジンは符号付き整数としてステータス コードを返します。ほとんどのプログラミング環境で、ステータス コードは Btrieve API 関数呼び出しの戻り値です。ただし、一部の BASIC および COBOL 言語インターフェイスでは、ステータス コード パラメーターが必要となります。このパラメーターには、オペレーションの実行中にエラーが発生したかどうかを示す、コード化された値が格納されます。Btrieve API 呼び出しの終了後、アプリケーションではステータス変数の値を必ずチェックして、正常に終了したかどうかを判断する必要があります。
Zen コンポーネントによって、呼び出しから API へステータス コードが返されます。これらの API に書き込む場合は、以下の 3 つの状態に対して処理を行う必要があります。
•API の成功
•予期された API の失敗
•予期されなかった API の失敗
以下は、3 つすべての状態を処理する C コードの例です。
status = BTRVID(B_VERSION, posBlock1, &versionBuffer, &dataLen, keyBuf1, keyNum, (BTI_BUFFER_PTR) &clientID);
if (status == B_NO_ERROR)
{
/* 通常のオペレーションを続行 */
status = BTRVID(...);
}
else if (status == B_RECORD_MANAGER_INACTIVE)
{
/* 予期されたエラーの処理 */
printf("Btrieve Get Version() returned B_RECORD_MANAGER_INACTIVE\n");
}
else
{
/* 予期されなかったエラー */
printf("Btrieve Get Version() returned %d\n", status);
} /* 別の場合は終了 */
このステータス コードの処理方法に従うと、アプリケーションの将来的な安定性を確保する上で役立ちます。
メモ：古い BTRV 関数では、ステータス コードは 2 バイト整数でしたが、新しい BTRVEX および BTRVEXID では 4 バイト整数を返します。
ポジション ブロック
ポジション ブロック パラメーターは、128 バイト配列のアドレスで、MicroKernel エンジンがファイル I/O 構造体や Open（0）オペレーションに関連するポジショニング情報を格納するために使用されます。アプリケーションは、ファイルを開くたびに固有のポジション ブロックを割り当てる必要があります。MicroKernel エンジンは、アプリケーションが Open オペレーションを実行する際にポジション ブロックを初期化し、その後ファイルの操作中にこのポジション ブロックを参照して更新します。このため、アプリケーションでは、そのファイルに対する以降すべての Btrieve API オペレーションで同じポジション ブロックを指定する必要があります。
メモ：ポジション ブロックへの書き込みを行ってはいけません。書き込みを行うと、ポジション喪失エラーやその他のエラー、あるいはファイルの損傷などの原因となります。
一度に複数のファイルを開く場合、MicroKernel エンジンはポジション ブロックを使って、特定の呼び出しで対象となるファイルを判別します。同様に、同じファイルを複数回開く場合、エンジンは Open オペレーションごとにそれぞれ異なるポジション ブロックを使用します。さらに、エンジンは、同じファイルを開くクライアントごとにも別個のポジション ブロックを使用します。クライアント間でポジション ブロックを共有することはできません。
メモ：ポジション ブロックはエントリ ポイントにバインドされません。そのため、BTRV を使用してデータ ファイルを開き、BTRVEX を使用してデータを読み取り、BTRCALL を使用してファイルを閉じることが可能です。
データ バッファー
アプリケーションでファイルとデータをやり取りする場合は、データ バッファーを使用します。データ バッファーを使って MicroKernel エンジンとの間でやり取りされる情報は、実行される Btrieve API オペレーションによって異なります。しばしば、データ バッファーには、アプリケーションとファイルの間で相互に転送される 1 つまたは複数のレコードが格納されています。しかし、Btrieve API オペレーションによっては、ファイル仕様やキー仕様、MicroKernel エンジンのバージョン情報など、その他の情報がデータ バッファーに格納されることもあります。
必ず、ファイル内の最長レコードを収容できるだけの長さのデータ バッファーを割り当ててください。データ バッファーの割り当てサイズよりも大きな値をデータ バッファー長パラメーターに指定した場合、MicroKernel エンジン変更オペレーションによって、データ バッファーの後に続くデータが破壊される可能性があります。
メモ：エントリ ポイントに応じて、同じオペレーションで異なるレイアウトを使用します。BTRV、BTRVID、BTRCALL、および BTRCALLID は従来のレイアウトを使用します。BTRVEX および BTRVEXID は新しい、少し異なるレイアウトを使用します。レイアウトが異なっても、ユーザー データ レコードには影響しません。
データ バッファー長
データ バッファーを必要とするオペレーションでは、アプリケーションはデータ バッファーのサイズ（バイト単位）を示す変数を渡す必要があります。このデータ バッファーは、オペレーションによって返されるデータを十分格納できるだけの大きさでなければなりません。
メモ：BASIC 開発者：データ バッファー長パラメーターとして、長整数の ByRef を渡す必要があります。
C、COBOL、Pascal の開発者：古い BTRV 関数の場合は、データ バッファー長パラメーターとして 2 バイト整数へのポインターを渡す必要がありますが、新しい BTRVEX および BTRVEXID 関数は 4 バイト整数を使用します。
可変長レコードを含むファイルにレコードを挿入したり、そのファイルを更新したりする場合、データ バッファー長は、ファイルを最初に作成したときに指定したレコード長に、固定長部分を超えて含まれる文字数を加算した値と等しくなければなりません。可変長レコードを取得する場合、データ バッファー長はファイル内の最長レコードに対応できる長さである必要があります。1 件のレコードが最大データ バッファー サイズより長い場合は、チャンク オペレーションを使用して、レコードの部分を操作する必要があります。
MicroKernel エンジンはデータ バッファー長パラメーターによって、データ バッファーに使用可能なスペース量を判断します。割り当てたデータ バッファーより長いデータ バッファー長を渡すと、MicroKernel エンジンによってメモリが上書きされる場合があります。データ バッファー長は、実際に割り当てられたデータ バッファーのサイズを常に正確に表すようにしてください。
メモ：データ バッファー長は、古い BTRV 関数の場合は 2 バイト、新しい BTRVEX および BTRVEXID 関数の場合は 4 バイトです。最大データ バッファー サイズは、古い関数の場合は 64 KB、新しい関数の場合は 252 KB です。
キー バッファー
Btrieve API オペレーションでキー バッファーが使用されない場合でも、アプリケーションは各 Btrieve API オペレーションにキー バッファー パラメーターを渡す必要があります。オペレーションによっては、アプリケーションがキー バッファーのデータを設定する場合や、Btrieve API 関数がこれを返す場合があります。
メモ：BASIC 開発者：キー バッファー パラメーターとして文字列を渡す必要があります。キー値が整数である場合、アプリケーションでは Btrieve API 関数を呼び出す前に、MKI$ ステートメントを使用してキー値を文字列に変換しておく必要があります。キーが複数のセグメントから構成されている場合は、それらを結合して 1 つの文字列変数にし、その変数をキー バッファーとして渡す必要があります。
キー バッファーとして渡した文字列変数が定義されたキー長より短い場合、MicroKernel エンジンからエラーが返されます。最初のアプリケーション呼び出しがキー バッファーの初期化を必要としない場合は、文字列変数に SPACE$(x) の値を割り当てます。この x は、キーの定義されている長さを表します。アプリケーションが文字列変数に BASIC の値を割り当てるまで、その長さは 0 になります。
C 開発者：キー バッファー パラメーターとしてキー値を含む変数のアドレスを渡す必要があります。btitypes.h ファイルは、キー バッファーを VOID ポインター（BTI_VOID_PTR）として定義しています。キー バッファーのデータ型は、必要に応じてアプリケーションで定義できます。
COBOL 開発者：キー バッファー パラメーターとしてレコード変数を渡す必要があります。キーが複数のセグメントから構成されている場合は、01 レベルのレコード下の個別フィールドとして、それらを正しい順序でリストします。これで、レコード全体をキー バッファーとして渡すことができます。
Pascal 開発者：キー バッファー パラメーターとしてキー値を含む変数を渡す必要があります。キーが複数のセグメントから構成されている場合は、レコード構造体を使ってキーに含まれる個々のフィールドを定義します。
ほとんどの環境で、アプリケーションが Btrieve API 呼び出しを実行するとき、MicroKernel エンジンはキー バッファー長を決めることができません。バッファーは少なくとも、キーを作成したときに選択したキー長と同じだけの長さがあるようにしてください。そうでないと、Btrieve オペレーションにより、メモリ内でキー バッファーの後に格納されているデータが破壊される可能性があります。キーの最大長は 255 なので、255 バイトのキー バッファーにすることをお勧めします。
キー番号
キー番号パラメーターで渡される情報は、実行しているオペレーションによって異なります。ほとんどの場合、キー番号には、特定のオペレーションが最高 119 あるキー（アクセス）パスのうちのどれに従っているかを示す値が含まれます。すべての関数で、キー番号は 0 から 118 までの範囲の値となります。
キー番号のサイズは次のように異なります。
•BTRV および BTRVID では、このパラメーターは 2 バイト整数です。
•BTRCALL、BTRCALLID、BTRCALL32、および BTRCALLID32 では、これは 1 バイトの符号付き文字（BTI_CHAR）です。
•BTRVEX および BTRVEXID では、これは 4 バイト整数です。BTRVEX へコードを移行するための便宜上、キー値 128 ～ 255 は -128 ～ -1 にマップされます。これは、大きな符号なしバイト値（例：0xFF）から BTRCALL の符号付きバイト引数への変換をシミュレートします。
Btrieve API 関数がキー番号パラメーターを変更することはありません。
ファイルを開くときのモードを示す値など、その他の情報がキー番号パラメーターから渡されたり、キー番号パラメーターに返される場合もあります。
クライアント ID
クライアント ID パラメーターは、BTRVID、BTRCALLID、および BTRVEXID 関数でのみ使用されます。クライアント ID パラメーターは、MicroKernel エンジンがコンピューター上のクライアントを区別できるようにする 16 バイト構造体のアドレスです。クライアント ID には次のような構造体を使用します。
表 2 クライアント ID 構造体
要素 | 長さ（バイト単位） | 説明 |
|---|
Filler（フィラー） | 12 | 0 に初期化します。 |
Service Agent ID（サービス エージェント ID） | 2 | MicroKernel エンジンに対するアプリケーションの各インスタンスを識別します。これは 2 文字の ASCII 値です。この ID の値は ASCII 値の AA（0x41 0x41）より大きいか等しくなければなりません。MicroKernel エンジンは次の値に特殊な意味を持たせています。 |
0x4140（@A） | 内部処理に使用されます。 |
0xFFFF | 内部処理に使用されます。 |
0x4952（RI） | 内部処理に使用されます。 |
0x5244（DR） | 内部処理に使用されます。 |
0x4553（SE）
0x4353（SC）
0x4344（DC）
0x4544（DE）
0x5544（DU） | Scalable SQL によって生成されたクライアントを識別するために使用されます。 |
0x5257（WR） | Btrieve リクエスターによって使用されます。 |
Client Identifier（クライアント識別子） | 2 | アプリケーションの現在のインスタンス内でクライアント ID を確立します。MicroKernel エンジンでは、この一意な識別子を、並行処理およびトランザクション処理のために使用します。 |
キー長
キー長パラメーターは、BTRCALL、BTRCALLID、BTRVEX、および BTRVEXID でのみ使用されます。
キー長の値は次のように使用されます。
•BTRCALL および BTRCALLID の場合は、キー長は符号なし文字の型 BTI_BYTE として、割り当てられたキー バッファーの長さの値を渡します。指定できる最大長は 255 で、これはキーの最大長です。
•BTRVEX および BTRVEXID の場合は、キー長は符号なし文字の型 BTI_INT として、最大長の 255 を渡します。
キー バッファーを利用する場合には、次のことを考慮してください。
•4 つの関数すべてについて、オペレーション コードによっては、指定されたキー長までのキー バッファーのバイトは読み取り可能または書き込み可能である必要があります。
•BTRV および BTRVID は、255 のキー長を想定しているため、少なくともその大きさのキー バッファーを提供する必要があります。
•BTRCALL および BTRCALLID の場合は、Zen クライアント コンポーネントが実際のキー長を決定しようとしたり、場合によっては、キー バッファーの小さな部分を読み書きしたりすることがあります。
•BTRVEX および BTRVEXID は、指定されたキー長をそのまま受け取ります。
Btrieve API オペレーションの要約
Btrieve API には、アプリケーション プログラムから呼び出せる 40 以上のオペレーションが用意されています。以下の表に、これらのオペレーションの要約を示します。詳細については、
Btrieve API オペレーションを参照してください。オペレーション コード順の簡単な説明については、
Btrieve オペレーションのクィック リファレンスを参照してください。
セッション固有のオペレーション
次のオペレーションを使用すると、現在のディレクトリの設定と取得、ワークステーション MicroKernel エンジンのシャットダウン、MicroKernel エンジン バージョン番号の取得、サーバー MicroKernel エンジンに接続されているクライアントの終了、トランザクションの開始、終了または中止といった処理を実行できます。複数のクライアントを処理するアプリケーションでは、これらのオペレーションは呼び出し元のクライアントに固有のものとなります。
表 3 セッション固有のオペレーション
オペレーション | コード | 説明 |
|---|
Stop | 25 | ワークステーション MicroKernel エンジンを終了します（サーバー ベースの MicroKernel エンジンでは使用できません）。 |
Version | 26 | MicroKernel エンジンのバージョン番号を返します。 |
Reset | 28 | クライアントによって保持されているすべてのリソースを解放します。 |
Set Directory | 17 | 現在のディレクトリを指定されたパス名に設定します。 |
Get Directory | 18 | 指定された論理ディスク ドライブの現在のディレクトリを返します。 |
Begin Transaction | 19
1019 | 論理的に関連している一連のオペレーションの開始を指定します。オペレーション 19 は排他トランザクションを開始します。オペレーション 1019 は並行トランザクションを開始します。 |
End Transaction | 20 | 論理的に関連している一連のオペレーションの終了を指定します。 |
Abort Transaction | 21 | 完了しなかったトランザクション中に実行されたオペレーションを取り消します。 |
Continuous Operation | 42 | アクティブな MicroKernel エンジン ファイルを閉じずに、システム バックアップを実行できるようにします。 |
ファイル固有のオペレーション
次のオペレーションは特定のファイルを取り扱います。このため、操作対象となるファイルを識別するためにポジション ブロック パラメーターが使用されます。ファイル固有のオペレーションは次の 3 つのタイプに分類されます。
•ファイル アクセスと情報。これらのオペレーションでは、ファイルの作成、ファイルの開閉、ファイル統計情報の取得、ファイルのオーナー ネームの設定と削除、ファイルに対する Continuous オペレーション モードの開始と終了、ファイルのロック解除、ファイルに対するインデックスの作成と削除といった処理を実行できます。
•データ取得。これらのオペレーションでは、指定した条件に基づいて単一レコードまたはレコードのセットを取得することができます。Btrieve API は、インデックス パスによる論理的位置、または物理的位置に基づくデータ検索をサポートしています。詳細については、『Zen Programmer's Guide』でレコードのアクセスに関する情報をお読みください。
さらに、オペレーション コードにバイアスを適用して、マルチクライアント状況にあるファイルやレコードのロックを制御することもできます。詳細については、『Zen Programmer's Guide』の「複数のクライアントのサポート」を参照してください。
•データ操作。これらのオペレーションでは、データの挿入、更新、または削除が行えます。
表 4 ファイル アクセスおよび情報オペレーション
オペレーション | コード | 説明 |
|---|
Open | 0 | ファイルをアクセス可能な状態にします。 |
Close | 1 | ファイルをアクセス可能な状態から解放します。 |
Create | 14 | 指定された特性を持つファイルを作成します。 |
Stat | 15 | ファイルおよびインデックスの特性とレコードの数を返します。 |
Continuous Operation | 42 | アクティブな MicroKernel エンジン ファイルを閉じずに、システム バックアップを実行できるようにします。 |
Stat Extended | 65 | 拡張ファイルの構成要素のパスとファイル名を返し、ファイルがシステム定義のログ キーを使用しているかどうかを報告します。 |
Set Owner | 29 | ファイルにオーナー ネームを割り当てます。 |
Clear Owner | 30 | ファイルからオーナー ネームを削除します。 |
Unlock | 27 | レコードのロックを解除します。 |
Create Index | 31 | インデックスを作成します。 |
Drop Index | 32 | インデックスを削除します。 |
表 5 データ取得オペレーション
オペレーション | コード | 説明 |
|---|
インデックス ベースの（論理）データ取得 |
Get Equal | 5 | 指定されたインデックス パス内で、指定されたキー値と合致するキー値を持つ最初のレコードを返します。 |
Get Next | 6 | インデックス パスで現在のレコードの次にあるレコードを返します。 |
Get Previous | 7 | インデックス パスで現在のレコードの前にあるレコードを返します。 |
Get Greater Than | 8 | 指定されたインデックス パス内で、指定されたキー値より大きいキー値を持つ最初のレコードを返します。 |
Get Greater Than or Equal | 9 | 指定されたインデックス パス内で、指定されたキー値より大きいまたは等しいキー値を持つ最初のレコードを返します。 |
Get Less Than | 10 | 指定されたインデックス パス内で、指定されたキー値より小さいキー値を持つ最初のレコードを返します。 |
Get Less Than or Equal | 11 | 指定されたインデックス パス内で、指定されたキー値より小さいまたは等しいキー値を持つ最初のレコードを返します。 |
Get First | 12 | 指定されたインデックス パスの先頭のレコードを返します。 |
Get Last | 13 | 指定されたインデックス パスの末尾のレコードを返します。 |
Get Next Extended | 36 | インデックス パスで現在のレコードの次にある 1 つまたは複数のレコードを返します。フィルター条件を適用できます。 |
Get Previous Extended | 37 | インデックス パスで現在のレコードの前にある 1 つまたは複数のレコードを返します。フィルター条件を適用できます。 |
Get Key | +50 | 実際のレコードを返すことなく、ファイル内に特定のキー値が存在するかどうかを検出します。 |
Get By Percentage | 44 | 指定されたパーセンテージ値によって示される位置の最も近くにあるレコードを返します。 |
Find Percentage | 45 | ファイル内における現在のレコード位置に基づいたパーセンテージ値を返します。 |
非インデックス ベースの（物理）データ取得 |
Get Position | 22 | 現在のレコードの位置を返します。 |
Get Direct/Chunk | 23 | 指定された位置にあるレコードの指定部分（チャンク）からデータを返します。 |
Get Direct/Record | 23 | 指定された位置にあるレコードを返します。 |
Step Next | 24 | 物理的に現在のレコードの次にあるレコードを返します。 |
Step First | 33 | ファイル内で物理的な先頭位置にあるレコードを返します。 |
Step Last | 34 | ファイル内で物理的な末尾位置にあるレコードを返します。 |
Step Previous | 35 | 物理的に現在のレコードの前にあるレコードを返します。 |
Step Next Extended | 38 | 物理的に現在のレコードの次の位置から 1 つまたは複数の連続するレコードを返します。フィルター条件を適用できます。 |
Step Previous Extended | 39 | 物理的に現在のレコードの前の位置から 1 つまたは複数の連続するレコードを返します。フィルター条件を適用できます。 |
Get By Percentage | 44 | 指定されたパーセンテージ値によって示される位置の最も近くにあるレコードを返します。 |
Find Percentage | 45 | ファイル内における現在のレコード位置に基づいたパーセンテージ値を返します。 |
並行制御バイアス（適切なオペレーション コードに追加） |
単一レコードの読み取りウェイト ロック | +100 | 一度に 1 つのレコードだけをロックします。レコードが既にロックされている場合、クライアントによってオペレーションが再試行されます。 |
単一レコードの 読み取りノーウェイト ロック | +200 | 一度に 1 つのレコードだけをロックします。レコードが既にロックされている場合、MicroKernel エンジンからエラー ステータス コードが返されます。 |
複数レコードの読み取りウェイト ロック | +300 | 同一ファイルの複数のレコードを並行的にロックします。レコードが既にロックされている場合、クライアントによってオペレーションが再試行されます。 |
複数レコードの 読み取りノーウェイト ロック | +400 | 同一ファイルの複数のレコードを並行的にロックします。レコードが既にロックされている場合、MicroKernel エンジンからエラー ステータス コードが返されます。 |
書き込みノーウェイト ページ ロック | +500 | 並行トランザクションで、変更しようとしたページがアクティブな別の並行トランザクションによって既に変更されている場合、MicroKernel エンジンにウェイトしないように指示します。このバイアスは、どのレコード読み取りロック バイアス（+100、+200、+300、+400）とでも組み合わせることができます。 |
表 6 データ操作オペレーション
オペレーション | コード | 説明 |
|---|
Insert | 2 | ファイルに新しいレコードを挿入します。 |
Update | 3 | 現在のレコードを更新します。 |
Delete | 4 | ファイルから現在のレコードを削除します。 |
Insert Extended | 40 | ファイルに 1 つまたは複数のレコードを挿入します。 |
Update Chunk | 53 | 現在のレコードの指定された部分（チャンク）を更新します。このオペレーションでは、レコードにデータを追加したり、レコードを切り詰めることもできます。 |
Get Next Delete Extended | 85 | 論理位置の直後からファイルの末尾までで、フィルター条件に一致するレコードを削除します。 |
Get Previous Delete Extended | 86 | 論理位置の直前からファイルの先頭までで、フィルター条件に一致するレコードを削除します。 |
Step Next Delete Extended | 87 | 物理位置の直後からファイルの末尾までで、フィルター条件に一致するレコードを削除します。 |
Step Previous Delete Extended | 88 | 物理位置の直前からファイルの先頭までで、フィルター条件に一致するレコードを削除します。 |
サポートされないオペレーション
MicroKernel エンジン トレースや SDK ヘッダー ファイルを見たときに Btrieve API オペレーションのリファレンスに記載されていないオペレーションがあるかもしれません。これらは Zen が内部的に使用するもので、アプリケーションで使用する必要はありません。以下に示すオペレーションはサポートされません。
表 7 サポートされないオペレーション
オペレーション | コード | 説明 |
|---|
B_MISC_DATA | 41 | MicroKernel エンジンが使用するために予約されています。 |
B_EXTEND | 16 | SQL エンジンが使用するために予約されています。 |
Btrieve による（ネストされた）Begin Transaction | 2019 | MicroKernel エンジンが使用するために予約されています。 |
Btrieve API オペレーションの実行における一連のイベント
►Btrieve API オペレーションを実行するには、アプリケーションで以下のタスクを完了する必要があります。
1 オペレーションが要求する必要条件をすべて満たします。たとえば、ファイルの I/O オペレーションを実行する前に、対象となるファイルで Open（0）オペレーションを実行し、そのファイルを使用可能な状態にしておく必要があります。
2 Btrieve API オペレーションが要求するパラメーターを初期化します。パラメーターとはプログラム変数またはデータ構造体のことで、その型とサイズは、MicroKernel エンジンがオペレーションに期待する特定の値に対応していなければなりません。
将来の互換性を維持するため、使用するかどうかに関係なく、すべてのパラメーターを初期化してください。INTEGER 型のパラメーターの場合、値をバイナリ 0 に設定します。文字列配列の場合、バッファーへのポインターを渡します。この場合は、バッファーの先頭バイトをバイナリ 0 に初期化します。
4 関数呼び出しの実行結果を評価します。すべての Btrieve API オペレーションからステータス コードが返されます。アプリケーションではステータス コードをチェックし、適切な操作を行う必要があります。また、オペレーションからはその目的に基づいて、個々のパラメーターにデータやその他の情報も返されます。