================================================================================
aSync: A synchronizer of Psion's Agenda with iCalendar
Version 1.18 (29 May 2009)
Noriyuki Mihashi
================================================================================
[Contents]
1. Summary
2. System reqirement
3. Installation
4. Uninstallation
5. Usage (Preparing)
6. Usage (Dairy tasks)
7. Usage (Details)
8. Note
9. Licences
10.Changes history
Thanks
Thanks to all people for giving me great helps to make this program.
Mr. Reishi Kondo:
For developping the MD5.OPX, and for adding a new function by my request.
Mr. Peter Cheyne:
For checking and giving advices to correct my strange English messages.
Mr. Jean-Baptiste Giraud, Mr. Kevin Moloney:
For finding and reporting serious bug. (Ver.1.02)
Mr. Quintin:
For giving me an idea of supporting Mozilla Calendar. (Ver.1.10)
Mr. Pierre Ferriere:
For giving me an idea of turning off calendar ID verifycation. (Ver.1.13)
Mr. Nicholas Law:
For finding and reporting serious bug. (Ver.1.14, 1.16)
For correcting a lot of mistypes and strange expessions in this document.
(Ver.1.15)
Mr. Fredi Brost:
For finding and reporting a new bug. (Ver.1.17)
1. Summary
This program makes it possible to sync calendar data of Psion's Agenda with
Mac's iCal. It works as a Psion application and functions with Agenda and
iCal files on Psion's file system.
* Version 1.10 or later
Other than iCal, it also supports calendar files of Mozilla (Calendar or
Sunbird). If you want to sync Agenda with Mozilla, read 'Mozilla' for
'iCal' in this document. My apologies to Mozilla users, who will have to
work out the details for themselves.
Syncing is achieved by following these steps:
1) Tranfer the iCal file from your Mac to your Psion.
2) Start the aSync application and do sync.
3) Transfer the iCal file back from your Psion to your Mac.
2. System reqirement
aSync has the following system requirements:
- Mac OS X (Ver.10.2 or later) and iCal on your Mac.
Mozilla Calendar on various platforms is also supported.
- Utilities that can transfer files between your Mac and your Psion.
* Java Psion Link is recommended.
(http://sourceforge.net/projects/javapsionlink)
- Psion Series 5, 5mx, Revo or other compatible EPOC machines.
- MD5.OPX (Ver.0.03 or later) installed on your Psion.
* MD5.OPX is an OPX to calculate MD5 checksum and was developed by
Mr. Reishi Kondo. (http://www01.upp.so-net.ne.jp/rey/)
3. Installation
Before you install aSync, get MD5.OPX (Ver.0.03 or later) and install it into
your Psion. (See chapter 2 to get this OPX.)
Then install aSync. After you uncompress its ZIP archive, you will find the
following files.
./ ----- aSync_en.txt This text.
aSync_ja.txt Text written in Japanese.
aSync.SIS Installation file.
srcs/ ------- aSync.opl Source lists.
aSync.oph
aSync.mbm
Pick up the extracted 'aSync.SIS' file and install it on your Psion. While
you install aSync, Agenda2.OPX will also be installed automatically. When
installation is complete, the aSync icon will appear in the Extras bar on
your Psion.
4. Uninstallation
If you have the 'Add/remove' icon in your Psion's control panel, select aSync
in the 'Add/remove' window and remove it. Or find the 'aSync' directory in
the '\System\Apps\' directories in drives C: and D: on your Psion, and delete
all the files included in them.
5. Usage (Preparing)
Before syncing, an aSync file must be created. This is the file that contains
individual settings for syncing and status of your synced events. Syncing is
executed using a set of three files
an Agenda file
an iCal file
and an aSync file
This may sound tedious, but once you have created an aSync file, you don't
need to do it again, unless you wish to change a sync setting. Clicking on
the aSync file you have created will then sync your diary, without your
having to select either your Agenda file or your iCal file.
If you wish to sync a couple of different sets of Agenda files and iCal
files, you can save each setting in separate aSync files.
Create an aSync file by following the instructions in the next sections.
5.1. Preparation
First prepare an Agenda file and an iCal file for aSync. If you can find
'Export' in 'File' menu on the iCal's menubar, select it. Then specify
place and name to save iCal's schedule on the dialog window. After this
your schedules will be exported into an iCal file with suffix '.ics'.
If you cannot find 'Export' in 'File' menu on the iCal's menubar, get iCal
file from '~/Library/Calendars/' directory on your Mac. You can find some
files with '.ics' suffix in there, and thie filename may equals to your
calendar name. For example, a calendar named 'Private' will be saved in
'~/Library/Calendars/Private.ics'.
Then transfer your iCal file from your Mac to your Psion.
5.2. Creating aSync file
Run aSync from the extras bar on your Psion. A dialogue window titled
'Opening aSync file' will appear with no file selected.
Tap the [Create/Edit...] button on it. The navigation dialogue to create
a new aSync file starts.
Navigation #1/6: Selecting an Agenda file.
Select an Agenda file for sync with your iCal file. You will see only
Agenda files in this dialogue. If the file you select uses or is opened
by another application, aSync tries to close it. And if the file you
select is set to read-only, you will not be able go to the next step.
Navigation #2/6: Selecting an iCal file.
Select an iCal file for syncing with the Agenda file. Although any type
of file can appear in this dialogue, you will not be able to go to the
next step if the file you select is not an iCal file. And if the file
you select is set to read-only, you will not be able to go to the next
step either.
Navigation #3/6: Setting the starting date for syncing.
Set the start date between days -1 to 366. This determines how many days
back from today aSync must sync. The events ending during those days
will be synced. For example, if the value you set is 7, and the date you
do your sync is 10 April, events ending after 3 April will be synced.
The value -1 is special and it means no limit. This option is set to
reduce the time it takes to sync. Remember that the higher the number of
days you set in this dialogue, the longer the sync will take.
Navigation #4/6: Selecting entry types you wish to sync.
Check at least one of the entry types you wish to sync.
Navigation #5/6: Setting filter types and symbols.
These options may be hard to understand at first. The options in this
dialogue allow you to restrict syncing to events with specific symbols
in the Agenda. For example, if you have both official and private events
in your Agenda and you wish to sync them separately with your two iCal
calendars - 'Official' and 'Private', you can use options in this
dialogue.
The first option 'Sync entries which' is a type of restriction. You can
choose one of the following three types:
'with ANY symbol' makes no restriction of symbol character.
'WITH target symbol' syncs only events with the symbol character
specified in the second option 'Target symbol'.
'WITHOUT target symbol' syncs events without the symbol character
specified in the second option 'Target symbol'.
The third option 'Default symbol' defines a symbol character auto-
matically set to new events that are inserted from your iCal file.
The values you can set for 'Default symbol' are restricted by the two
options above. If 'WITH target symbol' is set in the first option,
'Default symbol' must be the same as the 'Target' symbol. If 'WITHOUT
target symbol' is set in the first option, 'Default symbol' cannot be
the same as the 'Target' symbol.
Example 1)
Setting:
Sync entries which: 'with ANY symbol'
Target symbol: none
Default symbol: 'P'
Either Agenda entries are synced or not:
Entry Symbol ---> Synced or Not
--------------------------------------------------
'Shopping' 'H' ---> Synced
'Ski tour' 'P' ---> Synced
'Meeting' none ---> Synced
Agenda entries and symbols after syncing:
iCal Entry Agenda entry Symbol ---> Agenda entry Symbol
-------------------------------------------------------------------
'Birthday' none ---> 'Birthday' 'P'
'Meeting' 'Meeting' none ---> 'Meeting' none
Example 2)
Setting:
Sync entries which: 'WITH target symbol'
Target symbol: 'P'
Default symbol: 'P'
Either Agenda entries are synced or not:
Entry Symbol ---> Synced or Not
--------------------------------------------------
'Shopping' 'H' ---> Not synced
'Ski tour' 'P' ---> Synced
'Meeting' none ---> Not synced
Agenda entries and symbols after syncing:
iCal Entry Agenda entry Symbol ---> Agenda entry Symbol
-------------------------------------------------------------------
'Birthday' none ---> 'Birthday' 'P'
'Ski tour' 'Ski tour' 'P' ---> 'Ski tour' 'P'
Example 3)
Setting:
Sync entries which: 'WITHOUT target symbol'
Target symbol: 'H'
Default symbol: none
Either Agenda entries are synced or not:
Entry Symbol ---> Synced or Not
--------------------------------------------------
'Shopping' 'H' ---> Not synced
'Ski tour' 'P' ---> Synced
'Meeting' none ---> Synced
Agenda entries and symbols after syncing:
iCal Entry Agenda entry Symbol ---> Agenda entry Symbol
-------------------------------------------------------------------
'Birthday' none ---> 'Birthday' none
'Ski tour' 'Ski tour' 'P' ---> 'Ski tour' 'P'
Navigation #6/6: Saving a new Agenda file.
Finally, set the filename for your new aSync file. You might wish to
avoid using suffixes such as '(01)' because aSync creates backup files
with names including these suffixes. This filename cannot have any
spaces in it.
When you have finished the above, a new aSync file is created and the
screen will return to the first dialogue of 'Opening aSync file'. The
locations of your Agenda file and iCal files, the unique ID records of
these files, and the preferences you have set are all saved in the new
aSync file. You don't need to change these settings unless and until you
wish to change specific settings or create other syncing sets.
6. Usage (Daily tasks)
To sync your Agenda file with your iCal file by using the aSync file you have
created, do as follows:
6.1. Transferring your iCal file from your Mac to your Psion
Transfer your iCal file from your Mac to your Psion. The iCal file trans-
ferred to your Psion must be put in the same directory that you placed it
when you created the aSync file.
6.2. Syncing
Tap your aSync file, or select the aSync icon on the extras bar on your
Psion. If you tap the aSync file, it starts syncing immediately. If you
select the aSync icon on the extras bar, the dialogue for selecting an
aSync file will appear. Then select your aSync file in this dialogue and
tap the [OK] button.
6.3. Transferring your iCal file back to your Mac
After syncing is complete, your iCal file will be updated, and the old one
backed up with same filename and the '(01)' suffix appended. Transfer your
updated iCal file back to your Mac.
If you can find 'Import' in 'File' menu on the iCal's menubar, select it.
Then select transfered iCal's schedule on the dialog window. After this
your schedules will be imported into the iCal schedule.
If you cannot find 'Import' in 'File' menu on the iCal's menubar, put iCal
file into under '~/Library/Calendars/' directory on your Mac after quiting
iCal applecation. Then restart the iCal. You will find your schedules are
updated.
7. Usage (Details)
There are some other functions that I have not yet described.
7.1. To modify existing sync settings
If you tap the [Create/Edit...] button when an aSync file is selected on
the first dialog of 'Opening aSync file', a confirmation of editing the
selected aSync file will appear. To start modifying it, tap the [Edit]
button. Then the navigation dialogue to modify settings starts. It is
similar to the one when you created a new aSync file.
Navigation #1/5: Selecting an Agenda file.
In this step you can change the place or name of your Agenda file. You
can select different file. But caution it may cause probrems such as
that all entries are deleted or duplicated.
Navigation #2/5: Selecting an iCal file.
In this step you can change the place or name of your iCal file. Same as
Agenda file, you can select diffrent file with same risks of selecting
defferent Agenda file.
Navigation #3/5: Setting start of sync duration.
This step is the same as when creating an aSync file. See section 5.2.
Navigation #4/5: Selecting entry types you wish to sync.
This step is the same as when creating an aSync file. See section 5.2.
Navigation #5/5: Setting filter types and symbols.
This step is the same as when creating an aSync file. See section 5.2.
Confirmation of overwriting an aSync file.
In this dialogue, you can select either save or abort modified settings.
After this, the screen returns to the first dialog of 'Opening aSync
file.'.
7.2. Further settings
In the last step of navigation for creating or modifying an aSync file,
there is another button [More...]. Tap it to start navigation to further
settings.
Navigation #1/4: UID suffix for new iCal entries.
Each iCal entry must have a unique key 'UID' to identify itself. When a
new event is inserted into your iCal file during the sync process, aSync
generates a new UID by using system time and a predefined suffix string.
This suffix string is automatically generated from system time and the
machine unique ID of your Psion when you created your aSync file. You
can change this suffix string in this dialogue.
Navigation #2/4: Separator before location and default priority of to-do.
Agenda entries have no information about location. aSync puts the iCal
location value into the subject text of Agenda entries.
To divide the subject itself from the location, aSync uses a token
string defined here. If this value is none, location information in the
iCal file is not put into the subject text of the Agenda entries. Be
careful about changing this value. If you do, existing location strings
in Agenda entry will become unrecognisable. The initial value is not
set when the aSync file created.
Default priority of to-do is used when a new to-do without priority is
inserted into Agenda from iCal.
Navigation #3/4: Behaviour of events outside the syncing period.
The longer the period you sync, the larger your files become. To save
disk space, aSync can delete sync status and entries that are out of
sync duration automatically. If you allow deleting expired sync status,
you can keep the aSync file small. If you allow deleting expired entries
in your Agenda and iCal files, you can keep them small.
Navigation #4/4: Behaviour about special situations on modifying events.
aSync cannot modify Agenda entries with embedded objects such as Sketch,
Sheet and so on. If they were modified in iCal files, aSync makes a copy
of the original entries except objects and updates copied entries. Then
it deletes or leaves original stands on setting in this dialog. If you
choose 'Backup original', the original events are not deleted, but their
linkage to the iCal events are removed and they are not synced anymore.
The other setting in this dialogue is that either the Agenda or the iCal
entry can be selected if the same entry is modified on both sides.
If you tap the [Commit] button in the last dialogue, the changes are fixed
and the screen returns to the last step of the navigation for creating or
modifying an aSync file. Changes to further settings are also saved in
your aSync file when you save the basic settings.
7.3. Common settings
Each sync setting is saved in an aSync file, but common settings of aSync
are defined in the configuration file called 'aSync.ini'. It is a text
file in the 'C:\System\Apps\aSync' directory and it defines several pro-
perties in 'Key=Value' style listed below.
Key: backup
Data type: integer digit
Value takable: -99 to 99
Default value: -1
Meaning:
Maximum number of backup generations. Each file is backed up to the
generation of this item's absolute value. Backed up files have a suffix
of ascending numbers such as '(01)'. The number starts at 01 and in-
creases up to the specified generation if the same name is found. If the
value of this item is 0, no backup is created. A positive value indi-
cates that aSync is asking for an alternative name if the backed up file
of maximum generation already exists. A negative value indicates that
the backed up file of maximum generation is overwritten without confir-
mation.
Key: lastUsedFile
Data type: string
Value takable: up to 255 charactors
Default value: none
Meaning:
The file path of the aSync file used last. This item is updated auto-
matically when aSync finishes.
Key: alwaysShowDialog
Data type: integer digit
Value takable: 0 or 1
Default value: 0
Meaning:
If the value is 1, aSync shows the first dialogue for selecting an aSync
file when you start the application by tapping the aSync file icon.
If the value is 0, it starts syncing immediately without showing the
dialogue.
Key: logging
Data type: integer digit
Value takable: 0 or 1
Default value: 1
Meaning:
If the value is 1, aSync outputs text formatted logs into file while
syncing. The log file is placed in 'C:\System\Apps\aSync\aSync.log' and
is overwritten on every syncing.
Key: priorityHighTo
Data type: integer digit
Value takable: 1 to 4
Default value: 3
Meaning:
Priority range in Agenda to-do can take all value from 1 to 9. But iCal
and Mozilla support only three levels - 1(high), 5(normal), 9(low). So
it must be converted to one of three levels if the other priority level
appears in Agenda to-do. This item defines the bottom level of priority
high. For example, if the value of this item is 3, priority 1 to 3 in
Agenda to-do will be converted to 1(high) on syncing.
Key: priorityLowFrom
Data type: integer digit
Value takable: 6 to 9
Default value: 7
Meaning:
Similar to the item 'priorityHighTo' above, this item defines the top
level of priority low. For example, if the value of this item is 7,
priority 7 to 9 in Agenda to-do will be converted to 9 (low) on syncing.
8. Note
8.1. This program supports only US-ASCII character code. It is not supported
with other character codes, especially multi-byte codes such as Japanese.
8.2. This program uses the Agenda2.opx to read and write Agenda files. So the
entry properties unsupported by Agenda2.opx like 'Synchronize with other
agendas' might be lost during sync.
8.3. To reducing file size, entries are checked for updates by comparing MD5
checksum instead of whole entry data. It is therefore possible, if un-
usual, that a modified entry might be recognised as unmodified.
8.4. This program does not support time zone or summer time. Information
on time zones are neglected and all time values are processed as local
time.
8.5. Entry repetition rules in Agenda and iCal are different from each other.
So all entries but anniversaries are synced as ones those have no
repetition.
8.6. Anniversaries in Agenda are synced as all day events that have 'yearly
by date' repeatation in iCal calendar. If you want to set other types
of repeatation, you should set them manualy on both Agenda and iCal.
8.7. There are some differences in supported entry status among Agenda, iCal
and Mozilla. aSync converts entry status through syncing using the
following rules:
Agenda and iCal)
Agenda iCal
-------------------------------------------------------------------
Appt, Event, Anniv: none <---- none
none <---> CONFIRMED
tentative <---> TENTATIVE
cross out ----> CANCELLED
tentative + cross out <---> CANCELLED
To-do: none <---> none
tentative ----> none
cross out <---> COMPLETED
tentative + cross out ----> COMPLETED
Agenda and Mozilla)
Agenda Mozilla
-------------------------------------------------------------------
Appt, Event, Anniv: none <---> CONFIRMED
tentative <---> TENTATIVE
cross out ----> CANCELLED
tentative + cross out <---> CANCELLED
To-do: none <---> NEEDS-ACTION
tentative ----> NEESS-ACTION
cross out <---> COMPLETED
tentative + cross out ----> CANCELEED
8.9. Agenda2.opx cannot access value of completed date from to-do entries. So
when a to-do entry is set to completed, completed date is set to synced
date in another side of synced to-do.
9. Licences
9.1. The copyright of this program and other related products distributed
together (source codes, icons, documents, etc.) belongs to the author of
this program, except the Agenda2.opx which belongs to Symbian Ltd.
9.2. This program is distributed as freeware by the copyrighter. No payment
is necessary for commercial or noncommercial use.
9.3. The author of this program accepts no claims for physical, mental,
material, monetary, social, religious, political or any kind of damages
caused by you using this program. Anyone who use this program must aban-
don all claims for all damages described above.
9.4. Those who have this program may reuse a whole or part of its source code
for their own products and can redistribute them freely for commercial
or non-commercial use without the permission of the copyrighter, except
the official application UID allocated by the Symbian Ltd.
9.5. Those who make their own products by reusing the source code of this
program may not prevent others from using this program and must allow
its free distribution, free use, free redistribution and free reuse by
claimimg their copyrights.
9.6. You agree to all the articles listed above in this chapter when you use
this program or reuse source code of it.
10. Changes history
Ver.0.01 (18 Nov 2003):
- Prototype release.
Ver.0.10 (24 Dec 2003):
- Fixed bug of duplicated 'END:VCALENDAR' line.
- Fixed bug that "END:VCALENDAR" line inserted into wrong position.
- Corrected overflow of entry ID on updating Agenda entries.
- Re-designed settings and setting dialogs.
- Removed function of setting oneself as invisible application.
- Added function of logging.
- Removed debug outputs.
- Re-designed output messages.
- Changed icons.
- Added temporary function of converting prototype-version aSync files.
Ver.1.00 (05 Jan 2004):
- Changed rules on deleting entries to that entries not recorded in aSync
file are not deleted if their end-date is out of sync duration. This is
a countermeasure to avoid Agenda2.OPX crashes by happening to access
broken entries created because of miss deleting.
- Corrected overflow of entry ID on searching Agenda entries.
- Changed default value of backup generation from 999 to -1.
- Added start date and summary of entries to output messages on syncing.
- Added start date of entries to log messages.
- To avoid disk full caused by increasing file size of aSync file, added
processes of compressing aSync file during sync.
- After deleting backed up Agenda entries that include embedded objects,
newly inserted entries were often ignored or deleted. To avoid this
trouble, rules about backed up entries were changed so that new entries
with changed checksum could be correctly identified.
- Removed temporary function of converting prototype-version aSync files.
- Re-design of icon so that it cannot be mistaken for the Agenda icon.
Ver.1.01 (13 Jun 2004):
- Corrected strange messages.
- Made it available to abort settings in any steps in the navigation
dialogues for creating or editing a aSync file.
Ver.1.02 (17 Jul 2004):
- Fixed bug that an error occurs if an iCal file placed on D drive.
- Available to recover if the ID entry in Agenda file was deleted.
Ver.1.03 (28 Jul 2004):
- Fixed bug that cannot update preference.
Ver.1.10 (08 Aug 2004):
- Fixed bug that status of completed to-do not synced correctly to iCal.
- Fixed bug that invalid priority levels are synced to iCal.
- Also supported calendar files of Mozilla Calendar and Sunbird.
Ver.1.11 (20 Aug 2004):
- Fixed bug that outputs wrong date in log message and file.
- Fixed bug that cannot return from the dialog of selecting iCal file if
the aSync file itself is selected on this dialogue.
Ver.1.12 (22 Oct 2004):
- Fixed bug of occurring error if 'DURATION' tag appears before 'DTSTART'
tag in iCal entries.
Ver.1.13 (8 Dec 2004):
- Enabled to turning off the calendar ID verification.
Ver.1.14 (17 Mar 2005):
- Fixed bug of crushing if 'PRIORITY:0' record exists in iCal entries.
- Enabled to turning off the calendar ID verification also during step of
creating a aSync file.
Ver.1.15 (23 May 2005):
- Added prompts in dialogues of selecting files.
- Fixed bug on creating backup files when same filename already exists.
- Fixed a lot of mistypes and strange expressions in this document.
Ver.1.16 (12 Sep 2005):
- Fixed bug on accessing files those contains space charactors in their
file path.
- Fixed bug on turning off calendar ID verification.
- Fixed bug on opening an Agenda file opened by other programs.
- Supported anniversaries.
Ver.1.17 (19 Aug 2007):
- Supported entries have no DTEND or DURATION.
Ver.1.18 (29 May 2009):
- Fixed bug of error on sync with empty Agenda file.
- Fixed bug of wrong value initialization.
- Omitted calender ID verification.
- Changed rule of naming backuped file to '(01)' style just as
Psion's file copying.
- Improved handling for out-of-range value in INI file.
aSync