db/dbm Database Applications for Bbuuzzb

The db (C language version) or db (Tcl version) and dbm database command line applications take interactive commands and send requests to the Bbuuzzb database engine/server. db is a stand-alone GPL application and dbm is the same GPL application for the client/server Bbuuzzb database server.

Each command request starts with a command keyword followed by a series of parameters. The command keyword must be complete (no abbreviations are allowed) and can be given in upper, lower or mixed case. All parameters are space delimited command words (C language version) or command_words (Tcl version).

All parameters containing spaces must be quoted with either single or double quotes but they must match. These command line applications use the single quote to pass parameters to the Bbuuzzb database engine/server so the use of single quotes within a parameter is not allowed. Unless specifically mentioned, all commands are valid for the single-user db and the multi-user dbm applications.

Here is a list of the database commands:

- off
- open
- close
- next
- top
- get.rec
- get.field
- goto
- count
- put.field
- write
- delete
- get.delete.flag
- set.delete.flag
- get.nfields
- get.rec.size
- get.field.size
- get.rec.num
- get.pos
- set.pos
- get.change.rec.flag
- set.change.rec.flag
- pack
- new
- find
- find.field
- find.part
- find.field.part
- get.rec.count
- get.enf.change.rec.flag
- set.enf.change.rec.flag
- get.is.table.locked
- set.is.table.locked
- new.table
- config.get.tmp.path
- config.get.log
- config.get.session
- config.get.catalog
- config.get.log.flag
- config.get.session.flag
- config.get.catalog.flag
- config.get.replicate.flag
- config.get.version
- config.set.tmp.path
- config.set.log
- config.set.session
- config.set.catalog
- config.set.log.flag
- config.set.session.flag
- config.set.catalog.flag
- config.set.replicate.flag
- version
- get.open.table.list
- get.nsubfields
- get.subfield.size
- get.subfield
- put.subfield
- get.nsubsubfields
- get.subsubfield.size
- get.subsubfield
- put.subsubfield
- replicate.update
- get.catalog.list
- sort
- get.sort.mem
- set.sort.mem
- get.sort.open.bin
- set.sort.open.bin
- delete.field
- delete.subfield
- delete.subsubfield
- trans.num
- connect.num

# off

    Syntax: off

This command will exit the db or dbm application. Note that no check is currently made for open tables. Make sure you close all tables that you have opened before exiting the application.

# open

    db syntax : open file_name
    dbm syntax: open table_name|%file_name

This command will open a Bbuuzzb table. When using the db or dbm application and the catalog is not in use, tables must be opened by also using the physical OS file name. When the catalog is active, tables are opened by default using the logical table name instead of the physical OS file name. If you need to open a table using the physical OS file name when the catalog is active, you must prefix the file name with a percent sign (%).

Once the table is successfully opened, the tid will be displayed on the screen. Most db/dbm commands require the tid as the first parameter. The table file pointer will be positioned at the top of the table. The will be no current record and the enforce change record flag will not be on.

# close

    Syntax: close tid

This command will close a table. The table must have already be opened and the tid must be valid. If the current record has changed and record changes are enforced,the table will not close. The current record must be written or the enforce change record flag must be lowered.

# next

    Syntax: next tid

This command will advance the table file pointer to the next record in the table. The record contents will be loaded into the record buffer. If the file pointer is already at the end of the table, eof will be returned. If the current record has changed and record changes are enforced, the file pointer will not be advanced. The current record must be written or the enforce change record flag must be lowered.

# top

    Syntax: top tid

This command will move the table file pointer to the top of the table. There will be no current record. If the current record has changed and record changes are enforced, the file pointer will not be move to the top of the table. The current record must be written or the enforce change record flag must be lowered.

# get.rec

    Syntax: get.rec tid

This command will get and display the contents of the current record.

# get.field

    Syntax: get.field tid field_number

This command will get and display the contents of the specific field_number.

# goto

    Syntax: goto tid record_number

This command will move the table file pointer to the specific record_number from the top of the table. The record_number is a sequential count from top of the table. The contents of the specific record will be loaded into the record buffer. If the current record has changed and record changes are enforced, the file pointer will not be moved. The current record must be written or the enforce change record flag must be lowered.

# count

    Syntax: count tid

This command will count records in the table. If the current record has changed and record changes are enforced, the count will not take place. The current record must be written or the enforce change record flag must be lowered. The number of active records and the number of records marked for deletion will be displayed on the screen.

# put.field

    Syntax: put.field tid field_number field_data

This command will put field_data into the specified field_number of the current record. There must be a current record or you must have declared a new record. If field_data contains spaces, you must quote the string.

# write

    Syntax: write tid

