FairCom DB API for C

ctdbSetBatch

Performs operations on a group of records.

DECLARATION

CTDBRET ctdbDECL ctdbSetBatch(CTHANDLE Handle, CTBATCH_MODE mode, VRLEN targetLen, VRLEN bufferLen);

DESCRIPTION

ctdbSetBatch() 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.

Handle parameter must be a record handle associated with an opened table.
mode specifies 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.
targetLen specifies the number of significant bytes of the partial target key when the batch mode is CTBATCH_GET or CTBATCH_DEL.
bufferLen is the size of the buffer used internally by FairCom DB API code to handle batch operations. A zero value for this parameter indicates the default value size should be used. The default buffer size is calculated as the size of the fixed portion of the record multiplied by 128.

You must specify one of the following Mandatory modes when calling the ctdbSetBatch() function or the CTRecord:SetBatch() method:

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

The following modes are optional and can be OR-ed to the mandatory mode to specify other details on how the batch operation is to be performed.

Mode	Description
CBATCH_GET_INCREMENTAL	Used with CTBATCH_GET or CTBATCH_RANGE to retrieve records incrementally by partial key. The call to ctdbSetBatch() only reads the records that fit into the output buffer.
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_KEEPBUFFER	Added in V12.6 when this mode is OR'd into ctdbSetBatch() mode parameter then the code reuses the batch buffer if already allocated and then ctdbEndBatch() does not release it. If this mode is not OR’d in than ctdbSetBatch() behaves as before and if for any reason there is a batch buffer still allocated it gets freed and reallocated. ctdbBatchEnd() was modified to avoid making client-server round-trips to free resources as it is now aware of pending batch states.
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.

Automatic FairCom DB API Batch Buffer Resize

The ctdbSetBatch() function takes a parameter buffeLen which is the size of the buffer used internally by FairCom DB API to handle batch operations.

CTDBRET ctdbDECL ctdbSetBatch(CTHANDLE Handle, CTBATCH_MODE mode, VRLEN targetLen, VRLEN bufferLen)

A value of 0 for this parameter was an indication that the default value size should be used. The default buffer size is calculated as the size of the fixed portion of the record multiplied by 128.

In this release and later, when bufferLen is set to 0, the default buffer size is calculated as described above, and logic is activated to perform automatic buffer resize if the buffer is not large enough to contain one record.

When bufferLen is not 0 and the buffer is not large enough to contain at least one record, the error BTBZ_ERR (429) is returned. In this case, it is possible to activate the logic to automatically resize the buffer by adding the new CTBATCH_AUTORESIZE FairCom DB API batch mode to the mode parameter.

Retrieving records by partial key

All records with key matching a partial target key are loaded into a buffer region maintained internally by FairCom DB API. 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 batch retrieval operation based on a partial key:

Clear a record buffer by calling ctdbClearRecord() or the CTRecord:Clear() method.
Use ctdbSetFieldAs()... functions or CTRecord::SetFieldAs() methods to set the fields that form the partial target key that will be used to select a group of records.
Call the ctdbSetBatch() function or the CTRecord::SetBatch() method, with CTBATCH_GET mode, to start a new record retrieval batch operation.
If the ctdbSetBatch() function returns with no errors, continue to call the ctdbNextBatch() function repeatedly until all related records are retrieved. ctdbNextBatch() returns BTMT_ERR (428) to indicate no more records are available.
With the FairCom DB API C++ API, call the CTRecord::NextBatch() method repeatedly until all related records are retrieved. CTRecord::NextBatch() returns false to indicate no more records are available.
When you are done with the batch records, call the ctdbEndBatch() function or 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 FairCom DB API. 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:

Establish an index range by calling the ctdbRecordRangeOn() function or the CTRecord::RangeOn() method.
Call the ctdbSetBatch() function or the CTRecord::SetBatch() method with CTBATCH_RANGE mode to start a new record retrieval batch operation.
If the ctdbSetBatch() function returns with no errors, continue to call the ctdbNextBatch() function repeatedly until all related records are retrieved. ctdbNextBatch() returns BTMT_ERR (428) to indicate no more records are available.
With the FairCom DB API C++ API call the CTRecord::NextBatch() method repeatedly until all related records are retrieved. CTRecord::NextBatch() returns false to indicate no more records are available.
When you are done with the batch records, call the ctdbEndBatch() function or the CTRecord::EndBatch() method to terminate the batch operation.
Call the ctdbRecordRangeOff() function or the CTRecord::RangeOff() method to terminate index range operations.

Retrieving records by physical order

All records of a table are loaded by physical order into a buffer region maintained internally by FairCom DB API. 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:

Call the ctdbSetBatch() function or the CTRecord::SetBatch() method with CTBATCH_PHYS mode to start a new record retrieval batch operation.
If the ctdbSetBatch() function returns with no errors, call ctdbNextBatch() repeatedly until all related records are retrieved. ctdbNextBatch() returns BTMT_ERR (428) to indicate no more records are available.
With the FairCom DB API C++ API continue to call the CTRecord::NextBatch() method repeatedly until all related records are retrieved. CTRecord::NextBatch() returns false to indicate no more records are available.
When you are done with the batch records, call the ctdbEndBatch() function or the CTRecord::EndBatch() method to terminate the batch operation.

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, ctdbEndBatch() must be called to terminate the current batch operation.

The following steps must be taken to perform a batch delete record operation:

Clear a record buffer by calling the ctdbClearRecord() function or the CTRecord::Clear() method.
Use the ctdbSetFieldAs...() functions or the CTRecord::SetFieldAs...() methods to set the fields that form the partial target key that will be used to select a group of records.
Call the ctdbSetBatch() function or the CTRecord::SetBatch() method with CTBATCH_DEL mode to delete a group of related records.
Call the ctdbEndBatch() function or the CTRecord::EndBatch() method to terminate the delete record batch operation.

Inserting a group of records

A group of new records are loaded into a buffer region maintained internally by FairCom DB API 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 ctdbEndBatch() 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.

Currently, all record insertion operations do not perform any conversion of record images, key values and record position for heterogeneous client/server implementations.

The following steps must be taken to perform a batch insert record operation:

Call the ctdbSetBatch() function or the CTRecord::SetBatch() method, with CTBATCH_INS mode, to insert a group of records.
For each record to be inserted perform the following operations:
- Call the ctdbClearRecord() function or the CTRecord::Clear() method to clear a record buffer.
- For each field in the record call one of the ctdbSetFieldAs...() functions or CTRecord::SetFieldAs...() methods to set the field data.
- Call the ctdbInsertBatch() or the CTRecord::InsertBatch() method to insert the record into the batch buffer.
Call the ctdbEndBatch() function or the CTRecord::EndBatch() method to indicate no more records will be inserted.

RETURNS

Value	Symbolic Constant	Explanation
0	CTDBRET_OK	No error occurred.

See Appendix A for a complete listing of valid c-tree Plus error values.

EXAMPLE

void GetInvoiceItems(CTHANDLE hRecord, NINT Invoice)

{

NINT count = 0;

/* set the partial target key */

ctdbClearRecord(hRecord);

ctdbSetFieldAsSigned(hRecord, 0, Invoice);

/* set the batch operation */

if (ctdbSetBatch(hRecord, CTBATCH_GET, sizeof(Invoice), 0) == CTDBRET_OK)

{

/* retrieve records */

while (ctdbNextBatch(hRecord) == CTDBRET_OK)

count++;

/* terminate batch operations */

ctdbEndBatch(hRecord);

}

printf("%d records found\n", count);

}