Indexing

ctdbGetCndxIndex

Retrieve the conditional index expression string, given the index number.

Declaration

CTDBRET ctdbGetCndxIndex(CTHANDLE Handle, NINT indexnbr, pTEXT buffer,

NINT bufferlen)

Description

ctdbGetCndxIndex() retrieves the conditional index expression string, given the index number. The conditional expression is added, deleted or updated with ctdbUpdateCndxIndex() or ctdbUpdateCndxIndexByName().

• Handle [in] the Table Handle.
• indexnbr [in] the index number.
• buffer [OUT] pointer to buffer to receive the conditional expression.
• bufferlen [IN] size in bytes of buffer. Maybe retrieved with ctdbGetCndxIndexLength() or ctdbGetCndxIndexLengthByName().

Returns

ctdbGetCndxIndex() returns CTDBRET_OK on success, or FairCom DB API error on failure.

See also

ctdbUpdateCndxIndex(), ctdbUpdateCndxIndexByName(), ctdbGetCndxIndexLength(), ctdbGetCndxIndexLengthByName()

ctdbGetCndxIndexByName

Retrieve the conditional index expression string, given the index name.

Declaration

CTDBRET ctdbGetCndxIndexByName(CTHANDLE Handle, pTEXT indexname,

pTEXT buffer, NINT bufferlen)

Description

ctdbGetCndxIndexByName() retrieves the conditional index expression string, given the index name. The conditional expression is added, deleted or updated with ctdbUpdateCndxIndex() or ctdbUpdateCndxIndexByName().

• Handle [in] the Table Handle.
• indexname [in] the index name.
• buffer [OUT] pointer to buffer to receive the conditional expression.
• bufferlen [IN] size in bytes of buffer. Maybe retrieved with ctdbGetCndxIndexLength() or ctdbGetCndxIndexLengthByName().

Returns

ctdbGetCndxIndexByName() returns CTDBRET_OK on success, or FairCom DB API error on failure.

See also

ctdbGetCndxIndex(), ctdbUpdateCndxIndex(), ctdbUpdateCndxIndexByName(), ctdbGetCndxIndexLength(), ctdbGetCndxIndexLengthByName()

ctdbGetCndxIndexLength

Retrieve the length in bytes of the conditional expression string, given the index number.

Declaration

NINT ctdbGetCndxIndexLength(CTHANDLE Handle, NINT indexnbr)

Description

ctdbGetCndxIndexLength() retrieves the length in bytes of the conditional expression string, given the index number. To retrieve the conditional expression, use ctdbGetCndxIndex() or ctdbGetCndxIndexByName(). The conditional expression is added, deleted or updated with ctdbUpdateCndxIndex() or ctdbUpdateCndxIndexByName().

• Handle [in] the Table Handle.
• indexnbr [in] the index number.

Returns

ctdbGetCndxIndexLength() returns the conditional index length in bytes on success or -1 on failure.

See also

ctdbGetCndxIndexLengthByName(), ctdbUpdateCndxIndex(), ctdbUpdateCndxIndexByName()

ctdbGetCndxIndexLengthByName

Retrieve the length in bytes of the conditional expression string, given the index name.

Declaration

NINT ctdbGetCndxIndexLengthByName(CTHANDLE Handle, pTEXT indexname)

Description

ctdbGetCndxIndexLengthByName() retrieves the length in bytes of the conditional expression string, given the index name. To retrieve the conditional expression, use ctdbGetCndxIndex() or ctdbGetCndxIndexByName(). The conditional expression is added, deleted or updated with ctdbUpdateCndxIndex() or ctdbUpdateCndxIndexByName().

• Handle [in] the Table Handle.
• indexname [in] the index name.

Returns

ctdbGetCndxIndexLengthByName() returns the conditional index length in bytes on success or -1 on failure.

See also

ctdbGetCndxIndexLength(), ctdbUpdateCndxIndex(), ctdbUpdateCndxIndexByName()

ctdbGetErrorIndex

Declaration

NINT ctdbDECL ctdbGetErrorIndex(CTHANDLE Handle);

Description

