C API Functions I

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

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

SEE ALSO

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

 

ctdbInsField

  • Insert a new field into a table before the field number given by Index.

Declaration

CTHANDLE ctdbInsField(CTHANDLE Handle, NINT Index, pTEXT FieldName,

CTDBTYPE FieldType, VRLEN FieldLength)

Description

ctdbInsField() inserts a new field into a table before the field number given by the Index parameter. This is implemented as follows: the field that is currently at position Index, and any fields "above" it (with higher field numbers than Index) will be shifted upwards (have one added to their field numbers). This frees up position Index, which will then be occupied by the new field. See the code below for an example. This function handles the field handle allocation. Field handle deallocation is automatically handled by ctdbCloseTable() and ctdbCloseAll(). Use ctdbInsFieldByName() to insert a field in a table in a position specified by name. Use ctdbAddField() to add a field to the end of the table. Use ctdbDelField() and ctdbDelFieldByName() to delete fields from a table. ctdbInsField() does the field handle allocation. After the segments, indexes, and fields have been defined, the table can be created or altered with ctdbCreateTable() or ctdbAlterTable().

  • Handle [in] the Table handle.
  • Index [in] the field number - notice that the new field will have this field number.
  • FieldName [in] the field name.
  • FieldType [in] the field type. Available types are listed in the left-hand column ("FairCom DB API Field Type") in Field Types.
  • FieldLength [in] the maximum length of CHAR, VARCHAR, BINARY, and VARBINARY fields (64K bytes max). The maximum length of LVARCHAR, LVARBINARY fields (2GB max, or set to 0 for "2GB"). This parameter is ignored for all other field types (the non-array-like types).

    Note that FieldLength [in] must account for the underlying data type. For example, for a string field allowing up to 256 bytes of application data, the following field length needs to be specified:

    CT_FSTRING (fixed length string) length = 256
    CT_STRING (null terminated string) length = 257
    CT_2STRING (2 byte length prefix) length = 258
    CT_4STRING (4 byte length prefix) length = 260

Returns

ctdbInsField() returns a field handle on success, or NULL on failure.

Example

/* allocate a new table handle */

CTHANDLE hTable = ctdbAllocTable(hDatabase);

/* add two fields to the table record definition */

ctdbAddField(hTable, "FirstField", CT_INTEGER, 4); /* This is field #0 */

ctdbAddField(hTable, "SecondField", CT_CHAR, 30); /* This is field #1 (for now!) */

/* insert a field into the location previously occupied by field #1 ("SecondField") */

ctdbInsField(hTable, 1, "ThirdField", CT_BOOL, 1);

/* create the table */

ctdbCreateTable(hTable, "MyTable", CTCREATE_NORMAL);

The fields in the table are now as follows: Field #0="FirstField". Field #1="ThirdField". Field #2="SecondField".

 

See also

ctdbAllocTable(), ctdbAddField(), ctdbInsFieldByName(), ctdbDelField(), ctdbDelFieldByName(), ctdbMoveField()

ctdbInsFieldByName

Insert a new field into a table before the field named by FieldIndex.

Declaration

CTHANDLE ctdbInsFieldByName(CTHANDLE Handle, pTEXT FieldIndex, pTEXT

FieldName, CTDBTYPE FieldType, VRLEN FieldLength)

Description

ctdbInsFieldByName() inserts a new field into a table before the field given by the FieldIndex parameter, which specifies the name of an existing field in the table. This is implemented as follows: the existing field with the name FieldIndex, and any fields "above" it (with higher field numbers than that field) will be shifted upwards (have one added to their field numbers). This frees up the position previously occupied by the named field, which will then be occupied by the new field. See the code below for an example.

This function handles the field handle allocation. Field handle deallocation is automatically handled by ctdbCloseTable() and ctdbCloseAll(). Use ctdbInsField() to insert a field in a table in a position specified by a number. Use ctdbAddField() to add a field to the end of the table. Use ctdbDelField() and ctdbDelFieldByName() to delete fields from a table.

ctdbInsFieldByName() does the field handle allocation. After the segments, indexes, and fields have been defined, the table can be created or altered with ctdbCreateTable() or ctdbAlterTable().

  • Handle [in] the Table handle.
  • FieldIndex [in] the name of the existing field - notice that the new field will go into the table at this field's current location.
  • FieldName [in] the new field name.
  • FieldType [in] the field type. Available types are listed in the left-hand column ("FairCom DB API Field Type") of the table in Field Types.

