Update Chunk (53)
The Update Chunk operation (B_CHUNK_UPDATE) can change the information in one or more portions of a record (each portion being a chunk). It can also append information to an existing record (thereby lengthening the record), or truncate an existing record at a specified offset.
Parameters
 
 
Op Code
Pos Block
Data Buf
Data Buf Len
Key Buffer
Key Number
Sent
* 
* 
* 
* 
 
* 
Returned
 
* 
 
 
* 
 
Prerequisites
•
The file must be open.
•
You must have an established current physical or logical record in the file.
*Note: Although an extended operation or a Get Key operation (+50) establishes the required position, you cannot issue an Update Chunk operation immediately after these operations, because they do not return a single record.
Procedure
1
Set the Operation Code to 53.
2
Pass the Position Block for the file containing the record.
3
Specify a Data Buffer, as described in Details.
4
Set the Data Buffer Length to a value greater than or equal to the number of bytes your application has placed in the Data Buffer. See the “Details” section for more information about calculating the Data Buffer Length.
5
Set the Key Number used for retrieving the record in the Key Number parameter. To use the system-defined log key (also called system data), specify 125.
Details
Use one of the following chunk descriptors in the Data Buffer:
•
Random Chunk Descriptor—To update a single chunk per operation, or to update more than one chunk in a single operation when the chunks are spaced randomly throughout the record.
•
Rectangle Chunk Descriptor—To update many chunks in an operation, when each chunk is the same length and chunks are spaced equidistantly in the record.
•
Truncate Chunk Descriptor—To truncate a record at a specified offset.
Random Chunk Descriptor Structure
The following example shows a record with three randomly spaced chunks (areas containing [*]): chunk 0 (bytes 0x12 through 0x16), chunk 1 (bytes 0x2A through 0x31), and chunk 2 (bytes 0x41 through 0x4E).
00
01
02
03
04
05
06
07
08
09
0A
0B
0C
0D
0E
0F
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
10
11
[*]
[*]
[*]
[*]
16
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
To define a random chunk descriptor, your application must create a structure in the Data Buffer, based on the following table.
Table 48
Random Chunk Descriptor Structure
Element
Length (Bytes)
Description
Subfunction
4
Type of chunk descriptor; one of the following:
•
0x80000000 (Direct random chunk descriptor)—Updates chunks stored directly in the Data Buffer. The data for updating the first chunk is stored in the Data Buffer immediately after the last chunk definition (Chunk n), the data for the second chunk immediately follows the first, and so on.
•
0x80000001 (Indirect random chunk descriptor)—Updates chunks from data at addresses specified by the Chunk Definitions.
NumChunks
4
Number of chunks to be updated. The value must be at least 1. Although no explicit maximum value exists, the chunk definitions must fit in the Data Buffer, which is limited in size as described in 18.
Chunk Definition
(Repeat for each chunk)
12 (for 32-bit applications)
16 (for 64-bit applications)
 
