Readme Last Updated:  Tue Jul 15 2000

CONVDB Revision Number: 2.7
Author: Narayan Natarajan
Email : venkman1@ix.netcom.com
Web   : http://www.geocities.com/Venkman69

T A B L E    O F    C O N T E N T S
===================================


     Preamble
     Description
     Program Notes
     What's new in the latest release?
     Usage
     How do you make a text file?
     Description of the flexible format text reading capability
     Field definitions within the text file
     Minimum Fields Required
     TroubleShooting
     Examples
     Development History & Bugs

Preamble:
==========

Skip this if you get bored with egotistical rantings...

Around October of 1997 I bought my PalmPilot Professional. At that time
there was no synchronization capabilities with different softwares and the
datebook database. My company decided to use Lotus Notes as the primary
vehicle and I found out quickly that it was irritating to try and manually
"sync" the information.

Just like everyone else I was surprised that there was no import feature in
the Palm software for datebook - well other than its own "dba" format. That
is when I thought it would be an interesting idea to try and figure out how
the format works and write an application. After searching on the web for
some resources on the datebook format.. and failing, I started to hack at
it with my favorite editor on the windows platform - elvis. That and quite
a bit of emailing to programming groups and generous support from several
people, plus finally finding Nico Seesle's rosetta stone for datebook, I
started getting a better picture of the whole format.

Unfortunately, I found that I still did not know some of the features of
the datebook format. And, fortunately, I found that some of the
gobble-de-gook could be spit out verbatim and it would work just fine.

After quite a lot of hours of coding late in the night the first release of
convdb started to materialize. By then things had started changing at my
work and I no longer had the need to sync with Lotus Notes anymore.
Sometimes I wondered what was my motivation to write the software after
that point. I must admit creating the software gave a lot of pleasure,
especially the part that it was helping a lot of people on the net. That
was one of my original intentions - I wished to contribute to the net in my
own little way. I felt a kind of belonging to the group of people that
create wonderful freeware and let it loose on the net to evolve and
proliferate.

About 8 months into the development, I had a bit of a setback. I'd moved to
wonderful Seattle and there was so much to do and see that...  "life"
happened :-) and convdb took the back seat. Fighting against losing
interest I tried to desperately finish programming the much needed "note"
feature. For nearly a year I dilly-dallied and the programming wouldn't
budge. Eventually I had to return to boring Michigan around end of 1998 and
that was not fun at all. So again convdb fell in its priority. Finally
around February of 2000 - a whole year later almost, on a cold sunday in
michigan, I took my laptop into a caribou coffee. For a good solid 4 hours
(until battery started to beep me) I kept at it and made a lot of headway.
Sometime later during the same month at the same Caribou Coffee, it kinda
snapped together. The bugs became evident and stuff just kinda .. worked.

That was when I realized all that I'd set out to do with the program was
finished. Sure there is always room for progress, but my personal desire to
finish the code was fulfilled. Now what? Quite honestly I vacillated
between wanting to make some money and setting it out free. The decision
finally was made when I spoke to my friend who said "you had fun writing
the code, that was the return for the effort you put in". I am sure the
majority of the population would think that that is such a brain-dead thing
to say, but I must admit that it did bring some kind of satisfaction. The
main part of that satisfaction coming from all the users sending me "thank
you" notes. In fact through which I ended up making a very good friend as
well. The desire to generate some cash flow out of this venture did not
really die, but sort of simmers. And therefore, here is a shameless pitch:
If you feel that you'd like to say thanks in a "financially beneficial"
way, then please send no more than $5 to:

Narayan Natarajan
2930 Olden Oak ln #201
Auburn Hills, MI 48326

I am not very certain of what I'd do with the money, but two things come to
mind:
1. to purchase a new Handspring Visor and sell/give my PalmPilot Pro
2. to donate it to charity.
In fact I leave it up to you to decide how you wish me to use any monies
that you may send and I promise to honor it.

I realize now at this point, that I don't have any more interest in
developing this software further. Although, I do have interest in seeing it
grow and be used, span across operating systems, gain a GUI, and be able to
identify fields without the use of all the funky header information, and
then sync right into the datebook without any more manual help. I am
therefore setting my source code loose for anyone to use and modify under
the GNU license. I hope that you find the code worthy of development and
request that you keep the development under the GNU umbrella.



