Xbase DBMS Chapter 12

#

Database Methods

Chapter Updated 1/30/99

This chapter lists the database methods and provides links to examples of how to use them.

### Xbase Database Method List

Method | Description
xbShort rc AppendRecord() | Append a new record to the end of an open database
void AutoLockOn() | Turns on automatic record locking (see locking chapter)
void AutoLockOff() | Turns off automatic record locking (see locking chapter)
void BlankRecord() | Fill the current record buffer with blanks
xbLong csum CalcCheckSum() | Calculate checksum on a data record
xbShort rc CloseDatabase() | Close an open database
xbShort rc CopyDbfStructure( char * NewFileName, xbShort OverlaySwitch ) | Copies the structure of a xbDbf file to a new file
xbShort rc CreateDatabase( char * FileName, XbSchema *s, xbShort OverlaySwitch ) | Close an open database
xbULong CurrentRecNo() | Returns the current record number
xbShort rc DeleteAllRecords() | Mark all records for deletion
xbShort rc DeleteRecord() | Mark a record for deletion
xbShort rc DumpHeader(xbShort option) | Display information about a .DBF file header
xbShort rc DumpRecord( xbULong RecNo) | Dump a record for a database
xbLong cnt FieldCount() | Returns number of fields in database
xbLong recno GetCurRecNo() | Returns current record number
xbShort rc GetFirstRecord() | Get the first record in the database
xbShort rc GetLastRecord() | Get the last record in the database
xbShort rc GetNextRecord() | Get the next record in the database
xbShort rc GetPrevRecord() | Get the previous record in the database
xbShort rc GetRecord(xbLong RecNo) | Get a record by record number from an open database
char * buf GetRecordBuf() | Returns a pointer to the record buffer
xbLong RecCnt NoOfRecords() | Returns the number of records in an open database
xbShort rc OpenDatabase(char * FileName) | Open an existing database
xbShort rc PackDatabase( xbShort WaitOption) | Compress file and remove deleted records
xbShort rc PutRecord(xbULong RecNo) | Put a record in an open database
xbShort rc RebuildAllIndices() | Rebuilds all open indices
xbShort dflag RecordDeleted() | Determine if a record has been deleted
xbShort version SetVersion(xbShort Ver) | Set version to xbase III+ or IV style xbDbf files
xbShort rc UndeleteAllRecords() | Unmark all deleted records
xbShort rc UndeleteRecord() | Unmark a deleted record
xbShort rc Zap(xbShort WaitOption) | Deletes all records from a database

## Method Definitions

### Method xbShort xbDbf::AppendRecord( void )

This method appends the contents of the database record buffer to the end of the .DBF file and updates the date and number of records in the header of the datafile.
This method also updates any open indexes associated with the database.

### Method Return Codes

Return Code | Description
XB_LOCK_FAILED | Write lock not successful
XB_NO_ERROR | If there is no error
XB_WRITE_ERROR | Unsuccessful write operation

#### Example Program:

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

### Method xbShort xbDbf::BlankRecord( void )

This method overlays the database record buffer with space (0x20) CHARacters. This method is useful for initializing the record buffer.

#### Example Program:

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

### Method xbLong xbDbf::CalcCheckSum( void )

This method calculates the checksum of a database record.

### Method xbShort xbDbf::CloseDatabase( void )

This method closes an Xbase (.DBF) file which was previously opened by CreateDatabase or OpenDatabase and frees any previously allocated memory which is no LONGer needed.
This method automatically closes any open indexes associated with the database before closing the database.

### Method Return Codes

Return Code | Description
XB_NO_ERROR | If there is no error
XB_NOT_OPEN | If there is no error

#### Example Program:

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

### Method xbShort xbDbf::CopyDbfStructure( char *NewFileName, xbShort OverLay )

