Tcl Database Engine

This Tcl module is the Bbuuzzb database engine and has the file name dbeng.tcl. All table,record/field access is performed by procedures in this module.

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 an array called dbeng_table. Each time a table is opened, a unique positive integer is generated called a tid. Both the single user and client/server API's use tids to access table data.

This module contains two types of procedures:

- db_ - procedures prefixed with db_ are user callable
- dbeng_ - procedures prefixed with dbeng_ are internal

The internal procedures contained in this module should only be called by other procedures in this module. When writing applications that use this API, make your calls to db_ procedures only.

Here is a list of procedures in this module:

- db_initialize
- db_end
- db_open
- db_close
- db_next
- db_get_rec_num
- db_get_pos
- db_set_pos
- db_get_change_rec_flag
- db_set_change_rec_flag
- db_get_delete_flag
- db_set_delete_flag
- db_get_enf_change_rec_flag
- db_set_enf_change_rec_flag
- db_get_autopack
- db_set_autopack
- db_get_is_table_locked
- db_set_is_table_locked
- db_top
- db_get_rec_count
- db_goto
- db_count
- db_pack
- db_copy_table
- db_new
- db_get_rec
- db_get_rec_size
- db_get_field_size
- db_get_subfield_size
- db_get_subsubfield_size
- db_write
- db_delete
- db_get_nfields
- db_get_nsubfields
- db_get_nsubsubfields
- db_get_field
- db_get_subfield
- db_get_subsubfield
- db_put_field
- db_put_subfield
- db_put_subsubfield
- db_find
- db_find_field
- db_find_part
- db_find_field_part
- db_new_table
- db_delete_table
- db_get_open_table_list
- db_exist
- db_clear_table
- db_delete_field
- db_delete_subfield
- db_delete_subsubfield
- dbeng_is_systable
- dbeng_tmp_systable
- dbeng_new_systable
- dbeng_put_which_field
- dbeng_put_which_subfield
- dbeng_put_which_subsubfield
- dbeng_ll_copy_table
- dbeng_open_systable
- dbeng_ll_open_table
- dbeng_record_header
- dbeng_write_new_recd
- dbeng_write_string_recd
- dbeng_rewrite_recd
- dbeng_is_active_rec
- dbeng_get_tid
- dbeng_set_record_count
- dbeng_lock_table
- dbeng_unlock_table
- dbeng_table_in_use
- dbeng_atid_lookup
- dbeng_ll_new_table
- dbeng_ll_open
- dbeng_ll_close
- dbeng_compare_field
- dbeng_unset_table

# Module Dependencies

This module is part of the single user database access and requires the following modules:

- fio.tcl
- parse.tcl
- logger.tcl
- dbiocode.tcl
- dbengcfg.tcl
- dbengcat.tcl
- dbengsrt.tcl

There are a number of good example applications that use this engine including:

- database command line interpreter
- database stress

# Module Definition Files

The following modules are required along with this module:

- stdhead.tcl
- dbmess.tcl

# Module Procedures

## db_initialize

    Declaration   : proc db_initialize {}

    Returns       : dbeng code

This procedure will initialize the Bbuuzzb database engine by reading the configuration file.

## db_end

    Declaration   : proc db_end {}

    Returns       : dbeng code

This procedure will shutdown the database engine by closing all the tables in use.

## db_open

    Declaration   : proc db_open {fname tid}
    Parameters    :
          Name    : fname
          Type    : string
    Description   : path/file name

          Name    : tid
          Type    : positive integer
    Description   : returned tid

    Returns       : dbeng code

This procedure will open a table. The 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.

## db_close

    Declaration   : proc db_close {tid}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : table tid

    Returns     : dbeng code

This procedure will close a table.

## db_next

    Declaration   : proc db_next {tid}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : table tid

    Returns     : dbeng code

This procedure will obtain the next record in the table along with advancing the file position to the beginning of the following record. The record contents will be loaded in the tid's dbeng_table array rec element. Use the procedure db_get_rec to obtain the record contents.

## db_get_rec_num

    Declaration   : proc db_get_rec_num {tid rec_num}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

          Name    : rec_num
          Type    : positive integer
    Description   : returned record number

    Returns       : dbeng code

This procedure will get the record number for the specified tid. The record number is actually retrieved from the dbeng_table array member record_number. Upon success the record number will be loaded into the returned record number.