FieldLength [in] the maximum length of CHAR, VARCHAR, BINARY, and VARBINARY fields (64K bytes max). The maximum length of LVARCHAR, LVARBINARY fields (2GB max, or set to 0 for "2GB"). This parameter is ignored for all other field types (the non-array-like types).

Returns

ctdbInsFieldByName() returns a field handle on success, or NULL on failure.

Example

/* allocate a new table handle */

CTHANDLE hTable = ctdbAllocTable(hDatabase);

/* add two fields to the table record definition */

ctdbAddField(hTable, "FirstField", CT_INTEGER, 4); /* This is field #0 */

ctdbAddField(hTable, "SecondField", CT_CHAR, 30); /* This is field #1 (for now!) */

/* insert a field into the location previously occupied by field "SecondField" */

ctdbInsFieldByName(hTable, "SecondField", "ThirdField", CT_BOOL, 1);

/* create the table */

ctdbCreateTable(hTable, "MyTable", CTCREATE_NORMAL);

The fields in the table are now as follows: Field #0="FirstField". Field #1="ThirdField". Field #2="SecondField".

See also

ctdbAllocTable(), ctdbAddField(), ctdbInsField(), ctdbDelField(), ctdbDelFieldByName(), ctdbMoveField()
 

ctdbInsSegment

Insert a segment before the segment indicated by SegNumber

Declaration

CTHANDLE ctdbInsSegment(CTHANDLE Handle, NINT SegNumber,

CTHANDLE FieldHandle, CTSEG_MODE SegMode)

Description

ctdbInsSegment() inserts a segment before the segment indicated by SegNumber segment, given the index handle. The operation of inserting a segment links the index with the field in the table. In order to insert a segment with this function, the segment must be defined based on individual full fields, using what is known as record schema. See the c-tree Plus documentation for further information on record schemas. This function handles the segment handle allocation. Segment handle deallocation is automatically handled by ctdbCloseTable() and ctdbCloseAll().

Use ctdbInsSegmentByName() or ctdbInsSegmentByNbr() to insert a segment given the index number.Use ctdbAddSegment() to add a segment to an index. Use ctdbDelSegment() to delete a segment from an index.

After the segments, indexes, and fields have been defined, the table can be created or altered with ctdbCreateTable() or ctdbAlterTable().

  • Handle [in] the index handle.
  • SegNumber [in] the position to insert the new segment - insert the new segment before this segment number.
  • FieldHandle [in] the Field Handle.
  • SegMode [in] the Index segment mode. The valid values for the segment modes are: CTSEG_SCHSEG, CTSEG_USCHSEG, CTSEG_VSCHSEG, CTSEG_UVSCHSEG, CTSEG_SCHSRL, described in FairCom DB API definitions. If used with a different segment mode, this call will return error 4047, meaning invalid segment mode. ctdbInsSegmentEx() accepts any segment mode.

Returns

ctdbInsSegment() returns the new segment handle on success, or NULL on failure.

Example


pMyIndex = ctdbGetIndex(pMyTable, 0); // retrieve first index handle

pMyNewIseg = ctdbInsSegment(pMyIndex, 0, , CTSEG_ UREGSEG);

RetVal = ctdbAlterTable(pMyTable, 0);

See also

ctdbAddSegment(), ctdbDelSegment(), ctdbInsSegmentByName(), ctdbInsSegmentByNbr(), ctdbInsSegmentEx()

 

ctdbInsSegmentByName

Insert a segment before the segment indicated by SegNumber, given the field name.

Declaration

CTHANDLE ctdbInsSegmentByName(CTHANDLE Handle, NINT IndexNbr, NINT SegNumber,

pTEXT FieldName, CTSEG_MODE SegMode)

Description

ctdbInsSegmentByName() inserts a new segment index before the segment indicated by SegNumber, given the index number and the field name. The operation of inserting a segment links the index with the field in the table. In order to insert a segment with this function, the segment must be defined based on individual full fields, using what is known as record schema. See the c-tree Plus documentation for further information on record schemas. This function handles the segment handle allocation. Segment handle deallocation is automatically handled by ctdbCloseTable() and ctdbCloseAll().

