Database Low Level Engine

This module represents the Bbuuzzb database engine. All table/record access is actually performed by functions in this module.

Each table is a file. A table can have as many records as you have available disk space. Each record is made up of a series of fields. Fields are referenced by field number starting from the beginning of the record. The engine is data typeless so all data is in string format. The database engine and API's page contains a complete discussion of the engine file format and limitations.

The engine manages all table access through a single link list of dbeng_table structures. Each time a table is opened, a unique positive integer is generated called a tid. This engine uses the dbeng_table link list based on a head node called dbeng_head. Both stand-alone and client/server API's use tids to access table data.

While it is possible for a software developer to call the functions in this module directly from his/her application, this is not recommended for two reasons:

Here is a list of functions in this module:

Module Dependencies

This module is part of stand-alone database access and needs to be linked with the following modules:

In the Unix platform, this module is compiled along with the other database modules as part of the script cdbeng. A good example of a Unix script for a client application that uses this database engine is mkdbm or mkdbsrv. There are a number of good example applications that use this engine including:

Module Header Files

This module depends on the following header files:

Module Functions

Here is a list of all functions contained within the Bbuuzzb database engine. Note that each function contains a reference to the high level equivalent function.

dbeng_pack_table

Prototype   : int dbeng_pack_table(struct dbeng_table *ot)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

Returns     : dbeng code
High Level  : db_pack

This function will pack a table by physically removing all records marked for deletion. Packing involves copying all active records to a temporary table and then swapping the actual table for the temporary table.

dbeng_open_table

Prototype   : int dbeng_open_table(char *filename, int *tid)
Parameters  :
      Name  : filename
Description : path/file name

      Name  : tid
Description : returned tid

Returns     : dbeng code
High Level  : db_open

This function will open a Bbuuzzb table. Once the file is open, the data format will be verified and all records will be counted.

dbeng_close_table

Prototype   : int dbeng_close_table(struct dbeng_table *ot)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

Returns     : dbeng code
High Level  : db_close

This function will close a table.

dbeng_goto_top

Prototype   : int dbeng_goto_top(struct dbeng_table *ot)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

Returns     : dbeng code
High Level  : db_top

This function will move the file pointer to the top of the table.

dbeng_rewrite_recd

Prototype   : int dbeng_rewrite_recd(struct dbeng_table *ot)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

Returns     : dbeng code
High Level  : none

This function will re-write the current record by deleting the existing record and writing a new record at the end of the table. The record contents are assumed to already be loaded into the record buffer (rec). Note that there is no direct equivalent high level function although the function db_write will re-write a record if one already exists.

dbeng_delete_recd

Prototype   : int dbeng_delete_recd(struct dbeng_table *ot)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

Returns     : dbeng code
High Level  : db_delete

This function will delete the ot current record. The record is not actually deleted from the table but is marked for deletion. Once the dbeng_pack_table function is called, the table will be re-written and the records marked for deletion are removed.

dbeng_write_new_recd

Prototype   : int dbeng_write_new_recd(struct dbeng_table *ot)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

Returns     : dbeng code
High Level  : none

This function will write a new record in the table. No regard is given to the fact that the record might already exist. The record contents are assumed to already be loaded into the record buffer (rec). Note that there is no direct equivalent high level function although the function db_write will write a new record if an existing record does not exist.

dbeng_write_string_recd

Prototype   : int dbeng_write_string_recd(struct dbeng_table *ot, char *rec)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

      Name  : rec
Description : record string

Returns     : dbeng code
High Level  : none

This function will write a new record in the table. Instead of the record being written from the record buffer (rec) (as with dbeng_write_new_recd), the record will be written from the record string. No regard is given to the fact that the record might already exist. Note that there is no direct equivalent high level function. This function is used internally by the engine to copy records.

dbeng_write_recd

Prototype   : int dbeng_write_recd(struct dbeng_table *ot)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

Returns     : dbeng code
High Level  : db_write

This function will either write a new record or re-write an existing record depending on the value of the record_number. If the record_number is zero, a new record will be written to the end of the table. If the record_number is non-zero an existing record is assumed and this record will first be marked for deletion before the new record is written.

dbeng_new

