Database High Level API

Many of the database high-level functions have the same name in the files dblocal.c (stand-alone) and dbcs.c (client/server). Here is a list of functions that are common to both API's:

Module Functions

db_initialize

Prototype  : int db_initialize(void)
Returns    : dbeng code

This function must be called once by your application during initialization.

Stand-Alone Versions

In applications that use the Bbuuzzb database engine, this function will initialize all engine data.

Client/Server Versions

An attempt will be made to read the database engine TCP configuration file that must contain the host name and TCP port number of the Bbuuzzb database server. Once the TCP configuration file is read and parsed, an attempt will be made to contact the Bbuuzzb database server and make a status request.

db_open

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

      Name  : tid
Description : returned tid

Returns     : dbeng code

This function will open a Bbuuzzb table. Once the file is open, the data format will be verified and all records will be counted. There is currently a 1023 byte limit to the path/file name.

db_close

Prototype   : int db_close(int tid)
Parameters  :
      Name  : tid
Description : tid

Returns     : dbeng code

This function will close a table.

db_next

Prototype   : int db_next(int tid)
Parameters  :
      Name  : tid
Description : tid


Returns     : dbeng code

This function will get the next record in the table and load it into the current record buffer.

db_top

Prototype   : int db_top(int tid)
Parameters  :
      Name  : tid
Description : tid

Returns     : dbeng code

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

db_get_rec

Prototype   : int db_get_rec(int tid, char *rec_out)
Parameters  :
      Name  : tid
Description : tid

      Name  : rec_out
Description : output record

Returns     : dbeng code

This function will load the current record into the output record. The file pointer will not be advanced.

db_get_rec_size

Prototype   : int db_get_rec_size(int tid, int *rec_size)
Parameters  :
      Name  : tid
Description : tid

      Name  : rec_size
Description : output record size

Returns     : dbeng code

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

db_get_field_size

Prototype   : int db_get_field_size(int tid, int fnum, int *field_size)
Parameters  :
      Name  : tid
Description : tid

      Name  : fnum
Description : field number

      Name  : field_size
Description : output field size

Returns     : dbeng code

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

db_get_field

Prototype   : int db_get_field(int tid, int fnum, int *field_out)
Parameters  :
      Name  : tid
Description : tid

      Name  : fnum
Description : field number

      Name  : field_out
Description : output field

Returns     : dbeng code

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

db_goto

Prototype   : int db_goto(int tid, long rec_num)
Parameters  :
      Name  : tid
Description : tid

      Name  : rec_num
Description : record number

Returns     : dbeng code

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.

db_count

Prototype   : int db_count(int tid, int allopt, long *rec_count)
Parameters  :
      Name  : tid
Description : tid

      Name  : allopt
Description : all records flag

      Name  : rec_count
Description : returned record count

Returns     : dbeng code

This function will physically count the number of records in the table. If the all records flag is off, deleted records will only be counted if the tids process_deleted flag is on. TO unconditionally count all records, set the function all records flag to TRUE. The record count is loaded into the returned record count. The tids record_count will not be affected by the count.

db_put_field

Prototype   : int db_put_field(int tid, int field_num, char *field_data)
Parameters  :
      Name  : tid
Description : tid

      Name  : field_num
Description : field number

      Name  : field_data
Description : field data string

Returns     : dbeng code

This function will put the field data string 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.

db_write

Prototype   : int db_write(int tid)
Parameters  :
      Name  : tid
Description : tid

Returns     : dbeng code

This function will write the current record to the table. The record will be re-written if the record already existed or a new record will be written if the record did not previously exist.

db_delete

Prototype   : int db_delete(int tid)
Parameters  :
      Name  : tid
Description : tid

Returns     : dbeng code

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

db_get_delete_flag

Prototype   : int db_get_delete_flag(int tid, int *flag_value)
Parameters  :
      Name  : tid
Description : tid

      Name  : flag_value
Description : returned flag value

Returns     : dbeng code

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

db_set_delete_flag

Prototype   : int db_set_delete_flag(int tid, int flag_value)
Parameters  :
      Name  : tid
Description : tid

      Name  : flag_value
Description : flag value

Returns     : dbeng code

This function will set the tid 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.

db_pack

Prototype   : int db_pack(int tid)
Parameters  :
      Name  : tid
Description : tid

Returns     : dbeng code

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.

db_find

Prototype   : int db_find(int tid, int cs_flag, char *fdata, int *field_num)
Parameters  :
      Name  : tid
Description : tid

      Name  : cs_flag
