ctdbBatchFiltered

Retrieves the number of records that are rejected in a batch retrieval operation because they do not match the active filter.

Declaration

ULONG ctdbDECL ctdbBatchFiltered(CTHANDLE Handle)

Description

• Handle [IN] - Record handle

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

Return Values

Returns the number of records rejected in a batch retrieval operation that do not match the active filter.

Returns zero if a batch retrieval operation is not active.

The value is significant only if the CTBATCH_RET_FILTER mode has been used in the ctdbSetBatch() call.

See Also

ctdbSetBatchFilter (ctdbSetBatchFilter, ctdbSetBatchFilter)()

ctdbSetBatchRangeOn (ctdbSetBatchRangeOn, ctdbSetBatchRangeOn)()

ctdbSetBatchRangeOff (ctdbSetBatchRangeOff, ctdbSetBatchRangeOff)()

ctdbBatchLoaded

Retrieves the number of batch records loaded into batch buffer.

DECLARATION

LONG ctdbDECL ctdbBatchLoaded(CTHANDLE Handle);

DESCRIPTION

ctdbBatchLoaded() retrieves the number of batch records loaded into batch buffer for CTBATCH_GET, CTBATCH_RANGE or CTBATCH_PHYS operations. This is the number of records that are ready to be retrieved by ctdbNextBatch() function.

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

RETURNS

ctdbBatchLoaded() returns the number of records ready for retrieval or a negative value indicating an error. In case of an error, use the ctdbGetError() function to retrieve the error code.

EXAMPLE

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

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

/* show how many records are ready */

printf("%d records are ready for retrieval\n", ctdbBatchLoaded(hRecord));

SEE ALSO

ctdbBatchLocked(), ctdbBatchMode(), ctdbBatchTotal(), ctdbEndBatch(), ctdbInsertBatch(),
ctdbIsBatchActive(), ctdbNextBatch(), ctdbSetBatch()

ctdbBatchLocked

Retrieves the number of locked batch records.

DECLARATION

LONG ctdbDECL ctdbBatchLocked(CTHANDLE Handle);

DESCRIPTION

Retrieves the number of records locked during a CTBATCH_GET, CTBATH_RANGE or CTBATCH_PHYS operation. If CTBATCH_LOCK_READ or CTBATCH_LOCK_WRITE are specified in the batch mode, ctdbBatchLocked() return the total number of records locked. If CTBATCH_LOCK_ONE is specified, or if no CTBATCH_LOCK_READ or CTBATCH_LOCK_WRITE modes are not specified, ctdbBatchLocked() return zero.

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

RETURNS

ctdbBatchLocked() returns the number of locked records. In case of an error, ctdbBatchLocked() returns a negative value and you may use ctdbGetError() function to retrieve the error code

EXAMPLE

/* set the partial target key */

ctdbClearRecord(hRecord);

ctdbSetFieldAsSigned(hRecord, 0, Invoice);

/* set the batch operation */

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

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

/* show how many records are locked */

printf("%d records are locked\n", ctdbBatchLoaded(hRecord));

SEE ALSO

ctdbBatchLoaded(), ctdbBatchMode(), ctdbBatchTotal(), ctdbEndBatch(), ctdbInsertBatch(),
ctdbIsBatchActive(), ctdbNextBatch(), ctdbSetBatch()

ctdbBatchMode

Retrieve the current batch mode.

DECLARATION

CTBATCH_MODE ctdbDECL ctdbBatchMode(CTHANDLE Handle);

DESCRIPTION

ctdbBatchMode() retrieves the current batch mode. The batch mode is set by calling ctdbSetBatch() function. If a batch operation is not active, ctdbBatchMode() return CTBATCH_NONE. Handle must be a record handle associated with an opened table.

RETURNS

ctdbBatchMode() returns the current batch mode or CTBATCH_NONE if no batch operation is currently active.

Refer to the FairCom DB API Batch Operations chapter for complete details concerning all of the optional batch modes.

EXAMPLE

/* check if a batch operation is in progress */

if (ctdbBatchMode(hRecord) != CTBATCH_NONE)

    printf("Batch operation is underway\n");

