Berkeley DB support This package supports object-oriented access to Berkeley DB BTREE files. It has been tested only on Solaris 2.5 and version 1.85 of the berkeley database. To compile this extension, use the command "configure" to create a Makefile using system information detected when you installed TCL. You may need to tweak a path in the configure script to make this work. In order to compile and link a dynamically loadable version of this package, you will need a version of the berkeley database which has been compiled as position independent object code. This directory includes a copy of libdb.so which is a Solaris version of db1.85 compile in such a way. If you don't have such a beast, you should still be able to create a staticly linked version of tcl with db support, but this would be of considerably lower utility. The function dbopen creates a command which is then used in the style of the TK widgets. This package also includes a binary string manipulation package which allows arbitrary C data to be accessed. db -create db_name db -create db_name file_name db -create -binary db_name file_name db -create -multiple db_name file_name db -create -multiple -binary db_name file_name creates a database object. the tcl database object will be called db_name and the file associated with the database (if any) will be called file_name. with -binary option, all accesses will be encoded binary which can be constructed and decoded using the binary_append and binary_scan functions. with -multiple, multiple entries for the same key are allowed. db db_name file_name db -binary db_name file_name opens a database object. the tcl database object will be called db_name and the file associated with the database (if any) will be called file_name. with -binary option, all accesses will be encoded binary which can be constructed and decoded using the binary_append and binary_scan functions. possible operations on a database object include: db close closes the database. db delete key db -glob delete pattern deletes the specified key, or with -glob, the specified keys. db get key db -glob get pattern gets the value associated with the specified key or with -glob get multiple values associated with keys which match the pattern.) db names db names pattern db -glob names pattern gets a list of the valid keys for a database. if -glob is used, then a list of keys matching a wildcard pattern is returned. the -glob can also be omitted. db foreach key value body db -glob foreach pattern key value body iterate through the database. with -glob, iterates only through keys which match the pattern. db sync flushes all data to the underlying database file. ================================================================ This directory also contains a dynamically loadable tcl extension which supports the manipulation of binary data. This extension defines the Tcl commands binary_append for building binary data, binary_scan for disassembling binary structures, binary_read for reading from files containing binary data and binary_write for writing binary data to files. The append and scan routines each accept format arguments which determine what data is expected. This format argument is a list of codes which can include: b - the data is a single 8 bit byte h - the data is a 16 bit integer i - the data is a 32 bit integer f - the data is a 4 byte floating point number in whatever format is native to the current machine. d - the data is an 8 byte floating point number in whatever format is native to the current machine. s - the data is a null terminated string Note the possible confusion between d here and %d in printf type formats. In addition, structures can be read or written using a notation in which < and > enclose a list of the structure components. Each component consists of a name followed by a colon, and then a type signature for that component. Components of structures can themselves be structures or vectors. When scanning structures, the components will be stored in a single tcl array which is indexed by the component names. Vectors are indicated by a v, an optional count followed by the element type enclosed in parentheses. If the count is not given, then it is assumed that the first 4 bytes of the vector will contain the count. When a vector is scanned, the elements are stored in a tcl array in a manner similar to the way that structures are stored, except that the indexes are integers. Vectors are zero-origin, so the first index is 0. The number of elements is also stored under the index count. When structures and vectors are used recursively, the indices are concatenated using a comma as a separator. Thus a structure defined by would have tcl index values of "first", "other,0", "other,1", "other,2" and "other,count". Just now, scanning vectors and structures isn't fully supported. Binary_scan accepts a first argument which is an offset at which conversion should start and returns an offset where conversion left off. This returned offset can be used if successive elements of binary data should be converted. This makes it easy to use binary_scan in (for instance) a loop. Encoding Method These routines all encode binary data so that Tcl doesn't have trouble when it encounters null bytes. The encoding used by all of the binary_* commands is designed to avoid changing the length of the encoded string as much as possible. Since a null is quite common in most binary data, this goal means that nulls have to be encoded in a single byte. This package encodes a null as 0x80, encodes 0x80 as 0x81 0x80, and encodes 0x81 as 0x81 0x81. This has the virtue of leaving strings containing ISO-latin, ASCII, EUC, GuoBiao, and Big5 unchanged. I am unsure what will happen with Unicode encoded as UTF-8, but 16 bit Unicode data should mostly not expand. Command Arguments binary_read fileID ?numBytes? reads all or part of a file and encodes it for safe manipulation by Tcl binary_write fileID string writes a string to a file after decoding it. binary_append var format value1 ... valuen adds encoded binary representations of the values according to the supplied format. vectors and structures are assumed to be stored in Tcl arrays. binary_scan offset format binary_value var1 ... varn reads encoded binary values from binary_value starting at offset. the formats for the values are determined by examining format. the places to put the values are determined by the variable names var1 through varn. vectors and structures only need a single variable to hold them since they will be stored as a Tcl array. binary_scan returns the offset of the first unconverted byte.