This command will write a new record or re-write an existing record. An existing record will be re-written even if has not been changed. A new record must contain data. Empty records are not allowed to be written.

# delete

    Syntax: delete tid

This command will mark the current record for deletion. The record will not be physically deleted until a pack or sort is performed. If the current record has changed and record changes are enforced, the delete will not take place. The current record must be written or the enforce change record flag must be lowered.

# get.delete.flag

    Syntax: get.delete.flag tid

This command will get the current value of the process deleted flag. The Bbuuzzb database engine uses this flag to indicate whether records marked for deletion should be included in record processing.

# set.delete.flag

    Syntax: set.delete.flag tid flag_value

This command will set the process deleted flag to the flag_value which must be zero or one. The Bbuuzzb database engine uses this flag to indicate whether records marked for deletion should be included in record processing.

# get.nfields

    Syntax: get.nfields tid

This command will get and display the number of fields in the current record. There must be a current record to report on.

# get.rec.size

    Syntax: get.rec.size tid

This command will get and display the size (in bytes) of the current record. There must be a current record to report on.

# get.field.size

    Syntax: get.field.size tid field_number

This command will get and display the size (in bytes) of the field field_number within the current record. Zero bytes is a valid field size. There must be a current record to report on.

# get.rec.num

    Syntax: get.rec.num tid

This command will get and display the current record number. Record numbers are sequential from the top of the table.

# get.pos

    Syntax: get.pos tid

This command will get and display the starting file position of the current record within the table. The file position starts from zero which is the top of the table. Note that this command does not report the current file position.

# set.pos

    Syntax: set.pos tid file_position

This command will set the file pointer to the file_position which must be a numeric byte offset from the beginning of the table (which is offset zero). The file_position must be the start of a record. An error will be flagged (upon the next read record) if you attempt to position the file pointer to anywhere except the start of a record. If the current record has changed and record changes are enforced, the set position will not take place. The current record must be written or the enforce change record flag must be lowered.

# get.change.rec.flag

    Syntax: get.change.rec.flag tid

This command will get and display the current value of the table change record flag. This flag is automatically maintained by the Bbuuzzb database engine to indicate when a record has been changed/updated. This flag may be manually updated with the command set.change.rec.flag.

# set.change.rec.flag

    Syntax: set.change.rec.flag tid flag_value

This command will set the change record flag to the flag_value which must be zero or one.

# pack

    Syntax: pack tid

This command will pack the table by physically removing all records marked for deletion. The table is packed by copying all active records to a temporary table (built in the directory specified by the temporary path configuration parameter) and then deleting the original table and renaming the temporary table back to the original file name. If the current record has changed and record changes are enforced, the pack will not take place. The current record must be written or the enforce change record flag must be lowered.

# new

    Syntax: new tid

This command will set up the table for a new record. This command must be issued just prior to building a new table record. When this command is executed, the Bbuuzzb database engine will move the record pointer to the top of the table and change the current record number to zero. The write command uses these indicators to detect a new record as opposed to an existing record. If the current record has changed and record changes are enforced, the set up for a new record will not take place. The current record must be written or the enforce change record flag must be lowered.

# find

    Syntax: find tid search_string [case_flag]

This command will search the table from the start of the current record (if any) for the search_string. All fields in each record will be searched. Only whole words will match. This command will stop at the first match and display the field number where the match occurred. This form of search cannot be used to locate a string containing multiple words. String comparison is case insensitive by default unless the case_flag is specified (zero indicates case sensitive, one indicates case insensitive).

# find.field

    Syntax: find.field tid field_number search_string [case_flag]

This command will search the table from the start of the current record (if any) for the search_string. Only field field_number will be searched in each record. Only whole words will match. This command will stop at the first match and display the field number where the match occurred. This form of search cannot be used to locate a string containing multiple words. String comparison is case insensitive by default unless the case_flag is specified (zero indicates case sensitive, one indicates case insensitive).

# find.part

    Syntax: find.part tid search_string [case_flag]

This command will search the table from the start of the current record (if any) for the search_string. All fields in each record will be searched. Any part of the word will match. This command will stop at the first match and display the field number where the match occurred. This form of search can be used to locate a string containing multiple words by using a space delimited quoted search_string. String comparison is case insensitive by default unless the case_flag is specified (zero indicates case sensitive, one indicates case insensitive).

# find.field.part

    Syntax: find.field.part tid field_number search_string [case_flag]

This command will search the table from the start of the current record (if any) for the search_string. Only field field_number will be searched in each record. Any part of the word will match. This command will stop at the first match and display the field number where the match occurred. This form of search can be used to locate a string containing multiple words by using a space delimited quoted search_string. String comparison is case insensitive by default unless the case_flag is specified (zero indicates case sensitive, one indicates case insensitive).

