Btrieve API Guide (v11)

Btrieve API 関数のパラメーター

呼び出しのたびにすべてのパラメーターを入力する必要がありますが、トランザクショナル インターフェイスではオペレーションのたびにすべてのパラメーターが使用されるわけではありません。場合によっては、トランザクショナル インターフェイスではそれらの値が無視されます。一般に、それぞれのオペレーションでは異なるパラメーターが送られ、返されます。第 2「Btrieve API オペレーション」で、各 Btrieve API オペレーションに関連するパラメーターについて詳しく説明します。


メモ

C 開発者:C 言語インターフェイスで使用されるプラットフォームに依存しないデータ型とポインターについては、BTITYPES.H を参照してください。


Btrieve API 関数のパラメーターを以下に示します。

オペレーション コード

オペレーション コード パラメーターは、Btrieve API 関数によって実行される動作を決定します。たとえば、1 つまたは複数のレコードの読み取り、書き込み、削除、更新などのオペレーションです。アプリケーションでは、すべての Btrieve API 呼び出しに対して有効なオペレーション コードを指定する必要があります。トランザクショナル インターフェイスがオペレーション コードを変更することはありません。指定する変数の値は、第 2「Btrieve API オペレーション」に示されている Btrieve API の正しいオペレーション コードのいずれかでなければなりません。


メモ

C 開発者:指定する変数は BTI_WORD 型(符号なし short integer)でなければならず、値渡しする必要があります。


ステータス コード

トランザクショナル インターフェイスは、符号付き整数としてステータス コードを返します。ほとんどのプログラミング環境で、ステータス コードは Btrieve API 関数呼び出しの戻り値です。ただし、一部の BASIC および COBOL 言語インターフェイスでは、ステータス コード パラメーターが必要となります。このパラメーターは 2 バイトの整数で、オペレーションの実行中に何らかのエラーが発生したかどうかを示すコード化された値を含みます。Btrieve API 呼び出しの終了後、アプリケーションではステータス変数の値を必ずチェックし、その呼び出しが正常に終了したかどうかを確認する必要があります。

Pervasive PSQL コンポーネントによって、呼び出しから API へステータス コードが返されます。これらの API に書き込む場合は、以下の 3 つの状態に対して処理を行う必要があります。

以下は、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); 
} /* 別の場合は終了 */ 

このステータス コードの処理方法に従うと、Pervasive Software がお使いのアプリケーションの将来的な安定性を確保する上で役立ちます。Pervasive Software は、製品を改良し続けるために、開発者からのフィードバックを奨励し、これを反映させています。たとえば、Pervasive PSQL 7 では、ステータス コード 20 はカスタマーのフィードバックに応じてさらにいくつかのステータス コードに分かれていました。ここで示したようにステータス情報を処理しているアプリケーションは、このような拡張に速やかに対応することができます(ステータス コードの区分に関する詳細については、『Status Codes and Messages』を参照してください)。

ポジション ブロック

ポジション ブロック パラメーターは、128 バイト配列のアドレスで、がトラフンザクショナル インターフェイスァイル I/O 構造体や Open(0)オペレーションに関連するポジショニング情報を格納するために使用されます。アプリケーションは、ファイルを開くたびに、固有のポジション ブロックを割り当てる必要があります。

トランザクショナル インターフェイスは、アプリケーションが Open オペレーションを実行する際にポジション ブロックを初期化し、その後ファイルの操作中にこのポジション ブロックを参照して更新します。このため、アプリケーションでは、そのファイルに対する以降すべての Btrieve API オペレーションで同じポジション ブロックを指定する必要があります。


メモ

ポジション ブロックへの書き込みを行ってはいけません。書き込みを行うと、ポジション喪失エラーやその他のエラー、あるいはファイルの損傷などの原因となります。


一度に複数のファイルを開く場合、トランザクショナル インターフェイスはポジション ブロックを使って、特定の呼び出しで対象となるファイルを判別します。同様に、同じファイルを複数回開く場合、トランザクショナル インターフェイスは Open オペレーションごとにそれぞれ異なるポジション ブロックを使用します。さらに、トランザクショナル インターフェイスは、同じファイルを開くクライアントごとにも別個のポジション ブロックを使用します。複数のクライアントでポジション ブロックを共有することはできません。

データ バッファー

アプリケーションでは、データ バッファーを使用してファイルとのデータのやり取りを行います。データ バッファーを使ってトランザクショナル インターフェイスとの間でやり取りされる情報は、実行される Btrieve API オペレーションによって異なります。しばしば、データ バッファーには、アプリケーションとファイルの間で相互に転送される 1 つまたは複数のレコードが格納されています。しかし、Btrieve API オペレーションによっては、ファイル仕様やキー仕様、トランザクショナル インターフェイスのバージョン情報など、その他の情報がデータ バッファーに格納されることもあります。

必ず、ファイル内の最長レコードを収容できるだけの長さのデータ バッファーを割り当ててください。データ バッファーの割り当てサイズよりも大きな値をデータ バッファー長パラメーターに指定した場合、トランザクショナル インターフェイス変更オペレーションによって、データ バッファーの後に続くデータが破壊される可能性があります。

データ バッファー長

データ バッファーを必要とするオペレーションでは、アプリケーションはデータ バッファーのサイズ(バイト単位)を示す変数を渡す必要があります。このデータ バッファーは、オペレーションによって返されるデータを十分格納できるだけの大きさでなければなりません。


メモ

BASIC 開発者:データ バッファー長パラメーターとして、ByRef の長整数を渡す必要があります。

C、COBOL、Pascal の開発者:データ バッファー長パラメーターとして、2 バイトの符号なし整数へのポインターを渡す必要があります。


