no way to compare when less than two revisions

Differences

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

@@ 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.