After the segments, indexes, and fields have been defined, the table can be created or altered with ctdbCreateTable() or ctdbAlterTable().

  • Handle [in] the Table Handle.
  • IndexNbr [in] the Index number.
  • SegNumber [in] the segment before which the new segment will be inserted.
  • FieldName [in] the Field name.
  • SegMode [in] the Index segment mode. The valid values for the segment modes are: CTSEG_SCHSEG, CTSEG_USCHSEG, CTSEG_VSCHSEG, CTSEG_UVSCHSEG, CTSEG_SCHSRL, described in FairCom DB API definitions. If used with a different segment mode, this call will return error 4047, meaning invalid segment mode. ctdbInsSegmentEx() accepts any segment mode.

Returns

ctdbInsSegmentByName() returns the segment handle on success, or NULL on failure

Example


pMyNewIseg = ctdbInsSegmentByNbr(pMyTable,0,0,Balance,CTSEG_ REGSEG);

RetVal = ctdbAlterTable(pMyTable, 0);

See also

ctdbInsSegment(), ctdbInsSegmentByNbr(), ctdbInsSegmentEx()

ctdbInsSegmentByNbr

Insert a segment before the segment indicated by SegNumber, given the field and index numbers.

Declaration

CTHANDLE ctdbInsSegmentByNbr(CTHANDLE Handle, NINT IndexNbr,

NINT SegNumber, NINT FieldNbr, CTSEG_MODE SegMode)

Description

ctdbInsSegmentByNbr() inserts a segment before the segment indicated by SegNumber, given the index and field numbers. The operation of inserting a segment links the index with the field in the table. In order to insert a segment with this function, the segment must be defined based on individual full fields, using what is known as record schema. See the c-tree Plus documentation for further information on record schemas. This function handles the segment handle allocation. Segment handle deallocation is automatically handled by ctdbCloseTable() and ctdbCloseAll().

After the segments, indexes, and fields have been defined, the table can be created or altered with ctdbCreateTable() or ctdbAlterTable().

  • Handle [in] the Table Handle.
  • IndexNbr [in] the Index number.
  • SegNumber [in] the segment before which the new segment will be inserted.
  • FieldNbr [in] the Field number.
  • SegMode [in] the Index segment mode. The valid values for the segment modes are: CTSEG_SCHSEG, CTSEG_USCHSEG, CTSEG_VSCHSEG, CTSEG_UVSCHSEG, CTSEG_SCHSRL, described in FairCom DB API definitions. If used with a different segment mode, this call will return error 4047, meaning invalid segment mode. ctdbInsSegmentEx() accepts any segment mode.

Returns

ctdbInsSegmentByNbr() returns the segment handle on success, or NULL on failure

Example


pMyNewIseg = ctdbInsSegmentByNbr(pMyTable, 0, 0, 1, CTSEG_ REGSEG);

RetVal = ctdbAlterTable(pMyTable, 0);

See also

ctdbInsSegmentByName(), ctdbInsSegment(), ctdbInsSegmentEx()

ctdbInsSegmentEx

Insert a new extended index segment before the segment indicated.

Declaration

CTHANDLE ctdbInsSegmentEx(CTHANDLE Handle, NINT SegNumber, NINT offset,

NINT length, CTSEG_MODE SegMode)

Description

ctdbInsSegmentEx() inserts a new extended index segment before the segment SegNumber. A segment is denominated extended if it is based on the segment offset. This function handles the segment handle allocation. Segment handle deallocation is automatically handled by ctdbCloseTable() and ctdbCloseAll().

After the segments, indexes, and fields have been defined, the table can be created or altered with ctdbCreateTable() or ctdbAlterTable().

  • Handle [in] the index handle.
  • SegNumber [in] the segment number before which we should insert the new segment.
  • offset [in] the absolute byte offset.
  • length [in] the segment length in bytes.
  • SegMode [in] the Index segment mode. The valid values for the segment modes are listed in Section FairCom DB API definitions. Notice that ctdbInsSegmentEx() does work with Absolute byte offset segments.

Returns

ctdbInsSegmentEx() returns the segment handle on success, or NULL on failure

Example


pMyIndex = ctdbGetIndex(pMyTable, 0); // retrieve first index handle

pMyNewIseg = ctdbInsSegmentEx(pMyIndex, 0, 32, 4, CTSEG_ UREGSEG);

RetVal = ctdbAlterTable(pMyTable, 0);

See also

ctdbInsSegmentByName(), ctdbInsSegment(), ctdbInsSegmentByNbr(), ctdbAddSegmentEx()

ctdbIsActiveDatabase

Retrieve the active state of a database.

Declaration

CTBOOL ctdbIsActiveDatabase(CTHANDLE Handle)

Description

