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 (see the man-pages from gdbm).
Tclgdbm 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 Tclgdbm is provided as a loadable Tcl-Module, it can be easily integrated into a Tcl-Application.
To have a more highlevel (sql-like) access to data stored in a gdbm-database-file you should have a look at Qgdbm.package require gdbm set gdbm_handle [gdbm_open -writer -newdb first.gdbm] $gdbm_handle -insert store key1 {Some value to be stored.} set value [$gdbm_handle fetch key1] puts "value: $value" $gdbm_handle closeThat'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.
The following commands are available (for a detailed discussion of these commands you should also look-up the gdbm-man-pages):
Syntax: | gdbm_open [option] file |
Options: | -writer -reader -wrcreat -newdb -nolock -sync
-block_size block_size_number -mode file-mode
-fatal_func function_name |
Gdbm-Command: | gdbm_open |
Return-Value: | Handle to database-file file |
Description: | The specified file is opened either for
reading or writing. Gdbm sets a lock on this file so there is only
one writer. With -wrcreat the file is created
if it is not existent. -newdb creates file
regardless if one exists.With -mode the file mode may be specified.In case of a fatal-error a Tcl-callback-function may be specified with -fatal_func Example: gdbm_open -writer -newdb -nolock -fatal_func my_callback_fct
help.gdbm Opens/creates a new gdbm-database-file help.gdbm and doesn't lock the file even though it will write to this file (should really be used with care). The fatal-error-function my_callback_fct must be
defined as this:proc my_callback_fct {error_message} { |
Syntax: | gdbm_handle close |
Options: | none |
Gdbm-Command: | gdbm_close |
Return-Value: | none |
Description: | Close the database-file which is associated with
gdbm_handle. Where gdbm_handle is retrieved with a
call to gdbm_open |
Syntax: | gdbm_handle [option] store
key value |
Options: | -insert -replace |
Gdbm-Command: | gdbm_store |
Return-Value: | none |
Description: | The given value is stored in the
database-file with the given key. If -insert
is specified and the provided key is already stored in the
database an error is thrown. |
Syntax: | gdbm_handle [option] fetch key |
Options: | none |
Gdbm-Command: | gdbm_fetch |
Return-Value: | The value associated with key in the database. |
Description: | Fetch the key/value-pair from the database |
Syntax: | gdbm_handle exists key |
Options: | none |
Gdbm-Command: | gdbm_exists |
Return-Value: | 0 or 1 |
Description: | If the key does exists, 1 is returned. Otherwise 0. |
Syntax: | gdbm_handle delete key |
Options: | none |
Gdbm-Command: | gdbm_delete |
Return-Value: | none |
Description: | Delete the given key from databasefile. If the key does not exist an error is thrown. |
Syntax: | gdbm_handle reorganize |
Options: | none |
Gdbm-Command: | gdbm_reorganize |
Return-Value: | none |
Description: | When you have done many deletes on a
database-file, the space is not freed until you call reorganize . |
Syntax: | gdbm_handle count |
Options: | none |
Gdbm-Command: | none |
Return-Value: | Number of total rows in gdbm-file |
Description: | This is aequivalent to a "select count(*)
from table " in a relational database. |
Syntax: | gdbm_handle maxkey |
Options: | none |
Gdbm-Command: | none |
Return-Value: | Number of the maximum primary-key |
Description: | Should be used only when the primary-key consists
of integer-numbers (as always when you use an ID as the primary
key). In most cases you want to insert a new element and give this
element a unique ID. Use [expr [gdbm_handle maxkey] +
1] for this purpose.You could also simulate sequences that way. |
Variablename/Syntax: | GDBM_VERSION |
Options: | none |
Gdbm-Command: | gdbm_version gdbm_errno gdbm_strerror |
Return-Value: | gdbm_version returns a version-string gdbm_strerror gives an error-description to an error-number |
Description: | You can access the version-string provided in the
variable GDBM_VERSION . In case of an error the variable
GDBM_ERRNO is filled with the corresponding
gdbm-error-number (see gdbm.h for detailer error-numbers). Withgdbm_strerror $GDBM_ERRNO an error-description could be retrieved. In case of most errors the error-description is thrown with the error -command.
|
Variablename: | gdbm_error |
Description: | To provide a way to access the error-code-defines
in gdbm (e.g.: GDBM_FILE_OPEN_ERROR, ..) the array
gdbm_error is provided. With these you can check
GDBM_ERRNO for specific error-codes without using the
integer-values of the gdbm-error-code-defines.The following "defines" (that is array-entries) exists: 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) Example: set gdbm [gdbm_open -writer file.gdbm] if {[catch {$gdbm fetch store key1} result]} { if {$GDBM_ERRNO == $gdbm_error(GDBM_ITEM_NOT_FOUND)} { puts stderr "Item not found." } } |
Even though the Tclgdbm-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.data
)package require gdbm 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 Bibel"} store_array books.gdbm books
firstkey, nextkey
For Suggestions, improvements, bugs or bug-fixes please contact:
Stefan Vogel (stefan.vogel@avinci.de)