Product Documentation

c-treeDB API API for C

Previous Topic

Next Topic

Starting a new batch operation

The way a new batch operation is started will depend on the type of batch operation you are performing:

  • Retrieving records by partial key
  • Retrieving records by index range
  • Retrieving records by physical order
  • Deleting a group of records
  • Inserting a group of records

Each of these situations is discussed below.

In This Section

Retrieving records by partial key

Retrieving records by index range

Retrieving records by physical order

Deleting a group of records

Inserting a group of records

Previous Topic

Next Topic

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 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:

  1. Clear a record buffer by calling ctdbClearRecord().
  2. Use ctdbSetFieldAs()... to set the fields that form the partial target key that will be used to select a group of records.
  3. Call the ctdbSetBatch() function with CTBATCH_GET mode, to start a new record retrieval batch operation.
  4. 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.
  5. When you are done with the batch records, call the ctdbEndBatch() function to terminate the batch operation. Please note that another batch operation can only start after the current batch operation is terminated.

To start a new batch operation to retrieve records, you must first establish the partial target key that will identify the group of related records. This is accomplished by clearing a record buffer and setting the fields that form the partial target key. For example, if an invoice item table has one index with segments based on invoice number and item number fields, the following partial code will create a partial target key that will select all invoice item records associated with a particular invoice number:

Example

/* set the partial target key */

ctdbClearRecord(hRecord);

ctdbSetFieldAsSigned(hRecord, 0, Invoice);

After preparing the partial target key, a new batch operation is started by calling the function ctdbSetBatch(). Continuing from the example above, a new batch operation is started by performing the following call:

Example

/* set the batch operation */

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

printf("ctdbSetBatch failed with error %d\n", ctdbGetError(hRecord));

/* retrieve and display all records */

while (ctdbNextBatch(hRecord) == CTDBRET_OK)

PrintRecord(hRecord);

/* terminate batch operations */

ctdbEndBatch(hRecord);

ctdbSetBatch() takes as first argument a valid record handle. The second argument is the batch mode that will direct how the batch operation will be performed. The chapters below describe the available batch modes in detail.

You must provide the length of the ctdbSetBatch()’s target key in bytes. The length of the target key will indicate how many bytes of the target key should be used to create the partial target key. The last parameter is the size of the buffer used internally by c-treeDB API to handle batch operations. A zero value for the last parameter is 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.

Previous Topic

Next Topic

Retrieving records by index range

All records that match an index range expression are loaded into a buffer region maintained internally by c-treeDB 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:

  1. Establish an index range by calling the ctdbRecordRangeOn() function.
  2. Call the ctdbSetBatch() function with the CTBATCH_RANGE mode to start a new record retrieval batch operation.
  3. 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.
  4. When you are done with the batch records, call the ctdbEndBatch() function to terminate the batch operation.
  5. Call the ctdbRecordRangeOff() function to terminate index range operations.

To start a new batch operation to retrieve records, you must first establish the index range operation that will identify the group of related records.

Example:

/* build target key to be used in index range */

TEXT lRange[32];

VRLEN len = (VRLEN)sizeof(lRange);

NINT op = CTIX_EQ;

