Tgdbm Library for Tcl (Version 0.5)

This is the documentation of the functions provided by the Gdbm-Tcl-Wrapper.

Overview

When opening a gdbm-database-file a handle for this database is provided for
accessing the file. This handle is used to call the gdbm-commands.

Furthermore you can use Tgdbm for transparently accessing and storing tcl-
arrays (persistant arrays). An array is attached to the gdbm-file as a handle.
With this you can set an array-entry which is stored or updated transparently
in the corresponding gdbm-file.

Tgdbm is meant to be used in Tcl-Applications which has to store some
small/medium amount of data. In many cases there is not enough data to be
stored, so that a „real“ database is justified.

But though there is only a small amount of data, you often have to use an
efficient way to store them (not just write them in a plain text-file).

Because Tgdbm is provided as a loadable Tcl-Module, it can be easily
integrated into any Tcl-Application.

For information about downloads, … see the Tgdbm-overview.

Commands

Let’s have a look at a simple walk-through.

  package require tgdbm

  set gdbm_handle [gdbm_open -wrcreat -newdb first.gdbm]

  $gdbm_handle -insert store key1 {Some value to be stored.}

  set value [$gdbm_handle fetch key1]
  puts "value: $value"

  $gdbm_handle close

That’s nearly all there is. When opening/creating a gdbm-database-file a handle
is returned, which is used as a Tcl-command for accessin this
database-file. When calling this command you provide the „usual“
gdbm-commands (like gdbm_store, …) but without the gdbm-prefix
as a parameter.

Now let’s use the persistant array feature:

  package require tgdbm
  gdbm_open -wrcreat -newdb -array my_array second.gdbm
  set my_array(1) one  ;# this will store 1/one in my_array and directly
                       ;# in file "second.gdbm"
  set my_array(2) two
  unset my_array(2)    ;# this will delete key '2' from second.gdbm
  set my_array(1) eins ;# this will update key '1' to 'eins'

  my_array -replace store 2 zwei
  set x $my_array(2)   ;# x == zwei
  unset my_array       ;# this will close the file second.gdbm
                       ;# this could be done with:
                       ;#  my_array close
                       ;#  too, which will also unset the array

The following commands are available which are directly mapped from
aequivalent gdbm-commands:

• gdbm_open
• gdbm_handle close
• gdbm_handle store
• gdbm_handle fetch
• gdbm_handle exists
• gdbm_handle delete
• gdbm_handle firstkey and gdbm_handle nextkey
• gdbm_handle reorganize
• gdbm_handle sync

Furthermore there are some useful additional commands:

• gdbm_handle count
• gdbm_handle maxkey
• gdbm_handle attach_array
• gdbm_handle detach_array
• gdbm_handle keys

gdbm_open

 proc my_callback_fct {error_message} {
     ...
 }

  gdbm_open -writer -array ini ini.gdbm
  set ini(font) Times
  proc setSize {size} {
    # wrong!!!: set ini(size) $size
    global ini
    set ini(size) $size
  }

close

store

fetch

exists

delete

firstkey, nextkey

  set gdbm [gdbm_open -reader file.gdbm]
  if {[set key [$gdbm firstkey]] != ""} {
      puts "key: '$key' value: '[$gdbm fetch $key]'"
      while {[set key [$gdbm nextkey $key]] != ""} {
          puts "key: '$key' value: '[$gdbm fetch $key]'"
      }
  }
  $gdbm close

reorganize

sync

count (extension of gdbm)

maxkey (extension of gdbm)

attach_array (extension of gdbm)

detach_array (extension of gdbm)

keys (extension of gdbm)

Versions and Errors

	gdbm_strerror gives an error-description to an error-number||

	gdbm_error(GDBM_NO_ERROR)
	gdbm_error(GDBM_MALLOC_ERROR)
	gdbm_error(GDBM_BLOCK_SIZE_ERROR)
	gdbm_error(GDBM_FILE_OPEN_ERROR)
	gdbm_error(GDBM_FILE_WRITE_ERROR)
	gdbm_error(GDBM_FILE_SEEK_ERROR)
	gdbm_error(GDBM_FILE_READ_ERROR)
	gdbm_error(GDBM_BAD_MAGIC_NUMBER)
	gdbm_error(GDBM_EMPTY_DATABASE)
	gdbm_error(GDBM_CANT_BE_READER)
	gdbm_error(GDBM_CANT_BE_WRITER)
	gdbm_error(GDBM_READER_CANT_DELETE)
	gdbm_error(GDBM_READER_CANT_STORE)
	gdbm_error(GDBM_READER_CANT_REORGANIZE)
	gdbm_error(GDBM_UNKNOWN_UPDATE)
	gdbm_error(GDBM_ITEM_NOT_FOUND)
	gdbm_error(GDBM_REORGANIZE_FAILED)
	gdbm_error(GDBM_CANNOT_REPLACE)
	gdbm_error(GDBM_ILLEGAL_DATA)
	gdbm_error(GDBM_OPT_ALREADY_SET)
	gdbm_error(GDBM_OPT_ILLEGAL)

set gdbm [gdbm_open -wrcreat file.gdbm]
if {[catch {$gdbm fetch store key1} result]} {
    if {$GDBM_ERRNO == $gdbm_error(GDBM_ITEM_NOT_FOUND)} {
        puts stderr "Item not found."
   }
}

Examples

Even though the Tgdbm-commands should be easy enough (if you know
the gdbm-library) a few examples should help to start immediately.

Pay attention to the reduced error-handling.

1. Store a bunch of data (which is stored in the array data)

package require tgdbm

proc store_array {file data} {
    upvar $data dat
    # create file if it doesn't exist
    set gdbm [gdbm_open -wrcreat $file]

    foreach entry [array names dat] {
        $gdbm -replace store $entry $dat($entry)
    }
    $gdbm close
}

# ISBN - Booktitles
array set books {1-567xyz "XML Pocket Reference" abc "The Bible"}
store_array books.gdbm books

2. List the content of a database-file

See Description of firstkey, nextkey

3. Using the array-commands

Example with array-extension (since version 0.5).

package require tgdbm
gdbm_open -wrcreat -array books books.gdbm

# this one automagically stores the data in books.gdbm
# in the form (ISBN title)
array set books {
    1-567xyz "XML Pocket Reference"
    abc      "The Bible"
}

# now closing the file
unset books
# this could also be done with
# books close

4. gdbm-arrays and namespaces

This example shows how to use „global“ gdbm-arrays inside namespaces:

package require tgdbm

namespace eval gdbm::ar {
    variable myArray
}

proc gdbm::ar::init {gdbm_file} {
	variable myArray
	gdbm_open -wrcreat -array myArray $gdbm_file
}

proc gdbm::ar::close {} {
	variable myArray
	myArray close
}

proc gdbm::ar::printData {} {
	variable myArray
    parray myArray
}

proc gdbm::ar::get {key} {
	variable myArray
	return $myArray($key)
}

proc gdbm::ar::fillData {args} {
	variable myArray
	array set myArray $args
}

gdbm::ar::init "airports.gdbm"
gdbm::ar::fillData ADD "Addis Ababa" MUC "Munich" ZAG "Zagreb"
gdbm::ar::printData
gdbm::ar::close

This example can be immediately used for implementing something
similar to ini-files (where configurable user-data like
window-positions or font-selections are stored).