Database High Level API

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:

- db_initialize
- db_open
- db_close
- db_next
- db_top
- db_get_rec
- db_get_rec_size
- db_get_field_size
- db_get_field
- db_goto
- db_count
- db_put_field
- db_write
- db_delete
- db_get_delete_flag
- db_set_delete_flag
- db_pack
- db_find
- db_find_field
- db_find_part
- db_find_field_part
- db_get_nfields
- db_get_rec_num
- db_get_pos
- db_set_pos
- db_get_change_rec_flag
- db_set_change_rec_flag
- db_get_enf_change_rec_flag
- db_set_enf_change_rec_flag
- db_get_autopack
- db_set_autopack
- db_get_rec_count
- db_new
- db_get_is_table_locked
- db_set_is_table_locked
- db_new_table
- db_get_open_table_list
- db_get_nsubfields
- db_get_subfield_size
- db_get_subfield
- db_put_subfield
- db_get_nsubsubfields
- db_get_subsubfield_size
- db_get_subsubfield
- db_put_subsubfield
- db_delete_table
- db_exist
- db_clear_table
- db_copy_table
- db_sort
- db_get_sort_max_mem
- db_set_sort_max_mem
- db_get_sort_max_open_bin
- db_set_sort_max_open_bin
- db_delete_field
- db_delete_subfield
- db_delete_subsubfield
- db_get_catalog_list
- db_end

# High-level Database Functions

## db_initialize

    Prototype  : int db_initialize(void)
    Returns    : dbeng code

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

### Single User 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 contact a socloc server and obtain the host name and TCP port number of the Bbuuzzb database server.

## 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. 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.

## 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 before the first record in 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, 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.

## 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, 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.

## 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 or db_sort 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 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.

## 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 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.

## 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 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.

## 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 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.

## 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. 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.

## 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_autopack

    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.

## db_set_autopack

    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.

## db_get_rec_count

    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).

## 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:

- rec (cleared)
- record_number (zeroed)
- orig_position (-1)
- change_rec_flag (FALSE)

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. The contents of the path/file name should be given according to the guidelines given in the function dbeng_ll_new_table.

## db_get_open_table_list

    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.

## db_get_nsubfields

    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.

## db_get_subfield_size

    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.

## db_get_subfield

    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.

## db_put_subfield

    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.

## db_get_nsubsubfields

    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.

## db_get_subsubfield_size

    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.

## db_get_subsubfield

    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.

## db_put_subsubfield

    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.

## db_delete_table

    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.

## db_exist

    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).

## db_clear_table

    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.

## db_copy_table

    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.

## db_sort

    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.

## db_get_sort_max_mem

    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.

## db_set_sort_max_mem

    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.

## db_get_sort_max_open_bin

    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.

## db_set_sort_max_open_bin

    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.

## db_delete_field

    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.

## db_delete_subfield

    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.

## db_delete_subsubfield

    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.

## db_get_catalog_list

    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.

## db_end

    Prototype  : void db_end(void)

This function will shutdown the database API.

Goto Top | Future Lab Home | Contact Webmaster | Feedback

Copyright © 1999-2006 Future Lab, Last Updated Jun 30, 2006