Out of the need for datebook data conversion and correction, I've created a little program which supports this very well. Since I think this program will also be very useful for many other people I decided to publish it. I've placed it under the GPL because I have enjoyed the benefit of this source model for a long time (using pilot-link, and Linux) - this is my opportunity to give something back to the community, for everyone to benefit.
It was my intension to get pilot-datebook included in pilot-link, the Unix hotsync tool for Palm OS devices. Unfortunately, I was only temporarily successful with this, for pilot-link versions 0.10.x and 0.11.x. Pilot-datebook compiles against pilot-link libraries, therefore pilot-link needs to be installed before pilot-datebook.
For future work, and known bugs please have a look at the file pilot-datebook-todo.txt, which is part of the pilot-datebook tar file.
Please enjoy, and let me know whether you like it. I think it is in a fairly stable state. Unless someone convinces me otherwise, I'll only do bug fixes. However, if you want to contribute - patches are always welcome!
For any suggestions or comments, please write me at:
You can download the latest pilot-datebook tar file from: pilot-datebook-20020224.tar.gz (174627 bytes)
For your convenience, here is also the source code for pilot-link 0.9.5: pilot-link.0.9.5.tar.bz2. Please note that the latest version of pilot-link is always available from http://www.pilot-link.org. In the versions 0.10.x and 0.11.x of pilot-link, pilot-datebook was already included. With the version 0.12.0 pilot-datebook had been removed from pilot-link without me knowing about this. It would have been nice if someone had told me about it beforehand...
The following text is from file pilot-datebook-readme.txt, which is also included in the pilot-datebook tar file:
WHAT IS IT? 'pilot-datebook' has been intended to be the 'Swiss Army Knife' for datebook related data manipulation. The main strengths of pilot-datebook are the number of data formats it supports for import/export (including csv, plain text, Windows desktop format), and its manipulation abilities. HOW DO I INSTALL IT? To install pilot-datebook you need the latest pilot-link version (currently pilot-link 0.9.5) first. pilot-datebook can be installed on top of this pilot-link version in the following way: * Untar source code: tar xf pilot-datebook-20020224.tar * Add the following lines to Makefile.in: pilot-datebook$(EXT): $(PILIB) $(GETOPT) \ pilot-datebook.o pilot-datebook-data.o \ pilot-datebook-joblist.o pilot-datebook-job.o pilot-datebook-sort.o \ pilot-datebook-update.o pilot-datebook-compare.o pilot-datebook-io.o \ pilot-datebook-pdb.o pilot-datebook-csv.o pilot-datebook-longtxt.o \ pilot-datebook-hotsync.o pilot-datebook-remind.o pilot-datebook-ical.o \ pilot-datebook-shorttxt.o pilot-datebook-windat.o parsedate.o $(CCLINK) pilot-datebook.o pilot-datebook-data.o \ pilot-datebook-joblist.o pilot-datebook-job.o pilot-datebook-sort.o \ pilot-datebook-update.o pilot-datebook-compare.o pilot-datebook-io.o \ pilot-datebook-pdb.o pilot-datebook-csv.o pilot-datebook-longtxt.o \ pilot-datebook-hotsync.o pilot-datebook-remind.o pilot-datebook-ical.o \ pilot-datebook-shorttxt.o pilot-datebook-windat.o parsedate.o \ $(PILIB) $(GETOPT) -o $@ $(LIBS) [the character in front of $(CCLINK) has to be a tab, make sure you change it accordingly when copy & pasting] * Run './configure' This should generate a new Makefile which contains the above lines. * Run 'make pilot-datebook' This should compile the source code and eventually generate an executable. * Run 'pilot-datebook -h' This should start the program and display a short summary screen on how to use it. An overview of all available help screens can be seen when calling 'pilot-datebook -hhelp'. * Go to subdirectory pilot-datebook-test cd pilot-datebook-test * Run 'test_all' This will run various tests which ensure that pilot-datebook runs properly as intended by the author. The test script will abort if an error is encountered. If all tests are passed, then it should be safe to use pilot-datebook. * Enjoy! You might want to have a look at the various test scripts for samples on how to use pilot-datebook. For an especially complex update/read/write example have a look at script 'test_update_complex'. For the conversion help screen use 'pilot-datebook -hconvert' (it also explains how to replace the existing pilot-link tools 'install-datebook', 'reminders', 'read-ical'). Matthias Hessler email@example.com http://www.mhessler.org/pilot-datebook/ ADDITIONAL NOTES: Please note that so far pilot-datebook has been developed and tested in a Linux environment (Suse 7.0, Kernel 2.2.16). Although the author has tried to not endanger portability, porting to other platforms has not been attempted so far. Usual disclaimer: use pilot-datebook at your own risk, it may corrupt your data. Absolutely no warrenty! By using pilot-datebook you agree to these terms. In particular, pilot-datebook does not do any consistency checks for your data (i.e. it will not prevent you from having appointments which begin today, and end yesterday - hotsync will crash on these things).
The following text is the help output you can get from pilot-datebook when calling it with its various help options:
# pilot-datebook -h pilot-datebook 0.98 (c) 2000 by Matthias Hessler usage: pilot-datebook [options] [[command] [cmd_options] [@optfile]...] Mostly: pilot-datebook -r <in_fmt> -f <in_file> -w <out_fmt> -f <out_file> or: pilot-datebook -r <in_fmt> -w <out_fmt> < <in_file> > <out_file> [use pilot-datebook -hconvert to see command line examples] [options]: -q quiet mode -v verbose/debug mode -h show this help -hhelp show overview on all available help screens [command]: -i <cond> only do next command if <cond> is true -r <fmt> read file with format <fmt> (ignoring -i) -w <fmt> write file with format <fmt> -s <order> sort rows by <order> (ignoring -i) -u <assign> update rows according to <assign> -d delete rows (only useful with -i) [cmd_options] (for read/write): -f <file> read from <file>/write to <file> (default: stdin/stdout) # pilot-datebook -hhelp pilot-datebook 0.97 (c) 2000 by Matthias Hessler (use pilot-datebook -h to see usage) Available help screens: -h show usage -hhelp show overview on all help screens -hfield show supported data field names -hftype show supported data field types -hformat show supported data formats for <fmt> -hif show information on how to specify <cond> for conditions -hsort show information on <order> for sorting -hupdate show information on <assign> for updating -hconvert show command line examples for data conversion (read/write) -hcsv show information on csv import/export # pilot-datebook -hfield pilot-datebook 0.97 (c) 2000 by Matthias Hessler (use pilot-datebook -h to see usage) Available data fields (for use in <fmt>, <order>, <assign>): * uid (long) * attributes (int) * category (int: 0=Unfiled) * untimed (int: 0=Appointment, 1=Untimed) * begin (time) = beginDate (time) + beginTime (seconds) * end (time) = endDate (time) + endTime (seconds) * alarm (int: 0=no alarm, 1=alarm) * advance (int), advanceUnit (int: 0=minutes, 1=hours, 2=days) * repeatType (int: 0=none, 1=daily, 2=weekly, 3=monthly, 4=monthly/weekday, * repeatForever (int: 0=not forever, 1=forever) 5=yearly) * repeatEnd (time) * repeatFrequency (int) * repeatDay (int: day# or 0..6=Sun..Sat 1st, 7..13 2nd, 14..20 3rd, 21..27 4th, * repeatWeekstart (int) 28-34 last week) * repeatWeekdays (int: add - 1=Sun,2=Mon,4=Tue,8=Wed,16=Thu,32=Fri,64=Sat) * description (str) * note (str) * xLong,yLong,zLong (long), xInt,yInt,zInt (int), xTime,yTime,zTime (time), * xSeconds,ySeconds,zSeconds (seconds), xStr,yStr,zStr (str) # pilot-datebook -hftype pilot-datebook 0.97 (c) 2000 by Matthias Hessler (use pilot-datebook -h to see usage) Available data field types: * long (is 'unsigned long' in C) Examples: '123456789','987654321' * int (is 'int' in C) Examples: '123456','654321' * time (is 'struct tm' in C, but will be converted to time_t for calculation) Examples: '27 oct 1968 19:15','1968-10-27 19:15','27 oct 1968','1968-10-27' * seconds (is 'long' in C) Modifiers 'd','m','h' are possible (days, minutes, hours); alternatively specify in form 'x:y:z' (hours:minutes:seconds). Time field assignments will use 'seconds modulo 86400'. Examples: '86400','1d','24:' (= 1 day) Examples: '3600','1h','1:' (= 1 hour) Examples: '60','1m','0:1' (= 1 minute) Examples: '1','0:0:1' (= 1 second) * str (is 'char *' in C, requires strdup) String literals have to be surrounded by single or double quotes. String literals may quote characters with backslash (like printf). Examples: "String1", "String2,line1\n\t\"String2\",line2" # pilot-datebook -hformat pilot-datebook 0.97 (c) 2000 by Matthias Hessler (use pilot-datebook -h to see usage) Available data formats (for <fmt>): * hotsync direct connection to pilot (read & write) * pdb pilot database file format (read & write) * windat file format for Windows desktop (read & write) * csv comma-separated values format (read & write) * longtxt human-readable text file format (read & write) * shorttxt install-datebook import text file format (read & write) * remind reminders import text format (write only) * ical ical import text format (write only) Please note: * File formats hotsync, pdb, windat, and longtxt are almost lossless * csv can be lossless with the exception of repeat exceptions * Use command line option -l to set the desktop file location for windat * See separate help screen for csv format (-hcsv) # pilot-datebook -hif pilot-datebook 0.97 (c) 2000 by Matthias Hessler (use pilot-datebook -h to see usage) Condition: -i "<cond>" * <cond> specifies a list of conditions * Multiple conditions can be listed with ';' in between (= AND). * Each condition consists of: <field> <operator> <value> * <field>: has to be a field name * Use pilot-datebook -hfields to see available data fields * <operator>: use '==' for equal, '!=' for not equal, '<' for less, * '<=' for less or equal, '>' for greater, '>=' for greater or equal * <value>: currently has to be a literal * All listed conditions within <cond> are connected with AND * Multiple definitions of -i will be connected with OR Example: -i "alarm=0" -u "alarm=1;advance=5;advanceUnit=0" [if no alarm is set, then set alarm to 5 minutes before] or: -i "begin<27 oct 1988 10:13" -d [delete all rows which begin before 27 Oct 1988 10:13] # pilot-datebook -hsort pilot-datebook 0.97 (c) 2000 by Matthias Hessler (use pilot-datebook -h to see usage) Sort: -s "<order>" * <order> specifies a list of sort fields * Multiple sort fields can be listed with ';' in between * Use pilot-datebook -hfields to see available data fields * Rows are compared first on their first sort field. If those are equal, then the second (then third,...) sort fields are compared * Add '+' for ascending, '-' for descending order before sort field name * Use '-s ""' to buffer all rows unsorted (avoids straight-through processing) Example: -s "alarm;advanceUnit;advance" [default = ascending sort order] or: -s "-alarm;-advanceUnit;-advance" [descending sort order] # pilot-datebook -hupdate pilot-datebook 0.97 (c) 2000 by Matthias Hessler (use pilot-datebook -h to see usage) Update: -u "<assign>" * <assign> specifies a list of assignments * Multiple assignments can be listed with ';' in between. * Each assignment consists of: <field> <operator> <value> * <field>: has to be a field name * Use pilot-datebook -hfields to see available data fields * <operator>: use '=' to assign, '+=' to increase, '-=' to decrease * <value>: currently has to be a literal * String literals have to be surrounded by single or double quotes * String literals may quote characters with backslash (like printf) * All listed updates are carried out Example: -u "alarm=1;advance=5;advanceUnit=0" [set alarm: 5 minutes before] or: -u "note+='\nadditional\tcomment\;line1\nline2'" [add text to note] # pilot-datebook -hconvert pilot-datebook 0.97 (c) 2000 by Matthias Hessler (use pilot-datebook -h to see usage) Examples for data conversion (read/write): * Drop records starting before 1971: pilot-datebook -r pdb -f in.pdb -i "beginDate<1Jan1971" -d -w pdb -f out.pdb * Export in.pdb into clear text file out.txt: pilot-datebook -r pdb -f in.pdb -w longtxt -f out.txt * Import clear text file in.txt and write desktop file datebook.dat: pilot-datebook -r longtxt -f in.txt -w windat -f datebook.dat * Behave like pilot-xfer -f DatebookDB (read hotsync, write to pdb): pilot-datebook -r hotsync -f /dev/pilot -w pdb -f DatebookDB.pdb * Behave like install-datebook (read shorttxt, write hotsync): pilot-datebook -r shorttxt <in_file> -w hotsync -f /dev/pilot or (for multiple files): cat <files> | pilot-datebook -r shorttxt -w hotsync -f /dev/pilot * Behave like reminders (read hotsync, write to stdout): pilot-datebook -r hotsync -f /dev/pilot -w remind * Behave like read-ical -d (read hotsync, pipe to ical): pilot-datebook -r hotsync -f /dev/pilot -w ical | ical -f - -calendar <filename> # pilot-datebook -hcsv pilot-datebook 0.97 (c) 2000 by Matthias Hessler (use pilot-datebook -h to see usage) CSV (comma-separated values) import/export (read/write): * The CSV format is well understood by many programs, especially by spreadsheet programs * Two additional [cmd_options] are supported: -o and -t * -o <output_value_list> specifies a comma separated list of output values * The default for <output_value_list> includes all printable data fields * All data fields can be used in <output_value_list>, even transient internal data fields like the x/y/z variables * -t <header_value_list> specifies which header to write/expect in the file * <header_value_list> can be empty to indicate that no header line should be written/expected in the csv file * If <header_value_list> has been provided, then it has to match * If <header_value_list> is just "*", then it will always match * Field names may be quoted; unknown field names can be matched with '*' * If only <output_value_list> was provided, then it will also be used as <header_value_list> * If neither <output_value_list> nor <header_value_list> have been provided, then default will be used for writing, and encountered header for reading * You can use 'Outlook' as <header_value_list> to get compatible format which can be read by Outlook. Outlook output can be difficult to read, since it uses the local date format for writing, which may be difficult to parse. * Outlook does a different quoting for newlines, therefore avoid those for now.
(c) 2001 by Matthias Hessler