Site Tools


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,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'
 +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 by 127.0.0.1