else

    printf("No batch operations\n");

SEE ALSO

ctdbBatchLoaded(), ctdbBatchLocked(), ctdbBatchTotal(), ctdbEndBatch(), ctdbInsertBatch(), ctdbIsBatchActive(), ctdbNextBatch(), ctdbSetBatch()

ctdbBatchTotal

Retrieves the total number of records affected by a batch retrieval operation.

DECLARATION

LONG ctdbDECL ctdbBatchTotal(CTHANDLE Handle);

DESCRIPTION

ctdbBatchTotal() retrieves the total number of records selected by a batch retrieval operation. If a batch operation is not active, ctdbBatchTotal() returns zero. Handle must be a record handle associated with an opened table.

RETURNS

Returns the total number of records selected by a batch retrieval operation. In case of an error, ctdbBatchLocked() returns a negative value and you may use ctdbGetError() function to retrieve the error code.

EXAMPLE

ctdbClearRecord(hRecord);

ctdbSetFieldAsSigned(hRecord, 0, Invoice);

/* set the batch operation */

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

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

/* show total number of records */

printf("%d records selected\n", ctdbBatchTotal(hRecord));

SEE ALSO

ctdbBatchLoaded ctdbBatchLocked ctdbBatchMode ctdbEndBatch ctdbInsertBatch ctdbIsBatchActive ctdbNextBatch ctdbSetBatch

ctdbEndBatch

Terminates or cancels a batch operation.

DECLARATION

CTDBRET ctdbDECL ctdbEndBatch(CTHANDLE Handle);

DESCRIPTION

A batch operation must be terminated by calling the ctdbEndBatch() function. Once a batch operation is started with ctdbSetBatch(), no other batch operation is allowed to start until the current batch operation is terminated.

When performing batch retrieval operations, you may cancel the batch operation before retrieving all the records by calling ctdbEndBatch().

If the batch operation is a CTBATCH_RANGE then you must also call ctdbRecordRangeOff() function to terminate the index range used for the batch operation.

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

RETURNS

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

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

SEE ALSO

ctdbBatchLoaded(), ctdbBatchLocked(), ctdbBatchMode(), ctdbBatchTotal(), ctdbInsertBatch(),
ctdbIsBatchActive(), ctdbNextBatch(), ctdbSetBatch()

ctdbFindTableXtd

Find a table in a database dictionary.

Declaration

CTDBRET ctdbDECL ctdbFindTableXtd(CTHANDLE Handle, pTEXT Name, pCTDBDICTDATA data)

Description

CTDB dictionary also stores the table owner while searching for a specific table.

Handle [IN] - Database handle

Name [IN] - Table name

data [OUT] - dictionary data for the table

At table open time, set the table owner in the CTHANDLE structure as defined in the dictionary so that this information is available in the table handle itself.

Return Values

Returns CTDBRET_OK on success or the c-tree error code on failure.

See c-tree Plus Error Codes for a complete listing of valid c-tree Plus error values.

See Also

ctdbFindTable

ctdbFirstTableXtd

Get the first table in a database dictionary.

Declaration

CTDBRET ctdbDECL ctdbFirstTableXtd(CTHANDLE Handle, pCTDBDICTDATA data)

Description

Handle [IN] - Database handle.

data [OUT] - dictionary data for the table

CTDBRET_OK on success or the c-tree error code on failure.

Return Values

CTDBRET_OK on success or the c-tree error code on failure.

See c-tree Plus Error Codes for a complete listing of valid c-tree Plus error values.

See Also

ctdbFirstTable

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:

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

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

RETURNS

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

SEE ALSO

ctdbBatchLoaded(), ctdbBatchLocked(), ctdbBatchMode(), ctdbBatchTotal(), ctdbEndBatch(),
ctdbIsBatchActive(), ctdbNextBatch(), ctdbSetBatch()

ctdbIsBatchActive

Indicates if a batch operation is underway or not.

DECLARATION

CTBOOL ctdbDECL ctdbIsBatchActive(CTHANDLE Handle);

DESCRIPTION

