The FooDoo Lounge

Scripting Palm Desktop 2.x-4.0

Index

Introduction

This is an adaption of a tutorial I wrote some years ago for people who were trying to script Palm Desktop versions prior to 4.1. I did it to help and encourage others to script what I believe is a highly useful application, with what was a fairly poor AS implementation.

The release of PD 4.1, with its completely re-engineered AS Dictionary made this tutorial more or less redundant - it strange syntax and many broken commands are in the past now, thanks to the efforts of Chris Page. I've left this here basically for people who are still needing to use one of the older versions for some reason. Anyone wanting to script PD who can do so (requires OS 8.6 minimum) should use version 4.1.

My explorations of the older versions were by no means exhaustive. I figured out what I needed to achieve my ends and picked up a few other things along the way. If you have something useful to add and would like to make a contribution to this page, please let me know via the email addess here.

PD Version History

Palm Desktop was originally called Claris Organizer 2.0. Palm bought it and released their first version as 2.1. Up to V2.5.x, there were no obvious changes to the AS dictionary. Apart from V4.1, these versions were the most scriptable.

Things changed in V2.6 and some commands were broken. I avoided 2.6 and continued to use 2.5, because the other changes in the app seemed to mainly affect HotSync and it was possible to use the updated components with V2.5 anyway. Things improved slightly with V4.0, though I only used the OS X version of it.

Chris Page, the “Mac Guy” at Palm, posted this to the AS Users list on the 12th of November 2002:

“I can't promise when or if it will ship, but I completely gutted and re-implemented the AS support in Palm Desktop. I've tried to maintain backwards compatibility where possible. In most instances, simple compiled scripts that just read address information, for example, should run, but text-only scripts will need to be rewritten. Some terms have been deprecated, and de-compiling a script will produce terms with the word "obsolete" in them to make them obvious. I've put them all in an "Obsolete Terms" suite, and the comments for each term indicate what new term(s) to use.”

PD 4.1 shipped in April 2003 and provides a very easy "upgrade" path for old scripts. I updated all my handlers quickly & easily and they're all shorter and faster than they were before.

Using this code

PD 2.6 changed many of the terms that are displayed in a script editor. This makes things a little difficult when it comes to copying and pasting code directly from this page, though compiled scripts are not affected by the changes.

All the terms here are as displayed in PD 4.0 for OS X and should be OK for V2.6.x. If you are using V2.5 or earlier, you may wish to download my original tutorial. All snippets assume a tell block to PD - they will not compile or work unless they are in a tell block to the app:

tell application "Palm Desktop"
    -- any code from this page
end tell

These snippets all test OK in PD 2.5 under OS 8.6, 9.0.4 & 9.1 and in PD 4.0 under OS 10.1.5 & 10.2, unless otherwise noted.

Creating & displaying objects

These use a fairly standard syntax, pretty much as the dictionary would suggest.

Create new address (contact)

Creates and displays a new, empty address and returns the object record.

make new address
--> {object classclass CONT», object number:15, object instance:-1}

object class is PD's internal specifier - CONT for addresses, STSK for to do's, SAPP for events, etc.
object number is an internal object id. It does not appear to change, so once you have it you could use it to call that object again.
object instance is set to -1 unless it's a repeating to do or event.

New memo (note) with initial data

Note that the data in the body will not necessarily be visible immediately, though it is there - it can be got with AS and will appear in the UI eventually.

make new memo with data {title:"Note for Foo", body:"Foo has a Bar"}

New event (appointment) with initial data

The date property accepts an AS date object. The duration is in minutes.

make new event with data {title:"Meeting with Steve Jobs", date:current date, start time:"8:00 AM", duration:60}

New to do (task) with initial data

Includes the setting of a category, which can be new or existing.

set newTask to make new to do with data {title:"test - delete this", due date:current date, primary category:category "Friends"}

Displaying objects

The previously created to do can be displayed in the Date Book window using this:

show to do (object newTask)

The next example will show the first address in the last displayed address list. These numbers change depending on the address list they happen to have been in last.

show address 1

An object can also be displayed using a previously obtained object number. These numbers do not appear to change:

set n to 1
show address (object {object classclass CONT», object number:n, object instance:-1})

Use the above with caution and only specify object numbers previously obtained from PD.

This opens the Date Book window to a daily view:

show day (current date) in window "Date Book"

I think this was posted to the Organizer Talk list by Joel Jones. The window is called "Daily Calender" in older versions and either string works in V4.0.

Getting data

This can be done one field at a time, which sends an AppleEvent for each, or by getting records, such as all fields. Not everything works as advertised. Apart from the info here, testing is the only way to determine what can be done.

