Index Methods

Chapter Updated 2/12/99

This chapter lists the xbNdx and xbNtx index methods and provides examples of how to use them.

There are many methods in the xbNdx and xbNtx classes which are used for maintaining and updating NDX and NTX files. Fortunately for the application programmer, most of the complexities of dealing with the NDX and NTX indices are automatically cared for by the Xbase library.

xbNdx and xbNtx methods which are used by application programs are documented here. With some exceptions (OpenIndex,CloseIndex and KeyExists) using the index routines automatically positions and returns the associated record in the DBF database.


Xbase xbNdx Index Method List
MethodDescription
CheckIndxIntegrityChecks an index file for integrity
CloseIndexOptional, closes an index. Closing the DBF file will close any open indexes.
CreateIndexCreate an index
FindKeyFind a key in an index file
GetFirstKeyGet the first key in an index
GetLastKeyGet the last key in an index
GetNextKeyGet the next key in an index
GetPrevKeyGet the previous key in an index
KeyExistsDetermine if a key exists w/o positioning DBF file
OpenIndexOpen an index
ReIndexRebuilds an index
in

Method Definitions

Method xbShort xbNdx::CheckIndexIntegrity( xbShort option )

Method xbShort xbNtx::CheckIndexIntegrity( xbShort option )


This method checks an open index for accuracy or file corruption. If the option is non zero, the method will display informational messages.


Method Return Codes
Return CodeDescription
XB_NO_ERRORIf there is no error
XB_LOCK_FAILEDRead lock not successfull
XB_NOT_OPENFile not open
XB_INVALID_RECORDInvalid record number
XB_SEEK_ERRORSeek routine error
XB_WRITE_ERRORWrite routine error

Example Program:

See program checkndx.cpp for an example of how to use this method.

Method xbShort xbNdx::CloseIndex( VOID )

Method xbShort xbNtx::CloseIndex( VOID )


This method closes an open NDX index. NDX indexes are closed automatically by the DBF::CloseDatabase routine, so this is an optional method. Closed indices are not updated by the Xbase routines.


Method Return Codes
Return CodeDescription
XB_NO_ERRORIf there is no error

Example Program:

See program sample1.cpp for an example of how to use this method.

Method xbShort xbNdx::CreateIndex( char * IndexName, char * KeyExpression, xbShort Unique, xbShort OverLay )

Method xbShort xbNtx::CreateIndex( char * IndexName, char * KeyExpression, xbShort Unique, xbShort OverLay )


