SYNCAL

Section: User Commands (1)
Updated: USR Pilot tools
Index
 

NAME

syncal - synchronizes an ical(1) calendar file and with a Palm device DateBookDB database  

SYNOPSIS

syncal [-a archive_file] [-c calendar_file] [-d pilot_device] [-h] [-l][-n] [-p private_text] [-q] [-s] [-u username] [-v] [-3]

 

DESCRIPTION

syncal reads a current ical calendar file, an archived ical calendar file from the last time syncal was run, and a Palm device DateBook database and reconciles them. It creates a new ical calendar file which replaces both the current and archived ones and updates the Pilot DateBookDB to coincide with them.

Once syncal is started, the user must invoke HotSync on the target device.

 

REQUIRES

You will need the pilot-link libpisock library installed. I am using pilot-link.0.9.1. See ftp://ryeham.ee.ryerson.ca/pub/PalmOS/ to get this. Also a version of ical later than 2.0 is necessary. I recommend 2.2. The ical home page is at http://www.research.digital.com/SRC/personal/Sanjay_Ghemawat/ical/home.html

 

OPTIONS

-a archive_file
Use archive_file as the archive from the last synchronization. The default is $HOME/.syncal/calendar.archive This is dangerous if the file was not actually produced by syncal.

-c calendar_file
Use calendar_file as the current ical calendar. This file will be renamed by appending ".bak" to is name and the new calendar file will be created with the original name. The default default ical calendar file is $HOME/.calendar

-d pilot_device
Uses pilot_device as the target device to which the pilot is assumed to to be attached. The default is /dev/pilot. If the environment variable PILOTPORT is set, its value will override the default, but a target device set with this command-line option will be used regardless of any PILOTPORT setting. If the single character '.' is used instead of a device name, syncal will expect a network connection from a Palm device attached to a remote computer. See NETWORK SYNCS below for more details.

-h 
Prints version information and the usage message.

-l 
Show changes in linked categories (see datebk3/4 support below). Normally items in linked categories are deleted and recreated each time syncal is run and it is not desirable to have these numerous changes displayed with the -v option. The -l option causes all these changes to be displayed in the same way regular changes are displayed with the -v option.

-n 
No-action. This option causes syncal to write all information provided with the -v option to standard output, but to do nothing else. No files are changed and the contents of the Pilot remain unchanged.

-p private_text
Your private entries on the Palm device are supressed on an ical calendar with private_text entry.

-q 
Quiet This option causes syncal to suppress the output to stdout of any messages including errors. In particular with this option syncal will not prompt for the user to press the HotSync button (as it does when this option is not invoked).

-s 
hide_Secret This option hides private entries from the Palm device totally to the ical calendar.

-u username
Causes syncal to install 'username' as the user name on the Palm device. This name will henceforth be used as the contents of the "Owner" field of any ical calendar entry which is created by importing an entry from the Palm device to an ical calendar. You only need to do this once. The Palm device will remember thereafter.

-v 
Verbose. This option causes syncal to write a brief description of each appointment to standard output as the appointment is being inserted into the pilot DateBookDB from the calendar file or as it is being inserted into the calendar file. Deletions are also reported. With this option syncal also prompts for the user to press the HotSync button.

-3 

This indicates that datebk3/4 is being used on the Palm device as the calendar manager. This option need only be used once as the use of datebk3/4 will be remembered and recorded in the syncal.archive file. See DATEBK3/4 SUPPORT below for more details.

 

USAGE

syncal reads a current ical calendar file, an archived ical calendar file from the last time syncal was run, and a Palm device DateBook database and reconciles them. It creates a new ical calendar file which replaces both the current and archived ones and updates the Pilot to coincide. The previous archive file and calendar file are saved with their names changed by adding the suffix ".bak".

If an entry in the calendar file or on the Pilot is new since the last time syncal was run, it is added to the the new reconciled list. If a previous entry has been changed on either the Pilot or by ical the new version is used. If the entry has been changed in both the Pilot database and the ical calendar file, the version from the Pilot is used.

The Pilot DateBookDB supports notes attached to an appointment or event while ical does not, but can handle larger text items in its entries. Accordingly syncal translates a DateBookDB entry with description and note by appending the note to the description, separating them with a blank line, and using this as the ical entry contents. Translating in the other direction, when the first blank line is encountered in a ical entry, everything prior to it is used as the DateBookDB appointment description and everything after it is used as an attached note.

Syncal preserves the Owner field of ical calendar entries and adds one to new entries from the pilot if the PilotUser field username is set. See th -uoption above to install a name as the username on the Pilot.

Like other programs based on the pilot-link library libpisock the syncal program will check the environment variable PILOTRATE to set the transfer rate of the serial connection between the computer and the Palm device. The default rate is 9600, but rates as high as 115200 work fine on many systems. To customize the rate (say to 57600) initialize the PILOTRATE variable in your login startup script. Depending on the shell you use this might involve adding the line "PILOTRATE=57600; export PILOTRATE" or the line "setenv PILOTRATE 57600".

 

DATEBK3/4 SUPPORT

As of version 0.7.X syncal supports some features of the datebk3 Pilot application which is an alternative to the standard Palm DateBookDB. See http://www.gorilla-haven.org/pimlico/datebk3.htm for more information about datebk3.

As of version 0.8.6 syncal supports the extended features of the datebk4 Pilot application by correctly handling the larger hidden tags in the Note field of appointments. See http://www.pimlicosoftware.com/datebk4.htm for more information about datebk4.

The features supported by syncal include support for categories and for floating todos. To use these features simply create a new category or floating todo on the Palm device with datebk3. Floating appointments will henceforth be converted to "todo" items for ical automatically.

