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

Method | Description
CheckIndxIntegrity | Checks an index file for integrity
CloseIndex | Optional, closes an index. Closing the DBF file will close any open indexes.
CreateIndex | Create an index
FindKey | Find a key in an index file
GetFirstKey | Get the first key in an index
GetLastKey | Get the last key in an index
GetNextKey | Get the next key in an index
GetPrevKey | Get the previous key in an index
KeyExists | Determine if a key exists w/o positioning DBF file
OpenIndex | Open an index
ReIndex | Rebuilds 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 Code | Description
XB_NO_ERROR | If there is no error
XB_LOCK_FAILED | Read lock not successfull
XB_NOT_OPEN | File not open
XB_INVALID_RECORD | Invalid record number
XB_SEEK_ERROR | Seek routine error
XB_WRITE_ERROR | Write 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 Code | Description
XB_NO_ERROR | If 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 Code | Description
  XB_NO_ERROR | If there is no error
  XB_NO_MEMORY | Memory error
  XB_OPEN_ERROR | Could not open index file
  XB_INVALID_KEY_EXPRESSION | Bad index key expression
  XB_NOT_OPEN | The database was not open
  XB_SEEK_ERROR | Seek error encountered
  XB_READ_ERROR | Read 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

  Expression | Description
  "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

  Operator | Key Type | Description
  + | Character | Concatonate string fields
  - | Character | Concatonate string fields, remove trailing spaces
  'literal' | Character | include literal value
  "literal" | Character | include literal value
  + | Numeric | Add two numeric fields togethor
  - | Numeric | Subtract one numeric field from another
  * | Numeric | Mulitply two numeric fields togethor
  / | Numeric | Divide one numeric field into another
  ** | Numeric | Exponential

  #### 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 Code | Description
  XB_FOUND | The key was found
  XB_NOT_FOUND | The key was not found
  XB_NO_MEMORY | Memory error
  XB_OPEN_ERROR | Could not open index file
  XB_SEEK_ERROR | Seek error encountered
  XB_READ_ERROR | Read 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 Code | Description
  XB_NO_ERROR | If there is no error
  XB_NO_MEMORY | Memory error
  XB_OPEN_ERROR | Could not open index file
  XB_SEEK_ERROR | Seek error encountered
  XB_READ_ERROR | Read 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 Code | Description
  XB_NO_ERROR | If there is no error
  XB_NO_MEMORY | Memory error
  XB_OPEN_ERROR | Could not open index file
  XB_SEEK_ERROR | Seek error encountered
  XB_READ_ERROR | Read 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 Code | Description
  XB_NO_ERROR | If there is no error
  XB_NO_MEMORY | Memory error
  XB_OPEN_ERROR | Could not open index file
  XB_SEEK_ERROR | Seek error encountered
  XB_READ_ERROR | Read 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 Code | Description
  XB_NO_ERROR | If there is no error
  XB_NO_MEMORY | Memory error
  XB_OPEN_ERROR | Could not open index file
  XB_SEEK_ERROR | Seek error encountered
  XB_READ_ERROR | Read 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 Code | Description
  XB_FOUND | The key was found
  XB_NOT_FOUND | The key was not found
  XB_NO_MEMORY | Memory error
  XB_OPEN_ERROR | Could not open index file
  XB_SEEK_ERROR | Seek error encountered
  XB_READ_ERROR | Read 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 Code | Description
  XB_NO_ERROR | If there is no error
  XB_NO_MEMORY | Memory error
  XB_OPEN_ERROR | Could not open index file
  XB_INVALID_KEY_EXPRESSION | Bad key in index
  XB_NOT_OPEN | The database was not open
  XB_SEEK_ERROR | Seek error encountered
  XB_READ_ERROR | Read 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 Code | Description
  XB_NO_ERROR | If there is no error
  XB_OPEN_ERROR | Could not open index file
  XB_WRITE_ERROR | Error writing data
  XB_CLOSE_ERROR | Error closing work file

  #### Example Program:

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