This method copies the structure of an Xbase (.DBF) file to file NewFileName. If there are memo fields, they are included.
The OverLay switch is used to determine what to do if a xbDbf file with the same name already exists. If OverLay is set to XB_OVERLAY and the file exists, the file is overwritten, otherwise an error is returned.
Overlay Switch is:
- XB_OVERLAY = Overlay file if it exists
- XB_DONTOVERLAY = Return with error if file exists

  ### Method Return Codes

  Return Code | Description
  XB_NO_ERROR | If there is no error
  XB_FILE_EXISTS | If a file exists and OverLay switch = FALSE
  XB_OPEN_ERROR | Couldn't open the file
  XB_NO_MEMORY | Memory allocation error
  XB_WRITE_ERROR | Couldn't write to disk
  XB_SEEK_ERROR | Seek routine error

  #### Example Program:

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

  ### Method: xbShort xbDbf::CreateDatabase( char *FileName, xbSchema *s, xbShort OverLay )

  This method creates an Xbase (.DBF) file with the name of FileName and builds the header record with the format as defined in the xbSchema parameter. The OverLay switch is used to determine what to do if a xbDbf file with the same name already exists. If OverLay is set to XB_OVERLAY and the file exists, the file is overwritten, otherwise an error is returned.
  Overlay Switch is:
- XB_OVERLAY = Overlay file if it exists
- XB_DONTOVERLAY = Return with error if file exists
  xbSchema has the following format:

      xbSchema MyRecordSchema[] =
      {
         { FieldName,  Type, FieldLength, NoOfDecimals },
         { FieldName2, Type, FieldLength, NoOfDecimals },
            ...
         { "",0,0,0 }
      };

  Where:
- FieldName is the name of the data field.
- Type

  #### Version 1.7.4 and greater:

  XB_CHAR_FLD or C
  XB_DATE_FLD or D
  XB_LOGICAL_FLD or L
  XB_MEMO_FLD or M
  XB_FLOAT_FLD or F
  XB_NUMERIC_FLD or N
