Btrieve API Guide (v11)

Update Chunk(53)

Update Chunk オペレーション(B_CHUNK_UPDATE)では、レコードの 1 つまたは複数の部分(チャンク)の情報を変更できます。また、既存のレコードに情報を追加してレコードを長くしたり、既存のレコードを指定したオフセットで切り詰めることもできます。

パラメーター

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

 

戻り値
 

 
 

 

前提条件

手順

  1. オペレーション コードに 53 を設定します。
  2. レコードを含むファイルのポジション ブロックを渡します。
  3. 詳細の説明に従って、データ バッファーを指定します。
  4. データ バッファー長に、データ バッファーに格納するバイト数以上の値を設定します。データ バッファー長の計算の詳細については、「詳細」を参照してください。
  5. レコードの取得に使用したキー番号をキー番号パラメーターに設定します。システム定義のログ キー(システム データ)を使用するには、125 を指定します。

詳細

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

ランダム チャンク ディスクリプター構造体

次の例は、ランダムに配置されている 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 オペレーションに渡さないでください。異なるキー番号を渡すと、トランザクショナル インターフェイスによって確立されるポジショニングが予測できないものになります。



Update(3)

Version(26)