可変長レコードを含むファイルにレコードを挿入したり、そのファイルを更新する場合、データ バッファー長は、ファイルを最初に作成したときに指定したレコード長に、固定長部分を超えて含まれる文字数を加算した値と等しくなければなりません。可変長レコードを取得する場合、データ バッファー長はファイル内の最長レコードに対応できる長さである必要があります。1 件のレコードが 64 KB より長い場合は、レコードの部分を操作するためにチャンク オペレーションを使用する必要があります。

トランザクショナル インターフェイスはデータ バッファー長パラメーターによって、データ バッファーに使用可能なスペース量を判断します。割り当てたデータ バッファーより長いデータ バッファー長を渡すと、トランザクショナル インターフェイスによってメモリが上書きされる場合があります。データ バッファー長は、実際に割り当てられたデータ バッファーのサイズを常に正確に表すようにしてください。

キー バッファー

Btrieve API オペレーションでキー バッファーが使用されない場合でも、アプリケーションは各 Btrieve オペレーションにキー バッファー パラメーターを渡す必要があります。オペレーションによっては、アプリケーションがキー バッファーのデータを設定する場合や、Btrieve API 関数がこれを返す場合があります。


メモ

BASIC 開発者:キー バッファー パラメーターとして文字列を渡す必要があります。キー値が整数である場合、アプリケーションでは Btrieve API 関数を呼び出す前に、MKI$ ステートメントを使用してキー値を文字列に変換しておく必要があります。キーが複数のセグメントから構成されている場合は、それらを結合して 1 つの文字列変数にし、その変数をキー バッファーとして渡す必要があります。

キー バッファーとして渡した文字列変数がキーの定義された長さより短い場合、トランザクショナル インターフェイスからエラーが返されます。アプリケーションの最初の呼び出しがキー バッファーの初期化を必要としない場合は、文字列変数に SPACE$(x) の値を割り当てます。ここで x は、キーの定義されている長さを表します。アプリケーションが文字列変数に BASIC の何らかの値を割り当てるまで、その長さは 0 になります。

C 開発者:キー バッファー パラメーターとしてキー値を含む変数のアドレスを渡す必要があります。BTITYPES.H ファイルは、キー バッファーを VOID ポインター(BTI_VOID_PTR)として定義しています。必要に応じて、アプリケーションでキー バッファーのデータ型を定義できます。

COBOL 開発者:キー バッファー パラメーターとしてレコード変数を渡す必要があります。キーが複数のセグメントから構成されている場合は、01 レベルのレコード下の個別フィールドとして、それらを正しい順序でリストします。これで、レコード全体をキー バッファーとして渡すことができます。

Pascal 開発者:キー バッファー パラメーターとしてキー値を含む変数を渡す必要があります。キーが複数のセグメントから構成されている場合は、レコード構造体を使ってキーに含まれる個々のフィールドを定義します。


ほとんどの環境で、アプリケーションが Btrieve API 呼び出しを実行するとき、トランザクショナル インターフェイスはキー バッファー長を決めることができません。このため、バッファーは少なくとも、キーを最初に作成したときに指定したキー長と同じだけの長さがあるようにしてください。そうでないと、Btrieve API オペレーションにより、メモリ内でキー バッファーの後に格納されているデータが破壊される可能性があります。キーの最大長は 255 なので、常に 255 バイトのキー バッファーにすることをお勧めします。

キー番号

キー番号パラメーターで渡される情報は、実行しているオペレーションによって異なります。ほとんどの場合、キー番号には、特定のオペレーションが最高 119 あるキー(アクセス)パスのうちのどれに従っているかを示す値が含まれます。しかし、ファイルを開くときのモードを示す値など、その他の情報がキー番号パラメーターから渡されたり、キー番号パラメーターに返される場合もあります。

BTRV および BTRVID 関数では、キー番号パラメーターは 2 バイト整数です。BTRCALL、BTRCALLID、BTRCALL32、および BTRCALLID32 関数では、キー番号パラメーターは 1 バイトの符号付き文字(BTI_CHAR)です。すべての関数で、キー番号パラメーターは 0 から 118 までの範囲の値となります。Btrieve API 関数がキー番号パラメーターを変更することはありません。

クライアント ID

クライアント ID パラメーターは、BTRVID 関数および BTRCALLID 関数でのみ使用されます。クライアント ID パラメーターは、トランザクショナル インターフェイスがコンピューター上のクライアントを区別できるようにする 16 バイト構造体のアドレスです。クライアント ID には次のような構造体を使用します。

表 2 クライアント ID 構造体
要素
長さ
(バイト単位)
説明
Filler(フィラー)
12
0 に初期化します。
Service Agent ID
(サービス エージェント ID)
2
トランザクショナル インターフェイスに対するアプリケーションの各インスタンスを識別します。これは 2 文字の ASCII 値です。この ID の値は ASCII 値の AA(0x41 0x41)より大きいか等しくなければなりません。トランザクショナル インターフェイスは次の値に特殊な意味を持たせています。
 
 
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 を確立します。トランザクショナル インターフェイスでは、この一意な識別子を、並行処理およびトランザクション処理のために使用します。

キー長

キー長パラメーターは、BTRCALL、BTRCALLID、BTRCALL32 および BTRCALLID32 関数でのみ使用されます。

これらの関数を使用する場合は、キー長パラメーターとして、割り当てられたキー バッファー長の値を含む符号なしの文字(BTI_BYTE)を渡す必要があります。指定できる最大長は 255 です(キーの最大長)。


Btrieve API 関数

Btrieve API オペレーションの要約