Description:
============

CONVDB :
This utility converts a formatted text file to the datebook database
format. The output can be imported into the Pilot Desktop.

Program notes:
==============
C Program Compiled with mingw32 and Cygnus gcc for winNT/95/98 on Win98.


==========================================================================

What's new in the latest release?
=================================

   * CONVDB accepts a note! So far no bug reports have been sent back.
   * Internally, the code has been thoroughly revamped to be more modular.
   * I tested Y2K out on the program and it seems to work. "00" as year
     yields correct date format.


Previous release notes:
=======================

   * CONVDB is now capable of reading a flexible format text file. All it
     requires for this is a field description string as the first record.
     This field description is a requirement and must be added to existing
     conversion processes. In order for this to work (reliably) the event
     string must be the last field.

   * CYGWIN.DLL dependancy has been removed. I am using mingw32 libraries
     that allows me to compile without referring to cygwin.dll. You no
     longer need to keep this.

   * Private and Untimed events are supported.

   * Date and time I hope have been fixed finally

   * Added support for AM/PM

   * Added empty line support. Yes, I finally got off my lazy b*** and
     added it. Yes you can have empty lines in your datafile!

USAGE:
======

COVNDB works from the command prompt. There is no user interface.

CONVDB without arguments prints this message out:
-------------------------------------------------

Usage: convdb -[OPTIONS <value>] <filename>
        Alarm may be set globally:
        -m N     N minutes in advance
        -h N     N hours   in advance
        -d N     N days    in advance
        -x  e'x'plain more : Help
$Revision: 2.7 $

How do you make a text file?
==========================