# get.rec.count

    Syntax: get.rec.count tid

This command will get and display the current record count.

# get.enf.change.rec.flag

    Syntax: get.enf.change.rec.flag tid

This command will get and display the value of the enforce change record flag. The Bbuuzzb database engine uses this flag to determine whether record changes should be enforced. When record changes are enforced, no re-positioning of the file pointer is allowed until the changed record has been written to disk.

# set.enf.change.rec.flag

    Syntax: set.enf.change.rec.flag tid flag_value

This command will set the enforce change record flag to the flag_value which must be zero or one.

# get.is.table.locked

    Syntax: get.is.table.locked tid

This command will get and display the value of the table locked flag. The Bbuuzzb database engine uses this flag when table maintenance is taking place. Normally, this flag is only used in client/server environments.

# set.is.table.locked

    Syntax: set.is.table.locked tid flag_value

This command will set the value of the table locked flag to flag_value which must be zero or one.

# new.table

    Syntax: new.table [table_name,]file_name tid_flag

This command will create a new Bbuuzzb table. In addition, if the tid_flag is one, the new table will be opened and the tid will be displayed. The file_name must contain the path and file name. The tid_flag must have the value of zero or one.

There may be two names on the command line starting first with the logical table name followed by a comma and the physical file name. The logical file name is optional and if supplied a new catalog entry will be made for the table regardless of the setting of the catalog flag. Do not put any spaces before or after the comma when giving both the logical table name and the physical file name.

# config.get.tmp.path

    Syntax: config.get.tmp.path

This command will get and display the value of the current temporary path. The temporary path is used to store temporary files.

# config.get.log

    Syntax: config.get.log

This command will get and display the value of the current log destination (file or system log server). Database logging may be turned on or off using the config.set.log.flag command. Note that when logging is turned on, the speed of the Bbuuzzb database engine will be affected and the size of the log file will grow rapidly.

# config.get.session

    Syntax: config.get.session

This command will get and display the current session table. The Bbuuzzb database server uses the session table to store record contents when the particular table is not currently being worked on. The session table may be turned off (at the penalty of the Bbuuzzb database server using much more memory) by using the config.set.session.flag command. This command is only valid in client/server (dbm) mode.

# config.get.catalog

    Syntax: config.get.catalog

This command will get and display the current catalog table. The catalog table contains a list of available tables including their physical file names and logical tables names. The catalog table feature may be turned off by using the config.set.catalog.flag command.

# config.get.log.flag

    Syntax: config.get.log.flag

This command will get and display the current value of the log flag. The log flag controls whether Bbuuzzb database logging will take place.

# config.get.session.flag

    Syntax: config.get.session.flag

This command will get and display the current value of the session flag. The session flag controls whether the Bbuuzzb database server uses the session table during its operation. Note that session table processing is active only in client/server (dbm) mode.

# config.get.catalog.flag

    Syntax: config.get.catalog.flag

This command will get and display the current value of the catalog flag. The catalog flag controls whether the Bbuuzzb engine/server uses the catalog table during its operation.

# config.get.replicate.flag

    Syntax: config.get.replicate.flag

This command will get and display the current value of the replication flag. The replication flag controls whether the Bbuuzzb database server will replicate record changes during its operation. Note that replication processing is active only in client/server mode (TCP IPC method only).

# config.get.version

    Syntax: config.get.version

This command will get and display the current version of the Bbuuzzb database engine. Note that this version number is different than the version of db or dbm.

# config.set.tmp.path

    Syntax: config.set.tmp.path tmp_path

This command will set the Bbuuzzb database engine temporary files path to tmp_path which must be a valid path that the engine can create files in.

# config.set.log

    Syntax: config.set.log log_file|sys_log

This command will set the Bbuuzzb database engine/server log destination.

# config.set.session

    Syntax: config.set.session session_table

This command will set the Bbuuzzb database server session table to session_table which may or may not exist. If the session_table does not exist, it will be created. Since the session table is valid only in client/server mode, this command is also only valid in client/server mode.

# config.set.catalog

    Syntax: config.set.catalog catalog_table

This command will set the Bbuuzzb database server catalog table to catalog_table which must already exist. The engine will attempt to open the given catalog.

# config.set.log.flag

    Syntax: config.set.log.flag log_flag

This command will set the log flag to log_flag which must be either zero or one. The log flag allows you to turn application logging on or off.

# config.set.session.flag

    Syntax: config.set.session.flag session_flag

This command will set the session flag to session_flag which must be either zero or one. The session flag allows you to turn the database server session table support on or off. Note that since the session table is specific to client/server mode only, this command is only valid in client/server mode.

# config.set.catalog.flag

    Syntax: config.set.catalog.flag catalog_flag

