dbdb - the database datebook, or vice-versa. by aaron brick, aa@lithic.org 8/1998 - 3/2000, under professor scott smith. released under the GPL. OVERVIEW dbdb is a fairly complex and robust environment for storing, retrieving, and manipulating entries in a datebook. each entry can contain a good deal of specificity beyond its main text: a category, a priority, text fields for notes and location, dependency on another entry, etc. a daemon server runs on any network-accessible host; various client implementations can run on any networkable machine, or the same one which hosts the daemon. this file describes the default client, which has a command-line interface. the client is started without any options. it connects to the server based on the username and machine in question, and when that succeeds, presents the user with a prompt from which to execute commands within the system - a simple "dbdb shell". the commands are styled after traditional UNIX command-line program options: switches and options are denoted by a character preceded by a hyphen; options are followed by a piece of data separated by whitespace. see below for examples. PRIMARY OPERATIONS the user must specify one of five primary operations: add entry -a [options] category ops -c [category] help -h remove entries -r [options] [substring] show entries -s [options] [substring] -a requires that the user pass the entry text. a number of options can be optionally specified. -c by itself will yield a list of available categories along with the number of entries which belong to each one. if a string is passed, that category is either removed or added, depending if it existed beforehand. the program will not remove categories to which entries still belong. -h displays a summary of the syntax. -r removes the entries which match the options and entry text substring passed. it requires the use of -F (force) to remove multiple entries at a time, as a safeguard. -s shows the entries in question, ordered by the earliest of the start and end times (failing that, they are ordered by ID number). it will show entries in the brief form unless -f (full records) is also passed. note that the syntax for remove and show are nearly identical, so that one can give a list of arguments with -s and then remove the same set by passing -r. OPTIONS -A signifies that the operation at first affect _all_ records, as opposed to the default of only the parents of dependency hierarchies. it is valid with -s and -r. -b is the way to pass an entry's start or event time. the argument must be in the form 11/11/98,4:20pm, as adjusted by the time_style and date_style preferences (e.g., could be "...16:20"). you may use whatever neutral punctuation you want (except hyphens), or specify only certain parts of the time information, as long as the numbers appear in the expected order. a hyphen indicates a non-specified variable (see "vague and recurrent timings"). -d refers to a dependency (a child). with -a, it means that the new record will depend on . with -r or -s, it refers to those records which depend on . -D is the opposite of -d: the parent. with -a, it makes the specified entry depend on the new one. with -r or -s, it refers to the entry upon which the current entry depends. -e specifies the entry's end time, with the same characteristics as -b. it is also used for deadlines. -f along with -s means to show a "full" record - a lengthier, more detailed printout of the entries in question. the data includes classifications as follows: event has start date/time period has start and end dates/times deadline has end date/time todo has no date/time specifications -F is for forcing a remove operation on multiple entries. -i specifies the id number of a single entry with -s or -r. this option has the highest priority of all the specifiers; if you enter a -i with any other details, only the id specification will count. -I indicates that the record with the given id and all its dependents, any number of generations deep, should be affected by the given operation. it is valid with -s and -r. -l specifies the location, a text string, of an entry. it can be used with -a, to add a record with this attribute, or in -r or -s to specify one or more entries with this as a case-sensitive substring. -n behaves just like -l . -p is a numeric value. if used with -r or -s, it can be optionally prefixed with a plus or minus. for -a, it only makes sense to enter a plain number. higher numbers are higher-priority. with -r and -s, n refers to all entries of priority n; +n, to all those more than n; and -n, to all those less than n. -u is a date/time in the same format as -b and -e. used with -s and -r, it means to affect entries with a start or end date before the one passed. -y specifies a category. with -a, it stores the new event as belonging to the category specified; with -s or -r, it restricts the results to events belonging to that category. note that if any option with argument is given more than once, or if two conflicting options are passed, it is the second of the two which is used. FILES on the server, the daemon creates and uses the directory /var/dbdb/machinename/username/ (or as respecified in the header file) to store its data and preference files. the data files are not human-readable; the preferences file is. the preference file's format is simple (and not too tolerant). lines beginning with # (comments) and blank lines are ignored; all others are processed and will generate errors if they don't fit the syntax. there are about a half dozen options, each of which is set by a number. for those options where a numerical setting is not obvious, the comments in the file explain the valid values to use. DEPENDENCY SYSTEM the dependency system is hierarchical; any number of entries may depend on another (single) entry, to any depth. if an an entry is a dependent, it does not appear in -s or -r operations unless specified with the -A or -d switch, or matching criteria that its parent does not. the entries shown in a -s operation are prefixed with an indicator of their dependency status. if an entry has dependents, it is prefixed with a +; if it is a dependent, a -. in the case that the entry both depends and is depended on, a ± will be shown. VAGUE AND RECURRENT TIMINGS dbdb allows the use of timings with various fields not specified. this functionality can be used for recurrent events (eg, a monthly task) or when certain specificity is not appropriate (eg, someone stopping by at an unknown time on a given day). a hyphen (`-') in the argument of a -b or -e, in place of a numeral, indicates this inaccuracy. when evaluated, these entries are sorted as having a start or end time equal to the next occurence of the given timing; eg, as of november 29, 1998, at 9:16 pm, my entry with start timing "-/2/-,1:00pm" will appear as if it were a fixed "12/2/98,1:00pm". COMPILING i doubt dbdb will run under anything but UNIX. its development platform is linux 2.2.14 (debian 2.2), running gcc 2.95 and gdbm 1.7.3. when it has been successfully compiled on other OSs they will be listed here. ACKNOWLEDGEMENTS philip a. nelson, author of gdbm, for his advice and troubleshooting. scott smith, my advisor, for his support and suggestions. ramin takloo-bighash, for his work on the prediction algorithm. gdb, the GNU debugger, without whom, etc.