From daf17154bf13139d9375f48525d19d6aaba08155 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Frings-F=C3=BCrst?= Date: Sat, 2 Aug 2014 08:43:31 +0200 Subject: Imported Upstream version 3.1.2 --- html/xbc17.htm | 352 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 352 insertions(+) create mode 100755 html/xbc17.htm (limited to 'html/xbc17.htm') diff --git a/html/xbc17.htm b/html/xbc17.htm new file mode 100755 index 0000000..c1d2c37 --- /dev/null +++ b/html/xbc17.htm @@ -0,0 +1,352 @@ + + +Xbase DBMS Chapter 17 + +

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.

    +
    +


    + + -- cgit v1.2.3