Prototype   : int dbeng_new(struct dbeng_table *ot)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

Returns     : dbeng code
High Level  : db_new

This function will prepare for a new record. The following dbeng_table values are affected:

dbeng_get_rec

Prototype   : int dbeng_get_rec(struct dbeng_table *ot, char *rec_out)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

      Name  : rec_out
Description : output record

Returns     : dbeng code
High Level  : db_get_rec

This function will load the contents of the record buffer into the output record which must already be allocated to sufficient size.

dbeng_get_field

Prototype   : int dbeng_get_field(struct dbeng_table *ot, char *fout, int fnum)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

      Name  : fout
Description : output field

      Name  : fnum
Description : field number

Returns     : dbeng code
High Level  : db_get_field

This function will load the contents of the field field number into the output field which must already be allocated to sufficient size.

dbeng_put_field

Prototype   : int dbeng_put_field(struct dbeng_table *ot, char *fout, int fnum)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

      Name  : fin
Description : input field

      Name  : fnum
Description : field number

Returns     : dbeng code
High Level  : db_put_field

This function will put the input field into the record buffer at the indicated field number. If the field number does not exist, the record buffer will be extended out to the required field.

dbeng_find

Prototype   : int dbeng_find(struct dbeng_table *ot, int cs, char fstr, int *fnum)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

      Name  : cs
Description : case flag

      Name  : fstr
Description : find string

      Name  : fnum
Description : returned field number

Returns     : dbeng code
High Level  : db_find

This function will search all fields in all records (starting from the top of the table) for the find string. Only complete/whole fields will match. Comparison is according to the case flag where zero is case sensitive and one is case insensitive. Upon a successful match, the matching record will be current and the returned field number will indicate the field that matched.

dbeng_find_field

Prototype   : int dbeng_find_field(struct dbeng_table *ot, int cs, char fstr, int fnum)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

      Name  : cs
Description : case flag

      Name  : fstr
Description : find string

      Name  : fnum
Description : field number

Returns     : dbeng code
High Level  : db_find_field

This function will search field number in all records (starting from the top of the table) for the find string. Only complete/whole fields will match. Comparison is according to the case flag where zero is case sensitive and one is case insensitive.

dbeng_find_part

Prototype   : int dbeng_find_part(struct dbeng_table *ot, int cs, char fstr, int *fnum)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

      Name  : cs
Description : case flag

      Name  : fstr
Description : find string

      Name  : fnum
Description : returned field number

Returns     : dbeng code
High Level  : db_find_part

This function will search all fields in all records (starting from the top of the table) for the find string. Any part of any field will match. Comparison is according to the case flag where zero is case sensitive and one is case insensitive. Upon a successful match, the matching record will be current and the returned field number will indicate the field that matched.

dbeng_find_field_part

Prototype   : int dbeng_find_field_part(struct dbeng_table *ot, int cs, char fstr, int fnum)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

      Name  : cs
Description : case flag

      Name  : fstr
Description : find string

      Name  : fnum
Description : field number

Returns     : dbeng code
High Level  : db_find_field_part

This function will search field number in all records (starting from the top of the table) for the find string. Any part of the field will match. Comparison is according to the case flag where zero is case sensitive and one is case insensitive.

dbeng_nfields

Prototype   : int dbeng_nfields(struct dbeng_table *ot, int *nfields)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

      Name  : nfields
Description : returned number of fields

Returns     : dbeng code
High Level  : db_get_nfields

This function will get the number of fields in the current record. Upon success the number of fields in the record will be loaded into the returned number of fields.

dbeng_count_rec

Prototype   : int dbeng_count_rec(struct dbeng_table *ot, long *count)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

      Name  : count
Description : returned record count

Returns     : dbeng code
High Level  : db_count

This function will physically count the number of records in the table. The record count is loaded into the returned record count. The record_count will not be affected by the count.

dbeng_rec_count

Prototype   : int dbeng_rec_count(struct dbeng_table *ot, long *count)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

      Name  : count
Description : returned record count

Returns     : dbeng code
High Level  : db_get_rec_count

This function will get the record_count and load it into the returned record count. Note that this function does not physically count the records in the table (as dbeng_count_rec does).

dbeng_goto_record