Categories on the pilot are converted to subsidiary calendar files for ical and these files are kept in the .syncal directory. For example, if you create a category in datebk3/4 called "Work" and create appointments in it or change the category of existing appointments to it, then syncal will create an ical calendar file called ".syncal/Work" containing these appointments. These appointments will not be included in the main ical calendar file. Hence the first time you use ical after creating a category, items in the category will not be visible. To view them you must select the "File/Include Calendar" menu item in ical and add the calendar file .syncal/Work. Which categories are visible in ical depends on which calendars have been included or excluded and this state is maintained over ical sessions and syncs with syncal. In general the name of the ical calendar file corresponding to a category is obtained by taking the category name, converting spaces and some other characters to '_'. Categories should be created and removed on the Palm device.

In some cirumstances it is useful to have categories for which the ical entries take precedence over pilot entries or vice versa. These are called Ical dominant or Pilot dominant categories respectively. and they are created by renaming the category file in the .syncal directory so that it ends with the suffix ".Ical" or ".Pilot". Thus, for example, if you create a category named "Meeting Sched" on the Palm device and run syncal, a file named ".syncal/Meeting_Sched" will be created. If you rename this file "Meeting_Sched.Ical" (or replace it with a symbolic link by this name) then the entries in this file created by Ical will always take precedence over what has been done on the Pilot. When a sync is done this file will be unchanged and the entries on the Pilot will be modified to coincide with the entries of this file. Similarly if this file is renamed with a ".Pilot" suffix, each sync will not change any entries for this category on the Pilot, but will modify this file to reflect the entries with this category on the Pilot.

 

CUSTOMIZING ICAL

A tcl customization for ical is included in the file user.tcl. It should be installed as $HOME/.tk/ical/user.tcl where $HOME represents the user's home directory. This will create a new item labelled Sync with Pilot on the ical File menu. You may then run syncal from within ical by selecting this menu item, clicking "Okay" on the subsequent dialog box and then pressing Hotsync button on the Pilot cradle. The syncal executable must be in your path.

The user.tcl file also creates a new Item menu entry called Move Entry to which enables shifting an ical entry from one file to another. This is necessary to change the category of an item (see datebk3/4 support above).

 

LIMITATIONS / BUGS

Any included calendars in the ical calendar file being processed will be ignored but the request to include them will be present in the new calendar file which syncal produces.

The repeated date formats possible with ical those possible with the Pilot do not precisely coincide. For example, The second from last Thursday of every month is possible with ical, but not on the pilot. And Monday, Wednesday, and Friday of every third week is possible on the Pilot but not in ical. syncal understands the intersection of the two sets of formats. Thus you may specify Monday, Wednesday, and Friday of every week, but not every third week. And you may specify the last week of every second month, or the second week of every second month, but not the second from last week of every month. One inconsistency is that an appointment entered in ical for the fifth Wednesday of every month will display in ical only in months which have five Wednesdays, but will display as the last Wednesday of every month on the Pilot. After running syncal this appointment will be changed in the ical calendar to the last Wednesday of every month.

syncal does not interact with the Palm device ToDo list. If an ical item is marked 'todo' or the todo box is checked. This information will be preserved in the ical calendar as long as the Palm device does alter the entry. The 'todo' or 'checked' information is not representable in the Palm DateBookDB. If an entry is created on the Palm device it will not have the 'todo' property, and if it is even altered on the Palm device this property will be removed.

 

NETWORK SYNCS

Like all programs based on the pilot-link library libpisock the syncal program can synchronize between a host on which syncal is running and a Palm device physically attached to a remote client. This presupposes a working TCP/IP network connection between the client, computer A, and the host, computerB.

On the Palm device, in the HotSync preferences menu, in the primary PC setup, set the name of host B, and its IP address. In the HotSync Prefs / LANSync Prefs set LANSYNC.

Connect the Pilot to a cradle attached to client A. On client computer A, run pi-nredir /dev/pilot.

Now telnet to host B and run syncal -d . -v on host B. The use of the device '.' indicates that the program should use a network connection rather than a serial port to connect to the Pilot.

Finally press the Hotsync button on the Pilot cradle.

The security of this process leaves a great deal to be desired. A better way to do this is use the secure shell ssh(1). I do this as follows. On the Pilot, I set primary PC to "localhost", 127.0.0.1. If my Palm device is physically connected to host.A and I want to sync with host.B, from host.A I run
  ssh -L 14238:host.B:14238 host.B
  This logs me in to host.B where I run syncal-d . -v Back on host.A in another window, I run pi-nredir /dev/pilot and then press the Hotsync button.
  This works because ssh forwards the local port 14238 to port 14238 on host.B over an encrypted channel. pi-nredir communicates with the local port 14238 and pilot-xfer connects to 14238 at the host.B end.

An alternative method staying completely on host. A would be to run

ssh -L 14238:host.B:14238 host.B syncal -d . -v

and then run pi-nredir /dev/pilot.

 

SEE ALSO

ical(1), read-ical(1), pilot-link(1) ssh(1)

 

VERSION

This man page documents version 0.8.6 of syncal. The -h option will display the version which is being used.

 

AUTHOR

Syncal was written by John Franks, <john@math.nwu.edu>. Several people deserve thanks for providing suggestions, bug fixes and enhancements. They include Dennis Director, Tessa Lau, Dominik Madon, and Kaj Mustikkamäk.

 

LICENSE

syncal is free software licensed under the GNU Public License.


 

Index

NAME
SYNOPSIS
DESCRIPTION
REQUIRES
OPTIONS
USAGE
DATEBK3/4 SUPPORT
CUSTOMIZING ICAL
LIMITATIONS / BUGS
NETWORK SYNCS
SEE ALSO
VERSION
AUTHOR
LICENSE