Retrieves the index number that cause a record insert or record update operation to fail. This function should only be called after a ctdbWriteRecord() call fails. The error index number value is maintained until the next call to ctdbWriteRecord().

• Handle must be a record handle

Return Values

A number from 0 to n to indicate which index caused the error. A value of 0 represents the first index, 1 represents the second index, and so on. If the index number can not be obtained, ctdbGetErrorIndex() returns -1.

See Also

ctdbWriteRecord()

ctdbGetIdxno

Retrieve the index file number from a index handle.

DECLARATION

NINT ctdbGetIdxno(CTHANDLE Handle)

DESCRIPTION

Retrieves the index file number to be used with c-tree ISAM or low-level index functions.

• Handle must be an index or segment handle.

Returns the index number on success or -1 on failure. If ctdbGetIdxno() function returns -1, the error code can be retrieved by calling the ctdbGetError() function.

RETURN

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

EXAMPLE

/* retrieve the first key of first index */

TEXT keyval[256];

COUNT idxno = (COUNT)ctdbGetIdxno(ctdbGetIdnex(hTable, 0));

if (FirstKey(idxno, 0), keyval)

printf("FirstKey failed\n");

SEE ALSO

ctdbSwitchInstance(), ctdbSwitchContext(), ctdbGetDatno(), ctdbGetIdxnoByName(), ctdbGetIdxnoByNumber(), ctdbGetError()

ctdbGetIdxnoByName

Retrieve the index file number from a table handle.

Declaration

NINT ctdbGetIdxnoByName(CTHANDLE Handle, pTEXT indexname)

Description

Retrieve the index file number to be used with c-tree ISAM or low-level index functions.

• Handle is a table handle.
• indexname is a string containing the index name.

Return the index number on success or -1 on failure. If ctdbGetIdxnoByNumber() return -1, the error code can be retrieved by calling ctdbGetError() function.

Return

See Appendix A "c-tree Plus Error Codes" in c-tree Plus Programmer's Reference Guide for a complete listing of valid c-tree Plus error values.

Example

/* retrieve the first key of first index */

TEXT keyval[256];

COUNT idxno = (COUNT)ctdbGetIdxnoByName(hTable, "indexname");

if (FirstKey(idxno, 0), keyval)

printf("FirstKey failed\n");

See also

ctdbSwitchInstance(), ctdbSwitchContext(), ctdbGetDatno(), ctdbGetIdxno(), ctdbGetIdxnoByNumber(), ctdbGetError()

ctdbGetIdxnoByNumber

Retrieve the index file number from a table handle.

DECLARATION

NINT ctdbGetIdxnoByNumber(CTHANDLE Handle, NINT index)

DESCRIPTION

Retrieves the index file number to be used with c-tree ISAM and low-level index functions.

• Handle is a table handle.
• index is a FairCom DB API index number. The first FairCom DB API index number is zero.

Returns the index number on success or -1 on failure. If ctdbGetIdxnoByNumber() returns -1, the error code can be retrieved by calling ctdbGetError() function.

RETURN

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

EXAMPLE

/* retrieve the first key of first index */

TEXT keyval[256];

COUNT idxno = (COUNT)ctdbGetIdxnoByNumber(hTable, 0);

if (FirstKey(idxno, 0), keyval)

printf("FirstKey failed\n");

SEE ALSO

ctdbSwitchInstance(), ctdbSwitchContext(), ctdbGetDatno(), ctdbGetIdxno(), ctdbGetIdxnoByName(), ctdbGetError()

ctdbGetIndexDistinctKeyCountFlag

Get the status of the distinct count flag for an index. To optimize some SQL queries, provides a better estimation of the duplicate index selectivity by determining how many distinct keys there are in an index allowing duplicates. The CTDBINDEX_DUPCNTFLAG index status value indicates that the index has distinct key count capability.

Declaration

CTBOOL ctdbGetIndexDistinctKeyCountFlag(CTHANDLE Handle);

Description

ctdbGetIndexDistinctKeyCountFlag() retrieves the setting of the distinct count flag for an index. Use ctdbSetIndexDistinctKeyCountFlag() to set the flag.

• Handle [in] the index handle.

See also

ctdbSetIndexDistinctKeyCountFlag

ctdbGetIndexFilename

