FairCom ISAM for C

BAT_UPD and BAT_UPD_KEY

By default, BAT_UPD extracts the unique key from the record image, reads the record and then uses the record image provided in the input buffer to perform an Update operation. If the extracted key does not exist, a record ADD operation is performed. A mode called BAT_UPD_KEY is provided in which the old key can be specified for situations in which a rewrite might change the unique key used to locate the record.

Overview of Operations Performed

For each record in the input buffer, the batch update operation will do the following:

1. Either begin a transaction or establish a save point if the user already has an active transaction.
2. Build target key on the unique key.
3. Read the record with the requested lock:
   • If the record exists, update it.
   • If the record does not exist, add it.
4. In case of success or failure: Commit or abort the transaction or clear or restore the save point.
5. Release record locks if requested.

Notice that a missing key implies that a new record will be added.

A unique key is required on the file. If the index allows duplicates, the operation will return an error, so it is important to specify which unique index to use.

The function will return the number of records that were added and the number of records that were updated.

Update Modes

This operation provides two update modes:

• BAT_UPD (default) - The batch update call sends a series of record images and the filno parameter corresponds to a unique key index.
• BAT_UPD_KEY - The record images are preceded by the key value that uniquely identifies the record to be rewritten or added.

In both cases, variable-length data files have the 4-byte length of the data record as the first field of each entry.

In the default BAT_UPD mode, entries are formatted as shown below:

• For fixed-length data file: <record image 1> <record image 2> ...
• For variable-length data file: <reclen 1> <record image 1> <reclen 2> <record image 2> ...

When BAT_UPD_KEY mode is used, entries are formatted as:

• For fixed-length data file: <old key 1> <record image 1> <old key 2> <record image 2> ...
• For variable-length data file: <reclen 1> <old key 1> <record image 1> <reclen 2> <old key 2> <record image 2> ...

The BAT_UPD_KEY mode should be used when a rewrite might change the unique key used to locate the record. The old key permits the record to be located and read before the rewrite operation.

Batch Updates and BAT_RET_BLK Format

Beginning with FairCom DB V11, batch update now recognizes BAT_RET_BLK record format. When using batch update to add variable-length records that were read using a batch physical read with the BAT_RET_BLK option, the batch update failed with error SDAT_ERR. Batch update logic has been modified to recognize the BAT_RET_BLK record format.

Additional Modes

Additional modes can be used with BAT_UPD and BAT_UPD_KEY to provide record locking. See Batch Update operations: BAT_UPD and BAT_UPD_KEY.