This command will set the catalog flag to catalog_flag which must be either zero or one. The catalog flag allows you to turn the database server catalog table support on or off.

# config.set.replicate.flag

    Syntax: config.set.replicate.flag replicate_flag

This command will set the replicate flag to replicate_flag which must be either zero or one. The replicate flag allows you to turn the database server replication support on or off. Note that since replication is specific to multi-user mode only, this command is only valid in multi-user mode (TCP IPC method).

# version

    Syntax: version

This command will obtain and display the current version of the currently connected Bbuuzzb server. This command is only valid in multi-user mode.

# get.open.table.list

    Syntax: get.open.table.list [pat]

This command will obtain and display a list of current tables in use including the table tid and file name. The optional parameter pat (if present) should contain an acceptable pattern (to the pmatch function) of file names which will limit the returned list to only those tables that match the given pattern.

# get.nsubfields

    Syntax: get.nsubfields tid fnum

This command will get and display the number of sub-fields within the field fnum in the current record. There must be a current record to report on.

# get.subfield.size

    Syntax: get.subfield.size tid fnum sfnum

This command will get and display the size (in bytes) of the sub-field sfnum within the field fnum in the current record. Zero bytes is a valid sub-field size. There must be a current record to report on.

# get.subfield

    Syntax: get.subfield tid fnum sfnum

This command will get and display the contents of the specific sub-field sfnum within the field fnum in the current record. There must be a current record to report on.

# put.subfield

    Syntax: put.subfield tid fnum sfnum sfdata

This command will put the sub-field data sfdata into the sub-field sfnum within the field fnum of the current record. There must be a current record or you must have declared a new record. If sfdata contains spaces, you must quote the string.

# get.nsubsubfields

    Syntax: get.nsubsubfields tid fnum sfnum

This command will get and display the number of sub-sub-fields within the sub-field sfnum in the field fnum in the current record. There must be a current record to report on.

# get.subsubfield.size

    Syntax: get.subsubfield.size tid fnum sfnum ssfnum

This command will get and display the size (in bytes) of the sub-sub-field ssfnum in the sub-field sfnum within the field fnum in the current record. Zero bytes is a valid sub-sub-field size. There must be a current record to report on.

# get.subsubfield

    Syntax: get.subsubfield tid fnum sfnum ssfnum

This command will get and display the contents of the specific sub-sub-field ssfnum within the sub-field sfnum and the field fnum in the current record. There must be a current record to report on.

# put.subsubfield

    Syntax: put.subsubfield tid fnum sfnum ssfnum ssfdata

This command will put the sub-sub-field data ssfdata into the sub-sub-field ssfnum in the sub-field sfnum within the field fnum of the current record. There must be a current record or you must have declared a new record. If ssfdata contains spaces, you must quote the string.

# replicate.update

    Syntax: replicate.update

This command will cause the currently connected Bbuuzzb server to update all of its replication information. Note that replication processing is active only in client/server mode (TCP IPC method only).

# get.catalog.list

    Syntax: get.catalog.list [pat]

This command will obtain and display a list of catalog entries including the table logical name and physical file name. The optional parameter pat (if present) should contain an acceptable pattern (to the pmatch function) of logical table names which will limit the returned list to only those tables that match the given pattern. Note that this command will function properly regardless of the current value of the catalog flag.

# sort

    Syntax: sort tid specs

This command will sort a table. A list of sort specifications is expected in specs.

# get.sort.mem

    Syntax: get.sort.mem tid

This command will get and display the current allowable sort max memory allocation.

# set.sort.mem

    Syntax: set.sort.mem tid mem

This command will set the allowable maximum sort memory to mem.

# get.sort.open.bin

    Syntax: get.sort.open.bin tid

This command will get and display the current allowable sort number of open bin tables.

# set.sort.open.bin

    Syntax: set.sort.open.bin tid open_bin

This command will set the allowable maximum number of open bin tables to open_bin.

# delete.field

    Syntax: delete.field tid fnum

This command will completely remove the fnum field from the current record. Note that all field numbers past the field being deleted will change.

# delete.subfield

    Syntax: delete.subfield tid fnum sfnum

This command will completely remove the sfnum subfield in the fnum field within the current record.

# delete.subsubfield

    Syntax: delete.subsubfield tid fnum sfnum ssfnum

This command will completely remove the ssfnum subsubfield in the sfnum subfield contained in the fnum field within the current record.

# trans.num

    Syntax: trans.num

This command will fetch and display the transaction count of the current Bbuuzzb server. This command is only valid in client/server mode.

# connect.num

    Syntax: connect.num

This command will fetch and display the connection count of the current Bbuuzzb server. This command is only valid in client/server mode.

Goto Top | Future Lab Home | Contact Webmaster | Feedback

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