This method creates an index. Indices are created as either a character based index or a numeric based index, depending on the KeyExpression value.

  • Indexname - is the name of the physical index file name.
  • KeyExpression - is the key of the index.
  • Unique - XB_UNIQUE or XB_NOT_UNIQUE
  • Overlay - XB_OVERLAY or XB_DONTOVERLAY


    Method Return Codes
    Return CodeDescription
    XB_NO_ERRORIf there is no error
    XB_NO_MEMORYMemory error
    XB_OPEN_ERRORCould not open index file
    XB_INVALID_KEY_EXPRESSIONBad index key expression
    XB_NOT_OPENThe database was not open
    XB_SEEK_ERRORSeek error encountered
    XB_READ_ERRORRead error encountered


    Index expressions can be a single field or multiple fields. Assuming a database has fields LASTNAME and FIRSTNAME, valid index expressions could be:


    Sample Index Expressions
    ExpressionDescription
    "LASTNAME"Index on LASTNAME only.
    "LASTNAME+FIRSTNAME"Index on LASTNAME and FIRSTNAME
    "LASTNAME-FIRSTNAME"Index on LASTNAME and FIRSTNAME, all spaces between the two fields removed.
    "LASTNAME-','FIRSTNAME"Index on LASTNAME and FIRSTNAME, insert a comma between the two values, remove spaces between the two fields.


    Allowable Index Expression Operators

    OperatorKey TypeDescription
    +CharacterConcatonate string fields
    -Character Concatonate string fields, remove trailing spaces
    'literal'Characterinclude literal value
    "literal"Characterinclude literal value
    +NumericAdd two numeric fields togethor
    -NumericSubtract one numeric field from another
    *NumericMulitply two numeric fields togethor
    /NumericDivide one numeric field into another
    **NumericExponential


    Example Program:

    See program sample1.cpp for an example of how to use this method.

    Method xbShort xbNdx::FindKey( char * SearchValue )

    Method xbShort xbNdx::FindKey( xbDouble SearchValue )

    Method xbShort xbNtx::FindKey( char * SearchValue )

    Method xbShort xbNtx::FindKey( xbDouble SearchValue )


    This method searches the index for key SearchValue. The routine positions in the index, then positions to the database record for the key. If the key is not found, the key value that is the next higher value is returned.

    For character keys, the SearchValue should be a null terminated string. To find an exact match, use a key value which is as long as the key is, padded on the right with spaces.

    For numeric keys, use a xbDouble value for a search value. This is because all numeric field indices are saved as double values.


    Method Return Codes
    Return CodeDescription
    XB_FOUNDThe key was found
    XB_NOT_FOUNDThe key was not found
    XB_NO_MEMORYMemory error
    XB_OPEN_ERRORCould not open index file
    XB_SEEK_ERRORSeek error encountered
    XB_READ_ERRORRead error encountered

    Example Program:

    See program sample5.cpp for an example of how to use this method.

    Method xbShort xbNdx::GetFirstKey( VOID )

    Method xbShort xbNtx::GetFirstKey( VOID )


    This method retrieves the record for the first key in the index.


    Method Return Codes
    Return CodeDescription
    XB_NO_ERRORIf there is no error
    XB_NO_MEMORYMemory error
    XB_OPEN_ERRORCould not open index file
    XB_SEEK_ERRORSeek error encountered
    XB_READ_ERRORRead error encountered

    Example Program:

    See program sample5.cpp for an example of how to use this method.

    Method xbShort xbNdx::GetLastKey( VOID )

    Method xbShort xbNtx::GetLastKey( VOID )


    This method retrieves the record for the last key in the index.


    Method Return Codes
    Return CodeDescription
    XB_NO_ERRORIf there is no error
    XB_NO_MEMORYMemory error
    XB_OPEN_ERRORCould not open index file
    XB_SEEK_ERRORSeek error encountered
    XB_READ_ERRORRead error encountered

    Example Program:

    See program sample5.cpp for an example of how to use this method.

    Method xbShort xbNdx::GetNextKey( VOID )


    This method retrieves the record for the next key in the index. If the index is not positioned, a call to GetFirstKey is autoamtically executed.


    Method Return Codes
    Return CodeDescription
    XB_NO_ERRORIf there is no error
    XB_NO_MEMORYMemory error
    XB_OPEN_ERRORCould not open index file
    XB_SEEK_ERRORSeek error encountered
    XB_READ_ERRORRead error encountered

    Example Program:

    See program sample5.cpp for an example of how to use this method.

    Method xbShort xbNdx::GetPrevKey( VOID )

    Method xbShort xbNtx::GetPrevKey( VOID )


    This method retrieves the record for the previous key in the index. If the index is not positioned, a call to GetLastKey is autoamtically executed.


    Method Return Codes
    Return CodeDescription
    XB_NO_ERRORIf there is no error
    XB_NO_MEMORYMemory error
    XB_OPEN_ERRORCould not open index file
    XB_SEEK_ERRORSeek error encountered
    XB_READ_ERRORRead error encountered

    Example Program:

    See program sample5.cpp for an example of how to use this method.

    Method xbShort xbNdx::KeyExists( char * SearchValue )

    Method xbShort xbNdx::KeyExists( xbDouble SearchValue )

    Method xbShort xbNtx::KeyExists( char * SearchValue )

    Method xbShort xbNtx::KeyExists( xbDouble SearchValue )


    This method searches the index for the key SearchValue. The routine does not position the database record for the key. See the reference on FindKey for more information regarding KeyValue.


    Method Return Codes
    Return CodeDescription
    XB_FOUNDThe key was found
    XB_NOT_FOUNDThe key was not found
    XB_NO_MEMORYMemory error
    XB_OPEN_ERRORCould not open index file
    XB_SEEK_ERRORSeek error encountered
    XB_READ_ERRORRead error encountered

    Example Program:

    if( xbNdx::KeyExists( "MyKeyValue" )) cout << "\nKey was found"; else cout << "\nKey was not found";

    Method xbShort xbNdx::OpenIndex( char * IndexName )

    Method xbShort xbNtx::OpenIndex( char * IndexName )


    This method opens index IndexName for a given DBF database. An index must be opened before it will be automatically updated by the database update routines.


    Method Return Codes
    Return CodeDescription
    XB_NO_ERRORIf there is no error
    XB_NO_MEMORYMemory error
    XB_OPEN_ERRORCould not open index file
    XB_INVALID_KEY_EXPRESSIONBad key in index
    XB_NOT_OPENThe database was not open
    XB_SEEK_ERRORSeek error encountered
    XB_READ_ERRORRead error encountered

    Example Program:

    See program sample1.cpp for an example of how to use this method.

    Method xbShort xbNdx::ReIndex( VOID )

    Method xbShort xbNtx::ReIndex( VOID )


    This method rebuilds an index. It is used for optimizing an index, or recreating a damaged index. If the index is severly damaged (ie; the first 512 bytes are foobar) then the index must be recreated with the CreateIndex method before using the ReIndex method.


    Method Return Codes
    Return CodeDescription
    XB_NO_ERRORIf there is no error
    XB_OPEN_ERRORCould not open index file
    XB_WRITE_ERRORError writing data
    XB_CLOSE_ERRORError closing work file

    Example Program:

    See program reindex.cpp for an example of how to use this method.