Retrieves the current index file name associated with an index.

Declaration

pTEXT ctdbGetIndexFilename(CTHANDLE Handle);

• Handle is an index handle returned by ctdbAddIndex() or ctdbGetIndex() calls.

Description

ctdbGetIndexFilename() may return NULL indicating that the index is a member of an index superfile.

Return

ctdbGetIndexFilename() returns the physical filename of the index.

See Appendix A "c-tree Plus Error Codes" in c-tree Plus Programmer's Reference Guide for a complete listing of valid c-tree Plus error values.

See also

ctdbSetIndexFilename(), ctdbAddIndex(), ctdbGetIndex()

ctdbGetIndexKSeg

Retrieves the index current extended key segment definition.

DECLARATION

CTDBRET ctdbGetIndexKSeg(CTHANDLE Handle, pctKSEGDEF pKSeg);

DESCRIPTION

ctdbGetIndexKSeg() retrieves the current index-wide extended key segment definition. Handle must be a FairCom DB API index handle and pKSeg is a pointer to an extended key segment definition structure which will receive the definition.

RETURN

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

EXAMPLE

ctKSEGDEF kseg;

if ((eRet = ctdbGetIndexKSeg(hTable, &kseg)) != CTDBRET_OK)

printf("ctdbGetIndexKSeg failed with error %d\n", eRet);

SEE ALSO

ctdbSetTableKSeg(), ctdbGetTableKSeg(), ctdbSetIndexKSeg(), ctdbSetSegmentKSeg(), ctdbGetSegmentKSeg(), ctdbSetKSegDefaults()

ctdbGetIndexStatus

Retrieves the status of the index handle.

DECLARATION

ULONG ctdbGetIndexStatus(CTHANDLE Handle);

DESCRIPTION

Retrieves the status of the index handle. Handle is a FairCom DB API index handle.The status of the index handle is a bit map describing one or more changes that have occurred to the index object.

RETURN

ctdbGetIndexStatus() returns a bitmap of the following::

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

EXAMPLE

/* if the index has been changed, call alter table */

CTHANDLE hIndex = ctdbGetIndex(hTable, 0);

if (ctdbGetIndexStatus(hIndex) != CTDBINDEX_OLD)

if (ctdbAlterTable(hTable, CTDB_ALTER_NORMAL) != CTDBRET_OK)

printf("ctdbAlterTable failed\n");

SEE ALSO

ctdbGetFieldStatus(), ctdbGetSegmentStatus()

ctdbGetRecordKeyPos

Retrieve the given record position in the default index.

Syntax

CTDBRET ctdbDECL ctdbGetRecordKeyPos(CTHANDLE Handle, pCTOFFSET pPosition)

Parameters

• Handle [IN] - FairCom DB API C API record handle
• pPosition [OUT] - Position in the given index

Description

Retrieves the given record position in the default index. The returned position is the Ordinal key position, not a file offset.

Return

CTDBRET_OK on success.

ctdbGetSegmentKSeg

Retrieves the segment extended key definition.

DECLARATION

CTDBRET ctdbGetSegmentKSeg(CTHANDLE Handle, pctKSEGDEF pKSeg);

DESCRIPTION

ctdbGetSegmentKSeg() retrieves the current extended key segment definition.

• Handle must be a segment handle.
• pKSeg is a pointer to an extended key segment definition structure which will receive the definition.

RETURN

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

EXAMPLE

ctKSEGDEF kseg;

if ((eRet = ctdbGetSegmentKSeg(hTable, &kseg)) != CTDBRET_OK)

printf("ctdbGetSegmentKSeg failed with error %d\n", eRet);

SEE ALSO

ctdbSetTableKSeg(), ctdbGetTableKSeg(), ctdbSetIndexKSeg(), ctdbGetIndexKSeg(), ctdbSetSegmentKSeg(), ctdbSetKSegDefaults()

ctdbGetTableKSeg

Retrieves the current table-wide extended key segment definition.

DECLARATION

CTDBRET ctdbGetTableKSeg(CTHANDLE Handle, pctKSEGDEF pKSeg);

DESCRIPTION

