"SfR Fresh" - the SfR Freeware/Shareware Archive

Member "q-7.11/modules/gdbm/README-Gdbm" of archive q-7.11.tar.gz:

    1 
    2 Q-Gdbm - GNU DBM interface for the Q programming language
    3 ====== = === === ========= === === = =========== ========
    4 
    5 For this module to work, you must have the GNU dbm library (libgdbm) on your
    6 system. If you have a Linux system then you most likely have this library,
    7 otherwise you can get it from http://www.gnu.org or one of its mirrors. This
    8 module is also supported on Windows.
    9 
   10 The gdbm library provides some simple database functions, suitable for storing
   11 indexed data in a file. The interface provided by this module is a straight-
   12 forward wrapper for (most of) the C functions provided by the library; see
   13 gdbm(3) for more information. Database files are represented using an external
   14 type `GdbmFile'. Both keys and data are represented using clib's byte strings
   15 (see clib.q), thus arbitary binary data can be stored in a database. In the
   16 following we give a brief description of the most important operations.
   17 
   18 
   19 VERSION INFORMATION AND ERROR CODES
   20 ======= =========== === ===== =====
   21 
   22 The version of the host gdbm library can be retrieved with the `gdbm_version'
   23 function:
   24 
   25 ==> gdbm_version
   26 "This is GDBM version 1.8.0, as of May 19, 1999."
   27 
   28 When any of the other gdbm operations fail you can usually retrieve an error
   29 code with the `gdbm_errno' function. It is also possible to set the value of
   30 this variable with `gdbm_seterrno' and determine a readable message for an
   31 error code with `gdbm_strerror'.
   32 
   33 ==> gdbm_strerror gdbm_errno
   34 
   35 
   36 OPENING AND CLOSING DATABASES
   37 ======= === ======= =========
   38 
   39 Before you can work with a database you must open it with the `gdbm_open'
   40 function, which takes the name, block size, read/write flags and a file
   41 creation mode as its arguments; the latter is only used when a new database
   42 file is created. The function returns a `GdbmFile' object which is used in
   43 subsequent operations on the database.
   44 
   45 For instance, here is how we can open a database for both reading and writing,
   46 creating it if it does not yet exist:
   47 
   48 ==> def DBF = gdbm_open "testdb" 512 GDBM_WRCREAT 0666
   49 
   50 The supported flag values are GDBM_READER (readonly access), GDBM_WRITER
   51 (read/write access), GDBM_WRCREAT (read/write, create if necessary), and
   52 GDBM_NEWDB (read/write, always create a new database). These can be combined
   53 (i.e., or'ed bitwise) with the following values: GDBM_FAST (obsolete, since
   54 gdbm now always opens databases in "fast" mode), GDBM_SYNC ("slow" mode,
   55 immediately commit changes to the disk file), and GDBM_NOLOCK (don't perform
   56 locking on the database).
   57 
   58 Unless the GDBM_NOLOCK flag is specified, gdbm uses file locking on the
   59 database to guarantee exclusive access to writers. The database can also be
   60 opened simultaneously by any number of readers, provided that no writer is
   61 currently accessing the database. When using the GDBM_NOLOCK flag the
   62 application is responsible to perform its own locking. To these ends, the
   63 `gdbm_fdesc' function can be used to determine the file descriptor associated
   64 with a database file:
   65 
   66 ==> gdbm_fdesc DBF
   67 
   68 A database file is closed automatically when the corresponding GdbmFile object
   69 is garbage-collected. You can also close it explicitly by invoking the
   70 `gdbm_close' function:
   71 
   72 ==> gdbm_close DBF
   73 
   74 After closing the database file in this manner, all subsequent operations on
   75 the `GdbmFile' object will fail.
   76 
   77 
   78 STORING AND RETRIEVING DATA
   79 ======= === ========== ====
   80 
   81 A new item is stored in the database using the `gdbm_store' function which
   82 takes as arguments the `GdbmFile' object, a key, a value, and a flag
   83 indicating whether an existing item with the same key is to be replaced. Both
   84 the key and the associated value must be encoded as clib byte strings.
   85 
   86 For instance, we can store a binary integer value under the string key "foo"
   87 as follows. (The GDBM_REPLACE flag indicates that any existing item under the
   88 "foo" key is to be replaced. When using the GDBM_INSERT flag instead, only a
   89 new key can be inserted.)
   90 
   91 ==> gdbm_store DBF (bytestr "foo") (bytestr 99) GDBM_REPLACE
   92 
   93 You can also store an arbitrary (printable) Q expression by first converting
   94 it to a string.
   95 
   96 ==> gdbm_store DBF (bytestr "bar") (bytestr (str [1,2,3])) GDBM_REPLACE
   97 
   98 The `gdbm_fetch' function is used to retrieve the value associated with a key
   99 in the database:
  100 
  101 ==> gdbm_fetch DBF (bytestr "foo")
  102 <<ByteStr>>
  103 
  104 Note that the result is again encoded as a byte string which must be converted
  105 back to the desired data type:
  106 
  107 ==> bint _
  108 99
  109 
  110 ==> val (bstr (gdbm_fetch DBF (bytestr "bar")))
  111 [1,2,3]
  112 
  113 You can check beforehand whether a key exists in the database with the
  114 `gdbm_exists' function:
  115 
  116 ==> gdbm_exists DBF (bytestr "foo")
  117 true
  118 
  119 You can also traverse all keys in the database with the `gdbm_firstkey' and
  120 `gdbm_nextkey' functions. E.g.:
  121 
  122 ==> map bstr (while isbytestr (gdbm_nextkey DBF) (gdbm_firstkey DBF))
  123 ["foo","bar"]
  124 
  125 The keys will be listed in an apparently random order (i.e., not sorted by the
  126 keys).
  127 
  128 To delete a key from the database we employ the `gdbm_delete' function:
  129 
  130 ==> gdbm_delete DBF (bytestr "foo")
  131 ()
  132 
  133 ==> gdbm_exists DBF (bytestr "foo")
  134 false
  135 
  136 
  137 MAINTENANCE FUNCTIONS
  138 =========== =========
  139 
  140 By default, gdbm databases are opened in "fast" mode which means that data
  141 will be buffered and hence might not be written to the disk file immediately.
  142 The `gdbm_sync' function can be used to forcibly commit all changes to the
  143 disk file:
  144 
  145 ==> gdbm_sync DBF
  146 
  147 For efficiency, a gdbm database never shrinks when deleting items; instead,
  148 unused entries will be reused when new items are inserted. Hence much space
  149 may be wasted in the database file after deleting a large number of items. You
  150 can use the `gdbm_reorganize' function to shrink the database in such
  151 cases. This will rebuild the database from scratch and hence is a costly
  152 operation which should be used sparingly.
  153 
  154 ==> gdbm_reorganize DBF
  155 
  156 
  157 EXAMPLES
  158 ========
  159 
  160 A sample script illustrating most of the functions discussed above can be
  161 found in the `testdb.q' file. Moreover, the `gdbm_dict.q' script shows how a
  162 dictionary-like interface can be implemented on top of the gdbm module.
  163 
  164 
  165 Enjoy! :)
  166 
  167 May 6 2003
  168 Albert Graef
  169 ag@muwiinfa.geschichte.uni-mainz.de, Dr.Graef@t-online.de
  170 http://www.musikwissenschaft.uni-mainz.de/~ag