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