ctdbReadRecord

Reread a record from its offset

Declaration

CTDBRET ctdbReadRecord(CTHANDLE Handle)

Description

ctdbReadRecord() rereads a record from its offset. The record cursor must have been activated with a call to one of the search routines, and no subsequent call to ctdbClearRecord().

• Handle [in] the record handle.

Returns

ctdbReadRecord() returns CTDBRET_OK if successful, or the c-tree error code on failure.

See also

ctdbAllocRecord(), ctdbWriteRecord(), ctdbClearRecord()

ctdbRebuildTable

Calls the RBLIFILX() function to rebuild a c-tree table.

Declaration

CTDBRET ctdbRebuildTable(CTHANDLE Handle, CTREBUILD_MODE mode);

Description

• Handle [IN] Table handle
• mode [IN] The following modes are available:

Note Exercise care when using CTREBUILD_DATAONLY and CTCREBUILD_UPDATEIFIL modes together as the index files will be removed from the table IFIL definition even if the index files still exist in the file system. This can cause later problems if ctdbAlterTable() is called to recreate the removed indexes.

ctdbRebuildTable() calls the FairCom DB RBLIFILX() function to rebuild a c-tree table. When used in conjunction with the open modes CTOPEN_CORRUPT and CTOPEN_DATAONLY, the ctdbRebuildTable() function can be used as a direct replacement for the c-tree ctrbldif rebuild utility.

The following steps are performed by FairCom DB API during a table rebuild process:

1. If a transaction is active, and the table being rebuilt was created with CTCREATE_TRNLOG or CTCREATE_PREIMG, the transaction is committed before the table is rebuilt, and the transaction is restarted after the table rebuild process is completed.
2. The update corrupt flag, updflg, of the header of the data file is cleared.
3. The internal delete stack chain of fixed-length data files or the internal delete management index of variable length data files are rebuilt.
4. The existing index files are removed and new index files are rebuilt over the existing files, optimized for both size and speed.

You must open the table before ctdbRebuildTable() is executed. It is recommended that the table be opened with CTOPEN_EXCLUSIVE mode. If the table is corrupt, you will need to open the table with the CTOPEN_CORRUPT mode and then call ctdbRebuildTable() to rebuild the data and index files. If there are missing or corrupt index files, open the table with CTOPEN_DATAONLY mode and ctdbRebuildTable() will reconstruct the missing index files.

There may be situations when you need to invoke this function to rebuild only the data file. After the data file rebuild is successful, you may need to call ctdbRebuildTable() again to rebuild the index files.

Return Values

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

See Also

ctdbAlterTable()

ctdbRecordAtPercentile

Find a record located at about the given percentile value.

Declaration

CTDBRET ctdbRecordAtPercentile(CTHANDLE Handle, NINT pecent);

Description

ctdbRecordAtPercentile() read the record located at, approximately, the given percentile value.

Handle is a record handle and percent indicate the percentile value. The valid values for percent are from 0 to 100, indicating 0% to 100%. ctdbRecordAtPercentile() return CTDBRET_OK on success.

The record is located using the record handle current index. You may select a new current index by calling ctdbSetDefaultIndex() function. The table must have at least one index to be able to use this function.

The record returned is an approximation location indicated by the percentual value passed to ctdbRecordAtPercentile().

ctdbRecordAtPercentile(), which is based on c-tree low level function KeyAtPercentile(), and it is very efficient since it does not traverse all of the key values in order to determine the record located at the specified percentile. However, ctdbRecordAtPercentile() is only an approximation since it assumes that key values are uniformly distributed among all of the b-tree leaf nodes.

ctdbRecordAtPercentile() may be used to support scroll bar positioning, found in many GUI windowing environments, in the cases when the position must be maintained in key sequential order.

Return

See FairCom DB API Errors and Return Values for a complete listing of valid FairCom DB API error codes and return values.

Example

/* display the record at 50% of table */

if (ctdbRecordAtPercentile(hRecord, 50) == CTDBRET_OK)

{

DisplayTheRecord(hRecord);

}

else

{

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

}

See also

ctdbSetDefaultIndex()

ctdbRecordRangeOff

Terminate a record index range operation established by ctdbRecordRangeOn().

Declaration

CTDBRET ctdbRecordRangeOff(CTHANDLE Handle);

Description

ctdbRecordRangeOff() terminate a range operation.

• Handle is a record handle.

Return