ctdbGetTableKSeg() retrieves the current table-wide extended key segment definition. Handle must be a FairCom DB API table handle and pKSeg is a pointer to an extended key segment definition structure which will receive the definition.

Note: The kseg_type member of the extended key segment definition structure must be set on input to the type of segment to be retrieved.

RETURN

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

EXAMPLE

ctKSEGDEF kseg;

if ((eRet = ctdbGetTableKSeg(hTable, &kseg)) != CTDBRET_OK)

printf("ctdbGetTableKSeg failed with error %d\n", eRet);

SEE ALSO

ctdbSetTableKSeg(), ctdbSetIndexKSeg(), ctdbGetIndexKSeg(),
ctdbSetSegmentKSeg(), ctdbGetSegmentKSeg(), ctdbSetKSegDefaults()

ctdbMoveSegment

Moves a key segment to a location indicated by newIndex.

DECLARATION

CTDBRET ctdbDECL ctdbMoveSegment(CTHANDLE Handle, NINT newIndex);

DESCRIPTION

ctdbMoveSegment() moves a key segment to a location indicated by newIndex. Handle is a segment handle and newIndex indicates the relative position were the key segment should be moved to.

RETURN

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

EXAMPLE

/* move the last segment to first */

NINT count = ctdbGetIndexSegmentCount(hIndex);

if (count > 0)

{

CTHANDLE hSeg = ctdbGetSegment(hIndex, (count - 1));

if (ctdbMoveSegment(hSeg, 0) != CTDBRET_OK)

printf("ctdbMoveSegment failed\n");

}

SEE ALSO

ctdbAddSegment(), ctdbInsSegment(), ctdbDelSegment()

ctdbNumberOfKeyEntries

Declaration

LONG ctdbDECL ctdbNumberOfKeyEntries(CTHANDLE Handle, NINT index);

Description

ctdbNumberOfKeyEntries() retrieves the number key entries in an index file identified by its index number.

• Handle is a table handle or a handle that can be evaluated into a table handle.
• index identifies the index to obtain the number of entries. The first index number is zero.

Return Values

ctdbNumberOfKeyEntries() returns the number of key entries in the index. ctdbNumberOfKeyEntries() returns -1 and users should call the ctdbGetError() function to retrieve the error code.

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

Example

LONG Estimate(CTHANDLE Handle, NINT index)

{

LONG Retval = 0;

TEXT key1[16], key2[16];

VRLEN klen;

/* set the default index */

ctdbSetDefaultIndex(Handle, index);

/* load the first record */

ctdbFirstRecord(Handle);

/* build the target key for the first record */

klen = sizeof(key1);

ctdbBuildTargetKey(Handle, CTFIND_EQ, key1, &klen);

/* load the last record */

ctdbLastRecord(Handle);

/* build the target key for the last record */

klen = sizeof(key2);

ctdbBuildTargetKey(Handle, CTFIND_EQ, key2, &klen);

/* get the estimated span */

Retval = ctdbEstimateSpan(Handle, key1, key2);

if (Retval > 0)

Retval--;

return Retval;

}

See Also

ctdbGetError(), ctdbEstimateKeySpan()

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

ctdbSetIndexCndxExpr

Add, change, or delete the conditional expression associated with an index.

Declaration

CTDBRET ctdbSetIndexCndxExpr(CTHANDLE Handle, pTEXT conditionExpr)

Description

ctdbSetIndexCndxExpr() adds, changes, or deletes the conditional expression associated with an index. After the conditional expression is successfully associated with the index the index data is not automatically rebuilt. To retrieve the conditional expression, use ctdbGetCndxIndex() or ctdbGetCndxIndexByName().

• Handle [in] the Table Handle.
• conditionExpr [in] string containing the conditional expression.

Note: For updating the conditional expression of existing indexes, use ctdbAlterTable() with mode CTDB_ALTER_INDEX.

Returns

ctdbSetIndexCndxExpr() returns CTDBRET_OK on success, or FairCom DB API C API error code on failure.

See also

ctdbAlterTable(), ctdbGetCndxIndex(), ctdbGetCndxIndexByName()

ctdbSetIndexDistinctKeyCountFlag