The most reliable way to get properties from the name info rec is to call them directly. The next line gets the full name of the currently (or last) displayed address. See the PD dictionary for a list of the other properties.

first name of address 0

The name info rec can be used in older versions (before V2.6), but is still broken in V4.0. Most other properties can still be retrieved in all versions though:

primary address of address 0
mailing label of (primary address of address 0)
primary category of address 0 as string -- returns a PD object without the string coercion

Miscellaneous snippets

Attaching 2 objects

set myContact to address 0 -- 1st object, the current contact
set myTask to make new to do with data ¬
    {title:"test - delete this", due date:current date, primary category:category "Friends"} -- 2nd object, a new task
try
    attach (object myContact) to (object myTask) -- works, but errors anyway on some systems
on error errMsg number errNum
    if errNum -1703 then -- returns this number - "...some data was the wrong type"
        error errMsg number errNum -- optional trapping of other errors
    end if
end try

Attach an object to a file

set currAdd to address 0 -- get a PD object reference
attach (object currAdd) to file "Disk:Folder:File" -- must be a valid file specification

Using the Custom fields of addresses

These can be hidden in the UI (set this in Preferences) though still used for storing data for scripts. For example, if the prefs are set to display 9 custom fields, 3 are hidden and can be used for 'private' data that you don't want a user to be able to easily edit. It also means you can store a lot of info without cluttering up the interface.

One of the custom fields - custom 12 - cannot be shown at all in the UI, though is available via AS. Don't use it if you sync a handheld to your PD file though - it's used by the HotSync software.

These fields only take strings (text) or data that can be stored/retrieved as such, like numbers. Other data types (like lists) require some processing, or cannot be used (like alias references). Be aware that leading spaces in strings will be removed.

I use them for things like storing the path string to a 'log of contact' file (an AppleWorks doc in this case) for each of my clients. A script running from the OSA Menu or Script Menu reads the path and then opens the file. When I used Claris Emailer, I put the Emailer id of the contact in a custom field rather than their email address, because Emailer allows multiple addresses. I had a script that would create a new message in Emailer to that person using the id.

The possibilities are limited only by the data that can be stored in these fields and I find them very efficient way of linking things to PD addresses.

Bugs & Workarounds

Various things don't work as advertised and some things broke with V2.6 and later versions. Repeatedly calling broken commands when testing can cause PD to crash, so backup your data file before testing and relaunch it regularly to minimise problems. PD 4.0 under OS X seems to be less prone to these issues.

These commands have never worked. There are no doubt many others:

phone label of (phone 1 of address 0)
export to do into file "Disk:Folder:File" -- works, but only exports addresses under PD 4.0. Earlier versions export everything (I think), i.e. the reference is ignored

Version 2.6.x broke a few things I relied on and created a few terminology conflicts. The use of the keyword text for the field text of the custom recs of addresses is an example of the latter. I recommend skipping this version for scripting purposes.

Version 4.0 fixed the terminology conflicts - text became field text - though my testing suggests that other things remain broken. I recently discovered that there is a workaround for these, or at least all the ones that affect me, for those that can be bothered.

The main issue for me with V2.6 and V4.0 is getting info from the record returned by all fields, which is a property of most PD objects. I used to get this record and then extract what I wanted out of it without any further AppleEvents, which are relatively slow:

set addressRec to all fields of address 0 -- the displayed address, can be used with most objects
set fullName to full informal name of name info of addressRec -- errors in V2.6.x and V4.0

This construct broke with the changes made to V2.6 and remains so in V4.0. I did not test V2.6 extensively, but tests of V4.0 under OS 10.1.5 reveal that a number of the sub-records are still readable:

set addressRec to all fields of address 0 -- the displayed address
set myStr to field text of custom 3 of addressRec -- works
set priAdd to primary address of addressRec -- works
set mLabel to mailing label of primary address of addressRec -- works

It's important to note that this is just a way to speed things up. Everything that was once available from the all fields rec still seems to be available directly from the object, though not always, as ever, in the most obvious ways.

The workaround I stumbled on is to compile the code under PD 2.5: All my PD routines are in a library which was written with V2.5 and compiled under OS 9.0.4. Everything in this library works as it always did, but if I paste the handlers into a new script and compile them under PD 4.0 they break.

To use facilities that are broken under post 2.5 versions, simply compile the code with only an earlier version running, so that the commands use the old terminology. This works fine in Classic under OSX.

Handlers

Most of my PD handlers are specific to my own requirements, though I've put a few general ones here.

 

The FooDoo Lounge is Copyright © Richard Morton 2002-2005

|| url: http://www.foodoo.sunreal.com.au/info/palm_desktop.html
|| created: 4-Aug-03, 10:11 PM; updated: 24-Aug-04, 1:19 PM
|| size: 49102 bytes