March 31, 2014
Updated Batch Arsenal
Note: c-treeACE became FairCom DB in November 2020.
c‑treeACE batch operations greatly improve performance by reducing the number of round-trips to the server when processing a group of related records. New additions to c‑treeACE batch operations added in V10.3 extend this valuable capability.
Previously, batch operations provided capabilities to bulk retrieve or delete records matching a partial key. A new powerful batch update mode joins these bulk record operations in the batch function. We have added capability to update a collection of records, each identified by its unique key.
New Options
By default, the new BAT_UPD option 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 Batch Update Operations
For each record in the input buffer, the batch update operation performs the following:
- Either begin a transaction or establish a save point if the user already has an active transaction.
- Build target key from the unique key.
- Read the record with the requested lock:
– If the record exists, update it.
– If the record does not exist, add it. - In case of success or failure: Commit or abort the transaction or clear or restore the save point.
- Release record locks if requested.
Note that a missing key implies a new record will be added.
A unique key is required on the file. If the chosen index allows duplicates, the operation will return an error, so it is important to specify which unique index to use.
The batch function returns the number of added records and the number of updated records.
Update Modes
The Update 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 – Record images are preceded by the key value uniquely identifying the record to be rewritten or added.
With both modes, variable-length data files include a 4-byte data record length 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 can change the unique key used to locate the record. The old key permits the record to be located and read before the rewrite operation.