See FairCom DB API Errors and Return Values for a complete listing of valid FairCom DB API error codes and return values.

Example

/* display all records where age is greater than 65 */

void DisplayAll(CTHANDLE hRecord)

{

UTEXT lRange[32];

VRLEN lRangeLen = 32;

NINT op[1] = {CTIX_GT};

NINT fldno = ctdbGetFieldNumberByName(hHandle, "age");

CTDBRET eRet;

ctdbClearRecord(hRecord);

ctdbSetFieldAsSigned(hRecord, fldno, 65);

ctdbSetDefaultIndex(hRecord, 0);

ctdbBuildTargetKey(hRecord, CTFIND_EQ, lRange, &lRangeLen);

eRet = ctdbRecordRangeOn(hRecord, 1, lRange, NULL, op);

if (eRet == CTDBRET_OK)

{

eRet = ctdbFirstRecord(hRecord);

while (eRet == CTDBRET_OK)

{

TEXT str[128];

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

printf("%s\n", str);

eRet = ctdbNextRecord(hRecord);

}

}

if (ctdbIsRecordRangeOn(hRecord))

ctdbRecordRangeOff(hRecord);

}

See also

ctdbRecordRangeOn(), ctdbIsRecordRangeOn()

ctdbRecordRangeOn

Establish a new index range on a record handle.

Declaration

CTDBRET ctdbRecordRangeOn(CTHANDLE Handle, NINT SegCount,

pVOID lRange, pVOID uRange, pNINT operators);

Description

ctdbRecordRangeOn() establish a new range based on the key segment values passed on lRange and uRange buffers, and the operators for each segment. Once the range is set, use ctdbFirstRecord(), ctdbNextRecord(), ctdbPrevRecord() and ctdbLastRecord() to navigate the records in the specified range. The range is set for all index entries that are situated between the lower bounds and upper bounds values. The segment values are stored in lRange and uRange buffers in the same order and type of the index segment definition. If a previous range exists for this index, the previous range is released and the new range is established. Ranges take precedence over sets. While a record handle has both a Set (ctdbRecordSetOn()) and a Range enabled, the Range takes precedence and the Set is ignored.

