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:
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:
This module depends on the following header files:
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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:
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.
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.
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.
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.
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.
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.
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.
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.
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.
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).
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.