# $EPIC: dbmctl.txt,v 1.6 2007/05/15 01:28:58 jnelson Exp $
$dbmctl(OPEN type filename)
$dbmctl(OPEN_READ type filename)
$dbmctl(CLOSE refnum)
$dbmctl(ADD refnum “varname” value)
$dbmctl(CHANGE refnum “varname” value)
$dbmctl(DELETE refnum “varname”)
$dbmctl(READ refnum “varname”)
$dbmctl(NEXT_KEY refnum start-over)
$dbmctl(ALL_KEYS refnum)
$dbmctl(ERROR refnum)
refnum is a value returned by OPEN and OPEN_READ.
type must always be STD for now.
filename is a dbm file (without the .db extension!)
varname is a dbm key. It is always a dword. Spaces are important!
value is a dbm value. Spaces are important!
start-over is 1 if you want to begin at the first key, and 0 if you
want to move to the next key.
The dbmctl function is a low-level interface to reading and writing variables from a permanent file.
The format of the permanent file is an SDBM hash file, which is compatable with perl and apache, but is not compatable with ndbm or gdbm.
Hash files are binary files that let you read and write variables and values. Because the values are stored in a file, they persist after you quit. So it's a great place to put the user's permanent configuration options that need to reload every time they start your script.
It's faster than using save and load, but because it stores in a binary format, the user can't read (and edit) the values directly.
Because the values are stored in a file, the variables you don't use don't take up any memory, and don't cause namespace pollution for your script.
| OPEN | Return a refnum that can be used to read and write variables in the file filename. Right now the type argument must be STD. |
| OPEN_READ | Return a refnum that can be used only for reading variables in the file filename. Right now the type argument must be STD. |
| CLOSE | Close the file previous opened with OPEN or OPEN_READ |
| ADD | Add a new variable to the file and set its value. |
| CHANGE | Change the value of an existing variable in the file. |
| DELETE | Remove a variable from the file. |
| READ | Return the value of a variable from the file |
| NEXT_KEY | Iterate over all of the variable names in the file. The ordering is always unspecified. The first time you call NEXT_KEY, start-over should be 1. Afterwards, it should be 0. When this operations returns the empty string, you have visited all the keys |
| ALL_KEYS | Return all of the variable names in the file. This could take a long time, and it might return a very large string! This operation implicitly does a “start-over”, and you must “start-over” next time you call NEXT_KEY. |
| ERROR | Return the errno value for the last operation. Use this if any previous value returns the empty string. |
Hash files use file descriptors, along with $open() and logfiles, and connections to servers, and dcc, and so on, so you shouldn't just open up a bunch of hash files and ignore them forever. Make sure you CLOSE your hash files you aren't using if this becomes a problem.
This whole thing was specifically written for people who wanted hash table support for saving script configuration values permanently.
The dbmctl function first appeared in EPIC5-0.0.8.