PiTcl commands: conversion

Commands
Sitemap
 

The four conversion commands provided by the extension are

  • piAddress
  • piAppointment
  • piMemo
  • piTodo

The overall syntax is the same for all of them, they differ only in the expected structure of in- and output.

cmd <direction> <what> <data>
Converts <data> of type <what> using the specified <direction>.

The possible types are listed below. Shortcuts are accepted too, as long as they are unambiguous.

  • appinfo
  • record
  • sortinfo

Attention: None of the standard databases use their 'sortinfo' block. Trying to convert one will throw an error, independent of the direction. I could have removed this type from the list, but decided against, as it is provided by the underlying and more general implementation of the converters and might be used by future converters.

Possible directions are:

pack
<data> has to be a list structure conforming to the expectations of the used <cmd>. See below for an explanation of these expectations. The result of the command is the binary information to send to the pilot.
unpack
<data> has to be the binary information coming from the pilot and from the appropriate database. The result of the command is a list structure containing the same information in a human readable way.

General information

All the lists are based on key/value-pairs, the same format which is generated by 'array get'.

Some of the values are key/value-lists too, so you either have to use 'array set' repeatedly or the TclX-commands for keyed-lists.

The category information is the same across all standard databases:

Categories
Key Value
renamed

A list containing the indices of the category names which were renamed by the user. Indices out of the range 0 ... 15 are reported as errors.

name

A list containing the names given to the 16 possible categories. An empty string indicates a category without name, these are unused. The palm pilot restricts the length of the category names to 15 characters (+ a terminating \0 character). Longer names are automatically truncated during conversion, shorter strings are padded with \0's.

id

A string, nothing more is known. Well, it is restricted to at most 16 characters, as the name's above.

lastUniqueId

The numerical id given to the last inserted record (?).

Example

{
    renamed {0 1 2 3}
    name {
	{Nicht abgelegt} Firma
	Privat Einkaufen
	{} {} {} {}
	{} {} {} {}
	{} {} {} {}
    }
    id {}
    lastUniqueId 18
}
        

piMemo

Memo record
Key Value
text

The text stored in this memo. Its length is restricted to 64 Kbyte of data.

Example

{
    text {Hello world}
}
	

Memo AppInfo block
Key Value
category

Information about the available categories to memos. A list of key/value-pairs. This information is the same for all standard databases and was already described.

sortByAlpha

Sortorder, either 0 or 1.

Example

{
    category {
	renamed {3 4 5}
	name {
	    {Nicht abgelegt} Firma Privat
	    Palm Reise Tcl/Tk {} {}
	    {} {} {} {}
	    {} {} {} {}
	}
	id {}
	lastUniqueId 22
    }
    sortByAlpha 1
}
	

piTodo

Todo list record
Key Value
priority

Numerical priority of the todo item.

indefinite

Boolean flag, either 0 or 1. The latter indicates that the item has no due-date.

complete

Boolean flag, either 0 or 1. The latter indicates that the item was done.

description

Textual description of the things to do.

note

Additional textual information about the things to do.

due

Date at which the described things have to be done. The information is in the same format as returned by the tcl-command [clock seconds]. Irrelevant for indefinite = 1.

Example

{
    priority    1
    indefinite  0
    complete    0
    description {Convert $$ to DM}
    note        {}
    due         906415200
}
	

Todo list AppInfo block
Key Value
sortMode

Sortorder, one of

  • date,priority
  • priority,date
  • category,priority
  • category,date
dirty

A boolean flag, either 0 or 1. The latter indicates that the application information was changed.

Example

{
    category {
	renamed {0 1 2 3}
	name {
	    {Nicht abgelegt} Firma
	    Privat Einkaufen
	    {} {} {} {}
	    {} {} {} {}
	    {} {} {} {}
	}
	id {}
	lastUniqueId 18
    }
    sortMode priority,date
    dirty    1
}
	

piAddress

Addressbook record
Key Value
showPhone

Boolean flag. Determines whether phone information is shown for the entry or not.

phoneLabels

A key/value-list associating the phone items with their respective titles. Keys are the letters A to E, values are keys into the application information (restricted to phone1 .. phone8).

lastName

Last name of the person.

firstName

First name of the person.

company

Name of the company to associate with the person.

phoneA

First of five possible phone numbers.

phoneB

Second of five possible phone numbers.

phoneC

Third of five possible phone numbers.

phoneD

Fourth of five possible phone numbers.

phoneE

Fifth of five possible phone numbers.

address

Name of street, number of house.

city

Name of the city the street is part of.

state

Name of the state the city is part of.

zipcode

Zipcode of the given address.

country

Name of the country the state is part of.

title

Title of the person

custom1

Textual custom information, part 1.

custom2

see above, part 2.

custom3

see above, part 3.

