Chapter 5. B Tree Test Harness

The B Tree library is distributed with a test harness, bt, which exercises all of the functions supplied by the B Tree library.

Most bt commands correspond directly to a matching B Tree library function call. Additional commands are available to automate testing scripts and manage concurrently open files. bt reads from stdin and writes normal output to stdout. Terminal error messages go to stderr. A prompt of bt: is issued prior to reading from stdin. Long running commands may be interrupted using cntrl-c, which will return to the command prompt.

bt is built with GNU readline support, if readline libraries and include files are detected when building the BT library and supporting tools. Readline enables bt to offer command editing, command history and file completion. More information on the capabilities provided by readline can be found in the full GNU documentation.

A typical bt session might look like:

      $ bt
      bt: c test
      bt: d newkey 55
      bt: f newkey
      Key: 'newkey' = 55
      bt: dd datakey some_text_string
      bt: fd datakey
      Data returned: 'some_text_string'
      bt: fd datakey d
      some_text_string
      bt: b abuf 512
      bt: dd bufkey *abuf
      bt: fd bufkey
      Data record: 
      aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
      aaaaaaaaaaaaaaaaaaaaaaaaa'
      bt: sd bufkey
      Key 'bufkey' record size: 512 bytes
      bt: q
      $

bt commands have a both a full and abbreviated versions. The descriptions below show the full command first, followed by the abbreviated version (comma separated). A command may optionally be followed by an argument and a qualifier. The following table lists the commands supported by bt:

Table 5.1. B Tree Commands

`buffer,b` `bufname` {[ `size` ] \| [ `filename` ]}
		Buffer: Creates a data buffer called bufname. If the numeric size argument is given, the buffer is created with that number of bytes. The buffer is filled with the first character of the bufname. If the size argument is non-numeric, it is assumed to be a file name, and the contents of the file are read into the buffer. The data buffer can subsequently be specified as data for a define-data command.
`buffer-delete,bd` `bufname`
		Buffer Delete: Deletes an existing data buffer identified by bufname.
`buffer-list,bl`
		Buffer List: Lists the names of the currently defined data buffers on stdout.
`create,c` `filename` [s]
		Create file: Creates a new B Tree file. If a file of the same name already exists, it will be silently overwritten. If the s qualifier is given, the file will be created in shared mode. The newly created B Tree file becomes the current file; use the file-list command to view the list of open files.
`change-root,cr` `rootname`
		Change Root: Switches the current root to the root named rootname in the in-use B Tree file. If switch is successful, rootname becomes the current root. All subsequent key and/or data operations will take place against rootname.
`close,x`
		Close: Closes the in-use B Tree file. The next available open file, if one exists, is automatically made the in-use B Tree file. If there are no candidate B Tree files, a warning message is issued.
`define,d` `key` `value`
		Define key: Defines a new key in the current root of the in-use B Tree index file. The new key name is defined by key, and is assigned value. If value is omitted, zero is assumed.
`data-address,da` `key`
		Data Address: Prints, in a decoded form, the data segment address associated with key.
`define-data,dd` `key` {[ `string` ] \| [ `bufname`* ]}
		Define key with Data: Defines a new key with an associated data record in the current root of the in-use B Tree index file. key defines the key name. Data can be provided in one of two ways: either a plain string or the name of a previously defined buffer can be specified. If the latter, it should be indicated by a leading *.
`define-root,dr` `rootname`
		Define Root: Creates a new B Tree index root, named rootname in the currently selected B Tree file. If creation is successful, the current root becomes the new root. All subsequent key and/or data operations will take place against the new root.
`echo,ec` {[on] \| [off]}
		Echo: When echo is on, commands read from an execute file are echoed to stdout. If off, no echo is performed. If no argument is given to echo, the current status of the echo setting is displayed.
`error,er` {[on] \| [off]}
		Error: When error is on, an execution error while reading commands from an execute file will cause terminated of the execute file. If off, command execution will continue when errors are encountered. If no argument is given to error, the current status of the error setting is displayed.