## db_get_pos

    Declaration   : proc db_get_pos {tid pos}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

          Name    : pos
          Type    : integer
    Description   : returned record position

    Returns       : dbeng code

This procedure will get the file position/offset for the current record and the specified tid. The file position is actually retrieved from the dbeng_table array 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

    Declaration   : proc db_set_pos {tid pos}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

          Name    : pos
          Type    : integer
    Description   : channel position/offset

    Returns       : dbeng code

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

## db_get_change_rec_flag

    Declaration   : proc db_get_change_rec_flag {tid flag}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

          Name    : flag
          Type    : boolean flag
    Description   : returned change record flag

    Returns       : dbeng code

This procedure 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

    Declaration   : proc db_set_change_rec_flag {tid flag}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

          Name    : flag
          Type    : boolean flag
    Description   : change record flag

    Returns       : dbeng code

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

## db_get_delete_flag

    Declaration   : proc db_get_delete_flag {tid flag_value}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

          Name    : flag_value
          Type    : boolean flag
    Description   : returned flag value

    Returns       : dbeng code

This procedure 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

    Declaration   : proc db_set_delete_flag {tid flag_value}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

          Name    : flag_value
          Type    : boolean flag
    Description   : flag value

    Returns       : dbeng code

This procedure 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_get_enf_change_rec_flag

    Declaration   : proc db_get_enf_change_rec_flag {tid flag}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

          Name    : flag
          Type    : boolean flag
    Description   : returned enforce change record flag

    Returns       : dbeng code

This procedure 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

    Declaration   : proc db_set_enf_change_rec_flag {tid flag}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

          Name    : flag
          Type    : boolean flag
    Description   : enforce change record flag

    Returns       : dbeng code

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

## db_get_autopack

    Declaration   : proc db_get_autopack {tid pvalue}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

          Name    : pvalue
          Type    : boolean flag
    Description   : returned autopack value

    Returns       : dbeng code

This procedure 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

    Declaration   : proc db_set_autopack {tid pvalue}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

          Name    : pvalue
          Type    : boolean flag
    Description   : autopack value

    Returns       : dbeng code

This procedure 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_is_table_locked

    Declaration   : proc db_get_is_table_locked {tid flag}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

          Name    : flag
          Type    : boolean flag
    Description   : returned table locked flag

    Returns       : dbeng code

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

## db_set_is_table_locked

    Declaration   : proc db_set_is_table_locked {tid flag}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

          Name    : flag
          Type    : boolean flag
    Description   : is table locked flag

    Returns       : dbeng code

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

## db_top

    Declaration   : proc db_top {int tid}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

    Returns       : dbeng code

This procedure will move the channel position to the top of the table before the first record in the table.

## db_get_rec_count

    Declaration   : proc db_get_rec_count {tid acount dcount}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

          Name    : acount
          Type    : integer
    Description   : returned active record count

          Name    : dcount
          Type    : integer
    Description   : returned deleted record count

    Returns       : dbeng code

This procedure 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 procedure does not physically count the records in the table (as the procedure db_count does).

## db_goto

    Declaration   : proc db_goto {tid rec_num}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

          Name    : rec_num
          Type    : positive integer
    Description   : record number

    Returns       : dbeng code

This procedure 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

    Declaration   : proc db_count {tid acount dcount}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

          Name    : acount
          Type    : integer
    Description   : returned active record count

          Name    : dcount
          Type    : integer
    Description   : returned deleted record count

    Returns       : dbeng code

This procedure 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 is 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_pack

    Declaration   : proc db_pack {tid}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

    Returns       : dbeng code

This procedure 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_copy_table

    Declaration   : proc db_copy_table {src_tid dest_tid}
    Parameters    :
          Name    : src_tid
          Type    : positive integer
    Description   : source tid

          Name    : dest_tid
          Type    : positive integer
    Description   : destination tid

    Returns       : dbeng code

This procedure will copy a table from source tid to destination tid. No regard is given to whether the destination tid table already contains data.

## db_new

    Declaration   : proc db_new {tid}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

    Returns       : dbeng code

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

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

This procedure should be called before loading a new record.

## db_get_rec

    Declaration   : proc db_get_rec {tid rec_out}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

          Name    : rec_out
          Type    : string
    Description   : output record

    Returns       : dbeng code