if (ctdbClearRecord(hRecord);

ctdbSetFieldAsSigned(hRecord, 0, Invoice);

if (ctdbBuildTargetKey(hRecord, CTFIND_EQ, (pVOID)lRange, &len) != CTDBRET_OK)

printf("ctdbBuildTargetKey failed with error %d\n", ctdbGetError(hRecord));

/* set the index range based on the target key */

if (ctdbRecordRangeOn(hRecord, 1, (pVOID)lRange, NULL, CTIX_EQ&op) != CTDBRET_OK)

printf("ctdbRecordRangeOn failed with error %d\n", ctdbGetError(hRecord));

After setting the index range operation, you may start a new batch operation by calling the ctdbSetBatch() function.

Example:

/* set the batch operation */

if (ctdbSetBatch(hRecord, CTBATCH_RANGE, 0, 0) != CTDBRET_OK)

printf("ctdbSetBatch failed with error %d\n", ctdbGetError(hRecord));

/* retrieve and display all records */

while (ctdbNextBatch(hRecord) == CTDBRET_OK)

PrintRecord(hRecord);

/* terminate batch operations */

ctdbEndBatch(hRecord);

/* terminate the index range */

ctdbRecordRangeOff(hRecord);

Notice when retrieving records by index range ctdbSetBatch()’s targetLen parameter is set to zero. The last parameter is the size of the buffer used internally by c-treeDB API to handle batch operations. A zero value for the last parameter is 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.

Previous Topic

Next Topic

Retrieving records by physical order

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

  1. Call the ctdbSetBatch() function with the CTBATCH_PHYS mode to start a new record retrieval batch operation.
  2. 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.
  3. When you are done with the batch records, call the ctdbEndBatch() function to terminate the batch operation.

Example

/* set the batch operation */

if (ctdbSetBatch(hRecord, CTBATCH_PHYS, 0, 0) != CTDBRET_OK)

printf("ctdbSetBatch failed with error %d\n", ctdbGetError(hRecord));

/* retrieve and display all records */

while (ctdbNextBatch(hRecord) == CTDBRET_OK)

PrintRecord(hRecord);

/* terminate batch operations */

ctdbEndBatch(hRecord);

Notice when retrieving records by index range ctdbSetBatch()’s targetLen parameter is set to zero since no partial key is need for this operation. The last parameter is the size of the buffer used internally by c-treeDB API code to handle batch operations. A zero value for this parameter is 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.

A physical order batch read is slightly faster than going through an index because it has fewer reads to do.

See Also

Previous Topic

Next Topic

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:

  1. Clear a record buffer by calling the ctdbClearRecord() function.
  2. Use the ctdbSetFieldAsxxx() functions to set the fields that form the partial target key that will be used to select a group of records.
  3. Call the ctdbSetBatch() function with the CTBATCH_DEL mode to delete a group of related records.
  4. Call the ctdbEndBatch() function to terminate the delete record batch operation.

Example

/* set the partial target key */

ctdbClearRecord(hRecord);

ctdbSetFieldAsSigned(hRecord, 0, Invoice);

/* set the batch operation */

if (ctdbSetBatch(hRecord, CTBATCH_DEL, sizeof(Invoice), 0) != CTDBRET_OK)

printf("ctdbSetBatch failed with error %d\n", ctdbGetError(hRecord));

/* end the batch operation */

if (ctdbEndBatch(hRecord) != CTDBRET_OK)

printf("ctdbEndBatch failed with error %d\n", ctdbGetError(hRecord));

You must provide the length of ctdbSetBatch()’s Target key in bytes. The length of the target key indicates how many bytes of the target key should be used to create the partial target key. The last parameter is the size of the buffer used internally by c-treeDB API to handle batch operations. A zero value for the last 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.

Previous Topic

Next Topic

Inserting a group of records

A group of new records are loaded into a buffer region maintained internally by c-treeDB 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 records 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:

  1. Call the ctdbSetBatch() function with the CTBATCH_INS mode, to insert a group of records.
  2. For each record to be inserted perform the following operations:
    1. Call the ctdbClearRecord() function to clear a record buffer.
    2. For each field in the record call one of the ctdbSetFieldAs...() functions to set the field data.
    3. Call the ctdbInsertBatch() to insert the record into the batch buffer.
  3. Call the ctdbEndBatch() function to indicate no more records will be inserted.

Example

/* set the batch operation */

if (ctdbSetBatch(hRecord, CTBATCH_INS, 0, 0) != CTDBRET_OK)

printf("ctdbSetBatch failed with error %d\n", ctdbGetError(hRecord));

/* prepare the first record */

ctdbClearRecord(hRecord);

ctdbSetFieldAsSigned(hRecord, 0, Invoice); /* invoice number */

ctdbSetFieldAsSigned(hRecord, 1, 0); /* invoice item number */

ctdbSetFieldAsSigned(hRecord, 2, 100); /* item quantity */

ctdbSetFieldAsSigned(hRecord, 3, 1001); /* item code */

if (ctdbInsertBatch(hRecord) != CTDBRET_OK) /* insert record in batch */

printf("ctdbInsertBatch failed with error %d\n", ctdbGetError(hRecord));

/* prepare the second record */

ctdbClearRecord(hRecord);

ctdbSetFieldAsSigned(hRecord, 0, Invoice); /* invoice number */

ctdbSetFieldAsSigned(hRecord, 1, 1); /* invoice item number */

ctdbSetFieldAsSigned(hRecord, 2, 200); /* item quantity */

ctdbSetFieldAsSigned(hRecord, 3, 1002); /* item code */

if (ctdbInsertBatch(hRecord) != CTDBRET_OK) /* insert record in batch */

printf("ctdbInsertBatch failed with error %d\n", ctdbGetError(hRecord));

/* terminate the batch operation */

if (ctdbEndBatch(hRecord) != CTDBRET_OK)

printf("ctdbEndBatch failed with error %d\n", ctdbGetError(hRecord));

Notice when inserting a group of records ctdbSetBatch()’s targetLen parameter is set to zero as no partial key is needed for this operation. The last parameter is the size of the buffer used internally by c-treeDB API 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.

TOCIndex