User Tools

Site Tools


dbmctl

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

dbmctl [2007/05/15 01:28] (current)
Line 1: Line 1:
 +# $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.
 +
  
dbmctl.txt ยท Last modified: 2007/05/15 01:28 (external edit)