ctdbIsActiveDatabase() retrieves the active state of a database, connected or disconnected. A database is active when it is connected. To connect the database, use ctdbConnect().

  • Handle [in] the Database Handle.

Returns

ctdbIsActiveDatabase() returns YES if the database is connected and NO if the database is disconnected.

See also

ctdbAllocDatabase(), ctdbIsActiveSession(), ctdbIsActiveTable(), ctdbConnect()

ctdbIsActiveSession

Check if a session is active. A session is active when the session handle has been allocated and the session is logged in to the server.

Declaration

CTBOOL ctdbIsActiveSession(CTHANDLE Handle)

Description

ctdbIsActiveSession() checks to see if a session is active. A session is defined as active when the session handle has been allocated by ctdbAllocSession() and the session is logged in to the server with ctdbLogon().

  • Handle [in] the session handle.

Returns

ctdbIsActiveSession() returns YES if the session is active and NO otherwise.

Example


act=ctdbIsActiveSession(hSession);

if (act)

printf("\n\nThe server is active.\n");

else

{

printf("\n\nThe Session is not active. Logon first.\n");

ctdbLogon(hSession, "FAIRCOMS", "ADMIN", "ADMIN");

}

See also

ctdbLogon(), ctdbAllocSession(), ctdbIsActiveDatabase(), ctdbIsActiveTable()

ctdbIsActiveTable

Retrieve the active state of a table.

Declaration

CTBOOL ctdbIsActiveTable(CTHANDLE Handle)

Description

ctdbIsActiveTable() retrieves the active state of a table. A table is active if it is open.

  • Handle [in] the Table Handle.

Returns

ctdbIsActiveTable() returns YES if the table is open and NO otherwise.

See also

ctdbAllocTable(), ctdbFreeTable(), ctdbIsActiveSession(), ctdbIsActiveDatabase()

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

Value Symbolic Constant Explanation
0 NO Batch operation not underway.
1 YES Batch operation underway.

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

Value Symbolic Constant Explanation
0 NO Batch operation not underway.
1 YES Batch operation underway.

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

ctdbIsEditedRecord

Retrieve the edited record flag.

Declaration

CTBOOL ctdbIsEditedRecord(CTHANDLE Handle)

Description

ctdbIsEditedRecord() retrieves the edited record flag. If YES, the record has been edited since it has been read from the table. Functions like ctdbSetFieldAsString() and all other ctdbSetFieldAs...() functions set the edited record flag to YES. Functions like ctdbAllocRecord(), ctdbClearRecord(), ctdbResetRecord(), ctdbFindRecord() and other search functions clear the edited record flag. Use ctdbIsNewRecord() to check the new record flag.

  • Handle [in] the record handle.

Returns

ctdbIsEditedRecord() returns the edited record flag.

See also

ctdbAllocRecord(), ctdbIsNewRecord()

ctdbIsExtSegment

Check if the segment mode is one of the extended modes.

Declaration

CTBOOL ctdbIsExtSegment(CTSEG_MODE SegMode)

Description

ctdbIsExtSegment() checks to see if the segment mode is one of the extended modes. Extended segments must have been added to the index with ctdbAddSegmentEx().

  • SegMode [in] the segment mode.

Returns

ctdbIsExtSegment() returns YES if the segment mode is extended, NO otherwise.

See also

ctdbAddSegmentEx()

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

Value Symbolic Constant Explanation
0 NO Batch operation not underway.
1 YES Batch operation underway.

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

 

ctdbIsFieldMaskOn

Return if a field Mask has been activated on the record handle.

Declaration

CTBOOL ctdbDECL ctdbIsFieldMaskOn(CTHANDLE Handle)

Description

  • Handle [IN] - Record handle

Returns

TRUE if a field mask has been defined (and so it is active) on the record handle.

 

ctdbIsFieldNumeric

Indicate if a field represents a numeric field type.

Declaration

CTBOOL ctdbIsFieldNumeric(CTHANDLE Handle)

Description

ctdbIsFieldNumeric() indicates if the field handle represents a field with a numeric value. The numeric field types are: CT_CHAR, CT_CHARU, CT_INT2, CT_INT2U, CT_INT4, CT_INT4U, CT_DATE, CT_TIME, CT_MONEY, CT_TIMES, CT_SFLOAT, CT_DFLOAT, CT_EFLOAT, CT_CURRENCY, CT_NUMBER, and CT_INT8.

  • Handle [in] a Field Handle.

Returns