custom4

see above, part 4.

note

Additional notes for the entry.

Example

{
    showPhone   0
    phoneLabels {
	A phone1
	B phone2
	C phone3
	D phone4
	E phone5
    }
    lastName    {}
    firstName   {}
    company     {Ascom (Aachen)}
    phoneA      {0241  96806  0}
    phoneB      {}
    phoneC      {0241 }
    phoneD      {}
    phoneE      {}
    address     {Charlottenburger Allee 61}
    city        Aachen
    state       NRW
    zipcode     52064
    country     DE
    title       {}
    note        {}
    custom1 {} custom2 {}
    custom3 {} custom4 {}
}
	

Addressbook AppInfo block
Key Value
country

A numerical country code. Nothing more is known.

sortByCompany

A boolean flag indicating how the database is sorted.

labels

A list of key/value-pairs. The values are the labels to put to the left of the various entry fields. They are restricted to a length of 16 characters, like the category names. The keys are the same as the keys for a record, with the following exceptions:

  • showPhone and phoneLabels are missing.
  • phoneA .. E are replaced by phone1 .. 8.

Remark: As was said before, the phoneLabels item in a record associates every phone item in it with one of the eight possible labels, using the appropriate phoneX key, X in {1..8}.

Example

{
    category {
	renamed {0 1 2 3 4 5 6 7}
	name {
	    {Nicht abgelegt} Firma
	    Privat QuickList
	    Freunde Palm
	    Bekannte T-Mobil
	    {} {} {} {} {} {} {} {}
	}
	id {}
	lastUniqueId 24
    }
    country 2048
    sortByCompany 0
    labels {
	lastName  {0 Nachname}
	firstName {0 Vorname}
	company   {0 Firma}
	phone1    {0 Büro}
	phone2    {0 Privat}
	phone3    {0 Fax}
	phone4    {0 Andere}
	phone5    {0 E-Mail}
	phone6    {0 Firma}
	phone7    {0 Funkruf}
	phone8    {0 Handy}
	address   {0 Adresse}
	city      {0 Ort}
	state     {0 Bundesland}
	zipcode   {0 PLZ}
	country   {0 Land}
	title     {0 Titel}
	custom1   {1 {Geburtstag }}
	custom2   {1 {WWW }}
	custom3   {0 {Definiert 3 }}
	custom4   {0 {Definiert 4 }}
	note      {0 Notiz}
    }
}
        

piAppointment

Datebook record
Key Value
begin

Day and starting time of the appointment.

end

Day and end time of the appointment.

The day is the same as in begin, the standard datebook application delivered with a pilot is unable to handle appointments crossing date boundaries.

description

Textual description of the appointment.

note

Additional note.

event

A boolean flag. If set, the appointment is an all-day event, and the time information in begin and end is irrelevant.

alarm

A boolean flag. If set, an alarm is scheduled for the event, and the information in advance is valid.

advance

Describes how much in advance the alarm for this event is triggered. It is a key/value-list with the keys value and unit. Possible values for unit are:

  • min
  • hour
  • day
repeat

A list of key/value-pairs describing the repeat behaviour of the appointment. This is described in a separate table, see below.

Example

{
    begin       910525500
    end         910528200
    description Mittagessen
    note        {}
    event       0
    alarm       1
    advance {
	value 5
	unit  min
    }
    repeat {
	type       weekly
	freq       1
	weekstart  monday
	forever    1
	end       -1
	day        0
	exceptions {}
	days       0111110
    }
}
	

Repeat information in a datebook record
Key Value
type

The general type of repeat, one of:

  • none
  • daily
  • weekly
  • monthlyByDay
  • monthlyByDate
  • yearly
freq

Frequency of the repetition.

weekstart

Either sunday or monday.

forever

A boolean flag. If set, the value in end is irrelevant.

end

The date at which the system shall stop repeating the appointment. Not valid for forever = 1.

day

The day of the month to repeat, valid only for type = monthlyByDay.

exceptions

A list of days which are exempt to the repeating.

days

Valid for type = weekly. Defines the days of the week the appointment shall repeat on, as a 7-characters string containing 0 (don't repeat) and 1 (repeat). The value of weekstart must be factored into the interpretation of this string.

Example

{
    type       weekly
    freq       1
    weekstart  monday
    forever    1
    end       -1
    day        0
    exceptions {}
    days       0111110
}
	

Datebook AppInfo block
Key Value
startOfWeek

Either sunday or monday.

Example

{
    category {
	renamed {}
	name {
	    {} {} {} {} {} {} {} {}
	    {} {} {} {} {} {} {} {}
	}
	id {}
	lastUniqueId 0
    }
    startOfWeek sunday
}
	

© Andreas Kupries
Last update at Sun Aug 29 00:44:05 MEST 1999