This procedure will load the current record into the output record. The channel position will not be advanced.

## db_get_rec_size

    Declaration   : proc db_get_rec_size {tid rec_size}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

          Name    : rec_size
          Type    : integer
    Description   : output record size

    Returns       : dbeng code

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

## db_get_field_size

    Declaration   : proc db_get_field_size {tid fnum field_size}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

          Name    : fnum
          Type    : positive integer
    Description   : field number

          Name    : field_size
          Type    : integer
    Description   : output field size

    Returns       : dbeng code

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

## db_get_subfield_size

    Declaration   : proc db_get_subfield_size {tid fnum sfnum sfsize}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

          Name    : fnum
          Type    : positive integer
    Description   : field number

          Name    : sfnum
          Type    : positive integer
    Description   : subfield number

          Name    : sfsize
          Type    : integer
    Description   : output subfield size

    Returns       : dbeng code

This procedure will load the size (in bytes) of the subfield number into the output subfield size.

## db_get_subsubfield_size

    Declaration   : proc db_get_subsubfield_size {tid fnum sfnum ssfnum ssfsize}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

          Name    : fnum
          Type    : positive integer
    Description   : field number

          Name    : sfnum
          Type    : positive integer
    Description   : subfield number

          Name    : ssfnum
          Type    : positive integer
    Description   : subsubfield number

          Name    : ssfsize
          Type    : integer
    Description   : output subsubfield size

    Returns       : dbeng code

This procedure will load the size (in bytes) of the subsubfield number into the output subsubfield size.

## db_write

    Declaration   : proc db_write {tid}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

    Returns       : dbeng code

This procedure 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

    Declaration   : proc db_delete {tid}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

    Returns       : dbeng code

This procedure 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 procedure is called, the table will be re-written and the records marked for deletion are removed.

## db_get_nfields

    Declaration   : proc db_get_nfields {tid nfields}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

          Name    : nfields
          Type    : integer
    Description   : returned number of fields

    Returns       : dbeng code

This procedure 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_nsubfields

    Declaration   : proc db_get_nsubfields {tid fnum nsubfields)
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

          Name    : fnum
          Type    : positive integer
    Description   : field number

          Name    : nsubfields
          Type    : integer
    Description   : returned number of subfields

    Returns       : dbeng code

This procedure will get the number of subfields in the field number for the tid. Upon success the number of subfields will be loaded into the returned number of subfields.

## db_get_nsubsubfields

    Declaration   : proc db_get_nsubsubfields {tid fnum sfnum nsubsubfields}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

          Name    : fnum
          Type    : positive integer
    Description   : field number

          Name    : sfnum
          Type    : positive integer
    Description   : subfield number

          Name    : nsubsubfields
          Type    : integer
    Description   : returned number of subsubfields

    Returns       : dbeng code

This procedure will get the number of subsubfields in the subfield number within the field number for the tid. Upon success the number of subsubfields will be loaded into the returned number of subsubfields.

## db_get_field

    Declaration   : proc db_get_field {tid fnum field_out}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

          Name    : fnum
          Type    : positive integer
    Description   : field number

          Name    : field_out
          Type    : string
    Description   : output field

    Returns       : dbeng code

This procedure will load the contents of the field field number into the output field.

## db_get_subfield

    Declaration   : proc db_get_subfield {tid fnum sfnum sfout}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

          Name    : fnum
          Type    : positive integer
    Description   : field number

          Name    : sfnum
          Type    : positive integer
    Description   : subfield number

          Name    : sfout
          Type    : string
    Description   : output subfield

    Returns       : dbeng code

This procedure will load the contents of the subfield subfield number into the output subfield.

## db_get_subsubfield

    Declaration   : proc db_get_subsubfield {tid fnum sfnum ssfnum ssfout}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

          Name    : fnum
          Type    : positive integer
    Description   : field number

          Name    : sfnum
          Type    : positive integer
    Description   : subfield number

          Name    : ssfnum
          Type    : positive integer
    Description   : subsubfield number

          Name    : ssfout
          Type    : string
    Description   : output subsubfield

    Returns       : dbeng code

This procedure will load the contents of the subsubfield subsubfield number into the output subsubfield.