Description : case flag

      Name  : fdata
Description : find data

      Name  : field_num
Description : returned field number

Returns     : dbeng code

This function will search all fields in all records (starting from the top of the table) for the find data. 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.

db_find_field

Prototype   : int db_find_field(int tid, int cs_flag, char *fdata, int field_num)
Parameters  :
      Name  : tid
Description : tid

      Name  : cs_flag
Description : case flag

      Name  : fdata
Description : find data

      Name  : field_num
Description : field number

Returns     : dbeng code

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

db_find_part

Prototype   : int db_find_part(int tid, int cs_flag, char *fdata, int *field_num)
Parameters  :
      Name  : tid
Description : tid

      Name  : cs_flag
Description : case flag

      Name  : fdata
Description : find data

      Name  : field_num
Description : returned field number

Returns     : dbeng code

This function will search all fields in all records (starting from the top of the table) for the find data. 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.

db_find_field_part

Prototype   : int db_find_field_part(int tid, int cs_flag, char *fdata, int field_num)
Parameters  :
      Name  : tid
Description : tid

      Name  : cs_flag
Description : case flag

      Name  : fdata
Description : find data

      Name  : field_num
Description : field number

Returns     : dbeng code

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

db_get_nfields

Prototype   : int db_get_nfields(int tid, int *nfields)
Parameters  :
      Name  : tid
Description : tid

      Name  : nfields
Description : returned number of fields

Returns     : dbeng code

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

db_get_rec_num

Prototype   : int db_get_rec_num(int tid, long *rec_num)
Parameters  :
      Name  : tid
Description : tid

      Name  : rec_num
Description : returned record number

Returns     : dbeng code

This function will get the record number for the specified tid. 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.

db_get_pos

Prototype   : int db_get_pos(int tid, long *pos)
Parameters  :
      Name  : tid
Description : tid

      Name  : pos
Description : returned record position

Returns     : dbeng code

This function will get the file position/offset for the current record and the specified tid. 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 record position.

db_set_pos

Prototype   : int db_set_pos(int tid, long pos)
Parameters  :
      Name  : tid
Description : tid

      Name  : pos
Description : file position/offset

Returns     : dbeng code

This function will set the file pointer to the specified file position/offset. An engine error will be logged if the file position/offset is not the first byte in a record header. To obtain the file position of the desired record, use the function db_get_pos once you have located the desired record.

db_get_change_rec_flag

Prototype   : int db_get_change_rec_flag(int tid, int *flag)
Parameters  :
      Name  : tid
Description : tid

      Name  : flag
Description : returned change record flag

Returns     : dbeng code

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

db_set_change_rec_flag

Prototype   : int db_set_change_rec_flag(int tid, int flag)
Parameters  :
      Name  : tid
Description : tid

      Name  : flag
Description : change record flag

Returns     : dbeng code

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

db_get_enf_change_rec_flag

Prototype   : int db_get_enf_change_rec_flag(int tid, int *flag)
Parameters  :
      Name  : tid
Description : tid

      Name  : flag
Description : returned enforce change record flag

Returns     : dbeng code

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

db_set_enf_change_rec_flag

Prototype   : int db_set_enf_change_rec_flag(int tid, int flag)
Parameters  :
      Name  : tid
Description : tid

      Name  : flag
Description : enforce change record flag

Returns     : dbeng code

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

db_get_rec_count

Prototype   : int db_get_rec_count(int tid, long *count)
Parameters  :
      Name  : tid
Description : tid

      Name  : count
Description : returned record count

Returns     : dbeng code

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

db_new

Prototype   : int db_new(int tid)
Parameters  :
      Name  : tid
Description : tid

Returns     : dbeng code

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

This function should be called before loading a new record.

db_get_is_table_locked

Prototype   : int db_get_is_table_locked(int tid, int *flag)
Parameters  :
      Name  : tid
Description : tid

      Name  : flag
Description : returned table locked flag

Returns     : dbeng code

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

db_set_is_table_locked

Prototype   : int db_set_is_table_locked(int tid, int flag)
Parameters  :
      Name  : tid
Description : tid

      Name  : flag
Description : is table locked flag

Returns     : dbeng code

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

db_new_table

Prototype   : int db_new_table(char *fname, int *tid)

Parameters  :
      Name  : fname
Description : path/file name

      Name  : tid
Description : input tid flag and output tid

Returns     : dbeng code

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 output tid.

Goto Top | Future Lab Home | Contact Webmaster | Feedback

Copyright © 1999 Future Lab Inc., Last Updated Jun 8, 1999