CTIndex Class

class CTIndex

Description

The CTIndex class deals with the index concept. The index is part of the table, and represents one field, or parts of one field, or parts of several fields. One single index may be composed of several segments.

See Also

CTBase, CTTable, CTRecord, CTField, CTSegment

Preconditions

Before any task is developed with a CTIndex object, a CTTable must have been initialized.

 

CTIndex Operators

  • = : Assign a CTIndex object to another

 

CTIndex::operator=

Syntax

CTIndex& operator=(const CTIndex& pField)

Parameters

  • pField [in] The index object.

Description

Assigns one CTIndex object to another

Return

Returns a CTIndex object

 

CTIndex Methods

Constructor / Destructor

  • CTIndex(): Creates a CTIndex object
  • ~CTIndex(): Destroys a CTIndex Object and resets all the dependent objects

Key Handling

  • GetKeyLength(): Retrieves the key length
  • GetKeyType(): Retrieves the key type
  • GetEmptyChar(): Retrieves the index empty char
  • GetDuplicateFlag(): Retrieves the allow duplicated flag for this index
  • GetNullFlag(): Retrieve the null flag
  • GetTemporaryFlag(): Retrieves the temporary flag
  • SetEmptyChar(): Sets the empty char value.
  • SetDuplicateFlag(): Sets the allow duplicate flag
  • SetNullFlag(): Sets the null flag.
  • SetKeyType(): Set the index key type.
  • SetTemporaryFlag(): Sets the temporary flag.

Segment Handling

  • GetSegmentCount(): Retrieves the index segments count
  • AddSegment(): Adds a new segment to the index
  • InsertSegment(): Inserts a segment to the index
  • DelSegment(): Deletes a segment from the index
  • GetSegment(): Retrieves an index segment

Index Handling

  • GetIdxno(): Retrieves a table index number from an index object.
  • GetNumber(): Retrieves the index position in table indexes list.
  • GetName(): Retrieves the index name.
  • GetUID(): Retrieves the index uid.
  • GetIndexFileName(): Retrieves the index file name for the associated index.
  • SetIndexFileName(): Sets the index file name for the associated index.

 

CTIndex::CTIndex

Syntax

CTIndex ( )
CTIndex(const CTIndex& pIndex)

Parameters

  • pIndex [in] The index object.

Description

This is the constructor for the CTIndex object.

See also

~CTIndex()

 

CTIndex::~CTIndex

Syntax

~CTIndex

Parameters

This destructor has no parameters.

Description

This is the destructor for the CTIndex object.

See also

CTIndex()

 

CTIndex::AddSegment

Syntax

CTSegment AddSegment(const CTField& pField, CTSEG_MODE SegMode)
CTSegment AddSegment(NINT offset, NINT length, CTSEG_MODE SegMode)

Parameters

  • pField [in] The segment object to be inserted.
  • SegMode [in] The field segment mode. The valid values for the segment mode are shown in "FairCom DB API definitions".
  • offset [in] The segment offset to be inserted.
  • length [in] The segment length to be inserted.

Description

Adds a new segment to the index at the end of the index.

Return

Returns a segment object

See also

InsertSegment(), DelSegment(), GetSegmentCount()

 

CTIndex::DelSegment

Syntax

void DelSegment(NINT SegmentNumber)

Parameters

  • SegmentNumber [in] The segment number to be deleted.

Description

Deletes a segment from the index.

Return

None.

See also

AddSegment(), InsertSegment()

 

CTIndex::GetDuplicateFlag

Syntax

CTBOOL GetDuplicateFlag( ) const

Parameters

This method has no parameters.

Description

Retrieves the allow duplicated flag for this index

Return

GetDuplicateFlag() returns YES if the index allows duplicated keys, and NO otherwise.

See also

SetDuplicateFlag()

 

CTIndex::GetEmptyChar

Syntax

NINT GetEmptyChar( ) const

Parameters

This method has no parameters.

Description

Retrieves the index empty char

Return

GetEmptyChar() returns the index empty char. The empty char property is expressed as the decimal equivalent of the ASCII table. See SetEmptyChar() for more information.

See also