## db_put_field

    Declaration   : proc db_put_field {tid field_num field_data}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

          Name    : field_num
          Type    : positive integer
    Description   : field number

          Name    : field_data
          Type    : string
    Description   : field data string

    Returns       : dbeng code

This procedure 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_put_subfield

    Declaration   : proc db_put_subfield {tid fnum sfnum sfdata}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

          Name    : fnum
          Type    : positive integer
    Description   : field number

          Name    : sfnum
          Type    : positive integer
    Description   : subfield number

          Name    : sfdata
          Type    : string
    Description   : subfield data

    Returns       : dbeng code

This procedure will put the subfield data into the record buffer at the indicated field number and subfield number. If the field number or subfield number does not exist, the record buffer will be extended out to the required subfield.

## db_put_subsubfield

    Declaration   : proc db_put_subsubfield {tid fnum sfnum ssfnum ssfdata}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

          Name    : fnum
          Type    : positive integer
    Description   : field number

          Name    : sfnum
          Type    : positive integer
    Description   : subfield number

          Name    : ssfnum
          Type    : positive integer
    Description   : subsubfield number

          Name    : ssfdata
          Type    : string
    Description   : subsubfield data

    Returns       : dbeng code

This procedure will put the subsubfield data into the record buffer at the indicated field number, subfield number and subsubfield number. If the field number, subfield number or subsubfield number does not exist, the record buffer will be extended out to the required subsubfield.

## db_find

    Declaration   : proc db_find {tid cs_flag fdata field_num}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

          Name    : cs_flag
          Type    : boolean flag
    Description   : case flag

          Name    : fdata
          Type    : string
    Description   : find data

          Name    : field_num
          Type    : positive integer
    Description   : returned field number

    Returns       : dbeng code

This procedure 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

    Declaration   : proc db_find_field {tid cs_flag fdata field_num}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

          Name    : cs_flag
          Type    : boolean flag
    Description   : case flag

          Name    : fdata
          Type    : string
    Description   : find data

          Name    : field_num
          Type    : positive integer
    Description   : field number

    Returns       : dbeng code

This procedure 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

    Declaration   : proc db_find_part {tid cs_flag fdata field_num}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

          Name    : cs_flag
          Type    : boolean flag
    Description   : case flag

          Name    : fdata
          Type    : string
    Description   : find data

          Name    : field_num
          Type    : positive integer
    Description   : returned field number

    Returns       : dbeng code

This procedure 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

    Declaration   : proc db_find_field_part {tid cs_flag fdata field_num}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

          Name    : cs_flag
          Type    : boolean flag
    Description   : case flag

          Name    : fdata
          Type    : string
    Description   : find data

          Name    : field_num
          Type    : positive integer
    Description   : field number

    Returns       : dbeng code

This procedure 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_new_table

    Declaration   : proc db_new_table {fname tid}
    Parameters    :
          Name    : fname
          Type    : string
    Description   : path/file name

          Name    : tid
          Type    : integer
    Description   : input tid flag and output tid

    Returns       : dbeng code

This procedure 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 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 catalog will be made (whether or not the catalog flag is on). An entry will 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 db_open).

## db_delete_table

    Declaration   : proc db_delete_table {tname}
    Parameters    :
          Name    : tname
          Type    : string
    Description   : table name

    Returns       : dbeng code

This procedure 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_get_open_table_list

    Declaration   : proc db_get_open_table_list {pat list_out}
    Parameters    :
          Name    : pat
          Type    : string
    Description   : match pattern

          Name    : list_out
          Type    : string
    Description   : returned open table list

    Returns       : dbeng code

This procedure will return a list of all open tables in the returned open table list. 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 Tcl string match command. If the match pattern is empty, all tables in use will be returned.

## db_exist

    Declaration   : proc db_exist {tname exist_flag}
    Parameters    :
          Name    : tname
          Type    : string
    Description   : table name

          Name    : exist_flag
          Type    : boolean flag
    Description   : returned exist flag

    Returns       : dbeng code

This procedure will determine whether a database table exists. table name convention is the same as for db_open.

## db_clear_table

    Declaration   : proc db_clear_table {tname}
    Parameters    :
          Name    : tname
          Type    : string
    Description   : table name

    Returns       : dbeng code