ctdbIsFieldNumeric() returns YES if the field represents a numeric value and NO if the field does not represent a numeric value

Example


/* if fields hField1 and hField2 are numeric, add the values and store the result in hField1 */

if (ctdbIsFieldNumeric(hField1) && ctdbIsFieldNumeric(hField2))

{

CTNUMBER res, val1, val2;

ctdbGetFieldAsNumber(hRecord, ctdbGetFieldNbr(hField1), &val1);

ctdbGetFieldAsNumber(hRecord, ctdbGetFieldNbr(hField2), &val2);

ctdbNumberAdd(&val1, &val2, &res);

ctdbSetFieldAsNumber(hRecord, ctdbGetFieldNbr(hField1), &res);

}

See also

ctdbGetFieldNbr(), ctdbGetFieldProperties()

ctdbIsFilteredRecord

Indicate if the record is being filtered or not.

Declaration

CTBOOL ctdbIsFilteredRecord(CTHANDLE Handle)

Description

ctdbIsFilteredRecord() indicates if the records are being filtered or not. To insert filtering logic to the record retrieval, use ctdbFilterRecord().

  • Handle [in] the Record or Table Handle.

Returns

ctdbIsFilteredRecord() returns YES if the record has been filtered, and NO otherwise.

Example

/* if record filter is active, turn it off */

if (ctdbIsFilteredRecord(hRecord))

ctdbSetFilter(hRecord, NULL, CTFILTER_NONE);

See also

ctdbFilterRecord(), ctdbGetFilter(), ctdbGetFilterType(), ctdbIsFilteredRecord(), ctdbSetFilter()

 

ctdbIsFTSearchOn

Indicate if a Full-Text Search is active or not.

ctdbIsLeapYear

Indicate if the year in a packed CTDATE is a leap year.

Declaration

CTBOOL ctdbIsLeapYear(CTDATE date)

Description

ctdbIsLeapYear() indicates if the year in a packed CTDATE is a leap year.

  • date is the date in CTDATE format.

Returns

ctdbIsLeapYear() returns YES if the year in a packed CTDATE is a leap year, and NO otherwise.

ctdbIsLockActive

Indicates if session-wide record locking is currently active.

Declaration

CTBOOL ctdbIsLockActive(CTHANDLE Handle)

Description

ctdbIsLockActive() indicates if session-wide record locking is currently active. Session-wide record locking is active/enabled if a call to ctdbLock(), with one of the READ or WRITE segment mode variations, has been made. The lock active flag is cleared with a call to ctdbUnlock() or with a call to ctdbLock() with the lock mode set to CTLOCK_FREE or CTLOCK_SUSPEND. Ending a transaction via calls to ctdbCommit() or ctdbUnlock() will also clear the lock active flag. This function does not verify if a call to ctdbLockRecord() was made because ctdbIsLockActive() does not check the lock status of individual records. To do that, use ctdbGetRecordLock().

  • Handle [in] the Session or any other Handle.

Returns

ctdbIsLockActive() returns YES if the session-wide record locking mode is one of the READ or WRITE variations, NO otherwise.

Example


if (ctdbIsLockActive(pSession))

ctdbUnlock(pSession);

See also

ctdbLock(), ctdbUnlock(), ctdbGetLockMode(), ctdbLockRecord(), Locking

ctdbIsNewRecord

Retrieve the new record flag.

Declaration

CTBOOL ctdbIsNewRecord(CTHANDLE Handle)

Description

ctdbIsNewRecord() retrieves the new record flag. The new record flag is set to YES by functions like ctdbAllocRecord(), ctdbClearRecord(), ctdbDeleteRecord(). Functions like ctdbFindRecord(), ctdbWriteRecord() set the new record flag to NO. Use ctdbIsEditedRecord() to check the edited record flag.

  • Handle [in] the record handle.

Returns

ctdbIsNewRecord() returns the new record flag.

See also

ctdbAllocRecord(), ctdbIsEditedRecord()

ctdbIsNullField

Check if the contents of a field are null.

Declaration

CTBOOL ctdbIsNullField(CTHANDLE Handle, NINT FieldNbr)

Description

ctdbIsNullField() checks to see if the contents of a field are null.

  • Handle [in] the record handle.
  • FieldNbr [in] the field number.

Note: this function looks at a single field in a single record/row.

Returns

ctdbIsNullField() returns YES if the field is NULL, or NO if the field is not NULL.

See also