ctdbIsBatchActive() indicates if a batch operation is active or not. This is equivalent to ctdbBatchMode() returning CTBATCH_NONE. Handle must be a FairCom DB API record handle associated with an opened table.

RETURNS

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

EXAMPLE

/* check if a batch operation is active */

if (ctdbIsBatchActive(hRecord))

printf("Batch operation underway\n");

else

printf("No batch operation\n");

SEE ALSO

ctdbBatchLoaded(), ctdbBatchLocked(), ctdbBatchMode(), ctdbBatchTotal(), ctdbEndBatch(),
ctdbInsertBatch(), ctdbNextBatch(), ctdbSetBatch()

ctdbIsDatabaseExclusive

Retrieves the status of the database exclusive flag.

DECLARATION

CTBOOL ctdbIsDatabaseExclusive(CTHANDLE Handle);

DESCRIPTION

ctdbIsDatabaseExclusive() retrieves the status of the database exclusive flag.

• Handle is a session Handle.

RETURN

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

EXAMPLE

/* verify an exclusive logon and connect */

CTHANDLE hSession = ctdbAllocSession(CTSESSION_CTDB);

if (hSession)

{

ctdbSetSessionExclusive(hSession, YES);

if (ctdbLogon(hSession, "FAIRCOM", "ADMIN", "ADMIN") != CTDBRET_OK)

printf("ctdbLogon failed\n");

}

if (ctdbIsSessionExclusive(hSession))

printf("Session is exclusive\n");

else

printf("Session is shared\n");

if (ctdbIsDatabaseExclusive(hDatabase))

printf("Database is exclusive\n");

else

printf("Database is shared\n");

ctdbFreeDatabase(hDatabase);

ctdbFreeSession(hSession);

SEE ALSO

ctdbSetSessionExclusive(), ctdbIsSessionExclusive(), ctdbSetDatabaseExclusive()

ctdbIsFieldDefaultValueSet

Checks if a field default value has been set or not.

DECLARATION

TYPE FunctionTemplate(parameters) TYPE parameters;

DESCRIPTION

Checks if a field default value has been set or not. Returns YES if a field default value was set, otherwise returns NO.

RETURN

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

EXAMPLE

/* check if default field value is set */

hField = ctdbGetField(hTable, 5);

if (ctdbIsFieldDefaultValueSet(hField))

printf("Default field value is set\n");

else

printf("No default field value\n");

SEE ALSO

ctdbSetFieldDefaultValue(), ctdbGetFieldDefaultValue(), ctdbClearFieldDefaultValue(), ctdbClearAllFieldDefaultValue(), ctdbSetFieldDefaultDateTimeType(), ctdbGetFieldDefaultDateType(), ctdbGetFieldDefaultTimeType()

ctdbGetBatchBufferSize

Return the size of the batch buffer.

DECLARATION

VRLEN ctdbDECL ctdbGetBatchBufferSize(CTHANDLE Handle)

DESCRIPTION

ctdbGetBatchBufferSize() returns the size of the batch buffer currently allocated (or -1 if the handle is not a record handle).

• Handle [in] the record handle.

USE CASE

The CTBATCH_KEEPBUFFER mode of ctdbSetBatch can be used to preserve the batch buffer after the batch is finished and reuse it for another batch. ctdbGetBatchBufferSize() can be used to determine if the buffer has gotten too big. If so, ctdbReleaseBatchBuffer() releases the buffer and reallocates it on the next ctdbSetBatch request.

SEE ALSO

ctdbReleaseBatchBuffer(), ctdbSetBatch

ctdbNextBatch

Retrieves the next record from batch buffer.

DECLARATION

CTDBRET ctdbDECL ctdbNextBatch(CTHANDLE Handle);

DESCRIPTION

If the mode of the batch operation is one of CTBATCH_GET, CTBATCH_RANGE or CTBATCH_PHYS then it may be necessary to retrieve all records that match the batch criteria. The records are retrieved by calling the ctdbNextBatch() function.

The ctdbNextBatch() function retrieves the record data from the batch buffer maintained by FairCom DB API’s record handle. After a successful call to the ctdbNextBatch() function the field data can be retrieved by calling the appropriate ctdbGetFieldAs..() functions.

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