Prototype   : int dbeng_goto_record(struct dbeng_table *ot, long rnum)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

      Name  : rnum
Description : record number

Returns     : dbeng code
High Level  : db_goto

This function will goto to a specific record number within the table. The record number is a sequential number starting from the top of the table.

dbeng_get_recd

Prototype   : int dbeng_get_recd(struct dbeng_table *ot, long rnum)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

Returns     : dbeng code
High Level  : db_next

This function will get the next record in the table and load it into the current record buffer. The file pointer must be positioned at the beginning of a record header.

dbeng_rec_resize

Prototype   : int dbeng_rec_resize(struct dbeng_table *ot, int nsize)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

      Name  : nsize
Description : new record size

Returns     : dbeng code
High Level  : none

This function will re-allocate the record buffer to the new record size. This function is used internally by the engine itself and, as such, there is no equivalent high level function.

dbeng_rec_size

Prototype   : int dbeng_rec_size(struct dbeng_table *ot, int *rsize)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

      Name  : rsize
Description : returned record size

Returns     : dbeng code
High Level  : db_get_rec_size

This function will load the size (in bytes) of the current record into the returned record size.

dbeng_field_size

Prototype   : int dbeng_field_size(struct dbeng_table *ot, int fnum, int *fsize)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

      Name  : fnum
Description : field number

      Name  : fsize
Description : returned field size

Returns     : dbeng code
High Level  : db_get_field_size

This function will load the size (in bytes) of the field number into the returned field size.

dbeng_rec_num

Prototype   : int dbeng_rec_num(struct dbeng_table *ot, long *rnum)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

      Name  : rnum
Description : returned record number

Returns     : dbeng code
High Level  : db_get_rec_num

This function will get the record number. The record number is actually retrieved from the dbeng_table structure member record_number. Upon success the record number will be loaded into the returned record number.

dbeng_pos

Prototype   : int dbeng_pos(struct dbeng_table *ot, long *fpos)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

      Name  : fpos
Description : returned file position

Returns     : dbeng code
High Level  : db_get_pos

This function will get the file position/offset for the current record. The file position is actually retrieved from the dbeng_table structure member orig_position. Upon success the file position will be loaded into the returned file position.

dbeng_set_pos

Prototype   : int dbeng_set_pos(struct dbeng_table *ot, long fpos)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

      Name  : fpos
Description : file position

Returns     : dbeng code
High Level  : db_set_pos

This function will set the file pointer to the specified file position. An engine error will be logged if the file position is not the first byte in a record header.

dbeng_change_rec_flag

Prototype   : int dbeng_change_rec_flag(struct dbeng_table *ot, int *flag)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

      Name  : flag
Description : returned change record flag

Returns     : dbeng code
High Level  : db_get_change_rec_flag

This function will get the change_rec_flag. Upon success, the flag will be loaded into the returned change record flag.

dbeng_set_change_rec_flag

Prototype   : int dbeng_set_change_rec_flag(struct dbeng_table *ot, int flag)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

      Name  : flag
Description : change record flag

Returns     : dbeng code
High Level  : db_set_change_rec_flag

This function will set the change_rec_flag. The value of change record flag must be zero or one.

dbeng_delete_flag

Prototype   : int dbeng_delete_flag(struct dbeng_table *ot, int *flag)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

      Name  : flag
Description : returned delete flag

Returns     : dbeng code
High Level  : db_get_delete_flag

This function will get the process_deleted flag. This flag indicates whether records marked for deletion are included in table/record processing.

dbeng_set_delete_flag

Prototype   : int dbeng_set_delete_flag(struct dbeng_table *ot, int flag)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

      Name  : flag
Description : flag value

Returns     : dbeng code
High Level  : db_set_delete_flag

This function will set the process_deleted flag to the given flag value which must be zero or one. The process_deleted flag indicates whether records marked for deletion are included in table/record processing.

dbeng_enf_change_rec_flag

Prototype   : int dbeng_enf_change_rec_flag(struct dbeng_table *ot, int *flag)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

      Name  : flag
Description : returned enforce change record flag

Returns     : dbeng code
High Level  : db_get_enf_change_rec_flag