Set the status of the distinct count flag for an index. To optimize some SQL queries, a better estimation of the duplicate index selectivity is required, which implies determining how many distinct keys there are in an index that allows duplicates. The CTDBINDEX_DUPCNTFLAG index status value indicates that the index has distinct key count capability.

Declaration

CTDBRET ctdbSetIndexDistinctKeyCountFlag(CTHANDLE Handle, CTBOOL Flag);

Description

ctdbSetIndexDistinctKeyCountFlag() sets the distinct count flag for an index. Use ctdbGetIndexDistinctKeyCountFlag() to retrieve the setting of this flag.

• Handle [in] the index handle.
• Flag [in] the distinct count flag.

It is possible to "promote" a duplicate index to a duplicate index with a distinct count by opening the table, calling ctdbSetIndexDistinctKeyCountFlag() for the index and finally calling ctdbAlterTable() to execute the changes.

A FairCom DB API utility, ctdbdistinct, is available to enable the distinct key count feature for existing index files. This utility is created from mtmake by default.

See also

ctdbGetIndexDistinctKeyCountFlag

ctdbSetIndexFilename

Specify the Physical index file name.

Declaration

CTDBRET ctdbSetIndexFilename(CTHANDLE Handle, pTEXT path, pTEXT filename);

Description

• Handle is an index handle returned by ctdbAddIndex() or ctdbGetIndex() calls.
• path specifies the directory location of the index file. A NULL value for path indicates that the index file is to be located in the same directory as the data file.
• filename specifies the name of the index file. If filename is NULL, this index is to be a member of the previous index file. If the filename of all index files are NULL, then all indexes will be placed in one physical index file located in the same directory as the data file, and the index file name is the same as the data file name, with the current index file extension.

An application can change the current index file extension by calling ctdbSetIndexExtension().

Return

See Appendix A "c-tree Plus Error Codes" in c-tree Plus Programmer's Reference Guide for a complete listing of valid c-tree Plus error values.

Example

CTHANDLE hTable = ctdbAllocTable(hDatabase);

CTHANDLE hIndex;

ctdbAddField(hTable, "name", CT_FSTRING, 20);

ctdbAddField(hTable, "age", CT_INT2);

hIndex = ctdbAddIndex(hTable, "index1", CTINDEX_FIXED, NO, NO);

ctdbSetIndexFilename(hIndex, NULL, "myindex1");

ctdbAddSegmentByName(hTable, 0, "name", CTSEG_SCHSEG);

ctdbAddIndex(hTable, "index2", CTINDEX_FIXED, NO, NO);

ctdbAddSegmentByName(hTable, 1, "age", CTSEG_SCHSEG);

hIndex = ctdbAddIndex(hTable, "index3", CTINDEX_FIXED, NO, NO);

ctdbSetIndexFilename(hIndex, NULL, "myindex2");

ctdbAddSegmentByName(hTable, 2, "name", CTSEG_SCHSEG);

ctdbAddSegmentByName(hTable, 2, "age", CTSEG_SCHSEG);

if (ctdbCreateTable(hTable, "mytable", CTCREATE_NORMAL) != CTDBRET_OK)

printf("ctdbCreateTable failed with code %d\n", ctdbGetError(hTable));

See also

ctdbGetIndexFilename(), ctdbSetIndexExtension(), ctdbAddIndex(), ctdbGetIndex()

ctdbSetIndexKSeg

Establishes an index-wide extended key segment definition.

DECLARATION

CTDBRET ctdbSetIndexKSeg(CTHANDLE Handle, pctKSEGDEF pKSeg);

DESCRIPTION

ctdbSetIndexKSeg() establishes an index-wide extended key segment definition. Handle must be an index handle and pKSeg is a pointer to an extended key segment definition structure with the extended key definition.

RETURN

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

EXAMPLE

ctKSEGDEF kseg;

kseg.kseg_ssiz = ctKSEG_SSIZ_COMPUTED;

kseg.kseg_type = ctKSEG_TYPE_UNICODE;

kseg.kseg_styp = ctKSEG_STYP_UTF16;

kseg.kseg_comp = ctKSEG_COMPU_S_DEFAULT | ctKSEG_COMPU_N_NONE;