RETURNS

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

EXAMPLE

/* retrieve records */

while (ctdbNextBatch(hRecord) == CTDBRET_OK)

{

TEXT invoice[32], item[32];

ctdbGetFieldAsString(hRecord, 0, invoice, sizeof(invoice));

ctdbGetFieldAsString(hRecord, 1, item, sizeof(item));

printf("%-11s %s\n", invoice, item);

}

SEE ALSO

ctdbBatchLoaded(), ctdbBatchLocked(), ctdbBatchMode(), ctdbBatchTotal(), ctdbEndBatch(),
ctdbInsertBatch(), ctdbIsBatchActive(), ctdbSetBatch()

ctdbNextTableXtd

Get the next table in a database dictionary.

Declaration

CTDBRET ctdbDECL ctdbNextTableXtd(CTHANDLE Handle, pCTDBDICTDATA data)

Description

Handle [IN] - Database handle.

data [OUT] - dictionary data for the table

Return Values

Returns CTDBRET_OK on success or the c-tree error code on failure.

See c-tree Plus Error Codes for a complete listing of valid c-tree Plus error values.

See Also

ctdbNextTable

ctdbReleaseBatchBuffer

Release the batch buffer.

Declaration

CTDBRET ctdbDECL ctdbReleaseBatchBuffer (CTHANDLE Handle)

Description

ctdbReleaseBatchBuffer() explicitly releases the batch buffer allocated by ctdbSetBatch. Once the batch is terminated, it can be called to release a buffer left in place due to the CTBATCH_KEEPBUFFER mode.

• Handle [in] the record handle.

Use case

The CTBATCH_KEEPBUFFER mode of ctdbSetBatch can be used to preserve the batch buffer after the batch is finished and reuse it for another batch. ctdbGetBatchBufferSize() can be used to determine if the buffer has gotten too big. If so, ctdbReleaseBatchBuffer() releases the buffer and reallocates it on the next ctdbSetBatch request.

Returns

• CTDBRET_OK on success
• CTDBRET_BATCHISACTIVE if the batch is still active
• CTDBRET_NOTRECORD if the handle passed in is not a record handle

See also

ctdbGetBatchBufferSize(), ctdbSetBatch

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:

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.

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:

1. Clear a record buffer by calling ctdbClearRecord() or the CTRecord:Clear() method.
2. 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.
3. Call the ctdbSetBatch() function or the CTRecord::SetBatch() method, 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.

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.

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

1. Establish an index range by calling the ctdbRecordRangeOn() function or the CTRecord::RangeOn() method.
2. Call the ctdbSetBatch() function or the CTRecord::SetBatch() method with 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.

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.
 

1. When you are done with the batch records, call the ctdbEndBatch() function or the CTRecord::EndBatch() method to terminate the batch operation.
2. 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:

1. Call the ctdbSetBatch() function or the CTRecord::SetBatch() method with 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.

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.

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

1. Clear a record buffer by calling the ctdbClearRecord() function or the CTRecord::Clear() method.
2. 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.
3. Call the ctdbSetBatch() function or the CTRecord::SetBatch() method with CTBATCH_DEL mode to delete a group of related records.
4. 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:

1. Call the ctdbSetBatch() function or the CTRecord::SetBatch() method, with CTBATCH_INS mode, to insert a group of records.
2. 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.
3. Call the ctdbEndBatch() function or the CTRecord::EndBatch() method to indicate no more records will be inserted.

RETURNS

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

}

SEE ALSO

ctdbBatchLoaded(), ctdbBatchLocked(), ctdbBatchMode(), ctdbBatchTotal(), ctdbEndBatch(),
ctdbInsertBatch(), ctdbIsBatchActive(), ctdbNextBatch()

ctdbSetBatchFilter

Sets a record filter to be used in batch operations.

Declaration

CTDBRET ctdbDECL ctdbSetBatchFilter(CTHANDLE Handle, cpTEXT expr)

Description

