Update (3)

The Update operation (B_UPDATE) changes the information in an existing record.

Parameters


	Op Code	Pos Block	Data Buf	Data Buf Len	Key Buffer	Key Number
Sent
Returned

Note
When using the no-currency-change (NCC) option, the Update operation does not update the value of the Key Buffer parameter; it does not return any information in that parameter.

Prerequisites

The file must be open.

You must have established physical currency in the file. (Although an Extended Get, Extended Step, or Get Key operation establishes the required position, these operations cannot be followed by an Update.)

Procedure

Set the Operation Code to 3. Optionally, you can include a lock bias:

+100-Single wait record lock.

+200-Single no-wait record lock.

+300-Multiple wait record lock.

+400-Multiple no-wait record lock.

For more information about locking, refer to the Pervasive.SQL Programmer's Guide.

Pass the Position Block for the file containing the record.

Store the updated data record in the Data Buffer.

Set the Data Buffer Length to the length of the updated record.

Set the Key Number used for retrieving the record. To use the NCC option, specify -1 (0xFF) for the Key Number. To use the system-defined log key (also called system data), specify 125.

When performing a non-NCC Update operation immediately following a Get operation, pass the Key Number exactly as the MicroKernel returned it on the Get operation; otherwise, the MicroKernel updates the record successfully but returns Status Code 7 on the first Get operation performed after the update.

Result

If the Update operation is successful, the MicroKernel updates the record stored in the file with the new value in the Data Buffer, adjusts the indexes to reflect any change in the key values, and returns the value of the specified key in the Key Buffer. An NCC Update operation does not update the value of the Key Buffer parameter.

If the application holds a single-record lock on the record to be updated, the MicroKernel releases the lock. However, a multiple-record lock is never released by an Update operation.

If the Update operation is unsuccessful, the MicroKernel 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.
80	The MicroKernel encountered a record-level conflict.

Positioning

The Update operation and the NCC Update operation do not affect physical currency.

An Update operation that does not use the NCC option can affect logical currency if the value of the updated key repositions the record in the index. For example, suppose an INTEGER key's logical current record has a value of 1. For that same key, the logical next record has a value of 2. If you update 1 to 4, you no longer have the same logical next record. In this example, after the Update operation, the logical next record has a value that is greater than 4.

An NCC Update operation does not affect logical currency. This means that an application, having performed an NCC Update operation, has the same logical position in the file as it had prior to the Update operation. In such a situation, operations that follow an NCC Update-such as Get Next (6), Get Next Extended (36), Get Previous (7), and Get Previous Extended (37)-return values based on the application's logical currency prior to the NCC Update.

Note
The MicroKernel does not return any information in the Key Buffer parameter as the result of an NCC Update operation. Therefore, an application that must maintain the logical currency must not change the value of the Key Buffer following the NCC Update operation. Otherwise, the next Get operation has unpredictable results.