• Handle is the record handle.
• SegCount indicates the number of index segments values that should be used for setting the range, and the number of operators, since there must be one operator for each key segment in lRange and/or uRange.
• lRange is a buffer with the lower range segment values. Use the function ctdbBuildTargetKey() to build the lRange buffer.
• uRange is a buffer with the upper range segment values. Use the function ctdbBuildTargetKey() to build the uRange buffer.
• operators 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 maybe set to null (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.

Return

See FairCom DB API Errors and Return Values for a complete listing of valid FairCom DB API error codes and return values.

Example

/* display all records where age is greater than 65 */

/* NOTE: Always check the return type of API functions for errors. */

/* This code omits much of that for brevity. */

void DisplayAll(CTHANDLE hRecord)

{

UTEXT lRange[32];

VRLEN lRangeLen = 32;

NINT op[1] = {CTIX_GT};

NINT fldno = ctdbGetFieldNumberByName(hHandle, "age");

CTDBRET eRet;

ctdbClearRecord(hRecord);

ctdbSetFieldAsSigned(hRecord, fldno, 65);

ctdbSetDefaultIndex(hRecord, 0);

ctdbBuildTargetKey(hRecord, CTFIND_EQ, lRange, &lRangeLen);

eRet = ctdbRecordRangeOn(hRecord, 1, lRange, NULL, op);

if (eRet == CTDBRET_OK)

{

eRet = ctdbFirstRecord(hRecord);

while (eRet == CTDBRET_OK)

{

TEXT str[128];

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

printf("%s\n", str);

eRet = ctdbNextRecord(hRecord);

}

}

if (ctdbIsRecordRangeOn(hRecord))

ctdbRecordRangeOff(hRecord);

}

See also

ctdbRecordRangeOff(), ctdbIsRecordRangeOn()

ctdbRecordSetOff

Disable and free an existing record set.

Declaration

CTDBRET ctdbRecordSetOff(CTHANDLE Handle)

Description

ctdbRecordSetOff() disables and free an existing record set. To enable a new record set, use ctdbRecordSetOn().

• Handle [in] the record handle.

Returns

ctdbRecordSetOff() returns CTDBRET_OK if successful, or the c-tree error code on failure. The possible errors associated with ctdbRecordSetOff() are:

• CTDBRET_NOTRECORD (4024): Invalid Record Handle

Example

ctdbRecordSetOn(pRec, 5);

ctdbSetDefaultIndexByName(pRec, "last name");

ctdbSetFieldAsString(pRec, 0, "silva");

ctdbFirstRecord(pRec);

ctdbRecordSetOff(pRec);

See also

ctdbAllocRecord(), ctdbRecordSetOn()

ctdbRecordSetOn

Enable a new record set. The target key is built from the contents of the record buffer.

Declaration

CTDBRET ctdbRecordSetOn(CTHANDLE Handle, NINT siglen)

Description

ctdbRecordSetOn() enables a new record set. The target key is built from the contents of the record buffer.

• Handle [in] the record handle.
• siglen [in] the number of key bytes to be used by the set.

When record set is enabled, the record operations will be substituted by the set operations. This means that, when record set is enabled, operations like ctdbFirstRecord() will search for the first record in the set instead of the first record in the entire table.

Just one record set can be enabled for each record handle. If it is necessary to have more than one record set enabled at the same time, more than one record handle will be required. To disable and free an existing record set, use ctdbRecordSetOff().

If used in conjunction with filters (ctdbFilterRecord()), may behave as a simple query.

Returns

ctdbRecordSetOn() returns CTDBRET_OK if successful, or the c-tree error code on failure. The possible errors associated with ctdbRecordSetOn() are:

• CTDBRET_NOTRECORD (4024): Invalid record handle
• CTDBRET_NOTACTIVE (4012): Table is not active
• CTDBRET_NOINDEX (4048): No index in the active table
• CTDBRET_NOMEMORY (4001): No memory to allocate the key

Example

/* display all records in set - no error checking */

void DisplayAll(CTHANDLE pRec)

{

NINT count = 0;

ctdbClearRecord(pRec);

ctdbSetDefaultIndexByName(pRec, "index_name");

ctdbSetFieldAsString(pRec, 0, "silva");

ctdbRecordSetOn(pRec, 5);

if (ctdbFirstRecord(pRec) == CTDBRET_OK)

{

do

{

count++;

PrintRecord(pRec);

}

while (ctdbNextRecord(pRec) == CTDBRET_OK);

}

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

}

See also

ctdbAllocRecord(), ctdbRecordSetOff(), ctdbFilterRecord()

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

ctdbRemoveCriteria

Removes a criteria from the given CTResultSet handle.

Declaration

ctdbRemoveCriteria(CTHANDLE Handle, CTHANDLE CriteriaHandle)

Parameters:

• Handle [IN] - Result Set handle
• CriteriaHandle [IN] - Result Set Criteria Handle

Description

The result set handle is allocated (ctdbAllocateResultSet()) for a specific table handle, and then it is possible to add one or more criteria (ctdbAddCriteria()). The criteria have a field to be checked against the table handle that owns the result set, one or two values (depending on the comparison operator) and the operator to be used. The operator can be on of: CTIX_EQ, CTIX_NE, CTIX_GT, CTIX_GE, CTIX_LE, CTIX_LT, CTIX_BET, CTIX_BET_IE, CTIX_BET_EI, CTIX_BET_EE or CTIX_NOTBET. When the result set has all the criteria added, it can be turned on or off (ctdbResultSetOnOff()) for any record handle that is allocated for the same table handle that owns the result set.

Limitations

• A result set can't be turned on for a record that is already filtered. And when a record has a result set turned on, it is not possible to add any other filter. This limitation may be relaxed in the future.
• When a result set is changed (ctdbAddCriteria(), ctdbRemoveCriteria() and ctdbUpdateCriteria()), it must be re-applied to the record handle (ctdbResultSetOnOff()) to have these changed take effect..

Returns

CTDBRET_OK on success. CTDBRET error code on failure.

Example

   CTHANDLE hResSet;
   CTHANDLE hResSetCri;
 
/* Allocate a Result Set for Table */
if (!(hResSet = ctdbAllocateResultSet( hTable, "resSet1" )))
    Handle_Error("Test_ResultSet1(); ctdbAllocateResultSet()");

/* Add a new criteria for the Result Set just allocated */
if (!(hResSetCri = ctdbAddCriteria( hResSet, hField0, "1002", NULL, CTIX_EQ )))
    Handle_Error("Test_ResultSet1(); ctdbAddCriteria()");

/* Turn on the Result Set for the current record handle */
if (ctdbResultSetOnOff( hResSet, hRecord, YES, YES, CTLOC_NONE ) != CTDBRET_OK)
    Handle_Error("Test_ResultSet1(); ctdbResultSetOnOff()");

/* Display records on the Result Set */
Display_Records(hRecord);

/* Release Result Set handle */
ctdbFreeResultSet( hResSet );

See also

• ctdbGetResultSetHandle, ctdbAllocateResultSet, ctdbFreeResultSet, ctdbResultSetOnOff, ctdbGetResultSetByName, ctdbGetResultSetCriHandle, ctdbAddCriteria, ctdbRemoveCriteria, ctdbUpdateCriteria, ctdbGetActiveResultSet

ctdbRemoveFieldMask

Empty and deactivate the field Mask.

Declaration

CTDBRET ctdbDECL ctdbRemoveFieldMask(CTHANDLE Handle)

Description

• Handle [IN] - Record handle

Returns

FairCom DB API return code on error.

ctdbRemoveTable

Removes any c-tree table.

Declaration

CTDBRET ctdbDECL ctdbRemoveTable(CTHANDLE Handle);

• Handle is a table handle.

Description

The ctdbRemoveTable() function allows any table data file and its associated index files to be deleted from disk, including tables that are not members of a database / not created in a CTSESSION_CTDB or CTSESSION_SQL session. This function is intended for CTSESSION_CTREE tables, which are not a part of a database.

If the table was opened under a database handle, the table is closed and ctdbDeleteTable() is called. The handle must be active.

If the table was opened under a database handle, meaning that the provided table handle is "active", this function closes that table and then calls ctdbDeleteTable() to delete the files. If the table handle is not active, the table is opened exclusive by this function and then deleted. In this case, you must first set the path, file extension, and password for the table handle before calling ctdbRemoveTable(). See ctdbSetTablePath(), ctdbSetTableExtension(), and ctdbSetTablePassword(). Note that it is simpler to delete the table and index files using ctdbDeleteTable(), so use that function if you can.

V11.5 and Later

In V11.5 and later, ctdbRemoveTable() expects the table handle to have the path, password, file extension, and name information. A non-active table handle does not have this information. (Close and create clean up and deactivate the table handle.) While the path, password and file extensions can be set by the FairCom DB API API, there is no function to set the name. As a result, ctdbRemoveTable() does not work on non-active tables and could have failed with various errors.

This function will now fail immediately and return error CTDBRET_NOTACTIVE (4012) if the table handle is not active.

ctdbRemoveTable() deletes a c-tree data file and associated index files from disk. If the table was opened under a database handle, the table is closed and ctdbDeleteTable() is called. The handle must be active.

Compatibility Change: This modification is a change in behavior.

Return

See FairCom DB API Errors and Return Values for a complete listing of valid FairCom DB APIerror codes and return values.

Example

/* delete a FairCom DB API table */

if (ctdbRemoveTable(MyHandle) != CTDBRET_OK)

printf("ctdbRemoveTable Failed!\n");

See also

ctdbDeleteTable()

ctdbRenameTable

Renames the specified table from oldname to newname.

Declaration

ctdbRenameTable(CTHANDLE Handle, pTEXT oldname, pTEXT newname);

Description

• Handle a database handle
• newname a string containing the original table name
• newname a string containing the new table name

SESSION_CTREE Mode

Prior to release V11, the FairCom DB API ctdbRenameTable() function was able to rename tables only with a valid database handle involved in the process, which made this function unusable when working with CTREE session modes.

In release V11 and later, new functionality has been implemented in ctdbRenameTable() so that, if a table handle that directly refers to a session is passed to the function, the rename is done at the CTREE level. If the first parameter is a database handle or a table handle referring to a database, the function continues to work as it has in the past.

Return Values

ctdbResetAll

Reset all record buffers associated with a table.

Declaration

CTDBRET ctdbResetAll(CTHANDLE Handle)

Description

ctdbResetAll() resets all record buffers associated with a table.

• Handle [in] the Table Handle.

Returns

ctdbResetAll() returns CTDBRET_OK if successful, or the c-tree error code on failure.

See also

ctdbResetRecord()

ctdbResetRecord

Reset the record buffer to its original state

Declaration

CTDBRET ctdbResetRecord(CTHANDLE Handle)

Description

ctdbResetRecord() resets the record buffer to its original state.

• Handle [in] the record handle.

Returns

ctdbResetRecord() returns CTDBRET_OK if successful, or the c-tree error code on failure.

See also

ctdbResetAll(), ctdbClearRecord()

ctdbRestoreSavePoint

Restore a transaction save point.

Declaration

CTDBRET ctdbRestoreSavePoint(CTHANDLE Handle, NINT SavePoint)

Description

ctdbRestoreSavePoint() restores a transaction save point.

• Handle [in] the session handle.
• SavePoint [in] the save point number returned by ctdbSetSavePoint(). SavePoint can be set to -1 to back up to most current save point, can be set to -2 to back up one more, -3 more....etc. If SavePoint is 0, the most current save point is restored.

Returns

ctdbRestoreSavePoint() returns CTDBRET_OK if successful, or the c-tree error code on failure.

See also

ctdbAbort(), ctdbBegin(), ctdbClearSavePoint(), ctdbCommit(), ctdbSetSingleSavePoint()

ctdbResultSetOnOff

Attaches or detaches a result set from a record handle.

Declaration

CTDBRET ctdbResultSetOnOff(CTHANDLE Handle, CTHANDLE RecordHandle, 
     CTBOOL OnOffFlag, CTBOOL AutoSortFlag, CTLOC_MODE LocateMode)

Parameters:

• Handle [IN] - Result Set handle.
• RecordHandle [IN] - Record handle.
• OnOffFlag [IN] - YES, if it is turning ON; or NO, if it is turning OFF.
• AutoSortFlag [IN] - YES, if FairCom DB API can choose the best index, or NO, if the current index must be kept.
• LocateMode [IN] - The find modes are: CTLOC_NONE, CTLOC_CASEIN, CTLOC_PARTIAL, and CTLOC_CASEIN_PARTIAL.

Description

ctdbResultSetOnOff() attaches or detaches a given CTResultSet handle to a given record handle. It checks if the result set's table is the of the record and also checks if there isn't any existing filter applied to the record. If there is any, it is not possible to set the result set ON.

The result set handle is allocated (ctdbAllocateResultSet()) for a specific table handle, and then it is possible to add one or more criteria (ctdbAddCriteria()). The criteria have a field to be checked against the table handle that owns the result set, one or two values (depending on the comparison operator) and the operator to be used. The operator can be on of: CTIX_EQ, CTIX_NE, CTIX_GT, CTIX_GE, CTIX_LE, CTIX_LT, CTIX_BET, CTIX_BET_IE, CTIX_BET_EI, CTIX_BET_EE or CTIX_NOTBET. When the result set has all the criteria added, it can be turned on or off (ctdbResultSetOnOff()) for any record handle that is allocated for the same table handle that owns the result set.

Limitations

• A result set can't be turned on for a record that is already filtered. And when a record has a result set turned on, it is not possible to add any other filter. This limitation may be relaxed in the future.
• When a result set is changed (ctdbAddCriteria(), ctdbRemoveCriteria() and ctdbUpdateCriteria()), it must be re-applied to the record handle (ctdbResultSetOnOff()) to have these changed take effect..

Returns

Return CTDBRET_OK on success. CTDBRET code for failure.

Example

   CTHANDLE hResSet;
   CTHANDLE hResSetCri;
 
/* Allocate a Result Set for Table */
if (!(hResSet = ctdbAllocateResultSet( hTable, "resSet1" )))
    Handle_Error("Test_ResultSet1(); ctdbAllocateResultSet()");

/* Add a new criteria for the Result Set just allocated */
if (!(hResSetCri = ctdbAddCriteria( hResSet, hField0, "1002", NULL, CTIX_EQ )))
    Handle_Error("Test_ResultSet1(); ctdbAddCriteria()");

/* Turn on the Result Set for the current record handle */
if (ctdbResultSetOnOff( hResSet, hRecord, YES, YES, CTLOC_NONE ) != CTDBRET_OK)
    Handle_Error("Test_ResultSet1(); ctdbResultSetOnOff()");

/* Display records on the Result Set */
Display_Records(hRecord);

/* Release Result Set handle */
ctdbFreeResultSet( hResSet );

See also

• ctdbGetResultSetHandle, ctdbAllocateResultSet, ctdbFreeResultSet, ctdbResultSetOnOff, ctdbGetResultSetByName, ctdbGetResultSetCriHandle, ctdbAddCriteria, ctdbRemoveCriteria, ctdbUpdateCriteria, ctdbGetActiveResultSet