• Handle [IN] - Record handle
• expr [IN] - The filter expression in text format. NULL or "" to reset it.

This is the batch version of ctdbFilterRecord(). When performing a record batch, use ctdbSetBatchFilter() as it does not connect to the server but instead sets the information locally in the client so it can piggyback onto the ctdbSetBatch() call avoiding an extra network hit. When performing individual record lookups, use ctdbFilterRecord().

Returns

New error code CTDBRET_ALREADYSET = 4170 indicates that a range or a filter for batch operation is already set.

See Also

ctdbSetBatchRangeOn (ctdbSetBatchRangeOn, ctdbSetBatchRangeOn)()

ctdbSetBatchRangeOff (ctdbSetBatchRangeOff, ctdbSetBatchRangeOff)()

ctdbSetBatchRangeOff

Removes the range for record batch operations.

Declaration

CTDBRET ctdbDECL ctdbSetBatchRangeOff(CTHANDLE Handle)

Description

• Handle [IN] - Record handle

This is the batch version of ctdbRecordRangeOff(). When performing a record batch, use ctdbSetBatchRangeOff() as it does not connect to the server but instead clears the information locally in the client avoiding an extra network hit. When performing individual record lookups, use ctdbRecordRangeOff().

Returns

Return CTDBRET_OK on success.

New error code CTDBRET_ALREADYSET = 4170 indicates that a range or a filter for batch operation is already set.

See Also

ctdbSetBatchRangeOn (ctdbSetBatchRangeOn, ctdbSetBatchRangeOn)()

ctdbSetBatchFilter (ctdbSetBatchFilter, ctdbSetBatchFilter)()

ctdbRecordRangeOn()

ctdbRecordRangeOff()

ctdbSetBatchRangeOn

Sets a range to be used in batch operations.

Declaration

CTDBRET ctdbSetBatchRangeOn(CTHANDLE Handle, NINT SegCount, pVOID lRange, pVOID uRange, pNINT operators)

Description

• Handle [IN] - Record handle
• SegCount [IN] - segcount indicates the number of index segments values that should be used for setting the range, and the number of operators, because there must be one operator for each key segment in lRange and/or uRange.
• lRange [IN] - lRange is a buffer with the lower range segment values. Use the function ctdbBuildTargetKey to build the lRange buffer.
• uRange [IN] - uRange is a buffer with the upper range segment values. Use the function ctdbBuildTargetKey to build the uRange buffer.
• operators [IN] - operators is an array of operators. There must be one operator for each key segment in lRange and/or uRange.

The operators CTIX_EQ, CTIX_NE, CTIX_GT, CTIX_GE, CTIX_LE, CTIX_LT are open -ended and use only the lRange buffer for range values and the equivalent key segment in uRange is ignored and may be set to nul (ASCII \0 values). The operators CTIX_BET, CTIX_BET_IE, CTIX_BET_EI, CTIX_BET_EE and CTIX_NOTBET use both lRange and uRange buffers to establish the lower and upper bound values.

This is the batch version of ctdbRecordRangeOn(). When performing a record batch, use ctdbSetBatchRangeOn() as it does not connect to the server but instead sets the information locally in the client so it can piggyback onto the ctdbSetBatch() call avoiding an extra network hit. When performing individual record lookups, use ctdbRecordRangeOn().

Returns

Return CTDBRET_OK on success.

New error code CTDBRET_ALREADYSET = 4170 indicates that a range or a filter for batch operation is already set.

See Also

ctdbSetBatchRangeOff (ctdbSetBatchRangeOff, ctdbSetBatchRangeOff)()

ctdbSetBatchFilter (ctdbSetBatchFilter, ctdbSetBatchFilter)()

ctdbSetBehavior

Set the specified CTDB runtime behavior status.

Declaration

CTDBRET ctDECL ctdbSetBehavior(CTHANDLE Handle, LONG item, CTBOOL state)

Parameters

• Handle [in] the session handle.
• Item [in] the behavior to be set.

Valid Item values include:

Returns

ctdbSetBehavior returns CTDBRET_OK on success, or a FairCom DB API error on failure.

See also

ctdbGetBehavior