This procedure 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_delete_field

    Declaration   : proc db_delete_field (tid fnum}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : table tid

          Name    : fnum
          Type    : positive integer
    Description   : field number

    Returns       : dbeng code

This procedure 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

    Declaration   : proc db_delete_subfield {tid fnum sfnum}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : table tid

          Name    : fnum
          Type    : positive integer
    Description   : field number

          Name    : sfnum
          Type    : positive integer
    Description   : subfield number

    Returns       : dbeng code

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

## db_delete_subsubfield

    Declaration   : proc db_delete_subsubfield {tid fnum sfnum ssfnum}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : table tid

          Name    : fnum
          Type    : positive integer
    Description   : field number

          Name    : sfnum
          Type    : positive integer
    Description   : subfield number

          Name    : ssfnum
          Type    : positive integer
    Description   : subsubfield number

    Returns       : dbeng code

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

## dbeng_is_systable

    Declaration   : proc dbeng_is_systable {tid flag}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : table tid

          Name    : flag
          Type    : boolean flag
    Description   : returned system table flag

    Returns       : dbeng code

This procedure will obtain the current value of is_systable dbeng_table array element for the specified table.

## dbeng_tmp_systable

    Declaration   : proc dbeng_tmp_systable {tid}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : returned tid

    Returns       : dbeng code

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

## dbeng_new_systable

    Declaration   : proc dbeng_new_systable {fname tid}
    Parameters    :
          Name    : fname
          Type    : string
    Description   : path/file name

          Name    : tid
          Type    : integer
    Description   : input tid flag and returned tid

    Returns       : dbeng code

This procedure 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_put_which_field

    Declaration   : proc dbeng_put_which_field {tid fnum new_fnum}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : table tid

          Name    : fnum
          Type    : integer
    Description   : input field number

          Name    : new_fnum
          Type    : positive integer
    Description   : output field number

    Returns       : dbeng code
    High Level  : none

This procedure 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. Procedure returns the field number loaded into the output field number upon success.

## dbeng_put_which_subfield

    Declaration   : proc dbeng_put_which_subfield {tid fnum sfnum new_fnum new_sfnum}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : table tid

          Name    : fnum
          Type    : integer
    Description   : input field number

          Name    : sfnum
          Type    : integer
    Description   : input subfield number

          Name    : new_fnum
          Type    : positive integer
    Description   : output field number

          Name    : new_sfnum
          Type    : positive integer
    Description   : output subfield number

    Returns       : dbeng code

This procedure 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. Procedure 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

    Declaration   : proc dbeng_put_which_subsubfield {tid fnum sfnum ssfnum new_fnum new_sfnum new_ssfnum}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : table tid

          Name    : fnum
          Type    : integer
    Description   : input field number

          Name    : sfnum
          Type    : integer
    Description   : input subfield number

          Name    : ssfnum
          Type    : integer
    Description   : input subsubfield number

          Name    : new_fnum
          Type    : positive integer
    Description   : output field number

          Name    : new_sfnum
          Type    : positive integer
    Description   : output subfield number

          Name    : new_ssfnum
          Type    : positive integer
    Description   : output subsubfield number

    Returns       : dbeng code

This procedure 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. Procedure 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

    Declaration   : proc dbeng_ll_copy_table {src dest}
    Parameters    :
          Name    : src
          Type    : positive integer
    Description   : source table tid

          Name    : dest
          Type    : positive integer
    Description   : destination table tid

    Returns       : dbeng code
    High Level  : none

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

## dbeng_open_systable

    Declaration   : proc dbeng_open_systable {filename tid}
    Parameters    :
          Name    : filename
          Type    : string
    Description   : path/file name

          Name    : tid
          Type    : positive integer
    Description   : returned tid

    Returns       : dbeng code

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

## dbeng_ll_open_table

    Declaration   : proc dbeng_ll_open_table {filename tid systable_flag}
    Parameters    :
          Name    : filename
          Type    : string
    Description   : path/file name

          Name    : tid
          Type    : positive integer
    Description   : returned tid

          Name    : systable_flag
          Type    : boolean flag
    Description   : system table flag

    Returns       : dbeng code

This procedure 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_record_header

    Declaration   : proc dbeng_record_header {tid len status}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : table tid

          Name    : len
          Type    : positive integer
    Description   : returned record length

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

    Returns       : dbeng code

