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.
`check-order,co` [s] [c]
		Check Order: Checks the lexicographic order of keys in the current root, starting from the current position within the BTree. If the s argument is given, the check is performed from the first key of the BTree index. If a disordered index is discovered, the keys at fault are displayed. Otherwise, check-order is silent, unless the c argument is specified, which causes the number of keys checked to be displayed.
`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.
`duplicates,dups` { on \| off }
		Duplicates: Sets or unsets support for duplicate keys in the current root. When on is specified, duplicate keys are permitted. When off, duplicate keys are not permitted .
`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 termination 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. If key is omitted, the index is positioned prior to the first key (like position s).
`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` [c]
		List: Displays all key and 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, next-data, previous or previous-data command. If the c argument is given, the count of keys listed will be displayed in addition.
`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, next-data previous or previous-data command.
`list-data-prev,ldp`
		List Data Previous: Displays all keys, and associated data records, prior to 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, next-data previous or previous-data command.
`list-prev,lp` [c]
		List Previous: Displays all keys, and associated value, prior to 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, next-data, previous or previous-data command. If the c argument is given, the count of keys listed will be displayed in addition.
`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, next-data, previous or previous-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, next-data, previous or previous-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, next-data, previous or previous-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.
`open-readonly,or` `filename` [s]
		Open Readonly: Opens the existing B Tree file identified by filename in read-only mode. 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.
`position,pos` { s \| e }
		Position: Sets the position in the current root. s will cause the position to be set prior to the first key in the index, e will cause the position to be set after the last key.
`prompt,p`
		Prompt: Toggles the display of a command prompt when bt is ready for the next user command.
`previous,prv`
		Previous: Displays the key prior to 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, next-data, previous or previous-data command.
`previous-data,pd`
		Previous Data: Displays the key and associated data record prior to 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, next-data, previous or previous-data 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-cur,rc`
		Remove Current key: Removes 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, next-data, previous or previous-data command.
`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-data-cur,rdc`
		Removes Current Data: Removes the current key and its associated data record in the current root of the in-use B Tree index file. The current key is set by the last find, find-data, next, next-data, previous or previous-data command.
`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` structure [v] }
		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. For the structure option, specifying v will cause a detailed report on the structure to be displayed. Otherwise, only a summary is displayed.
`size-data,sd` [ `key` ]
		Size Data: Displays the number of bytes occupied by the data record associated with key. If key is omitted, the size of the data record associated with the current key is displayed. The current key is set by the last find, find-data, next, next-data, previous or previous-data command. 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 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 *.
`update-data-cur,udc` { `string` \| `bufname`* }
		Update Data Current: Updates the current key with a new associated data record in the current root of the in-use B Tree index file. The current key is set by the last find, find-data, next, next-data, previous or previous-data command. 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.
`update-value,uv` `value`
		Update Value Current: Modifies the value associated with current key 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, next-data, previous or previous-data command.
`write-threshold,wt` `threshold`
		Write Threshold: Sets the number of index block updates beyond which the block contents must be writtent to disk. A threshold of zero means writes will not take place unless a block must be flushed to disk.
`help,?` [cmd]
		Help: Displays a list of bt commands and a terse description of syntax and usage. If cmd is specified, only help on that command will be displayed.
`comment,#`
		Comment: bt will ignore any line starting with a #. Note that bt will also ignore blank lines.