FairCom DB API for C

ctdbInsertBatch

Inserts a new record into a batch buffer.

DECLARATION

CTDBRET ctdbDECL ctdbInsertBatch(CTHANDLE Handle);

DESCRIPTION

ctdbInsertBatch() inserts a new record into a batch buffer maintained internally by FairCom DB API. 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.

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:

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

Handle must be a record handle associated with an opened table.

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

/* 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 */

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

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

if (ctdbInsertBatch(hRecord) != CTDBRET_OK) /* insert */

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 */

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

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

if (ctdbInsertBatch(hRecord) != CTDBRET_OK) /* insert */

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));