dbmctl
no way to compare when less than two revisions
Differences
This shows you the differences between two versions of the page.
— | dbmctl [2007/05/15 01:28] (current) – created - external edit 127.0.0.1 | ||
---|---|---|---|
Line 1: | Line 1: | ||
+ | # $EPIC: dbmctl.txt, | ||
+ | ======Synopsis: | ||
+ | $[[dbmctl]](OPEN //type// filename) \\ | ||
+ | $[[dbmctl]](OPEN_READ //type// filename) \\ | ||
+ | $[[dbmctl]](CLOSE //refnum//) \\ | ||
+ | $[[dbmctl]](ADD //refnum// "// | ||
+ | $[[dbmctl]](CHANGE //refnum// "// | ||
+ | $[[dbmctl]](DELETE //refnum// "// | ||
+ | $[[dbmctl]](READ //refnum// "// | ||
+ | $[[dbmctl]](NEXT_KEY //refnum// // | ||
+ | $[[dbmctl]](ALL_KEYS //refnum//) \\ | ||
+ | $[[dbmctl]](ERROR // | ||
+ | |||
+ | //refnum// is a value returned by OPEN and OPEN_READ. \\ | ||
+ | //type// must always be **STD** for now. \\ | ||
+ | // | ||
+ | //varname// is a dbm key. It is **always** a [[what is a word|dword]]. | ||
+ | //value// is a dbm value. | ||
+ | // | ||
+ | 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' | ||
+ | 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 // | ||
+ | | OPEN_READ | Return a refnum that can be used only for reading variables in the file // | ||
+ | | 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. | ||
+ | | 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! | ||
+ | | ERROR | Return the errno value for the last operation. | ||
+ | |||
+ | ======Notes: | ||
+ | Hash files use file descriptors, | ||
+ | connections to servers, and dcc, and so on, so you shouldn' | ||
+ | a bunch of hash files and ignore them forever. | ||
+ | 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 by 127.0.0.1