# $EPIC: dbmctl.txt,v 1.6 2007/05/15 01:28:58 jnelson Exp $
======Synopsis:======
$[[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 [[what is a word|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.

======Technical:======
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.

======About Hash Files:======
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.

======Hash file operations:======
| 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. |

======Notes:======
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.

======Examples:======

======History:======
The [[dbmctl]] function first appeared in EPIC5-0.0.8.