CTRecord::SetBatch
Perform operations on a group of records.
Declaration
void CTRecord::SetBatch(CTBATCH_MODE mode, VRLEN targetLen, VRLEN bufferLen);
Description
CTRecord::SetBatch() attempts to initiate a specified operation on a group of records with keys matching a partial key value, an index range expression, or the entire table by physical order.
The mode parameter specify which batch operation is to take place. You must choose at least one of the mandatory modes. You may or one or more of the optional mode to specify further parameters for the batch operation. Please refer to the description of the modes below.
In case of errors, CTRecord::NextBatch() throws a CTException.
Mandatory modes
MODE |
Description |
---|---|
CTBATCH_GET |
Retrieve a group of related records by partial key |
CTBATCH_RANGE |
Retrieve a group of related records based on an index range expression |
CTBATCH_PHYS |
Retrieve records from a table in physical order. The starting record for the batch retrieval may be specified. |
CTBATCH_DEL |
Delete a group of related records by partial key |
CTBATCH_INS |
Insert a group of records |
Optional modes
Mode |
Description |
---|---|
CTBATCH_GKEY |
Process records with a greater than or equal key match with the target key. When this mode is specified, the number of matched records is not readily available. ctdbBatchLocked() and CTRecord::BatchLocked() returns a value one greater than ctdbBatchLoaded() to indicate there may be more records to process.This mode is applicable only with CTBATCH_GET and CTBATCH_DEL modes and can not be used with CTBATCH_LKEY. |
CTBATCH_LKEY |
Process records that have a less than or equal key match with the target key.This mode is applicable only with CTBATCH_GET and CTBATCH_DEL modes and can not be used with CTBATCH_GKEY. |
CTBATCH_VERIFY |
Verify that the keys in the index match the values in the key fields of the record. |
CTBATCH_LOCK_KEEP |
Keep all records locked after ...EndBatch() is called. Without this mode, all records locks are released when ...EndBatch() is called. This option is only in effect when used with CTBATCH_LOCK_READ or CTBATCH_LOCK_WRITE. |
CTBATCH_LOCK_READ |
Place a read lock on each record that matches the partial key. |
CTBATCH_LOCK_WRITE |
Place a write lock on each record that matches the partial key. |
CTBATCH_LOCK_BLOCK |
Convert a CTBATCH_LOCK_READ or CTBATCH_LOCK_WRITE to blocking read and blocking write locks, respectively. |
CTBATCH_LOCK_ONE |
Implement an alternative locking strategy: only locks the record during the record read; original locking strategy keeps locks on during entire batch processing. |
CTBATCH_COMPLETE |
...SetBatch() returns a success code only if all matching records are successfully locked. You must specify either CTBATCH_LOCK_READ or CTBATCH_LOCK_WRITE. |
Retrieving records by partial key
All records with key matching a partial target key are loaded into a buffer region maintained internally by c-treeDB. If the selected records do not fit in the buffer, those that fit are loaded, and subsequent calls will retrieve the remaining records.
The following steps must be taken to perform a retrieval batch operation based on a partial key:
When you are done with the batch records, call the CTRecord::EndBatch() method to terminate the batch operation. Please note that another batch operation can only start after the current batch operation is terminated.
Retrieving records by index range
All records that match an index range expression are loaded into a buffer region maintained internally by c-treeDB. If the selected records do not fit in the buffer, those that fit are loaded, and subsequent calls will retrieve the remaining records.
The following steps must be taken to perform an index range batch retrieval of records:
Retrieving records by physical order
All records of a table are loaded by physical order into a buffer region maintained internally by c-treeDB. If the selected records do not fit in the buffer, those that fit are loaded, and subsequent calls will retrieve the remaining records.
The following steps must be taken to perform a physical order batch retrieval of records:
Note: Setting a batch with CTBATCH_PHYS will cause slightly different behavior from setting it with CTBATCH_GET.
If the number of records exceeds the size of the buffer set when calling SetBatch, the total returned by BatchTotal will be only the number of records that fit into the batch buffer for CTBATCH_PHYS batches. If the batch was set with the CTBATCH_GET mode, the total number of records satisfying the batch will be returned, regardless if they all fit in the batch buffer. If a precise count of the number of records in a file is necessary, use GetRecordCount when you are in CTBATCH_PHYS mode.
This difference also affects record locking. If the batch was set with CTBATCH_PHYS, the records are locked when they are read into the buffer, so only the records that have been read into the batch buffer are locked. If the batch was set with CTBATCH_GET, all records are locked on the initial call.
Deleting a group of records
If the intended batch operation is to delete a group of selected records, you need to initially set the partial target key to select the group of related records and then start the batch operation to delete the selected records.
Even if no records are retrieved with the delete operation, CTRecord::EndBatch() must be called to terminate the current batch operation.
The following steps must be taken to perform a batch delete record operation:
Inserting a group of records
A group of new records are loaded into a buffer region maintained internally by c-treeDB and this group of records are inserted into a table.
When the batch buffer fills up, the group of records stored in the batch buffer are inserted into the table. If CTRecord::EndBatch() is called and the batch buffer still contains records, a new insert record operation is performed for the remaining records before the batch operation is terminated.
For transaction controlled files, the batch insertion operation is treated as one all or nothing operation. If no explicit transaction is started, each insertion of records with will start and end its own transaction. Even if an explicit transaction is started, each insertion operation is treated independently through safe points.
Note: currently, all records insertion operations will not perform any conversion of records images, key values and records position for heterogeneous client/server implementations.
The following steps must be taken to perform a batch insert record operation:
For each record to be inserted perform the following operations:
Return
void
Example
void GetInvoiceItems(CTRecord& hRecord, NINT Invoice)
{
NINT count = 0;
try
{
// set the partial target key */
hRecord.Clear();
hRecord.SetFieldAsSigned("Invoice", Invoice);
// set the batch operation
hRecord.SetBatch(CTBATCH_GET, sizeof(Invoice), 0);
{
// retrieve records
while (hRecord.NextBatch())
count++;
// terminate batch operations
hRecord.EndBatch();
}
printf("%d records found\n", count);
}
catch (CTException& err)
{
printf("Batch failed [error %d]\n", hRecord.GetError());
}
}
See Also
CTRecord::BatchLoaded(), CTRecord::BatchLocked(), CTRecord::BatchMode(), CTRecord::BatchTotal(), CTRecord::EndBatch(), CTRecord::InsertBatch(), CTRecord::IsBatchActive(), CTRecord::NextBatch()