Index of /tcl/ftparchive/sorted/databases/tcl_db-1.0

      Name                   Last modified     Size  Description


[DIR] Parent Directory       18-Dec-99 07:01      -  
[   ] README                 30-Mar-97 15:39     7k  
[CMP] tcl_db-1.0.tar.gz      30-Mar-97 15:45   236k  

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 <first:i other:v3(d)> 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.