The text file can be created manually using a text editor or by exporting
data from your scheduler. When exporting data from the scheduler, you can
usually define the fields that need to be exported. The most reliable
format would be a tab delimited format. As far as the event description
goes, do not include any delimiters such as quotes ("). Next you may need
to clean up this exported file if it has fields that do not conform to the
requirements of CONVDB. Once this is done, insert the field definitions
record as the first record in the file. Here are the basic requirements:


   * First record must be a "Field Definitions" record. See table below for
     a list of valid field definitions. Easiest way to create this is by
     copying the first record and editing its values to call out the field
     definition flags. This would make sure that the delimiters between
     each field are kept intact.

   * Each subsequent record is an entry in the schedule. Each record !MUST!
     follow the field definitions specified in the first record.

   * A '#' mark at the beginning of the file indicates that the record is a
     comment and must be skipped.

Description of the flexible format text reading capability
==========================================================

The flexible format allows you to have any group of characters as a
delimter. You could have for example: "gobble-de-gook" as the delimiter.
The only requirement, therefore, is that the *data* inside a field should
not contain this group of characters. Since, the record is parsed one field
at a time, the search for a delimiter group is forward. Meaning, if your
string had a tab which was used to delimit field #1, and say your event
string is the last field (therefore delimited by return character), then
your string may have tabs in it. This would not cause problems.
To illustrate:

     Field descriptor:
     %y<tab>%m/%d<tab>%h<tab>%v

     Record:
     98<tab>1/3<tab>10<tab>This string has a <tab> in it.

The event field, even though has a tab in it (which was the delimiter for
another field), does not have problems being read because *its* delimiter
is the end of line.


Field definitions within the text file
======================================



 Flag     Description        Type of value                Default Value

 %d       [d]ate             Number

 %y       [y]ear             Number, 4 digit or 2         Current Year
                             digit. Ex: 1998, 98

 %m       [m]onth            Number, String: 10, Oct,
                             October, Octo

 %h       [h]our: start      Number
          hour

 %i       [i]   : start min  Number                       zero

              (i follows h)

 %e       [e]nd : end hour   Number                       start_hour + 1

 %f       [f]: end min       Number                       start_min
              (f follows e)

 %t       [t]ime span:       Number: integral hours.      1 (hour)
          duration of event  Ex: 2 (hours)

 %r       [r]epeat flag      String:                      "None"
                             Date: Yearly by date
                             Day : Yearly by day of the
                             month
                             None: No Repeat

 %a       [a]m/pm: start     String/Char case ignored,
          time               only 1st character is
                             checked: A[M], P[M].
                             If field not specified
                             time is assumed to be in
                             24 Hr format.

 %b       [b] am/pm: end     -- ditto --
          time
             (b follows a)

 %p       [p]rivate flag     Boolean, case ignored: y,    N (not private)
                             n, 1, 0

 %u       [u]ntimed event    Boolean, case ignored: y,    N (not untimed)
          flag               n, 1, 0
                             Note: event must have some
                             number (dummy value) in
                             the time fields even if it
                             is untimed.

 %v       e[v]ent.           String: Preferably be the
                             last field.
                             Multi-line string not
                             supported because return
                             character is considered to
                             be end of record.

 %n       [n]ote             This is NOT a FIELD!!!
                             Note FOLLOWS the record in
                             lines of text. The END of
                             a note is denoted by a
                             single PERIOD (.) all by
                             itself on a line.

                             The delimiter for '%n'
                             could be anything, but
                             keep it simple and make it
                             a a space or a tab.

                             NOTE:  !!! YOU MUST HAVE A
                             PERIOD EVEN IF YOU DON'T
                             HAVE A NOTE FOR THAT
                             RECORD !!!



Minimum fields required:
========================

Month, date, start_hour, event

TroubleShooting:
================


  1. Field Descriptor: The descriptors are case sensitive.
  2. Event String: Event description should preferably be the last field
     because delimiters are confusing for a string.
  3. Note feature NEEDS a PERIOD all by itself to denote end of note.

E X A M P L E S
===============

The examples are included in this package in form of example1.txt,
example2.txt and so on. Open them in a text editor and see how the fields
have been formatted. Suggestion: Use Notepad and not Microsoft Word or some
hefty application to read the text.

Example : To add an alarm 10 minutes prior to every event in the file:

convdb -m 10 example1.txt


Development History and Ideas for the future:

IDEAS for the future:
=====================


  1. Port convdb to other OSs
  2. Make a GUI for creating the flexible record header (something like
     Excel's import feature). Probably using some portable language like
     tcl/tk etc.
  3. Have the records written AS they are processed so that it requires
     less memory to process the records. Or write a temporary file and then
     spit out a dba file.

BUGS! ( Eeeeeeek! take that! and that! and that! *splat*):
=====================================================================
(Seems like the bug list grows as I improve(?) the converter)

Fri Jan 16 20:03:26 GMT-8:00 1998:
----------------------------------

     Major release. Following added/modified/fixed:
        o Flexible format text file reading capability added
        o Date/time works (quite sure :-)
        o CYGWIN.DLL dependancy removed
        o Untimed and Private flag support added
        o AM/PM time format support added.

     Bugs Fixed:

        o There was a problem if the events were early in the morning. I
          think it is now fixed.
        o The event description used to have a return character code at the
          end. This has been removed because if the entry is copied or
          edited pilot desktop displays a block character. This character,
          however, is not displayed while browsing.
        o The event description only allows 256 characters. In my code I
          hack of the rest of the string in case it is longer. Although,
          due to some strange reason it seems to work only for 254
          characters. So in fixing a bug I have created another? Damn! Oh,
          well... :-)

Tue Dec  9 23:10:21 GMT-8:00 1997:
----------------------------------

     New! Improved! Added memory management. Now you may convert to your
     heart's content! millions, even billions of records can be converted!
     (... if it works :-)

     Note: This is now limited by your computer's memory settings alone.

Mon Dec  8 22:45:26 GMT-8:00 1997:
----------------------------------

     I goofed on the number of records, its 99 not 100.

Earlier:
--------

     Found another bug regarding time across the GMT ( UTC ..whatever ) I
     think I have fixed this and the bug above just keep a look out for the
     modification date in the download page.

Earlier still:
--------------

     For some reason April 2nd, 3rd, 4th, and 5th the time goes back by 1
     hour. So an appointment on april 4th at 8:00 am would end up at 7:00
     am. I have'nt had time to look into this. I think it has something to
     do with the daylight savings time.

- Narayan Natarajan aka Venkman
E-mail: venkman1@ix.netcom.com
Web   : http://www.geocities.com/Venkman69



