Database Low Level Engine

This module is the Bbuuzzb database engine and has the file name dbeng.c. All table/record access is actually performed by functions in this module. This API can be compiled for all stated platforms.

Each database table is an OS 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. All table data is 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 single user 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:

- the same code could not be used for a client/server version of the application
- the developer must manage an array (how big?) of dbeng_table pointers.

Any mention of QNX in this documentation refers to the QNX 4.x OS.

Here is a list of functions in this module:

- dbeng_pack_table
- dbeng_open_systable
- dbeng_open_table
- dbeng_ll_open_table
- dbeng_close_table
- dbeng_goto_top
- dbeng_rewrite_recd
- dbeng_delete_recd
- dbeng_write_new_recd
- dbeng_write_string_recd
- dbeng_write_recd
- dbeng_new
- dbeng_get_rec
- dbeng_get_field
- dbeng_put_field
- dbeng_find
- dbeng_find_field
- dbeng_find_part
- dbeng_find_field_part
- dbeng_nfields
- dbeng_count_rec
- dbeng_rec_count
- dbeng_goto_record
- dbeng_get_recd
- dbeng_rec_resize
- dbeng_rec_size
- dbeng_field_size
- dbeng_rec_num
- dbeng_pos
- dbeng_set_pos
- dbeng_change_rec_flag
- dbeng_set_change_rec_flag
- dbeng_delete_flag
- dbeng_set_delete_flag
- dbeng_enf_change_rec_flag
- dbeng_set_enf_change_rec_flag
- dbeng_autopack
- dbeng_set_autopack
- dbeng_is_table_locked
- dbeng_set_is_table_locked
- dbeng_lock_table
- dbeng_unlock_table
- dbeng_tmp_systable
- dbeng_new_systable
- dbeng_new_table
- dbeng_ll_new_table
- dbeng_delete_table
- dbeng_open_table_list
- dbeng_exist
- dbeng_clear_table
- dbeng_nsubfields
- dbeng_subfield_size
- dbeng_get_subfield
- dbeng_put_subfield
- dbeng_nsubsubfields
- dbeng_subsubfield_size
- dbeng_get_subsubfield
- dbeng_put_subsubfield
- dbeng_ll_open
- dbeng_ll_close
- dbeng_is_systable
- dbeng_copy_table
- dbeng_record_header
- dbeng_put_which_field
- dbeng_put_which_subfield
- dbeng_put_which_subfield
- dbeng_put_which_subsubfield
- dbeng_ll_copy_table
- dbeng_delete_field
- dbeng_delete_subfield
- dbeng_delete_subsubfield
- dbeng_set_record_count
- dbeng_terminate
- dbeng_is_active_rec
- dbeng_initialize
- dbeng_get_tid
- dbeng_table_in_use
- dbeng_atid_lookup
- dbeng_ferror

# Module Dependencies

This module is part of the single user and server database access and needs to be linked with the following modules:

- fio.c
- parse.c
- logger.c
- ip.c (database server and single user if using system logger, all platforms except QNX and DOS)
- ipcomm.c (database server and single user if using system logger, all platforms except QNX and DOS)
- ipcsrv.c (database server only)
- sys_log.c (database server and single user if using system logger, all platforms except DOS)
- slogcode.c (database server and single user if using system logger, all platforms except DOS)
- sloc.c (database server and single user if using system logger, all platforms except QNX and DOS)
- slconfig.c (database server and single user if using system logger, all platforms except QNX and DOS)
- sliocode.c (database server and single user if using system logger, all platforms except QNX and DOS)
- sconnect.c (database server and single user if using system logger, all platforms except QNX and DOS)
- dbengses.c (database server only)
- dbengrep.c (database server only)
- dbiocode.c
- dblocal.c
- dbengcfg.c
- dblocfg.c
- dbengsrt.c
- dbengcat.c

