

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 <file> using <mode>.  
     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

      <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>

      "db forall" 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>

      "db searchall" 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>

    "db sync" causes the database to be synced to disk.


WWW - WORLD WIDE WEB EXTENSIONS
===============================

www_load_stats hourlyArrayName webstatsFilename

    Read through a CERN or NCSA HTTPD log file.  Distribute accesses
    by hour into elements of the specified array.  Create a tree of
    access counts in a series of arrays, starting with "/".

www_unescape_string string

    Given a string, convert all of the hex-encoded ASCII characters
    contained therein back to their original value, and return the
    result.

www_escape_shell_command command

    Given a command to be passed in a command line of a shell, 
    quote all of the shell metacharacters with backslash and return
    the result.

www_load_agent_log logfile

    Given an agent log, collect accesses by client type.  BUGGY.


GENERAL EXTENSIONS
==================

    incr0 var [increment]

    Increment the contents of a variable by one, or by the specified
    increment.  If var does not exist, set it to zero before incrementing.