This function will get the enforce_change_rec_flag. Upon success, the flag will be loaded into the returned enforce change record flag.

dbeng_set_enf_change_rec_flag

Prototype   : int dbeng_set_enf_change_rec_flag(struct dbeng_table *ot, int flag)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

      Name  : flag
Description : enforce change record flag

Returns     : dbeng code
High Level  : db_set_enf_change_rec_flag

This function will set the enforce_change_rec_flag. The value of enforce change record flag must be zero or one.

dbeng_is_table_locked

Prototype   : int dbeng_is_table_locked(struct dbeng_table *ot, int *flag)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

      Name  : flag
Description : returned table locked flag

Returns     : dbeng code
High Level  : db_get_is_table_locked

This function will retrieve the is_table_locked flag and load it into the returned table locked flag.

dbeng_set_is_table_locked

Prototype   : int dbeng_set_is_table_locked(struct dbeng_table *ot, int flag)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

      Name  : flag
Description : table locked flag

Returns     : dbeng code
High Level  : db_set_is_table_locked

This function will set the is_table_locked flag to the value of table locked flag which must be zero or one.

dbeng_lock_table

Prototype   : int dbeng_lock_table(struct dbeng_table *ot)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

Returns     : dbeng code
High Level  : none

This function will lock a table. Every occurrence of the table will be locked. This function is used internally by the engine and should not be called outside of this module.

dbeng_unlock_table

Prototype   : int dbeng_unlock_table(struct dbeng_table *ot)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

Returns     : dbeng code
High Level  : none

This function will unlock a table. Every occurrence of the table will be unlocked. This function is used internally by the engine and should not be called outside of this module.

dbeng_new_table

Prototype   : int dbeng_new_table(char *fname, int *tid)
Parameters  :
      Name  : fname
Description : path/file name

      Name  : tid
Description : input tid flag and returned tid

Returns     : dbeng code
High Level  : db_new_table

This function will create a new empty table using the path/file name. If the input tid flag is one, the table will also be opened and upon successful completion, the new table tid will be returned in the returned tid.

dbeng_terminate

Prototype   : void dbeng_terminate(void)

High Level  : none

This function will terminate the Bbuuzzb database engine by first closing all tables and de-allocating the engine link list. This function should only be called by the engine upon a critical situation.

dbeng_is_active_rec

Prototype   : int dbeng_is_active_rec(struct dbeng_table *ot)
Parameters  :
      Name  : ot
Description : pointer to dbeng_table structure

Returns     : dbeng code
High Level  : none

This function will determine whether there is an active record. An active record is assumed when all of the following conditions are meet:

This function should only be called internally by the Bbuuzzb database engine.

dbeng_initialize

Prototype   : int dbeng_initialize(void)

Returns     : dbeng code
High Level  : db_initialize

This function will initialize the Bbuuzzb database engine by setting the head (dbeng_head) of the link list to null and setting the table counter (dbeng_table_count) to zero. Lastly, the configuration file is read and parsed.

dbeng_get_tid

Prototype   : int dbeng_get_tid(void)

Returns     : tid
High Level  : none

This function will generate the next tid to be used. The tid is then checked against all tids in use. This function is used internally by the Bbuuzzb database engine and should not be called outside of this module.

dbeng_atid_lookup

Prototype   : struct dbeng_table *dbeng_atid_lookup(int tid)
Parameters  :
      Name  : tid
Description : tid

Returns     : pointer to dbeng_table structure
High Level  : none

This function will perform a lookup based on a given tid and return the corresponding dbeng_table pointer. This function is used internally by the Bbuuzzb database engine and should not be called outside of this module.

dbeng_ferror

Prototype   : void dbeng_ferror(char *mess)
Parameters  :
      Name  : mess
Description : message

High Level  : none

This function will log the message with the personal logger (if compiled for stand-alone) or the system logger (if compiled for client/server). The message will be logged regardless of the logging status (on or off). The original status of logging will be preserved. The Bbuuzzb engine uses this function to record critical errors. This function is used internally by the Bbuuzzb database engine and should not be called outside of this module.

Goto Top | Future Lab Home | Contact Webmaster | Feedback

Copyright © 1999-2000 Future Lab Inc., Last Updated May 2, 2000