kseg.kseg_desc = "en_US"

if ((eRet = ctdbSetIndexKSeg(hIndex, &kseg)) != CTDBRET_OK)

printf("ctdbSetIndexKSeg failed with error %d\n", eRet);

SEE ALSO

ctdbSetTableKSeg(), ctdbGetTableKSeg(), ctdbGetIndexKSeg(),
ctdbSetSegmentKSeg(), ctdbGetSegmentKSeg(), ctdbSetKSegDefaults()

ctdbSetKSegDefaults

Sets the system-wide default values for the extended key segment definition.

DECLARATION

CTDBRET ctdbSetKSegDefaults(pctKSEGDEF pKSeg);

DESCRIPTION

Sets the system-wide default values for the extended key segment definition. pKSeg is a pointer to an extended key segment definition structure which will receive the definition. The default values are:

kseg_ssiz = ctKSEG_SSIZ_COMPUTED;

kseg_type = ctKSEG_TYPE_UNICODE;

kseg_styp = ctKSEG_STYP_UTF16;

kseg_comp = ctKSEG_COMPU_S_DEFAULT | ctKSEG_COMPU_N_NONE;

kseg_desc = "en_US"

RETURN

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

EXAMPLE

ctKSEGDEF kseg;

if ((eRet = ctdbSetKSegDefaults(&kseg)) != CTDBRET_OK)

printf("ctdbSetKSegDefaults failed with error %d\n", eRet);

SEE ALSO

ctdbSetTableKSeg(), ctdbGetTableKSeg(), ctdbSetIndexKSeg(), ctdbGetIndexKSeg(),
ctdbSetSegmentKSeg(), ctdbGetSegmentKSeg()

ctdbSetSegmentKSeg

Establishes a segment extended key definition.

DECLARATION

CTDBRET ctdbSetSegmentKSeg(CTHANDLE Handle, pctKSEGDEF pKSeg);

DESCRIPTION

ctdbSetSegmentKSeg() establishes a segment extended key segment definition. Handle must be a segment handle and pKSeg is a pointer to an extended key segment definition structure with the extended key definition.

RETURN

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

EXAMPLE

ctKSEGDEF kseg;

kseg.kseg_ssiz = ctKSEG_SSIZ_COMPUTED;

kseg.kseg_type = ctKSEG_TYPE_UNICODE;

kseg.kseg_styp = ctKSEG_STYP_UTF16;

kseg.kseg_comp = ctKSEG_COMPU_S_DEFAULT | ctKSEG_COMPU_N_NONE;

kseg.kseg_desc = "en_US"

if ((eRet = ctdbSetSegmentKSeg(hIndex, &kseg)) != CTDBRET_OK)

printf("ctdbSetSegmentKSeg failed with error %d\n", eRet);

SEE ALSO

ctdbSetTableKSeg(), ctdbGetTableKSeg(), ctdbSetIndexKSeg(), ctdbGetIndexKSeg(),
ctdbGetSegmentKSeg(), ctdbSetKSegDefaults()

ctdbSetSessionExclusive

Sets or clears the session exclusive flag.

DECLARATION

CTDBRET ctdbSetSessionExclusive(CTHANDLE Handle, CTBOOL flag);

DESCRIPTION

ctdbSetSessionExclusive() sets or clears the session exclusive flag. If a session exclusive flag is set, only one CTSESSION_CTDB or CTSESSION_SQL session will be allowed. Set the session exclusive flag after allocating the session handle, but before performing a logon. Setting the session exclusive flag after a session logon is performed will not have any effect during the current session. Handle is a session handle. If flag is YES, this will set the exclusive flag, while NO will clear the exclusive flag.

RETURN

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

EXAMPLE