SetEmptyChar(), GetNullFlag()

 

CTIndex::GetIndexFileName

Returns the name of the index file name for the given index name or number.

Declaration

CTString CTTable::GetIndexFileName(NINT IndexNumber)
CTString CTTable::GetIndexFileName(const CTString& IndexName)

Description

Retrieves the file pathname for the given index name or number. GetIndexFileName() accepts as parameters either the index number or the index name.

Return

The index file pathname is returned. If the index has no file name, for example, the index is a member of an index file, GetIndexFileName() returns an empty string.

Example


void SetFirstIndexName(CTTable& htable, const CTString idxFileName)
{
    try
    {
        if (hTable.GetIndexFileName(0) != idxFileName)
        {
            hTable.SetIndexFileName(0, idxFileName);
            hTable.Alter(CTDB_ALTER_NORMAL);
        }
    }
    catch (CTException &err)
    {
        hSession.Abort();
        printf("Error: %d - %s\n", err.GetErrorMsg(), err.GetErrorCode());
    }
}

See also

CTTable:GetIndexFilename(), CTTable::SetIndexFilename, CTIndex::SetIndexFilename

 

CTIndex::GetIndexKSeg

Retrieves the current index wide extended key segment definition.

Declaration

void CTIndex::GetIndexKSeg(ctKSEGDEF pKSeg);

Description

CTIndex::GetIndexKSeg() retrieves the current index wide extended key segment definition. pKSeg is a pointer to an extended key segment definition structure which will receive the definition.

Return

void

Example


ctKSEGDEF kseg;
hIndex.GetIndexKSeg(&ksge);
 

See Also

CTIndex::SetIndexKSeg(), CTSegment::GetSegmentKSeg(), CTSegment::SetKSegDefaults(),
CTSegment::SetSegmentKSeg(), CTTable::GetTableKSeg(), CTTable::SetTableKSeg()

 

CTIndex::GetIdxno

Retrieves a table index file number from an index object.

Declaration

NINT CTIndex::GetIdxno()

Description

Retrieves a table index file number from an index object.

Return

GetIdxno() returns a table index file number.

Example


// retrieve the first key  of first index
TEXT keyval[256];
CTIndex hIndex = hTable.GetIndex(0);