- FieldLength is the length of the field.
- NoOfDecimals is the number of decimals for NUMERIC fields.
  The record buffer is automatically set to spaces when this method is called.

  ### Method Return Codes

  Return Code | Description
  XB_NO_ERROR | If there is no error
  XB_FILE_EXISTS | If a file exists and OverLay switch = FALSE
  XB_OPEN_ERROR | Couldn't open the file
  XB_NO_MEMORY | Memory allocation error
  XB_WRITE_ERROR | Couldn't write to disk

  #### Example Program:

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

  ### Method xbULong xbDbf::CurrentRecNo( void )

  This method returns the current record number.

  #### Example Program:

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

  ### Method xbShort xbDbf::DeleteAllRecords( void )

  This method marks all unmarked records in the database for deletion.

  ### Method Return Codes

  Return Code | Description
  XB_NO_ERROR | No error encountered
  XB_INVALID_RECORD | Could not mark record
  XB_NOT_OPEN | If the file is not open
  XB_SEEK_ERROR | Seek routine error
  XB_WRITE_ERROR | Write routine error

  #### Example Program:

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

  ### Method xbShort xbDbf::DeleteRecord( void )

  This method marks the current record for deletion in the database.

  ### Method Return Codes

  Return Code | Description
  XB_NO_ERROR | No error encountered
  XB_INVALID_RECORD | Could not mark record

  #### Example Program:

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

  ### Method xbShort xbDbf::DumpHeader( xbShort Option )

  This method displays information about a .DBF file header to stdout. This method is only available if the DEBUG option is turned on in the options.h file

  ### Method Options

  Option | Action
  1 | Print Header Only
  2 | Field Data Only
  3 | Header and Field Data

  ### Method Return Codes

  Return Code | Description
  XB_INVALID_OPTION | Option must be 1,2 or 3
  XB_NOT_OPEN | File is not open
  XB_NO_ERROR | No error encountered

  #### Example Program:

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

  ### Method xbShort xbDbf::DumpRecord( xbULong RecNo )

  This method dumps record RecNo for the database to stdout.

  ### Method Return Codes

  Return Code | Description
  XB_NO_ERROR | No error encountered
  XB_INVALID_RECORD | Invalid record for RecNo parameter

  #### Example Program:

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

  ### Method xbLong xbDbf::FieldCount( void )

  This method returns the number of fields defined in the database.

  ### Method xbLong xbDbf::GetCurRecNo( void )

  This method returns the current record number of the record in the record buffer.

  #### Example Program:

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

  ### Method xbShort xbDbf::GetFirstRecord( void )

  This method loads the first record of the file into the record buffer.

  ### Method Return Codes

  Return Code | Description
  XB_NO_ERROR | If there is no error
  XB_INVALID_RECORD | Invalid record number
  XB_LOCK_FAILED | Unsuccessful lock operation
  XB_NOT_OPEN | If the file is not open
  XB_SEEK_ERROR | Seek routine error
  XB_WRITE_ERROR | Write routine error

  #### Example Program:

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

  ### Method xbShort xbDbf::GetLastRecord( void )

  This method loads the last record of the file into the record buffer.

  ### Method Return Codes

  Return Code | Description
  XB_LOCK_FAILED | Read lock not successful
  XB_NO_ERROR | If there is no error
  XB_EOF | At end of file
  XB_NOT_OPEN | If the file is not open
  XB_INVALID_RECORD | Invalid record number
  XB_SEEK_ERROR | Seek routine error
  XB_WRITE_ERROR | Write routine error

  #### Example Program:

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

  ### Method xbShort xbDbf::GetNextRecord( void )

  This method loads the next record of the file into the record buffer.

  ### Method Return Codes

  Return Code | Description
  XB_LOCK_FAILED | Read lock not successful
  XB_NO_ERROR | If there is no error
  XB_EOF | At end of file
  XB_NOT_OPEN | If the file is not open
  XB_INVALID_RECORD | Invalid record number
  XB_SEEK_ERROR | Seek routine error
  XB_WRITE_ERROR | Write routine error

  #### Example Program:

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

  ### Method xbShort xbDbf::GetPrevRecord( void )

  This method loads the previous record of the file into the record buffer.

  ### Method Return Codes

  Return Code | Description
  XB_LOCK_FAILED | Read lock not successful
  XB_NO_ERROR | If there is no error
  XB_BOF | At beginning of file
  XB_NOT_OPEN | If the file is not open
  XB_INVALID_RECORD | Invalid record number
  XB_SEEK_ERROR | Seek routine error
  XB_WRITE_ERROR | Write routine error

  #### Example Program:

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

  ### Method xbShort xbDbf::GetRecord( xbLong RecNo )

  This method retrieves record RecNo from the database into the record buffer.
  This method will call the PutRec method and flush all updates to disk if necessary before moving to the specified record. If PutRecord is not successful, this method will return the return code from PutRecord.

  ### Method Return Codes

  Return Code | Description
  XB_LOCK_FAILED | Read lock not successful
  XB_NO_ERROR | If there is no error
  XB_NOT_OPEN | If the file is not open
  XB_INVALID_RECORD | Invalid record number
  XB_SEEK_ERROR | Seek routine error
  XB_WRITE_ERROR | Write routine error

  #### Example Program:

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

  ### Method char * xbDbf::GetRecordBuf( void )

  This method returns a pointer to the record buffer.

  #### Example Program:

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

  ### Method xbLong xbDbf::NoOfRecords( void )

  This method returns the number of records in the file.

  #### Example Program:

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

  ### Method xbShort xbDbf::OpenDatabase( char * FileName )

  This method opens an Xbase (.DBF) file with the name of FileName. FileName must a valid filename which can include drives identifier, directory, filename and extension.
  The OpenDatabase method does not position to any any particular data record. After opening a database, use GetRecord, GetFirstRecord or GetLastRecord to position to a particular data record and load a data record into the record buffer.
  The record buffer is automatically set to spaces when this method is called.

  ### Method Return Codes

  Return Code | Description
  XB_NO_ERROR | If there is no error
  XB_OPEN_ERROR | Couldn't open the file
  XB_NO_MEMORY | Memory allocation error
  XB_NOT_XBASE | Not an xbXBase type file

  #### Example Program:

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

  ### Method xbShort xbDbf::PackDatabase( xbShort WaitOption )

  This method removes all records marked for deletion from an Xbase (.DBF) file and reindexes any open index files. This method also reorganizes any memo fields stored in a .DBT memo file.
  WaitOption is one of:
- F_SETLK - returns if the xbDbf file can not be exclusively locked
- F_SETLKW - will wait to execute until it can exclusively lock the file

  ### Method Return Codes

  Return Code | Description
  XB_NO_ERROR | If there is no error
  XB_CLOSE_ERROR | If intermediate work file can not be closed
  XB_OPEN_ERROR | Could not open file
  XB_NO_MEMORY | Memory allocation error
  XB_WRITE_ERROR | Error writing to file
  XB_SEEK_ERROR | Seek error encountered
  XB_LOCK_FAILED | Can not lock file or index

  #### Example Program:

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

  ### Method xbShort xbDbf::PutRecord( xbLong RecNo )

  This method copies the record buffer into record RecNo in the database. This method can be used for updating records which were retrieved by the GetRecord method.
  This method updates any open index files.

  ### Method Return Codes

  Return Code | Description
  XB_LOCK_FAILED | Write lock not successful
  XB_NO_ERROR | If there is no error
  XB_NOT_OPEN | Database is not open
  XB_INVALID_RECORD | Invalid record number
  XB_SEEK_ERROR | Seek operation failed
  XB_WRITE_ERROR | Write operation failed

  #### Example Program:

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

  ### Method xbShort xbDbf::RebuildAllIndicis( void )

  This method rebuilds all opened indicis for the database file.

  ### Method Return Codes

  Return Code | Description
  XB_NO_ERROR | If there is no error
  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.

  ### Method xbShort xbDbf::RecordDeleted( void )

  This method returns TRUE (or 1) if a record is marked for deletion and returns FALSE (or 0) if the record is not marked for deletion.

  ### Method Return Codes

  Return Code | Description
  TRUE (1) | Record is marked for deletion
  FALSE (0) | Record is not marked for deletion

  #### Example Program:

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

  ### Method xbShort xbDbf::SetVersion( xbShort Vswitch )

  This method sets the version of xbDbf and DBT database files and memo files to be created using the CreateDatabase method. The default setting is 3 - dBASE III+ version files. It can be set to 4 - for dBASE IV style files.
  Vswitch is one of:
  0 - return current setting
  3 - Set to create version III files (default)
  4 - Set to create version IV files

  ### Method Return Codes

  Return Code | Description
  XB_NO_ERROR | Setting updated
  3 or 4 | If Vswitch = 0, it returns current version setting
  XB_INVALID_OPTION | Vswictch not one of 0,3 or 4

  #### Example Program:

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

  ### Method xbShort xbDbf::UndeleteAllRecords( void )

  This method unmarks all marked for deletion records in the database.

  ### Method Return Codes

  Return Code | Description
  XB_NO_ERROR | No error encountered
  XB_INVALID_RECORD | Could not mark record
  XB_NOT_OPEN | If the file is not open
  XB_SEEK_ERROR | Seek routine error
  XB_WRITE_ERROR | Write routine error

  #### Example Program:

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

  ### Method xbShort xbDbf::UndeleteRecord( void )

  This method removes the mark for deletion on the current record in the database.

  ### Method Return Codes

  Return Code | Description
  XB_NO_ERROR | No error encountered
  XB_INVALID_RECORD | Could not unmark record

  #### Example Program:

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

  ### Method xbShort xbDbf::Zap( xbShort WaitOption )

  This method removes all records from a database and any open indices.
  WaitOption is one of:
- F_SETLK - returns if the xbDbf file can not be exclusively locked
- F_SETLKW - will wait to execute until it can exclusively lock the file

  ### Method Return Codes

  Return Code | Description
  XB_NO_ERROR | No error encountered
  XB_LOCK_FAILED | Could not lock file
  XB_WRITE_ERROR | Could not write to file
  XB_OPEN_ERROR | Could not open temp database

  #### Example Program:

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