ctdbHasNullFieldSupport(), ctdbGetFieldNullFlag(), ctdbClearField

To read/write the "NOT NULL" attribute of a column in the SQL layer, see ctdbGetFieldNullFlag and, see ctdbSetFieldNullFlag

ctdbIsNumberZero

Check if a number is zero.

Declaration

CTBOOL ctdbIsNumberZero(pCTNUMBER pNumber)

Description

ctdbIsNumberZero() checks to see if a number is zero.

  • pNumber [in] pointer to a number.

Returns

ctdbIsNumberZero() returns YES if the number is zero, NO otherwise.

See also

ctdbNumberZero()

ctdbIsRecordRangeOn

Indicate if an index range operation is active for this record handle.

Declaration

CTBOOL ctdbIsRecordRangeOn(CTHANDLE Handle);

Description

ctdbIsRecordRangeOn() returns YES if a index range operation is active for this record handle, or NO is no index range is active.

  • Handle is a record handle.

Return

Value

Symbolic Constant

Explanation

0

NO

No index range operation is active

1

YES

Index range operation is active

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(), ctdbRecordRangeOff()

ctdbIsRecordSetOn

Declaration

CTBOOL ctdbDECL ctdbIsRecordSetOn(CTHANDLE Handle);

Description

Indicates if record set is active or not. A record set is active after a successful call to ctdbRecordSetOn(). A record set can be switched off by calling ctdbRecordSetOff().

  • Handle must be a record handle.

Return Values

Returns YES if a record set if active and NO if a record set is not active.

See Also

ctdbRecordSetOn(), ctdbRecordSetOff()

ctdbIsResourceLocked

Indicate if a resource is locked.

DECLARATION

CTBOOL ctdbDECL ctdbIsResourceLocked(CTHANDLE resource);

DESCRIPTION

Retrieve indication if the resource is locked. resource is a handle allocated by ctdbAllocResource().

RETURN

Returns YES if resource is locked, or NO if resource is not locked.

EXAMPLE

if (ctdbIsResourceLocked(hRes))

ctdbUnlockResource(hRes);

SEE ALSO

ctdbAllocResource(), ctdbFreeResource(), ctdbAddResource(), ctdbDeleteResource(), ctdbFirstResource(), ctdbNextResource(), ctdbFindResource(), ctdbFindResourceByName(), ctdbGetResourceType(), ctdbSetResourceType(), ctdbGetResourceNumber(), ctdbSetResourceNumber(), ctdbGetResourceName(), ctdbSetResourceName(), ctdbGetResourceDataLength(), ctdbGetResourceData(), ctdbSetResourceData(), ctdbIsResourceLocked(), ctdbUnlockResource()

ctdbIsSessionExclusive

Retrieves the status of the session exclusive flag.

DECLARATION

CTBOOL ctdbIsSessionExclusive(CTHANDLE Handle);

DESCRIPTION

ctdbIsSessionExclusive() retrieves the status of the session exclusive flag.

  • Handle is a session handle.

RETURN

Value Symbolic Constant Explanation
0 NO Batch operation not under way.
1 YES Batch operation under way.

See Errors for a complete listing of valid c-tree error values.

EXAMPLE

/* verify an exclusive logon */
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");
ctdbFreeSession(hSession);

SEE ALSO
ctdbSetSessionExclusive(), ctdbSetDatabaseExclusive(), ctdbIsDatabaseExclusive()

ctdbIsTransActive

Check whether a transaction commit or abort is pending.

Declaration

CTBOOL ctdbIsTransActive(CTHANDLE Handle)

Description

ctdbIsTransActive() checks whether a transaction commit or abort is pending. An active transaction is one that has been initiated with a ctdbBegin() call.

  • Handle [in] the session handle.

Returns

ctdbIsTransActive() returns YES if the transaction is active, NO otherwise.

See also

ctdbBegin(), ctdbCommit(), ctdbAbort()

ctdbIsVariableField

Indicate if a field is allocated in the variable portion of the record.

Declaration

CTBOOL ctdbIsVariableField(CTHANDLE Handle, NINT FieldNbr)

Description

ctdbIsVariableField() Indicates if a field, represented by the field number, is allocated in the variable portion of the record.

  • Handle [in] the record handle.
  • FieldNbr [in] the field number.

Returns

ctdbIsVariableField() returns YES if the field is allocated in the variable portion of the record, NO otherwise.

 

 

 

 

functions api

Was this article helpful?

Give feedback about this article

Related Articles