Btrieve API Guide (v11)

Get Direct/Chunk(23)

Get Direct/Chunk オペレーション(B_GET_DIRECT)では、チャンクと呼ばれるレコードの部分を 1 つまたは複数取得できます。このオペレーションは、65,535 バイトより長いレコードを含むファイルで特に役に立ちます。データ バッファー パラメーターの長さには制限があるため、このようなレコードは長すぎて、ほかの Get および Step オペレーションでは取得できません。アプリケーションでは、物理アドレスを指定することで、チャンクが取得されるレコードを指定します。通常、レコード内でのチャンクの位置は、そのオフセットと長さで指定されます。

パラメーター

 
オペレーション コード
ポジション ブロック
データ バッファー
データ バッファー長
キー バッファー
キー番号
送り値

 

戻り値
 

 
 

前提条件

手順

  1. オペレーション コードに 23 を設定します。オプションで、ロック バイアスも指定できます。
  2. ファイルのポジション ブロックを渡します。
  3. 詳細の説明に従って、データ バッファーを指定します。
  4. データ バッファー長に、入力構造体の長さ(表 19 または表 20)とトランザクショナル インターフェイスに取得するように要求したバイト数の、どちらか大きい方を指定します。
    Get Direct/Chunk オペレーションの一部のオプションでは、データ バッファー以外の場所にチャンクを取得します。データ バッファー長を計算する方法については、詳細を参照してください。
  5. キー番号パラメーターに -2(0xFE)を設定します。

詳細

データ バッファーでは、次のチャンク ディスクリプターのいずれかを使用します。

ランダム チャンク

次の例は、ランダムに配置されている 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 By Percentage(44)

Get Direct/Record(23)