## DBOPEN - DATABASE ACCESS METHODS

Dbopen is the library interface to database files. The supported file format are btree, hashed ans UNIX file-oriented.

The btree format is a representation of a sorted, balanced tree structure.

The hashed format is an extensible, dynamic hashing scheme.

The flat-file format is a byte stream file with fixed or variable length records.

The formats and file format-specific information is described in detail in the manual pages included with the dbopen package.

Dbopen was written by Keith Bostic (bostic@cs.berkeley.edu) of the University of California at Berkeley.

Unlike most traditional Unix "db" implementations, both key and data byte strings may be of essentially unlimited length.

The Tcl interface to dbopen was written by NeoSoft, and is based on a Tcl/dbopen interface written by Poul-Henning Kamp (phk@data.fls.dk).

NeoSoft added shared and exclusive file locking, non-blocking access, "db forall" and "db searchall" access methods, code cleanup and reformatting, plus some other stuff.

A summary of the dbopen function and methods follows:

- db open <file> <type> [<flags> [<mode>]]

  Opens the specified database file using . A dbopen session ID is returned. <type> must be either "hash", for a hashtable, or "btree", for a btree. <flags> is a subset of these chars: (default: r)

  - c -- create
  - r -- read mode
  - w -- read-write mode
  - t -- truncate
  - l -- shared lock
  - L -- exclusive lock
  - ? -- non-blocking
  - + -- enable multiple records with the same key under btree access
  <mode> is a octal integer used for creating files. (default 644)

- db close <sess> closes the specified db file.

- db cache <sess> Cache the specified db file.

  NOT CURRENTLY SUPPORTED.

- db get <sess> <key> [<var>]

  "db get" will try to get the value addressed by <key>.

  If <var> is specified, the result will be written into it, and the return value will be a boolean: 1 for success, 0 for failure.

  If a variable is not specified, found value will be returned, and failures will result in a Tcl error being generated.

- db put <sess> <key> <data> [insert|replace]

  "db put" stores <data> under <key>. 'replace' is the default mode. "db put" returns an error on failure.

  "insert" is only valid in the case of btrees. In this case, multiple key-value pairs may have the same key.

- db del <sess> <key>

  Delete the entry with the specified <key>.

  If the record is deleted, "1" is returned, else "0" is returned.

  If the record wasn't deleted, it's probably because the <key> wasn't there to begin with.

- db seq <sess> <flag> [<key>] [<var>]

  Sequential read.

  <flag> can be:

  - cursor - Data associated with key is returned, and partial matches are allowed.
  - first - the first key/data pair in the database is returned.
  - last - the last key/data pair in the database is returned.
  - next - The next key/data pair after the cursor is returned, or the first key/data pair if the cursor hasn't been set.
  - prev - retrieve the key/data pair immediately before the cursor.

        if <var> is specified:

            if no keys found:

      	  <var> is set to "" and "0" is returned

            else

      	  <var> is set to the key and "1" is returned.

        If <var> is not specified,

            if no keys were found, "" is returned, else the key is returned.

- db forall <sess> <key_var> <proc>

  executes <proc> for all keys found in the database.

  The actual key_value is available in $<key_var>.

  Example:

            db forall $db key {
      	      puts stdout "$key: [db get $db $key]"
            }

- db searchall <sess> <keyvar> [-<searchtype>] <pattern> <proc> executes <proc> for all keys found in the database that match the specified pattern, based on the specified search type. <searchtype> may be "-glob" or "-regexp". The default type is "-glob". Within the <proc> fragment, the actual key is available in $<key_var>. Example:

            db searchall $db key -glob "*foo*" {
      	      puts stdout "$key: [db get $key]"
            }

  db sync <sess> causes the database to be synced to disk.

  $Id: db-bak.html,v 1.1.1.1 1999/03/31 20:34:36 damon Exp $