This procedure will read and verify the record header which is assumed to start at the current channel 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_write_new_recd

    Declaration   : proc dbeng_write_new_recd {tid}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : table tid

    Returns       : dbeng code

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

## dbeng_write_string_recd

    Declaration   : proc dbeng_write_string_recd {tid rec}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : table tid

          Name    : rec
          Type    : string
    Description   : record string

    Returns       : dbeng code

This procedure will write a new record in the table. Instead of the record being written from the record buffer (rec) (as with db_write), the record will be written from the record string. No regard is given to the fact that the record might already exist. This function is used internally by the engine to copy records.

## dbeng_rewrite_recd

    Declaration   : proc dbeng_rewrite_recd {tid}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : table tid

    Returns       : dbeng code

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

## dbeng_is_active_rec

    Declaration   : proc dbeng_is_active_rec {tid}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : table tid

    Returns       : dbeng code

This procedure will determine whether there is an active record for the specified table tid. An active record is assumed when all of the following conditions are meet:

- the dbeng_table array element exists
- the record buffer (rec) is not empty

This procedure should only be called internally by the Bbuuzzb database engine.

## dbeng_get_tid

    Declaration   : proc dbeng_get_tid {}

    Returns       : tid

This procedure will generate the next tid to be used. The tid is then checked against all tids in use. This procedure is used internally by the Bbuuzzb database engine and should not be called outside of this module.

## dbeng_set_record_count

    Declaration   : proc dbeng_set_record_count {tid}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : table tid

    Returns       : dbeng code

This procedure 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_lock_table

    Declaration   : proc dbeng_lock_table {tid}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : table tid

    Returns       : dbeng code

This procedure will lock a table. Every occurrence of the table will be locked. This procedure is used internally by the engine and should not be called outside of this module.

## dbeng_unlock_table

    Declaration   : proc dbeng_unlock_table {tid}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : table tid

    Returns       : dbeng code

This procedure will unlock a table. Every occurrence of the table will be unlocked. This procedure is used internally by the engine and should not be called outside of this module.

## dbeng_table_in_use

    Declaration   : proc dbeng_table_in_use {fname}
    Parameters    :
          Name    : fname
          Type    : string
    Description   : path/file name

    Returns       : 1 if table is in use, 0 otherwise

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

## dbeng_atid_lookup

    Declaration   : proc dbeng_atid_lookup {int tid}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

    Returns       : 1 if table is present, 0 otherwise

This procedure will perform a lookup based on a given tid This procedure is used internally by the Bbuuzzb database engine and should not be called outside of this module.

## dbeng_ll_new_table

    Declaration   : proc dbeng_ll_new_table {fname tid systable_flag}
    Parameters    :
          Name    : fname
          Type    : string
    Description   : path/file name

          Name    : tid
          Type    : integer
    Description   : input tid flag and returned tid

          Name    : systable_flag
          Type    : boolean flag
    Description   : system table flag

    Returns       : dbeng code

This procedure 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 db_open.

## dbeng_ll_open

    Declaration   : proc dbeng_ll_open {tid}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

    Returns       : dbeng code

This procedure will open the file associated with the tid.

## dbeng_ll_close

    Declaration   : proc dbeng_ll_close {tid}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

    Returns       : dbeng code

This procedure will close the file associated with the tid.

## dbeng_compare_field

    Declaration   : proc dbeng_compare_field {field_data find_str cs_flag}
    Parameters    :
          Name    : field_data
          Type    : string
    Description   : field data

          Name    : find_str
          Type    : string
    Description   : find string

          Name    : cs_flag
          Type    : boolean flag
    Description   : case flag

    Returns       : result of comparison (0=equal)

This procedure will compare the field data to the find string according to the case flag. This procedure is unique to this Tcl version.

## dbeng_unset_table

    Declaration   : proc dbeng_unset_table {tid}
    Parameters    :
          Name    : tid
          Type    : positive integer
    Description   : tid

This procedure will unset all dbeng_table array elements for a single tid. This procedure is unique to this Tcl version.

Goto Top | Tcl Database Engine and API's | Tcl Applications | Tcl Software Overview | Tcl Library Overview
| Future Lab Home | Contact Webmaster | Feedback

Copyright © 2006 Future Lab, Last Updated Jul 01, 2006