 | Btrieve API Guide (v9 SP2 (9.5) revision 1) |  |
|
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.
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.
Use one of the following chunk descriptors in the Data Buffer:
The following example shows a record with three randomly spaced chunks (shaded areas): chunk 0 (bytes 0x12 through 0x16), chunk 1 (bytes 0x2A through 0x31), and chunk 2 (bytes 0x41 through 0x4E).
To define a random chunk descriptor, your application must create a structure in the Data Buffer, based on the following table.
|
Element
|
Length (in Bytes)
|
Description
|
|---|---|---|
|
Subfunction
|
4
|
Type of chunk descriptor; one of the following:
|
|
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 Table 2-11.
|
|
Chunk Definition
(Repeat for each chunk) |
12
|
Each Chunk Definition is a 4-byte Chunk Offset, followed by a 4-byte Chunk Length, followed by a 4-byte User Data, described as follows:
|
|
1For 16-bit 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.
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:
The record contains three chunks (shaded areas): 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 2-38.
|
Element
|
Length (in Bytes)
|
Description
|
|---|---|---|
|
Subfunction
|
4
|
Type of chunk descriptor; one of the following:
|
|
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 Table 2-11.
|
|
Distance Between Rows
|
4
|
Number of bytes between the beginning of each chunk.
|
|
User Data
|
4
|
(Used only with indirect descriptors.) A 32-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 16-bit 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.
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:
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.
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.
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.
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:
The Update Chunk operation does not change the physical currency or the current logical record.
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.
|
Chapter contents
Prev topic: Update (3)
|