Each Chunk Definition is a 4-byte Chunk Offset, followed by a 4-byte Chunk Length, followed by a 4-byte User Data for 32-bit applications or an 8-byte User Data for 64-bit applications, described as follows:
•
Chunk Offset—Indicates where the chunk begins as an offset in bytes from the beginning of the record. The minimum value is 0, and the maximum value is the offset of the last byte in the record, plus 1.
•
Chunk Length—Indicates how many bytes are in the chunk. The minimum value is 0, and the maximum value 65,535; however, the chunk definitions must fit in the Data Buffer, which is limited in size as described in 18.
•
User Data—(Used only for indirect descriptors.) For 32-bit applications, a 32-bit pointer to the actual chunk data. For 64-bit applications, a 64-bit pointer to the actual chunk data. The format you should use depends on your operating system.1 The transactional interface ignores this element for direct chunk descriptor subfunctions.
1For DOS applications, initialize User Data as a 16-bit offset and a 16-bit segment. User Data cannot address memory beyond the end of its segment. When Chunk Length is added to the offset portion of User Data, the result must be within the segment that User Data defines. By default, the transactional interface does not check for violations of this rule and does not properly handle such violations.
The following table shows a sample direct random chunk descriptor structure for a 32-bit application.
Element
Sample Value
Length (in Bytes)
Subfunction
0x8000000
4
NumChunks
3
4
Chunk 0
 
 
Chunk Offset
0x12
4
Chunk Length
0x05
4
User Data
N/A
4
Chunk 1
 
 
Chunk Offset
0x2A
4
Chunk Length
0x08
4
User Data
N/A
4
Chunk 2
 
 
Chunk Offset
0x41
4
Chunk Length
0x0E
4
User Data
N/A
4
Data for Chunk 0
N/A
5
Data for Chunk 1
N/A
8
Data for Chunk 2
N/A
14
Rectangle Chunk Descriptor Structure
When chunks of the same length are spaced equidistantly throughout a record, you can describe all the chunks to update with a rectangle chunk descriptor. For example, consider the following diagram, which represents offset 0x00 through 0x4F in a record:
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
The record contains three chunks (areas containing [*]): chunk 0 (bytes 0x19 through 0x1C), chunk 1 (bytes 0x29 through 0x2C), and chunk 2 (bytes 0x39 through 0x3C). Each chunk is four bytes long, and a total of 16 (0x10) bytes, calculated from the beginning of each chunk, separates the chunks from one another.
You can update all three chunks using a single rectangle descriptor. To update rectangle chunks, you must create a structure in the Data Buffer based on Table 49.
Table 49
Rectangle Chunk Descriptor Structure
Element
Length (Bytes)
Description
Subfunction
4
Type of chunk descriptor; one of the following:
•
0x80000002 (Direct rectangle chunk descriptor)—Updates chunks stored directly in the Data Buffer. The data for updating the first chunk is stored in the Data Buffer immediately after the last chunk definition (Chunk n), the data for the second chunk immediately follows the first, and so on.
•
0x80000003 (Indirect rectangle chunk descriptor)—Updates chunks from data at addresses specified by the Chunk Definitions.
Number of Rows
4
Number of chunks on which the rectangle chunk descriptor must operate. The minimum value is 1. No explicit maximum value exists.
Offset
4
Offset from the beginning of the record of the first byte to update. The minimum value is 0, and the maximum value is the offset of the last byte in the record, plus 1. If the record is viewed as a rectangle, this element refers to the offset of the first byte in the first row to be retrieved.
Bytes Per Row
4
Number of bytes in each chunk to be updated. The minimum value is 0, and the maximum value is 65,535; however, the chunk definitions must fit in the Data Buffer, which is limited in size as described in 18.
Distance Between Rows
4
Number of bytes between the beginning of each chunk.
User Data
4 (for 32-bit applications)
8 (for 64-bit applications)
(Used only with indirect descriptors.) For 32-bit applications, a 32-bit pointer to the actual chunk data. For 64-bit applications, a 64-bit pointer to the actual chunk data. The format you should use depends on your operating system.1 The transactional interface ignores this element for direct rectangle descriptors; however, you must still allocate the element and initialize it to 0.
Application Distance Between Rows
4
(Used only with indirect rectangle descriptors.) Number of bytes between the beginning of chunks in the rectangle, as the rectangle is stored in your application’s memory, at the address specified by User Data. The transactional interface ignores this element for direct rectangle descriptors; however, you must still allocate the element and initialize it to 0.
1For DOS applications, express User Data as a 16-bit offset followed by a 16-bit segment.
If the rectangle has the same number of bytes between rows when it is in memory as when it is stored as a record, set Application Distance Between Rows with the same value as Distance Between Rows. However, if the rectangle is arranged in your application’s memory with either more or fewer bytes between rows, Application Distance Between Rows allows you to pass that information to the transactional interface.
When you use an indirect rectangle descriptor, the transactional interface uses both the User Data and the Application Distance Between Rows elements to determine the locations from which to read the data for the update. The transactional interface reads data for the first row from offset 0 of User Data. The transactional interface reads the second row’s data from an address specified by User Data plus Application Distance Between Rows. The transactional interface reads the third row’s data from the address specified by User Data plus (Application Distance Between Rows * 2), and so on.
The following table shows a sample direct rectangle chunk descriptor structure for a 32-bit application.
Element Name
Sample Value
Length (in Bytes)
Subfunction
0x80000002
4
Number of Rows
3
4
Offset
0x19
4
Bytes Per Row
0x04
4
Distance Between Rows
0x10
4
User Data
0
4
Application Distance Between Rows
0
4
Data (Row 0)
N/A
4
Data (Row 1)
N/A
4
Data (Row 2)
N/A
4
Truncate Descriptor Structure
The truncate descriptor allows you to truncate a record at a specified offset. To use this type of chunk descriptor, you must create a structure in the Data Buffer, based on the following table:
Table 50
Truncate Descriptor Structure
Element
Length (in Bytes)
Description
Subfunction
4
Type of chunk descriptor. Specify 0x80000004.
ChunkOffset
4
Byte offset into the record where truncation begins. That byte and every byte following it is eliminated. The minimum value is 4. The maximum value is the offset of the final byte in the record.
Next-in-Record Subfunction Bias
If you add a bias of 0x40000000 to any of the subfunctions previously listed, the transactional interface calculates the subfunction’s Offset element values based on your physical intrarecord currency (that is, your current physical position within the record). When you use the Next-in-Record subfunction, the transactional interface ignores the Offset element in the chunk descriptor.
If you use this bias in combination with a random chunk descriptor and it updates more than one chunk in a single operation, the transactional interface calculates the offset for all chunks (except the first) by adding the previous chunk’s length to the previous chunk’s offset. In other words, the next-in-record bias applies to all chunks in the operation.
Append Subfunction Bias
If you add a bias of 0x20000000 to the random chunk descriptor’s subfunction or to the rectangle chunk descriptor’s subfunction, the transactional interface calculates the subfunction’s Offset element value to be one byte beyond the end of the record.
*Note: Do not use this bias with the Next-in-Record bias or the Truncate subfunction.
If you use this bias in combination with a random chunk descriptor and it updates more than one chunk in a single operation, the transactional interface calculates the offset for all chunks (except the first chunk) based on the record’s length after the transactional interface appends the previous chunk.
Result
If the Update Chunk operation is successful, the transactional interface updates the portions of the record identified as chunks in the chunk descriptor portion of the Data Buffer. The new data for updating the chunks is contained either in the chunk descriptor itself (for direct chunk descriptor subfunctions) or in the memory address specified by the 32-bit pointer in each chunk’s User Data element (for indirect chunk descriptor subfunctions). After the Update Chunk operation completes, the transactional interface adjusts the key indexes to reflect any change in the key values, and, if necessary, updates the Key Buffer parameter.
In addition, if the application holds a single-record lock on the record to be updated, the transactional interface releases the lock. However, a multiple-record lock is never released by an Update Chunk operation.
If the Update Chunk operation is unsuccessful, the transactional interface returns one of the following status codes:
5
The record has a key field containing a duplicate key value.
8
The current positioning is invalid.
10
The key field is not modifiable.
22
The data buffer parameter is too short.
58
The compression buffer length is too short.
62
The descriptor is incorrect.
80
The transactional interface encountered a record-level conflict.
97
The data buffer is too small.
103
The chunk offset is too big.
106
The transactional interface cannot perform a Get Next Chunk operation.
Positioning
The Update Chunk operation does not change the physical currency or the current logical record.
*Note: When you perform an Update Chunk operation following a Get operation, do not pass to the Update Chunk operation a Key Number that differs from the one specified in the preceding Get operation. If you do, the positioning established by the transactional interface is unpredictable.