/* perform 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");

}

ctdbFreeSession(hSession);

SEE ALSO

ctdbIsSessionExclusive(), ctdbSetDatabaseExclusive(), ctdbIsDatabaseExclusives()

ctdbSetTableKSeg

Establishes a table wide extended key segment definition.

DECLARATION

CTDBRET ctdbSetTableKSeg (CTHANDLE Handle, pctKSEGDEF pKSeg);

DESCRIPTION

ctdbSetTableKSeg() establishes a table wide extended key segment definition. Handle must be a FairCom DB API table handle. pKSeg is a pointer to an extended key segment definition structure with the extended key definition.

RETURN

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

EXAMPLE

ctKSEGDEF kseg;

kseg.kseg_ssiz = ctKSEG_SSIZ_COMPUTED;

kseg.kseg_type = ctKSEG_TYPE_UNICODE;

kseg.kseg_styp = ctKSEG_STYP_UTF16;

kseg.kseg_comp = ctKSEG_COMPU_S_DEFAULT | ctKSEG_COMPU_N_NONE;

kseg.kseg_desc = "en_US"

if ((eRet = ctdbSetTableKSeg(hTable, &kseg)) != CTDBRET_OK)

printf("ctdbSetTableKSeg failed with error %d\n", eRet);

See Also

ctdbGetTableKSeg(), ctdbSetIndexKSeg(), ctdbGetIndexKSeg(),
ctdbSetSegmentKSeg(), ctdbGetSegmentKSeg(), ctdbSetKSegDefaults()

ctdbSetTablePartitionNumberBits

Set the number of bits used to store the raw partition number.

Declaration

CTDBRET ctdbDECL ctdbSetTablePartitionNumberBits(CTHANDLE Handle, UCOUNT bitno)

Description

Sets the number of bits used to store the raw partition number.

By default, 16 bits of the 64-bit record offset are used to reference the raw partition number, allowing each partitioned file to support up to 65535 member files over its lifetime. This function allows adjusting this when it is called before creating the file.

A value of 0 defaults to 16 bits, values less than 4 bits default to 4 bits (maximum 15 member files), and 32 bits is the maximum value.

Parameters

• Handle [IN] - Table handle
• bitno [IN] - Number of bits to be used for raw partition number

Return Values

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

ctdbSetTablePartitionRule

Set partition rule using an expression.

Declaration

CTDBRET ctdbDECL ctdbSetTablePartitionRule(CTHANDLE Handle, pTEXT expr)

Description

Sets a partition rule using an expression.

Parameters:

• Handle [IN] - Table handle
• expr [IN] - expression that evaluates into an integer that will be used as partition number

Return Values

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

ctdbUpdateCndxIndex

Add, change or delete the conditional expression associated with an index, given by number.

Declaration

CTDBRET ctdbUpdateCndxIndex(CTHANDLE Handle, NINT indexnbr,

pTEXT cndexpr)

Description

ctdbUpdateCndxIndex() adds, changes or deletes the conditional expression associated with an index. After the conditional expression is successfully associated with the index, the index data is automatically rebuilt. To retrieve the conditional expression, use ctdbGetCndxIndex() or ctdbGetCndxIndexByName().

• Handle [in] the Table Handle.
• indexnbr [in] the index number.
• cndexpr [in] string containing the conditional expression.

Returns

ctdbUpdateCndxIndex() returns CTDBRET_OK on success, or FairCom DB API C API error code on failure.

See also

ctdbUpdateCndxIndexByName(), ctdbGetCndxIndex(), ctdbGetCndxIndexByName(), ctdbGetCndxIndexLength(), ctdbGetCndxIndexLengthByName()

ctdbUpdateCndxIndexByName

Add, change or delete the conditional expression associated with an index, given by name.

Declaration

CTDBRET ctdbUpdateCndxIndexByName(CTHANDLE Handle, pTEXT indexname,

pTEXT cndexpr)

Description

ctdbUpdateCndxIndexByName() adds, changes or deletes the conditional expression associated with an index, given by name. After the conditional expression is successfully associated with the index, the index data is automatically rebuilt. To retrieve the conditional expression, use ctdbGetCndxIndex() or ctdbGetCndxIndexByName().

• Handle [in] the Table Handle.
• indexname [in] the index name.
• cndexpr [in] string containing the conditional expression.

Returns

ctdbUpdateCndxIndexByName() returns CTDBRET_OK on success, or FairCom DB API C API error code on failure.

See also

ctdbUpdateCndxIndex(), ctdbGetCndxIndex(), ctdbGetCndxIndexByName(), ctdbGetCndxIndexLength(), ctdbGetCndxIndexLengthByName()