In the Linux/Unix/QNX platforms, this module is compiled along with the other database modules as part of the script cdbeng. A good example of a shell script for a single user application that uses this database engine is mkdb or mkdbstress. There are a number of good example applications that use this engine including:

- database command line interpreter
- database server
- database stress

# Module Header Files

This module depends on the following header files:

- stdhead.h
- dbmess.h
- dbeng.h
- dbiocode.h
- dbengcfg.h
- dbengsrt.h

# 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 system table and then swapping the actual table for the temporary table.

## dbeng_open_systable

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

          Name  : tid
    Description : returned tid

    Returns     : dbeng code
    High Level  : None

This function will open a Bbuuzzb system table. Once the file is open, the data format will be verified and all records will be counted. This function behaves just like dbeng_open_table except that the physical file is always left open.

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

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

          Name  : tid
    Description : returned tid

          Name  : systable_flag
    Description : system table flag

    Returns     : dbeng code
    High Level  : None

This private function will open a table. Table ID is returned in the returned tid upon success. If the system catalog flag is on, only logical table names listed in the system catalog will succeed unless the name is prefixed with the DBENG_CATALOG_FNAME_IND character.

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

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

## 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 *fin, 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 beginning of the current record) 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 beginning of the current record) 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 beginning of the current record) 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 beginning of the current record) 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 *acount,
                                      long *dcount)
    Parameters  :
          Name  : ot
    Description : pointer to dbeng_table structure

          Name  : acount
    Description : returned active record count

          Name  : dcount
    Description : returned deleted record count

    Returns     : dbeng code
    High Level  : db_count

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.

## dbeng_rec_count

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

          Name  : acount
    Description : returned active record count

          Name  : dcount
    Description : returned deleted record count
    Returns     : dbeng code
    High Level  : db_get_rec_count

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 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 flag to the given flag value which must be zero or one. The enforce_change_rec_flag flag indicates whether record changes should be enforced.

## dbeng_autopack

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

          Name  : pvalue
    Description : returned autopack value

    Returns     : dbeng code
    High Level  : db_get_autopack

This function will obtain the current table autopack value. Upon success, the value will be loaded into the returned autopack value.

## dbeng_set_autopack

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

          Name  : pvalue
    Description : autopack value

    Returns     : dbeng code
    High Level  : db_set_autopack

This function will set a new autopack value for a specific table.

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

    Prototype   : int dbeng_tmp_systable(int *tid)
    Parameters  :
          Name  : tid
    Description : returned tid

    Returns     : dbeng code
    High Level  : None

This function will create a new system table with a unique file name. This function exits with the table open and the table tid placed into the returned tid.