if (FirstKey(hIndex.GetIdxno(), keyval)
    printf("FirstKey failed\n");
 

See Also

CTBase::SwitchInstance(), CTRecord::SwitchContext(), CTTable::GetDatno(), CTTable::GetIdxno()

 

CTIndex::GetKeyLength

Syntax

NINT GetKeyLength( ) const

Parameters

This method has no parameters.

Description

Retrieves the key length.

Return

GetKeyLength() returns the key length.

See also

GetKeyType()

 

CTIndex::GetKeyType

Syntax

CTDBKEY GetKeyType( ) const

Parameters

This method has no parameters.

Description

Retrieves the key type.

Return

GetKeyType() returns the key type.

See also

GetKeyLength()

 

CTIndex::GetName

Syntax

CTString GetName( )

Parameters

This method has no parameters.

Description

Retrieves the index name.

Return

GetName() returns the index name.

See also

GetNumber(), GetSegment()

 

CTIndex::GetNullFlag

Syntax

CTBOOL GetNullFlag( ) const

Parameters

This method has no parameters.

Description

Retrieves the null flag.

Return

GetNullFlag() returns YES if the null flag is set, and NO otherwise

See also

SetNullFlag(), GetEmptyChar()

 

CTIndex::GetNumber

Syntax

NINT GetNumber( )

Parameters

This method has no parameters.

Description

Retrieves the index position in table indexes list.

Return

GetNumber() returns the index position.

See also

GetName()

 

CTIndex::GetSegment

Syntax

CTSegment GetSegment(NINT SegmentNumber)

Parameters

  • SegmentNumber [in] The segment number to be retrieved.

Description

Retrieves an index segment.

Return

GetSegment() returns a CTSegment object.

See also

GetSegmentCount(), GetName(), GetNumber()

 

CTIndex::GetSegmentCount

Syntax

NINT GetSegmentCount( ) const

Parameters

This method has no parameters.

Description

Retrieves the index segments count.

Return

GetSegmentCount() returns the number of segments in the index.

See also

GetSegment()

 

CTIndex::GetStatus

Retrieves the status of the index object.

Declaration

ULONG CTIndex::GetStatus() const;

Description

CTIndex::GetStatus() retrieves the status of a index object The status of the index object is a bit map describing one or more changes that have occurred to the index object.

Return

CTIndex::GetStatus() returns a bitmap of the following:

Value Symbolic Constant Explanation
0x00 CTDBINDEX_OLD Original value (no changes)
0x01 CTDBINDEX_NEW Index added
0x02 CTDBINDEX_DEL Original Index deleted
0x04 CTDBINDEX_KEYTYPE Index key type changed
0x10 CTDBINDEX_EMPCHAR Index empty char changed
0x20 CTDBINDEX_DUPFLAG Index duplicate flag changed
0x40 CTDBINDEX_NULLFLAG Index null flag changed
0x80 CTDBINDEX_AIDXNAM Index file name changed

Example


// if the index has been changed, call alter table
CTIndex hIndex = hTable.GetIndex(0);

if (hIndex.GetStatus() != CTDBINDEX_OLD)
    if (hTable.Alter(CTDB_ALTER_NORMAL);
 

See Also

CTField::GetStatus(), CTSegment::GetStatus()

 

CTIndex::GetTemporaryFlag

Syntax

CTBOOL GetTemporaryFlag( ) const

Parameters

This method has no parameters.

Description

Retrieves the temporary flag.

Return

GetTemporaryFlag() returns YES if the index is temporary, NO otherwise

See also

SetTemporaryFlag()

 

CTIndex::GetUID

Syntax

ULONG GetUID( )

Parameters

This method has no parameters.

Description

Retrieves the index UID.

Return

GetUID() returns the index UID.

See also

GetName()

 

CTIndex::InsertSegment

Syntax

CTSegment InsertSegment(NINT BeforeSegment, const CTField& Field,
                        CTSEG_MODE SegMode)
CTSegment InsertSegment(NINT BeforeSegment, NINT offset, NINT length,
                        CTSEG_MODE SegMode)

Parameters

  • BeforeSegment [in] Insert the new segment before this segment.
  • Field [in] The segment object to be inserted.
  • SegMode [in] The field segment mode. The valid values for the segment mode are shown in "FairCom DB API definitions".
  • offset [in] The segment offset to be inserted.
  • length [in] The segment length to be inserted.

Description

Inserts a new segment to the index, in a specified position.

Return

Returns a segment object

See also

AddSegment(), DelSegment(), GetSegmentCount()

 

CTIndex::MoveSegment

Moves a key segment.

Declaration

void CTIndex::MoveSegment(NINT segmentNumber, NINT newIndex);

Description

CTIndex::MoveSegment() moves a key segment to a location indicated by newIndex.

  • segmentNumber is a relative number for a segment in an index definition.
  • newIndex indicates the relative position were the key segment should be moved to.

Return

None.

Example


// move the last segment to first
CTIndex hIndex = hTable.GetIndex(0);
NINT count = hIndex.GetSegmentCount();

if (count > 0)
    hIndex.MoveSegment((count - 1), 0);
 

See Also

CTTable::MoveSegment(), CTSegment::MoveSegment()

 

CTIndex::SetDuplicateFlag

Syntax

void SetDuplicateFlag(CTBOOL DupFlag)

Parameters

  • DupFlag [in] The allow duplicates flag

Description

Sets the allow duplicates flag. If set to YES, this index allows duplicated values.

Return

None.

See also

GetDuplicateFlag()

 

CTIndex::SetEmptyChar

Syntax

void SetEmptyChar(NINT EmptyChar)

Parameters

  • EmptyChar [in] The empty char value. The empty char property is expressed as the decimal equivalent of the ASCII table. For instance, an ASCII space is specified as 32, and a NULL byte is specified as 0.

Description

Sets the empty char property.

Return

None.

See also

GetEmptyChar(), SetNullFlag()

 

CTIndex::SetIndexFileName

Sets the index file name of the given index name or number.

Declaration

void CTTable::SetIndexFilename(const CTString& IndexName, const CTString* path, const CTString* filename)
void CTTable::SetIndexFilename(NINT IndexNumber, const CTSTring* path, const CTString* filename)

Description

Sets the index file path and name of the given index name or number. By default, when a table is created, all indexes are created as members of one index file with the table name and path, and with the extension .idx. SetIndexFileName() allows the specification of a file name and path for any one of the table’s indexes. If an index file name is not specified, the index will be created as a member of the previous index file. If no index file name and path is specified, the default is applied. If all indexes of a table specify an index file name and path, each index will be placed in a separate index file.

  • path specifies the directory were the index file is located. If path is NULL the index is located in the same directory of its table.
  • Indexname specifies the name of index file. If name is NULL the index file will use the name of its table.
  • filename is the name to assign to the index file.

Return

void

Example


void CreateTable(CTDatabase& hDatabase, const CTString& tabName, const CTString& idxName)
{
    CTTable hTable(hDatabase);

    try
    {
        hTable.AddField("name", CT_FSTRING, 20);
        hTable.AddField("surname", CT_FSTRING, 20);
        hTable.AddField("code", CT_INT4, 4);
        hTable.AddIndex("index1", CTINDEX_FIXED, NO, NO);
        hTable.SetIndexFilename("index1", NULL, IdxName);
        hTable.AddSegment("index1", "surname", CTSEG_SCHSEG);
        hTable.AddSegment("index1", "code", CTSEG_SCHSEG);
        hTable.Create(tabName, CTCREATE_NORMAL);
    }
    catch (CTException &err)
    {
        printf("Error: %d - %s\n", err.GetErrorMsg(), err.GetErrorCode());
    }
}
 

See Also

CTTable:GetIndexFilename(), CTTable::SetIndexFilename, CTIndex::SetIndexFilename

 

CTIndex::SetIndexKSeg

Establishes an index-wide extended key segment definition.

Declaration

void CTIndex::SetIndexKSeg(pctKSEGDEF pKSeg);

Description

CTIndex::SetIndexKSeg() establishes an index wide extended key segment definition. pKSeg is a pointer to an extended key segment definition structure with the extended key definition.

Return

void

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"
hIndex.SetIndexKSeg(&kseg);
 

See Also

CTIndex::GetIndexKSeg(), CTSegment::GetSegmentKSeg(), CTSegment::SetKSegDefaults(),
CTSegment::SetSegmentKSeg(), CTTable::GetTableKSeg(), CTTable::SetTableKSeg()

 

CTIndex::SetKeyType

Set the index key type.

Declaration

void CTIndex::SetKeyType(CTDBKEY keytype)

Description

CTIndex::SetKeyType() sets the key type for this index. Use CTIndex::Add() to add an index to a table. Use the CTIndex:GetKeyType() to retrieve the Index key type.

  • KeyType [in] the key type

Valid keytype values are:

  • CTINDEX_FIXED: Fixed-length key
  • CTINDEX_LEADING: Leading-character compression
  • CTINDEX_PADDING: Padding compression
  • CTINDEX_LEADPAD: Leading and padding compression

Note Key compression imposes a significant performance impact, especially when deleting records. Use this feature only when absolutely necessary to keep index space requirements to a minimum.

Return

SetKeyType() does not return a value but will throw an exception if the index key type cannot be set.

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

See Also

CTIndex::GetKeyType(), CTIndex::Add()

 

CTIndex::SetNullFlag

Syntax

void SetNullFlag(CTBOOL NullFlag)

Parameters

  • NullFlag [in] The new null flag.

Description

Sets the null flag. If set to YES, the system checks for NULL or missing key values after the index has been concatenated.

Return

None.

See also

GetNullFlag(), SetEmptyChar()

 

CTIndex::SetTemporaryFlag

Syntax

void SetTemporaryFlag(CTBOOL TempFlag)

Parameters

  • TempFlag [in] The temporary flag.

Description

Sets the temporary flag. If set to YES, this index is a temporary index.

Return

None.

See also

GetTemporaryFlag()

indexclass ctobject

Was this article helpful?

Give feedback about this article

Related Articles