Readme Last Updated:  Sun Jan 18 16:52:19 GMT-8:00 1998

CONVDB Revision Number: 2.3

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


     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

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 on NT4.0 SP3.


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

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

   * 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.3 $

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]   : start
 %i       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)

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

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

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

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

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

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




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

Month, date, start_hour, event

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

Take a .45 and point it at .... alright, alright.


  1. First Line: First Line *MUST* be the field descriptor. This line
     cannot be anything else.
  2. Field Descriptor: The descriptors are case sensitive.
  3. Event String: Event description should preferably be the last field
     because delimiters are confusing for a string.



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

I have moved the sample text data to 2 files (example1.txt and
example2.txt). These files are correctly formatted so that you can use
convdb and see the results on your desktop.

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

convdb -m 10 example1.txt


Development History and,

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 :-)

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.netcom.com/~venkman1
(you can see this file at ~venkman1/Readme.html)