`execute,e` `filename`
		Execute: Causes commands to be read and executed from the file denoted by filename. execute commands can be nested, currently up to five deep. No command prompts will be issued while reading commands from a file. See also the echo and error command descriptions for more information on execution control when reading commands from a file.
`find,f` `key`
		Find: Attempts to locate key in the current root of the in-use B Tree index file. If found, the value associated with the key is printed.
`find-data,fd` `key` [d]
		Find Data: Attempts to locate key in the current root of the in-use B Tree index file. If found, the first 80 bytes of the data record associated with the key is displayed. If the d qualifier is given, the whole of the data record is displayed. Note that the data record is displayed as character data; control characters or escape sequences in the data record could cause strangenesses on display.
`file-list,fl`
		File List: Lists the set of open B Tree index files. To change the current file, issue a use command.
`list,l`
		List: Displays all keys, starting from the current key in the current root of the in-use B Tree index file. The current key is set by the last find, find-data, next or next-data command.
`list-data,ld`
		List Data: Displays all keys, and associated data records, starting from the current key in the current root of the in-use B Tree index file. The current key is set by the last find, find-data, next or next-data command.
`list-keys-only,lko`
		List Keys Only: Displays all keys, but not associated value, starting from the current key in the current root of the in-use B Tree index file. The current key is set by the last find, find-data, next or next-data command.
`lock,lk`
		Lock: Acquires exclusive access to the in-use B Tree file which was originally opened in shared mode. If the file was opened in exclusive mode (the default), lock will have no effect.
`next,n`
		Next: Displays the key following the current key in the current root of the in-use B Tree index file. The current key is set by the last find, find-data, next or next-data command.
`next-data,nd`
		Next Data: Displays the key and associated data record following the current key in the current root of the in-use B Tree index file. The current key is set by the last find, find-data, next or next-data command.
`open,o` `filename` [s]
		Open: Opens the existing B Tree file identified by filename. If the optional s qualifier is given, the file will be opened in shared mode. More than one B Tree index file may be open currently; the newly opened file is made the in-use B Tree file. The in-use file may be changed by the use command, while the list of open files is displayed through the file-list command.
`prompt,p`
		# Prompt: Toggles the display of a command prompt when bt is ready for the next user command.
`quit,q`
		Quit: Terminates bt. Any open B Tree files will be closed automatically.
`remove,r` `key`
		Remove key: Removes a previously defined key in the current root of the in-use B Tree index file. The key name is specified by key.
`remove-data,rd` `key`
		Removes key with Data: Removes a previously defined key and its associated data record in the current root of the in-use B Tree index file. key defines the key name.
`remove-root,rr` `rootname`
		Remove Root: Removes an existing B Tree index root, named rootname in the in-use B Tree file. If removal is successful, all blocks used by the root (both index and data) will be returned to the free list. It is not permitted to remove the current root.
`show,s` {[control] \| [super] \| [stats] \| [space] \| [stack] \| [block `n` ]}
		Show: Displays B Tree debug information. The option specified is passed directly to the `bdbug` function. See the `bdebug` description for the information provided by each option.
`size-data,sd` `key`
		Size Data: Displays the number of bytes occupied by the data record associated with key. If key has no associated data record, results are undefined.
`system,!` `command`
		System: Passes the text following the system command to the shell for execution.
`use,u` `filename`
		Use: Changes the in-use B Tree file to filename. The file must have already been opened or created, using the open or create command.
`update-data,ud` `key` {[ `string` ] \| [ `bufname`* ]}
		Update key with Data: Updates an existing key with a new associated data record in the current root of the in-use B Tree index file. key defines the key name. Data can be provided in one of two ways: either a plain string or the name of a previously defined buffer can be specified. If the latter, it should be indicated by a leading *.
`unlock,ulk`
		Unlock: Unlocks the in-use B Tree file, if it was locked with the lk command. If not locked, or the file was originally opened in exclusive mode, unlock has no effect.
`update-value,uv` `key` `value`
		Update Value: Modifies the value associated with key in the current root of the in-use B Tree index file.
`help,?`
		Help: Displays a list of bt commands and a terse description of syntax and usage.
`comment,#`
		Comment: bt will ignore any line starting with a #. Note that bt will also ignore blank lines.