## dbeng_new_systable

    Prototype   : int dbeng_new_systable(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  : None

This function will create a new empty system 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_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. The contents of the path/file name should be given according to the guidelines given in the function dbeng_ll_new_table.

## dbeng_ll_new_table

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

          Name  : tid
    Description : input tid flag and returned tid

          Name  : systable_flag
    Description : system table flag

    Returns     : dbeng code
    High Level  : None

This private function will create a new empty table. If tid is a positive number, the table will be opened and the tid will be returned in same. The path/file name may be in two parts separated by a comma which will indicate the logical table name followed by the physical name, ie:

       test.primary,/hd1/bbuuzzb/tables/test.buz

Do not put spaces before or after the comma. If the two part form is used, an entry in the system catalog will be made (whether or not the catalog flag is on). An entry with the same logical name must not already exist. If the two part form is not used, a physical file name is assumed (do not prefix the physical file name with DBENG_CATALOG_FNAME_IND as in dbeng_open_table.

## dbeng_delete_table

    Prototype   : int dbeng_delete_table(char *fname)
    Parameters  :
          Name  : fname
    Description : table name

    Returns     : dbeng code
    High Level  : db_delete_table

This function will delete a Bbuuzzb table by name. The catalog will be used to obtain the physical file name if the catalog flag is high. Both catalog entry and physical file will be deleted. The table must not be in current use by any other tid.

## dbeng_open_table_list

    Prototype   : int dbeng_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
    High Level  : db_get_open_table_list

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.

## dbeng_exist

    Prototype   : int dbeng_exist(char *tname, int *exist_flag)
    Parameters  :
          Name  : tname
    Description : table name

          Name  : exist_flag
    Description : returned exist flag

    Returns     : dbeng code
    High Level  : db_exist

This function will determine whether a database table exists. Naming convention is the same as for dbeng_open_table. The returned exist flag will be loaded with the exist flag (TRUE=table exists).

## dbeng_clear_table

    Prototype   : int dbeng_clear_table(char *tname)
    Parameters  :
          Name  : tname
    Description : table name

    Returns     : dbeng code
    High Level  : db_clear_table

This function will clear a table of all records by deleting the table and re-creating it. The table must not already be in use. Naming convention is the same as for dbeng_open_table.

## dbeng_nsubfields

    Prototype   : int dbeng_nsubfields(struct dbeng_table *ot,
                                        int fieldno, int *nsubfields)
    Parameters  :
          Name  : ot
    Description : pointer to dbeng_table structure

          Name  : fieldno
    Description : field number

          Name  : nsubfields
    Description : returned number of sub-fields

    Returns     : dbeng code
    High Level  : db_get_nsubfields

This function will get the number of sub-fields in the field number field. Upon success the number of sub-fields in the field will be loaded into the returned number of sub-fields.

## dbeng_subfield_size

    Prototype   : int dbeng_subfield_size(struct dbeng_table *ot, int fnum,
                                          int sfnum, int *sfsize)
    Parameters  :
          Name  : ot
    Description : pointer to dbeng_table structure

          Name  : fnum
    Description : field number

          Name  : sfnum
    Description : sub-field number

          Name  : sfsize
    Description : returned sub-field size

    Returns     : dbeng code
    High Level  : db_get_subfield_size

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

## dbeng_get_subfield

    Prototype   : int dbeng_get_subfield(struct dbeng_table *ot,
                                         char *sfout, int fnum, int sfnum)
    Parameters  :
          Name  : ot
    Description : pointer to dbeng_table structure

          Name  : sfout
    Description : output sub-field

          Name  : fnum
    Description : field number

          Name  : sfnum
    Description : sub-field number

    Returns     : dbeng code
    High Level  : db_get_subfield

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.

## dbeng_put_subfield

    Prototype   : int dbeng_put_subfield(struct dbeng_table *ot,
                                         char *sfin, int fnum, int sfnum)
    Parameters  :
          Name  : ot
    Description : pointer to dbeng_table structure

          Name  : sfin
    Description : input sub-field

          Name  : fnum
    Description : field number

          Name  : sfnum
    Description : sub-field number

    Returns     : dbeng code
    High Level  : db_put_subfield

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

## dbeng_nsubsubfields

    Prototype   : int dbeng_nsubsubfields(struct dbeng_table *ot,
                                        int fnum, int sfnum, int *nsubsubfields)
    Parameters  :
          Name  : ot
    Description : pointer to dbeng_table structure

          Name  : fnum
    Description : field number

          Name  : sfnum
    Description : sub-field number

          Name  : nsubsubfields
    Description : returned number of sub-sub-fields

    Returns     : dbeng code
    High Level  : db_get_nsubsubfields

This function will get the number of sub-sub-fields in the sub-field number sub-field within the field number field. Upon success the number of sub-sub-fields will be loaded into the returned number of sub-sub-fields.

## dbeng_subsubfield_size

    Prototype   : int dbeng_subsubfield_size(struct dbeng_table *ot,
                                             int fnum, int sfnum, int ssfnum,
                                             int *ssfsize)
    Parameters  :
          Name  : ot
    Description : pointer to dbeng_table structure

          Name  : fnum
    Description : field number

          Name  : sfnum
    Description : sub-field number

          Name  : ssfnum
    Description : sub-sub-field number

          Name  : ssfsize
    Description : returned sub-sub-field size

    Returns     : dbeng code
    High Level  : db_get_subsubfield_size

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

## dbeng_get_subsubfield

    Prototype   : int dbeng_get_subsubfield(struct dbeng_table *ot,
                                         char *ssfout, int fnum, int sfnum,
                                         int ssfnum)
    Parameters  :
          Name  : ot
    Description : pointer to dbeng_table structure

          Name  : ssfout
    Description : output sub-sub-field

          Name  : fnum
    Description : field number

          Name  : sfnum
    Description : sub-field number

          Name  : ssfnum
    Description : sub-sub-field number

    Returns     : dbeng code
    High Level  : db_get_subsubfield

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.

## dbeng_put_subsubfield

    Prototype   : int dbeng_put_subsubfield(struct dbeng_table *ot,
                                         char *ssfin, int fnum, int sfnum,
                                         int ssfnum)
    Parameters  :
          Name  : ot
    Description : pointer to dbeng_table structure

          Name  : ssfin
    Description : input sub-sub-field

          Name  : fnum
    Description : field number

          Name  : sfnum
    Description : sub-field number

          Name  : ssfnum
    Description : sub-sub-field number

    Returns     : dbeng code
    High Level  : db_put_subsubfield

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

## dbeng_ll_open

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

    Returns     : dbeng code
    High Level  : none

This function will open the file associated with the pointer to dbeng_table structure.

## dbeng_ll_close

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

    Returns     : dbeng code
    High Level  : none

This function will close the file associated with the pointer to dbeng_table structure.

## dbeng_is_systable

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

          Name  : flag
    Description : returned system table flag

    Returns     : dbeng code
    High Level  : none

This function will obtain the current value of is_systable for the specified table.

## dbeng_copy_table

    Prototype   : int dbeng_copy_table(struct dbeng_table *src,
                                       struct dbeng_table *dest)
    Parameters  :
          Name  : src
    Description : source table

          Name  : dest
    Description : destination table

    Returns     : dbeng code
    High Level  : db_copy_table

This function will copy a table from the source table to the destination table. No regard is given to the existing contents of the destination table (if any).

## dbeng_record_header

    Prototype   : static int dbeng_record_header(struct dbeng_table *ot,
                                                 int *len, char *status)
    Parameters  :
          Name  : ot
    Description : pointer to dbeng_table structure

          Name  : len
    Description : returned record length

          Name  : status
    Description : returned record status (A for active, D for deleted)

    Returns     : dbeng code
    High Level  : none

This private function will read and verify the record header which is assumed to start at the current file position. Upon success, the record length is returned in the returned record length and the record status is returned in the returned record status.

## dbeng_put_which_field

    Prototype   : static int dbeng_put_which_field(struct dbeng_table *ot,
                                                   int fnum, int *new_fnum)
    Parameters  :
          Name  : ot
    Description : pointer to dbeng_table structure

          Name  : fnum
    Description : input field number

          Name  : new_fnum
    Description : output field number

    Returns     : dbeng code
    High Level  : none

This private function will determine which field to put data into. A positive integer is assumed to be the absolute field number. A zero indicates to append a new field to the record. Function returns the field number loaded into the output field number upon success.

## dbeng_put_which_subfield

    Prototype   : static int dbeng_put_which_subfield(struct dbeng_table *ot,
                                                      int fnum, int sfnum,
                                                      int *new_fnum, int *new_sfnum)
    Parameters  :
          Name  : ot
    Description : pointer to dbeng_table structure

          Name  : fnum
    Description : input field number

          Name  : sfnum
    Description : input subfield number

          Name  : new_fnum
    Description : output field number

          Name  : new_sfnum
    Description : output subfield number

    Returns     : dbeng code
    High Level  : none

This private function will determine which field and subfield to put data into. A positive integer is assumed to be the absolute field/subfield number. A zero indicates to append a new field/subfield to the record. Function returns the field number loaded into the output field number and the new subfield number loaded into the output subfield number upon success.

## dbeng_put_which_subsubfield

    Prototype   : static int dbeng_put_which_subsubfield(struct dbeng_table *ot,
                                                         int fnum, int sfnum,
                                                         int ssfnum, int *new_fnum,
                                                         int *new_sfnum, int *new_ssfnum)
    Parameters  :
          Name  : ot
    Description : pointer to dbeng_table structure

          Name  : fnum
    Description : input field number

          Name  : sfnum
    Description : input subfield number

          Name  : ssfnum
    Description : input subsubfield number

          Name  : new_fnum
    Description : output field number

          Name  : new_sfnum
    Description : output subfield number

          Name  : new_ssfnum
    Description : output subsubfield number

    Returns     : dbeng code
    High Level  : none

This private function will determine which field, subfield and subsubfield to put data into. A positive integer is assumed to be the absolute field/subfield/subsubfield number. A zero indicates to append a new field/subfield/subsubfield to the record. Function returns the field number loaded into the output field number, the new subfield number loaded into the output subfield number and the new subsubfield number loaded into the output subsubfield number upon success.

## dbeng_ll_copy_table

    Prototype   : static int dbeng_ll_copy_table(struct dbeng_table *src,
                                                 struct dbeng_table *dest)
    Parameters  :
          Name  : src
    Description : source table

          Name  : dest
    Description : destination table

    Returns     : dbeng code
    High Level  : none

This private function will copy a table from source table to destination table. Both tables are assumed to be open. No regard is given to existing contents of destination table. Records are copied in accordance with the current value of the source table process_deleted flag. Function exits with the tables remaining open.

## dbeng_delete_field

    Prototype   : int dbeng_delete_field(struct dbeng_table *ot, int fnum)
    Parameters  :
          Name  : ot
    Description : source table

          Name  : fnum
    Description : field number

    Returns     : dbeng code
    High Level  : db_delete_field

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.

## dbeng_delete_subfield

    Prototype   : int dbeng_delete_subfield(struct dbeng_table *ot,
                                            int fnum, int sfnum)
    Parameters  :
          Name  : ot
    Description : source table

          Name  : fnum
    Description : field number

          Name  : sfnum
    Description : subfield number

    Returns     : dbeng code
    High Level  : db_delete_subfield

This function will completely remove the subfield number subfield from the field number field within the current record.

## dbeng_delete_subsubfield

    Prototype   : int dbeng_delete_subsubfield(struct dbeng_table *ot,
                                               int fnum, int sfnum, int ssfnum)
    Parameters  :
          Name  : ot
    Description : source table

          Name  : fnum
    Description : field number

          Name  : sfnum
    Description : subfield number

          Name  : ssfnum
    Description : subsubfield number

    Returns     : dbeng code
    High Level  : db_delete_subsubfield

This function will completely remove the subsubfield number subsubfield from the subfield number subfield in the field number field within the current record.

## dbeng_set_record_count

    Prototype   : int dbeng_set_record_count(struct dbeng_table *ot)
    Parameters  :
          Name  : ot
    Description : source table

    Returns     : dbeng code
    High Level  : None

This function will check all tables in use and adjust the active record count and deleted record count of each matching table in use to the source table.

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

- the dbeng_table pointer is not null
- the record buffer pointer is not null
- the record buffer has a non-zero length

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_table_in_use

    Prototype   : static int dbeng_table_in_use(char *fname)
    Parameters  :
          Name  : fname
    Description : path/file name

    Returns     : TRUE if table is in use, FALSE otherwise
    High Level  : None

This private function will determine whether a table is in use by its physical file name.

## 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 current log destination. 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-2006 Future Lab, Last Updated Jun 30, 2006