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
MethodDescription
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 CodeDescription
XB_LOCK_FAILEDWrite lock not successful
XB_NO_ERRORIf there is no error
XB_WRITE_ERRORUnsuccessful 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 CodeDescription
XB_NO_ERRORIf there is no error
XB_NOT_OPENIf 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 CodeDescription
    XB_NO_ERRORIf there is no error
    XB_FILE_EXISTSIf a file exists and OverLay switch = FALSE
    XB_OPEN_ERRORCouldn't open the file
    XB_NO_MEMORYMemory allocation error
    XB_WRITE_ERRORCouldn't write to disk
    XB_SEEK_ERRORSeek 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 CodeDescription
    XB_NO_ERRORIf there is no error
    XB_FILE_EXISTSIf a file exists and OverLay switch = FALSE
    XB_OPEN_ERRORCouldn't open the file
    XB_NO_MEMORYMemory allocation error
    XB_WRITE_ERRORCouldn'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 CodeDescription
    XB_NO_ERRORNo error encountered
    XB_INVALID_RECORDCould not mark record
    XB_NOT_OPENIf the file is not open
    XB_SEEK_ERRORSeek routine error
    XB_WRITE_ERRORWrite 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 CodeDescription
    XB_NO_ERRORNo error encountered
    XB_INVALID_RECORDCould 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
    OptionAction
    1Print Header Only
    2Field Data Only
    3Header and Field Data


    Method Return Codes
    Return CodeDescription
    XB_INVALID_OPTIONOption must be 1,2 or 3
    XB_NOT_OPENFile is not open
    XB_NO_ERRORNo 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 CodeDescription
    XB_NO_ERRORNo error encountered
    XB_INVALID_RECORDInvalid 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 CodeDescription
    XB_NO_ERRORIf there is no error
    XB_INVALID_RECORDInvalid record number
    XB_LOCK_FAILEDUnsuccessful lock operation
    XB_NOT_OPENIf the file is not open
    XB_SEEK_ERRORSeek routine error
    XB_WRITE_ERRORWrite 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 CodeDescription
    XB_LOCK_FAILEDRead lock not successful
    XB_NO_ERRORIf there is no error
    XB_EOFAt end of file
    XB_NOT_OPENIf the file is not open
    XB_INVALID_RECORDInvalid record number
    XB_SEEK_ERRORSeek routine error
    XB_WRITE_ERRORWrite 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 CodeDescription
    XB_LOCK_FAILEDRead lock not successful
    XB_NO_ERRORIf there is no error
    XB_EOFAt end of file
    XB_NOT_OPENIf the file is not open
    XB_INVALID_RECORDInvalid record number
    XB_SEEK_ERRORSeek routine error
    XB_WRITE_ERRORWrite 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 CodeDescription
    XB_LOCK_FAILEDRead lock not successful
    XB_NO_ERRORIf there is no error
    XB_BOFAt beginning of file
    XB_NOT_OPENIf the file is not open
    XB_INVALID_RECORDInvalid record number
    XB_SEEK_ERRORSeek routine error
    XB_WRITE_ERRORWrite 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 CodeDescription
    XB_LOCK_FAILEDRead lock not successful
    XB_NO_ERRORIf there is no error
    XB_NOT_OPENIf the file is not open
    XB_INVALID_RECORDInvalid record number
    XB_SEEK_ERRORSeek routine error
    XB_WRITE_ERRORWrite 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 CodeDescription
    XB_NO_ERRORIf there is no error
    XB_OPEN_ERRORCouldn't open the file
    XB_NO_MEMORYMemory allocation error
    XB_NOT_XBASENot 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 CodeDescription
    XB_NO_ERRORIf there is no error
    XB_CLOSE_ERRORIf intermediate work file can not be closed
    XB_OPEN_ERRORCould not open file
    XB_NO_MEMORYMemory allocation error
    XB_WRITE_ERRORError writing to file
    XB_SEEK_ERRORSeek error encountered
    XB_LOCK_FAILEDCan 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 CodeDescription
    XB_LOCK_FAILEDWrite lock not successful
    XB_NO_ERRORIf there is no error
    XB_NOT_OPENDatabase is not open
    XB_INVALID_RECORDInvalid record number
    XB_SEEK_ERRORSeek operation failed
    XB_WRITE_ERRORWrite 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 CodeDescription
    XB_NO_ERRORIf there is no error
    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.

    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 CodeDescription
    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 CodeDescription
    XB_NO_ERRORSetting updated
    3 or 4If Vswitch = 0, it returns current version setting
    XB_INVALID_OPTIONVswictch 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 CodeDescription
    XB_NO_ERRORNo error encountered
    XB_INVALID_RECORDCould not mark record
    XB_NOT_OPENIf the file is not open
    XB_SEEK_ERRORSeek routine error
    XB_WRITE_ERRORWrite 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 CodeDescription
    XB_NO_ERRORNo error encountered
    XB_INVALID_RECORDCould 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 CodeDescription
    XB_NO_ERRORNo error encountered
    XB_LOCK_FAILEDCould not lock file
    XB_WRITE_ERRORCould not write to file
    XB_OPEN_ERRORCould not open temp database

    Example Program:

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