Many of the database high-level functions have the same name in the files dblocal.c (single user) and dbcs.c (client/server). Here is a list of functions that are common to both API's:
Prototype : int db_initialize(void) Returns : dbeng code
This function must be called once by your application during initialization.
In applications that use the Bbuuzzb database engine, this function will initialize all engine data.
An attempt will be made to contact a socloc server and obtain the host name and TCP port number of the Bbuuzzb database server.
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. When the catalog flag is down, a physical path/file name is expected. When the catalog flag is high, a logical Bbuuzzb table name is expected.
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.
Prototype : int db_close(int tid)
Parameters :
Name : tid
Description : tid
Returns : dbeng code
This function will close a table.
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.
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 before the first record in the table.
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.
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.
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.
Prototype : int db_get_field(int tid, int fnum, char *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.
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.
Prototype : int db_count(int tid, long *acount, long *dcount)
Parameters :
Name : tid
Description : tid
Name : acount
Description : returned active record count
Name : dcount
Description : returned deleted record count
Returns : dbeng code
This function will physically count the number of records in the table. The active record count is loaded into the returned active record count and the deleted record count will be loaded into the returned deleted record count upon success. The actual table active_record_count and the deleted_record_count will not be affected by the count.
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.
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.
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 or db_sort function is called, the table will be re-written and the records marked for deletion are removed.
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.
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.
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.
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 current record) 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.
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 current record) 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.
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 current record) 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.
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 current record) 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.
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.
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.
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. Note that the position returned is not the current position (which is usually the end of the record) but the starting position of the current record.
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.
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.
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.
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.
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.
Prototype : int db_get_autopack(int tid, int *pvalue)
Parameters :
Name : tid
Description : tid
Name : pvalue
Description : returned autopack value
Returns : dbeng code
This function will obtain the current value of the autopack threshold for a single table. Upon success, the table autopack value will be returned in the returned autopack value.
Prototype : int db_set_autopack(int tid, int pvalue)
Parameters :
Name : tid
Description : tid
Name : pvalue
Description : autopack value
Returns : dbeng code
This function will set the autopack threshold for a single table. Note that a zero autopack value will turn off the autopack feature for the given table.
Prototype : int db_get_rec_count(int tid, long *acount, long *dcount)
Parameters :
Name : tid
Description : tid
Name : acount
Description : returned active record count
Name : dcount
Description : returned deleted record count
Returns : dbeng code
This function will get the table record counts and load the active record count into the returned active record count and load the deleted record count into the returned deleted record count. Note that this function does not physically count the records in the table (as the function db_count does).
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.
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.
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.
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. The contents of the path/file name should be given according to the guidelines given in the function dbeng_ll_new_table.
Prototype : int db_get_open_table_list(char *pat, char *list_out)
Parameters :
Name : pat
Description : match pattern
Name : list_out
Description : returned open table list
Returns : dbeng code
This function will return a list of all open tables in the returned open table list which must be allocated to sufficient size by the caller. The list consists of each open table tid followed by a comma and the table path/file name. Each entry in the list is delimited by DBENG_LIST_DELIM defined in dbmess.h. The match pattern may contain a table path/file pattern acceptable to the pmatch function. If the match pattern is NULL or empty, all tables in use will be returned.
Prototype : int db_get_nsubfields(int tid, int fnum, int *nsubfields)
Parameters :
Name : tid
Description : tid
Name : fnum
Description : field number
Name : nsubfields
Description : returned number of sub-fields
Returns : dbeng code
This function will get the number of sub-fields in the field number for the tid. Upon success the number of sub-fields will be loaded into the returned number of sub-fields.
Prototype : int db_get_subfield_size(int tid, int fnum, int sfnum,
int *sfsize)
Parameters :
Name : tid
Description : tid
Name : fnum
Description : field number
Name : sfnum
Description : sub-field number
Name : sfsize
Description : output sub-field size
Returns : dbeng code
This function will load the size (in bytes) of the sub-field number into the output sub-field size.
Prototype : int db_get_subfield(int tid, int fnum, int sfnum, char *sfout)
Parameters :
Name : tid
Description : tid
Name : fnum
Description : field number
Name : sfnum
Description : sub-field number
Name : sfout
Description : output sub-field
Returns : dbeng code
This function will load the contents of the sub-field sub-field number into the output sub-field which must already be allocated to sufficient size.
Prototype : int db_put_subfield(int tid, int fnum, int sfnum, char *sfdata)
Parameters :
Name : tid
Description : tid
Name : fnum
Description : field number
Name : sfnum
Description : sub-field number
Name : sfdata
Description : sub-field data
Returns : dbeng code
This function will put the sub-field data into the record buffer at the indicated field number and sub-field number. If the field number or sub-field number does not exist, the record buffer will be extended out to the required sub-field.
Prototype : int db_get_nsubsubfields(int tid, int fnum, int sfnum,
int *nsubsubfields)
Parameters :
Name : tid
Description : tid
Name : fnum
Description : field number
Name : sfnum
Description : sub-field number
Name : nsubsubfields
Description : returned number of sub-sub-fields
Returns : dbeng code
This function will get the number of sub-sub-fields in the sub-field number within the field number for the tid. Upon success the number of sub-sub-fields will be loaded into the returned number of sub-sub-fields.
Prototype : int db_get_subsubfield_size(int tid, int fnum, int sfnum,
int ssfnum, int *ssfsize)
Parameters :
Name : tid
Description : tid
Name : fnum
Description : field number
Name : sfnum
Description : sub-field number
Name : ssfnum
Description : sub-sub-field number
Name : ssfsize
Description : output sub-sub-field size
Returns : dbeng code
This function will load the size (in bytes) of the sub-sub-field number into the output sub-sub-field size.
Prototype : int db_get_subsubfield(int tid, int fnum, int sfnum, int ssfnum,
char *ssfout)
Parameters :
Name : tid
Description : tid
Name : fnum
Description : field number
Name : sfnum
Description : sub-field number
Name : ssfnum
Description : sub-sub-field number
Name : ssfout
Description : output sub-sub-field
Returns : dbeng code
This function will load the contents of the sub-sub-field sub-sub-field number into the output sub-sub-field which must already be allocated to sufficient size.
Prototype : int db_put_subsubfield(int tid, int fnum, int sfnum, int ssfnum,
char *ssfdata)
Parameters :
Name : tid
Description : tid
Name : fnum
Description : field number
Name : sfnum
Description : sub-field number
Name : ssfnum
Description : sub-sub-field number
Name : ssfdata
Description : sub-sub-field data
Returns : dbeng code
This function will put the sub-sub-field data into the record buffer at the indicated field number, sub-field number and sub-sub-field number. If the field number, sub-field number or sub-sub-field number does not exist, the record buffer will be extended out to the required sub-sub-field.
Prototype : int db_delete_table(char *tname)
Parameters :
Name : tname
Description : table name
Returns : dbeng code
This function will delete a table by its table name (physical file name if the catalog flag is down, logical table name with the catalog flag high). The table must not be open by any tid.
Prototype : int db_exist(char *tname, int *exist_flag)
Parameters :
Name : tname
Description : table name
Name : exist_flag
Description : returned exist flag
Returns : dbeng code
This function will determine whether a database table exists. Naming convention is the same as for db_open. The returned exist flag will be loaded with the exist flag (TRUE=table exists).
Prototype : int db_clear_table(char *tname)
Parameters :
Name : tname
Description : table name
Returns : dbeng code
This function will clear a table of all its data by its table name (physical file name when the catalog flag is down, logical table name when the catalog flag is high). Table must not be open by any tid.
Prototype : int db_copy_table(int src_tid, int dest_tid)
Parameters :
Name : src_tid
Description : source tid
Name : dest_tid
Description : destination tid
Returns : dbeng code
This function will copy a table from source tid to destination tid. No regard is given to whether the destination tid table already contains data.
Prototype : int db_sort(int tid, char *specs)
Parameters :
Name : tid
Description : table tid
Name : specs
Description : sort specifications
Returns : dbeng code
This function will sort a table. The sort specifications are expected in specs.
Prototype : int db_get_sort_max_mem(int tid, long *mem)
Parameters :
Name : tid
Description : table tid
Name : mem
Description : returned memory value
Returns : dbeng code
This function will get the current allowable sort max memory allocation. The returned memory value is returned upon success.
Prototype : int db_set_sort_max_mem(int tid, long mem)
Parameters :
Name : tid
Description : table tid
Name : mem
Description : sort memory value
Returns : dbeng code
This function will set the allowable maximum sort memory to the sort memory value.
Prototype : int db_get_sort_max_open_bin(int tid, int *open_bin)
Parameters :
Name : tid
Description : table tid
Name : open_bin
Description : returned open bin value
Returns : dbeng code
This function will get the current allowable sort number of open bin tables. The returned open bin value is returned upon success.
Prototype : int db_set_sort_max_open_bin(int tid, int open_bin)
Parameters :
Name : tid
Description : table tid
Name : open_bin
Description : open bin value
Returns : dbeng code
This function will set the allowable maximum number of open bin tables during a sort to the open bin value.
Prototype : int db_delete_field(int tid, int fnum)
Parameters :
Name : tid
Description : table tid
Name : fnum
Description : field number
Returns : dbeng code
This function will completely remove the field number field from the current record. Note that all field numbers past the field being deleted will change.
Prototype : int db_delete_subfield(int tid, int fnum, int sfnum)
Parameters :
Name : tid
Description : table tid
Name : fnum
Description : field number
Name : sfnum
Description : subfield number
Returns : dbeng code
This function will completely remove the subfield number subfield from the field number field within the current record.
Prototype : int db_delete_subsubfield(int tid, int fnum, int sfnum,
int ssfnum)
Parameters :
Name : tid
Description : table tid
Name : fnum
Description : field number
Name : sfnum
Description : subfield number
Name : ssfnum
Description : subsubfield number
Returns : dbeng code
This function will completely remove the subsubfield number subsubfield from the subfield number subfield in the field number field within the current record.
Prototype : int db_get_catalog_list(char *pat, char *lout)
Parameters :
Name : pat
Description: input match pattern
Name : lout
Description: output catalog list
Returns : dbeng code
This function will return a list of matching table names (logical) from the system catalog. The list is returned in the output catalog list which must be already allocated to sufficient size. The list is delimited by DBENG_LIST_DELIM. Each entry in the list contains the logical name followed by the file/path name (physical name). The two fields in the list are delimited by a comma. The input match pattern may contain a pattern acceptable to the pmatch function. If the input match pattern is NULL or empty, all entries from the catalog will be returned.
Prototype : void db_end(void)
This function will shutdown the database API.